AO（音频输出）接口说明文档

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

1 概述

AO（Audio Output）模块负责把 PCM 音频帧通过内部 Audio Codec 或外部 I2S 接口输出到扬声器 / 耳机等播放设备。HI3516CV610 上 AO 最多支持 2 个设备（设备号 0～1），每个设备最多 2 个用户通道（通道号 0～1，通道 2 被内部系统通道占用）。AO 支持音量 / 静音控制、采样率重采样、VQE（语音质量增强）等功能。

2 接口总览

编号	接口	功能概述
1	`hi_mapi_ao_init`	初始化指定 AO 设备，设置其公共属性（采样率、位宽、声道、工作模式等）。
2	`hi_mapi_ao_deinit`	反初始化指定 AO 设备。若设备处于 `STARTED` 状态，会先停止所有已启动的通道。
3	`hi_mapi_ao_start`	启动指定 AO 设备的某个通道。第一次启动时会同时启动设备本身并尝试启用硬件重采样（若 `sample_rate` 与 `in_sample_rate` 不同）。
4	`hi_mapi_ao_stop`	停止指定 AO 设备的某个通道。所有用户通道都停止后，设备整体也会停止。
5	`hi_mapi_ao_enable_vqe`	启用指定 AO 通道的 VQE（语音质量增强）功能，如 HPF / ANR / AGC / EQ（需固件开启 `SUPPORT_TALKVQE`）。
6	`hi_mapi_ao_disable_vqe`	禁用指定 AO 通道的 VQE 功能（需固件开启 `SUPPORT_TALKVQE`）。
7	`hi_mapi_ao_set_volume`	设置 AO 输出音量（dB 为单位，作用于内部 Audio Codec）。
8	`hi_mapi_ao_get_volume`	获取 AO 当前输出音量（dB）。
9	`hi_mapi_ao_set_mute`	设置 AO 输出静音 / 取消静音状态。
10	`hi_mapi_ao_send_frame`	向指定 AO 通道发送一帧 PCM 音频数据。
11	`hi_mapi_ao_send_sys_frame`	向指定 AO 设备的系统通道（`OT_AO_SYS_CHN_ID`）发送一帧 PCM 音频数据。系统通道用于播放系统提示音等优先级较高的音频。
12	`hi_mapi_ao_get_default_attr`	按采样率与声道模式返回推荐的默认 AO 属性，其余字段由库填充为常见默认值。

3 API 参考

1 hi_mapi_ao_init

【描述】初始化指定 AO 设备，设置其公共属性（采样率、位宽、声道、工作模式等）。

【语法】

td_s32 hi_mapi_ao_init(td_handle ao_hdl, const hi_mapi_ao_attr *ao_attr);

【参数】

参数名称	输入/输出	类型	描述
`ao_hdl`	输入	`td_handle`	AO 设备句柄，取值范围：0～1（HI3516CV610 上共 2 个 AO 设备）。
`ao_attr`	输入	`const hi_mapi_ao_attr *`	AO 设备属性指针，不能为 `TD_NULL`。

成员名称	描述
`sample_rate`	输出采样率（Hz），枚举 `hi_mapi_audio_sample_rate`，例如 8000/16000/48000。
`bit_width`	采样位宽，枚举 `hi_mapi_audio_bit_width`，通常取 `HI_MAPI_AUDIO_BIT_WIDTH_16`。
`sound_mode`	声道模式：`HI_MAPI_AUDIO_SOUND_MODE_MONO` 或 `_STEREO`。
`track_mode`	声道轨迹模式，枚举 `hi_mapi_audio_track_mode`，常用 `HI_MAPI_AUDIO_TRACK_NORMAL`。
`work_mode`	AIO 工作模式，枚举 `hi_mapi_aio_work_mode`：`I2S_MASTER` / `I2S_SLAVE` / `PCM_SLAVE_STD` 等。
`pt_num_per_frm`	每帧采样点数（建议与 ADEC / ACAP 保持一致，典型 1024；OPUS 建议为 `sample_rate/100`）。
`in_sample_rate`	输入重采样率；当与 `sample_rate` 不同时启用硬件重采样。
`i2s_type`	I2S 接入类型，枚举 `hi_mapi_aio_i2s_type`：`INNERCODEC` / `INNERHDMI` / `EXTERN`。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_AO_EINVALIDHDL`	`ao_hdl` 超出范围（≥2）。
`HI_MAPI_AO_ENULLPTR`	`ao_attr` 为 `TD_NULL`。
`HI_MAPI_AO_ENOTINITED`	AO 子系统未被预初始化（需先调用 `hi_mapi_sys_init`）。
`HI_MAPI_AO_ESTATEERR`	AO 设备已处于 `STARTED` 状态。

【需求】

头文件：hi_mapi_ao.h
库文件：libhi_mapi.so

【注意】

若设备处于 STOPED 且新传入 ao_attr 与现有属性全部相同，则直接返回成功（幂等）。
若属性改变，会重新下发 SDK 公共属性。

【举例】参见【相关主题】中 SAMPLE_AUDIO_StartAo。

【相关主题】 hi_mapi_ao_get_default_attr、hi_mapi_ao_deinit

2 hi_mapi_ao_deinit

【描述】反初始化指定 AO 设备。若设备处于 STARTED 状态，会先停止所有已启动的通道。

【语法】

td_s32 hi_mapi_ao_deinit(td_handle ao_hdl);

【参数】

参数名称	输入/输出	类型	描述
`ao_hdl`	输入	`td_handle`	AO 设备句柄，取值范围：0～1。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_AO_EINVALIDHDL`	`ao_hdl` 超出范围。
`HI_MAPI_AO_ENOTINITED`	AO 子系统未被预初始化。

