音频转 Opus 格式用于 WebRTC

1. 什么是 Opus

Opus 是一种开放、免版税的音频编码格式，由 IETF（互联网工程任务组）标准化（RFC 6716）。它专为互联网上的实时音频传输而设计，是目前 WebRTC 的默认音频编解码器。

Opus 的核心特点：

• 混合编码架构：结合 SILK（针对语音）和 CELT（针对音乐）两种编码器，能根据音频内容自动切换
• 超宽频率范围：支持 6Hz ~ 51.2kHz 的采样率，覆盖人耳可感知的全部范围
• 灵活的码率：支持 6kbps ~ 510kbps，可根据网络带宽动态调整
• 低延迟：帧时长最低 2.5ms，端到端延迟可低至 5ms
• 抗丢包：内置前向纠错（FEC）和丢包隐藏（PLC）机制

2. 为什么 WebRTC 使用 Opus

WebRTC（Web Real-Time Communication）是浏览器原生支持的实时通信协议。Opus 被选为默认音频编解码器的原因：

3. Opus 编码核心概念

3.1 采样率（Sample Rate）

每秒对模拟信号采样的次数，单位 Hz。

WebRTC 中最常用 16000Hz（语音）和 48000Hz（音乐/高清通话）。

3.2 声道数（Channels）

• 单声道（Mono）：1 个声道，语音场景标准配置
• 立体声（Stereo）：2 个声道，音乐或空间音频场景

语音场景使用单声道即可，立体声会使数据量翻倍但对语音清晰度无明显提升。

3.3 采样宽度（Bit Depth）

每个采样点用多少位表示。

• 16bit（2 字节）：CD 音质标准，范围 -32768 ~ 32767
• 8bit：电话音质，动态范围小
• 24bit / 32bit：专业音频，Opus 编码前会量化回 16bit

Opus 编码器的输入固定为 16bit 有符号整数。

3.4 帧时长（Frame Duration）

Opus 将音频切成固定时长的帧逐帧编码。

帧时长越短，延迟越低，但压缩率也越低。 WebRTC 标准推荐 20ms，非实时场景可用 60ms 以获得更高压缩率。

3.5 编码应用场景（Application Mode）

Opus 编码器根据使用场景选择不同的优化策略：

4. PCM 数据与帧切割

4.1 什么是 PCM

PCM（Pulse Code Modulation，脉冲编码调制）是最基本的数字音频表示方式。它将模拟信号按固定采样率采样，每个采样点用固定位数的整数表示。

PCM 数据 = 原始音频，未经任何压缩。

4.2 PCM 数据的内存布局

以 16kHz、单声道、16bit 为例：

字节位置:[0] [1] [2] [3] [4] [5] [6] [7] ...
含义:采样1 采样2 采样3 采样4 ...
 低 高 低 高 低 高 低 高
字节序:小端序（Little-Endian），低字节在前

立体声时采用交错排列：

字节位置:[0] [1] [2] [3] [4] [5] ...
含义:左1右1左2右2左3右3 ...

4.3 帧切割计算

以 16kHz、单声道、16bit、60ms 帧时长为例：

每帧采样点数 = 采样率 / 1000 × 帧时长
 = 16000 / 1000 × 60
 = 960 个采样点

每帧字节数 = 采样点数 × 声道数 × 采样宽度
 = 960 × 1 × 2
 = 1920 字节

一段 5 秒的音频：

总采样点数 = 16000 × 5 = 80000
总字节数 = 80000 × 2 = 160000 字节
总帧数 = 80000 / 960 ≈ 84 帧

4.4 最后一帧的处理

如果音频总长度不是帧大小的整数倍，最后一帧会不足。处理方式是用 0x00 字节填充（等效于添加静音），因为 Opus 编码器要求每帧输入必须是固定长度。

5. 编码流程总结

