版本：2.9.0

音频编解码 (ACODEC)

概述

目前支持的编解码类型为 g711a、g711u、g722、g726。音频编解码通过 CPU 软解。

编解码协议

内部支持的音频编解码协议如下表所示：

协议	采样率	声道数	码率（kbps）	码字（bits）	压缩比	描述
g711a	8000 16000	1 2	64	8	16:8	优点：语音质量最好；CPU 消耗小；支持广泛。缺点：压缩效率低。欧洲和其他地区大都采用 A 律编码。
g711u	8000 16000	1 2	64	8	16:8	优点：语音质量最好；CPU 消耗小；支持广泛。缺点：压缩效率低。北美与日本通常采用 µ 律编码。
g726	8000	1	40 32 24 16	5 4 3 2	16:5 16:4 16:3 16:2	g726 编解码类型需要按照码率设置对应的码字（codeword），g726 编解码器把 128 kbit/s 线性数据（64kbit/s PCM 数据）压缩为 16 kbit/s、24 kbit/s、32 kbit/s、40 kbit/s，数据压缩比分别为 8:1、16:3、4:1、16:5，码字分别为 2、3、4 和 5 bits。采用越高压缩比，码率越小，质量越差。最常用的是 32 kbit/s，即设置码字为 4 就好。
g722	16000	1	64	8	16:8	g722 的优点是延时和传输位误差率非常低。

API 参考

音频解码

该功能模块为用户提供以下 API :

ZH_MPI_ADEC_CreateChn：创建音频解码通道。
ZH_MPI_ADEC_DestroyChn：销毁音频解码通道。
ZH_MPI_ADEC_SendStream：发送音频码流到音频解码通道。
ZH_MPI_ADEC_GetFrame：获取音频解码帧数据。
ZH_MPI_ADEC_ReleaseFrame：释放音频解码帧数据。
ZH_MPI_ADEC_SendEndOfStream：向解码器发送码流结束标识符。
ZH_MPI_ADEC_QueryChnStat：查询 ADEC 通道中当前的音频数据缓存状态。

ZH_MPI_ADEC_CreateChn

描述

创建音频解码通道。

语法

ZH_S32 ZH_MPI_ADEC_CreateChn (ADEC_CHN AdChn, const ADEC_CHN_ATTR_S *pstAttr);

参数

参数名	数据类型	描述	输入 / 输出
AdChn	ADEC_CHN	通道号。取值范围：[0, ADEC_MAX_CHN_NUM]。	输入
pstAttr	const ADEC_CHN_ATTR_S*	通道属性指针。	输出

返回值

返回值	描述
0	成功。
非 0	失败，请参见 AUDIO 错误码

注意事项

音频解码支持的解码协议 : ZH_AUDIO_ID_PCM_ALAW、ZH_AUDIO_ID_PCM_MULAW、ZH_AUDIO_ID_ADPCM_G722、ZH_AUDIO_ID_ADPCM_G726 等，参⻅ zh_common.h 中 ZH_CODEC_ID_E 枚举音频定义。
g726 音频格式需要设置码流码字（codecwords），⽀持的协议说明见表音频编解码协议。
音频解码的初始化属性必须设置码流的采样率（u32SampleRate）、声道数（u32Channels）、codec id（enType）三个参数。解码模式默认为 PACK 模式，⽀持 STREAM 模式，但是建议使⽤ PACK 模式。
在通道闲置时才能使用此接口，如果通道已经被创建，则返回通道已经创建的错误。

ZH_MPI_ADEC_DestroyChn

描述

销毁音频解码通道。

语法

ZH_S32 ZH_MPI_ADEC_DestroyChn(ADEC_CHN AdChn);

参数

参数名	数据类型	描述	输入 / 输出
AdChn	ADEC_CHN	通道号。取值范围：[0, ADEC_CHN_NUM]。	输入

返回值

返回值	描述
0	成功。
非 0	失败，请参见 AUDIO 错误码。

注意事项

通道未创建的情况下调⽤此接口会返回 ZH_ERR_ADEC_UNEXIST。
建议通道使用完成后调用此接口。

ZH_MPI_ADEC_SendStream

描述

向音频解码通道发送码流。

语法

ZH_S32 ZH_MPI_ADEC_SendStream (ADEC_CHN AdChn, const AUDIO_STREAM_S *pstStream, ZH_BOOL bBlock);

参数

参数名	数据类型	描述	输入 / 输出
AdChn	ADEC_CHN	通道号。取值范围：[0, ADEC_MAX_CHN_NUM]。	输入
pstStream	const AUDIO_STREAM_S*	音频码流。	输入
bBlock	ZH_BOOL	阻塞标识。 ZH_TRUE：阻塞。ZH_FALSE：非阻塞。	输入

返回值

返回值	描述
0	成功。
非 0	失败，请参见 AUDIO 错误码。

注意事项

