前言

概述

BS2XV100通过API（Application Programming Interface）向开发者提供音频编解码的相关接口，包括编码器初始化及销毁接口、命令配置接口、编码一帧接口、解码一帧接口。

产品版本

与本文档对应的产品版本如下。

产品名称	产品版本
BS2X	V100

读者对象

本文档主要适用以下工程师：

• 技术支持工程

• 软件开发工程师

符号约定

在本文中可能出现下列标志，它们所代表的含义如下。

符号	说明
	表示如不避免则将会导致死亡或严重伤害的具有高等级风险的危害。
	表示如不避免则可能导致死亡或严重伤害的具有中等级风险的危害。
	表示如不避免则可能导致轻微或中度伤害的具有低等级风险的危害。
	用于传递设备或环境安全警示信息。如不避免则可能会导致设备损坏、数据丢失、设备性能降低或其它不可预知的结果。 “须知”不涉及人身伤害。
	对正文中重点信息的补充说明。 “说明”不是安全警示信息，不涉及人身、设备及环境伤害信息。

修改记录

文档版本	发布日期	修改说明
03	2025-05-30	新增“Audio Encoder”的“开发流程”小节内容。 更新“Audio Decoder”的“开发流程”小节内容。
02	2024-07-04	更新“概述”小节内容。 新增“Audio Encoder”的“开发流程”小节内容。 更新“Audio Decoder”的“开发流程”小节内容。 新增“调试与功能”小节内容。
01	2024-05-15	第一次正式版本发布。
00B02	2024-01-17	更新“Audio Decoder”的“开发流程”小节内容。 新增“调试与功能”章节内容。
00B01	2024-01-08	第一次临时版本发布。

概述

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 错误码

序号	定义	实际数值	描述
1	AUDIO_SUCCESS	0	执行成功错误码。
2	ERR_HACODEC_INVALID_PARAM	0x80005320	非法参数错误码。
3	ERR_HACODEC_INVALID_SAMPLERATE	0x80005321	非法采样率错误码。
5	ERR_HACODEC_INVALID_BITDEPTH	0x80005322	非法位宽错误码。
6	ERR_HACODEC_INVALID_CHANNEL	0x80005323	非法声道数错误码。
7	ERR_HACODEC_NULL_PTR	0x80005324	传入空指针错误码。
8	ERR_HACODEC_STREAM_CORRUPT	0x80005325	流损坏错误码。
9	ERR_HACODEC_NOT_ENOUGH_DATA	0x80005326	输入数据不足错误码。
10	ERR_HACODEC_NOT_SUPPORT	0x80005327	系统不支持错误码。
11	ERR_HACODEC_INIT_FAILED	0x80005328	初始化失败错误码。
12	ERR_HACODEC_ENCODE_FAILED	0x80005329	编码失败错误码。
13	ERR_HACODEC_DECODE_FAILED	0x8000532a	解码失败错误码。
14	ERR_HACODEC_WRONG_HEADER	0x8000532b	帧头错误错误码。
15	ERR_HACODEC_ALLOC_MEM_FAILED	0x8000532c	内存申请失败错误码。
16	ERR_HACODEC_MEM_COPY_FAILED	0x8000532d	内存拷贝失败错误码。
17	ERR_HACODEC_NOT_ENOUGH_OUT_BUFFER_SIZE	0x8000532e	输出buffer空间不足错误码。
18	ERR_HACODEC_NOT_ENOUGH_SCRATCH_BUFFER_SIZE	0x8000532f	暂存缓冲区空间不足错误码。
19	ERR_HACODEC_READ_FIFO_NOT_ENOUGH_DATA	0x80005330	FIFO中无足够数据错误码
20	ERR_HACODEC_WRITE_FIFO_OVERFLOW	0x80005331	写FIFO溢出错误码

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接口

接口名称	描述	参数说明	返回信息说明
name	获取编码器名称	-	char
codec_id	获取编码器id	-	enum
version.version	获取版本号	-	int
description	获取描述	-	char
init	编码器初始化	encoder：二维指针，指向编码器实例的地址 open_param：公共参数，如编码器的采样率、位宽、声道数等	错误码。
deinit	编码器去初始化，释放编码使用的内存空间	encoder：编码器实例地址	错误码。
send_cmd	cmd接口，可获取输入输出所需数据大小	encoder：编码器实例地址 cmd：cmd命令字 arg：接收返回值	错误码。
get_max_bits_out_size	获取最大输出大小	encoder：编码器实例地址 out_sizes：接收输出大小size	错误码。
encode_frame	编码接口	encoder：编码器实例地址 in_pkt：输入数据（编码前数据）buffer out_pkt：输出数据（编码后数据）buffer	错误码。
overlay_enc_entry	封装上述编码器接	-	NULL

开发流程

BS2X支持多规格编码器，编码器调用接口抽象为overlay_enc_entry，接口返回值解引用后对应元素为编码器实例，实例如表1所示。

