ffmpreg 是一个用 Rust 编写的原生多媒体工具包，不依赖 FFmpeg，专注于写出安全的解码器。本文以 ffmpreg 的PCM 编解码器为例，带你拆解它的状态机设计，看看一套真正面向安全的 Rust 解码器，从数据结构到数据流到底是怎么组织的。

适合人群：Rust 初学者、想理解"解码器为什么难写安全"的开发者、以及好奇 ffmpreg 内部原理的普通用户。

🧩 先认识 ffmpreg：一个"安全优先"的多媒体工具包

ffmpreg 提供命令行工具和库 API 两种用法，能解码、变换、编码音视频。它的设计目标写在 readme.md 里非常直白：

• safe：尽量避免unsafe、减少unwrap、减少 panic
• deterministic：显式管线，行为可预测
• minimal：外部依赖尽可能少

更硬核的是，Cargo.toml 在 release 配置里写了一行panic = "abort"，注释是"Let it crash and force ourselves to write safe Rust"（宁可崩溃，也要逼自己写安全的 Rust）。

这就引出了本文的核心问题：一个安全的解码器，状态到底该长什么样？答案就是 ffmpreg 的状态机（state machine）设计。

🔄 解码器状态机：ffmpreg 的核心

传统 C 解码器喜欢用一个巨大的结构体装全局变量，靠"约定"来保证线程安全。ffmpreg 反其道而行：把状态显式地传进传出每一次解码调用。

解码器必须实现Decoder这个 trait，定义在 src/core/traits.rs：

