Speex 编解码组件模块文档
适用 SDK:CI13LC_SDK_NN_ENC
组件路径:components/cias_speex
参考工程:projects/nn_denoise_rtc_sample
1. 组件概述
cias_speex 是一个基于 Speex 1.2rc2 移植的语音编解码组件,提供窄带/宽带语音的压缩与解压能力,用于:
- 上行(编码):把降噪后的 PCM 压缩成固定长度的 Speex 帧,写入本地 Flash 录音或经 UART 发送给主控 MCU;
- 下行(解码):把 UART 收到的 Speex 帧还原成 PCM,送到 codec 播放(对讲/回放场景)。
组件由三部分组成:
| 层次 |
目录 |
说明 |
| 编解码算法库 |
components/cias_speex/libspeex/ |
Speex 官方源码(CELP/LTP/LSP/SB-CELP 等),免修改 |
| 公共头文件 |
components/cias_speex/include/speex/ |
speex.h、speex_bits.h、speex_header.h 等官方 API |
| 平台移植层 |
components/cias_speex/port/ |
ci110x_speex.c/h(封装编码器创建/编码/销毁)、speex_config.h(编译期配置,决定定点/浮点) |
2. 系统架构
┌──────────────────────────── 应用层(projects/nn_denoise_rtc_sample/src)────────────────────────────┐
│ ci_uart_audio_data_handle.c speex_encode_task / speex_decode_task / speex_play_task │
│ ci_flash_record_play_handle.c Flash 录音写入 / 录音回放读取 │
└───────────────────────────────────────┬────────────────────────────────────────────────────────────┘
│
┌──────────────────────────── 业务层(components)──────────────────────────────────────────────┐
│ audio_pre_rslt_iis_out/audio_pre_rslt_out.c 降采样 + 增益 + 推入编码流缓冲 │
│ msg_com/voice_module_uart_protocol.c Speex 帧的 UART 打包/收包(type 0xA4) │
└───────────────────────────────────────┬────────────────────────────────────────────────────────────┘
│
┌──────────────────────────── 组件层(components/cias_speex)─────────────────────────────────────────┐
│ port/ci110x_speex.c ci_speex_encode_create / cias_speex_compressed_data / ci_speex_destroy │
│ libspeex/ speex_encode / speex_decode_int / SpeexBits │
└─────────────────────────────────────────────────────────────────────────────────────────────────────┘
3. 数据结构
3.1 ci_speex_t(句柄)
components/cias_speex/port/ci110x_speex.h
typedef struct _ci_speex_s
{
void * _encoder; // Speex 编码器状态
void * _decoder; // Speex 解码器状态
unsigned int _frame_size; // 每帧样点数
unsigned int _frame_cur; // 分帧残留计数
short * _buffer_in; // 输入缓冲区(short,长度 = _frame_size)
float * _buffer_in_float; // 输入缓冲区(float,长度 = _frame_size)
char * _buffer_out; // 输出缓冲区
SpeexBits _bits; // 比特流上下文
CI_SPEEX_MODE ci_speex_mode; // 输入数据类型标记
} ci_speex_t;
注意:缓冲区大小 必须 与 _frame_size 严格一致,否则会出现”解码后开头数据错误”
3.2 CI_SPEEX_MODE
ci110x_speex.h
typedef enum
{
CI_SPEEX_INT = 0, // 定点/整型输入(本工程使用)
CI_SPEEX_FLOAT = 1, // 浮点输入(当前编码路径未实现)
} CI_SPEEX_MODE;
工程中编码/解码句柄均设为 CI_SPEEX_INT(ci_uart_audio_data_handle.c)。
4. 应用开关(projects/nn_denoise_rtc_sample/src/user_config.h)
#if USE_FLASH_RECORD_PLAY_ENABLE // 由 makefile: CI_RTC_TYPE=0 置 1
#define IF_16K_DOWNSAMPLE_TO_8K 1 // 16k→8k(Speex 窄带/带宽受限场景)
#define USE_UART_SEND_SPEEX_ENABLE 1 // 编码:PCM → Speex
#define USE_UART_RCV_PLAY_SPEEX_ENABLE 1 // 解码:Speex → PCM
#define USE_SPEEX_STORE_LOCAL_ENABLE 1 // 1 = 存本地 Flash 0 = 串口发给另一 MCU
#define UART_SEND_SPEEX_GAIN 0 // 上行软件增益(1~8,0/1 表示不放大)
#endif
| 宏 |
作用 |
关闭影响 |
USE_UART_SEND_SPEEX_ENABLE |
使能编码链路(喂数据 + 编码任务 + send_voice_to_speex_encode) |
不创建编码任务,录音无数据 |
USE_UART_RCV_PLAY_SPEEX_ENABLE |
使能解码链路(收包入队 + 解码任务 + 播放任务) |
无法回放/对讲 |
USE_SPEEX_STORE_LOCAL_ENABLE |
编码结果去向 |
1:Flash 录音;0:UART 上行 |
IF_16K_DOWNSAMPLE_TO_8K |
编码前 16k→8k 抗混叠降采样 |
直接以 16k 数据编码(帧时长减半) |
UART_SEND_SPEEX_GAIN |
上行数据软件增益 |
— |
USE_FLASH_RECORD_PLAY_ENABLE 与 USE_IIS0_OUT_PRE_RSLT_AUDIO、USE_EQ_MODULE 互斥,编译期有 #error 保护(user_config.h)。
6. API 说明
6.1 ci_speex_encode_create
void *ci_speex_encode_create(void);
| 项 |
说明 |
| 功能 |
创建 Speex 编码器 句柄 |
| 参数 |
无 |
| 返回 |
ci_speex_t*,失败返回 NULL |
| 默认行为 |
使用 cias_speex_wb_mode;设置 quality=5、complexity=0;读取 frame_size;分配输入/输出缓冲 |
| 前置条件 |
必须先完成 cias_speex_wb_mode 的字段初始化 |
| 内存 |
ci_speex_t + 编码器状态 + 640 B(out)+ 640 B(in)+ 1280 B(float in) |
6.1.2 ci_speex_decode_create
void *ci_speex_decode_create(void);
| 项 |
说明 |
| 功能 |
创建 Speex 解码器 句柄 |
| 参数 |
无 |
| 返回 |
ci_speex_t*,失败返回 NULL |
| 默认行为 |
使用 cias_speex_wb_mode;设置 quality=5;读取 frame_size;分配缓冲并 speex_bits_init |
| 说明 |
创建后会打印 cias_speex_create, Speex frame size: 320 |
6.1.3 ci_speex_destroy
void ci_speex_destroy(void *handler);
| 项 |
说明 |
| 功能 |
释放编码器状态、输入/输出缓冲、SpeexBits 与句柄本身 |
| 参数 |
handler:ci_speex_encode_create/ci_speex_decode_create 的返回值,可为 NULL |
| 返回 |
无 |
| 限制 |
只销毁 _encoder,不会销毁 _decoder(ci110x_speex.c:172-176);解码器需自行 speex_decoder_destroy() 后再调用本函数 |
6.1.4 cias_speex_compressed_data
int32_t cias_speex_compressed_data(ci_speex_t *_speex, int8_t *data, char *raw_addr);
| 项 |
说明 |
| 功能 |
对 一帧 PCM 编码,输出带 1 字节长度前缀的 Speex 帧 |
| 参数 |
_speex:编码句柄
data:输入 PCM,小端 16 bit,长度必须 = _frame_size * 2 字节(320 样点 = 640 字节)
raw_addr:输出缓冲,≥ 43 字节 |
| 返回 |
写出的字节数(正常恒为 43);句柄/缓冲非法时返回 0 |
| 输出格式 |
raw_addr[0] = 42(payload 长度),raw_addr[1..42] = 比特流 |
| 实现要点 |
内部把 int16 转 float → speex_bits_reset → speex_encode → speex_bits_write |
| 注意 |
该函数未在 ci110x_speex.h 中声明,应用层需自行 extern(ci_uart_audio_data_handle.c 直接调用) |
7. 帧格式与通信协议
7.1 Speex 编码帧(43 字节)
| 偏移 |
长度 |
内容 |
| 0 |
1 |
payload 长度,固定 42(UART_SPEEX_FRAME_LEN - 1) |
| 1 |
42 |
Speex 比特流(speex_bits_write 输出) |
工程强校验:编码长度 != 43 的帧直接丢弃(ci_uart_audio_data_handle.c),以保证 Flash 中数据按 45 字节对齐。
7.2 带 CRC 的存储/传输帧(45 字节)
| 偏移 |
长度 |
内容 |
| 0 |
43 |
上述 Speex 帧 |
| 43 |
2 |
CRC16-CCITT(覆盖前 43 字节,大端 存放) |
- Flash 录音按
WRITE_FLASH_SPEEX_SIZE = 512 字节批量读写(45 的整数倍);
- 本地播报音(Flash 内置语音)走同一解码队列但 不带 CRC,通过
rtc_play_local_flag 跳过校验。
7.3 UART 协议包(components/msg_com/voice_module_uart_protocol.h)
| 字段 |
长度 |
Speex 帧取值 |
header |
2 |
0xFC 0xA5(低字节先发) |
data_length |
2 |
大端,Speex 载荷长度(含 CRC 时为 45) |
msg_type |
1 |
VMUP_MSG_TYPE_SPEEX = 0xA4 |
msg_cmd |
1 |
0x01 上行 / 0x02 下行 |
msg_seq |
1 |
递增序号 |
msg_data |
N |
45 字节 Speex+CRC 帧 |
chksum |
2 |
校验和(Speex 类型为 高字节先发,与其他类型相反) |
tail |
1 |
0xFB |
相关宏:VMUP_MSG_DATA_MAX_SIZE = 46(为容纳 45 字节 Speex 帧由 43 扩展而来)。
8. 配套工具与资源
| 资源 |
路径 |
说明 |
| 音频转 Speex 工具 |
音频转Speex工具V3.0.0.exe |
把 WAV 转为 Speex 帧序列(用于制作本地播报音) |
| 播报音 Speex 源 |
projects/nn_denoise_rtc_sample/firmware/voice/speex/[112]VOX.speex 等 |
[序号]词条 命名的提示音资源,与 voice/src/*.wav 对应 |
9. API 速查表
| API |
头文件 |
用途 |
ci_speex_encode_create(void) |
port/ci110x_speex.h |
创建编码器 |
ci_speex_decode_create(void) |
port/ci110x_speex.h |
创建解码器 |
ci_speex_destroy(void *h) |
port/ci110x_speex.h |
释放句柄(仅编码器状态) |
cias_speex_compressed_data(enc, pcm, out) |
port/ci110x_speex.c |
单帧编码,返回 43 |
speex_test(pcm_addr, raw_addr, size) |
port/ci110x_speex.h |
单帧自测 |
speex_encoder_init / destroy / ctl |
include/speex/speex.h |
编码器生命周期与配置 |
speex_encode(state, float*, bits) |
include/speex/speex.h |
浮点编码一帧 |
speex_decoder_init / destroy / ctl |
include/speex/speex.h |
解码器生命周期与配置 |
speex_decode_int(state, bits, out) |
include/speex/speex.h |
整型解码一帧 |
speex_bits_init / destroy / reset / read_from / write |
include/speex/speex_bits.h |
比特流读写 |
audio_speex_task_init(void) |
src/ci_uart_audio_data_handle.h |
应用层聚合初始化(模式+句柄+任务) |
uart_send_speex_frame(data, len) |
src/ci_uart_audio_data_handle.h |
按 VMUP 协议发送一帧 |