ACAP（音频采集）接口说明文档

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

---

1 概述

ACAP 模块负责管理片内 / 片外音频输入（AI）设备，完成音频采集、重采样、音量控制、静音、VQE（语音质量增强，如 AEC/ANR/AGC 等）以及帧获取等功能。HI3516CV610 平台上仅支持 1 路 AI 设备（acap_hdl = 0），单设备最多支持 4 个通道（acap_chn_hdl ∈ [0, 3]）。典型调用流程：hi_mapi_acap_init → hi_mapi_acap_start → hi_mapi_acap_get_frame / hi_mapi_acap_release_frame → hi_mapi_acap_stop → hi_mapi_acap_deinit。VQE 需在 start 之后调用 hi_mapi_acap_enable_vqe。

2 接口总览

编号	接口	功能概述
1	hi_mapi_acap_init	初始化指定 AI 设备，设置采样率、位宽、声轨模式、工作模式、每帧采样点数、混音器输入、重采样率、I2S 类型、输入拓扑等属性。
2	hi_mapi_acap_deinit	去初始化指定 AI 设备，释放重采样器及 HAL 资源。
3	hi_mapi_acap_start	启动指定 AI 设备上的指定通道。
4	hi_mapi_acap_stop	停止指定 AI 设备上的指定通道。
5	hi_mapi_acap_enable_vqe	为指定通道启用语音质量增强（VQE）。不同 vqe_type 对应不同的算法组合： - HI_MAPI_ACAP_VQE_TYPE_RECORD：录音模式（ANR + AGC），不需要 AO 参考。 - HI_MAPI_ACAP_VQE_TYPE_TALK：对讲模式（AEC + ANR + AGC），需要 AO 参考。 - HI_MAPI_ACAP_VQE_TYPE_TALKV2：双 MIC 对讲模式，需要 AO 参考。
6	hi_mapi_acap_disable_vqe	禁用指定通道上的 VQE，并恢复默认 AFE provider。
7	hi_mapi_acap_set_volume	设置 AI 设备采集音量（音频增益）。
8	hi_mapi_acap_get_volume	获取 AI 设备当前的采集音量（音频增益）。
9	hi_mapi_acap_mute	将指定 AI 设备静音。
10	hi_mapi_acap_unmute	解除指定 AI 设备的静音状态。
11	hi_mapi_acap_get_frame	从指定通道获取一帧音频数据。若启用了重采样，返回的帧为经过重采样后的数据。
12	hi_mapi_acap_release_frame	释放由 hi_mapi_acap_get_frame 获取的音频帧资源。
13	hi_mapi_acap_get_default_attr	按给定采样率与声道模式生成一组默认的 AI 设备属性，调用方可在此基础上修改需要覆盖的字段。
14	hi_mapi_acap_set_param	按命令设置 ACAP 扩展参数。_CONFIG 后缀的命令仅允许在 hi_mapi_acap_start 之前调用；在 STARTED 状态下调用会返回 HI_MAPI_ACAP_ESTATEERR。
15	hi_mapi_acap_get_param	按命令读取 ACAP 扩展参数的当前值。

3 API 参考

1 hi_mapi_acap_init

【描述】 初始化指定 AI 设备，设置采样率、位宽、声轨模式、工作模式、每帧采样点数、混音器输入、重采样率、I2S 类型、输入拓扑等属性。

【语法】

td_s32 hi_mapi_acap_init(td_handle acap_hdl, const hi_mapi_acap_attr *acap_attr);

【参数】

参数名称	输入/输出	类型	描述
acap_hdl	输入	td_handle	AI 设备句柄，HI3516CV610 仅支持 0。
acap_attr	输入	const hi_mapi_acap_attr *	AI 设备属性，不能为 NULL。

hi_mapi_acap_attr 成员：

成员名称	描述
sample_rate	采集采样率（Hz），取值见 hi_mapi_audio_sample_rate，如 8000、16000、48000 等。
bit_width	采样位宽，HI_MAPI_AUDIO_BIT_WIDTH_8 / _16 / _24。
sound_mode	声道模式，HI_MAPI_AUDIO_SOUND_MODE_MONO 或 _STEREO。
track_mode	声轨模式（normal / 双左 / 双右 / 交换 / 混音 / 静音等）。
work_mode	AIO 工作模式（I2S master / slave / PCM ...）。
pt_num_per_frm	每帧采样点数，范围 (0, 2048]。
mixer_mic_mode	混音器 MIC 输入模式。
resample_rate	重采样输出采样率；与 sample_rate 相等时不启用重采样。
i2s_type	I2S 类型（内 codec / 内 HDMI / 外部硬件）。
input_topology	可选的外部 ADC 通道拓扑，enable = TD_FALSE 时使用默认 2 通道内部 codec 拓扑。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_ACAP_EINVALIDHDL	acap_hdl 越界。
HI_MAPI_ACAP_ENULLPTR	acap_attr 为空指针。
HI_MAPI_ACAP_ENOINITED	MAPI 系统尚未初始化。
HI_MAPI_ACAP_EILLPARAM	input_topology 非法，或 sound_mode 不支持。

【需求】

• 头文件：hi_mapi_acap.h
• 库文件：libhi_mapi.so

【注意】

• 重复调用：若设备已经 started，直接返回成功；若处于 stopped 且属性未改变，也直接返回成功。
• 调用 hi_mapi_acap_get_default_attr 可快速获取一组缺省值，再覆盖需要修改的字段即可。
• input_topology.enable = TD_TRUE 时，mic_chn_hdl[] 必须互不相同、取值在 [0, chn_cnt)；reserved[4] 必须为 0。

