Hi3403开发文档
前言¶
本文档为使用媒体处理芯片的音频进行智能分析方案开发的程序员而写，目的是供您在开发过程中查阅音频支持的各种参考信息，包括各项协议说明、API、错误码等。
与本文档相对应的产品版本如下。
本文档（本指南）主要适用于以下工程师：
技术支持工程师
软件开发工程师
在本文中可能出现下列标志，它们所代表的含义如下。
修订记录累积了每次文档更新的说明。最新版本的文档包含以前所有文档版本的更新内容。
音频组件¶
概述¶
音频组件集成了AAC编解码协议，并开放接口，以便于用户集成第三方提供的编解码协议。AAC编解码使用示例代码在sample/audio目录。
须知： 客户如果需要使用AAC格式的专利，必须从版权权利人处获取授权，并缴纳Licensing Fee。
重要概念¶
音频编解码协议
音频组件提供的编解码功能基于独立封装的AAC编解码库，核心编解码器工作在用户态，使用CPU软件编解码。
AAC编解码协议说明如表1所示。
表 1 音频编解码协议说明
注：“cpu消耗”的结果值基于ARM9 288MHz环境，2/2 MHz表示编码和解码分别占有2M和2M CPU。
表 2 AAC Encoder各协议码率设置（码率单位为kbps）
注：“—”表示不支持这种情况。
表 3 AAC Encoder Low Delay协议码率设置（码率单位为kbps）
音频编解码集成接口
SDK发布包中开放接口用于注册和注销编码器和解码器，音频组件根据这些接口，提供了注册AAC编解码器的示例。用户既可以参考示例，注册自有的第三方编解码器，也可直接使用音频组件提供的示例来注册并使用组件中的AAC编解码器。
【注意】
AAC编解码器的使用支持静态库注册的形式，相关库包括libaac_comm.a、libaac_enc.a、libaac_sbr_enc.a、libaac_dec.a、libaac_sbr_dec.a。其中，libaac_sbr_enc.a在AAC编码器不使用EAAC、EAACPLUS、AACELD类型编码时可裁剪；libaac_sbr_dec.a在AAC解码器不使用EAAC、EAACPLUS、AACELD类型解码时可裁剪。当使用EAAC、EAACPLUS、AACELD编解码类型时，须在注册编解码器之前进行SBRENC、SBRDEC功能模块的静态注册。
AAC编解码器的使用还支持动态库调用的形式，相关库包括libaac_comm.so、libaac_enc.so、libaac_sbr_enc.so、libaac_dec.so、libaac_sbr_dec.so。其中，libaac_sbr_enc.so在AAC编码器不使用EAAC、EAACPLUS、AACELD类型编码时可裁剪；libaac_sbr_dec.so在AAC解码器不使用EAAC、EAACPLUS、AACELD类型解码时可裁剪。
AAC编解码器不支持同时使用静态库注册和动态库调用。
AAC编解码器的静态库注册只允许成功调用一次，不支持重复注册。
【举例】
下面的代码实现静态注册AAC的SBRENC和SBRDEC模块。
td_s32 ret;
td_void* sbr_enc_handle = ss_aac_sbrenc_get_handle();
/* register SBRENC module. */
ret = ss_aacenc_register_mod(sbr_enc_handle);
if (ret != TD_SUCCESS) {
printf("[func]:%s [line]:%d [info]:%s\n",
__FUNCTION__, __LINE__, "init sbr_enc lib fail!\n");
return OT_ERR_AENC_NOT_SUPPORT;
}
td_void* sbr_dec_handle = ss_aac_sbrdec_get_handle();
/* register SBRDEC module. */
ret = ss_aacdec_register_mod(sbr_dec_handle);
if (ret != TD_SUCCESS) {
printf("[func]:%s [line]:%d [info]:%s\n",
__FUNCTION__, __LINE__, "init sbr_dec lib fail!\n");
return OT_ERR_ADEC_NOT_SUPPORT;
}
API参考¶
SDK发布包中的以下API用于注册和注销编码器和解码器。
ss_mpi_aenc_register_encoder：注册编码器。
ss_mpi_adec_register_decoder：注册解码器。
音频组件中提供的注册示例：
ss_mpi_aenc_aac_init：注册AAC编码器。
ss_mpi_adec_aac_init：注册AAC解码器。
ss_mpi_aenc_register_encoder¶
【描述】
注册编码器。
【语法】
td_s32 ss_mpi_aenc_register_encoder(td_s32 *handle, const ot_aenc_encoder *encoder);
【参数】
【返回值】
失败，其值为错误码。 |
【需求】
头文件：ot_comm_aenc.h、ss_mpi_audio.h
库文件：libss_mpi.a
【注意】
用户通过传入编码器属性结构体，向AENC模块注册一个编码器，并返回注册句柄，用户可以最后通过注册句柄来注销该编码器。
AENC模块最大可注册20个编码器，且自身已注册LPCM、G711a、G711u、G726、ADPCM五个编码器。
同一种编码协议不允许重复注册编码器，例如假如已注册AAC编码器，不允许另外再注册一个AAC编码器。
编码器属性包括编码器类型、最大码流长度、编码器名称、打开编码器的函数指针、进行编码的函数指针、关闭编码器的函数指针。
编码器类型
SDK以枚举标识编码协议，注册时应选择相关协议的编码器类型。
最大码流长度
每帧编码后码流的最大长度，AENC模块将根据注册的最大码流长度分配内存大小。
编码器名称
编码器名称用字符串表示，用于在proc信息中显示。
打开编码器的函数指针
SDK封装的一个函数指针，其函数原型为：
td_s32 (*func_open_encoder)(td_void *encoder_attr, td_void **encoder);
其中第一个参数是编码器属性，用于传入不同类型的编码器的特定属性；第二个参数是编码器句柄，用于返回可用于操作编码器的句柄。这两个参数均由用户封装，用户封装第二个参数时需要注意分配内存，因为编码器句柄还将用于编码和关闭编码器。
进行编码的函数指针
SDK封装的一个函数指针，其函数原型为：
td_s32 (*func_enc_frame)(td_void *encoder, const ot_audio_frame *data, td_u8 *out_buf, td_u32 *out_len);
第一个参数是上一个函数打开编码器时返回的编码器句柄；第二个参数是SDK的音频帧数据结构体的指针，用于传入音频帧数据；第三个参数是输出缓存指针；第四个参数是输出缓存长度。
关闭编码器的函数指针
SDK封装的一个函数指针，其函数原型为：
td_s32 (*func_close_encoder)(td_void *encoder);
参数是打开编码器时返回的编码器句柄。
用户需根据这几个函数原型封装第三方编码器，并通过编码器属性结构体注册给AENC模块，从而实现第三方编码器的集成。
必须在创建编码通道前注册相关类型的编码器，编码器不需要重复注册。
【举例】
下面的代码举例AAC编码器的注册：
td_s32 handle, ret;
aenc_encoder aac;
ret = aac_init_enc_lib();
if (ret) {
return ret;
}
aac.type = OT_PT_AAC;
snprintf(aac.name, sizeof(aac.name), "aac");
aac.max_frame_len = MAX_AAC_MAINBUF_SIZE;
aac.func_open_encoder = open_aac_encoder;
aac.func_enc_frame = encode_aac_frm;
aac.func_close_encoder = close_aac_encoder;
ret = ss_mpi_aenc_register_encoder(&handle, &aac);
if (ret) {
return ret;
}
return TD_SUCCESS;
【相关主题】
无。
ss_mpi_aenc_unregister_encoder¶
【描述】
注销解码器。
【语法】
td_s32 ss_mpi_aenc_unregister_encoder(td_s32 handle);
【参数】
【返回值】
失败，其值为错误码。 |
【需求】
头文件：ot_comm_aenc.h、ss_mpi_audio.h
库文件：libss_mpi.a
【注意】
通常不需要注销编码器。
【举例】
无
【相关主题】
无
ss_mpi_adec_register_decoder¶
【描述】
注册解码器。
【语法】
td_s32 ss_mpi_adec_register_decoder(td_s32 *handle, const ot_adec_decoder *decoder);
【参数】
【返回值】
失败，其值为错误码。 |
【需求】
头文件：ot_comm_adec.h、ss_mpi_audio.h
库文件：libss_mpi.a
【注意】
用户通过传入解码器属性结构体，向ADEC模块注册一个解码器，并返回注册句柄，用户可以最后通过注册句柄来注销该解码器。
ADEC模块最大可注册20个解码器，且自身已注册LPCM、G711a、G711u、G726、ADPCM五个解码器。
同一种解码协议不允许重复注册解码器，例如假如已注册AAC解码器，不允许另外再注册一个AAC解码器。
解码器属性包括解码器类型、解码器名称、打开解码器的函数指针、进行解码的函数指针、获取音频帧信息的函数指针、关闭解码器的函数指针。
解码器类型
SDK以枚举标识解码协议，注册时应选择相关协议的解码器类型。
解码器名称
解码器名称用字符串表示，用于在proc信息中显示。
打开解码器的函数指针
SDK封装的一个函数指针，其函数原型为：
td_s32 (*func_open_decoder)(td_void *decoder_attr, td_void **decoder)；其中第一个参数是解码器属性，用于传入不同类型的解码器的特定属性；第二个参数是解码器句柄，用于返回可用于操作解码器的句柄。这两个参数均由用户封装，用户封装第二个参数时需要注意分配内存，因为解码器句柄还将用于解码和关闭解码器。
进行解码的函数指针
SDK封装的一个函数指针，其函数原型为：
td_s32 (*func_dec_frame)(td_void *decoder, td_u8 **in_buf, td_s32 *left_byte, td_u16 *out_buf, td_u32 *out_len, td_u32 *chns)；第一个参数是上一个函数打开解码器时返回的解码器句柄；第二个参数是输入缓存，用于传入音频帧数据；第三个参数用于返回剩余字节数，用于流式解码，即每次送入的音频帧数据不是完整的一帧的情形；第四个参数是输出缓存；第五个参数是输出数据的单声道长度；第六个参数是输出的通道数，码流数据经解码后，可能输出单声道，也可能输出立体声。
获取音频帧信息的函数指针
SDK封装的一个函数指针，其函数原型为：
td_s32 (*func_get_frame_info)(td_void *decoder, td_void *info)；第一个参数是打开解码器时返回的解码器句柄；第二个参数是用户封装的音频帧信息，有的解码器解析码流时会获取解码后音频数据的采样点、采样率等信息；如果用户解码器不需要此函数，可以为该函数原型封装一个空函数。
关闭解码器的函数指针
SDK封装的一个函数指针，其函数原型为：
td_s32 (*func_close_decoder)(td_void *decoder)；参数是打开解码器时返回的解码器句柄。
用户需根据这几个函数原型封装第三方解码器，并通过解码器属性结构体注册给ADEC模块，从而实现第三方解码器的集成。
必须在创建解码通道前注册相关类型的解码器，解码器不需要重复注册。
【举例】
下面的代码举例AAC解码器的注册：
td_s32 handle, ret;
adec_decoder aac;
ret = aac_init_dec_lib();
if (ret) {
return ret;
}
aac.type = OT_PT_AAC;
snprintf(aac.name, sizeof(aac.name), "aac");
aac.func_open_decoder = open_aac_decoder;
aac.func_dec_frame = decode_aac_frm;
aac.func_get_frame_info = get_aac_frm_info;
aac.func_close_decoder = close_aac_decoder;
aac.func_reset_decoder = reset_aac_decoder;
ret = ss_mpi_adec_register_decoder(&handle, &aac);
if (ret) {
return ret;
}
return TD_SUCCESS;
【相关主题】
无。
ss_mpi_adec_unregister_decoder¶
【描述】
注销解码器。
【语法】
td_s32 ss_mpi_adec_unregister_decoder(td_s32 handle);
【参数】
【返回值】
失败，其值为错误码。 |
【需求】
头文件：ot_comm_adec.h、ss_mpi_audio.h
库文件：libss_mpi.a
【注意】
通常不需要注销解码器。
【举例】
无
【相关主题】
无。
ss_mpi_aenc_aac_init¶
【描述】
注册AAC编码器。
【语法】
td_s32 ss_mpi_aenc_aac_init(td_void);
【参数】
无
【返回值】
失败，其值为错误码。 |
【需求】
源文件：audio_aac_adp.c
头文件：audio_aac_adp.h
库文件：libaac_comm.so、libaac_enc.so
【注意】
此接口在audio_aac_adp.c里实现，而audio_aac_adp.c并没有封装成库，所以在使用此接口时，需要包含audio_aac_adp.c和audio_aac_adp.h才能编译通过。这两个文件默认放置在sample/audio/adp文件夹中。此外，在需要使用到SBRENC功能时，需要添加libaac_sbr_enc.so库。
【举例】
无。
【相关主题】
无。
ss_mpi_adec_aac_init¶
【描述】
注册AAC解码器。
【语法】
td_s32 ss_mpi_adec_aac_init(td_void);
【参数】
无
【返回值】
失败，其值为错误码。 |
【需求】
源文件：aduio_aac_adp.h
头文件：audio_aac_adp.h
库文件：libaac_comm.so、libaac_dec.so
【注意】
请参考ss_mpi_aenc_aac_init接口注意项的说明。此外，在需要使用到SBRDEC功能时，需要添加libaac_sbr_dec.so库。
【举例】
无。
【相关主题】
无。
数据类型¶
音频组件相关数据类型、数据结构定义如下：
ot_aenc_encoder：定义编码器属性结构体。
ot_adec_decoder：定义解码器属性结构体。
ot_aac_type：定义AAC音频编解码协议类型。
ot_aac_bps：定义AAC音频编码码率。
ot_aac_transport_type：定义AAC音频编解码协议传输封装类型。
ot_aenc_attr_aac：定义AAC编码协议属性结构体。
ot_adec_attr_aac：定义AAC解码协议属性结构体。
ot_aenc_encoder¶
【说明】
定义编码器属性结构体。
【定义】
typedef struct {
ot_payload_type type;
td_u32 max_frame_len;
ot_char name[OT_MAX_ENCODER_NAME_LEN]; /* encoder type,be used to print proc information */
td_s32 (*func_open_encoder)(td_void *encoder_attr, td_void **encoder); /* encoder is the handle to control the encoder */
td_s32 (*func_enc_frame)(td_void *encoder, const ot_audio_frame *data, td_u8 *out_buf, td_u32 *out_len);
td_s32 (*func_close_encoder)(td_void *encoder);
} ot_aenc_encoder;
【成员】
编码器名称。OT_MAX_ENCODER_NAME_LEN定义见《MPP 媒体处理软件V5.0 开发参考》“音频”章节。 |
|
【注意事项】
无。
【相关数据类型及接口】
ot_adec_decoder¶
【说明】
定义解码器属性结构体。
【定义】
typedef struct {
ot_payload_type type;
ot_char name[OT_MAX_DECODER_NAME_LEN];
td_s32 (*func_open_decoder)(td_void *decoder_attr, td_void **decoder); /* struct decoder is packed by user, user malloc and free memory for this struct */
td_s32 (*func_dec_frame)(td_void *decoder, td_u8 **in_buf, td_s32 *left_byte, td_u16 *out_buf, td_u32 *out_len, td_u32 *chns);
td_s32 (*func_get_frame_info)(td_void *decoder, td_void *info);
td_s32 (*func_close_decoder)(td_void *decoder);
td_s32 (*func_reset_decoder)(td_void *decoder);
} ot_adec_decoder;
【成员】
解码器名称。OT_MAX_DECODER_NAME_LEN定义见《MPP 媒体处理软件V5.0 开发参考》“音频”章节。 |
|
【注意事项】
无。
【相关数据类型及接口】
ot_aac_type¶
【说明】
定义AAC音频编解码协议类型。
【定义】
typedef enum {
OT_AAC_TYPE_AACLC = 0,
OT_AAC_TYPE_EAAC = 1,
OT_AAC_TYPE_EAACPLUS = 2,
OT_AAC_TYPE_AACLD = 3,
OT_AAC_TYPE_AACELD = 4,
OT_AAC_TYPE_BUTT,
} ot_aac_type;
【成员】
【注意事项】
无。
【相关数据类型及接口】
无。
ot_aac_bps¶
【说明】
定义AAC音频编码码率。
【定义】
typedef enum {
OT_AAC_BPS_8K = 8000,
OT_AAC_BPS_16K = 16000,
OT_AAC_BPS_22K = 22000,
OT_AAC_BPS_24K = 24000,
OT_AAC_BPS_32K = 32000,
OT_AAC_BPS_48K = 48000,
OT_AAC_BPS_64K = 64000,
OT_AAC_BPS_96K = 96000,
OT_AAC_BPS_128K = 128000,
OT_AAC_BPS_256K = 256000,
OT_AAC_BPS_320K = 320000,
OT_AAC_BPS_BUTT
} ot_aac_bps;
【成员】
【注意事项】
无。
【相关数据类型及接口】
无。
ot_aac_transport_type¶
【说明】
定义AAC音频编解码协议传输封装类型。
【定义】
typedef enum {
OT_AAC_TRANSPORT_TYPE_ADTS = 0,
OT_AAC_TRANSPORT_TYPE_LOAS = 1,
OT_AAC_TRANSPORT_TYPE_LATM_MCP1 = 2,
OT_AAC_TRANSPORT_TYPE_BUTT
} ot_aac_transport_type;
【成员】
【注意事项】
LATM1格式由于不具备同步帧头机制，在码流出现问题时无法快速恢复，不推荐使用。
【相关数据类型及接口】
无。
ot_aenc_attr_aac¶
【说明】
定义AAC编码协议属性结构体。
【定义】
typedef struct {
ot_aac_type aac_type;
ot_aac_bps bit_rate;
ot_audio_sample_rate sample_rate;
ot_audio_bit_width bit_width;
ot_audio_snd_mode snd_mode;
ot_aac_transport_type transport_type;
td_s16 band_width;;
} ot_aenc_attr_aac;
【成员】
|
|
【注意事项】
无。
【相关数据类型及接口】
无。
ot_adec_attr_aac¶
【说明】
定义AAC解码协议属性结构体。
【定义】
typedef struct {
ot_aac_transport_type transport_type;
} ot_adec_attr_aac;
【成员】
|
【注意事项】
无。
【相关数据类型及接口】
无。
错误码¶
音频编码错误码¶
音频编码API错误码如下所示。
表 1 音频编码API错误码
音频解码错误码¶
音频解码API错误码如下所示。
表 1 音频解码API错误码