创建解码通道时可以指定解码方式为 pack 方式或者 stream 方式：
- pack 方式用于确定码流包为⼀帧的情况下，比如从网络直接获取的码流，从文件读取确切知道⼀帧边界的码流，效率较高。
- stream 方式用于不确定码流包为⼀帧的情况下，效率较低，且可能会有延迟。
发送数据时必须保证通道已经被创建，否则直接返回失败。
支持阻塞或者非阻塞方式发送码流。
当阻塞方式发送码流时，如果⽤于缓存解码后的⾳频帧的 buffer 满，则此接口调用会被阻塞，直到解码后的⾳频帧数据被取走，或 ADEC 通道被销毁，建议选择阻塞方式发送码流。
确保发送给 ADEC 通道的码流数据的正确性，否则可能引起解码器异常退出。
音频申请内存的方式建议尽量使用 malloc 方式申请。

ZH_MPI_ADEC_GetFrame

描述

获取音频解码帧数据。

语法

ZH_S32 ZH_MPI_ADEC_GetFrame (ADEC_CHN AdChn, AUDIO_FRAME_INFO_S *pstFrmInfo, ZH_BOOL bBlock);

参数

参数名	数据类型	描述	输入 / 输出
AdChn	ADEC_CHN	通道号。取值范围：[0, ADEC_MAX_CHN_NUM]。	输入
pstFrmInfo	AUDIO_FRAME_INFO_S*	音频帧数据结构体。	输出
bBlock	ZH_BOOL	是否以阻塞方式获取。	输入

返回值

返回值	描述
0	成功。
非 0	失败，请参见 AUDIO 错误码。

注意事项

必须在 ADEC 通道创建之后调⽤。
使用本接口获取音频帧数据时，建议发送码流时按 pack ⽅式（帧模式）发送。
使用本接口获取音频帧数据时，如果发送码流按 stream 发送，请务必保证获取解码帧数据的及时性；如果 SendStream 和 GetFrame 接口都是阻塞的，需要各自在不同的线程，不然会阻塞住。
GetFrame 成功后，需要调⽤ ReleaseFrame。
使用本接口获取音频数据时，ADEC BIND AO 的方式不需要用此接口，请先解除 ADEC 与 AO 的绑定关系，否则获取到的帧是不连续的。

ZH_MPI_ADEC_ReleaseFrame

描述

释放获取到的音频解码帧数据。

语法

ZH_S32 ZH_MPI_ADEC_ReleaseFrame (ADEC_CHN AdChn, AUDIO_FRAME_INFO_S *pstFrmInfo);

参数

参数名	数据类型	描述	输入 / 输出
AdChn	ADEC_CHN	通道号。取值范围：[0, ADEC_MAX_CHN-NUM]。	输入
pstFrmInfo	AUDIO_FRAME_INFO_S*	音频帧数据结构。	输入

返回值

返回值	描述
0	成功。
非 0	失败，请参见 AUDIO 错误码。

注意事项

必须在 ADEC 通道创建之后调用。
本接口必须与接口 ZH_MPI_ADEC_GetFrame 配合使用。

ZH_MPI_ADEC_SendEndOfStream

描述

向解码器发送码流结束标识符。

语法

ZH_S32 ZH_MPI_ADEC_SendEndOfStream (ADEC_CHN AdChn, ZH_BOOL bInstant);

参数

参数名	数据类型	描述	输入 / 输出
AdChn	ADEC_CHN	通道号。取值范围：[0, ADEC_MAX_CHN_NUM]。	输入
bInstant	ZH_BOOL	是否立刻清除解码器内部的缓存数据。取值范围： ZH_FALSE：不清除缓存数据，解码继续进行，直到音频解码完成。 ZH_TRUE：立刻清除解码器内部的缓存数据。	输入

返回值

返回值	描述
0	成功。
非 0	失败，请参见 AUDIO 错误码。

注意事项

建议 bInstant 使用 ZH_FALSE。

ZH_MPI_ADEC_QueryChnStat

描述

查询 ADEC 通道中当前的音频数据缓存状态。

语法

ZH_S32 ZH_MPI_ADEC_QueryChnStat (ADEC_CHN AdChn, ADEC_CHN_STATE_S *pstBufferStatus);

参数

参数名	数据类型	描述	输入 / 输出
AdChn	ADEC_CHN	通道号。取值范围：[0, ADEC_MAX_CHN_NUM]。	输入
pstBufferStatus	ADEC_CHN_STATE_S*	缓存状态结构体指针。	输出

返回值

返回值	描述
0	成功。
非 0	失败，请参见 AUDIO 错误码。

注意事项

在 ADEC 通道成功启用后再调用此接口。

音频编码

该功能模块提供以下 API：

ZH_MPI_AENC_CreateChn：创建音频编码通道。
ZH_MPI_AENC_DestroyChn：销毁音频编码通道。
ZH_MPI_AENC_SendFrame：发送音频编码音频帧。
ZH_MPI_AENC_GetStream：获取音频编码码流。
ZH_MPI_AENC_ReleaseStream：释放音频编码码流。
ZH_MPI_AENC_SaveFile：开启音频编码之前通道存文件功能。
ZH_MPI_AENC_QueryFileStatus：查询音频编码通道是否处于存文件状态。

ZH_MPI_AENC_CreateChn

描述

创建音频解码通道。

语法

ZH_S32 ZH_MPI_AENC_CreateChn(AENC_CHN AeChn, const AENC_CHN_ATTR_S *pstAttr);

参数

参数名	数据类型	描述	输入 / 输出
AeChn	AENC_CHN	通道号。取值范围：[0, AENC_MAX_CHN_NUM]。	输入
pstAttr	const AENC_CHN_ATTR_S*	通道属性指针。	输入