【举例】 无

【相关主题】 hi_mapi_acap_deinit、hi_mapi_acap_get_default_attr

2 hi_mapi_acap_deinit

【描述】 去初始化指定 AI 设备，释放重采样器及 HAL 资源。

【语法】

td_s32 hi_mapi_acap_deinit(td_handle acap_hdl);

【参数】

参数名称	输入/输出	类型	描述
acap_hdl	输入	td_handle	AI 设备句柄，HI3516CV610 仅支持 0。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_ACAP_EINVALIDHDL	acap_hdl 越界。
HI_MAPI_ACAP_ENOINITED	MAPI 系统尚未初始化。

【需求】

• 头文件：hi_mapi_acap.h
• 库文件：libhi_mapi.so

【注意】

• 若设备仍处于 started 状态，本接口会先尝试停止所有通道再释放资源。
• 重复 deinit 一个未初始化的设备，直接返回成功。

【举例】 无

【相关主题】 hi_mapi_acap_init

3 hi_mapi_acap_start

【描述】 启动指定 AI 设备上的指定通道。

【语法】

td_s32 hi_mapi_acap_start(td_handle acap_hdl, td_handle acap_chn_hdl);

【参数】

参数名称	输入/输出	类型	描述
acap_hdl	输入	td_handle	AI 设备句柄，HI3516CV610 仅支持 0。
acap_chn_hdl	输入	td_handle	通道句柄，范围 [0, 3]。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_ACAP_EINVALIDHDL	acap_hdl 或 acap_chn_hdl 越界。
HI_MAPI_ACAP_ENOINITED	MAPI 系统尚未初始化。
HI_MAPI_ACAP_ESTATEERR	设备尚未 init。

【需求】

• 头文件：hi_mapi_acap.h
• 库文件：libhi_mapi.so

【注意】

• 同一设备的不同通道可以分别 start / stop。
• 重复启动已启动的通道，直接返回成功。

【举例】 无

【相关主题】 hi_mapi_acap_stop、hi_mapi_acap_init

4 hi_mapi_acap_stop

【描述】 停止指定 AI 设备上的指定通道。

【语法】

td_s32 hi_mapi_acap_stop(td_handle acap_hdl, td_handle acap_chn_hdl);

【参数】

参数名称	输入/输出	类型	描述
acap_hdl	输入	td_handle	AI 设备句柄，HI3516CV610 仅支持 0。
acap_chn_hdl	输入	td_handle	通道句柄，范围 [0, 3]。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_ACAP_EINVALIDHDL	acap_hdl 或 acap_chn_hdl 越界。
HI_MAPI_ACAP_ENOINITED	MAPI 系统尚未初始化。
HI_MAPI_ACAP_ESTATEERR	设备尚未 init。

【需求】

• 头文件：hi_mapi_acap.h
• 库文件：libhi_mapi.so

【注意】

• 仅当设备上所有通道都已 stop 时，才会真正关闭 AI 设备；否则只关闭指定通道。

【举例】 无

【相关主题】 hi_mapi_acap_start

5 hi_mapi_acap_enable_vqe

【描述】 为指定通道启用语音质量增强（VQE）。不同 vqe_type 对应不同的算法组合：

• HI_MAPI_ACAP_VQE_TYPE_RECORD：录音模式（ANR + AGC），不需要 AO 参考。
• HI_MAPI_ACAP_VQE_TYPE_TALK：对讲模式（AEC + ANR + AGC），需要 AO 参考。
• HI_MAPI_ACAP_VQE_TYPE_TALKV2：双 MIC 对讲模式，需要 AO 参考。

【语法】

td_s32 hi_mapi_acap_enable_vqe(td_handle acap_hdl, td_handle acap_chn_hdl,
                               hi_mapi_acap_vqe_type vqe_type, td_handle ref_ao_hdl);

【参数】

参数名称	输入/输出	类型	描述
acap_hdl	输入	td_handle	AI 设备句柄，HI3516CV610 仅支持 0。
acap_chn_hdl	输入	td_handle	通道句柄，范围 [0, 3]。
vqe_type	输入	hi_mapi_acap_vqe_type	VQE 类型（RECORD / TALK / TALKV2）。
ref_ao_hdl	输入	td_handle	AEC 参考 AO 设备句柄。RECORD 类型应传 OT_INVALID_HANDLE（即 -1）；TALK / TALKV2 必须传一个有效 AO 设备句柄，HI3516CV610 取值范围 [0, 1]。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_ACAP_EINVALIDHDL	acap_hdl / acap_chn_hdl / ref_ao_hdl 越界。
HI_MAPI_ACAP_ENOINITED	MAPI 系统尚未初始化。
HI_MAPI_ACAP_ESTATEERR	设备或通道尚未 start。
HI_MAPI_ACAP_EILLPARAM	vqe_type 非法，或 AFE provider 不可用。

【需求】

• 头文件：hi_mapi_acap.h
• 库文件：libhi_mapi.so

【注意】

• 必须在 hi_mapi_acap_start 之后调用。
• 所选 AFE provider（默认 "hisi"）可通过 hi_mapi_acap_set_param 的 HI_MAPI_ACAP_CMD_AFE_PROVIDER_CONFIG 修改。

【举例】 无

【相关主题】 hi_mapi_acap_disable_vqe、hi_mapi_acap_set_param

