跳转至

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 协议发送一帧