返回值

返回值	描述
0	成功。
非 0	失败，请参见 AUDIO 错误码。

注意事项

音频编码支持的解码协议 : ZH_AUDIO_ID_ADPCM_G722、ZH_AUDIO_ID_ADPCM_G726、ZH_AUDIO_ID_PCM_MULAW、ZH_AUDIO_ID_PCM_ALAW 等，参见 zh_common.h 中 ZH_CODEC_ID_E 枚举音频定义。
音频编码的初始化属性必须设置码流的采样率（u32SampleRate）、声道数（u32Channels）、采样精度（enBitwidth）、codec id（enType）参数。
在通道闲置时才能使用此接口，如果通道已经被创建，则返回通道已经创建的错误。

ZH_MPI_AENC_DestroyChn

描述

销毁音频编码通道。

语法

ZH_S32 ZH_MPI_AENC_DestroyChn(AENC_CHN AeChn);

参数

参数名	数据类型	描述	输入 / 输出
AeChn	AENC_CHN	通道号。取值范围：[0, AENC_MAX_CHN_NUM]。	输入

返回值

返回值	描述
0	成功。
非 0	失败，请参见 AUDIO 错误码。

注意事项

通道未创建的情况下调用此接口会返回 ZH_ERR_AENC_UNEXIST。
建议通道使⽤完成后调用此接口。

ZH_MPI_AENC_SendFrame

描述

发送音频编码⾳频帧。

语法

ZH_S32 ZH_MPI_AENC_SendFrame(AENC_CHN AeChn, const AUDIO_FRAME_S *pstFrm, const AEC_FRAME_S *pstAecFrm, ZH_S32 s32MilliSec);

参数

参数名	数据类型	描述	输入 / 输出
AeChn	AENC_CHN	通道号。取值范围：[0, AENC_MAX_CHN_NUM]。	输入
pstFrm	const AUDIO_FRAME_S*	音频帧结构体指针。	输入
pstAecFrm	const AEC_FRAME_S*	回声抵消参考帧结构体指针。	输入
s32MilliSec	ZH_S32	发送数据的超时时间。 -1 表示阻塞模式； ≥0 表示非阻塞模式的超时时间（毫秒）。	输入

返回值

返回值	描述
0	成功。
非 0	失败，请参见 AUDIO 错误码。

注意事项

目前 pstAecFrm 未使⽤，置为 NULL。
s32MilliSec 等于 -1 时，表⽰采⽤阻塞模式发送数据，该接口会⼀直等待直到成功发送数据；⼤于等于 0 时表示非阻塞模式发送数据。s32MilliSec 表示超时时间，该接口在超时时间 s32MilliSec (毫秒)内，成功发送数据则返回成功，如超过设定的时间，没有成功发送数据则报错。
该接口用于用户主动发送音频帧进⾏编码，如果 AENC 通道已经通过系统绑定 (ZH_MPI_SYS_Bind) 接⼝与 AI 绑定，不需要也不建议调此接口。
调用该接口发送音频编码音频帧时，必须先创建对应的编码通道。

ZH_MPI_AENC_GetStream

描述

获取编码后码流。

语法

ZH_S32 ZH_MPI_AENC_GetStream(AENC_CHN AeChn, AUDIO_STREAM_S *pstStream, ZH_S32 s32MilliSec);

参数

参数名	数据类型	描述	输入 / 输出
AeChn	AENC_CHN	通道号。取值范围：[0, AENC_MAX_CHN_NUM]。	输入
pstStream	UDIO_STREAM_S*	音频帧数据结构体。	输出
s32MilliSec	ZH_S32	获取数据的超时时间。 -1 表示阻塞模式； ≥0 表示非阻塞模式超时时间。	输入

返回值

返回值	描述
0	成功。
非 0	失败，请参见 AUDIO 错误码。

注意事项

必须创建通道后才能通过该接口获取码流。
s32MilliSec 等于 -1 时，表示采用阻塞模式获取数据，该接⼝会⼀直等待直到成功获取到数据；⼤于等于 0 时表示非阻塞模式获取数据。该接口在超时时间s32MilliSec (毫秒) 内，如获取到数据则返回成功，如超过设定的时间，没有获取到数据则报错。

ZH_MPI_AENC_ReleaseStream

描述

释放从音频编码通道获取的码流。

语法

ZH_S32 ZH_MPI_AENC_ReleaseStream(AENC_CHN AeChn, const AUDIO_STREAM_S *pstStream);

参数

参数名	数据类型	描述	输入 / 输出
AeChn	AENC_CHN	通道号。取值范围：[0, AENC_MAX_CHN_NUM]。	输入
pstStream	const AUDIO_STREAM_S*	获取的码流指针。	输入

返回值

返回值	描述
0	成功。
非 0	失败，请参见 AUDIO 错误码。

注意事项

码流最好能够在使用完之后立即释放，如果不及时释放，会导致编码过程阻塞。
释放的码流必须是从该通道获取的码流，不得对码流信息结构体进行任何修改，否则会导致码流不能释放，使此码流 buffer 丢失，甚⾄导致程序异常。
释放码流时必须保证通道已经被创建，否则直接返回失败，如果在释放码流过程中销毁通道则会立刻返回失败。