【需求】

头文件：hi_mapi_ao.h
库文件：libhi_mapi.so

【注意】

若设备已处于 UNINITED 状态，则直接返回成功（幂等）。
反初始化时所有通道的启动标志都会被清除。

【举例】参见【相关主题】中 SAMPLE_AUDIO_StopAo。

【相关主题】 hi_mapi_ao_init

3 hi_mapi_ao_start

【描述】启动指定 AO 设备的某个通道。第一次启动时会同时启动设备本身并尝试启用硬件重采样（若 sample_rate 与 in_sample_rate 不同）。

【语法】

td_s32 hi_mapi_ao_start(td_handle ao_hdl, td_handle ao_chn_hdl);

【参数】

参数名称	输入/输出	类型	描述
`ao_hdl`	输入	`td_handle`	AO 设备句柄，取值范围：0～1。
`ao_chn_hdl`	输入	`td_handle`	AO 通道句柄，取值范围：0～1（HI3516CV610 上共 3 个通道，通道 2 为系统通道 `OT_AO_SYS_CHN_ID`，用户可用通道为 0～1）。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_AO_EINVALIDHDL`	`ao_hdl` 或 `ao_chn_hdl` 超出范围。
`HI_MAPI_AO_ENOTINITED`	AO 子系统未被预初始化。
`HI_MAPI_AO_ESTATEERR`	AO 设备尚未 `init`。

【需求】

头文件：hi_mapi_ao.h
库文件：libhi_mapi.so

【注意】

必须先 hi_mapi_ao_init 后才能启动通道。
重复启动同一通道（已处于已启动）直接返回成功。
若 sample_rate 与 in_sample_rate 不同，会自动启用重采样；重采样启用失败会回滚通道使能。

【举例】参见【相关主题】中 SAMPLE_AUDIO_StartAo。

【相关主题】 hi_mapi_ao_stop、hi_mapi_ao_init

4 hi_mapi_ao_stop

【描述】停止指定 AO 设备的某个通道。所有用户通道都停止后，设备整体也会停止。

【语法】

td_s32 hi_mapi_ao_stop(td_handle ao_hdl, td_handle ao_chn_hdl);

【参数】

参数名称	输入/输出	类型	描述
`ao_hdl`	输入	`td_handle`	AO 设备句柄，取值范围：0～1。
`ao_chn_hdl`	输入	`td_handle`	AO 通道句柄，取值范围：0～1。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_AO_EINVALIDHDL`	`ao_hdl` 或 `ao_chn_hdl` 超出范围。
`HI_MAPI_AO_ENOTINITED`	AO 子系统未被预初始化。
`HI_MAPI_AO_ESTATEERR`	AO 设备尚未 `init` 或已停止。

【需求】

头文件：hi_mapi_ao.h
库文件：libhi_mapi.so

【注意】

停止通道时若启用了重采样，会自动关闭重采样。
设备下仍有其他已启动通道时，只关闭当前通道，不整体停止设备。

【举例】参见【相关主题】中 SAMPLE_AUDIO_StopAo。

【相关主题】 hi_mapi_ao_start

5 hi_mapi_ao_enable_vqe

【描述】启用指定 AO 通道的 VQE（语音质量增强）功能，如 HPF / ANR / AGC / EQ（需固件开启 SUPPORT_TALKVQE）。

