跳转至

AENC(音频编码)接口说明文档

文档版本 V1.1
修订日期 2026-08-21
代码基线 hi_aiot_solution 8.18
对应头文件 components/media/pipeline/include/hi_mapi_aenc.h
类型定义 components/media/pipeline/include/hi_mapi_aenc_define.hinclude/adapt/*_adapt_define.h
适用模块 AENC / HI3516CV610

1 概述

AENC(Audio Encoder)模块负责将 PCM 原始音频帧编码为压缩码流(AAC / G.711 / MP3 / LPCM / OPUS),并在编码完成后通过回调方式将码流通知上层。AENC 最多支持 2 个通道(通道号 0~1),同一编码格式在多个通道之间共享底层编码器(基于引用计数自动注册 / 注销)。AENC 既可由 ACAP 通过 bind 自动喂帧,也可在非绑定模式下由用户调用 hi_mapi_aenc_send_frame 手动喂帧。

2 接口总览

编号 接口 功能概述
1 hi_mapi_aenc_init 初始化音频编码通道,完成编码器注册、底层通道创建以及取码流线程初始化。
2 hi_mapi_aenc_deinit 反初始化音频编码通道,停止取码流线程、销毁底层通道、按引用计数注销编码器。
3 hi_mapi_aenc_start 启动音频编码通道,使能编码器开始处理音频帧。
4 hi_mapi_aenc_stop 停止音频编码通道,使其回到 STOPED 状态(仍保持 init 态)。
5 hi_mapi_aenc_register_callback 向指定编码通道注册码流回调,编码器每完成一帧编码都会通过回调上报码流数据。
6 hi_mapi_aenc_unregister_callback 从指定编码通道反注册一个码流回调。
7 hi_mapi_aenc_send_frame 在非绑定模式下,由用户主动将一帧 PCM 音频数据送入编码器。若通道已与 ACAP 绑定则禁止调用。
8 hi_mapi_aenc_get_default_attr 按编码格式返回一套推荐的默认 AENC 属性,自动填充 pt_num_per_frmvaluevalue_len,便于上层快速初始化。
9 hi_mapi_aenc_set_param 设置 AENC 扩展参数(命令分发接口)。以 _CONFIG 结尾的命令必须在 hi_mapi_aenc_start 之前调用,否则返回状态错误。
10 hi_mapi_aenc_get_param 读取 AENC 扩展参数的当前值(命令分发接口)。

3 API 参考

1 hi_mapi_aenc_init

【描述】 初始化音频编码通道,完成编码器注册、底层通道创建以及取码流线程初始化。

【语法】

td_s32 hi_mapi_aenc_init(td_handle aenc_hdl, const hi_mapi_aenc_attr *aenc_attr);

【参数】

参数名称 输入/输出 类型 描述
aenc_hdl 输入 td_handle 音频编码通道句柄,取值范围:0~1(HI3516CV610 上最多 2 个 AENC 通道)。
aenc_attr 输入 const hi_mapi_aenc_attr * 音频编码通道属性指针,不能为 TD_NULL
成员名称 描述
aenc_format 编码格式,枚举 hi_mapi_audio_formatAACLC / G711A / G711U / MP3(需开启 ENABLE_MP3)/ LPCM / OPUS(需开启 AUDIO_COMP_HAS_OPUS_SDK)。
pt_num_per_frm 每帧采样点数。AAC-LC 通常为 1024,G.711 典型为 320/480,MP3 固定为 1152,LPCM 可配(默认 1024),OPUS 典型为 160/320/480。
value 指向编码格式私有属性结构(如 hi_mapi_aenc_aac_attr / hi_mapi_aenc_opus_attr / hi_mapi_aenc_mp3_attr 等)的指针;G.711 / LPCM 可传只含 resv 的默认属性。
value_len value 所指结构体的字节数,必须与真实类型大小一致。

【返回值】

返回值 描述
0 成功。
非0 失败,其值为错误码。
HI_MAPI_AENC_EINVALIDHDL aenc_hdl 超出范围(≥2)。
HI_MAPI_AENC_ENULLPTR aenc_attrTD_NULL
HI_MAPI_AENC_ENOTINITED MAPI 媒体子系统尚未初始化(需先调用 hi_mapi_sys_init)。
HI_MAPI_AENC_EILLPARAM 编码格式不支持,或 OPUS / MP3 未编入固件。
HI_MAPI_AENC_ENOTINITED 内部取码流线程创建失败。

【需求】

  • 头文件:hi_mapi_aenc.h
  • 库文件:libhi_mapi.so

【注意】

  • 同一通道重复调用 init:若通道已处于 STARTED 状态直接返回成功;若处于 STOPEDaenc_formatpt_num_per_frm 均未改变也直接返回成功;否则先释放旧格式引用再按新属性重新创建。
  • init 内部会自动调用底层编码器注册(按格式引用计数),用户无需再手动注册。
  • 编码格式对应的私有属性结构见 hi_mapi_aenc_adpt.h:AAC → hi_mapi_aenc_aac_attr;OPUS → hi_mapi_aenc_opus_attr;MP3 → hi_mapi_aenc_mp3_attr;G.711 → hi_mapi_aenc_g711_attr;LPCM → hi_mapi_aenc_lpcm_attr

【举例】 参见【相关主题】中 SAMPLE_AUDIO_StartAenc

【相关主题】 hi_mapi_aenc_get_default_attrhi_mapi_aenc_starthi_mapi_aenc_deinit

2 hi_mapi_aenc_deinit

【描述】 反初始化音频编码通道,停止取码流线程、销毁底层通道、按引用计数注销编码器。

【语法】

td_s32 hi_mapi_aenc_deinit(td_handle aenc_hdl);

【参数】

参数名称 输入/输出 类型 描述
aenc_hdl 输入 td_handle 音频编码通道句柄,取值范围:0~1。

【返回值】

返回值 描述
0 成功。
非0 失败,其值为错误码。
HI_MAPI_AENC_EINVALIDHDL aenc_hdl 超出范围。
HI_MAPI_AENC_ENOTINITED MAPI 媒体子系统未初始化。

【需求】

  • 头文件:hi_mapi_aenc.h
  • 库文件:libhi_mapi.so

【注意】

  • 若通道当前处于 STARTED 状态,函数会先内部调用 hi_mapi_aenc_stop 再执行反初始化。
  • 若通道已经处于 UNINITED 状态则直接返回成功(幂等)。
  • 反初始化时已注册的回调会被清空。

【举例】 无

【相关主题】 hi_mapi_aenc_inithi_mapi_aenc_stop

3 hi_mapi_aenc_start

【描述】 启动音频编码通道,使能编码器开始处理音频帧。

【语法】

td_s32 hi_mapi_aenc_start(td_handle aenc_hdl);

【参数】

参数名称 输入/输出 类型 描述
aenc_hdl 输入 td_handle 音频编码通道句柄,取值范围:0~1。

【返回值】

返回值 描述
0 成功。
非0 失败,其值为错误码。
HI_MAPI_AENC_EINVALIDHDL aenc_hdl 超出范围。
HI_MAPI_AENC_ENOTINITED MAPI 媒体子系统未初始化。
HI_MAPI_AENC_ESTATEERR 通道尚未初始化(处于 UNINITED 状态)。

【需求】

  • 头文件:hi_mapi_aenc.h
  • 库文件:libhi_mapi.so

【注意】

  • 必须先调用 hi_mapi_aenc_init 成功后才能启动。
  • 重复启动(已处于 STARTED)直接返回成功。

【举例】 参见【相关主题】中 SAMPLE_AUDIO_StartAenc

【相关主题】 hi_mapi_aenc_inithi_mapi_aenc_stop

4 hi_mapi_aenc_stop

【描述】 停止音频编码通道,使其回到 STOPED 状态(仍保持 init 态)。

【语法】

td_s32 hi_mapi_aenc_stop(td_handle aenc_hdl);

【参数】

参数名称 输入/输出 类型 描述
aenc_hdl 输入 td_handle 音频编码通道句柄,取值范围:0~1。

【返回值】

返回值 描述
0 成功。
非0 失败,其值为错误码。
HI_MAPI_AENC_EINVALIDHDL aenc_hdl 超出范围。
HI_MAPI_AENC_ENOTINITED MAPI 媒体子系统未初始化。
HI_MAPI_AENC_ESTATEERR 通道尚未初始化。
HI_MAPI_AENC_EBUSY 通道已与 ACAP 绑定,需先解绑才能停止。

【需求】

  • 头文件:hi_mapi_aenc.h
  • 库文件:libhi_mapi.so

【注意】

  • 通道已与 ACAP 绑定时调用本接口会返回 HI_MAPI_AENC_EBUSY,需先调用 hi_mapi_sys_unbind
  • 重复停止(已处于 STOPED)直接返回成功。

【举例】 参见【相关主题】中 SAMPLE_AUDIO_StopAenc

【相关主题】 hi_mapi_aenc_starthi_mapi_aenc_deinit

5 hi_mapi_aenc_register_callback

【描述】 向指定编码通道注册码流回调,编码器每完成一帧编码都会通过回调上报码流数据。

【语法】

td_s32 hi_mapi_aenc_register_callback(td_handle aenc_hdl, const hi_mapi_aenc_callback *aenc_cb);

【参数】

参数名称 输入/输出 类型 描述
aenc_hdl 输入 td_handle 音频编码通道句柄,取值范围:0~1。
aenc_cb 输入 const hi_mapi_aenc_callback * 回调结构体指针,不能为 TD_NULL
成员名称 描述
proc_data_cb 码数据回调函数指针,原型:td_s32 (*)(td_handle aenc_hdl, const hi_mapi_audio_stream *audio_stream_data, td_void *private_data)
private_data 用户自定义私有数据,会原样传递给回调。

【返回值】

返回值 描述
0 成功。
非0 失败,其值为错误码。
HI_MAPI_AENC_EINVALIDHDL aenc_hdl 超出范围。
HI_MAPI_AENC_ENULLPTR aenc_cbTD_NULL
HI_MAPI_AENC_ENOTINITED MAPI 媒体子系统未初始化。
HI_MAPI_AENC_ESTATEERR 通道尚未初始化。
HI_MAPI_AENC_ERESFULL 已注册回调数量达到上限(每通道最多 5 个)。

【需求】

  • 头文件:hi_mapi_aenc.h
  • 库文件:libhi_mapi.so

【注意】

  • 同一个回调函数 + private_data 组合重复注册会被识别为更新,不占用新槽位。
  • 每个通道最多可注册 HI_MAPI_AENC_CHN_CALLBACK_MAX_NUM(5)个不同回调。
  • 必须先 init 后才能注册。

【举例】 参见【相关主题】中 SAMPLE_AUDIO_StartAenc

【相关主题】 hi_mapi_aenc_unregister_callback

6 hi_mapi_aenc_unregister_callback

【描述】 从指定编码通道反注册一个码流回调。

【语法】

td_s32 hi_mapi_aenc_unregister_callback(td_handle aenc_hdl, const hi_mapi_aenc_callback *aenc_cb);

【参数】

参数名称 输入/输出 类型 描述
aenc_hdl 输入 td_handle 音频编码通道句柄,取值范围:0~1。
aenc_cb 输入 const hi_mapi_aenc_callback * 待反注册的回调结构体指针(按 proc_data_cb + private_data 匹配),不能为 TD_NULL

【返回值】

返回值 描述
0 成功。
非0 失败,其值为错误码。
HI_MAPI_AENC_EINVALIDHDL aenc_hdl 超出范围。
HI_MAPI_AENC_ENULLPTR aenc_cbTD_NULL
HI_MAPI_AENC_ENOTINITED MAPI 媒体子系统未初始化。
HI_MAPI_AENC_ESTATEERR 通道尚未初始化。
HI_MAPI_AENC_EUNEXIST 未找到匹配的已注册回调。

【需求】

  • 头文件:hi_mapi_aenc.h
  • 库文件:libhi_mapi.so

【注意】 无

【举例】 参见【相关主题】中 SAMPLE_AUDIO_StopAenc

【相关主题】 hi_mapi_aenc_register_callback

7 hi_mapi_aenc_send_frame

【描述】 在非绑定模式下,由用户主动将一帧 PCM 音频数据送入编码器。若通道已与 ACAP 绑定则禁止调用。

【语法】

td_s32 hi_mapi_aenc_send_frame(td_handle aenc_hdl, const hi_mapi_audio_frame *audio_frm);

【参数】

参数名称 输入/输出 类型 描述
aenc_hdl 输入 td_handle 音频编码通道句柄,取值范围:0~1。
audio_frm 输入 const hi_mapi_audio_frame * 音频帧指针,不能为 TD_NULL,其 vir_addr / phy_addr 等字段由调用方填充。

【返回值】

返回值 描述
0 成功。
非0 失败,其值为错误码。
HI_MAPI_AENC_EINVALIDHDL aenc_hdl 超出范围。
HI_MAPI_AENC_ENULLPTR audio_frmTD_NULL
HI_MAPI_AENC_ENOTINITED MAPI 媒体子系统未初始化。
HI_MAPI_AENC_ESTATEERR 通道未初始化,或通道已与 ACAP 绑定(不能手动喂帧)。

【需求】

  • 头文件:hi_mapi_aenc.h
  • 库文件:libhi_mapi.so

【注意】

  • 仅适用于非绑定模式;调用前需确认通道未通过 hi_mapi_sys_bind 与 ACAP 绑定。
  • 调用前必须 init 成功,且 start 后才真正会被编码处理。

【举例】 无

【相关主题】 hi_mapi_aenc_register_callback

8 hi_mapi_aenc_get_default_attr

【描述】 按编码格式返回一套推荐的默认 AENC 属性,自动填充 pt_num_per_frmvaluevalue_len,便于上层快速初始化。

【语法】

td_s32 hi_mapi_aenc_get_default_attr(hi_mapi_audio_format aenc_format, hi_mapi_aenc_attr *aenc_attr);

【参数】

参数名称 输入/输出 类型 描述
aenc_format 输入 hi_mapi_audio_format 编码格式。
aenc_attr 输出 hi_mapi_aenc_attr * 被填充后的默认属性,不能为 TD_NULL

【返回值】

返回值 描述
0 成功。
非0 失败,其值为错误码。
HI_MAPI_AENC_ENULLPTR aenc_attrTD_NULL
HI_MAPI_AENC_EILLPARAM aenc_format 不在支持集合内。

【需求】

  • 头文件:hi_mapi_aenc.h
  • 库文件:libhi_mapi.so

【注意】

  • 各格式默认值如下表(value 指向静态只读结构,用户可在此基础上修改后再传给 hi_mapi_aenc_init):
格式 默认 pt_num_per_frm 默认 value 结构
AACLC 1024 hi_mapi_aenc_aac_attr(AAC-LC / 64kbps / 16kHz / 16bit / mono / ADTS / band_width=0)
G711A / G711U 480 hi_mapi_aenc_g711_attr
LPCM 1024 hi_mapi_aenc_lpcm_attr
OPUS 320(20ms @16kHz) hi_mapi_aenc_opus_attr(16kHz / 16bit / mono / 24kbps / VOIP)
MP3(若启用) 1152 hi_mapi_aenc_mp3_attr(16kHz / 16bit / mono / 64kbps / quality=7)

【举例】 无

【相关主题】 hi_mapi_aenc_init

9 hi_mapi_aenc_set_param

【描述】 设置 AENC 扩展参数(命令分发接口)。以 _CONFIG 结尾的命令必须在 hi_mapi_aenc_start 之前调用,否则返回状态错误。

【语法】

td_s32 hi_mapi_aenc_set_param(td_handle aenc_hdl, hi_mapi_aenc_cmd cmd,
                              const td_void *attr, td_u32 attr_len);

【参数】

参数名称 输入/输出 类型 描述
aenc_hdl 输入 td_handle 音频编码通道句柄,取值范围:0~1,必须已 init
cmd 输入 hi_mapi_aenc_cmd 扩展命令 ID。当前仅支持 HI_MAPI_AENC_CMD_PAYLOAD_FORMAT_CONFIG(仅 OPUS 有效)。
attr 输入 const td_void * 命令对应属性结构指针,不能为 TD_NULL。对于 PAYLOAD_FORMAT_CONFIGhi_mapi_audio_payload_format
attr_len 输入 td_u32 *attr 字节长度,必须 ≥ 对应结构体大小(PAYLOAD_FORMAT_CONFIG 要求 ≥ sizeof(hi_mapi_audio_payload_format))。

【返回值】

返回值 描述
0 成功。
非0 失败,其值为错误码。
HI_MAPI_AENC_EINVALIDHDL aenc_hdl 超出范围。
HI_MAPI_AENC_ENULLPTR attrTD_NULL
HI_MAPI_AENC_ENOTINITED MAPI 未初始化或通道未 init
HI_MAPI_AENC_ESTATEERR _CONFIG 类命令,通道已处于 STARTED 状态。
HI_MAPI_AENC_EILLPARAM cmd 未知;或 attr_len 过小;或 PAYLOAD_FORMAT_CONFIG 用在了非 OPUS 格式上;或 payload_format 越界。

【需求】

  • 头文件:hi_mapi_aenc.h
  • 库文件:libhi_mapi.so

【注意】

  • HI_MAPI_AENC_CMD_PAYLOAD_FORMAT_CONFIG:设置编码后 OPUS 码流的封装格式,默认 HI_MAPI_AUDIO_PAYLOAD_HI_NATIVE(SDK 私有打包:每帧前带 8 字节大端长度头);可选 HI_MAPI_AUDIO_PAYLOAD_STANDARD(裸 RTP 载荷,符合 RFC 7587)。仅对 HI_MAPI_AUDIO_FORMAT_OPUS 有效。
  • 必须在 init 之后、start 之前调用。

【举例】 参见【相关主题】中 SAMPLE_AUDIO_StartAenc 的 OPUS 分支。

【相关主题】 hi_mapi_aenc_get_param

10 hi_mapi_aenc_get_param

【描述】 读取 AENC 扩展参数的当前值(命令分发接口)。

【语法】

td_s32 hi_mapi_aenc_get_param(td_handle aenc_hdl, hi_mapi_aenc_cmd cmd,
                              td_void *attr, td_u32 attr_len);

【参数】

参数名称 输入/输出 类型 描述
aenc_hdl 输入 td_handle 音频编码通道句柄,取值范围:0~1,必须已 init
cmd 输入 hi_mapi_aenc_cmd 扩展命令 ID,当前仅支持 HI_MAPI_AENC_CMD_PAYLOAD_FORMAT_CONFIG
attr 输出 td_void * 接收属性值的用户缓冲区,不能为 TD_NULL
attr_len 输入 td_u32 缓冲区字节长度,必须 ≥ 对应结构体大小。

【返回值】

返回值 描述
0 成功。
非0 失败,其值为错误码。
HI_MAPI_AENC_EINVALIDHDL aenc_hdl 超出范围。
HI_MAPI_AENC_ENULLPTR attrTD_NULL
HI_MAPI_AENC_ENOTINITED MAPI 未初始化或通道未 init
HI_MAPI_AENC_EILLPARAM cmd 未知;或 attr_len 过小。

【需求】

  • 头文件:hi_mapi_aenc.h
  • 库文件:libhi_mapi.so

【注意】 无

【举例】 参见【相关主题】中 SAMPLE_AUDIO_StartAenc 的 OPUS 分支。

【相关主题】 hi_mapi_aenc_set_param

4 数据类型

1 hi_mapi_aenc_attr

【说明】 定义 AENC 音频编码器初始化属性结构,包含编码格式、每帧采样点数及编码器私有属性。

【定义】

typedef struct {
    hi_mapi_audio_format aenc_format;
    td_u32 pt_num_per_frm;
    td_void *value;
    td_u32 value_len;
} hi_mapi_aenc_attr;

【成员】

成员名称 描述
aenc_format 音频编码格式,参见 hi_mapi_audio_format公共数据类型)。
pt_num_per_frm 每帧采样点数。取值范围 [1, 2048]HI_MAPI_AIO_MAX_POINT_PER_FRAME)。
value 指向编码器私有属性结构的指针。如 hi_mapi_aenc_g711_attrhi_mapi_aenc_lpcm_attr 等。
value_len value 所指结构的字节长度。

【注意事项】

  • CV610 平台 AENC 最大通道数为 8(OT_AENC_MAX_CHN_NUM = 8)。
  • 可通过 hi_mapi_aenc_get_default_attr 获取默认属性,自动填充 pt_num_per_frmvaluevalue_len
  • 编码器注册由 hi_mapi_aenc_init / hi_mapi_aenc_deinit 内部处理。

【相关数据类型及接口】 hi_mapi_aenc_inithi_mapi_aenc_get_default_attrhi_mapi_aenc_g711_attrhi_mapi_aenc_lpcm_attr

2 hi_mapi_aenc_proc_data_cb

【说明】 定义 AENC 码流数据回调函数指针类型,编码器每完成一帧编码都会通过该回调上报码流数据。

【定义】

typedef td_s32 (*hi_mapi_aenc_proc_data_cb)(td_handle aenc_hdl,
    const hi_mapi_audio_stream *audio_stream_data, td_void *private_data);

【成员】

成员名称 描述
aenc_hdl AENC 通道句柄。
audio_stream_data 编码后的码流数据,参见 hi_mapi_audio_stream
private_data 用户私有数据指针,由 hi_mapi_aenc_callback.private_data 传入。

【注意事项】 回调函数在编码器内部线程中执行,不应阻塞或执行耗时操作。

【相关数据类型及接口】 hi_mapi_aenc_callbackhi_mapi_audio_streamhi_mapi_aenc_register_callback

3 hi_mapi_aenc_callback

【说明】 定义 AENC 回调结构,包含码流数据回调函数指针及用户私有数据。

【定义】

typedef struct {
    hi_mapi_aenc_proc_data_cb proc_data_cb;
    td_void *private_data;
} hi_mapi_aenc_callback;

【成员】

成员名称 描述
proc_data_cb 码流数据回调函数指针,参见 hi_mapi_aenc_proc_data_cb
private_data 用户私有数据指针,会在回调时原样传回。

【注意事项】 CV610 平台单通道最大回调数为 5(HI_MAPI_AENC_CHN_CALLBACK_MAX_NUM = 5)。

【相关数据类型及接口】 hi_mapi_aenc_proc_data_cbhi_mapi_aenc_register_callbackhi_mapi_aenc_unregister_callback

4 hi_mapi_aenc_cmd

【说明】 定义 AENC 扩展命令枚举,用于 hi_mapi_aenc_set_param / hi_mapi_aenc_get_param 中分派命令。

【定义】

typedef enum {
    HI_MAPI_AENC_CMD_PAYLOAD_FORMAT_CONFIG = 0,
    HI_MAPI_AENC_CMD_BUTT
} hi_mapi_aenc_cmd;

【成员】

成员名称 描述
HI_MAPI_AENC_CMD_PAYLOAD_FORMAT_CONFIG 负载格式配置,参数为 hi_mapi_audio_payload_format,仅 OPUS 编码有效。必须在 hi_mapi_aenc_start 前设置。
HI_MAPI_AENC_CMD_BUTT 哨兵值。

【注意事项】 _CONFIG 后缀的命令必须在 hi_mapi_aenc_start 之前调用;若通道已启动,调用会返回 HI_MAPI_AENC_ESTATEERR

【相关数据类型及接口】 hi_mapi_aenc_set_paramhi_mapi_aenc_get_paramhi_mapi_audio_payload_format公共数据类型)。

5 hi_mapi_aenc_g711_attr

【说明】 定义 AENC G.711 编码器私有属性结构。当前为保留结构。

【定义】

typedef struct {
    td_u32 resv;
} hi_mapi_aenc_g711_attr;

【成员】

成员名称 描述
resv 保留字段,必须为 0。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_aenc_attr

6 hi_mapi_aenc_lpcm_attr

【说明】 定义 AENC LPCM 编码器私有属性结构。当前为保留结构。

【定义】

typedef struct {
    td_u32 resv;
} hi_mapi_aenc_lpcm_attr;

【成员】

成员名称 描述
resv 保留字段,必须为 0。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_aenc_attr

5 错误码

模块编号 mod=5,错误码基址 0xA3058000

错误代码 宏定义 描述
0xA3058002 HI_MAPI_AENC_EINVALIDHDL 句柄无效。
0xA3058003 HI_MAPI_AENC_EILLPARAM 参数非法。
0xA3058006 HI_MAPI_AENC_ENULLPTR 空指针。
0xA3058009 HI_MAPI_AENC_ESTATEERR 状态错误。
0xA3058010 HI_MAPI_AENC_ENOTINITED 模块未初始化。