音频文件（mp3/wav/flac/...）
│
▼
[1] 识别文件格式（扩展名）
│
▼
[2] 使用 ffmpeg + pydub 解码为 PCM
│
▼
[3] 统一参数：单声道 + 16kHz + 16bit
│
▼
[4] 按帧切割 PCM 数据（每帧 1920 字节）
│
▼
[5] 逐帧调用 Opus 编码器
│
▼
[6] 输出 Opus 帧列表
│
├──→ 实时传输：逐帧通过 WebRTC DataChannel 发送
└──→ 文件存储：封装到 Ogg/WebM 容器

6. WebRTC 中的 Opus 使用

6.1 实时通话场景

发送端：麦克风 → PCM → Opus 编码 → RTP 打包 → 网络发送
接收端：网络接收 → RTP 解包 → Opus 解码 → PCM → 扬声器

WebRTC 内部自动处理编码和解码，开发者通常不需要手动操作。但在以下场景需要手动处理：

• 从文件播放音频到 WebRTC 通话中
• 将通话中的音频录制为文件
• 使用自定义音频源（如 TTS 合成语音）

6.2 语音消息场景

用户录制语音 → 编码为 Opus → 上传服务器 → 其他用户下载 → 解码播放。

帧时长可选择 40ms 或 60ms 以提高压缩率，减少存储和传输成本。

6.3 关键参数对比

7. 依赖环境

7.1 ffmpeg

pydub 依赖 ffmpeg 解码 mp3、flac 等压缩格式。

• Windows：从 ffmpeg.org 下载，添加到 PATH
• macOS：brew install ffmpeg
• Linux：apt install ffmpeg 或 yum install ffmpeg

验证安装：

ffmpeg -version

7.2 Python 依赖

pip install pydub opuslib-next numpy

8. 常见问题

Q: 为什么用 16kHz 而不是 48kHz？

16kHz 已能满足语音场景的清晰度需求（覆盖 8kHz 带宽，足够表现人声），同时数据量仅为 48kHz 的 1/3，节省带宽和存储。48kHz 更适合音乐或高保真场景。

Q: 帧时长选多少合适？

• 实时通话：20ms（WebRTC 标准，延迟和压缩率平衡）
• 语音消息：40~60ms（非实时，追求更高压缩率）
• 超低延迟：2.5~10ms（游戏语音等）

Q: Opus 和 AAC、MP3 有什么区别？

Opus 是为实时传输设计的，延迟极低（最低 2.5ms），而 AAC 编码延迟通常 >20ms，MP3 更高（>26ms）。Opus 还内置抗丢包机制，适合网络不稳定的场景。MP3/AAC 更适合离线文件存储。

Q: 填充静音会影响音质吗？

不会。最后一帧不足的部分通常是音频末尾的极短片段（< 60ms），填充的静音在播放时表现为音频末尾多了不到 60ms 的静音，人耳无法察觉。

9. C 语言中使用 Opus（libopus）

Python 适合快速原型开发，但在性能敏感的场景（嵌入式设备、实时音频处理、游戏引擎等）中，直接使用 C 语言调用 libopus 是更优的选择。libopus 是 Opus 官方提供的 C 实现，也是所有其他语言绑定（Python、Go、Rust 等）的底层基础。

9.1 libopus 简介

libopus 是 Opus 编解码器的参考实现，由 Xiph.Org 基金会维护。

• 开源协议：BSD 许可证，可自由用于商业项目
• 仓库地址：https://github.com/xiph/opus
• 核心功能：提供 Opus 编码和解码的完整 C API
• 性能特点：高度优化的 C 代码，支持 SIMD 指令集加速

libopus 只负责编解码，不负责：

• 文件读写（需要自行处理或使用 libopusenc/libopusfile）
• 容器封装（Ogg/WebM 容器需要额外库）
• 网络传输（需要自行实现或结合 WebRTC 库）

9.2 各平台安装

Linux（Debian/Ubuntu）

# 安装开发库sudo apt install libopus-dev# 安装后可使用的文件：# 头文件：/usr/include/opus/opus.h# 库文件：/usr/lib/x86_64-linux-gnu/libopus.so

Linux（CentOS/RHEL/Fedora）

