纯 Zig 的流式音频解码库:不依赖 C、不依赖系统解码器、无全局状态、可 fuzz。
一句话定位:当 Zig 应用想在不依赖 C、不依赖系统、流式、可 fuzz 的前提下解码几种常见音频格式时,它应该是第一个被想到的库。
状态:WAV(PCM / IEEE float / EXTENSIBLE)完整支持,另加 G.711 µ-law/A-law、IMA ADPCM、Microsoft ADPCM;AIFF(大端 PCM 8/16/24/32)支持;FLAC 子帧集合完整支持:CONSTANT / VERBATIM / FIXED(0–4) / LPC(1–32 阶) + Rice 分区、wasted bits、independent 声道,以及 left/side、right/side、mid/side 三种声道去相关。官方 13 个测试向量全部整文件解码,与 ffmpeg 逐样本
max_diff 0。MP3(MPEG-1 Layer III)支持单声道 + 立体声 + 联合立体声(mid/side、intensity):八个测试向量(32/44.1/48 kHz,CBR 与 VBR,含 40.9 秒真实音乐)整文件对 ffmpeg 的 f32 输出 SNR 118.9–124.0 dB、逐 granule 最大绝对差 < 2e-6,s16 最大 1 LSB,含 short/start/stop 窗口切换与逐帧开关的 joint stereo,见下文。Ogg Vorbis 完整解码:容器、三个头包、floor 1 / residue 0-1-2 / 逆耦合 / IMDCT / 重叠相加,两个测试向量整文件对 ffmpeg 的 f32 输出 SNR 131.9–133.4 dB(最大差 < 8e-8)、s16 SNR 98.8–101.0 dB(最大 1 LSB),样本数与 granule 完全一致。Ogg Opus 现在是「容器 + CELT + SILK + Hybrid 解码」:OpusHead/OpusTags/ 每个包的 TOC 帧结构 / 时长全部可读,且 CELT 层(configuration 16–31)真的出 PCM——粗/细能量、比特分配、PVQ、anti-collapse、立体声 theta、IMDCT、重叠相加、音高后滤波、去加重全部实现,三个纯 CELT 测试向量整文件对 ffmpeg-f f32le的 SNR 为 140.7 / 140.4 / 141.9 dB(s16 SNR 102.6–105.3 dB,最大 1 LSB),样本数与granule − pre-skip完全一致。SILK 层(configuration 0–11)也真的出 PCM:VAD/LBRR、增益、LSF→LPC、音高/LTP、shell 激励、再白化、LPC 合成,以及 SILK 特有的 8/12/16→48 kHz 重采样全部实现,纯 SILK 测试向量整文件对 ffmpeg-f f32le的 SNR 为 145.3 dB(s16 107.3 dB,最大 1 LSB),样本数与granule − pre-skip完全一致。Hybrid(configuration 12–15)也真的出 PCM:SILK 低频带与 CELT 高频带在同一帧上分别解码、在时域相加,两个混合素材(9 / 10 个 Hybrid 包,夹在 SILK 与 CELT 包之间)整文件对 ffmpeg-f f32le的 SNR 为 141.9 / 145.4 dB(s16 105.9 / 106.1 dB,最大 1 LSB),样本数与granule − pre-skip完全一致;立体声 SILK / Hybrid 也已打通,整文件 SNR 144.8 / 139.1 dB(s16 106.8 / 103.8 dB,最大 1 LSB)。floor 0 未支持。
| 能力 | 状态 | 说明 |
|---|---|---|
| 入口 | ✅ | open / openBytes / openFile:*std.Io.Reader、内存切片、std.Io.File 三个便利入口,错误契约相同 |
| STREAMINFO(块大小、采样率、声道、位深、total samples、MD5) | ✅ | total_samples == 0 → Info.total_frames = null |
| 其它元数据块(padding / seektable / Vorbis comment…) | ✅ | 按长度跳过,遇 last-metadata-block 停止 |
| 帧头(同步码、blocking strategy、8/16 位块大小扩展、采样率编码、声道分配、位深编码) | ✅ | 帧头 CRC-8 校验 |
| 帧尾 CRC-16 | ✅ | 覆盖整帧(含帧头),不一致 → error.Corrupt |
| CONSTANT / VERBATIM 子帧 | ✅ | |
| FIXED 0–4 阶 + Rice 分区 | ✅ | 4/5 位参数、partition order、escape code(未压缩分区)、wasted bits |
| LPC 1–32 阶 | ✅ | qlp 系数精度 1–15 位(存储字段 0–14,0b1111 禁止);5 位有符号 shift(负值按左移解码);预测在 i64 中累加,不按 bps 截断 |
| independent 声道(1–8) | ✅ | 声道顺序原样保留,不混音 |
| left/side、right/side、mid/side | ✅ | side 子帧比源位深多 1 位(right/side 的 side 在第一个子帧);mid/side 用 side 的最低位恢复 mid 丢掉的奇偶位;去相关在 wasted bits 展开之后做 |
LPC 预测语义(RFC 9639 §9.2.6、附录 A.3/A.4):prediction = (Σ coeff[i] × sample[n-1-i]) >> shift,其中 Σ 在 i64 中累加(最坏情况约 33 + 15 + 5 = 53 位),预测值不按子帧位深截断——它可能远大于 16 位样本范围,要等加上残差后才落回样本范围;提前截断高位会得到"听起来正常但样本错误"的输出。shift 为负时按历史语义左移;规范要求编码器不得写负值,解码端接受它并做了溢出检查。最终样本 + 残差用带溢出检查的加法写入 i32,任何越界都返回 error.Corrupt,绝不回绕。
内存:open*() 按 STREAMINFO 的 max block size 分配一帧的 i32 缓冲(常见 4096×2×4 = 32 KiB,上限 65535×8×4 = 2 MiB),read() 之后不再分配;deinit() 释放。openFile*() 另加一块 64 KiB 的文件读缓冲。
官方测试向量:13 个 ietf-wg-cellar/flac-test-files 文件全部整文件解码,并与 ffmpeg 逐样本 max_diff 0。这批文件覆盖 LPC 阶数(subset 范围内)与 qlp 精度 2/15、wasted 1–12、8/12/16 位、1/3/6 声道、三种去相关、总样本数未知(total_frames = null)与 escape-code 分区。测试分两层:
- 官方向量:元数据必须完全正确,整文件样本数等于声明值(
45例外,按实际解码数),并与 ffmpeg 逐样本一致;60的 50% 截断必须返回error.Truncated; - 位深转换、FIXED 0–4 阶、LPC 1–32 阶、qlp precision 1/2/15、负 shift、32 位以上预测和、Rice 分区、escape code、wasted bits 与三种去相关声道由
src/flac_build.zig构造的合成流覆盖(src/flac_lpc_test.zig),并与 ffmpeg 的解码结果对齐。
61 - predictor overflow check 的预测值达到 860128(远超 16 位样本范围),而累加和最大约 8.8×10⁸;它检验的是"预测值不能按 bps 截断",不是 32 位累加和溢出。真正超过 32 位的累加和由合成用例覆盖:Σ = 32 × 16383 × 32767 = 17178296352(约为 2³⁴、i32 上限的 8 倍),i32 回绕会预测出 −48 而不是 524240。
已实现:帧同步与头解析、ID3v2/ID3v1/APE/Lyrics3 跳过、Xing/Info + LAME delay/padding、
MPEG-1 单声道与立体声 side info(每 granule 4 个 channel 块)、跨帧 bit reservoir、
ISO Table B.7 的 32 张 Huffman 表(表 0–31,含 linbits 与 count1 A/B)、scalefactors、
反量化、joint stereo(mid/side 与 intensity,含 is_pos 0–7)、short block 重排、抗混叠、
18/12 点 IMDCT、频率反转、32 子带多相合成(每声道一条),以及 gapless 裁剪
(delay + 529 样点滤波器延迟)。
| 能力 | 状态 |
|---|---|
| MPEG-1 Layer III / 单声道 | ✅ |
MPEG-1 Layer III / 立体声(mode 00/10,两声道独立) |
✅ |
MPEG-1 Layer III / 联合立体声(mode 01):mid/side、intensity |
✅ |
| MPEG-2/2.5、Layer I/II | error.Unsupported |
| 长块(normal) | 八个向量(单/双声道)逐 granule 与 ffmpeg 相差 < 2e-6(f32),s16 最大 1 LSB |
| short/start/stop 窗口 | 同上;1 秒静音 + 10 ms 脉冲的 start→short→short→stop 回归测试 SNR 121.6 dB |
| intensity stereo | 语料里没有(LAME 不产生 intensity),用 src/mp3_build.zig 手工构造的流对 ffmpeg 验证:SNR 122.9 dB |
立体声顺序:反量化(两声道)→ joint stereo → 重排 → 抗混叠 → IMDCT → 各自多相合成。
MS 与 intensity 都作用在反量化后的 xr 上,必须在抗混叠之前:抗混叠是单声道内部相邻谱线的
旋转,先做会把两个声道的混叠项转到错误的邻带上;IMDCT 之后更是时域样本,M + S 已不成立。
mode_extension 逐帧读取(LAME 会在帧之间开关 MS)。MS-only 帧的 global_gain 减 2 个
四分之一指数(1/√2 归一化,编码器放在增益里);intensity+MS 同时开启时该因子落在 MS 频带上。
is_pos == 7 按规范把该频带清零(不是缩放);ffmpeg 把 ≥7 当作"不是 intensity 位置"并沿用左声道,
这是本库唯一有意与 ffmpeg 不同的地方,合成用例里同时记录了两边的峰值(本库 0,ffmpeg 0.43)。
验收判据(见 src/mp3_vectors_test.zig):f32 与 ffmpeg 比 SNR ≥ 90 dB、逐 granule 最大差 < 1e-4;
s16 比 SNR ≥ 70 dB、最大差 ≤ 8 LSB,且每 20 个 granule 一段的 SNR 不得塌陷;样本总数与 ffmpeg 完全一致
(立体声按每声道计,交错样本数是两倍)。s16 的上限来自两边不同的 i16 舍入规则
(满幅时约 0.5 LSB ≈ 72 dB),所以两条判据不同。
zig build bench 的 MP3 行有两条:3 秒 44.1 kHz/128 kbps 单声道文件约 900x 实时,
1 秒 44.1 kHz/128 kbps 立体声文件约 570x 实时(ReleaseFast,两者都远高于 100x 目标)。
Ogg 容器 + Vorbis I 整条解码链:三个头包、audio packet、floor 曲线、residue(format 0/1/2)、逆耦合、IMDCT、重叠相加。open 返回可读 PCM 的 Decoder。Opus 共用同一套容器层,并且 CELT / SILK / Hybrid 三层都做完了,见下面「Ogg Opus:容器 + CELT + SILK + Hybrid 解码」。
| 能力 | 状态 | 说明 |
|---|---|---|
页面解析(OggS、版本、header type、granule、serial、sequence、segment table) |
✅ | 多字节字段小端;保留位非零 → error.Corrupt |
CRC-32(多项式 0x04C11DB7,MSB-first,init 0,无 final xor) |
✅ | 每一页都校验,包括被跳过的逻辑流页面;翻一个页体字节 → error.Corrupt |
| packet 拼装(一个 packet 可跨页,255 lacing 续页) | ✅ | 4 MiB 工程上限;悬空 continuation → error.Truncated |
| 多逻辑流 | ✅ | 只取第一个音频流(按 \x01vorbis / OpusHead 识别),其余页读过并丢弃;chained 流也忽略 |
| EOS / 页序号 | ✅ | EOS 结束(其后页不再读);目标流页序号跳号 → error.Corrupt |
| Vorbis identification / comment | ✅ | 版本、声道、采样率、bitrate 上限/标称/下限、块大小 2^n;comment 的 vendor 与条目跳过 |
| Vorbis setup:码本 | ✅ | ordered / unordered / sparse 三种长度表;lookup type 0/1/2;type 1 的 VQ 表只有 lookup_values 个标量 |
| Huffman 解码表 | ✅ | 规范式贪心分配(同一长度内码字不连续,所以是 trie 而不是区间查表)+ 10 位快表;内存按已用码字计 |
| floor 0 / 1 | ✅ floor 1 / ❌ floor 0 | floor1 走完整预测+曲线合成;用到 floor 0 的流在 open 直接 error.Unsupported(不假装静音) |
| residue 0 / 1 / 2 | ✅ | 先读完所有 cascade,再按 classification 读 book 列表(不是交错);classbook digit 从高下标往低填 |
| mapping / mode | ✅ | mapping type 0、耦合步、submap mux;模式切换的 4 种长窗(normal/start/end/transient) |
| 逆耦合 | ✅ | 在 residue 向量上、按耦合步逆序做,符号按 M>0 / A>0 四个象限走 square-polar 反变换,不是 M±A 蝴蝶 |
| IMDCT | ✅ | DCT-IV 经两个 M 点复数 FFT;无归一化因子(见下) |
| 重叠相加 | ✅ | 每块输出 (前块 + 本块)/4 个样本;首块只用于“预热”,不输出 |
Info.total_frames |
✅ | 流的最后一个 granule;因为要读到末页才知道,open 时是 null,read 到 EOF 后填上 |
| Opus | ✅ 容器 + CELT + SILK + Hybrid,单声道与立体声都支持 | probe 返回 .ogg_opus;opus.inspect 解析 OpusHead / OpusTags / 每个包的 TOC 与时长;open 返回一个真的会解码的 Decoder,CELT 包(16–31)、SILK 包(0–11)与 Hybrid 包(12–15)都出 PCM,3 帧以上的包与立体声 Hybrid 在 read() 返回 error.Unsupported,见下面「Ogg Opus」一节 |
验收素材(在仓库外的 ..\zig-audio-vectors\ogg,不进 git;缺失时打印一行并 SkipZigTest):
| 素材 | 编码 | 声道 | 采样率 | 块大小 | 码本 | floor | residue | mode | total_frames |
|---|---|---|---|---|---|---|---|---|---|
vorbis-44k-q4.ogg |
Vorbis q4 | 2 | 44100 | 256 / 2048 | 42 | 1, 1 | 2, 2 | 2 | 132300 |
vorbis-48k-noise.ogg |
Vorbis q6 | 2 | 48000 | 256 / 2048 | 44 | 1, 1 | 2, 2 | 2 | 96000 |
opus-48k-96.opus |
Opus 96k | 2 | 48000 | — | — | — | — | — | 144000(见「Ogg Opus」) |
opus-48k-mono.opus |
Opus 64k | 1 | 48000 | — | — | — | — | — | 144000(同上) |
与 ffmpeg 逐样本对比(整文件,ffmpeg -f f32le / -f s16le,样本数完全相同):
| 素材 | f32 SNR | f32 最大差 | s16 SNR | s16 最大差 |
|---|---|---|---|---|
vorbis-44k-q4.ogg |
133.42 dB | 6.7e-08 | 100.96 dB | 1 LSB |
vorbis-48k-noise.ogg |
131.93 dB | 7.5e-08 | 98.78 dB | 1 LSB |
对齐:没有任何偏移需要裁。 首块按规范只做预热(它的右半参与下一块的 lap),其后每块吐 (前块大小 + 本块大小)/4 个样本;整条流的样本数刚好等于最后一个 granule,末块按 granule 截断。所以开头不裁、结尾只按 granule 截断,与 ffmpeg 的 -f s16le 输出长度逐样本一致(132300 / 96000)。Vorbis 不像 MP3 有编码器延迟字段,重叠相加的首块丢弃就是它的“编码器预滚”。
IMDCT 不做归一化:教科书的 IMDCT 有 2/M 因子,Vorbis 没有——4/n 在编码器的前向变换上(参考实现 mdct_forward 里乘 scale),mdct_backward 是裸余弦和。这一条不会体现在波形相关性上(整体缩放一个常数相关系数仍是 1.000000),只体现在绝对电平,所以最容易被漏掉;本库在 vorbis_dsp.zig 的两个 dsp 测试里对冲,并在报告里写清。
floor1 的曲线合成必须整表排序:X 列表里 x[0]=0、x[1]=2^rangebits 分别是极小值和极大值,但“画曲线”那一步要对整个 X 列表按升序排,于是 x[1] 排到最后、最后才画。如果只排 2..n-1(保留前两个位置不动),曲线形状会整体错位而位流消耗一位不差——这是一个只在听感/SNR 上暴露、在解析测试里完全看不见的 bug。
位序与 FLAC/MP3 相反:Vorbis 的位打包是 LSB-first(多比特字段的第一个读到的位是最低位),FLAC/MP3 是 MSB-first。所以 src/vorbis_bits.zig 是独立读取器,不复用 flac_bits.BitReader。测试里对同一个字节 0xB5 做了对照:Vorbis 先读 4 位得到 0x5,FLAC/MSB 读取器得到 0xB。如果“顺手复用”MSB 读取器,setup 里每个字段都会静默反序。
float32_unpack 不是 @bitCast:码本的 minimum_value / delta_value 是 1 位符号 + 21 位整数尾数 + 10 位指数(偏置 788),不是 IEEE-754。按 IEEE 位型直读会得到指数离谱的“合法浮点数”(1.0 读成 2^65),音频变成 1e18 量级的噪声而不是报错。
zig build bench 的 Vorbis 行:3 秒 44.1 kHz/立体声 q4 循环到 20 秒,约 380x 实时(目标 100x,ReleaseFast)。
ffprobe 只暴露声道、采样率和时长(正好对上 total_frames);码本 / floor / residue / mode 的数量用一个独立的 Python 参考解析器按 Vorbis I 规范交叉核对。坏 CRC(页体翻一字节)→ error.Corrupt;截断(页体切 5 字节)→ error.Truncated,两者都在 read 阶段报出(open 只读头几页,这是流式解码的应有行为)。
Opus 不是一个编码器:它是 SILK + CELT 两层加一个切换器,逐包决定用哪一层。三层现在都能出 PCM:CELT 层(configuration 16–31,音乐)、SILK 层(0–11,语音),以及把两者放在同一帧里的 Hybrid 层(12–15)。SILK 与 CELT 共用同一套范围解码器、同一个 pre-skip/granule 裁剪路径,区别是 SILK 在 8/12/16 kHz 上合成再重采样到 48 kHz,而 Hybrid 在一帧里先解 SILK 低频再解 CELT 高频,最后在时域相加。立体声 Hybrid 仍然返回 error.Unsupported:没有素材,不写没测过的路径。
| 能力 | 状态 | 说明 |
|---|---|---|
OpusHead(RFC 7845 §5.1) |
✅ | magic、version、channels、pre-skip(u16 LE)、input sample rate、output gain(Q7.8,i16)、mapping family |
| channel mapping family 0 | ✅ | 单流单声道/立体声;stream count 固定 1、coupled count 固定 C-1,不编码 |
| channel mapping family 1 | ✅ | 解析 stream count / coupled count / mapping table(255 = 静音),并校验 N≥1、M≤N、M+N≤255、每个 index < M+N 或 255;不合法 → error.Corrupt |
| family ≥ 2(Ambisonics) | ❌ error.Unsupported |
明确拒绝,不静默忽略 mapping table |
OpusTags(RFC 7845 §5.2) |
✅ 校验 magic、跳过后面的 vendor + 条目 | 结构走通(长度自洽),内容不暴露 |
| TOC 帧结构(RFC 6716 §3.2) | ✅ | config / stereo / frame count code 0–3、1–2 字节帧长、padding、每帧大小与偏移 |
Info.total_frames |
✅ | 最后一页 granule − pre_skip;granule 含 pre-skip;与前几轮一样,open 时是 null,read 到 EOF 后填上 |
| CELT 解码(config 16–31) | ✅ | 粗能量(frame 级 inter/intra 预测)→ 细能量 → 比特分配 → PVQ 形状 → anti-collapse → 反归一化 → 立体声 theta 重建 → IMDCT → 重叠相加 → 音高后滤波 → 去加重 |
| SILK 解码(config 0–11) | ✅ | VAD/LBRR → 增益(绝对+差分)→ LSF(stage-1/2 VQ、反预测、稳定化、LSF→LPC)→ 音高(lag+contour)→ LTP → 激励(pulse/shell、LSB、符号、伪随机翻转)→ 再白化 → LTP 合成 → LPC 合成 → 限幅 → 8/12/16→48 kHz 重采样 |
| Hybrid 解码(config 12–15) | ✅ | 一帧内 SILK 占前半段比特、CELT 从 tell() 处接着解;CELT 起始频带 17(≈8 kHz)、终止频带按包带宽(SWB 19 / FB 21);SILK 半边固定按 WB 16 kHz 合成再升 48 kHz,两路时域相加;包尾 ≥37 比特时读模式切换的 CELT 冗余帧并做 2.5 ms crossfade |
| 立体声 SILK / Hybrid | ✅ | SILK 的立体声是 mid/side(RFC 6716 §4.2.2 的三组预测权 + silk_stereo_MS_to_LR),不是两路独立 SILK;Hybrid 立体声 = SILK 的 mid/side 解成 L/R 后逐声道升 48 kHz,再加 CELT 自己的立体声,两路分别相加。整文件 SNR:stereo-silk-24k 144.83 dB、stereo-hybrid-32k 139.08 dB(s16 106.8 / 103.8 dB,最大 1 LSB)。原先两端 transient 帧掉到 20–55 dB,是本轮关掉的两个 CELT 解码错误,见下面「已修复」 |
每包 3 帧及以上(code 3) |
❌ error.Unsupported |
多帧打包这一轮不做;只解第一帧等于悄悄丢音频,所以明确拒绝 |
open / PCM |
✅ | 返回可读 PCM 的 Decoder;opus.inspect 仍提供纯结构视图 |
五个素材(opus.inspect 的真实输出,与 ffprobe -show_entries stream=... 逐项对齐):
| 素材 | 声道 | pre_skip | input_rate | gain | family | total_frames | granule(= ffprobe duration_ts) |
包数 | 帧/包 | 配置分布 | 本轮可解码 |
|---|---|---|---|---|---|---|---|---|---|---|---|
opus-48k-128-20ms.opus |
2 | 312 | 48000 | 0 | 0 | 96000 | 96312 | 101 | 1 | 31 ×101 | ✅ |
opus-48k-24-voip.opus |
1 | 312 | 48000 | 0 | 0 | 96000 | 96312 | 101 | 1 | 9 ×11, 15 ×9, 23 ×80, 27 ×1 | ✅ |
opus-48k-64-60ms.opus |
2 | 312 | 48000 | 0 | 0 | 96000 | 96312 | 34 | 3 | 27 ×31, 31 ×3 | ❌ 3 帧/包 |
opus-48k-96.opus |
2 | 312 | 48000 | 0 | 0 | 144000 | 144312 | 151 | 1 | 31 ×151 | ✅ |
opus-48k-mono.opus |
1 | 312 | 48000 | 0 | 0 | 144000 | 144312 | 151 | 1 | 31 ×151 | ✅ |
三种编码路径都被触到,而且都能解码:五个文件合计 CELT 518 包、SILK-only 11 包、Hybrid 9 包(后两者全在 24k VOIP 那个文件里:config 9 = SILK WB 20 ms,config 15 = Hybrid FB 20 ms,config 23/27 = CELT 10/20 ms)。128k/20 ms 与 96k 的音乐素材全是 config 31(CELT 全带 20 ms)。60 ms 素材是 code 3 的 3×20 ms CELT,不是 SILK 长帧——libopus 在 64k 立体声下选了 CELT,这一点和“长帧就该是 SILK”的直觉相反,表格是按实际字节统计的。
| 素材 | 声道 | 帧数 | f32 SNR | f32 最大差 | s16 SNR | s16 最大差 |
|---|---|---|---|---|---|---|
opus-48k-128-20ms.opus |
2 | 96000 | 140.69 dB | 2.98e-08 | 104.91 dB | 1 LSB |
opus-48k-96.opus |
2 | 144000 | 140.42 dB | 2.98e-08 | 102.63 dB | 1 LSB |
opus-48k-mono.opus |
1 | 144000 | 141.91 dB | 3.7e-08 | 105.25 dB | 1 LSB |
判据(与 MP3/Vorbis 一致):f32 SNR ≥ 90 dB 且逐样本最大差 < 1e-4;s16 SNR ≥ 70 dB 且最大差 ≤ 8 LSB;样本数与 ffmpeg 完全一致。三个文件全部通过,样本数 96000 / 144000 / 144000,与 ffmpeg 逐样本数相同。
为什么 128k / 96k 两个纯 CELT 文件以前只有 94 / 123 dB:那两处 CELT 解码错误(折叠区间端点、anti-collapse 声道顺序)只在 transient 帧、并且只在零脉冲频带落到折叠边界时可见,坏帧被 99 个好帧平均掉了;本轮修掉后三个文件都在 140 dB 附近(见下面「已修复」)。另一方面,两个参考实现自己就对不上:同一份 ffmpeg 里,原生 CELT 解码器和它静态链接的 libopus 在这些文件上只差 77.0 / 77.0 / 80.0 dB(opus_celt_vectors_test.zig 里逐文件测出来并断言“我们比 libopus 更接近 ffmpeg”)。原因是 libopus 的 FLOAT_APPROX 构建用多项式近似 celt_exp2,而 ffmpeg 原生解码器用 exp2f,两者在 denormalise_bands 里差出约 1e-4 的相对增益,正好是 77 dB 量级。所以本轮刻意用精确的 exp2:这既是 RFC 的语义,也是比较目标的实现方式。剩下的差(约 4e-8)就是两种浮点求值顺序的舍入。
pre-skip 对齐结论:裁剪,不是偏移。 ffmpeg -f f32le / -f s16le 的输出长度恰好是 granule − pre_skip = 96000 / 144000,也就是说它把前 312 个样本丢掉了,而不是在时间轴上平移。本库做同一件事:解码器算出 skipped + delivered,前 pre_skip 个样本直接丢,再在末页 granule 处截断(delivered >= total_frames 就停)。如果改成“偏移”,整条流会晚 312 个样本 = 6.5 ms,逐样本比对立刻从 141 dB 掉到 0 dB。末尾还要截断:包内样本数求和的 96960/144960 比真实长度多出正好一个包(960),末页 granule 把它切掉——这一条和 Vorbis 不同,Vorbis 只截块,Opus 还要按 granule 裁到精确样本数。
celta 的坑(按出现顺序):
- 比特分配必须先对。
bits2pulses不是对数换算,而是在预计算的脉冲阶梯上二分,且“恰好一半”时向下取;细能量的除法在整除前先加den/4。任何一处差 1/8 bit,后面每个频带的预算都会漂,最后整帧的符号全错。校准办法:先让tell()/tellFrac()与参考完全一致,再用真实素材的 SNR 验证。 V(N,K)必须用 u32 模运算。宽频带高码率下V会超出 32 位,编码器因此强制分裂频带;用更宽的整数算“更对”,但会改变索引映射——那就是另一种码本,输出必然是噪声。- 立体声 theta 有三种分布:时间分裂用三角分布、立体声用阶梯分布、其余用均匀分布。选错一种,读到的符号数就不同,之后全盘错位。
itheta == 0与== 16384是特例:前者 mid 拿满、后者 side 拿满,fill掩码也要跟着改。 SHR16(mid, 1)在 float 构建里是恒等宏。stereo_merge里照抄定点版的“右移 1 位”会让每个样本大 2 倍(+6 dB),而频谱形状、L/R 相关性、逐帧波形看起来全都对,只有绝对电平错——本轮就是被这一条卡住,靠“逐频带能量比恰好 +6.00 dB”定位的。- PVQ 的展开方向:解码是先取索引再逐步降维(
uprev),不是从零重建;用unext正向重算结果一样,但每次都要 O(N·K)。
为什么 sample_rate 固定 48000:Opus 的内部带宽可以在 4/6/8/12/20 kHz 之间逐包切换,但输出采样率只有一个基准 48 kHz;RFC 7845 §5.1 明说 input sample rate 字段“not the sample rate to use for playback”,它只是编码前原始素材的提示。所以 Info.sample_rate 恒为 48000,提示值单独放在 input_sample_rate 里,不参与任何计算。
为什么 pre-skip 必须从 granule 里减掉:Opus 编码器有算法延迟,解码器开头要丢掉 pre_skip 个样本;而 granule position 记的是含这段延迟的绝对样本位置。RFC 7845 §4.3 的公式是 PCM sample position = granule position − pre-skip。于是 ffprobe 的 duration_ts(= granule,96312 / 144312)比真实音频长度(96000 / 144000)多出正好 312 个样本:duration_ts = total_frames + pre_skip,五个文件全部对上。反过来说,如果直接拿 granule 当长度,每个文件都会多报 6.5 ms;如果拿包内样本数求和,则会多报(96960 / 97920 / 144960)——因为末页的 granule 会把最后一个包截短(end trimming),差值恰好不超过一个包(960/1920/2880),测试里对这条也做了断言。
不伪造静音:3 帧以上的包在 read() 里返回 error.Unsupported(立体声 SILK/Hybrid 从这一轮起是支持的,见下)。返回静音只会把“不支持”变成“能播但没声音”,更难排查。open() 之所以不拒绝,是因为包的编码模式写在包里,头里没有——想知道就得先读包,那就已经是 read 了。
码率不变的是“结构”:opus.inspect 仍然只解析结构、不出 PCM,五个文件与 ffprobe 的 duration_ts/channels/sample_rate 全部对齐,并逐个包核对「帧大小 + framing + padding == 包长」。
合成用例覆盖真实素材没有的分支:code 1(两帧等长)、code 2(显式帧长,1 字节与 2 字节两种)、code 3 的 CBR/VBR、1 字节与多字节(255 续读)padding、M=0、120 ms 上限(48×2.5 ms 通过、49×2.5 ms 拒绝)、超过 1275 字节的帧、以及 OpusHeaX 式的坏 magic / 坏版本 / 零声道。真实素材里没有 padding,也没有 code 1/2,所以这几条只能靠合成包。
CELT 的单元测试按层拆开:PVQ(V(N,K) 手算值、cwrsi 把 18 个码字恰好枚举一次、脉冲阶梯与 bits2pulses 的往返)、能量反量化、比特分配(分配总量不超预算、caps 随声道数单调)、比特精确的 bitexact_cos/isqrt32、IMDCT(单频点、FFT 峰值位置、尺寸分解)、Hadamard 与 haar 往返、stereo_merge。整文件验收在 src/opus_celt_vectors_test.zig。
SILK 是预测编码:一个短时 LPC 滤波器 + 一个长时(音高)预测器,用稀疏脉冲激励驱动。解码顺序是规范的一部分(RFC 6716 §4.2.3–4.2.7),因为每个字段都改变下一个字段要花多少比特:
- 帧头:每个 20 ms 帧的 VAD 标志,然后一个 LBRR 标志;40/60 ms 包再跟一个 LBRR 位图;
- LBRR 帧(低码率冗余):只解比特、不合成——它描述的是更早一帧的副本;
- 帧类型:inactive / unvoiced / voiced + 量化偏移(
qoffset_high); - 增益:每 5 ms 子帧一个,首子帧绝对编码(6 位对数),其余差分编码;
- LSF:stage-1 索引选出码本与预测权重,stage-2 残差反向后向预测 → 归一化 LSF → 稳定化(最小间距、必要时排序推开)→ LSF→LSP→两个多项式→LPC,再做带宽扩展与 LEVINSON 稳定检查;
- 音高:绝对 lag 或相对上一帧的 delta,加 contour 偏移;LTP 五抽头;
- 激励:shell 块脉冲计数(含 17 逃逸与 LSB 扩展)、PVQ 二叉树定位、raw LSB、符号、伪随机符号翻转,装配成 Q23;
- 合成:系数变化处先再白化(把输出跑一遍新滤波器得到残差)、按增益比
rescale、LTP、LPC、±1限幅; - 重采样:8/12/16 kHz → 48 kHz,然后交给和 CELT 完全相同的输出路径(pre-skip 裁剪 + 末页 granule 截断)。
SILK 没有去加重这一步:去加重(ffmpeg 的 ff_opus_deemph_weights、α_p = 0.85)是 CELT 输出链的一部分;SILK 合成到 ±1 限幅就结束了,参考实现(ffmpeg silk.c 与 libopus silk/decode_core.c)里都没有对 SILK 做去加重。这里按参考实现来——也正因为如此才有 145 dB。
为什么重采样这一步必须"复刻"而不是"写个好滤波器":ffmpeg 原生 Opus 解码器的 SILK 输出是 8/12/16 kHz,它用 libswresample 升到 48 kHz(libavcodec/opus/dec.c 里 filter_size=16、按带宽设输入率、先用几个零样本预热、每包调一次 swr_convert)。同一份 SILK 码流,用 libopus 自己的 silk_resampler 和用 swresample 差 47 dB——比"两个解码器"的差别大得多。所以 src/opus_silk_resample.zig 复刻的是 swresample 在该配置下的算术:16 抽头/相位、Kaiser 窗 β=9、cutoff 0.97、按精确有理比取相位数(48/8=6、48/12=4、48/16=3,而不是默认的 1024)、index/frac 定点步进、以及启动时"镜像"补历史的那段。预热零样本数按带宽取 4/8/11(NB/MB/WB)。这套东西本身用一个独立探针和 ffmpeg -af aresample=filter_size=16 对过:8/12/16 kHz 三个速率上都是 ~144 dB、最大差 9e-8(就是 f32 舍入)。
验收(对 ffmpeg -f f32le / -f s16le):
| 素材 | 实际内容 | 帧数 | f32 SNR | f32 max | s16 SNR | s16 max |
|---|---|---|---|---|---|---|
silk-12k-nb.opus |
101 包全是 config 9 = SILK WB 20 ms(名字里的 nb 是码率标签,不是带宽) | 96000 | 145.30 dB | 2.98e-08 | 107.28 dB | 1 LSB |
silk-10k-nb.opus |
101 包全是 config 1 = SILK NB 20 ms(8 kHz 内部率,测 flush) | 96000 | 144.33 dB | 2.98e-08 | 107.72 dB | 1 LSB |
silk-14k-nb-40ms.opus |
51 包全是 config 2 = SILK NB 40 ms(每包两个 SILK 帧,测 flush) | 96000 | 144.39 dB | 2.98e-08 | 107.19 dB | 1 LSB |
stereo-silk-24k.opus |
91 包 config 9(SILK WB 20 ms,TOC stereo=1)+ 1 包 config 13 + 9 包 config 15 | 96000×2 | 144.83 dB | 4.47e-08 | 106.76 dB | 1 LSB |
stereo-hybrid-32k.opus |
101 包全是 config 15 = Hybrid FB 20 ms,stereo=1 | 96000×2 | 139.08 dB | 4.47e-08 | 103.80 dB | 1 LSB |
145 dB 不是"勉强过 90 dB",而是和比较目标是同一套浮点运算:SILK 的参数解码是定点(增益、LSF、音高、激励),合成是浮点,ffmpeg 的原生 SILK 也是这个分工。libopus 是全定点合成,两者在同样码流上只差约 40 dB,所以"照 libopus 写"会得到正确但和目标差 40 dB 的输出。
已修复(本轮):立体声素材的 transient 帧。 原先两个立体声素材的首/尾 transient 帧掉到 20–55 dB(整文件 82.91 / 47.05 dB),根因是 CELT 解码的两个错误叠加,都不在 SILK、也不在 mid/side:
quant_all_bands的折叠区间端点少算了一位。 libopus 与 ffmpeg 的fold_start都是先自减再比较(while (eBands[--fold_start] > target)),这样“恰好等于effective_lowband的那个频带”本身可折叠;原来的写法比较的是前一个频带,循环停下时没有把该频带包含进来。fold_end的包含性同样错了一位。于是x_cm(可折叠频带的 collapse mask 并集)取错,零脉冲频带的fill、以及写回的collapse_masks都跟着错。此外collapse_masks原来没有逐帧清零(ffmpeg 每帧memset);折叠区间错时它还会把上一帧的掩码读进来,让错值更不可预测。这一条主要打中立体声 / 混合帧:Hybrid 的effective_lowband总被钳到e_bands[17],正好落在频带边界上,所以每个 Hybrid 帧都在 band 18–20 命中;单声道素材修复前后都是 141.9 dB,没有踩到这条。- anti-collapse 的循环嵌套。 ffmpeg 是 channel-major(每声道调用一次
process_anticollapse,两个声道共享f->seed),libopus 是 band-major / channel-inner;这里原来照 libopus 写。噪声幅度r、prev_energy的两代历史、seed 来源都与 ffmpeg 逐位一致(用带fprintf的本地 ffmpeg 调试版逐频带对过),只有 LCG 序列分配给哪个 (band, channel) 不同——对 42 个 transient 帧里r > 0的那些,这决定了注入噪声的符号。既然验收目标是 ffmpeg,这里改成 channel-major。
修好后 stereo-silk-24k / stereo-hybrid-32k 整文件 144.83 / 139.08 dB(s16 106.76 / 103.80 dB,最大 1 LSB),交付的每一包都 ≥ 137.7 dB;两个文件回到 90 dB 判据,不再按实测值记录。为什么能躲过之前的 1525 帧素材:transient 帧只有 42/1525,anti-collapse 只在那里跑;而折叠端点的错误只在“频带零脉冲 + 折叠边界恰好落在频带边界”时可见,纯 CELT 素材里只有最后一个低码率帧满足;128k 那个文件整文件仍有 94.25 dB(其余 100 帧 140 dB),所以一直过线。
素材实况:任务给的三个"SILK 素材"里只有一个是纯 SILK,另两个是混合模式。Hybrid 做完之后它们都能整文件解码,所以三个文件现在都是验收素材(混合那两个的完整数字在下面「Hybrid」一节):
| 素材 | config 分布 | 第一个包 | 现在 |
|---|---|---|---|
silk-12k-nb.opus |
9 ×101 | SILK | ✅ 纯 SILK(而且是 WB,不是 NB),145.30 dB |
silk-20k-wb.opus |
9 ×91, 13 ×1, 15 ×9 | Hybrid(config 15) | ✅ 91 SILK + 10 Hybrid,145.36 dB |
opus-48k-24-voip.opus |
9 ×11, 15 ×9, 23 ×80, 27 ×1 | Hybrid(config 15) | ✅ 11 SILK + 9 Hybrid + 81 CELT,141.90 dB |
silk-20k-wb.opus 的结构特别有用:9 个 Hybrid 打头、91 个 SILK 中段、最后 1 个 10 ms Hybrid(config 13,SWB)收尾——10 ms 混合路径只有这里摸得到。opus-48k-24-voip.opus 则在第 19 个包(SILK config 9)的包尾塞了一个 CELT 冗余帧,正好覆盖 SILK→CELT 的模式切换 crossfade。为了让 NB/MB 与 40/60 ms 分支也有验收,本轮另外用 libopus 编了几条纯 SILK 素材(本地,不入库)交叉验证:
| 本地素材 | config | 帧数 | f32 SNR |
|---|---|---|---|
gen-x7000-0.opus(8 kbps NB 20 ms) |
1 | 96000 | 40.13 dB(见下) |
gen-x11000-6000.opus(11 kbps MB 20 ms) |
5 | 96000 | 144.18 dB |
gen-mb40.opus(NB 40 ms,2 个 SILK 帧) |
2 | 96000 | 46.02 dB(见下) |
gen-wb60.opus(WB 60 ms,3 个 SILK 帧) |
11 | 96000 | 144.66 dB |
8 kHz 的尾巴现在是 144 dB,不是 40 dB(这一轮修掉的):上一轮两条 8 kHz 素材的差异只在最后 24 个样本(第 95976..96000 个),前面的子帧全是 143–145 dB。原因是 swresample 在 8 kHz 这条路径上每个包少产几个样本,累计的 delayed_samples 最后由 resample_flush 补:它把缓冲区里最后 (min(count, 16)+1)/2 个输入样本镜像一份接在后面,让滤波器把还欠的输出算完。复刻要点三个:(1) 镜像规则(in_buffer[count+j] = in_buffer[count-1-j]),(2) swr_convert(NULL) 会同时清掉 resample_in_constraint(不清就一个样本都出不来),(3) 这段尾巴在 granule 截断之后才发——ffmpeg 的容器层只把最后一个包截到 granule,drain 出来的 flush 帧排在它后面,所以整流的最后 delayed_samples 个样本是 flush 而不是包内样本。三条都对上以后,silk-10k-nb.opus 与 silk-14k-nb-40ms.opus 的整文件 SNR 都是 144 dB、最大差 3e-8(逐样本全等),opus_silk_resample.zig 里也留了两条单测钉住镜像规则和"flush 恰好补上欠的样本数"。
SILK 的坑(按出现顺序):
nlsf_interp_factor忘了存回解码器:lpc.decode把插值因子作为返回值交出来,而合成读的是self.interp_factor。结果 20 ms 帧的前两个子帧(用插值 lead-in)完全正确、后两个子帧用错分支——症状极其有迷惑性:第一个包 145 dB、第二个包从第 2 个子帧起掉到 13 dB,随后的包慢慢"自愈"到 100 dB。这类"字段既是返回值又是状态"的移植错误只有逐子帧 SNR 才看得出来。- 输出的 −2 偏移:参考实现取的是
frame.output[SILK_HISTORY − flength − 2],比"刚写的那一帧"早 2 个样本。这不是笔误,是一个真实的 2 样本提前量;照直觉写成−flength会让整条流晚 2 个样本,SNR 直接从 145 dB 掉到 ~25 dB。 - 10 ms MB 的 shell 块多出 8 个样本:
shell_blocks[MB][10ms] = 8→ 128 个激励样本,而这一帧只有 120 个样本。多出来的 8 个是编在比特流里的(要照读),只是合成用不到。第一版在这里加了assert(samples == flength),fuzz 一跑就炸——参考实现根本没这个约束。 - 定点溢出在 Zig 里是 panic,在 C 里是回绕:
silk_lsf2lpc的ROUND_MULL、pol[j] += …、nlsf[k] = …(int16 截断)都依赖回绕。全部换成*%/+%/-%与@truncate之后,10000 轮变异 fuzz 才干净。 - 激励的符号概率是三维表:
excitation_sign[active + voiced][qoffset_high][min(pulsecount, 6)]。把active+voiced写成voiced时,pkt0(unvoiced)照样 145 dB,因为 unvoiced 的索引恰好也合法——只有 voiced 帧会错,而且错得"像那么回事"。 - LTP 的再白化与 rescale:
out_end与scale的分支(i<2 || interp==4)决定"从哪开始把输出反滤波成残差"和"用不用 LTP scale";out_end != 0时还要把上一子帧的残差按gain[i-1]/gain[i]缩放。少任何一半,增益突变的帧就会整体响度差 20%。 - 包尾的 ≥17 比特不是填充:SILK 包尾若剩下 ≥17 比特,那段是 CELT 冗余帧(RFC 6716 §4.2.3 的模式切换用),要读一个方向位、按
size − ceil(tell/8)切出它、解 5 ms CELT 再做 crossfade。把它当"剩余比特"跳过,opus-48k-24-voip.opus的 SNR 会从 141.9 dB 掉到 20.1 dB——只有 240 个样本,但足够毁掉整条流。 - 立体声 SILK 是 mid/side,不是两路独立 SILK(这一轮接上的):
stereo_weights每帧三组预测权(RFC 6716 §4.2.2),L/R 由silk_stereo_MS_to_LR(ffmpeg 的silk_unmix_ms)还原:L = (1+w1)·mid + side + w0·p0、R = (1-w1)·mid − side − w0·p0,其中p0 = 0.25·(mid[i-2]+2·mid[i-1]+mid[i])、前stereo_interp_len({64,96,128})个样本用上一帧权重线性插值。不要按"两路独立"实现:那样 side 会和 mid 一起被当成两路信号,输出是噪声。opus_silk.zig的unmixMs早就写好了,这一轮把它接进默认路径。
Hybrid(config 12–15)是 Opus 最后一块:同一帧里 SILK 编低频带、CELT 编高频带,解码器要把两路都解出来再相加 src/opus_hybrid.zig。它不是"先 SILK 后 CELT 的两个包",也不是频域拼接——理解这一点,四个决定就都顺下来了:
- 比特怎么分:没有长度字段,靠共享的范围解码器。 SILK 与 CELT 不是两段各自定长的字节区,而是同一个算术编码器:SILK 从前面消耗符号,CELT 从 SILK 停下的那个比特位置接着解。所以"切分点"就是
rc.tell(),一般不在字节边界上;CELT 的比特预算仍是整帧的比特数(不是剩下的尾巴)。实测:opus-48k-24-voip.opus第 0 个 Hybrid 包 SILK 用掉 578/744 bit(CELT 起于第 578 bit,剩 166 bit);silk-20k-wb.opus第 0 个是 543/672(剩 129);它结尾那个 10 ms Hybrid(config 13)是 224/360(剩 136)。 - 唯一的字节对齐边界是包尾的冗余帧。 RFC 6716 §4.2.3:SILK 解完后若还剩 ≥17 bit(SILK-only 包)或 ≥37 bit(Hybrid 包,多一个标志位和长度字段的最小空间),后面可能挂一个 5 ms 的 CELT 冗余帧(模式切换用)。SILK-only 包只要剩 ≥17 bit 就强制有;Hybrid 包要先读一个
logp=12的标志。切分点按ceil(tell/8)算,然后把范围解码器的可读区缩短(shrink)——这样 CELT 的 raw-bit 尾部和比特预算都止于冗余帧之前,和参考实现的dec.storage -= redundancy_bytes是同一件事。 - 频带怎么分:CELT 从 band 17 起。 起始频带固定 17(频带边界约 8 kHz),终止频带按包的带宽取 19(SWB)/ 21(FB);CELT 侧只需要把
start/end两个字段设对,其余比特分配、PVQ、IMDCT 全走原有代码。SILK 侧无论包标的是 SWB 还是 FB,内部一律按 WB(16 kHz) 合成,再用现成的重采样器升到 48 kHz。 - 怎么合:时域相加。 参考实现就是把 CELT 的输出加到 SILK 升采样后的缓冲上(ffmpeg 的
vector_fmac_scalar),本库同样out[i] = silk48[i] + celt[i]。对齐是这里唯一的暗礁:SILK 重采样器有固定群延迟,每帧会少产几个样本并把余额带到下一次调用;参考实现每包只要"恰好一帧"的输出(swr_convert的out_count = frame_duration)并记delayed_samples,本库照做——如果贪心地把重采样器攒下的 9 个样本一起吐出来,CELT 就会整体错位 9 个样本。实测错位 9 个样本时opus-48k-24-voip.opus是 81.60 dB / 最大差 1.5e-3:SNR 仍然"看着不错",但max_diff的判据直接不通过——这就是为什么验收必须两条都看。少于一帧时直接error.Unsupported,不"差不多对齐"。
模式切换的 crossfade:冗余帧解出来后,参考实现在时域做一个 2.5 ms 的交叉淡化,窗就是 CELT 的模式窗平方(libopus 的 smooth_fade 在调用点平方,ffmpeg 存成 ff_celt_window2;本库用 window120_reference 平方)。方向有两个且不对称:SILK→CELT 用冗余帧的后半段替换包尾(fadeTail),CELT→SILK 用前半段直接顶替再淡回主解码(spliceHead)。这一段值多少 dB:把 SILK 包的冗余分支关掉,opus-48k-24-voip.opus 从 141.90 dB 掉到 20.05 dB(最大差 0.133)——只有 240 个样本,但足够毁掉整条流。
验收(对 ffmpeg -f f32le / -f s16le,判据同前):
| 素材 | 内容 | 帧数 | f32 SNR | f32 max | s16 SNR | s16 max |
|---|---|---|---|---|---|---|
opus-48k-24-voip.opus |
9 Hybrid + 11 SILK + 81 CELT,单声道 | 96000 | 141.90 dB | 3.73e-08 | 105.85 dB | 1 LSB |
silk-20k-wb.opus |
9 Hybrid + 91 SILK + 1 个 10 ms Hybrid | 96000 | 145.36 dB | 2.98e-08 | 106.06 dB | 1 LSB |
opus-hybrid-mono-48k.opus(入库 fixture) |
101 包全是 config 15(纯 Hybrid) | 96000 | 133.34 dB | 1.34e-07 | 105.18 dB | 1 LSB |
前两个文件的价值在于三种包混在一条流里都解对:Hybrid 打头、SILK 中段、CELT 收尾,任何一个模式的状态没接上,整文件 SNR 都会塌。第三个是入库的纯 Hybrid fixture,让没有外部语料库的 CI 也能测 Hybrid。zig build bench 的 Hybrid 行(2 s 单声道 32 kbps,101 包全 config 15)是 535x 实时(同一轮 SILK 1289x、CELT 272x),高于 100x 目标。
Hybrid 的坑(按出现顺序):
- CELT 的
start是粘性状态。Hybrid 把它设成 17;如果下一个 CELT-only 包没有显式设回 0,它就会继续从 band 17 解,opus-48k-24-voip.opus的 SNR 直接掉到 17.90 dB(最大差 0.13)。这不是"声音闷一点",是整帧比特分配错位。 - 离开 SILK 要 flush CELT。参考实现在每个 SILK 包上 flush CELT(
ff_celt_flush:重叠历史、后滤波、去加重、折叠种子、当前包络清零,两个历史包络置 −28 dB)。漏掉的话,silk-20k-wb.opus末尾那个 Hybrid 包会带着 91 个 SILK 包之前的 CELT 历史解,SNR 从 145.36 dB 掉到 114.58 dB(最大差 1.4e-5)——仍然过 90 dB,所以这是一个"不报错、只变差"的 bug。 - 冗余帧的长度不是"剩下的字节"。Hybrid 用
decodeUint(256) + 2编码,SILK-only 用size − ceil(tell/8);两者都必须从 SILK 解完那一刻的tell()算,而不是读完方向位之后。差一个比特,切出来的 CELT 数据就整体偏。 ≥17与≥37不是拍脑袋。SILK-only 的 17 = 1 个方向位 + 2 字节长度字段的最低空间;Hybrid 的 37 还要加上logp=12的标志位本身。把两者写成同一个常数,会在边界包上读出假冗余。- 只解 SILK 半边也有 82.84 dB。这是最危险的"看起来对":丢掉的 CELT 高频带在 24 kbps VOIP 素材里能量不大,SNR 仍过 70 dB 的 s16 判据,但 f32 最大差 1.5e-3,离 1e-4 差一个数量级。所以 Hybrid 的验收必须看
max_diff,不能只看 SNR。
这一组格式的共同点是整数运算、可逐样本校验。六个 2 秒素材对 ffmpeg -f s16le 的 max_diff 全部为 0,样本总数完全一致:
| 素材 | 编码 | 样本数 | max_diff |
|---|---|---|---|
mulaw-8k.wav |
WAV µ-law 8 kHz 单声道 | 16000 | 0 |
alaw-8k.wav |
WAV A-law 8 kHz 单声道 | 16000 | 0 |
ima-wav-44k.wav |
WAV IMA ADPCM 44.1 kHz 单声道 | 89804 | 0 |
ms-adpcm-44k.wav |
WAV Microsoft ADPCM 44.1 kHz 单声道 | 89584 | 0 |
aiff-s16.aiff |
AIFF PCM16 44.1 kHz 单声道 | 88200 | 0 |
aiff-s24.aiff |
AIFF PCM24 44.1 kHz 单声道 | 88200 | 0 |
src/g711.zig 的 256 项表由 G.711 分段压扩公式在编译期算出,源码里只有公式:
- µ-law:
u = ~code,mag = ((((u & 0x0F) << 1) + 33) << ((u >> 4) & 7)) - 33,输出±4 * mag; - A-law:
a = code ^ 0x55,seg == 0 ? ((a & 0x0F) << 4) + 8 : (((a & 0x0F) << 4) + 0x108) << (seg - 1),符号位为 1 表示正。
两者都是 ITU-T G.711 的参考展开(与 Sun g711.c 的算术一致;µ-law 的 13 位幅度乘 4 进入 16 位范围)。测试用 256 个码的符号对称性 table[code] == -table[code ^ 0x80] 做全表校验,再对地标码做定点断言(µ-law 0x00 = -32124、0x80 = +32124;A-law 0x2A = -32256、0xAA = +32256)。
- IMA(tag 0x11):每声道 4 字节块头(
predictor: i16、step_index: u8、reserved),数据按 8 个样本一组、每组内每声道 4 字节排列,低 nibble 在前。diff = ((2 * (nibble & 7) + 1) * step) >> 3必须先乘后移:按参考实现逐项移位会分别截断,再经反馈环累积成几 LSB 的漂移。step index 钳位 0..88,predictor 饱和到 i16,每块独立重置状态。 - MS(tag 0x02):每声道 7 字节块头,字段按声道交错写(所有 predictor → 所有 delta → 所有 sample1 → 所有 sample2);输出先
sample2再sample1;nibble 高 4 位在前,且是二进制补码(-8..+7),不是 8 偏置。 - 块参数:MS 的 7 组预测系数从
fmt扩展里读(cbSize = 32),不写死;block_align决定每块字节数,samples_per_block由块大小推出(IMA1 + (block-4ch)/(4ch)*8,MS2 + (block-7ch)*2/ch),total_frames = 块数 * samples_per_block。ffmpeg 对 ADPCM 不按fact裁剪,最后一个块的填充样本照样输出,本库与之一致(所以 IMA 的样本数是 89804 而不是fact的 88200)。 - MS ADPCM 最容易错的地方:预测器是
(sample1*coeff1 + sample2*coeff2) / 256的向零截断除法,不是>> 8——负和时两者差 1。再叠加“nibble 用补码而不是偏置”和“sample1/sample2 的写入顺序”,任何一处错都会被反馈环放大成满量程误差。
src/aiff.zig 读大端 FORM/AIFF:COMM 给声道数、帧数、位深和 80 位 IEEE 754 扩展格式的采样率;SSND 前 8 字节是 offset/block size,音频从 8 + offset 开始。PCM 8/16/24/32 大端,8 位是有符号的(与 WAV 的 128 偏置不同)。
80 位扩展的解析不是查表:值 = mantissa * 2^(exponent - 16383 - 63),尾数带显式整数位。用 u128 做移位和就近舍入,因此 11025、37800、44056、192000 以及任何能放进 u32 的整数采样率都能解析;零、负数、NaN/Inf、次正规和超出 u32 的值分别有具名错误。
| 拒绝项 | 错误 | 原因 |
|---|---|---|
AIFC(压缩格式,也是 fl32/fl64 浮点 AIFF 的容器) |
error.Unsupported |
需要额外的压缩类型字段,本轮不猜 |
| AIFF 20 位等非字节对齐 PCM | error.Unsupported |
只做 8/16/24/32 |
AIFF SSND 在 COMM 之前 |
error.Unsupported |
流式解码无法回退去重读采样 |
| WAV GSM 6.10(0x0031)、MP3-in-WAV(0x0055)等其它压缩 tag | error.Unsupported |
解码器不内置 |
| IMA / MS ADPCM 的 2/3/5 位变体 | error.Unsupported |
只做 WAV 的 4 位定义 |
| MS ADPCM 超过 2 声道 | error.Unsupported |
ffmpeg 的 >2 声道布局是逐声道平面,本轮不做 |
src/g711_test.zig/src/adpcm_test.zig/src/aiff_test.zig:表地标与全表对称性、手算块(含 IMA 饱和、MS 截断除法与立体声交错)、AIFF 各位深与 80 位浮点边界、具名拒绝;src/legacy_vectors_test.zig:六个真文件的probe/Info/total_frames与max_diff 0验收(文件缺失时打印一行并SkipZigTest);src/vorbis_huffman_test.zig/vorbis_floor_test.zig/vorbis_residue_test.zig/vorbis_dsp_test.zig:规范里那张 8 码字示例表的逐码字回读、稀疏与单码字码本、截断/不可达码、trie 深码、X 列表整表排序(曲线形状回归)、render_point整数插值、dB 表单调性、residue 三种格式的样本落点、IMDCT 对直接余弦和、四种窗形与重叠相加;src/vorbis_decode_test.zig:两个 Ogg/Vorbis 真文件整文件对 ffmpeg 的 f32 与 s16 输出,逐样本 SNR / 最大差 / 样本数,以及ShortBuffer与 granule 截断;src/opus_test.zig/src/opus_vectors_test.zig:OpusHead各字段与 family 0/1、坏 magic/版本/零声道/坏 mapping 的具名错误、32 个 TOC config 与边界 0/11/12/15/16/31、code 0/1/2/3、1 字节与 2 字节帧长、1 字节与多字节 padding、120 ms 上限、1275 字节上限;五个真文件与 ffprobe 的duration_ts/channels/sample_rate对齐,并逐个包核对「帧大小 + framing + padding == 包长」;src/opus_hybrid_vectors_test.zig:Hybrid 的验收——两个混合素材与入库的纯 Hybrid fixture 整文件对 ffmpeg(f32/s16、样本数),两个素材的 config 直方图逐项钉死(防止某天素材悄悄少了 Hybrid 包还"通过"),10 ms Hybrid 收尾包单独测,以及"立体声 OpusHead + 单声道 Hybrid 包必须error.Unsupported"(顺手把被改坏的首页 CRC 重算,因为容器层校验它);src/opus_hybrid.zig里另有窗表与两个 crossfade 方向的单元测试;- 变异 fuzz 模板从 4 个扩到 12 个(六种老格式素材、Ogg/Vorbis 与 Ogg/Opus 全部在列;Ogg 模板真的走完整条解码链,Ogg-Opus 模板既走完整条解码链、又单独喂给
opus.inspect;Opus 模板现在有五个包:CELT、SILK WB 10 ms 双帧、SILK NB 40 ms、Hybrid FB 20 ms 与 Hybrid SWB 10 ms,让 SILK 的 8 kHz/两帧路径和 Hybrid 的共享范围解码器都吃到变异),zig build fuzz10000 轮无 panic(本轮 619 万样本、1619 次 Opus 结构解析;SILK 定点路径的回绕/截断问题就是这一步逼出来的); - bench 共 14 行:本轮新增 Opus 32k 单声道(Hybrid,两层同帧 + 时域相加)约 535x 实时,Opus 12k 单声道(SILK 全链 + 重采样)约 1289x,Opus 128k 立体声(CELT 全链)约 272x,Ogg Vorbis q4 立体声约 470x,其余老格式行 4.8k–330k× 实时,均远高于 100x 目标;
- 永久回归语料
src/fuzz_corpus/:20 个最小化样本(Ogg lace/packet 5、Opus TOC 4、FLAC bit reader 3、AIFF 大端长度 4、ADPCM 块边界 4),每个都有corpus.json条目写明构造与预期错误/阶段;src/fuzz_corpus_test.zig(L1)逐样本断言错误名、出错阶段、输入长度上限、峰值分配 ≤ 同族有效基线、deinit零泄漏。src/fuzz_corpus_gen.zig可从结构化 builder 重新生成全部.bin。反向证明:把任一expected_error改错一个名字,zig build test必红; - 分配/峰值/并发表:
zig build bench在吞吐行之后按格式输出open_allocs / open_bytes / read_allocs / read_bytes / steady_allocs / peak_bytes / samples_per_sec(构建模式ReleaseFast、CPU 型号、输入 fixture、8192 i16 读缓冲、输出格式都打印在表头)。read的 steady-state 分配实测为 0;Vorbis/Opus 的包前瞻只发生在首次 read(实测 1–3 次)。并发段同时打开 8 种解码器交错读,逐样本与单独解码完全一致,并报告并发峰值字节。
这个库只做一件事:把一个已经拿到的音频字节流解码成交错 PCM。它不是多媒体框架,也永远不会长成 FFmpeg。
| 不做 | 为什么永不支持 |
|---|---|
| 视频/图像解码 | 视频在 Windows / macOS / Linux 上都有系统解码器(Media Foundation + D3D11VA、VideoToolbox、VA-API),硬解、色彩管理和帧调度是平台强项;重写一遍只会更慢、更脆。 |
| 音频编码 / 转码 | 编码要码率控制、心理声学模型和大量格式组合,是另一条产品线;解码器的价值恰恰在于把这件事排除在外。 |
| 滤镜、重采样、混音图 | 这些是 DSP 策略,应该由调用方或专门的 DSP 库决定;解码器只负责把字节变成采样,不替调用方改变声音。 |
| 容器多路复用 / 解复用(MP4、MKV 的轨道、时间轴、编辑列表) | 本库只读单个音频流的负载,不选轨道、不建时间轴。唯一的例外是 Ogg:Vorbis 自身没有 framing,页、CRC 和 packet 边界只能由 Ogg 提供,所以 src/ogg.zig 只解析“第一个音频流”的页并校验 CRC,不做轨道选择,也没有编辑列表。MP4/MKV 仍在界外。 |
| 网络协议(HTTP、HLS、DASH、RTSP) | 网络、重试、缓存、鉴权都由调用方处理;库只接受一个 std.Io.Reader,不碰 socket,也不做请求。 |
| CLI / ffmpeg 命令行参数兼容 | 这不是命令行工具。目标 API 是 Zig 函数调用;模仿 ffmpeg -i ... -af ... 的参数方言与库的边界无关。 |
这些“永不支持”不是当前版本的偷懒,而是产品的边界:边界越窄,流式、无分配、可 fuzz 才守得住。
视频已经有系统解码器:Windows 的 Media Foundation + D3D11VA、macOS 的 VideoToolbox、Linux 的 VA-API 都能硬解,而且视频专利池复杂、格式迭代快。再写一个纯 Zig 视频解码器,投入产出比很差。
音频不一样:Windows 上 WASAPI 只负责输出,系统并不带 FLAC / Opus 解码器;macOS 的 AudioToolbox 对 FLAC 的支持也随版本和容器而变。一个应用如果想“走到哪都能放 FLAC”,最后往往还是得自带解码器。音频格式的专利面也窄得多(FLAC、Opus 都是开放、免专利的),维护成本比视频低一个数量级。
所以这里只做音频:WAV 已完整(含 G.711 与两种 ADPCM),AIFF PCM 已支持,FLAC 子帧集合已完整(官方 13 个向量全部整文件逐样本对齐),Ogg Vorbis 已完整解码,Ogg Opus 的 CELT + SILK + Hybrid 三层都已能解码(立体声 Hybrid/SILK 除外,见上)。
const std = @import("std");
const audio = @import("zig_audio");
pub fn main() !void {
const io = std.Io.Threaded.global_single_threaded.io();
var file = try std.Io.Dir.cwd().openFile(io, "music.wav", .{});
defer file.close(io);
// 流式:reader 只需要一块自己的缓冲区,不需要把整个文件读进内存。
var read_buf: [64 * 1024]u8 = undefined;
var file_reader = file.reader(io, &read_buf);
var dec = try audio.open(std.heap.page_allocator, &file_reader.interface);
defer dec.deinit();
// dec.info: 采样率、声道数、源位深、总帧数(未知时 null)
var pcm: [8192]i16 = undefined;
while (true) {
const n = try dec.read(&pcm); // 交错 i16,n == 0 表示结束
if (n == 0) break;
// pcm[0..n] 可以直接交给播放器;dec.info.channels 个 i16 为一帧。
}
}只想知道格式、不想消费流:
// header 至少 4 字节(FLAC/MP3 sync)或 12 字节(WAV);Ogg 需要 36 字节才能看到首包魔数。
// 函数不读 reader,也不修改切片。
if (audio.probe(header)) |format| {
// format == .wav、.flac、.mp3、.aiff、.ogg_vorbis 或 .ogg_opus
// .ogg_opus 现在也能 open:纯 CELT 的流会真的出 PCM。
}想在不解码的前提下看 Opus 的结构(这一轮新增):
var reader = std.Io.Reader.fixed(bytes);
const info = try audio.opus.inspect(allocator, &reader, "");
// info.channels、info.pre_skip、info.total_frames(已是真实音频长度)、
// info.granule(= ffprobe 的 duration_ts)、info.packets、info.configs[0..31]
// 以及 info.sample_rate,恒为 48000。
// audio.opus.Decoder.open(...) 返回会解码的 Decoder;CELT/SILK/Hybrid 包都出 PCM,
// 3 帧以上的包与立体声 SILK/Hybrid 包在 read() 上返回 error.Unsupported。已经有整段字节,或只想交出 std.Io.File:
// 不复制 bytes;调用方保证它在 dec.deinit() 之前一直有效。
var dec = try audio.openBytes(allocator, bytes);
defer dec.deinit();
// 流式读文件;库不拥有 file,deinit 不会关闭它(读缓冲 64 KiB)。
var dec2 = try audio.openFile(allocator, file);
defer dec2.deinit();probe() 是纯函数;open() / openBytes() / openFile() 都会消费流(openFile 从 offset 0 开始)。它们都不“猜”格式:认不出来就是 error.NotAudio。
open() 只要求一个 *std.Io.Reader。这不是“本库不认识你的文件”的借口,而是入口:任何能按字节产出数据的文件层,都可以用一块自己的缓冲包成 Reader。不需要把整个文件读进内存,也不需要本库认识你的 HANDLE。
OTTO 的第一版集成是:CreateFileW → 把整个文件读进内存 → std.Io.Reader.fixed(bytes)。它能出声,但峰值内存 = 压缩文件 + 解出的 PCM;一个 200 MB 的 FLAC 会先占 200 MB,再叠加 PCM。这正是“流式解码器”最容易自欺的地方:解码器是流式的,喂给它的却是全量缓冲。
openFile() 内部也只是 file.reader(io, &buffer)(64 KiB)+ open():文件多大都只占这一块读缓冲。测试里用 512 KiB 的 WAV + 128 KiB 的固定分配器验证了这一点——如果实现预读整个文件,openFile 会直接 OutOfMemory。另一个测试给 Io 套了计数 vtable:一个 524332 字节的 WAV 只发了 68 次文件读(平均约 7.5 KiB/次),而不是一次 512 KiB——既没有整文件缓冲,也没有按字节读。
假设你的文件层已经有一个“往 dst 写、返回字节数、0 表示 EOF”的函数:
/// 你的文件层:Win32 HANDLE、自己的预读缓冲、内存映射、网络流……都可以。
/// `readFn` 就是把你已有的读文件函数接上来(I/O 失败返回 error.ReadFailed)。
const Handle = struct {
ctx: *anyopaque,
readFn: *const fn (ctx: *anyopaque, dst: []u8) std.Io.Reader.Error!usize,
fn read(self: Handle, dst: []u8) std.Io.Reader.Error!usize {
return self.readFn(self.ctx, dst);
}
};
const HandleReader = struct {
handle: Handle,
interface: std.Io.Reader,
const vtable = std.Io.Reader.VTable{
.stream = stream,
.readVec = readVec,
};
/// `buffer` 由调用方持有,必须比 Decoder 活得久。
fn init(handle: Handle, buffer: []u8) HandleReader {
return .{
.handle = handle,
.interface = .{ .vtable = &vtable, .buffer = buffer, .seek = 0, .end = 0 },
};
}
fn self(r: *std.Io.Reader) *HandleReader {
return @alignCast(@fieldParentPtr("interface", r));
}
fn stream(
r: *std.Io.Reader,
w: *std.Io.Writer,
limit: std.Io.Limit,
) std.Io.Reader.StreamError!usize {
const dst = limit.slice(try w.writableSliceGreedy(1));
const n = self(r).handle.read(dst) catch return error.ReadFailed;
if (n == 0) return error.EndOfStream;
w.advance(n);
return n;
}
/// Reader 的其余 API(readSliceShort / peekByte / discard …)最终都会
/// 落到 stream 或 readVec 上。readVec 的契约里有一条容易漏:
/// `data[0]` 可能长度为 0,此时实现**必须写 Reader.buffer 并返回 0**。
/// 若返回 0 却什么都不写,fillUnbuffered 会永远循环(OTTO 踩过)。
fn readVec(r: *std.Io.Reader, data: [][]u8) std.Io.Reader.Error!usize {
if (data.len == 0) return 0;
if (data[0].len != 0) {
const n = self(r).handle.read(data[0]) catch return error.ReadFailed;
if (n == 0) return error.EndOfStream;
return n;
}
// 没有调用方目的地:填 Reader.buffer,返回 0 是“已填好,不是 EOF”。
// fillUnbuffered 在调用 readVec 前已经 rebase,保证这里仍有空间。
const space = r.buffer[r.end..];
if (space.len == 0) return error.EndOfStream;
const n = self(r).handle.read(space) catch return error.ReadFailed;
if (n == 0) return error.EndOfStream;
r.end += n;
return 0;
}
};接到本库:
var my_file: MyFile = .{ .handle = h, .offset = 0 };
const handle = Handle{ .ctx = &my_file, .readFn = MyFile.readSome };
var read_buffer: [64 * 1024]u8 = undefined;
var reader = HandleReader.init(handle, &read_buffer);
var dec = try audio.open(allocator, &reader.interface);
defer dec.deinit();
var pcm: [8192]i16 = undefined;
while (true) {
const n = try dec.read(&pcm);
if (n == 0) break;
// pcm[0..n] 是交错 i16;reader 与 read_buffer 必须活到 dec.deinit()。
}两个常见变体:
- 已经有一整段内存:用
openBytes(allocator, bytes),它就是Reader.fixed的糖;不复制字节,也不接管它的生命周期。 - 已经是
std.Io.File:用openFile(allocator, file)(单线程阻塞,内部用std.Io.Threaded.global_single_threaded)或openFileWithIo(allocator, io, file)(调用方自带Io,适合并发/取消/自定义事件循环)。库不拥有文件,deinit不关闭它。
| WAV 变体 | 状态 | 说明 |
|---|---|---|
| RIFF/WAVE,PCM 8 位(无符号) | ✅ | 按 WAV 约定 128 == 静音 |
| PCM 16 / 24 / 32 位 | ✅ | 24 位取高 16 位,32 位右移 16;输出统一为 i16 |
| IEEE float 32 位 | ✅ | clamp 到 [-1, 1],NaN → 0,±inf → 边界值 |
| PCM µ-law(tag 7)/ A-law(tag 6) | ✅ | ITU-T G.711 表在 comptime 生成,展开为 16 位线性;bits_per_sample 报 16 |
| IMA ADPCM(tag 0x11) | ✅ | 每块独立重置 predictor/step index;8 样本一组、每声道 4 字节;bits_per_sample 报 16 |
| Microsoft ADPCM(tag 0x02) | ✅ | 预测系数从 fmt 扩展读(不写死);1–2 声道;bits_per_sample 报 16 |
WAVE_FORMAT_EXTENSIBLE(PCM / IEEE_FLOAT 子格式) |
✅ | 校验 16 字节 GUID |
| 24-in-32(容器 32 位、valid bits 24) | ✅ | 按容器对齐读取,bits_per_sample 报 32 |
| 任意采样率 | ✅ | 不重采样,原样报告 |
| 1–64 声道 | ✅ | 原样保留声道数,不做下混;>64 声道明确拒绝 |
未知 chunk(LIST / fact / JUNK …) |
✅ | 跳过;奇数长度补 1 字节 padding |
fmt 长度 16 / 18 / 40+ |
✅ | 多余字节跳过;重复 fmt 忽略后一个 |
data 长度 = 0xFFFFFFFF |
✅ | 视为“读到 EOF”,total_frames = null(ffmpeg 写管道时就是这样) |
data 在 fmt 之后、但 data 不是最后一个 chunk |
✅ | 找到 data 立即开始解码;其后的 chunk 不再扫描 |
| RIFF 长度字段错误 | ✅ | 不依赖 RIFF 长度,按 chunk 自身长度扫描 |
| 变体 | 错误 | 原因 |
|---|---|---|
RIFX(大端 RIFF) |
error.Unsupported |
只支持 little-endian RIFF |
RF64 |
error.Unsupported |
64 位长度容器不在当前范围 |
| GSM 6.10(0x0031)、MP3-in-WAV(0x0055)等其它压缩 tag | error.Unsupported |
压缩/有损格式,解码器不内置 |
IMA / MS ADPCM 的 2/3/5 位变体(bits != 4) |
error.Unsupported |
只做 WAV 的 4 位定义 |
| MS ADPCM 超过 2 声道 | error.Unsupported |
ffmpeg 对 >2 声道用逐声道平面布局,本轮不做 |
MS ADPCM 系数表为 0 组 / 超过 16 组 / cbSize 不足 |
error.Corrupt / error.Unsupported |
头部自相矛盾 / 工程上限 |
| PCM 12 / 20 位等非字节对齐位深 | error.Unsupported |
只支持 8/16/24/32 |
| IEEE float 64 位 | error.Unsupported |
只支持 float32 |
data 在 fmt 之前 |
error.Unsupported |
流式解码无法回退去重读 data;不猜、不缓冲整个文件 |
| 超过 64 声道 | error.Unsupported |
明确的工程上限,避免帧大小失控 |
PCM 的 block_align 与声道×位深不一致 |
error.Corrupt |
头部自相矛盾 |
PCM 的 data 长度不是整帧 |
error.Corrupt |
半帧不是有效音频(ADPCM 允许最后一个块不完整,按实际字节数解码) |
ADPCM 的 block_align 小于块头 / 数据短于一个块头 |
error.Corrupt |
块布局自相矛盾,解码不了 |
| IMA 块头的 step index > 88、MS 块头的 predictor 越界 | error.Corrupt |
头部自相矛盾 |
fmt 长度 < 16、EXTENSIBLE 的 cbSize < 22、valid bits 越界 |
error.Corrupt |
头部结构损坏 |
| 流在头部/数据中途结束 | error.Truncated |
不把截断当正常 EOF |
多个 data chunk |
流式解码在第一个 data 结束;后续数据忽略 |
| AIFF 变体 | 状态 | 说明 |
|---|---|---|
FORM/AIFF 容器、COMM + SSND |
✅ | 大端;未知 chunk 按 AIFF 奇数长度 padding 跳过;重复 COMM 忽略后一个 |
| PCM 8 / 16 / 24 / 32 位 | ✅ | 全部大端;8 位是有符号的,与 WAV 的 128 偏置不同 |
| 任意整数采样率(80 位扩展浮点) | ✅ | u128 解析 mantissa * 2^(exp - 16383 - 63),不查表;小数按就近舍入 |
COMM 帧数声明 |
✅ | Info.total_frames 用声明值;SSND 实际字节更少时,读完前缀后返回 error.Truncated |
SSND 的 offset 字段 |
✅ | 跳过 offset 字节再读采样 |
AIFC(压缩格式,含 fl32/fl64 浮点) |
error.Unsupported |
需要解析压缩类型字段,本轮不做 |
AIFF 中的 ADPCM(AIFC 的 ima4 等) |
error.Unsupported |
属于 AIFC 压缩类型,同上 |
| 20 位等非字节对齐 PCM | error.Unsupported |
只做 8/16/24/32 |
32 位浮点 AIFF(fl32/fl64) |
error.Unsupported |
容器是 AIFC,本轮明确不做 |
SSND 在 COMM 之前 |
error.Unsupported |
流式解码无法回退去重读采样 |
COMM < 18 字节、SSND < 8 字节、offset 越过 payload |
error.Corrupt |
头部自相矛盾 |
| 流在 chunk 中途结束 | error.Truncated |
不把截断当正常 EOF |
| 变体 | 错误 | 原因 |
|---|---|---|
| 32 位 FLAC 的 side 声道 | error.Unsupported |
side 需要 33 位,超出 i32 帧缓冲与 32 位位读取器;明确拒绝而不是截断最高位 |
| 保留的声道分配 11–15、保留的子帧类型、保留的位深/块大小/采样率编码 | error.Corrupt |
格式本身不允许 |
| 帧头 CRC-8 或帧尾 CRC-16 不匹配 | error.Corrupt |
坏帧不会被当成好音频 |
| 帧的 block size 大于 STREAMINFO 的 max block size | error.Corrupt |
头部自相矛盾,且会越过已分配的帧缓冲 |
| 元数据 / 帧中途 EOF | error.Truncated |
不把截断当正常结束 |
| 输入开头 | probe() |
open() |
|---|---|---|
RIFF … WAVE |
.wav |
尝试按 WAV 打开(PCM / float / EXTENSIBLE / G.711 / IMA / MS ADPCM) |
fLaC |
.flac |
尝试按 FLAC 打开(支持 CONSTANT / VERBATIM / FIXED / LPC + 三种去相关) |
FORM … AIFF |
.aiff |
尝试按 AIFF 打开(大端 PCM 8/16/24/32) |
FORM … AIFC |
null |
error.Unsupported |
OggS + 首包 \x01vorbis(需要 ≥ 36 字节才能看到首包魔数) |
.ogg_vorbis |
解析 Ogg + Vorbis 头后返回可读 PCM 的 Decoder |
OggS + 首包 OpusHead(同样需要 ≥ 36 字节) |
.ogg_opus |
解析 Ogg + OpusHead/OpusTags 后返回 Decoder;CELT/SILK/Hybrid 包都出 PCM,3 帧以上的包与立体声 SILK/Hybrid 包在 read() 上 error.Unsupported |
OggS + 其它/未知逻辑流 |
null |
error.Unsupported |
RF64 / RIFX + WAVE |
null |
error.Unsupported |
| 其他 | null |
error.NotAudio |
probe() 宁可返回 null 也不把“看起来像”的东西当成可解码格式。.ogg_opus 是一个已识别、且部分可解码的格式:probe 如实报出容器与编码器,open 返回真正会解码的 Decoder,CELT/SILK/Hybrid 包都出 PCM,3 帧以上的包与立体声 SILK/Hybrid 包在 read() 上明确返回 error.Unsupported——打开成功不代表每条包都能解,因为包的编码模式写在包里。open() 也不接受 probe() 不会返回的格式。
pub const Format = enum { wav, flac, mp3, aiff, ogg_vorbis, ogg_opus };
pub const Info = struct {
format: Format,
sample_rate: u32,
channels: u16,
bits_per_sample: u16, // 源位深:WAV 报容器位深(float 报 32,G.711/ADPCM 报 16);
// FLAC 报真实位深 4..32;AIFF 报 COMM 的位数
total_frames: ?u64, // 头部声明;流式容器/未知总长时为 null
};
pub const Error = error{
NotAudio, // 不是本库认识的音频签名
Unsupported, // 认识但不支持(FLAC 32 位 side 声道、AIFC、RIFX/RF64、GSM…)
Truncated, // 流在完整头部/帧之前结束
Corrupt, // 头部字段自相矛盾、CRC 不符或结构损坏
OutOfMemory, // open 时分配失败(FLAC 分配一帧缓冲;WAV 的 ADPCM 分配一块)
Io, // 底层 Reader 报告 ReadFailed;不是格式错误
ShortBuffer, // 调用方给的输出缓冲比一帧还小
};
pub fn probe(header: []const u8) ?Format;
pub fn open(allocator: std.mem.Allocator, reader: *std.Io.Reader) Error!Decoder;
pub fn openBytes(allocator: std.mem.Allocator, bytes: []const u8) Error!Decoder;
pub fn openFile(allocator: std.mem.Allocator, file: std.Io.File) Error!Decoder;
pub fn openFileWithIo(allocator: std.mem.Allocator, io: std.Io, file: std.Io.File) Error!Decoder;
pub const Decoder = struct {
info: Info,
pub fn read(self: *Decoder, out: []i16) Error!usize;
pub fn deinit(self: *Decoder) void;
};四个入口的区别:
| 入口 | 数据来源 | 生命周期 | deinit() 释放什么 |
|---|---|---|---|
open |
调用方的 *std.Io.Reader |
reader 必须比 decoder 活得久 | 只释放 decoder 自己的内存 |
openBytes |
bytes 切片,不复制 |
bytes 必须比 decoder 活得久 |
reader 记录(不释放 bytes) |
openFile |
std.Io.File,64 KiB 流式读缓冲 |
file 必须比 decoder 活得久 | 读缓冲 + reader 记录(不关 file) |
openFileWithIo |
同上,但 Io 由调用方给 |
同上 | 同上 |
- 输出只有一条路径:交错 i16。8/16/24/32 位 PCM 和 float32 都在解码器内部转换;播放器不需要按源格式分支。
- 调用方给缓冲:
read()只在out里写,不分配;open()/openBytes()/openFile*()是仅有的可能使用 allocator 的地方(WAV 的 PCM/float/G.711 不分配帧缓冲,ADPCM 分配一个压缩块和解码块;FLAC 按 STREAMINFO 的 max block size 分配一帧 i32 缓冲;两个便利入口还会分配 Reader 状态,openFile*另加 64 KiB 读缓冲)。 read()的容量:能解out.len / info.channels帧。out.len不是声道数的整数倍时,只解完整帧,尾部 i16 不碰;out.len == 0返回 0;0 < out.len < channels返回error.ShortBuffer。- 返回的是写入的 i16 个数,一定是
channels的整数倍;0表示流结束。 - 前缀语义(FLAC / MP3 / Ogg Vorbis / Ogg Opus):如果某一帧/块/包失败(CRC、截断、32 位 side),此前已经解出的样本会先返回;下一次
read()返回同一个错误。调用方既能拿到合法音频,也能看到具名失败,而不是被“半段静音”糊弄。WAV / AIFF 是按调用全有或全无:出错的那次调用不返回样本,前缀只来自更早的成功调用;两种规则都在下面的跨格式契约表里,并由矩阵测试逐格式断言。 - 声道原样保留:不做下混、不做上混、不做采样率转换。5.1 就是 6 声道。
- reader / 文件生命周期:
open的reader由调用方持有;openBytes的bytes不被复制;openFile*的file不被关闭。三者都必须比Decoder活得久,deinit()只释放 decoder 自己分配的东西。 - 错误后不复用:
read()返回错误后,同一个错误会粘住(再次read()返回同一个具名错误,不会变成 0 或另一种错误),但 decoder 的状态不再保证可恢复,直接deinit();不要用“再读一次”来探测错误是否消失。 - 入口会消费流:
open()读取 12 字节签名并扫描元数据/chunk,直到首个音频帧(WAV 是data负载,FLAC 是第一帧)起点;openFile*用 positional reader 从 offset 0 开始;失败时也可能已经消费了最多 12 字节(甚至更多头部)。Ogg 的open()只读到三个 Vorbis 头包就返回流式 decoder;Opus 的opus.open()只读OpusHead/OpusTags两个头包就返回 decoder,两者的total_frames都要读到末页 granule 才知道,所以read()到 EOF 后才填上;opus.inspect()则把结构视图交出来。想先判断而不消费,用probe()(需要调用方自己准备那几字节;Ogg 要 36 字节)。 - 错误不吞:截断、损坏、不支持、I/O 失败分别有具名错误;不使用
catch {}把问题变成静音。
短缓冲矩阵(src/stream_matrix_test.zig,数据由 src/stream_builders.zig 在内存里构造,纯 L1)对每一种 decoder 跑同一组调用方缓冲大小:满缓冲(对照组)、1 个 i16、3、7、13 个 i16、固定种子的随机 1..64 个 i16,以及“小缓冲/满缓冲交替”的混合序列。缓冲大小按 i16 元素算,不按帧算;解码器每次最多解 out.len / channels 帧。26 个变体(WAV PCM 8/16/24/32、float32、EXTENSIBLE PCM/float、µ-law、A-law、IMA ADPCM、MS ADPCM;AIFF 8/16/24/32;FLAC 8/12/16/24;MP3 单/立体声;Vorbis 单/立体声;Opus 单/立体声)× 7 种缓冲 = 182 个格子,断言:
- 拼接起来的所有样本与满缓冲解码逐样本相等:不重复、不丢失、不插入静音;
- 非帧对齐的尾部(
out[n..out.len],n是实际写入数)不被写;测试先填哨兵值再检查; out.len == 0返回 0 且不推进状态;EOF 之后重复read()返回 0,不返回错误;0 < out.len < channels(例如立体声 + 1 个 i16)返回ShortBuffer且不消费任何样本,随后换回大缓冲必须从原位置继续;read()期间的单次分配 ≤ 512 B(上限写在测试里;实测:WAV/AIFF/FLAC/MP3 为 0 B,Vorbis 的包前瞻ArrayList最大 134 B,Opus 最大 204 B),且总分配量与调用方缓冲大小无关(逐变体对比满缓冲基线的字节总数)。open()按 STREAMINFO 分配的一帧缓冲、Ogg 的 64 KiB 页缓冲都不算在内,它们在read()之前完成。
截断输入的行为(头部完整、音频负载被切掉 20 字节,切点落在最后一帧/页内部):
| 格式 | 出错的那次 read() |
可解前缀 | 之后再次 read() |
|---|---|---|---|
| WAV PCM / G.711 | 返回 error.Truncated,该次调用不返回样本 |
只来自更早的调用 | 同一个 Truncated |
| WAV IMA / MS ADPCM | 返回 error.Truncated;同一次调用里已从上一块拷出的样本会被丢弃 |
只来自更早的调用(完整块) | 同一个 Truncated |
| AIFF | 返回 error.Truncated,该次调用不返回样本 |
只来自更早的调用 | 同一个 Truncated |
| FLAC | 先返回本次已解出的样本,错误挂起 | 是 | 同一个 Truncated |
| MP3 | 同上 | 是 | 同一个 Truncated |
| Ogg Vorbis | 同上 | 是 | 同一个 Truncated |
| Ogg Opus | 同上 | 是 | 同一个 Truncated |
所有行共同的断言:前缀是未截断解码结果的精确前缀,且严格短于它;不存在“补零到缓冲末尾”“返回 0 样本假装 EOF”或“前缀里混入静音”的行为。测试在 src/stream_contract_test.zig。
上面这套矩阵在 src/fixtures_test.zig 里还有一份真实素材版本(L2):MP3 单/立体声、Vorbis、FLAC 24-bit、WAV 5.1 五个仓库内 440 Hz fixture × 同一组 7 种缓冲 = 35 格。原因是 L1 合成流里 MP3 mono 与 Vorbis 的样本本身是静音(没有真实编码内容),只靠长度无法发现“等长但值被交换”的错误;真实素材把这一格补成逐样本断言。
open() 的错误映射(每种格式 × 同一组坏输入;断言的是错误类别,不是“有错就行”,并且 open 成功 + 首个 read 静默返回 0 也算失败):
| 输入 | WAV | AIFF | FLAC | MP3 | Vorbis | Opus |
|---|---|---|---|---|---|---|
| 空流 | NotAudio |
NotAudio |
NotAudio |
NotAudio |
NotAudio |
NotAudio |
| 随机字节(magic 不匹配) | NotAudio |
NotAudio |
NotAudio |
NotAudio |
NotAudio |
NotAudio |
| 真头、截到 12 字节 | Truncated |
Truncated |
Truncated |
Truncated |
Truncated |
Truncated |
| magic 被改坏 | NotAudio |
NotAudio |
NotAudio |
NotAudio |
NotAudio |
NotAudio |
底层 Reader 报 ReadFailed |
Io |
Io |
Io |
Io |
Io |
Io |
| 认识但拒绝 | Unsupported(RF64) |
Unsupported(AIFC) |
open 阶段无此类(见下) |
Unsupported(MPEG-2) |
Unsupported(未知 Ogg codec) |
Unsupported(mapping family 2) |
| 结构损坏 | Corrupt(fmt 块对齐矛盾) |
Corrupt(COMM 过短) |
Corrupt(STREAMINFO 块大小为 0) |
Corrupt(bitrate index 15) |
Corrupt(页 CRC 不符) |
Corrupt(OpusHead version 0) |
FLAC 唯一的 Unsupported 是帧级判定:32 位去相关流的 side 子帧会是 33 位,open 无法在不解一帧的情况下知道,所以 open 成功、read 返回 error.Unsupported(同一张契约测试里断言)。
read() 只输出一种格式:交错、帧优先的 i16。第 f 帧第 c 声道在 out[f * channels + c],一帧内声道顺序与源文件一致。
| 源格式 | 转换规则 | 说明 |
|---|---|---|
| WAV 8-bit unsigned PCM | (byte - 128) << 8 |
128 → 0,0 → -32768,255 → 32512 |
| WAV 16-bit PCM | 原样复制 | 逐位不变 |
| WAV 24-bit PCM | 算术右移 8 位(丢低 8 位) | 与 ffmpeg -f s16le 一致;不是四舍五入 |
| WAV 32-bit PCM | 算术右移 16 位(丢低 16 位) | 同上 |
| WAV float32 | clamp 到 [-1, 1],NaN → 0,±inf → ±满量程;round(x * 32768),1.0 → 32767 |
float 源的舍入不属于 WAV 格式,允许与其它实现差 1 LSB |
| WAV µ-law / A-law | 查表展开到 16 位 | ITU-T G.711 comptime 表,逐码精确;bits_per_sample 报 16 |
| WAV IMA / MS ADPCM | 块解码到 16 位 | 每块重置状态;total_frames 含末块填充样本,与 ffmpeg 一致 |
| AIFF 8-bit | sample << 8(有符号) |
与 FLAC 8 位相同,不是 WAV 的 128 偏置 |
| AIFF 16-bit | 原样复制(大端读取) | |
| AIFF 24-bit | 算术右移 8 位 | 取高 16 位 |
| AIFF 32-bit | 算术右移 16 位 | 取高 16 位 |
| FLAC 8-bit | sample << 8(有符号) |
0 → 0,-128 → -32768,127 → 32512;没有 WAV 的 128 偏置 |
| FLAC 12-bit | sample << 4 |
12 位源占满 i16 |
| FLAC 16-bit | 原样复制 | |
| FLAC 20-bit | 算术右移 4 位 | 取高 16 位 |
| FLAC 24-bit | 算术右移 8 位 | 取高 16 位,与 ffmpeg -f s32le >> 16 一致 |
| FLAC 32-bit | 算术右移 16 位 |
FLAC 的通式:bits <= 16 时左移 16 - bits,bits > 16 时算术右移 bits - 16;Info.bits_per_sample 始终报告真实源位深,不因为输出是 i16 而改变。
- 声道顺序按源文件原样保留(WAV/FLAC 的标准声道顺序),不做下混、上混或矩阵变换。
- 输出是 native
i16(当前所有 CI 目标都是 little-endian);和 ffmpeg-f s16le对比时按 little-endian 写字节。 - 整数 PCM 的转换与 ffmpeg 逐样本一致,由
src/compare.zig在集成测试里验证;FLAC 的 8/12/20/24/32 位由合成流与 ffmpeg 交叉验证(src/flac_test.zig)。
Error增加Io与ShortBuffer。前者把底层 Reader 的传输失败与“字节内容损坏”分开,后者让“输出缓冲比一帧还小”变成具名错误,而不是伪装成 EOF 的0。read()的帧容量按out.len / channels计算(草稿注释里的channels * 2是按字节算的;out是i16切片,所以按元素算)。Info.bits_per_sample明确是源位深。WAV 报容器位深(24-in-32 报 32;EXTENSIBLE 的 valid bits 不单独暴露);FLAC 报真实的 4..32 位,因为输出统一 i16 后仍需要这个值来计算移位。- 不做多声道下混。OTTO 的播放路径下混到立体声,因为 WASAPI 共享模式需要;解码库应该把 5.1 原样交给调用方,由播放策略决定。
open()自己读 12 字节做格式分派,不依赖Reader.buffer.len >= 12,因此任意小缓冲的 Reader 都能用。probe()保持纯切片接口。deinit()不带 allocator 参数;allocator 在open()时存进 decoder,FLAC 的帧缓冲释放不需要调用方再传一次。- FLAC 的帧级错误采用前缀语义:先把已解出的样本返回,再在下一次
read()返回错误。否则调用方拿到的只有"整块失败",一个 4000 帧的正常前缀就白解了。
- 流式:
open()只读到首个音频帧起点,read()按调用方的缓冲大小推进;openFile()用 64 KiB 读缓冲,不把整个文件读进内存。 - 调用方提供缓冲:
read()没有隐藏分配,也没有内部 PCM 环形缓冲。 - 解码器无全局状态:没有单例、没有线程局部缓存、没有全局注册表;两个 decoder 可以并发解不同的流。唯一的例外是
openFile()这个不带Io的便利入口——它必须从某处拿到Io,使用的是 std 的Threaded.global_single_threaded(单线程、阻塞)。需要并发、取消或自定义事件循环时,用openFileWithIo()或open()。 - 无分配(或显式 allocator):WAV 的 PCM / float / G.711 路径零分配;WAV 的 ADPCM 在
open*()用调用方的 allocator 分配一个压缩块 + 一个解码块;FLAC 在open*()分配一帧的 i32 缓冲;read()永远不分配;deinit()释放。 - 显式错误:
NotAudio/Unsupported/Truncated/Corrupt/Io/OutOfMemory/ShortBuffer;没有“静音代替错误”。 - 可 fuzz:解析器只接受
[]const u8和std.Io.Reader,没有文件系统、线程、时间依赖;zig build fuzz对 12 种合法模板(WAV / FLAC / MP3 mono / MP3 stereo / µ-law / A-law / IMA ADPCM / MS ADPCM / AIFF16 / AIFF24 / Ogg-Vorbis / Ogg-Opus)做随机变异,断言不 panic、不越界、错误具名。
需要 Zig 0.17.0。零外部依赖、零 C、禁止 @cImport。
zig build # 编译库(static lib 到 zig-out/)
zig build test # 单元 + API + fixture + ffmpeg 集成 + 1000 轮变异 fuzz(12 种模板,329 个测试)
zig build fuzz # 10000 轮变异 fuzz(WAV / FLAC / MP3 / G.711 / ADPCM / AIFF / Ogg-Vorbis / Ogg-Opus 共 12 种模板)
zig build bench # 10 秒 WAV + 各 20 秒 FLAC(固定预测 / LPC)、MP3 与老格式解码基准(ReleaseFast;低于目标会失败)实时 ffmpeg 对照只存在于测试和对照工具中,公共库模块不依赖 ffmpeg。路径按以下严格优先级解析;高优先级一旦设置,即使路径错误也不会悄悄回退:
ZA_FFMPEG_PATH:可以是 ffmpeg 可执行文件的完整路径,也可以是包含它的bin目录;- 仓库根目录的
ffmpeg.path:单行路径,规则同上;此文件已加入.gitignore,用于本机配置,不入库; - 原开发机默认路径:仅作为向后兼容的本机便利。
第一次调用会打印 ffmpeg: source=env|file|default path=...。找不到可执行文件时,每个受影响用例都会打印名称和 ffmpeg_unavailable 原因;ffmpeg 已启动但返回失败则是测试失败,不会伪装成 skip。
测试汇总分为四层:L1 纯库、L2 仓库内固定小样本、L3 外部向量结构/元数据对照、L4 实时 ffmpeg 对照。凡需实时 ffmpeg 的外部向量逐样本用例也归入 L4。每层打印 executed=N compared=M skipped=...;compared 是完成参考值/固定向量/ffmpeg 对照的测试数,不是样本数。
开发机默认仍允许 L4 skip,但发布门不允许:
# 新机器 / CI 的最小发布门命令(路径换成实际 exe 或 bin 目录)
ZA_FFMPEG_PATH=/path/to/ffmpeg zig build test -Drequire-ffmpeg=true
# PowerShell
$env:ZA_FFMPEG_PATH = 'C:\tools\ffmpeg\bin'
zig build test -Drequire-ffmpeg=true
# 也可用环境变量开启同一道门,不必重新编译选项
ZA_REQUIRE_FFMPEG=1 zig build test-Drequire-ffmpeg=true 或 ZA_REQUIRE_FFMPEG=1 会把任何 L4 skip 都提升为失败,逐个打印用例名与原因;这包括 external_vectors_missing,所以发布环境还必须准备好下面列出的外部向量。测试运行步骤不重用上一次的环境结果,修改 ZA_FFMPEG_PATH 后不会因为构建缓存而沿用“全绿”。
仓库还提交了 0.02 秒的 ffmpeg 生成音频样本(src/fixtures/,总计约 200 KB):没有 ffmpeg 的普通开发测试也能解码真实的 PCM8/16/24/32、float32、5.1 WAV,以及固定预测和 LPC(mono 8 kHz、stereo 44.1 kHz order 32 mid/side)的 FLAC;其中的 stereo LPC 文件还与其同源 WAV 逐样本一致。Opus 侧另有 2 秒 SILK 与 2 秒纯 Hybrid 素材。
tools/fetch-vectors.ps1:把 13 个 ietf-wg-cellar/flac-test-files 官方向量下载到.zig-cache/vectors/,逐个做 SHA-256 校验;向量不进 git。向量缺失时默认打印原因并SkipZigTest;发布门会拒绝涉及 L4 对照的缺失。src/compare.zig:测试辅助。把本库解出的 i16 与 ffmpeg 的-f s16le、-f s32le >> 16逐样本比较,并支持“截断流的可解前缀”对比(60 号向量的 50% 截断用例)。src/flac_build.zig:测试专用的小型 FLAC 编码器,用来造 CONSTANT / VERBATIM / FIXED / LPC、各种位深、块大小扩展、wasted bits、escape code、LPC 精度/阶数/正负 shift,以及 L/S、R/S、M/S 三种去相关声道的精确用例;不参与库代码。src/stream_builders.zig:测试专用的全格式合成流(26 个变体,全部在内存里构造);短缓冲矩阵与错误映射契约共用,不参与库代码。src/stream_matrix_test.zig:短缓冲矩阵(26 变体 × 6 种缓冲 = 156 格)与read()分配上限/独立性断言,纯 L1。src/stream_contract_test.zig:截断前缀语义与open()错误映射两张契约表,纯 L1。src/legacy_vectors_test.zig:G.711 / ADPCM / AIFF 六个 2 秒素材对 ffmpeg 的整文件逐样本验收;素材放在仓库外的..\zig-audio-vectors\legacy,缺失时默认打印原因并SkipZigTest,发布门下则失败。
src/root.zig 公共 API(probe / open / openBytes / openFile / Decoder)
src/types.zig 公共类型(Format / Info / Error)
src/wav.zig 流式 WAV 解码器(PCM / float / G.711 / ADPCM 分派)
src/g711.zig ITU-T G.711 µ-law/A-law 表(comptime 生成)
src/adpcm.zig IMA / Microsoft ADPCM 块解码与 fmt 扩展解析
src/aiff.zig 流式 AIFF 解码器(大端 PCM + 80 位扩展采样率)
src/flac.zig 流式 FLAC 解码器
src/flac_bits.zig MSB 位读取 + CRC-8 / CRC-16
src/flac_meta.zig STREAMINFO 与元数据块循环
src/flac_frame.zig 帧头、子帧、Rice 分区、帧尾 CRC
src/flac_build.zig 测试专用 FLAC 编码器(不进库)
src/ogg.zig Ogg 页、CRC-32、packet 拼装、首音频流选择
src/vorbis.zig Vorbis identification / comment / setup(floor、residue、mapping、mode)
src/vorbis_bits.zig LSB-first 位读取 + ilog / lookup1_values
src/vorbis_codebook.zig 码本长度表与 VQ lookup(含 type 1 lattice)
src/opus.zig Ogg Opus 入口(inspect 结构视图 / Decoder 流式解码,pre-skip 与 granule 裁剪)
src/opus_head.zig OpusHead / OpusTags(RFC 7845)
src/opus_packet.zig TOC 与帧打包(RFC 6716 §3.2):帧数、帧长、padding、每帧样本数
src/opus_range.zig 范围解码器(RFC 6716 §4.1):符号、raw bits、tell/tellFrac、Laplace
src/opus_celt_tables.zig CELT 常量表(48 kHz、21 频带):Table 57、caps、窗、IMDCT/FFT 旋转因子
src/opus_celt_energy.zig 粗/细/最终能量反量化(§4.3.2)
src/opus_celt_alloc.zig 比特分配(§4.3.3):预留、倾斜、两次二分、跳带、细能量分配
src/opus_celt_pvq.zig PVQ(§4.3.4.2):V(N,K)、cwrsi、扩散旋转、collapse mask
src/opus_celt_math.zig 比特精确的整数算术(bitexact_cos / isqrt32 / Q15 乘)+ folding LCG
src/opus_celt_bands.zig theta、递归分裂、单声道频带解码(§4.3.4)
src/opus_celt_frame.zig 立体声重建与逐帧频带循环(§4.3.4.4、§4.3.8)
src/opus_celt_post.zig anti-collapse 与反归一化(§4.3.5、§4.3.6)
src/opus_celt_dsp.zig IMDCT(混合基 FFT)、重叠相加、音高后滤波、去加重(§4.3.7)
src/opus_celt.zig 一帧的符号顺序与状态(§4.3、Table 56)
src/opus_silk.zig SILK 一帧的符号顺序与状态(§4.2):帧头、LBRR、增益、LSF、音高、激励、再白化 + LTP + LPC 合成
src/opus_silk_lpc.zig LSF→LPC:stage-2 反预测、稳定化、LSP→多项式→LPC、带宽扩展与稳定性检查
src/opus_silk_types.zig SILK 的每声道状态(LSF/LPC/增益/lag/两段历史)与带宽定义
src/opus_silk_resample.zig 8/12/16 kHz → 48 kHz,复刻 libswresample 在该配置下的多相滤波、流式缓冲与结尾 flush(镜像补尾)
src/opus_silk_tables_cdf.zig SILK 的算术模型(RFC 6716 §4.2 的 35 张 CDF 表)
src/opus_silk_tables_lsf.zig LSF 码本、权重、排序、cos 表
src/opus_silk_tables_pitch.zig 音高/LTP/激励/立体声表
src/opus_hybrid.zig Hybrid 与 SILK 包:共享范围解码器、SILK→48 kHz 对齐、SILK+CELT 逐声道时域相加、冗余帧 crossfade、立体声(mid/side + 每声道重采样)
src/ogg_build.zig / vorbis_build.zig / opus_build.zig 测试专用 Ogg 页 / Vorbis 头 / Opus 头与包的写入器(不进库)
src/stream_builders.zig / stream_matrix_test.zig / stream_contract_test.zig 全格式合成流 + 短缓冲矩阵 + 错误/前缀契约(不进库)
src/bench.zig WAV + FLAC + MP3 + Ogg + 老格式基准程序
src/fuzz.zig 变异 fuzzer(同时作为 1000 轮测试运行)
src/compare.zig 与 ffmpeg 逐样本比较的测试辅助
src/ffmpeg.zig 测试专用 ffmpeg 路径解析、来源审计与进程入口
src/test_audit.zig 测试分层、skip 原因与 L4 静态归类
src/test_runner.zig L1-L4 汇总和 require-ffmpeg 发布门
src/fixtures/ 提交进仓库的小样本 + 生成命令
src/*_test.zig 单元 / API / fixture / ffmpeg 集成测试
tools/ 官方 FLAC 测试向量下载脚本
MIT,见 LICENSE。作者:TLBtianhu。