ADEC（音频解码）接口说明文档
| 文档版本 | V1.1 |
|---|---|
| 修订日期 | 2026-08-21 |
| 代码基线 | hi_aiot_solution 8.18 |
| 对应头文件 | components/media/pipeline/include/hi_mapi_adec.h |
| 类型定义 | components/media/pipeline/include/hi_mapi_adec_define.h、include/adapt/*_adapt_define.h |
| 适用模块 | ADEC / HI3516CV610 |
1 概述
ADEC（Audio Decoder）模块将压缩音频码流（AAC / G.711 / MP3 / LPCM / OPUS）解码为 PCM 原始帧输出。ADEC 最多支持 4 个通道（通道号 0～3），底层解码器按格式引用计数在全局共享。ADEC 既可以绑定到 AO 自动播放，也可以在解绑定模式下由用户通过 hi_mapi_adec_send_stream / hi_mapi_adec_get_frame 主动喂码、取 PCM。
2 接口总览
| 编号 | 接口 | 功能概述 |
|---|---|---|
| 1 | hi_mapi_adec_init |
初始化音频解码通道，注册对应格式的解码器并创建底层通道。 |
| 2 | hi_mapi_adec_deinit |
反初始化音频解码通道，销毁底层通道并按引用计数注销解码器。所有通道都被反初始化后，内部模块上下文也会被复位。 |
| 3 | hi_mapi_adec_send_stream |
向解码通道送入一帧压缩码流。 |
| 4 | hi_mapi_adec_get_frame |
从解码通道取出一帧解码后的 PCM 音频数据。 |
| 5 | hi_mapi_adec_release_frame |
释放由 hi_mapi_adec_get_frame 获取的 PCM 帧资源。 |
| 6 | hi_mapi_adec_send_end_of_stream |
向解码通道发送流结束标记，通知解码器刷新内部缓冲。 |
| 7 | hi_mapi_adec_get_default_attr |
按解码格式返回推荐的默认 ADEC 属性（自动填充 adec_mode：LPCM 使用 PACK 模式，其他格式使用 STREAM 模式）。 |
| 8 | hi_mapi_adec_set_param |
设置 ADEC 扩展参数（命令分发接口）。以 _CONFIG 结尾的命令必须在首次调用 hi_mapi_adec_send_stream 之前设置，否则返回状态错误。 |
| 9 | hi_mapi_adec_get_param |
读取 ADEC 扩展参数的当前值。 |
3 API 参考
1 hi_mapi_adec_init
【描述】 初始化音频解码通道，注册对应格式的解码器并创建底层通道。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
adec_hdl |
输入 | td_handle |
音频解码通道句柄，取值范围：0～3（HI3516CV610 上 HI_MAPI_ADEC_CHN_MAX_NUM = 4）。 |
adec_attr |
输入 | const hi_mapi_adec_attr * |
解码通道属性指针，不能为 TD_NULL。 |
| 成员名称 | 描述 |
|---|---|
adec_format |
解码格式，枚举 hi_mapi_audio_format。 |
adec_mode |
解码模式，枚举 hi_mapi_adec_mode：HI_MAPI_ADEC_MODE_PACK（要求输入为完整解码包）或 HI_MAPI_ADEC_MODE_STREAM（流式输入，性能较低）。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_ADEC_EINVALIDHDL |
adec_hdl 超出范围（≥4）。 |
HI_MAPI_ADEC_ENULLPTR |
adec_attr 为 TD_NULL。 |
HI_MAPI_ADEC_ENOTINITED |
MAPI 媒体子系统未初始化。 |
HI_MAPI_ADEC_EILLPARAM |
解码格式不支持；或 OPUS / MP3 未编入固件。 |
【需求】
- 头文件：
hi_mapi_adec.h - 库文件：
libhi_mapi.so
【注意】
- 同一通道重复调用
init时，若通道已初始化则直接返回成功（幂等）。 init内部会自动注册对应格式的解码器（按格式引用计数），用户无需手动注册。init后payload_format默认置为HI_MAPI_AUDIO_PAYLOAD_HI_NATIVE，stream_started标志复位。
【举例】
参见【相关主题】中 SAMPLE_AUDIO_BindAdecAndStartAo。
【相关主题】
hi_mapi_adec_get_default_attr、hi_mapi_adec_deinit
2 hi_mapi_adec_deinit
【描述】 反初始化音频解码通道，销毁底层通道并按引用计数注销解码器。所有通道都被反初始化后，内部模块上下文也会被复位。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
adec_hdl |
输入 | td_handle |
音频解码通道句柄，取值范围：0～3。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_ADEC_EINVALIDHDL |
adec_hdl 超出范围。 |
HI_MAPI_ADEC_ENOTINITED |
MAPI 媒体子系统未初始化。 |
【需求】
- 头文件：
hi_mapi_adec.h - 库文件：
libhi_mapi.so
【注意】
- 若通道已经反初始化，则直接返回成功（幂等）。
- 反初始化不会自动解绑；若通道已绑定 AO，请先调用
hi_mapi_sys_unbind。
【举例】
参见【相关主题】中 SAMPLE_AUDIO_UnBindAdecAndStopAo。
【相关主题】
hi_mapi_adec_init
3 hi_mapi_adec_send_stream
【描述】 向解码通道送入一帧压缩码流。
【语法】
td_s32 hi_mapi_adec_send_stream(td_handle adec_hdl, const hi_mapi_audio_stream *adec_stream, td_bool block);
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
adec_hdl |
输入 | td_handle |
音频解码通道句柄，取值范围：0～3。 |
adec_stream |
输入 | const hi_mapi_audio_stream * |
码流结构体指针，不能为 TD_NULL，其成员 stream（虚拟地址）也不能为 TD_NULL。 |
block |
输入 | td_bool |
TD_TRUE 阻塞发送（直到有可用缓冲）；TD_FALSE 非阻塞（缓冲满则立即返回）。 |
成员名称（hi_mapi_audio_stream） |
描述 |
|---|---|
stream |
码流虚拟地址。 |
phy_addr |
码流物理地址（可选）。 |
len |
码流字节长度。 |
time_stamp |
时间戳。 |
seq |
帧序号，若为非有效帧则为 0。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_ADEC_EINVALIDHDL |
adec_hdl 超出范围。 |
HI_MAPI_ADEC_ENULLPTR |
adec_stream 或 adec_stream->stream 为 TD_NULL。 |
HI_MAPI_ADEC_ENOTINITED |
MAPI 媒体子系统未初始化。 |
HI_MAPI_ADEC_ESTATEERR |
通道尚未 init。 |
HI_MAPI_ADEC_ERR_BUF_FULL |
非阻塞模式下缓冲区已满。 |
【需求】
- 头文件：
hi_mapi_adec.h - 库文件：
libhi_mapi.so
【注意】
- 第一次调用
send_stream时，内部会把stream_started标志置为TD_TRUE，此后hi_mapi_adec_set_param中所有_CONFIG命令都会被拒绝。 - OPUS 码流若采用
HI_MAPI_AUDIO_PAYLOAD_STANDARD（裸 RTP），适配层会自动为其补上 8 字节大端长度头再送入 SDK 解码器。
【举例】 无
【相关主题】
hi_mapi_adec_get_frame、hi_mapi_adec_set_param
4 hi_mapi_adec_get_frame
【描述】 从解码通道取出一帧解码后的 PCM 音频数据。
【语法】
td_s32 hi_mapi_adec_get_frame(td_handle adec_hdl, hi_mapi_audio_frame_info *audio_frame_info, td_bool block);
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
adec_hdl |
输入 | td_handle |
音频解码通道句柄，取值范围：0～3。 |
audio_frame_info |
输出 | hi_mapi_audio_frame_info * |
输出帧信息结构指针，不能为 TD_NULL。 |
block |
输入 | td_bool |
TD_TRUE 阻塞获取；TD_FALSE 非阻塞。 |
成员名称（hi_mapi_audio_frame_info） |
描述 |
|---|---|
frame |
输出：指向获取到的 hi_mapi_audio_frame 的指针，可用于传递给 hi_mapi_adec_release_frame。 |
audio_frame |
获取到的音频帧内容。 |
index |
帧序号，释放时用作唯一标识。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_ADEC_EINVALIDHDL |
adec_hdl 超出范围。 |
HI_MAPI_ADEC_ENULLPTR |
audio_frame_info 为 TD_NULL。 |
HI_MAPI_ADEC_ENOTINITED |
MAPI 媒体子系统未初始化。 |
HI_MAPI_ADEC_ESTATEERR |
通道尚未 init。 |
【需求】
- 头文件：
hi_mapi_adec.h - 库文件：
libhi_mapi.so
【注意】
- 取到的帧必须通过
hi_mapi_adec_release_frame释放，否则会泄漏内部缓冲。
【举例】 无
【相关主题】
hi_mapi_adec_release_frame、hi_mapi_adec_send_stream
5 hi_mapi_adec_release_frame
【描述】
释放由 hi_mapi_adec_get_frame 获取的 PCM 帧资源。
【语法】
td_s32 hi_mapi_adec_release_frame(td_handle adec_hdl, const hi_mapi_audio_frame_info *audio_frame_info);
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
adec_hdl |
输入 | td_handle |
音频解码通道句柄，取值范围：0～3。 |
audio_frame_info |
输入 | const hi_mapi_audio_frame_info * |
待释放帧信息指针，不能为 TD_NULL；其成员 frame 也不能为 TD_NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_ADEC_EINVALIDHDL |
adec_hdl 超出范围。 |
HI_MAPI_ADEC_ENULLPTR |
audio_frame_info 或 audio_frame_info->frame 为 TD_NULL。 |
HI_MAPI_ADEC_ENOTINITED |
MAPI 媒体子系统未初始化。 |
HI_MAPI_ADEC_ESTATEERR |
通道尚未 init。 |
【需求】
- 头文件：
hi_mapi_adec.h - 库文件：
libhi_mapi.so
【注意】
- 必须与
hi_mapi_adec_get_frame配对使用。
【举例】 无
【相关主题】
hi_mapi_adec_get_frame
6 hi_mapi_adec_send_end_of_stream
【描述】 向解码通道发送流结束标记，通知解码器刷新内部缓冲。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
adec_hdl |
输入 | td_handle |
音频解码通道句柄，取值范围：0～3。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_ADEC_EINVALIDHDL |
adec_hdl 超出范围。 |
HI_MAPI_ADEC_ENOTINITED |
MAPI 媒体子系统未初始化。 |
HI_MAPI_ADEC_ESTATEERR |
通道尚未 init。 |
【需求】
- 头文件：
hi_mapi_adec.h - 库文件：
libhi_mapi.so
【注意】 无
【举例】 无
【相关主题】
hi_mapi_adec_send_stream
7 hi_mapi_adec_get_default_attr
【描述】
按解码格式返回推荐的默认 ADEC 属性（自动填充 adec_mode：LPCM 使用 PACK 模式，其他格式使用 STREAM 模式）。
【语法】
td_s32 hi_mapi_adec_get_default_attr(hi_mapi_audio_format adec_format, hi_mapi_adec_attr *adec_attr);
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
adec_format |
输入 | hi_mapi_audio_format |
解码格式。 |
adec_attr |
输出 | hi_mapi_adec_attr * |
被填充后的默认属性，不能为 TD_NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_ADEC_ENULLPTR |
adec_attr 为 TD_NULL。 |
HI_MAPI_ADEC_EILLPARAM |
adec_format 越界（<0 或 ≥HI_MAPI_AUDIO_FORMAT_BUTT）。 |
【需求】
- 头文件：
hi_mapi_adec.h - 库文件：
libhi_mapi.so
【注意】
- 默认模式规则：
LPCM→HI_MAPI_ADEC_MODE_PACK；其他格式 →HI_MAPI_ADEC_MODE_STREAM。 - 用户可在获取默认值后按需覆盖
adec_mode字段。
【举例】
参见【相关主题】中 SAMPLE_AUDIO_BindAdecAndStartAo。
【相关主题】
hi_mapi_adec_init
8 hi_mapi_adec_set_param
【描述】
设置 ADEC 扩展参数（命令分发接口）。以 _CONFIG 结尾的命令必须在首次调用 hi_mapi_adec_send_stream 之前设置，否则返回状态错误。
【语法】
td_s32 hi_mapi_adec_set_param(td_handle adec_hdl, hi_mapi_adec_cmd cmd,
const td_void *attr, td_u32 attr_len);
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
adec_hdl |
输入 | td_handle |
音频解码通道句柄，取值范围：0～3，必须已 init。 |
cmd |
输入 | hi_mapi_adec_cmd |
扩展命令 ID，当前仅支持 HI_MAPI_ADEC_CMD_PAYLOAD_FORMAT_CONFIG（仅 OPUS 有效）。 |
attr |
输入 | const td_void * |
命令对应属性结构指针，不能为 TD_NULL；对 PAYLOAD_FORMAT_CONFIG 为 hi_mapi_audio_payload_format。 |
attr_len |
输入 | td_u32 |
缓冲字节长度，必须 ≥ sizeof(hi_mapi_audio_payload_format)。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_ADEC_EINVALIDHDL |
adec_hdl 超出范围。 |
HI_MAPI_ADEC_ENULLPTR |
attr 为 TD_NULL。 |
HI_MAPI_ADEC_ENOTINITED |
MAPI 未初始化。 |
HI_MAPI_ADEC_ESTATEERR |
通道未 init；或对 _CONFIG 命令，通道已开始送流。 |
HI_MAPI_ADEC_EILLPARAM |
cmd 未知；或 attr_len 过小；或用于非 OPUS 格式；或 payload_format 越界。 |
【需求】
- 头文件：
hi_mapi_adec.h - 库文件：
libhi_mapi.so
【注意】
HI_MAPI_ADEC_CMD_PAYLOAD_FORMAT_CONFIG：设置输入 OPUS 码流的封装格式。HI_MAPI_AUDIO_PAYLOAD_HI_NATIVE（默认，调用方已在每帧前带 8 字节大端长度头）；HI_MAPI_AUDIO_PAYLOAD_STANDARD（裸 RTP 载荷，由适配层补齐长度头再送入 SDK 解码器）。- 在首次
hi_mapi_adec_send_stream之后调用_CONFIG命令将返回HI_MAPI_ADEC_ESTATEERR。
【举例】
参见【相关主题】中 SAMPLE_AUDIO_BindAdecAndStartAo 的 OPUS 分支。
【相关主题】
hi_mapi_adec_get_param、hi_mapi_adec_send_stream
9 hi_mapi_adec_get_param
【描述】 读取 ADEC 扩展参数的当前值。
【语法】
td_s32 hi_mapi_adec_get_param(td_handle adec_hdl, hi_mapi_adec_cmd cmd,
td_void *attr, td_u32 attr_len);
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
adec_hdl |
输入 | td_handle |
音频解码通道句柄，取值范围：0～3，必须已 init。 |
cmd |
输入 | hi_mapi_adec_cmd |
扩展命令 ID，当前仅支持 HI_MAPI_ADEC_CMD_PAYLOAD_FORMAT_CONFIG。 |
attr |
输出 | td_void * |
接收属性值的用户缓冲区，不能为 TD_NULL。 |
attr_len |
输入 | td_u32 |
缓冲字节长度，必须 ≥ 对应结构体大小。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_ADEC_EINVALIDHDL |
adec_hdl 超出范围。 |
HI_MAPI_ADEC_ENULLPTR |
attr 为 TD_NULL。 |
HI_MAPI_ADEC_ENOTINITED |
MAPI 未初始化。 |
HI_MAPI_ADEC_ESTATEERR |
通道未 init。 |
HI_MAPI_ADEC_EILLPARAM |
cmd 未知；或 attr_len 过小。 |
【需求】
- 头文件：
hi_mapi_adec.h - 库文件：
libhi_mapi.so
【注意】 无
【举例】
参见【相关主题】中 SAMPLE_AUDIO_BindAdecAndStartAo 的 OPUS 分支。
【相关主题】
hi_mapi_adec_set_param
4 数据类型
1 hi_mapi_adec_mode
【说明】 定义 ADEC 解码模式枚举，区分按帧（PACK）模式与按流（STREAM）模式。
【定义】
typedef enum {
HI_MAPI_ADEC_MODE_PACK = 0,
HI_MAPI_ADEC_MODE_STREAM,
HI_MAPI_ADEC_MODE_BUTT
} hi_mapi_adec_mode;
【成员】
| 成员名称 | 描述 |
|---|---|
HI_MAPI_ADEC_MODE_PACK |
按帧模式：要求输入为有效的解码帧（如 AENC 输出的完整帧、文件中已知帧长的码流）。高性能模式。 |
HI_MAPI_ADEC_MODE_STREAM |
按流模式：输入为连续码流，不要求帧边界对齐。低性能模式，适用于无法确定帧边界的场景。 |
HI_MAPI_ADEC_MODE_BUTT |
哨兵值。 |
【注意事项】
- LPCM 格式推荐使用
PACK模式。 - 可通过
hi_mapi_adec_get_default_attr获取默认模式。
【相关数据类型及接口】
hi_mapi_adec_attr、hi_mapi_adec_get_default_attr。
2 hi_mapi_adec_attr
【说明】 定义 ADEC 音频解码器初始化属性结构，包含解码格式与解码模式。
【定义】
typedef struct {
hi_mapi_audio_format adec_format;
hi_mapi_adec_mode adec_mode;
} hi_mapi_adec_attr;
【成员】
| 成员名称 | 描述 |
|---|---|
adec_format |
音频解码格式，参见 hi_mapi_audio_format（公共数据类型）。 |
adec_mode |
解码模式，参见 hi_mapi_adec_mode。 |
【注意事项】
- CV610 平台 ADEC 最大通道数为 8（
OT_ADEC_MAX_CHN_NUM= 8）。 - 可通过
hi_mapi_adec_get_default_attr获取默认属性，自动填充adec_mode（LPCM 使用PACK模式，其他格式使用STREAM模式）。
【相关数据类型及接口】
hi_mapi_adec_init、hi_mapi_adec_get_default_attr、hi_mapi_adec_mode。
3 hi_mapi_audio_frame_info
【说明】 定义音频帧信息结构，用于 ADEC 解码输出时携带解码后的 PCM 帧及其索引。
【定义】
typedef struct {
hi_mapi_audio_frame *frame;
hi_mapi_audio_frame audio_frame;
td_u32 index;
} hi_mapi_audio_frame_info;
【成员】
| 成员名称 | 描述 |
|---|---|
frame |
指向音频帧的指针。 |
audio_frame |
音频帧数据副本。 |
index |
音频帧索引，释放帧时作为唯一标识使用。 |
【注意事项】 无
【相关数据类型及接口】
hi_mapi_audio_frame；hi_mapi_adec_get_frame、hi_mapi_adec_release_frame。
4 hi_mapi_adec_cmd
【说明】
定义 ADEC 扩展命令枚举，用于 hi_mapi_adec_set_param / hi_mapi_adec_get_param 中分派命令。
【定义】
typedef enum {
HI_MAPI_ADEC_CMD_PAYLOAD_FORMAT_CONFIG = 0,
HI_MAPI_ADEC_CMD_BUTT
} hi_mapi_adec_cmd;
【成员】
| 成员名称 | 描述 |
|---|---|
HI_MAPI_ADEC_CMD_PAYLOAD_FORMAT_CONFIG |
负载格式配置，参数为 hi_mapi_audio_payload_format，仅 OPUS 解码有效。必须在第一次 hi_mapi_adec_send_stream 前设置。 |
HI_MAPI_ADEC_CMD_BUTT |
哨兵值。 |
【注意事项】
_CONFIG 后缀的命令必须在第一次 hi_mapi_adec_send_stream 之前调用；若送流已开始，调用会返回 HI_MAPI_ADEC_ESTATEERR。
【相关数据类型及接口】
hi_mapi_adec_set_param、hi_mapi_adec_get_param、hi_mapi_audio_payload_format（公共数据类型）。
5 错误码
模块编号
mod=9，错误码基址0xA3098000。
| 错误代码 | 宏定义 | 描述 |
|---|---|---|
0xA3098002 |
HI_MAPI_ADEC_EINVALIDHDL |
通道号无效。 |
0xA3098003 |
HI_MAPI_ADEC_EILLPARAM |
参数非法。 |
0xA3098006 |
HI_MAPI_ADEC_ENULLPTR |
空指针。 |
0xA3098009 |
HI_MAPI_ADEC_ESTATEERR |
操作未授权。 |
0xA3098010 |
HI_MAPI_ADEC_ENOTINITED |
系统未就绪。 |