sudo yum install opus-devel# 或sudo dnf install opus-devel

macOS

brew install opus# 安装后头文件位置：# /opt/homebrew/include/opus/opus.h# 库文件位置：# /opt/homebrew/lib/libopus.dylib

Windows

方式一：使用 vcpkg（推荐）

vcpkg install opus:x64-windows

方式二：手动编译

1. 从 https://opus-codec.org/downloads/ 下载源码
2. 使用 CMake 或 Visual Studio 编译
3. 将生成的 opus.lib 和 opus.dll 配置到项目中

方式三：使用 MSYS2

pacman -S mingw-w64-x86_64-opus

验证安装

# Linux/macOS：检查头文件是否存在ls /usr/include/opus/opus.h# 或pkg-config --cflags --libs opus

9.3 核心 API 详解

libopus 的 API 设计简洁，核心函数只有以下几个：

opus_encoder_create — 创建编码器

OpusEncoder *opus_encoder_create(
opus_int32 Fs,// 采样率：8000, 12000, 16000, 24000, 48000int channels, // 声道数：1（单声道）或 2（立体声）int application,// 应用场景：OPUS_APPLICATION_VOIP / AUDIO / RESTRICTED_LOWDELAYint *error// 输出参数，返回错误码（OPUS_OK 表示成功）);

返回值：成功返回 OpusEncoder*，失败返回 NULL（此时 *error 包含错误原因）。

opus_encode — 编码一帧（int16 输入）

opus_int32 opus_encode(
OpusEncoder *st,// 编码器状态const opus_int16 *pcm,// PCM 输入数据（int16 有符号整数）int frame_size, // 每声道的采样点数（不是字节数）unsigned char *data,// 输出缓冲区，存放编码后的 Opus 数据opus_int32 max_data_bytes // 输出缓冲区最大字节数);

返回值：> 0 表示编码成功，返回写入的字节数；< 0 表示失败（返回错误码）。

frame_size 的合法值取决于采样率：

对应关系：

opus_encode_float — 编码一帧（float 输入）

opus_int32 opus_encode_float(
OpusEncoder *st,const float *pcm, // PCM 输入数据（float，范围 -1.0 ~ 1.0）int frame_size,unsigned char *data,
opus_int32 max_data_bytes
);

与 opus_encode 功能相同，区别在于输入数据类型。float 版本适合与音频处理库（如 PortAudio、JUCE）对接，这些库通常使用 float 格式。

opus_encoder_ctl — 动态调整编码参数

// 设置码率opus_encoder_ctl(enc, OPUS_SET_BITRATE(32000));// 设置复杂度（0~10，10 最高但最慢）opus_encoder_ctl(enc, OPUS_SET_COMPLEXITY(10));// 设置信号类型（语音/音乐/未知）opus_encoder_ctl(enc, OPUS_SET_SIGNAL(OPUS_SIGNAL_VOICE));// 设置带宽限制opus_encoder_ctl(enc, OPUS_SET_MAX_BANDWIDTH(OPUS_BANDWIDTH_WIDEBAND));// 启用/禁用 VBRopus_encoder_ctl(enc, OPUS_SET_VBR(1));// 启用 DTX（静音检测传输，静音时降低码率）opus_encoder_ctl(enc, OPUS_SET_DTX(1));// 读取当前码率opus_int32 current_bitrate;
opus_encoder_ctl(enc, OPUS_GET_BITRATE(&current_bitrate));

opus_encoder_destroy — 销毁编码器

void opus_encoder_destroy(OpusEncoder *st);

释放编码器占用的所有资源。编码器不再使用时必须调用，否则会内存泄漏。

9.4 完整编码示例

以下示例将一个原始 PCM 文件编码为 Opus 帧数据并写入文件：

/*
 * opus_encode_example.c
 * 将 16bit 小端序 PCM 文件编码为 Opus 帧序列
 *
 * 编译命令：
 * Linux/macOS: gcc -o opus_encode_example opus_encode_example.c -lopus
 * Windows: gcc -o opus_encode_example opus_encode_example.c -lopus -lm
 */#include <stdio.h>#include <stdlib.h>#include <string.h>#include <opus.h>/* ============ 编码参数 ============ */#define SAMPLE_RATE 16000 /* 采样率 16kHz */#define CHANNELS1 /* 单声道 */#define APPLICATION OPUS_APPLICATION_AUDIO/* 应用场景：音频优化 */#define FRAME_DURATION60/* 帧时长 60ms */#define BITRATE 32000 /* 目标码率 32kbps */#define COMPLEXITY10/* 编码复杂度 0~10 *//* ============ 计算 derived 常量 ============ *//* 每帧采样点数 = 采样率 * 帧时长 / 1000 */#define FRAME_SIZE(SAMPLE_RATE * FRAME_DURATION / 1000)/* 16000 * 60 / 1000 = 960 *//* 每帧 PCM 字节数 = 采样点数 * 声道数 * 2字节(16bit) */#define FRAME_BYTES (FRAME_SIZE * CHANNELS * 2)/* 960 * 1 * 2 = 1920 *//* Opus 输出缓冲区大小（官方建议最大 4000 字节） */#define MAX_PACKET_SIZE 4000int main(int argc, char *argv[]){/* ---------- 1. 参数检查 ---------- */if (argc != 3) {fprintf(stderr, "用法: %s <输入.pcm> <输出.opus>
", argv[0]);fprintf(stderr, "输入文件必须是 16bit 小端序有符号 PCM 格式
");fprintf(stderr, "
生成测试 PCM 文件的方法：
");fprintf(stderr, "ffmpeg -i input.wav -f s16le -acodec pcm_s16le -ar 16000 -ac 1 output.pcm
");return EXIT_FAILURE;
}const char *input_path= argv[1];const char *output_path = argv[2];/* ---------- 2. 打开文件 ---------- */FILE *fin = fopen(input_path, "rb");if (!fin) {fprintf(stderr, "错误: 无法打开输入文件 %s
", input_path);return EXIT_FAILURE;
}

FILE *fout = fopen(output_path, "wb");if (!fout) {fprintf(stderr, "错误: 无法打开输出文件 %s
", output_path);
fclose(fin);return EXIT_FAILURE;
}/* ---------- 3. 创建 Opus 编码器 ---------- */int error;
OpusEncoder *encoder = opus_encoder_create(
SAMPLE_RATE,/* 16000 Hz */CHANNELS, /* 1（单声道） */APPLICATION,/* OPUS_APPLICATION_AUDIO */&error/* 错误码输出 */);if (error != OPUS_OK || encoder == NULL) {fprintf(stderr, "错误: 创建编码器失败: %s
", opus_strerror(error));
fclose(fin);
fclose(fout);return EXIT_FAILURE;
}/* ---------- 4. 配置编码器参数 ---------- *//* 设置目标码率 */error = opus_encoder_ctl(encoder, OPUS_SET_BITRATE(BITRATE));if (error != OPUS_OK) {fprintf(stderr, "警告: 设置码率失败: %s
", opus_strerror(error));
}/* 设置编码复杂度（10 为最高质量，CPU 消耗也最大） */error = opus_encoder_ctl(encoder, OPUS_SET_COMPLEXITY(COMPLEXITY));if (error != OPUS_OK) {fprintf(stderr, "警告: 设置复杂度失败: %s
", opus_strerror(error));
}/* 设置信号类型为语音（Opus 会针对语音内容优化） */error = opus_encoder_ctl(encoder, OPUS_SET_SIGNAL(OPUS_SIGNAL_VOICE));if (error != OPUS_OK) {fprintf(stderr, "警告: 设置信号类型失败: %s
", opus_strerror(error));
}/* 启用 VBR（可变码率），在保证质量的前提下节省带宽 */error = opus_encoder_ctl(encoder, OPUS_SET_VBR(1));if (error != OPUS_OK) {fprintf(stderr, "警告: 设置 VBR 失败: %s
", opus_strerror(error));
}printf("编码器配置完成:
");printf("采样率: %d Hz
", SAMPLE_RATE);printf("声道数: %d
", CHANNELS);printf("帧时长: %d ms
", FRAME_DURATION);printf("每帧采样点: %d
", FRAME_SIZE);printf("每帧字节数: %d
", FRAME_BYTES);printf("目标码率: %d bps
", BITRATE);printf("复杂度: %d
", COMPLEXITY);/* ---------- 5. 逐帧编码 ---------- */opus_int16 pcm_buffer[FRAME_SIZE * CHANNELS];/* PCM 输入缓冲区 */unsigned char opus_buffer[MAX_PACKET_SIZE]; /* Opus 输出缓冲区 */int frame_count = 0;int total_bytes = 0;while (1) {/* 从文件读取一帧 PCM 数据 */size_t read_count = fread(
pcm_buffer,sizeof(opus_int16), /* 每个采样 2 字节 */FRAME_SIZE * CHANNELS,/* 要读取的采样点总数 */fin
);/* 文件读完或出错 */if (read_count == 0) {break;
}/* 如果读取的数据不足一帧，用 0（静音）填充剩余部分 */if (read_count < (size_t)(FRAME_SIZE * CHANNELS)) {memset(
(unsigned char *)pcm_buffer + read_count * sizeof(opus_int16),0,
(FRAME_SIZE * CHANNELS - read_count) * sizeof(opus_int16)
);
}/* 调用 Opus 编码器编码一帧 */int nbBytes = opus_encode(
encoder,/* 编码器状态 */pcm_buffer, /* PCM 输入数据 */FRAME_SIZE, /* 每声道采样点数 */opus_buffer,/* 输出缓冲区 */MAX_PACKET_SIZE /* 输出缓冲区最大字节数 */);/* 检查编码是否成功 */if (nbBytes < 0) {fprintf(stderr, "错误: 编码失败: %s
", opus_strerror(nbBytes));break;
}/* 将编码后的帧写入输出文件 *//* 格式：先写 4 字节的帧长度（小端序），再写帧数据 *//* 这种格式方便后续读取时逐帧解析 */uint32_t frame_len = (uint32_t)nbBytes;
fwrite(&frame_len, sizeof(uint32_t), 1, fout);
fwrite(opus_buffer, 1, nbBytes, fout);

frame_count++;
total_bytes += nbBytes;
}/* ---------- 6. 输出统计信息 ---------- */printf("
编码完成:
");printf("总帧数: %d
", frame_count);printf("Opus 总字节数: %d
", total_bytes);if (frame_count > 0) {double duration_sec = (double)frame_count * FRAME_DURATION / 1000.0;double avg_bitrate = (double)total_bytes * 8.0 / duration_sec / 1000.0;printf("音频时长: %.2f 秒
", duration_sec);printf("平均码率: %.2f kbps
", avg_bitrate);double compression_ratio = (double)total_bytes / (double)(frame_count * FRAME_BYTES) * 100.0;printf("压缩率: %.1f%%
", compression_ratio);
}/* ---------- 7. 清理资源 ---------- */opus_encoder_destroy(encoder);
fclose(fin);
fclose(fout);return EXIT_SUCCESS;
}

9.5 编译与运行

Linux / macOS

# 编译gcc -o opus_encode_example opus_encode_example.c -lopus# 准备测试音频（将任意音频转为 16kHz 单声道 16bit PCM）ffmpeg -i test.wav -f s16le -acodec pcm_s16le -ar 16000 -ac 1 test.pcm# 运行./opus_encode_example test.pcm test.opus

Windows（MinGW）

gcc -o opus_encode_example opus_encode_example.c -lopus -I"C:path	oopusinclude" -L"C:path	oopuslib"

CMake 项目

cmake_minimum_required(VERSION 3.10)project(opus_encode_example C)# 查找 libopusfind_package(PkgConfig)
pkg_check_modules(OPUS REQUIRED opus)add_executable(opus_encode_example opus_encode_example.c)target_include_directories(opus_encode_example PRIVATE ${OPUS_INCLUDE_DIRS})target_link_libraries(opus_encode_example ${OPUS_LIBRARIES})

9.6 Python 与 C 的 API 对应关系

9.7 libopus 进阶用法

9.7.1 编码浮点 PCM

如果音频数据是 float 格式（范围 -1.0 ~ 1.0），使用 opus_encode_float：

float pcm_float[960];/* float PCM 数据 */unsigned char packet[4000];int nbBytes = opus_encode_float(
encoder,
pcm_float,/* float 类型输入 */960,/* 采样点数 */packet,4000);

9.7.2 静音检测（DTX）

DTX（Discontinuous Transmission）在检测到静音时自动降低码率：

/* 启用 DTX */opus_encoder_ctl(encoder, OPUS_SET_DTX(1));/* 同时启用 VBR 才能发挥 DTX 的效果 */opus_encoder_ctl(encoder, OPUS_SET_VBR(1));

静音帧通常只有 1~2 字节，大幅节省带宽。适用于通话中长时间静音的场景。

9.7.3 前向纠错（FEC）

FEC（Forward Error Correction）在当前帧中包含下一帧的冗余信息，接收端可以在丢帧时恢复：

/* 发送端：启用 in-band FEC */opus_encoder_ctl(encoder, OPUS_SET_INBAND_FEC(1));/* 接收端解码时启用 FEC 恢复 */opus_int32 lost_flag = 1;/* 1 表示当前帧丢失 */opus_decode(decoder, NULL, 0, pcm_out, 960, lost_flag);

9.7.4 多声道编码

立体声编码：

OpusEncoder *enc = opus_encoder_create(48000, 2, OPUS_APPLICATION_AUDIO, &err);/* PCM 数据交错排列：左1, 右1, 左2, 右2, ... */opus_int16 pcm_stereo[960 * 2];/* 960 采样点 * 2 声道 */int nbBytes = opus_encode(enc, pcm_stereo, 960, packet, 4000);

9.7.5 写入 Ogg/Opus 文件

libopus 只输出裸的 Opus 帧，如果需要生成可播放的 .opus 文件，需要使用 libopusenc 封装到 Ogg 容器中：

# 安装sudo apt install libopusenc-dev # Linuxbrew install libopusenc# macOS

#include <opusenc.h>int error;
OggOpusEnc *enc = ope_encoder_create_file("output.opus",/* 输出文件路径 */NULL, /* 默认注释 */48000,/* 采样率 */1,/* 声道数 */0,/* family（0=Vorbis mapping） */&error/* 错误码 */);/* 写入 PCM 数据（float 格式） */ope_encoder_write_float(enc, float_pcm_array, frame_count_per_channel);/* 刷新缓冲区并关闭 */ope_encoder_drain(enc);
ope_encoder_destroy(enc);

编译时需要链接 libopusenc：

gcc -o example example.c -lopus -lopusenc

9.8 libopus 解码 API

虽然本文重点是编码，但解码 API 同样重要，用于接收端还原音频：

/* 创建解码器 */OpusDecoder *decoder = opus_decoder_create(16000, 1, &error);/* 解码一帧 */opus_int16 pcm_out[960];int frame_size = opus_decode(
decoder,/* 解码器状态 */opus_packet,/* Opus 压缩数据 */packet_size,/* 数据字节数 */pcm_out,/* 输出 PCM 缓冲区 */960,/* 最大输出采样点数 */0 /* 0=正常解码，1=丢帧时用 FEC 恢复 */);/* 销毁解码器 */opus_decoder_destroy(decoder);

9.9 常见错误码

使用 opus_strerror(error_code) 可将错误码转为可读文本。

9.10 Python 与 C 的选择建议

建议：

• 快速验证逻辑 → 用 Python
• 性能敏感的生产环境 → 用 C
• WebRTC 前端（浏览器）→ 无需手动编码，浏览器自动处理
• WebRTC 后端（C/C++ 服务）→ 直接使用 libopus