6 hi_mapi_acap_disable_vqe

【描述】 禁用指定通道上的 VQE，并恢复默认 AFE provider。

【语法】

td_s32 hi_mapi_acap_disable_vqe(td_handle acap_hdl, td_handle acap_chn_hdl);

【参数】

参数名称	输入/输出	类型	描述
acap_hdl	输入	td_handle	AI 设备句柄，HI3516CV610 仅支持 0。
acap_chn_hdl	输入	td_handle	通道句柄，范围 [0, 3]。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_ACAP_EINVALIDHDL	acap_hdl 或 acap_chn_hdl 越界。
HI_MAPI_ACAP_ENOINITED	MAPI 系统尚未初始化。
HI_MAPI_ACAP_ESTATEERR	设备尚未 init。

【需求】

• 头文件：hi_mapi_acap.h
• 库文件：libhi_mapi.so

【注意】

• 若通道已经处于 stopped 状态，直接返回成功。

【举例】 无

【相关主题】 hi_mapi_acap_enable_vqe

7 hi_mapi_acap_set_volume

【描述】 设置 AI 设备采集音量（音频增益）。

【语法】

td_s32 hi_mapi_acap_set_volume(td_handle acap_hdl, td_s32 audio_gain);

【参数】

参数名称	输入/输出	类型	描述
acap_hdl	输入	td_handle	AI 设备句柄，HI3516CV610 仅支持 0。
audio_gain	输入	td_s32	音频增益，单位 dB。HI3516CV610 取值范围 [-78, 80]。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_ACAP_EINVALIDHDL	acap_hdl 越界。
HI_MAPI_ACAP_ENOINITED	MAPI 系统尚未初始化。
HI_MAPI_ACAP_EILLPARAM	audio_gain 超出范围 [-78, 80]。

【需求】

• 头文件：hi_mapi_acap.h
• 库文件：libhi_mapi.so

【注意】 无

【举例】 无

【相关主题】 hi_mapi_acap_get_volume

8 hi_mapi_acap_get_volume

【描述】 获取 AI 设备当前的采集音量（音频增益）。

【语法】

td_s32 hi_mapi_acap_get_volume(td_handle acap_hdl, td_s32 *audio_gain);

【参数】

参数名称	输入/输出	类型	描述
acap_hdl	输入	td_handle	AI 设备句柄，HI3516CV610 仅支持 0。
audio_gain	输出	td_s32 *	接收当前音频增益（dB），不能为 NULL。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_ACAP_EINVALIDHDL	acap_hdl 越界。
HI_MAPI_ACAP_ENULLPTR	audio_gain 为空指针。
HI_MAPI_ACAP_ENOINITED	MAPI 系统尚未初始化。

【需求】

• 头文件：hi_mapi_acap.h
• 库文件：libhi_mapi.so

【注意】 无

【举例】 无

【相关主题】 hi_mapi_acap_set_volume

9 hi_mapi_acap_mute

【描述】 将指定 AI 设备静音。

【语法】

td_s32 hi_mapi_acap_mute(td_handle acap_hdl);

【参数】

参数名称	输入/输出	类型	描述
acap_hdl	输入	td_handle	AI 设备句柄，HI3516CV610 仅支持 0。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_ACAP_EINVALIDHDL	acap_hdl 越界。
HI_MAPI_ACAP_ENOINITED	MAPI 系统尚未初始化。

【需求】

• 头文件：hi_mapi_acap.h
• 库文件：libhi_mapi.so

【注意】 无

【举例】 无

【相关主题】 hi_mapi_acap_unmute

10 hi_mapi_acap_unmute

【描述】 解除指定 AI 设备的静音状态。

【语法】

td_s32 hi_mapi_acap_unmute(td_handle acap_hdl);

【参数】

参数名称	输入/输出	类型	描述
acap_hdl	输入	td_handle	AI 设备句柄，HI3516CV610 仅支持 0。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_ACAP_EINVALIDHDL	acap_hdl 越界。
HI_MAPI_ACAP_ENOINITED	MAPI 系统尚未初始化。

【需求】

• 头文件：hi_mapi_acap.h
• 库文件：libhi_mapi.so

【注意】 无

【举例】 无

【相关主题】 hi_mapi_acap_mute

11 hi_mapi_acap_get_frame

【描述】 从指定通道获取一帧音频数据。若启用了重采样，返回的帧为经过重采样后的数据。

【语法】

td_s32 hi_mapi_acap_get_frame(td_handle acap_hdl, td_handle acap_chn_hdl, hi_mapi_audio_frame *audio_frm,
                             hi_mapi_aec_frame *aec_frm);

【参数】

参数名称	输入/输出	类型	描述
acap_hdl	输入	td_handle	AI 设备句柄，HI3516CV610 仅支持 0。
acap_chn_hdl	输入	td_handle	通道句柄，范围 [0, 3]。
audio_frm	输出	hi_mapi_audio_frame *	接收音频帧，不能为 NULL。
aec_frm	输出	hi_mapi_aec_frame *	接收 AEC 参考帧，不能为 NULL。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_ACAP_EINVALIDHDL	acap_hdl 或 acap_chn_hdl 越界。
HI_MAPI_ACAP_ENULLPTR	audio_frm 或 aec_frm 为空指针。
HI_MAPI_ACAP_ENOINITED	MAPI 系统尚未初始化。
HI_MAPI_ACAP_ESTATEERR	设备或通道尚未 start。

【需求】