【语法】

td_s32 hi_mapi_ao_enable_vqe(td_handle ao_hdl, td_handle ao_chn_hdl, const hi_mapi_ao_vqe_attr *ao_vqe_attr);

【参数】

参数名称	输入/输出	类型	描述
`ao_hdl`	输入	`td_handle`	AO 设备句柄，取值范围：0～1。
`ao_chn_hdl`	输入	`td_handle`	AO 通道句柄，取值范围：0～1。
`ao_vqe_attr`	输入	`const hi_mapi_ao_vqe_attr *`	VQE 属性指针，不能为 `TD_NULL`。

成员名称	描述
`work_state`	工作状态，枚举 `hi_mapi_audio_work_state`：`COMMON`（通用）/ `MUSIC`（音乐）/ `NOISY`（强噪环境）。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_AO_EINVALIDHDL`	`ao_hdl` 或 `ao_chn_hdl` 超出范围。
`HI_MAPI_AO_ENULLPTR`	`ao_vqe_attr` 为 `TD_NULL`。
`HI_MAPI_AO_ENOTINITED`	AO 子系统未预初始化。
`HI_MAPI_AO_ESTATEERR`	AO 设备或指定通道尚未启动。

【需求】

头文件：hi_mapi_ao.h
库文件：libhi_mapi.so

【注意】

必须在通道 start 之后调用。
未开启 SUPPORT_TALKVQE 编译宏时函数直接返回成功但不做任何事情。

【举例】无

【相关主题】 hi_mapi_ao_disable_vqe

6 hi_mapi_ao_disable_vqe

【描述】禁用指定 AO 通道的 VQE 功能（需固件开启 SUPPORT_TALKVQE）。

【语法】

td_s32 hi_mapi_ao_disable_vqe(td_handle ao_hdl, td_handle ao_chn_hdl);

【参数】

参数名称	输入/输出	类型	描述
`ao_hdl`	输入	`td_handle`	AO 设备句柄，取值范围：0～1。
`ao_chn_hdl`	输入	`td_handle`	AO 通道句柄，取值范围：0～1。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_AO_EINVALIDHDL`	`ao_hdl` 或 `ao_chn_hdl` 超出范围。
`HI_MAPI_AO_ENOTINITED`	AO 子系统未预初始化。
`HI_MAPI_AO_ESTATEERR`	AO 设备尚未 `init`。

【需求】

头文件：hi_mapi_ao.h
库文件：libhi_mapi.so

【注意】

若 AO 或通道已停止，则直接返回成功（幂等）。
未开启 SUPPORT_TALKVQE 时函数直接返回成功但不做任何事情。

【举例】无

【相关主题】 hi_mapi_ao_enable_vqe

7 hi_mapi_ao_set_volume

【描述】设置 AO 输出音量（dB 为单位，作用于内部 Audio Codec）。

【语法】

td_s32 hi_mapi_ao_set_volume(td_handle ao_hdl, td_s32 audio_gain);

【参数】

参数名称	输入/输出	类型	描述
`ao_hdl`	输入	`td_handle`	AO 设备句柄，取值范围：0～1。
`audio_gain`	输入	`td_s32`	音量增益，单位 dB，取值范围：-121～6（`HI_MAPI_AO_MIN_GAIN` ～ `HI_MAPI_AO_MAX_GAIN`）。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_AO_EINVALIDHDL`	`ao_hdl` 超出范围。
`HI_MAPI_AO_EILLPARAM`	`audio_gain` 不在 [-121, 6] 范围内。
`HI_MAPI_AO_ENOTINITED`	AO 子系统未预初始化。

【需求】

头文件：hi_mapi_ao.h
库文件：libhi_mapi.so

【注意】无

【举例】参见【相关主题】中 SAMPLE_AUDIO_StartAo。

【相关主题】 hi_mapi_ao_get_volume

8 hi_mapi_ao_get_volume

【描述】获取 AO 当前输出音量（dB）。

【语法】

td_s32 hi_mapi_ao_get_volume(td_handle ao_hdl, td_s32 *audio_gain);

【参数】

参数名称	输入/输出	类型	描述
`ao_hdl`	输入	`td_handle`	AO 设备句柄，取值范围：0～1。
`audio_gain`	输出	`td_s32 *`	输出音量（dB），不能为 `TD_NULL`。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_AO_EINVALIDHDL`	`ao_hdl` 超出范围。
`HI_MAPI_AO_ENULLPTR`	`audio_gain` 为 `TD_NULL`。
`HI_MAPI_AO_ENOTINITED`	AO 子系统未预初始化。