ZH_MPI_AENC_SaveFile

描述

开启音频编码之前通道存文件功能。

语法

ZH_S32 ZH_MPI_AENC_SaveFile(AENC_CHN AeChn, const AUDIO_SAVE_FILE_INFO_S *pstSaveFileInfo);

参数

参数名	数据类型	描述	输入 / 输出
AeChn	AENC_CHN	通道号。取值范围：[0, AENC_MAX_CHN_NUM]。	输入
pstSaveFileInfo	const AUDIO_SAVE_FILE_INFO_S*	音频保存文件属性结构体指针。	输入

返回值

返回值	描述
0	成功。
非 0	失败，请参见 AUDIO 错误码。

注意事项

在 AENC 通道成功启用后再调⽤此接口。

ZH_MPI_AENC_QueryFileStatus

描述

查询频编码通道是否处于存文件的状态。

语法

ZH_S32 ZH_MPI_AENC_QueryFileStatus(AENC_CHN AeChn, AUDIO_FILE_STATUS_S* pstFileStatus);

参数

参数名	数据类型	描述	输入 / 输出
AeChn	AENC_CHN	通道号。取值范围：[0, AENC_MAX_CHN_NUM]。	输入
pstFileStatus	AUDIO_FILE_STATUS_S*	状态属性结构体指针。	输出

返回值

返回值	描述
0	成功。
非 0	失败，请参见 AUDIO 错误码。

注意事项

此接口用于查询音频输出通道是否处于存文件的状态。

数据类型

音频编解码相关数据类型、数据结构定义如下：

ADEC_CHN：定义 ADEC 通道。
ADEC_MAX_CHN_NUM：定义音频解码通道的最大个数。
ADEC_MODE_E：定义解码方式。
ADEC_ATTR_CODEC_S：定义音频解码器属性结构体。
ADEC_CHN_ATTR_S：定义解码通道属性结构体。
ADEC_DECODER_S：定义解码器属性结构体。
AUDIO_FRAME_INFO_S：定义解码后的音频帧信息结构体。
ADEC_CHN_STATE_S：定义音频解码通道的数据缓存状态结构体。
AENC_CHN：定义 AENC 通道。
AENC_MAX_CHN_NUM：定义编码解码通道的最大个数。
AENC_ATTR_CODEC_S：定义音频编码器属性结构体。
AENC_CHN_ATTR_S：定义编码通道属性结构体。
AENC_ENCODER_S：定义编码器属性结构体。
[AUDIO_STREAM_S]：定义音频码流结构体。
AUDIO_ADENC_PARAM_S：定义音频编/解码函数数据交互结构体。

ADEC_CHN

说明

定义 ADEC 通道。

定义

typedef ZH_S32 ADEC_CHN;

ADEC_MAX_CHN_NUM

说明

定义音频解码通道的最大个数。

定义

#define ADEC_MAX_CHN_NUM 32

ADEC_MODE_E

说明

定义解码方式。

定义

typedef ZH_S32 ADEC_CHN;
typedef enum zhADEC_MODE_E {
    /*
     * require input is valid dec pack(a complete frame encode result),
     * e.g.the stream get from AENC is a valid dec pack, the stream know
     * actually pack len from file is also a dec pack.
     * this mode is high-performative*/
    ADEC_MODE_PACK = 0,
    /*
     * input is stream,low-performative, if you couldn't find out whether
     * a stream is vaild dec pack,you could use this mode
    */
    ADEC_MODE_STREAM,
    ADEC_MODE_BUTT
} ADEC_MODE_E;

成员

成员名称	描述
ADEC_MODE_PACK	pack 方式解码。
ADEC_MODE_STREAM	stream 方式解码。

注意事项

pack 方式用于用户确认当前码流包为⼀帧数据编码结果的情况下，解码器会直接进行对其解码，如果不是⼀帧，解码器会出错。这种模式的效率比较⾼，在使用 AENC 模块编码的码流包如果没有破坏，均可以使用此方式解码。
stream 方式用于用户不能确认当前码流包是不是⼀帧数据的情况下，解码器需要对码流进行判断并缓存，此工作方式的效率低下，⼀般⽤于读文件码流送解码或者不确定码流包边界的情况。当然由于语音编码码流⻓度固定，很容易确定在码流中的帧边界，推荐使用 pack 方式解码。

AUDIO_G726_BPS

说明

定义 G726 比特率。

成员

成员名称	描述
G726_BPS_16K	输⼊ / 出数据⽐特率 16000。对应 G726 编码/解码器码字 2 bit。
G726_BPS_24K	输⼊ / 出数据⽐特率 16000。对应 G726 编码/解码器码字 3 bit。
G726_BPS_32K	输⼊ / 出数据⽐特率 16000。对应 G726 编码/解码器码字 4 bit。
G726_BPS_40K	输⼊ / 出数据⽐特率 16000。对应 G726 编码/解码器码字 5 bit。

ADEC_ATTR_CODEC_S

说明

定义⾳频解码器属性结构体。

定义

typedef struct zhADEC_ATTR_CODEC_S {
    ZH_CODEC_ID_E enType;
    ZH_U32 u32Channels;
    ZH_U32 u32SampleRate;
    ZH_U32 u32Bitrate;
    
    ZH_VOID *pExtraData;
    ZH_U32 u32ExtraDataSize;
    
    ZH_U32 u32Resv[4];
    ZH_VOID *pstResv;
} ADEC_ATTR_CODEC_S;