• 头文件：hi_mapi_acap.h
• 库文件：libhi_mapi.so

【注意】

• 获取的帧必须通过 hi_mapi_acap_release_frame 释放，不能直接复用。

【举例】 无

【相关主题】 hi_mapi_acap_release_frame

12 hi_mapi_acap_release_frame

【描述】 释放由 hi_mapi_acap_get_frame 获取的音频帧资源。

【语法】

td_s32 hi_mapi_acap_release_frame(td_handle acap_hdl, td_handle acap_chn_hdl, const hi_mapi_audio_frame *audio_frm,
                                 const hi_mapi_aec_frame *aec_frm);

【参数】

参数名称	输入/输出	类型	描述
acap_hdl	输入	td_handle	AI 设备句柄，HI3516CV610 仅支持 0。
acap_chn_hdl	输入	td_handle	通道句柄，范围 [0, 3]。
audio_frm	输入	const hi_mapi_audio_frame *	待释放的音频帧，不能为 NULL。
aec_frm	输入	const hi_mapi_aec_frame *	待释放的 AEC 参考帧，不能为 NULL。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_ACAP_EINVALIDHDL	acap_hdl 或 acap_chn_hdl 越界。
HI_MAPI_ACAP_ENULLPTR	audio_frm 或 aec_frm 为空指针。
HI_MAPI_ACAP_ENOINITED	MAPI 系统尚未初始化。
HI_MAPI_ACAP_ESTATEERR	设备或通道尚未 start。

【需求】

• 头文件：hi_mapi_acap.h
• 库文件：libhi_mapi.so

【注意】

• 必须与 hi_mapi_acap_get_frame 成对使用。

【举例】 无

【相关主题】 hi_mapi_acap_get_frame

13 hi_mapi_acap_get_default_attr

【描述】 按给定采样率与声道模式生成一组默认的 AI 设备属性，调用方可在此基础上修改需要覆盖的字段。

【语法】

td_s32 hi_mapi_acap_get_default_attr(hi_mapi_audio_sample_rate sample_rate,
                                    hi_mapi_audio_sound_mode sound_mode,
                                    hi_mapi_acap_attr *acap_attr);

【参数】

参数名称	输入/输出	类型	描述
sample_rate	输入	hi_mapi_audio_sample_rate	采样率（Hz），必须小于 HI_MAPI_AUDIO_SAMPLE_RATE_BUTT。
sound_mode	输入	hi_mapi_audio_sound_mode	声道模式，MONO 或 STEREO。
acap_attr	输出	hi_mapi_acap_attr *	接收默认属性，不能为 NULL。

默认值：

字段	默认值
bit_width	HI_MAPI_AUDIO_BIT_WIDTH_16
track_mode	HI_MAPI_AUDIO_TRACK_NORMAL
work_mode	HI_MAPI_AIO_MODE_I2S_MASTER
pt_num_per_frm	1024
mixer_mic_mode	HI_MAPI_ACODEC_MIXER_IN0
resample_rate	与 sample_rate 相同
i2s_type	HI_MAPI_AIO_I2STYPE_INNERCODEC
input_topology.ref_chn_hdl	OT_INVALID_HANDLE
input_topology.out_chn_hdl	OT_INVALID_HANDLE

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_ACAP_ENULLPTR	acap_attr 为空指针。
HI_MAPI_ACAP_EILLPARAM	sample_rate 或 sound_mode 非法。

【需求】

• 头文件：hi_mapi_acap.h
• 库文件：libhi_mapi.so

【注意】 无

【举例】 无

【相关主题】 hi_mapi_acap_init

14 hi_mapi_acap_set_param

【描述】 按命令设置 ACAP 扩展参数。_CONFIG 后缀的命令仅允许在 hi_mapi_acap_start 之前调用；在 STARTED 状态下调用会返回 HI_MAPI_ACAP_ESTATEERR。

【语法】

td_s32 hi_mapi_acap_set_param(td_handle acap_hdl, hi_mapi_acap_cmd cmd,
                              const td_void *attr, td_u32 attr_len);

【参数】

参数名称	输入/输出	类型	描述
acap_hdl	输入	td_handle	AI 设备句柄，HI3516CV610 仅支持 0。
cmd	输入	hi_mapi_acap_cmd	扩展命令。HI_MAPI_ACAP_CMD_AFE_PROVIDER_CONFIG：设置 AFE provider 名称；HI_MAPI_ACAP_CMD_AFE_ATTR_CONFIG：设置 AFE provider 属性。
attr	输入	const td_void *	命令对应的参数指针。AFE_PROVIDER_CONFIG 对应以 \0 结尾的字符串（如 "hisi"），长度范围 (0, 16)；AFE_ATTR_CONFIG 对应 hi_mapi_acap_afe_attr_t *。
attr_len	输入	td_u32	attr 字节长度。AFE_PROVIDER_CONFIG 为字符串长度（包含 \0）；AFE_ATTR_CONFIG 必须 ≥ sizeof(hi_mapi_acap_afe_attr_t)。

hi_mapi_acap_afe_attr_t 成员：

成员名称	描述
model_path	可选的软件 AFE 模型路径；SDK 内置 provider 会忽略此字段。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_ACAP_EINVALIDHDL	acap_hdl 越界。
HI_MAPI_ACAP_ENULLPTR	attr 为空指针。
HI_MAPI_ACAP_ENOINITED	MAPI 系统尚未初始化。
HI_MAPI_ACAP_ESTATEERR	设备尚未 init，或处于 STARTED 状态。
HI_MAPI_ACAP_EILLPARAM	cmd 未知，或 attr_len 错误，或 AFE provider 名称未注册 / 被占用。