【需求】

头文件：hi_mapi_ao.h
库文件：libhi_mapi.so

【注意】无

【举例】无

【相关主题】 hi_mapi_ao_set_volume

9 hi_mapi_ao_set_mute

【描述】设置 AO 输出静音 / 取消静音状态。

【语法】

td_s32 hi_mapi_ao_set_mute(td_handle ao_hdl, td_bool enable);

【参数】

参数名称	输入/输出	类型	描述
`ao_hdl`	输入	`td_handle`	AO 设备句柄，取值范围：0～1。
`enable`	输入	`td_bool`	`TD_TRUE` 静音，`TD_FALSE` 取消静音。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_AO_EINVALIDHDL`	`ao_hdl` 超出范围。
`HI_MAPI_AO_ENOTINITED`	AO 子系统未预初始化。
`HI_MAPI_AO_ESTATEERR`	AO 设备未处于 `STARTED` 状态。

【需求】

头文件：hi_mapi_ao.h
库文件：libhi_mapi.so

【注意】

必须先启动 AO 设备后才能设置静音。

【举例】无

【相关主题】 hi_mapi_ao_start

10 hi_mapi_ao_send_frame

【描述】向指定 AO 通道发送一帧 PCM 音频数据。

【语法】

td_s32 hi_mapi_ao_send_frame(td_handle ao_hdl, td_handle ao_chn_hdl, const hi_mapi_audio_frame *audio_frame,
    td_u32 timeout);

【参数】

参数名称	输入/输出	类型	描述
`ao_hdl`	输入	`td_handle`	AO 设备句柄，取值范围：0～1。
`ao_chn_hdl`	输入	`td_handle`	AO 通道句柄，取值范围：0～1。
`audio_frame`	输入	`const hi_mapi_audio_frame *`	音频帧指针，不能为 `TD_NULL`。
`timeout`	输入	`td_u32`	发送超时时间（单位：ms）。`0` 表示非阻塞；`0xFFFFFFFF` 表示永久阻塞。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_AO_EINVALIDHDL`	`ao_hdl` 或 `ao_chn_hdl` 超出范围。
`HI_MAPI_AO_ENULLPTR`	`audio_frame` 为 `TD_NULL`。
`HI_MAPI_AO_ENOTINITED`	AO 子系统未预初始化。
`HI_MAPI_AO_ESTATEERR`	AO 设备或指定通道未处于 `STARTED` 状态。

【需求】

头文件：hi_mapi_ao.h
库文件：libhi_mapi.so

【注意】

必须在设备和通道都 start 之后才能发送。

【举例】无

【相关主题】 hi_mapi_ao_send_sys_frame、hi_mapi_ao_start

11 hi_mapi_ao_send_sys_frame

【描述】向指定 AO 设备的系统通道（OT_AO_SYS_CHN_ID）发送一帧 PCM 音频数据。系统通道用于播放系统提示音等优先级较高的音频。

【语法】

td_s32 hi_mapi_ao_send_sys_frame(td_handle ao_hdl, const hi_mapi_audio_frame *audio_frame, td_u32 timeout);

【参数】

参数名称	输入/输出	类型	描述
`ao_hdl`	输入	`td_handle`	AO 设备句柄，取值范围：0～1。
`audio_frame`	输入	`const hi_mapi_audio_frame *`	音频帧指针，不能为 `TD_NULL`。
`timeout`	输入	`td_u32`	发送超时时间（单位：ms），语义同 `hi_mapi_ao_send_frame`。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_AO_EINVALIDHDL`	`ao_hdl` 超出范围。
`HI_MAPI_AO_ENULLPTR`	`audio_frame` 为 `TD_NULL`。
`HI_MAPI_AO_ENOTINITED`	AO 子系统未预初始化。
`HI_MAPI_AO_ESTATEERR`	AO 设备未处于 `STARTED` 状态。

【需求】

头文件：hi_mapi_ao.h
库文件：libhi_mapi.so

【注意】

系统通道不需要用户调用 hi_mapi_ao_start 使能，只要设备启动即可。

【举例】无

【相关主题】 hi_mapi_ao_send_frame

12 hi_mapi_ao_get_default_attr

【描述】按采样率与声道模式返回推荐的默认 AO 属性，其余字段由库填充为常见默认值。

【语法】

td_s32 hi_mapi_ao_get_default_attr(hi_mapi_audio_sample_rate sample_rate,
                                  hi_mapi_audio_sound_mode sound_mode,
                                  hi_mapi_ao_attr *ao_attr);

【参数】

参数名称	输入/输出	类型	描述
`sample_rate`	输入	`hi_mapi_audio_sample_rate`	输出采样率（建议与 ADEC 输出一致）。
`sound_mode`	输入	`hi_mapi_audio_sound_mode`	声道模式（mono / stereo）。
`ao_attr`	输出	`hi_mapi_ao_attr *`	被填充后的默认属性，不能为 `TD_NULL`。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_AO_ENULLPTR`	`ao_attr` 为 `TD_NULL`。
`HI_MAPI_AO_EILLPARAM`	`sample_rate` 或 `sound_mode` 越界。