成员

成员名称	数据类型	描述
enType	ZH_CODEC_ID_E	解码协议 (同 ADEC_CHN_ATTR_S 的 enType)。
u32Channels	ZH_U32	码流声道数。
u32SampleRate	ZH_U32	码流采样率。
u32Bitrate	ZH_U32	音频数据比特率。
pExtraData	ZH_VOID*	解码外部数据。
u32ExtraDataSize	ZH_U32	解码外部数据长度。
u32Resv[4]	ZH_U32	保留字节，用于解码器参数扩展。
pstResv	ZH_VOID*	保留结构体指针，用于解码器参数扩展。

注意事项

当结构体变量不足以传递解码器参数时，用户可通过保留字节 u32Resv 和保留结构体指针 pstResv 来扩展参数。
特定解码器需要设置当前音频协议⽀持的⾳频数据比特率，⽐如 G726 解码器。G726 解码器在初始化时，需要根据比特率设置正确的码字 (codeword)，见 AUDIO_G726_BPS。

ADEC_CHN_ATTR_S

说明

定义解码通道属性结构体。

定义

typedef struct zhADEC_CH_ATTR_S {
    ZH_CODEC_ID_E enType;
    ADEC_MODE_E enMode;
    ZH_U32 u32BufCount;
    ZH_U32 u32BufSize;
    
    ADEC_ATTR_CODEC_S stCodecAttr;
} ADEC_CHN_ATTR_S;

成员

成员名称	数据类型	描述
enType	ZH_CODEC_ID_E	解码协议。
enMode	ADEC_MODE_E	解码方式。
u32BufCount	ZH_U32	解码缓存数量。
u32BufSize	ZH_U32	解码缓存大小（单位字节）。
stCodecAttr	ADEC_ATTR_CODEC_S	解码器属性结构体。

注意事项

u32BufSize 定义解码器 buffer 大小。当使用注册解码器解码时，函数 pfnDecodeFrm 的 pu8Outbuf 大小即为 u32BufSize 定义的大小。当该值定义过小时，会造成⼀次解码的数据，要多次读取的情况。当该值为定义时 (即 0)，ADEC 默认解码 buffer 大小为 4096 字节。

相关数据类型及接⼝

ZH_MPI_ADEC_CreateChn

ADEC_DECODER_S

说明

定义解码器结构体。

定义

typedef struct zhADEC_DECODER_S {
    ZH_CODEC_ID_E enType;
    ZH_UCHAR aszName[17];
    ZH_S32 (*pfnOpenDecoder)(ZH_VOID *pDecoderAttr, ZH_VOID **ppDecoder);
    ZH_S32 (*pfnDecodeFrm)(ZH_VOID *pDecoder, ZH_VOID *pDecParam);
    ZH_S32 (*pfnGetFrmInfo)(ZH_VOID *pDecoder, ZH_VOID *pInfo);
    ZH_S32 (*pfnCloseDecoder)(ZH_VOID *pDecoder);
    ZH_S32 (*pfnResetDecoder)(ZH_VOID *pDecoder);
} ADEC_DECODER_S;

成员

成员名称	数据类型	描述
enType	ZH_CODEC_ID_E	解码协议类型。
aszName	ZH_UCHAR	解码器名称。
pfnOpenDecoder	ZH_S32	打开解码器的函数指针。
pfnDecodeFrm	ZH_S32	解码器的函数指针。
pfnGetFrmInfo	ZH_S32	获取音频帧信息的函数指针。
pfnCloseDecoder	ZH_S32	关闭解码器的函数指针。
pfnResetDecoder	ZH_S32	清空缓存 buffer，复位编码器。

注意事项

pfnOpenDecoder 函数第⼀个参数 pDecoderAttr 为 ADEC_ATTR_CODEC_S 类型，用户可在对应的注册函数中强行类型转换，可访问 ADEC_ATTR_CODEC_S 中的相关变量。
pfnDecodeFrm 函数的第⼆个参数 pDecParam 为 AUDIO_ADENC_PARAM_S 类型，用户可在对应的注册函数中强行类型转换，可访问 AUDIO_ADENC_PARAM_S 中的相关变量。

ADEC_DECODER_RESULT

说明

定义注册解码器解码函数返回值。

定义

typedef enum zhADEC_DECODER_RESULT {
    ADEC_DECODER_OK = ZH_SUCCESS,
    ADEC_DECODER_TRY_AGAIN,
    ADEC_DECODER_ERROR,
    ADEC_DECODER_EOS,
} ADEC_DECODER_RESULT;

成员

成员名称	描述
ADEC_DECODER_OK	编码成功（送解码数据成功且拿到了解码数据）。
ADEC_DECODER_TRY_AGAIN	解码重试。
ADEC_DECODER_ERROR	解码错误。
ADEC_DECODER_EOS	解码最后一帧数据。

注意事项