Audio Encoder典型开发流程如下。

Server Node：

1. 调用overlay_enc_entry()->init（参数如表1所示），完成编码器初始化。

2. 调用overlay_enc_entry()->get_max_bits_out_size（参数如表1所示），获取编码器所需的输出buffer大小，用于判断当前系统中的预留空间是否满足需求。

3. 调用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中的数据不会消耗。

4. 连续调用overlay_enc_entry()->encode_frame，直至输入buffer数据全部处理，外部不再送数据，编码完成。

5. 调用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接口

接口名称	描述	参数说明	返回信息说明
name	获取解码器名称	-	char
codec_id	获取解码器id	-	enum
version.version	获取版本号	-	int
description	获取描述	-	char
init	解码器初始化	decoder：二维指针，指向解码器实例的地址 open_param：公共参数，如解码器的采样率、位宽、声道数等	错误码
deinit	解码器去初始化，释放解码使用的内存空间	decoder：解码器实例地址	错误码
send_cmd	cmd接口，可获取输入输出所需数据大小	decoder：解码器实例地址 cmd：cmd命令字 arg：接收返回值	错误码
get_max_pcm_out_size	获取最大输出大小	decoder：解码器实例地址 out_sizes：接收输出大小size	错误码
decode_frame	解码接口	decoder：解码器实例地址 in_pkt：输入数据（解码前数据）buffer out_pkt：输出数据（解码后数据）buffer	错误码
overlay_dec_entry	封装上述编码器接口	-	-

开发流程

BS2X支持多规格解码器，解码器调用接口抽象为overlay_dec_entry，接口返回值解引用后对应元素为解码器实例，实例如表1所示。

Audio Decoder典型的开发流程如下。

Server Node：

1. 调用overlay_dec_entry()->init（参数如表1所示），完成解码器初始化；

2. 调用overlay_dec_entry()->get_max_pcm_out_size（参数如表1所示），获取解码器所需的输出buffer大小，用于判断当前系统中的预留空间是否满足需求；

3. 调用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变量值的变化情况判断输入数据的消耗情况；

4. 连续调用overlay_dec_entry()->decode_frame，直至输入buffer数据全部处理，外部不再送数据，解码完成；

5. 调用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解码就不支持其他两种格式的解码。

• 解码器需要与本产品编码器配对使用。

调试与功能

ITCM链接

链接脚本路径：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*)。

性能数据表

CODEC	类型	帧长	采样率	算力	ITCM	动态空间	码率
sbc	编码	8ms	16kHz	5Mcps	10k Byte	1.93kByte	68kbps
		2.67ms	48kHz	10.2Mcps	10k Byte	1.93k Byte	126kbps
		2.67ms	48kHz	10.5Mcps	10k Byte	1.93k Byte	204kbps
		2.67ms	48kHz	10.8Mcps	10k Byte	1.93k Byte	258kbps
	解码	8ms	16kHz	4Mcps	13k Byte	1.14k Byte	68kbps
		2.67ms	48kHz	8.5Mcps	13k Byte	1.14k Byte	126kbps
		2.67ms	48kHz	8.7Mcps	13k Byte	1.14k Byte	204kbps
		2.67ms	48kHz	8.9Mcps	13k Byte	1.14k Byte	258kbps
msbc	编码	7.5ms	16kHz	5Mcps	10k Byte	1.93k Byte	64kbps
	解码	7.5ms	16kHz	4Mcps	13k Byte	1.14k Byte	64kbps
l2hc	编码	10ms	16kHz	35Mcps	30k Byte	7k Byte	64kbps
		10ms	48kHz	37.5Mcps	30k Byte	7k Byte	64kbps
		5ms	48kHz	47Mcps	30k Byte	7k Byte	96kbps
	解码	10ms	16kHz	13.6Mcps	30k Byte	3.7k Byte	64kbps
		10ms	48kHz	24Mcps	30k Byte	10k Byte	64kbps
		5ms	48kHz	29Mcps	30k Byte	10k Byte	96kbps
opus	编码	10ms	16kHz	36Mcps	28k Byte	7.1k Byte	64kbps
		10ms	48kHz	52Mcps	28k Byte	7.1k Byte	64kbps
		5ms	16kHz	41Mcps	28k Byte	7.1k Byte	64kbps
		5ms	48kHz	55Mcps	30k Byte	7.1k Byte	64kbps
		2.5ms	48kHz	45Mcps	30k Byte	7.1k Byte	64kbps
	解码	10ms	16kHz	21.5Mcps	30k Byte	9.1k Byte	64kbps
		10ms	48kHz	25Mcps	30k Byte	9.1k Byte	64kbps
		5ms	16kHz	25.3Mcps	30k Byte	9.1k Byte	64kbps
		5ms	48kHz	30Mcps	30k Byte	9.1k Byte	64kbps
		2.5ms	48kHz	30.2Mcps	30k Byte	9.1k Byte	64kbps