【需求】

头文件：hi_mapi_ao.h
库文件：libhi_mapi.so

【注意】

默认字段取值：bit_width = 16bit；track_mode = NORMAL；work_mode = I2S_MASTER；pt_num_per_frm = 1024；in_sample_rate = sample_rate；i2s_type = INNERCODEC。

【举例】无

【相关主题】 hi_mapi_ao_init

4 数据类型

1 hi_mapi_ao_attr

【说明】定义 AO 音频输出设备属性结构，包含采样率、位宽、声道、工作模式等配置。

【定义】

typedef struct {
    hi_mapi_audio_sample_rate sample_rate;
    hi_mapi_audio_bit_width bit_width;
    hi_mapi_audio_sound_mode sound_mode;
    hi_mapi_audio_track_mode track_mode;
    hi_mapi_aio_work_mode work_mode;
    td_u32 pt_num_per_frm;
    hi_mapi_audio_sample_rate in_sample_rate;
    hi_mapi_aio_i2s_type i2s_type;
} hi_mapi_ao_attr;

【成员】

成员名称	描述
`sample_rate`	音频输出采样率，单位 Hz，参见 `hi_mapi_audio_sample_rate`。应与 ADEC 输出采样率匹配。
`bit_width`	音频位宽，参见 `hi_mapi_audio_bit_width`。
`sound_mode`	声道模式（单声道 / 立体声），参见 `hi_mapi_audio_sound_mode`。
`track_mode`	声轨模式，参见 `hi_mapi_audio_track_mode`。
`work_mode`	音频工作模式（I2S 主/从、PCM 主/从），参见 `hi_mapi_aio_work_mode`。
`pt_num_per_frm`	每帧采样点数。取值范围 `[1, 2048]`（`HI_MAPI_AIO_MAX_POINT_PER_FRAME`）。
`in_sample_rate`	AO 输入重采样率，用于重采样器。参见 `hi_mapi_audio_sample_rate`。
`i2s_type`	I2S 接口类型，参见 `hi_mapi_aio_i2s_type`。

【注意事项】

CV610 平台 AO 最大通道数为 3（OT_AO_MAX_CHN_NUM = 3）。
可通过 hi_mapi_ao_get_default_attr 获取默认属性，仅需指定 sample_rate 与 sound_mode。

【相关数据类型及接口】 hi_mapi_ao_init、hi_mapi_ao_get_default_attr。

2 hi_mapi_ao_vqe_attr

【说明】定义 AO VQE（语音质量增强）属性结构，用于 hi_mapi_ao_enable_vqe 中指定 VQE 工作状态。

【定义】

typedef struct {
    hi_mapi_audio_work_state work_state;
} hi_mapi_ao_vqe_attr;

【成员】

成员名称	描述
`work_state`	VQE 工作状态，参见 `hi_mapi_audio_work_state`。可选值：`COMMON`（语音）/ `MUSIC`（音乐）/ `NOISY`（噪声）。

【注意事项】需固件开启 SUPPORT_TALKVQE 支持。

【相关数据类型及接口】 hi_mapi_audio_work_state；hi_mapi_ao_enable_vqe。

5 错误码

模块编号 mod=6，错误码基址 0xA3068000。

错误代码	宏定义	描述
`0xA3068001`	`HI_MAPI_AO_EINVALIDHDL`	句柄无效。
`0xA3068003`	`HI_MAPI_AO_EILLPARAM`（按命名推断）	参数非法。
`0xA3068006`	`HI_MAPI_AO_ENULLPTR`	空指针。
`0xA3068009`	`HI_MAPI_AO_ESTATEERR`	状态错误。
`0xA3068010`	`HI_MAPI_AO_ENOTINITED`	模块未初始化。