【需求】

• 头文件：hi_mapi_acap.h
• 库文件：libhi_mapi.so

【注意】

• AFE_PROVIDER_CONFIG 必须在 init 之后、start 之前调用，用于选择后续 hi_mapi_acap_enable_vqe 使用的 AFE provider。
• 当前可用 provider："hisi"（SDK 内置），若编译时启用了外部 provider 还可能包含 "external"。

【举例】 无

【相关主题】 hi_mapi_acap_get_param、hi_mapi_acap_enable_vqe

15 hi_mapi_acap_get_param

【描述】 按命令读取 ACAP 扩展参数的当前值。

【语法】

td_s32 hi_mapi_acap_get_param(td_handle acap_hdl, hi_mapi_acap_cmd cmd,
                              td_void *attr, td_u32 attr_len);

【参数】

参数名称	输入/输出	类型	描述
acap_hdl	输入	td_handle	AI 设备句柄，HI3516CV610 仅支持 0。
cmd	输入	hi_mapi_acap_cmd	扩展命令，取值同 hi_mapi_acap_set_param。
attr	输出	td_void *	接收参数值。AFE_PROVIDER_CONFIG 对应字符串缓冲区；AFE_ATTR_CONFIG 对应 hi_mapi_acap_afe_attr_t *。
attr_len	输入	td_u32	attr 缓冲区字节长度。AFE_PROVIDER_CONFIG 必须大于当前 provider 名称长度；AFE_ATTR_CONFIG 必须 ≥ sizeof(hi_mapi_acap_afe_attr_t)。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_ACAP_EINVALIDHDL	acap_hdl 越界。
HI_MAPI_ACAP_ENULLPTR	attr 为空指针。
HI_MAPI_ACAP_ENOINITED	MAPI 系统尚未初始化。
HI_MAPI_ACAP_ESTATEERR	设备尚未 init。
HI_MAPI_ACAP_EILLPARAM	cmd 未知，或 attr_len 不足。

【需求】

• 头文件：hi_mapi_acap.h
• 库文件：libhi_mapi.so

【注意】 无

【举例】 无

【相关主题】 hi_mapi_acap_set_param

4 数据类型

1 hi_mapi_audio_sample_rate

【说明】 定义音频采样率枚举，单位 Hz，用于 ACAP / AENC / ADEC / AO 属性中。

【定义】

typedef enum {
    HI_MAPI_AUDIO_SAMPLE_RATE_8000  = 8000,
    HI_MAPI_AUDIO_SAMPLE_RATE_12000 = 12000,
    HI_MAPI_AUDIO_SAMPLE_RATE_11025 = 11025,
    HI_MAPI_AUDIO_SAMPLE_RATE_16000 = 16000,
    HI_MAPI_AUDIO_SAMPLE_RATE_22050 = 22050,
    HI_MAPI_AUDIO_SAMPLE_RATE_24000 = 24000,
    HI_MAPI_AUDIO_SAMPLE_RATE_32000 = 32000,
    HI_MAPI_AUDIO_SAMPLE_RATE_44100 = 44100,
    HI_MAPI_AUDIO_SAMPLE_RATE_48000 = 48000,
    HI_MAPI_AUDIO_SAMPLE_RATE_64000 = 64000,
    HI_MAPI_AUDIO_SAMPLE_RATE_96000 = 96000,
    HI_MAPI_AUDIO_SAMPLE_RATE_BUTT
} hi_mapi_audio_sample_rate;

【成员】

成员名称	描述
HI_MAPI_AUDIO_SAMPLE_RATE_8000	8000 Hz。
HI_MAPI_AUDIO_SAMPLE_RATE_12000	12000 Hz。
HI_MAPI_AUDIO_SAMPLE_RATE_11025	11025 Hz。
HI_MAPI_AUDIO_SAMPLE_RATE_16000	16000 Hz。
HI_MAPI_AUDIO_SAMPLE_RATE_22050	22050 Hz。
HI_MAPI_AUDIO_SAMPLE_RATE_24000	24000 Hz。
HI_MAPI_AUDIO_SAMPLE_RATE_32000	32000 Hz。
HI_MAPI_AUDIO_SAMPLE_RATE_44100	44100 Hz。
HI_MAPI_AUDIO_SAMPLE_RATE_48000	48000 Hz。
HI_MAPI_AUDIO_SAMPLE_RATE_64000	64000 Hz。
HI_MAPI_AUDIO_SAMPLE_RATE_96000	96000 Hz。
HI_MAPI_AUDIO_SAMPLE_RATE_BUTT	哨兵值。

【注意事项】 ACAP / AO 实际支持的采样率取决于 Audio Codec 硬件能力。

【相关数据类型及接口】 hi_mapi_acap_attr、hi_mapi_ao_attr；hi_mapi_acap_init、hi_mapi_ao_init。

2 hi_mapi_audio_bit_width

【说明】 定义音频采样位宽枚举。

【定义】

typedef enum {
    HI_MAPI_AUDIO_BIT_WIDTH_8  = 0,
    HI_MAPI_AUDIO_BIT_WIDTH_16 = 1,
    HI_MAPI_AUDIO_BIT_WIDTH_24 = 2,
    HI_MAPI_AUDIO_BIT_WIDTH_BUTT
} hi_mapi_audio_bit_width;

