鸿蒙音频解码

以下是对鸿蒙音频解码模块的总结，包含核心流程、API设计与使用要点，以及Mermaid示意图：

一、鸿蒙音频解码核心流程

以下内容基于官方文档，用一张 Mermaid 时序图 把「鸿蒙音频解码（AVCodec Kit）」的核心流程、API 设计与使用要点一次性梳理出来。可直接复制到 mermaid.live 预览。

仅保留开发者最常调用的接口与顺序，省略了可选项与异常分支，方便快速上手。

%% 鸿蒙音频解码（AVCodec Kit）API 调用时序 sequenceDiagram participant App as 应用层 participant Codec as OH_AVCodec* 解码器实例 participant PCM as 音频输出（PCM） Note over App,PCM: 1. 准备阶段 App ->> App: 1.1 添加头文件 & CMake 链接 libnative_media_codecbase.so App ->> Codec: 1.2 OH_AudioCodec_CreateByMime("audio/mp4a-latm") 或通过 codecName App ->> Codec: 1.3 OH_AudioCodec_RegisterCallback(cb) 注册 4 个回调 App ->> Codec: 1.4 OH_AudioCodec_Configure(cfg) 配置采样率/声道/格式 App ->> Codec: 1.5 OH_AudioCodec_Prepare() App ->> Codec: 1.6 OH_AudioCodec_Start() Note over App,PCM: 2. 运行阶段 loop 解码循环 Codec -->> App: OH_AVCodecOnNeedInputBuffer(idx, buf) App ->> Codec: OH_AudioCodec_PushInputBuffer(idx, buf, size, flags) Codec -->> App: OH_AVCodecOnNewOutputBuffer(idx, info, buf) App ->> PCM: 取走 PCM 数据 App ->> Codec: OH_AudioCodec_FreeOutputBuffer(idx) end Note over App,PCM: 3. 结束阶段 App ->> Codec: OH_AudioCodec_Stop() App ->> Codec: OH_AudioCodec_Destroy()

1. 支持的输入格式

   AAC、FLAC、MP3、Vorbis、G711、AMR、APE、Opus、Audio Vivid 等，具体采样率/声道范围见文档表格。

2. PCM 输出格式

   通过 OH_MD_KEY_AUDIO_SAMPLE_FORMAT 可选 SAMPLE_S16LE 或 SAMPLE_F32LE，默认 S16LE。

3. 线程模型

   所有回调都在内部工作线程，请勿阻塞；应用需要保证线程安全。

4. DRM 解密

   若内容加密，需在 Prepare 前调用 OH_AudioCodec_SetDecryptionConfig，并在 PushInputBuffer 时把 cencInfo 通过 OH_AVCencInfo_SetAVBuffer 写入。

5. EOS 处理

   输入最后一包数据时把 flags 设为 AVCODEC_BUFFER_FLAGS_EOS，解码器会在回调中同样给出 EOS，应用即可进入停止流程。

6. CMake 链接

   target_link_libraries(xxx
       native_media_codecbase.so
   )

---

一句话总结

「鸿蒙音频解码」遵循 创建→配置→启动→循环喂数据→取 PCM→停止销毁 的极简五步模型；所有细节都围绕 OH_AVCodec* 句柄与 4 个回调完成，无需额外线程或同步，直接嵌入现有播放 / 编辑管线即可。

二、API设计与使用要点

1. ​核心API组件​

组件类型	关键API	作用说明
解码器实例	OH_AudioCodec_CreateByMime()	通过MIME类型创建解码器
	OH_AudioCodec_CreateByName()	通过编解码器名称创建
回调注册	OH_AudioCodec_RegisterCallback()	注册错误/数据流/缓冲区回调
参数配置	OH_AudioCodec_Configure()	设置采样率/声道数等参数
运行时控制	OH_AudioCodec_Start()	启动解码器
	OH_AudioCodec_Flush()	刷新缓冲区（可选）
	OH_AudioCodec_Reset()	重置解码器（可选）
数据操作	OH_AudioCodec_PushInputBuffer()	送入压缩数据
	OH_AudioCodec_FreeOutputBuffer()	释放PCM输出数据
资源管理	OH_AudioCodec_Destroy()	销毁解码器实例

2. ​关键开发步骤​

1. ​创建实例​

   // 通过MIME创建
   OH_AVCodec *decoder = OH_AudioCodec_CreateByMime(OH_AVCODEC_MIMETYPE_AUDIO_AAC, false);
   
   // 或通过名称创建
   const char *name = OH_AVCapability_GetName(capability);
   OH_AVCodec *decoder = OH_AudioCodec_CreateByName(name);

2. ​注册回调​

   OH_AVCodecCallback cb = {OnError, OnOutputFormatChanged, 
                           OnInputBufferAvailable, OnOutputBufferAvailable};
   OH_AudioCodec_RegisterCallback(decoder, cb, userData);

3. ​配置参数​

   OH_AVFormat *format = OH_AVFormat_Create();
   OH_AVFormat_SetIntValue(format, OH_MD_KEY_AUD_SAMPLE_RATE, 44100);
   OH_AVFormat_SetIntValue(format, OH_MD_KEY_AUD_CHANNEL_COUNT, 2);
   OH_AudioCodec_Configure(decoder, format);

4. ​**数据流处理

   • ​输入 ​：在OnInputBufferAvailable回调中填充压缩数据

     OH_AVBuffer_SetBufferAttr(buffer, &attr); // 设置PTS/flag等属性
     OH_AudioCodec_PushInputBuffer(decoder, index);

   • ​输出 ​：在OnOutputBufferAvailable中获取PCM数据

     OH_AVBuffer_GetBufferAttr(data, &attr); // 获取解码数据属性
     OH_AudioCodec_FreeOutputBuffer(decoder, index); // 释放缓冲区

3. ​特殊功能支持​

• ​DRM解密​

  OH_AudioCodec_SetDecryptionConfig(decoder, session, false);
  OH_AVCencInfo_SetAVBuffer(cencInfo, buffer); // 设置加密信息

• ​Audio Vivid元数据​

  OH_AVFormat_GetBuffer(format, OH_MD_KEY_AUDIO_VIVID_METADATA, &metadata, &metaSize);

三、重要注意事项

1. ​调用顺序强制要求​：

   创建 → 配置 → 准备 → 启动必须顺序执行，否则引发异常

2. ​解码格式限制​：

   • 支持AAC/FLAC/MP3/Vorbis等主流格式
   • 不同格式有特定参数要求（如Vorbis需ID Header）

3. ​资源释放​：

   OH_AudioCodec_Stop(decoder);   // 先停止
   OH_AudioCodec_Destroy(decoder); // 再销毁

4. ​动态库依赖​：

   target_link_libraries(sample 
       libnative_media_codecbase.so
       libnative_media_core.so
       libnative_media_acodec.so)

​文档链接 ​： 音频解码-音视频编解码-AVCodec Kit（音视频编解码服务）-媒体 - 华为HarmonyOS开发者