trait Decoder { fn create_state(&self, parameters: &Parameters) -> State; // ① 创建初始状态 fn decode(&self, state: &mut State, packet: Packet) -> Result<DecodeOut<State>>; // ② 解码 fn flush(&self, state: &mut State) -> Result<DecodeOut<State>>; // ③ 冲刷缓冲 }

三个方法构成一个清晰的状态机：

注意decode的返回值类型DecodeOut<State>（src/core/traits.rs）——它是StepOutput<Vec<Frame>, S>，里面同时携带了解码结果（帧）和更新后的状态。也就是说，状态不会"藏在某个隐藏字段里偷偷变"，而是每一步都被显式交还出来。这让每个状态转换都可测试、可审计。

State 长什么样

状态本体是一个枚举，定义在 src/core/context/state.rs：

pub enum State { Audio(AudioState), Video(VideoState), }

对 PCM 来说走的是Audio分支。AudioState字段（src/core/context/state.rs）大致是：

• 采样参数：sample_rate、channels、format、layout
• 时间账本：内嵌CodecState，含pts、dts、last_pts、extradata
• 缓冲账本：samples_consumed、samples_produced、buffer

关键洞察：PCM 虽是"无压缩"格式，但一个Packet可能只对应半帧，或跨帧拼接。所以解码器必须用buffer+ 消费/产出计数器来记账，这正是状态机里buffer与samples_*字段存在的原因。

📁 PCM 编解码器在代码里的位置

PCM 模块非常精简，遵循"一文件一职责"的组织方式：

PcmDecoder在创建状态时，会把 Parameters 里的sample_rate、channels转成强类型，并填好默认值（unwrap_or(44100)），避免下游拿到None后崩溃。

// src/codecs/pcm/decoder.rs 中 create_state 的核心思路 let audio_state = AudioState { sample_rate: p.sample_rate.unwrap_or(44100), channels: Channels::from_value(p.channels.unwrap_or(2)), format: SampleFormat::S16, layout: SampleLayout::Interleaved, ... };

🛡️ 安全解码器的 4 个关键实践

读完 PCM 与 core 的代码，能总结出 ffmpreg 写"安全解码器"的几条通用手法，对新手特别有参考价值：

1️⃣ 用显式状态替代全局变量

状态作为参数进出decode，天然避免全局可变状态，多线程或多次调用都不会互相污染。上下文中解码态与编码态也被分开存放，见 src/core/context/context.rs：state_decode与state_encode各管各的。

2️⃣ 用"类型"表达约束，而不是裸数字

• 声道不是u8，而是Channels枚举（Mono/Stereo/Quad…Custom(u8)），见 src/core/frame/audio/format.rs。
• 采样格式是SampleFormat枚举，bytes()直接告诉你在内存里占几字节（src/core/frame/audio/format.rs）。
• 时间戳是Option<Time>，缺失就是显式的 None，而不是悄悄填 0。

类型对了，编译器就帮你挡掉一大类"格式不匹配"的 bug。

3️⃣ 错误用类型返回，而不是 panic

解码器返回的是Result<T, Message>，Message是个分类清晰的错误枚举，定义在 src/message/mod.rs：

pub enum Message { Io(std::io::Error), Other(&'static str), Container(&'static str), Codec(&'static str), }

预期的失败走Err，不会让进程中途崩溃，也不会依赖unwrap把小错误放大成灾难。

4️⃣ 算术用checked_方法防溢出

时间相加/相减时，ffmpreg 提供Time::checked_add/checked_sub（src/core/time.rs）：

• 时基（timebase）不一致 → 返回None
• 数值溢出 → 返回None

这样解码器遇到"时间对不上"或"数值爆炸"时会拿到一个可处理的None，而不是无声地回绕成错误结果。

🎬 一次完整的解码数据流

把上面的零件拼起来，一条音频管线的数据流非常直观：

容器(Reader) → Packet → [PcmDecoder] → Frame → 变换 → [PcmEncoder] → Packet → 容器(Writer) 解复用 解码(状态机) 编码 复用

对应到结构就是：

• Packet（容器里的编码数据）：见 src/core/packet/packet.rs
• AudioFrame（解码后的可处理数据）：见 src/core/frame/audio/audio.rs

数据流是单向、显式的，每一步的输入输出类型都很清楚——这正是"deterministic / explicit pipelines"目标的具体落地。

🔍 动手阅读：3 步读懂 ffmpreg 解码器源码

跟着这条路径读，10 分钟就能建立完整认知：

1. 先读 src/core/traits.rs：搞懂Decoder/Encoder三件套方法。
2. 再读 src/core/context/state.rs：理解State、AudioState、CodecState各字段在记账什么。
3. 最后读 src/codecs/pcm/decoder.rs：看PcmDecoder如何把参数转成强类型、初始化状态。

小提示：src/codecs/ 下的adpcm、raw、pcm都复用同一套Decodertrait 与State骨架，所以读懂 PCM 后，换到其它解码器只是"解码逻辑"变了，状态机的骨架不变。

❓ 常见问题（FAQ）

Q1：PCM 不压缩，为什么还需要"状态机"？因为一个Packet不一定对齐帧边界。状态机里的buffer和samples_consumed/produced负责把"半帧"攒齐、把"多出来的"留到下一包，这就是跨包记账。

Q2：ffmpreg 和直接用 FFmpeg 有什么区别？ffmpreg 用纯 Rust 重写、无 FFmpeg 依赖，把"安全、可预测"放在第一位：错误走类型返回、算术用checked、状态显式传递，更适合需要强安全保证与可审计性的场景。

Q3：panic = "abort"是干啥的？它在 release 下让 panic 直接终止进程而非尝试恢复，是一种"用崩溃倒逼代码写出安全"的工程手段，见 Cargo.toml。

📌 总结

• ffmpreg 的安全解码器核心是显式状态机：create_state → decode → flush，状态每步都被交还，不藏全局变量。
• PCM 编解码器虽简单，却完整体现了这套骨架：[src/codecs/pcm/decoder.rs](https://link.gitcode.com/i/4bd9757557130de56287e0b64bc5951b)+[src/codecs/pcm/encoder.rs](https://link.gitcode.com/i/69947171fce6b5b738697ff9fa31baee)。
• 四条可复用的安全手法：显式状态、类型即约束、错误走 Result、算术用 checked。

掌握这套思路，你就能写出既好用、又经得起安全审计的 Rust 解码器。