【成员】

成员名称	描述
HI_MAPI_AUDIO_BIT_WIDTH_8	8 bit 位宽。
HI_MAPI_AUDIO_BIT_WIDTH_16	16 bit 位宽。
HI_MAPI_AUDIO_BIT_WIDTH_24	24 bit 位宽。
HI_MAPI_AUDIO_BIT_WIDTH_BUTT	哨兵值。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_acap_attr、hi_mapi_ao_attr。

3 hi_mapi_aio_work_mode

【说明】 定义音频 AIO（ACAP / AO）工作模式枚举，包括 I2S 主/从模式与 PCM 主/从模式。

【定义】

typedef enum {
    HI_MAPI_AIO_MODE_I2S_MASTER = 0,
    HI_MAPI_AIO_MODE_I2S_SLAVE,
    HI_MAPI_AIO_MODE_PCM_SLAVE_STD,
    HI_MAPI_AIO_MODE_PCM_SLAVE_NSTD,
    HI_MAPI_AIO_MODE_PCM_MASTER_STD,
    HI_MAPI_AIO_MODE_PCM_MASTER_NSTD,
    HI_MAPI_AIO_MODE_BUTT
} hi_mapi_aio_work_mode;

【成员】

成员名称	描述
HI_MAPI_AIO_MODE_I2S_MASTER	I2S 主模式。
HI_MAPI_AIO_MODE_I2S_SLAVE	I2S 从模式。
HI_MAPI_AIO_MODE_PCM_SLAVE_STD	PCM 从模式，标准时序。
HI_MAPI_AIO_MODE_PCM_SLAVE_NSTD	PCM 从模式，非标准时序。
HI_MAPI_AIO_MODE_PCM_MASTER_STD	PCM 主模式，标准时序。
HI_MAPI_AIO_MODE_PCM_MASTER_NSTD	PCM 主模式，非标准时序。
HI_MAPI_AIO_MODE_BUTT	哨兵值。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_acap_attr、hi_mapi_ao_attr。

4 hi_mapi_audio_sound_mode

【说明】 定义音频声道模式枚举（单声道 / 立体声）。

【定义】

typedef enum {
    HI_MAPI_AUDIO_SOUND_MODE_MONO   = 0,
    HI_MAPI_AUDIO_SOUND_MODE_STEREO = 1,
    HI_MAPI_AUDIO_SOUND_MODE_BUTT
} hi_mapi_audio_sound_mode;

【成员】

成员名称	描述
HI_MAPI_AUDIO_SOUND_MODE_MONO	单声道。
HI_MAPI_AUDIO_SOUND_MODE_STEREO	立体声。
HI_MAPI_AUDIO_SOUND_MODE_BUTT	哨兵值。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_acap_attr、hi_mapi_ao_attr。

5 hi_mapi_audio_track_mode

【说明】 定义音频声轨模式枚举，控制左右声道的处理方式。

【定义】

typedef enum {
    HI_MAPI_AUDIO_TRACK_NORMAL      = 0,
    HI_MAPI_AUDIO_TRACK_BOTH_LEFT   = 1,
    HI_MAPI_AUDIO_TRACK_BOTH_RIGHT  = 2,
    HI_MAPI_AUDIO_TRACK_EXCHANGE    = 3,
    HI_MAPI_AUDIO_TRACK_MIX         = 4,
    HI_MAPI_AUDIO_TRACK_LEFT_MUTE   = 5,
    HI_MAPI_AUDIO_TRACK_RIGHT_MUTE  = 6,
    HI_MAPI_AUDIO_TRACK_BOTH_MUTE   = 7,
    HI_MAPI_AUDIO_TRACK_BUTT
} hi_mapi_audio_track_mode;

【成员】

成员名称	描述
HI_MAPI_AUDIO_TRACK_NORMAL	正常模式，左右声道独立。
HI_MAPI_AUDIO_TRACK_BOTH_LEFT	左右声道均输出左声道数据。
HI_MAPI_AUDIO_TRACK_BOTH_RIGHT	左右声道均输出右声道数据。
HI_MAPI_AUDIO_TRACK_EXCHANGE	左右声道交换。
HI_MAPI_AUDIO_TRACK_MIX	左右声道混合。
HI_MAPI_AUDIO_TRACK_LEFT_MUTE	左声道静音。
HI_MAPI_AUDIO_TRACK_RIGHT_MUTE	右声道静音。
HI_MAPI_AUDIO_TRACK_BOTH_MUTE	双声道静音。
HI_MAPI_AUDIO_TRACK_BUTT	哨兵值。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_acap_attr、hi_mapi_ao_attr。

6 hi_mapi_aio_acodec_mixer

【说明】 定义 Audio Codec 混音器麦克风输入模式枚举。

【定义】

typedef enum {
    HI_MAPI_ACODEC_MIXER_IN0   = 0x0,
    HI_MAPI_ACODEC_MIXER_IN1   = 0x1,
    HI_MAPI_ACODEC_MIXER_IN_D  = 0x2,
    HI_MAPI_ACODEC_MIXER_BUTT
} hi_mapi_aio_acodec_mixer;

【成员】

成员名称	描述
HI_MAPI_ACODEC_MIXER_IN0	混音器输入 0。
HI_MAPI_ACODEC_MIXER_IN1	混音器输入 1。
HI_MAPI_ACODEC_MIXER_IN_D	混音器默认输入。
HI_MAPI_ACODEC_MIXER_BUTT	哨兵值。

