BS2X指导资料
前言¶
BS2XV100通过API（Application Programming Interface）向开发者提供音频编解码的相关接口，包括编码器初始化及销毁接口、命令配置接口、编码一帧接口、解码一帧接口。
与本文档对应的产品版本如下。
本文档主要适用以下工程师：
技术支持工程
软件开发工程师
在本文中可能出现下列标志，它们所代表的含义如下。
|
||
|
||
|
||
概述¶
BS2XV100通过API（Application Programming Interface）面向开发者提供音频编解码功能的开发和应用接口，包括Audio Encoder、Audio Decoder两个部分。
各组件功能说明如下：
Audio Encoder：音频编码器部分，主要提供sbc、msbc、opus、l2hc音频格式的编码功能。
Audio Decoder：音频解码器部分，主要解码Audio Encoder编码出的sbc、msbc、opus、l2hc格式的码流。
说明： 该文档描述各个模块功能的基本流程和API接口描述。
错误码¶
Audio Codec使用错误码指示用户当前任务执行结果，如下表 错误码所示。
表 1 错误码
Audio Encoder¶
概述¶
Audio Encoder主要提供音频编码功能，支持的规格有：
MSBC：16k
SBC：16k、48k
opus：16k、48k
l2hc：16k、48k
数据由MIC（AMIC/DMIC）采集，由PDM模块处理后送至Audio模块，由Audio Encoder进行编码。
开发流程¶
当设备为发送端，需要音频功能时，由Audio Encoder提供音频编码功能。
本章节主要介绍编码涉及数据结构。
1.open param 公共参数，表1中初始化用作传参的结构体。
ha_codec_enc_param {
bool interleaved； /* 解码解交织模式 */
uint32_t channels; /* 声道数 */
int32_t bit_depth; /* 位宽 */
uint32_t sample_rate; /* 采样率 */
uint32_t samples_per_frame; /* 每帧采样点 */
void *private_data； /* 编码器私有参数 */
uint32_t private_data_size; /* 解码器私有参数大小 */
}
2.in_pkt编码器输入buf，表1中作为编码输入的结构体。
ha_codec_enc_in_packet {
int64_tpts; /* 音频同步使用，保留参数，暂不使用 */
uint8_t *data; /* 输入数据指针 */
uint32_t size; /* 输入数据大小 */
}
3.out_pkt编码器输出buf，表1中作为编码输出的结构体。
ha_codec_enc_out_packet {
int32_t *bits_out_buf; /* 编码器输出buffer */
uint32_t bits_out_buf_size; /* 编码器输出buffer大小*/
uint32_t bits_out_bytes; /* 编码数据帧大小，单位Byte */
uint32_t bit_rate; /* 比特率 */
}
4.send_cmd命令字段，表1中cmd命令字。
ACODEC_PRIVATE_PARAM_GET_CMD 0xFFFF100C 获取编解码器私有参数
ACODEC_IN_FRAME_SIZE_GET_CMD 0xFFFF100D 获取编码输入数据大小
ACODEC_OUT_FRAME_SIZE_GET_CMD 0xFFFF100E 获取编码输出数据大小
ACODEC_SET_PLC_OFF_THR_CMD 0xFFFF1010 设置plc最大帧数，仅sbc解码有
ACODEC_GET_PLC_OFF_THR_CMD 0xFFFF1011 获取当前plc最大帧数，仅sbc解码有
Audio Encoder提供的接口如表1所示。
表 1 Audio Encoder接口
|
|||
|
|||
|
|||
BS2X支持多规格编码器，编码器调用接口抽象为overlay_enc_entry，接口返回值解引用后对应元素为编码器实例，实例如表1所示。
Audio Encoder典型开发流程如下。
Server Node：
调用overlay_enc_entry()->init（参数如表1所示），完成编码器初始化。
调用overlay_enc_entry()->get_max_bits_out_size（参数如表1所示），获取编码器所需的输出buffer大小，用于判断当前系统中的预留空间是否满足需求。
调用overlay_enc_entry()->encode_frame参数（参数如表1所示），对输入的数据进行编码，可通过返回值判断是否编码成功，如果返回AUDIO_SUCCESS，则表明编码成功，in_pkt参数的data指针会偏移掉一帧pcm的数据量，in_pkt参数的size大小会减去编码消耗的pcm数据量的大小。编码后输出码流写入out_pkt参数的bits_out_buf指针指向的空间，out_pkt参数的bits_out_bytes变量刷新为编码输出码率的数据量。如果编码接口返回值不为AUDIO_SUCCESS，则可根据“”中的错误码确定失败类型。编码失败，in_pkt中的数据不会消耗。
连续调用overlay_enc_entry()->encode_frame，直至输入buffer数据全部处理，外部不再送数据，编码完成。
调用overlay_enc_entry()->deinit（参数如表1所示），完成编码器销毁。
extern void *overlay_enc_entry(void);
int main()
{
设置open_param参数
overlay_enc_entry()->init/* 初始化 */
overlay_enc_entry()->get_max_bits_out_size /* 获取所需输出buff大小 */
if（buff大小不满足）
overlay_enc_entry()->deinit；/* 销毁编码器 */
while （编码未完成）
overlay_enc_entry()->encode_frame；
if（编码成功）
根据out_buf更新输入数据指针及size；
else
根据错误码处理；
end if
if （编码完成）
break；
overlay_enc_entry()->deinit /* 编码完成，销毁编码器 */
}
注意事项¶
单片仅支持一种规格的编码器，如：若支持sbc编码就不支持其他两种格式的编码。
Audio Decoder¶
概述¶
Audio Decoder主要提供音频解码功能，支持的规格有：
MSBC：16k
SBC：16k、48k
opus：16k、48k
l2hc：16k、48k
开发流程¶
当设备为接收端，需要音频功能时，由Audio Decoder提供音频解码功能。
本章节主要介绍编码涉及数据结构。
1.open param 公共参数，表1中初始化用作传参的结构体。
ha_codec_dec_param {
uint32_t channels; /* 声道数 */
int32_t bit_depth; /* 位宽 */
uint32_t sample_rate; /* 采样率 */
void *private_data； /* 编码器私有参数 */
uint32_t private_data_size; /* 解码器私有参数大小 */
}
2.in_pkt编码器输入buf，表1中作为解码输入的结构体。
ha_codec_dec_in_packet {
int64_t pts; /* 音频同步使用 */
uint8_t *data; /* 输入数据指针，解码完成后更新该指针 */
uint32_t size; /* 输入数据大小 */
bool eos; /* 是否为最后一帧 */
bool pag_loss; /* 是否丢包 */
}
3.out_pkt编码器输出buf，表1中作为解码输出的结构体。
ha_codec_dec_out_packet {
int32_t *pcm_out_buf; /* 解码器输出buffer */
uint32_t pcm_out_buf_size; /* 解码器输出buffer大小*/
int32_t *bits_out_buf; /* 指向透传解码输出指针 */
uint32_t bits_out_buf_size; /* 透传缓冲区大小 */
uint32_t pcm_out_samples; /* 解码pcm输出采样点 */
bool interleaved； /* 解码解交织模式 */
uint32_t bit_per_sample; /* 位宽 */
uint32_t bits_out_bytes; /* 透传输出帧大小 */
uint32_t out_channels; /* 输出声道数 */
uint32_t out_sample_rate; /* 输出采样率 */
uint32_t org_channels; /* 码流原始声道数 */
uint32_t org_sample_rate; /* 原始码流采样率 */
uint32_t bit_rate; /* 码流压缩率 */
ha_codec_out_pts_info; /* pts信息 */
uint32_t frame_index; /* 输出帧序号 */
}
4.send_cmd命令字段，表1中cmd命令字
ACODEC_PRIVATE_PARAM_GET_CMD 0xFFFF100C 获取解码器私有参数
ACODEC_IN_FRAME_SIZE_GET_CMD 0xFFFF100D 获取解码输入数据大小
ACODEC_OUT_FRAME_SIZE_GET_CMD 0xFFFF100E 获取解码输出数据大小
Audio Decoder提供的接口如表1所示。
表 1 Audio Decoder接口
|
|||
|
|||
|
|||
|
|||
BS2X支持多规格解码器，解码器调用接口抽象为overlay_dec_entry，接口返回值解引用后对应元素为解码器实例，实例如表1所示。
Audio Decoder典型的开发流程如下。
Server Node：
调用overlay_dec_entry()->init（参数如表1所示），完成解码器初始化；
调用overlay_dec_entry()->get_max_pcm_out_size（参数如表1所示），获取解码器所需的输出buffer大小，用于判断当前系统中的预留空间是否满足需求；
调用overlay_dec_entry()->decode_frame（参数如表1所示），对输入的数据进行解码，可通过返回值判断是否解码成功，如果返回AUDIO_SUCCESS，则表明解码成功，in_pkt参数的size指针会减少消耗的数据量的大小，例如原始值为1024，消耗68Byte数据，则size的值减少68，in_pkt参数的data指针偏移68Byte。解码生成的pcm数据写入out_pkt参数的pcm_out_buf指针指向的空间，pcm_out_buf_size变量刷新为输出pcm数据的大小。如果编码接口返回值不为AUDIO_SUCCESS，则可根据错误码中的错误码确定失败类型。解码失败，in_pkt中的数据也可能会消耗，可根据in_pkt参数中的size变量值的变化情况判断输入数据的消耗情况；
连续调用overlay_dec_entry()->decode_frame，直至输入buffer数据全部处理，外部不再送数据，解码完成；
调用overlay_dec_entry()->deinit（参数如表1所示），完成解码器销毁
extern void *overlay_dec_entry(void);
int main()
{
设置open_param参数
overlay_dec_entry()->init/* 初始化 */
overlay_dec_entry()->get_max_pcm_out_size /* 获取所需输出buff大小 */
if（buff大小不满足）
overlay_dec_entry()->deinit；/* 销毁解码器 */
while （解码未完成）
overlay_dec_entry()->decode_frame；
if（编码成功）
根据out_buf更新输入数据指针及size；
else
根据错误码处理；
end if
if （解码完成）
break；
overlay_dec_entry()->deinit /* 解码完成，销毁解码器 */
}
注意事项¶
单片仅支持一种规格的解码器，如：若支持sbc解码就不支持其他两种格式的解码。
解码器需要与本产品编码器配对使用。
调试与功能¶
链接脚本路径：drivers\chips\bs2x\board\linker\standard\linker.prelds
通过.plt_ramtext段将代码链接至ITCM上。
如链接libsbc_enc_all_itcm.a，在段中添加*libsbc_enc_all_itcm.a:*.o* (.text .text* .rodata .rodata* .srodata .srodata*)。