ADEC_DECODER_TRY_AGAIN：该值用于在表示当前解码数据送⼊失败 (比如当前解码内部缓冲满，无法送⼊新的数据) 或者送入码流数据后，没有拿到解码数据的情形。ADEC 模块在获取该返回值后，会再次送⼊当前码流(如果 AUDIO_ADENC_PARAM_S 的 u32InLen 输出值不为 0)。
ADEC_DECODER_ERROR：解码错误。ADEC 获取到该值后，会丢弃当前帧。
ADEC_DECODER_EOS：该值用于通知 ADEC 模块，解码器已送出最后⼀帧数据 (标记当前解码结束)。ADEC 模块获取到该值后，不再调用解码器相关函数进行解码，并标记当前音频帧为 EOS 帧。

ADEC_FRAME_INFO_S

说明

定义注册解码器⾳频帧信息。

定义

typedef struct zhADEC_FRAME_INFO_S {
    ZH_U32 u32SampleRate;
    ZH_U32 u32Channels;
    ZH_U64 u64ChnLayout;
    AUDIO_BIT_WIDTH_E enBitWidth;
    ZH_U32 resv[2];
} ADEC_FRAME_INFO_S;

成员

成员名称	数据类型	描述
u32SampleRate	ZH_U32	解码数据的采样率。
u32Channels	ZH_U32	解码数据的声道数。
u64ChnLayout	ZH_U64	解码数据的声道布局。
enBitWidth	AUDIO_BIT_WIDTH_E	解码数据的采样精度。
resv[2]	ZH_U32	保留位，用于扩展。

AUDIO_FRAME_INFO_S

说明

定义解码后的音频帧信息结构体。

定义

typedef struct zhAUDIO_FRAME_INFO_S {
    AUDIO_FRAME_S *pstFrame;/*frame ptr*/
    ZH_U32 u32Id; /*frame id*/
} AUDIO_FRAME_INFO_S;

成员

成员名称	数据类型	描述
pstFrame	AUDIO_FRAME_S*	音频帧指针。
u32Id	ZH_U32	音频帧的索引。

ADEC_CHN_STATE_S

说明

定义音频解码通道的数据缓存状态结构体。

定义

typedef struct zhADEC_CH_STATE_S {
    ZH_BOOL bEndOfStream; /* EOS flag */
    ZH_U32 u32BufferFrmNum; /* total number of channel buffer */
    ZH_U32 u32BufferFreeNum; /* free number of channel buffer */
    ZH_U32 u32BufferBusyNum; /* busy number of channel buffer */
} ADEC_CHN_STATE_S;

成员

成员名称	数据类型	描述
bEndOfStream	ZH_BOOL	解码码流结束状态。
u32BufferFrmNum	ZH_U32	解码通道总数的缓存块数。
u32BufferFreeNum	ZH_U32	可用的空闲缓存块数。
u32BufferBusyNum	ZH_U32	被占用缓存块数。

AENC_CHN

说明

定义 AENC 通道。

定义

typedef ZH_S32 AENC_CHN;

AENC_MAX_CHN_NUM

说明

定义音频解码通道的最大个数。

定义

#define AENC_MAX_CHN_NUM 32

AENC_ATTR_CODEC_S

说明

定义音频编码器属性结构体。

定义

typedef struct zhAENC_ATTR_CODEC_S {
    ZH_CODEC_ID_E enType;
    AUDIO_BIT_WIDTH_E enBitwidth;
    ZH_U32 u32Channels;
    ZH_U32 u32SampleRate;
    ZH_U32 u32Bitrate;
    ZH_U32 u32Resv[4];
    ZH_VOID *pstResv;
} AENC_ATTR_CODEC_S;

成员

成员名称	数据类型	描述
enType	ZH_CODEC_ID_E	编码协议类型（同 AENC_CHN_ATTR_S 的 enType）
enBitwidth	AUDIO_BIT_WIDTH_E	音频采样精度。
u32Channels	ZH_U32	音频声道数。
u32SampleRate	ZH_U32	音频采样率。
u32Bitrate	ZH_U32	音频流输出比特率。
u32Resc[4]	ZH_U32	保留字节，用于编码器参数扩展。
psrResv	ZH_VOID*	保留结构体指针，用于编码器参数扩展。

注意事项

部分编码器 (如 G726，⻅ AUDIO_G726_BPS) 需要设置当前音频协议支持的比特率，用于编码码流的比特率控制。

AENC_CHN_ATTR_S

说明

定义编码通道属性结构体。

定义

typedef struct zhAENC_CHN_ATTR_S {
    ZH_CODEC_ID_E enType;
    ZH_U32 u32BufCount;
    AENC_ATTR_CODEC_S stCodecAttr;
} AENC_CHN_ATTR_S;

成员

成员名称	数据类型	描述
enType	ZH_CODEC_ID_E	编码协议类型。
u32BufCount	ZH_U32	音频编码缓存个数。
stCodecAttr	AENC_ATTR_CODEC_S	编码器属性结构体。

AENC_ENCODER_S

说明

定义解码器结构体。

定义

typedef struct zhkAENC_ENCODER_S {
    ZH_CODEC_ID_E enType;
    ZH_U32 u32MaxFrmLen;
    ZH_CHAR aszName[17];
    ZH_S32 (*pfnOpenEncoder)(ZH_VOID *pEncoderAttr, ZH_VOID **ppEncoder);
    ZH_S32 (*pfnEncodeFrm)(ZH_VOID *pEncoder, ZH_VOID *pParam);
    ZH_S32 (*pfnCloseEncoder)(ZH_VOID *pEncoder);
} AENC_ENCODER_S;