【注意事项】 仅在使用内部 Audio Codec 时有效。

【相关数据类型及接口】 hi_mapi_acap_attr。

7 hi_mapi_aio_i2s_type

【说明】 定义 AIO I2S 接口类型枚举，表示 I2S 总线连接的对端设备。

【定义】

typedef enum {
    HI_MAPI_AIO_I2STYPE_INNERCODEC = 0,
    HI_MAPI_AIO_I2STYPE_INNERHDMI,
    HI_MAPI_AIO_I2STYPE_EXTERN,
} hi_mapi_aio_i2s_type;

【成员】

成员名称	描述
HI_MAPI_AIO_I2STYPE_INNERCODEC	I2S 连接内部 Audio Codec。
HI_MAPI_AIO_I2STYPE_INNERHDMI	I2S 连接内部 HDMI。
HI_MAPI_AIO_I2STYPE_EXTERN	I2S 连接外部硬件。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_acap_attr、hi_mapi_ao_attr。

8 hi_mapi_audio_frame

【说明】 定义音频 PCM 帧结构，由 OT 层 ot_audio_frame 直接别名而来，承载一帧音频采样数据。

【定义】

typedef ot_audio_frame hi_mapi_audio_frame;

【成员】

成员名称	描述
（成员由 ot_audio_frame 定义）	包含虚拟地址、物理地址、采样点数、时间戳、序号等，详见 ot_common_aio.h。

【注意事项】 该类型为 ot_audio_frame 的 typedef 别名，具体成员请参考 OT 层头文件。

【相关数据类型及接口】 hi_mapi_audio_stream、hi_mapi_audio_frame_info；hi_mapi_acap_get_frame、hi_mapi_aenc_send_frame、hi_mapi_ao_send_frame。

9 hi_mapi_audio_stream

【说明】 定义音频码流结构，用于 ADEC 送流场景，承载一帧压缩音频码流。

【定义】

typedef struct {
    td_u8 MAPI_ALIGN_ATTRIBUTE *stream;
    td_u64 MAPI_ALIGN_ATTRIBUTE phy_addr;
    td_u32 len;
    td_u64 time_stamp;
    td_u32 seq;
} hi_mapi_audio_stream;

【成员】

成员名称	描述
stream	码流虚拟地址。
phy_addr	码流物理地址。
len	码流长度，单位字节。
time_stamp	帧时间戳。
seq	帧序号；若码流无效，则 seq 为 0。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_adec_send_stream。

10 hi_mapi_audio_work_state

【说明】 定义 VQE 工作状态枚举，用于 ACAP / AO VQE 属性中。

【定义】

typedef enum {
    HI_MAPI_VQE_WORKSTATE_COMMON  = 0,
    HI_MAPI_VQE_WORKSTATE_MUSIC   = 1,
    HI_MAPI_VQE_WORKSTATE_NOISY   = 2
} hi_mapi_audio_work_state;

【成员】

成员名称	描述
HI_MAPI_VQE_WORKSTATE_COMMON	普通场景（语音）。
HI_MAPI_VQE_WORKSTATE_MUSIC	音乐场景。
HI_MAPI_VQE_WORKSTATE_NOISY	噪声场景。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_ao_vqe_attr。

11 hi_mapi_aec_frame

【说明】 定义 AEC（回声抵消）参考帧结构，用于 ACAP 获取音频帧时携带 AEC 参考信息。

【定义】

typedef struct {
    hi_mapi_audio_frame ref_frame;
    td_bool             valid;
    td_bool             sys_bind;
} hi_mapi_aec_frame;

【成员】

成员名称	描述
ref_frame	AEC 参考音频帧。
valid	参考帧是否有效。
sys_bind	是否为系统绑定模式。

【注意事项】 仅在 TALK / TALKV2 VQE 模式下使用，需要配合 AO 参考通道。

【相关数据类型及接口】 hi_mapi_audio_frame；hi_mapi_acap_get_frame、hi_mapi_acap_release_frame。

12 hi_mapi_acap_input_topology

【说明】 定义 ACAP 可选的外部硬件输入拓扑结构，用于描述外部 ADC 通道布局。禁用时保留传统的内部 Codec 默认配置。

【定义】

typedef struct {
    td_bool enable;
    td_u32 chn_cnt;
    td_bool clk_share;
    td_u32 mic_chn_cnt;
    td_handle mic_chn_hdl[HI_MAPI_ACAP_MIC_CHN_MAX_NUM];
    td_handle ref_chn_hdl;
    td_handle out_chn_hdl;
    td_u32 reserved[4];
} hi_mapi_acap_input_topology;

【成员】

成员名称	描述
enable	是否启用外部输入拓扑。TD_TRUE 启用，TD_FALSE 禁用（使用内部 Codec 默认）。
chn_cnt	总通道数。
clk_share	是否共享时钟。
mic_chn_cnt	麦克风通道数，取值范围 [0, HI_MAPI_ACAP_MIC_CHN_MAX_NUM]，CV610 上 HI_MAPI_ACAP_MIC_CHN_MAX_NUM = 2。
mic_chn_hdl[mic_chn_cnt]	麦克风通道句柄数组，最大长度 HI_MAPI_ACAP_MIC_CHN_MAX_NUM（= 2）。
ref_chn_hdl	参考通道句柄（用于 AEC）。
out_chn_hdl	输出通道句柄。
reserved[4]	保留字段，必须为 0。

