3.4 KiB
3.4 KiB
HarmonyOS Audio Research
1. 推荐方案
新增 MPV 音频输出 ao_harmony，直接接 HarmonyOS OHAudio：
MPV audio pipeline -> native PCM ring/buffer -> OHAudio write callback -> AudioRenderer
禁止 PCM 逐块跨 N-API/ArkTS。ArkTS 只发送播放器级控制和生命周期事件。
2. SDK 依据
- headers：
ohaudio/native_audiostreambuilder.h、native_audiorenderer.h、native_audiostream_base.h、multimedia/native_audio_channel_layout.h - library：
libohaudio.so - baseline：API 10
- builder：采样率、声道数、sample format、encoding、latency mode、channel layout、usage、write callback、callback frame size
- renderer：Start、Pause、Stop、Flush、Release、timestamp、frames written、volume、speed、underflow count、latency
API 24 还提供 advanced callback 等新接口，但首版使用最低且稳定的 callback API，避免无必要抬高最低版本。
3. 与 MPV AO 的映射
| MPV / 播放需求 | OHAudio 映射 | 设计 |
|---|---|---|
| PCM 格式协商 | SetSamplingRate、SetChannelCount/Layout、SetSampleFormat |
init() 将 MPV ao->format 映射为 OHAudio；不支持时返回 unsupported，让 MPV 重采样 |
| 数据输出 | renderer write callback | 回调只读取 MPV AO buffer，禁止阻塞、分配大对象或调用 ArkTS |
| Pause/Resume | OH_AudioRenderer_Pause/Start |
与 MPV control() 状态串行化 |
| Stop/Seek | Stop/Flush/Start |
Seek 时丢弃旧 PCM，并重建 MPV A/V sync 基准 |
| Volume | OH_AudioRenderer_SetVolume |
首版支持 0..1；MPV 软件音量仍可用，避免重复增益 |
| Speed | MPV 音频滤镜为主 | 不直接用 Renderer speed 改变 MPV 时钟；系统 speed 仅后续专项验证 |
| A/V Sync | GetTimestamp / GetFramesWritten |
驱动 delay 由已提交帧与硬件播放位置计算，必须做单调性/路由切换测试 |
| 低延迟 | SetLatencyMode |
视频播放默认 normal；fast 仅在设备支持和稳定性测试后启用 |
| 多声道 | channel layout + capability | 先 stereo；5.1/7.1 按设备能力协商，失败回退重混音，不 fake success |
4. MPV 接入位置
- 新文件建议：
audio/out/ao_harmony.c。 - 注册位置：
meson.build的 audio outputs 区域和audio/out/ao.cdriver list。 - 参考结构：
ao_aaudio.c的 callback/pull 模式及状态控制；不能复制其 Android API。 - OHAudio callback 与 MPV AO buffer 的线程安全遵循
audio/out/buffer.c现有模型；回调只消费系统请求的 frame 数。
5. 格式策略
首版候选优先级：float32（若稳定支持）→ signed 16-bit。采样率优先内容原始值，设备拒绝则让 MPV/libswresample 转为 48 kHz。声道首版 2.0，随后验证 5.1/7.1。所有实际支持值通过 builder 创建结果与设备行为确认，不从枚举存在推断硬件支持。
6. 风险与验证
- write callback 的实时线程约束和最大执行时间。
GetTimestamp在暂停、Flush、蓝牙/有线切换后的连续性。- underrun、首包预填充与首音频时间。
- Surface 暂停但音频继续、应用后台、音频焦点中断。
- 播放速度与 MPV 时钟双重调整风险。
- 多声道 layout 枚举和实际设备 route 不一致。
首版验收：PCM 正常播放；pause/resume/seek 无旧音频泄漏；1 小时无死锁；统计 underrun；A/V sync 偏差有真实测量。未完成这些测试前不宣称低延迟或多声道完成。