成员

成员名称	数据类型	描述
enType	ZH_CODEC_ID_E	编码协议类型。
u32MaxFrmLen	ZH_U32	最大码流长度。
aszName	ZH_CHAR	编码器名称。
pfnOpenEncoder	ZH_S32	打开编码器的函数指针。
pfnEncodeFrm	ZH_S32	进行编码的函数指针。
pfnCloseEncoder	ZH_S32	关闭编码器的函数指针。

注意事项

pfnOpenEncoder 函数第⼀个参数 pEncoderAttr 为 AENC_ATTR_CODEC_S 类型，用户可在对应的注册函数中强行类型转换，并访问到 AENC_ATTR_CODEC_S 中的相关变量。
pfnEncodeFrm 函数的第⼆个参数 pParam 为 AUDIO_ADENC_PARAM_S 类型，用户可在对应的注册函数中强行类型转换，并访问到 AUDIO_ADENC_PARAM_S 中的相关变量。

AUDIO_ADENC_PARAM_S

说明

定义注册解码器/编码器，解码/编码输入输出结构体。

定义

typedef struct zhAUDIO_ADENC_PARAM_S {
    ZH_U8 *pu8InBuf;
    ZH_U32 u32InLen;
    ZH_U64 u64InTimeStamp;
    
    ZH_U8 *pu8OutBuf;
    ZH_U32 u32OutLen;
    ZH_U64 u64OutTimeStamp;
} AUDIO_ADENC_PARAM_S;

成员

成员名称	数据类型	描述	输入 / 输出
pu8InBuf	ZH_U8*	输入数据 buffer 指针。	输入
u32InLen	ZH_U32	输入：输入数据长度（即 pu8InBuf 中输入有效数据的长度）。输出：输入 buffer 中（即 pu8InBuf）剩余数据的长度。	输入 / 出
u64InTimeStamp	ZH_U64	输入数据的时间戳。	输入
pu8OutBuf	ZH_U8*	输出数据 buffer 指针。	输入
u32OutLen	ZH_U32	输入：输出 buffer 的最大容量。输出：输出 buffer 中有效数据的长度。	输入 / 出
u64OutTimeStamp	ZH_U64	输出数据的时间戳。	输出

AENC_ENCODER_RESULT

说明

定义注册编码器编码返回值。

定义

typedef enum zhENC_ENCODER_RESULT {
    AENC_ENCODER_OK = ZH_SUCCESS,
    AENC_ENCODER_TRY_AGAIN,
    AENC_ENCODER_ERROR,
    AENC_ENCODER_EOS,
} AENC_ENCODER_RESULT;

成员

成员名称	描述
AENC_ENCODER_OK	编码成功（送编码数据成功且拿到了编码后的码流数据）。
AENC_ENCODER_TRY_AGAIN	编码重试。
AENC_ENCODER_ERROR	编码错误。
AENC_ENCODER_EOS	编码最后一帧数据。

注意事项

AENC_ENCODER_TRY_AGAIN：该值用于在表示当前帧送⼊失败或者送⼊当前帧后，没有获取码流。AENC模块在获取该返回值后，会再次送入当前码流(如果 AUDIO_ADENC_PARAM_S 的 u32InLen 输出值不为 0 时)。
AENC_ENCODER_ERROR：AENC 模块获取该返回值后，会丢弃当前输⼊ / 输出数据。
AENC_ENCODER_EOS：该值用于通知 AENC 模块，编码器已送出最后⼀帧数据 (标记当前解码结束)。AENC 模块获取到该值后，不再调用编码器相关函数进行编码，并标记当前音频帧为 EOS 帧。

AUDIO 错误码

⾳频解码 AUDIO 错误码

音频解码 API AUDIO 错误码如下所示。

错误代码	宏定义	描述
0xA00D8001	ZH_ERR_ADEC_INVALID_DEVID	音频解码设备号无效。
0xA00D8002	ZH_ERR_ADEC_INVALID_CHNID	音频解码通道号无效。
0xA00D8003	ZH_ERR_ADEC_ILLEGAL_PARAM	音频解码参数设置无效。
0xA00D8004	ZH_ERR_ADEC_EXIST	音频解码通道已被使用。
0xA00D8005	ZH_ERR_ADEC_UNEXIST	音频解码通道未被创建。
0xA00D8006	ZH_ERR_ADEC_NULL_PTR	输入参数空指针错误。
0xA00D8007	ZH_ERR_ADEC_NOT_CONFIG	音频解码属性未设置。
0xA00D8008	ZH_ERR_ADEC_NOT_SUPPORT	操作不被支持。
0xA00D8009	ZH_ERR_ADEC_NOT_PERM	操作不允许。
0xA00D800C	ZH_ERR_ADEC_NOMEN	解码分配内存失败。
0xA00D800D	ZH_ERR_ADEC_NOBUF	解码通道缓存分配失败。
0xA00D800E	ZH_ERR_ADEC_BUF_EMPTY	音频解码缓存 buffer 为空。
0xA00D800F	ZH_ERR_ADEC_BUF_FULL	音频解码缓存为满。
0xA00D8010	ZH_ERR_ADEC_SYS_NOTREADY	音频解码系统未初始化。
0xA00D8040	ZH_ERR_ADEC_DECODER_ERR	音频解码数据错误。
0xA00D8041	ZH_ERR_ADEC_BUF_LACK	音频解码输入缓存空间不够。
0xA00D8042	ZH_ERR_ADEC_REGISTER_ERR	音频解码器注册 / 注销失败。