【注意事项】 mic_chn_cnt 不能超过 HI_MAPI_ACAP_MIC_CHN_MAX_NUM（= 2）。

【相关数据类型及接口】 hi_mapi_acap_attr。

13 hi_mapi_acap_attr

【说明】 定义 ACAP 设备初始化属性结构，包含采样率、位宽、声道、工作模式等配置。

【定义】

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_aio_acodec_mixer  mixer_mic_mode;
    hi_mapi_audio_sample_rate resample_rate;
    hi_mapi_aio_i2s_type      i2s_type;
    hi_mapi_acap_input_topology input_topology;
} hi_mapi_acap_attr;

【成员】

成员名称	描述
sample_rate	音频采样率，单位 Hz，参见 hi_mapi_audio_sample_rate。
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）。
mixer_mic_mode	混音器麦克风输入模式，参见 hi_mapi_aio_acodec_mixer。仅内部 Codec 有效。
resample_rate	重采样率，用于重采样器输出帧。参见 hi_mapi_audio_sample_rate。
i2s_type	I2S 接口类型，参见 hi_mapi_aio_i2s_type。
input_topology	可选的外部 ADC 通道拓扑，参见 hi_mapi_acap_input_topology。

【注意事项】

• CV610 平台 ACAP 最大通道数为 4（OT_AI_MAX_CHN_NUM = 4）。
• 可通过 hi_mapi_acap_get_default_attr 获取默认属性，仅需指定 sample_rate 与 sound_mode。

【相关数据类型及接口】 hi_mapi_acap_init、hi_mapi_acap_get_default_attr、hi_mapi_acap_input_topology。

14 hi_mapi_acap_vqe_type

【说明】 定义 ACAP VQE（语音质量增强）类型枚举，用于 hi_mapi_acap_enable_vqe 中指定 VQE 算法组合。

【定义】

typedef enum {
    HI_MAPI_ACAP_VQE_TYPE_RECORD = 0,
    HI_MAPI_ACAP_VQE_TYPE_TALK,
    HI_MAPI_ACAP_VQE_TYPE_TALKV2,
    HI_MAPI_ACAP_VQE_TYPE_BUTT
} hi_mapi_acap_vqe_type;

【成员】

成员名称	描述
HI_MAPI_ACAP_VQE_TYPE_RECORD	录音 VQE：ANR + AGC，无需 AO 参考。
HI_MAPI_ACAP_VQE_TYPE_TALK	通话 VQE：AEC + ANR + AGC，需要 AO 参考。
HI_MAPI_ACAP_VQE_TYPE_TALKV2	通话 VQE V2：双麦克风，需要 AO 参考。
HI_MAPI_ACAP_VQE_TYPE_BUTT	哨兵值。

【注意事项】

• RECORD 模式无需传入 ref_ao_hdl（传 OT_INVALID_HANDLE）。
• TALK / TALKV2 模式必须传入有效的 AO 参考句柄。
• 需固件开启 SUPPORT_TALKVQE 支持。

【相关数据类型及接口】 hi_mapi_acap_enable_vqe。

15 hi_mapi_acap_cmd

【说明】 定义 ACAP 扩展命令枚举，用于 hi_mapi_acap_set_param / hi_mapi_acap_get_param 中分派命令。

【定义】

typedef enum {
    HI_MAPI_ACAP_CMD_AFE_PROVIDER_CONFIG = 0,
    HI_MAPI_ACAP_CMD_AFE_ATTR_CONFIG,
    HI_MAPI_ACAP_CMD_BUTT
} hi_mapi_acap_cmd;

【成员】

成员名称	描述
HI_MAPI_ACAP_CMD_AFE_PROVIDER_CONFIG	AFE Provider 配置，参数为 const char[]，如 "hisi" / "unisound"。必须在 hi_mapi_acap_start 前设置。
HI_MAPI_ACAP_CMD_AFE_ATTR_CONFIG	AFE 扩展属性，参数为 hi_mapi_acap_afe_attr_t。必须在 hi_mapi_acap_start 前设置。
HI_MAPI_ACAP_CMD_BUTT	哨兵值。

【注意事项】 _CONFIG 后缀的命令必须在 hi_mapi_acap_start 之前调用；若通道已启动，调用会返回 HI_MAPI_ACAP_ESTATEERR。

【相关数据类型及接口】 hi_mapi_acap_set_param、hi_mapi_acap_get_param、hi_mapi_acap_afe_attr_t。

16 hi_mapi_acap_afe_attr_t

【说明】 定义 ACAP AFE Provider 扩展属性结构，用于配置可选的软件 AFE 模型路径。

【定义】

typedef struct {
    const td_char *model_path;
} hi_mapi_acap_afe_attr_t;

【成员】

成员名称	描述
model_path	可选的软件 AFE 模型路径。SDK 内置 Provider 忽略该字段。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_acap_cmd、hi_mapi_acap_set_param、hi_mapi_acap_get_param。

5 错误码

模块编号 mod=4，错误码基址 0xA3048000。

错误代码	宏定义	描述
0xA3048001	HI_MAPI_ACAP_EINVALIDHDL	句柄无效。
0xA3048003	HI_MAPI_ACAP_EILLPARAM	参数非法。
0xA3048006	HI_MAPI_ACAP_ENULLPTR	空指针。
0xA3048009	HI_MAPI_ACAP_ESTATEERR	状态错误（操作未授权）。
0xA3048010	HI_MAPI_ACAP_ENOINITED	模块未初始化。