⾳频编码 AUDIO 错误码

音频编码 API AUDIO 错误码如下所示。

错误代码	宏定义	描述
0xA00C8001	ZH_ERR_AENC_INVALID_DEVID	音频设备号无效。
0xA00C8002	ZH_ERR_AENC_INVALID_CHNID	音频编码通道号无效。
0xA00C8003	ZH_ERR_AENC_ILLEGAL_PARAM	音频编码参数设置无效。
0xA00C8004	ZH_ERR_AENC_EXIST	音频编码通道已经创建。
0xA00C8005	ZH_ERR_AENC_UNEXIST	音频编码通道未创建。
0xA00C8006	ZH_ERR_AENC_NULL_PTR	输入参数空指针错误。
0xA00C8007	ZH_ERR_AENC_NOT_CONFIG	编码通道未配置。
0xA00C8008	ZH_ERR_AENC_NOT_SUPPORT	操作不被支持。
0xA00C8009	ZH_ERR_AENC_NOT_PERM	操作不允许。
0xA00C800C	ZH_ERR_AENC_NOMEN	系统内存不足。
0xA00C800D	ZH_ERR_AENC_NOBUF	编码通道缓存分配失败。
0xA00C800E	ZH_ERR_AENC_BUF_EMPTY	编码通道缓存空。
0xA00C800F	ZH_ERR_AENC_BUF_FULL	音频输出缓存为满。
0xA00C8010	ZH_ERR_AENC_SYS_NOTREADY	系统没有初始化。
0xA00C8040	ZH_ERR_AENC_ENCODER_ERR	音频编码数据错误。
0xA00C8041	ZH_ERR_AENC_VQE_ERR	AENC VQE 处理错误。
0xA00C8042	ZH_ERR_AENC_REGISTER_ERR	音频编码器注册 / 注销失败。

概述​

编解码协议​

API 参考​

音频解码​

ZH_MPI_ADEC_CreateChn​

ZH_MPI_ADEC_DestroyChn​

ZH_MPI_ADEC_SendStream​

ZH_MPI_ADEC_GetFrame​

ZH_MPI_ADEC_ReleaseFrame​

ZH_MPI_ADEC_SendEndOfStream​

ZH_MPI_ADEC_QueryChnStat​

音频编码​

ZH_MPI_AENC_CreateChn​

ZH_MPI_AENC_DestroyChn​

ZH_MPI_AENC_SendFrame​

ZH_MPI_AENC_GetStream​

ZH_MPI_AENC_ReleaseStream​

ZH_MPI_AENC_SaveFile​

ZH_MPI_AENC_QueryFileStatus​

数据类型​

ADEC_CHN​

ADEC_MAX_CHN_NUM​

ADEC_MODE_E​

AUDIO_G726_BPS​

ADEC_ATTR_CODEC_S​

ADEC_CHN_ATTR_S​

ADEC_DECODER_S​

ADEC_DECODER_RESULT​

ADEC_FRAME_INFO_S​

AUDIO_FRAME_INFO_S​

ADEC_CHN_STATE_S​

AENC_CHN​

AENC_MAX_CHN_NUM​

AENC_ATTR_CODEC_S​

AENC_CHN_ATTR_S​

AENC_ENCODER_S​

AUDIO_ADENC_PARAM_S​

AENC_ENCODER_RESULT​

AUDIO 错误码​

⾳频解码 AUDIO 错误码​

⾳频编码 AUDIO 错误码​

概述

编解码协议

API 参考

音频解码

ZH_MPI_ADEC_CreateChn

ZH_MPI_ADEC_DestroyChn

ZH_MPI_ADEC_SendStream

ZH_MPI_ADEC_GetFrame

ZH_MPI_ADEC_ReleaseFrame

ZH_MPI_ADEC_SendEndOfStream

ZH_MPI_ADEC_QueryChnStat

音频编码

ZH_MPI_AENC_CreateChn

ZH_MPI_AENC_DestroyChn

ZH_MPI_AENC_SendFrame

ZH_MPI_AENC_GetStream

ZH_MPI_AENC_ReleaseStream

ZH_MPI_AENC_SaveFile

ZH_MPI_AENC_QueryFileStatus

数据类型

ADEC_CHN

ADEC_MAX_CHN_NUM

ADEC_MODE_E

AUDIO_G726_BPS

ADEC_ATTR_CODEC_S

ADEC_CHN_ATTR_S

ADEC_DECODER_S

ADEC_DECODER_RESULT

ADEC_FRAME_INFO_S

AUDIO_FRAME_INFO_S

ADEC_CHN_STATE_S

AENC_CHN

AENC_MAX_CHN_NUM

AENC_ATTR_CODEC_S

AENC_CHN_ATTR_S

AENC_ENCODER_S

AUDIO_ADENC_PARAM_S

AENC_ENCODER_RESULT

AUDIO 错误码

⾳频解码 AUDIO 错误码

⾳频编码 AUDIO 错误码