先交代利益关系:笔者是 Rust crate ez-ffmpeg 的作者(和 JS 圈那个上过 HN 的 "Ez FFmpeg" 无关,同名不同物)。所以本文写到限制那节会写得比别处更狠。
你在搜索框里敲的从来不是 "AVFormatContext 怎么初始化",而是 "ffmpeg 提取音轨命令"。命令你早背下了,换到 Rust 项目里真正卡住的是:这条命令对应哪段 API?过去一年这篇本该是一张手写对照表------你查表,一条条把 -c:v libx264 -crf 23 翻成 builder 调用。ez-ffmpeg 0.15 的 cli 特性做了件更省事、也更有意思的事:把命令字符串粘进去,它要么在进程内直接跑(from_cli),要么翻译成一段可编译的 Rust 代码给你(emit_rust_code)。
有意思的不是"能翻译",而是它翻译的态度 :它把每一条命令分成三类------验证过的 (可以跑)、没验证的 (只生成带醒目警告的脚手架代码、拒绝执行)、不认识的(当场用 token 级的类型化错误拒掉)。它宁可清清楚楚地拒绝你,也不"跑起来了,但结果和 ffmpeg 微妙地不一样"------后者才是真正毁信任的东西。这篇讲这套契约怎么用、为什么这么设计。
from_cli:粘命令,进程内跑起来
依赖开 cli 特性(底层仍链 libav,FFmpeg 7.1--8.x 该装还得装):
toml
[dependencies]
ez-ffmpeg = { version = "0.15", features = ["cli"] }一个转码命令,原样粘进去就跑,不起子进程:
rust
use ez_ffmpeg::cli::from_cli;
fn main() -> Result<(), Box<dyn std::error::Error>> {
from_cli("ffmpeg -i input.mp4 -c:v libx264 -crf 28 -preset veryfast -c:a aac -y output.mp4")?
.start()?
.wait()?;
Ok(())
}笔者用一段真实的音视频素材跑过:输入进去,from_cli 解析、分类、建好流水线,output.mp4 落地,ffprobe 一验------h264 视频 + aac 音频,时长对得上。整条链路在你自己的进程里,没有 Command::new("ffmpeg"),没有 stderr 打捞。字符串里的引号、反斜杠转义按 POSIX 规则处理;不想碰引号,用 from_cli_args(&["-i", "input.mp4", ...]) 直接传 argv,零引号歧义(ffmpeg.wasm 的 exec 也选了 argv 数组这个形态)。
一个前置要先说:执行路径目前只认 FFmpeg 7.1 运行时 。链接的是别的版本(含 8.x),会在任何 I/O 之前明确报 UnverifiedRuntimeProfile,不会带病运行------为什么这么设计,下面「闸门」一节讲。
emit_rust_code:或者,把它翻译成代码
有时你不想让它替你跑,而是想要那段 builder 代码,好接着改、接着扩展。同一条命令:
rust
use ez_ffmpeg::cli::emit_rust_code;
fn main() {
let code = emit_rust_code(
"ffmpeg -i in.mkv -c:v libx264 -crf 23 -preset fast -c:a aac -y out.mp4"
).unwrap();
println!("{code}");
}打印出的是一段完整、可直接编译的程序(真实输出,逐字节被仓库的 pin 测试钉住):
rust
// Generated from an ffmpeg command by the ez-ffmpeg CLI-compat emitter.
// command: ffmpeg -i in.mkv -c:v libx264 -crf 23 -preset fast -c:a aac -y out.mp4
// dialect: ffmpeg 7.1 command line; manifest: r4; crate: ez-ffmpeg 0.15.0; cargo features: none required
// status: verified shape V1 (H.264/AAC transcode (crf + preset)) --- verified by the manifest-driven semantic golden suite (oracle: Transcode) against the ffmpeg CLI; ...
use ez_ffmpeg::{FfmpegContext, Output};
fn main() -> Result<(), Box<dyn std::error::Error>> {
FfmpegContext::builder()
.input("in.mkv")
.output(
Output::from("out.mp4")
.set_video_codec("libx264") // -c:v libx264
.set_audio_codec("aac") // -c:a aac
.set_video_codec_opt("crf", "23") // -crf 23
.set_video_codec_opt("preset", "fast") // -preset fast
)
.build()?
.start()?
.wait()?;
Ok(())
}注意头部那几行注释:命令原文、方言版本(ffmpeg 7.1)、manifest 修订号、crate 版本,以及最关键的一行------这条形态的验证状态 。上面这条标着 verified shape V1:它经过一套语义金样测试,把流身份、编码器、尺寸、时长、播放列表拓扑逐项和真正的 ffmpeg CLI 对拍过。翻译不是"看着像",是"对过账"。
契约:全分类,零近似
这套层的设计出发点在模块文档里写得明明白白:广义 CLI 兼容是非目标。 ffmpeg CLI 是约 1.4 万行、语义随版本漂移的选项机器;整体去追它,只会做出"能跑,但微妙地不对"的东西,而这种东西最毁信任。所以它反着来------每一个 argv token 必须命中一份带版本的兼容 manifest,否则整条命令被拒,给出锚定到具体 token 的类型化诊断,绝不丢弃、绝不猜。落到三种结局:
① 验证过的形态 → 可以跑。 上面那条 V1 就是。目前 6 个验证形态(V1--V6):H.264/AAC 转码、剪辑、抽音轨、单帧缩略图、带 scale 的转码、单码率 VOD HLS------每个都有语义金样兜底。6 个听起来少,但这个数字的含义是「每一条都对过账」:子集每扩一个形态,成本就是补一条金样 lane,manifest 随版本往外长------宽度用验证换,不用近似换。
② 没验证的形态 → 只翻译,不执行。 比如只选编码器、不给 crf/preset 的转码。emit_rust_code 照样给你代码,但顶部换成醒目的警告(真实输出):
rust
// status: UNVERIFIED SCAFFOLDING --- manifest entry U19 (audio+video codec selection only).
// This shape has no semantic golden. The code below compiles against the
// ez-ffmpeg builder API, but its behavior has NOT been checked against the
// ffmpeg CLI and must not be treated as a faithful translation. Review every
// call before use; in-process execution (from_cli / from_cli_args) refuses
// this shape.而 from_cli 对这类形态直接拒跑,错误首行是 command shape is not verified for execution,随后列出已解析的选项。它给你脚手架当起点,但明说"我没替这条对过账,你自己审"。
③ 不认识的 → 当场拒掉,锚定到 token。 命令里有个子集外的选项,比如 ffmpeg -i in.mp4 -bogus 1 -y out.mp4:
text
unsupported option `-bogus` (token #2, output #0)
this option is not in the CLI-compat subset不是"忽略这个选项继续跑",而是整条拒绝,并告诉你是第几个 token 出的问题。
几道诚实的闸门
除了三分类,还有几处"宁可拒绝也不将就"的设计,值得单独点出------它们最能说明这套层的性格:
- 强制
-y。 少写-y,直接报错:missing mandatory `-y`。理由很实在:ffmpeg CLI 没有-y时会提示你确认覆盖,而这个库总是创建/截断输出,复现不了那个交互提示,所以干脆要求你显式写-y,把"会不会覆盖"这件事摆到台面上。 - 不模拟 shell。 字符串形式只做 POSIX 分词。命令里带管道?报 tokenize 错误并定位到具体字节:
shell operator; pipes, redirects, command lists and subshells are not ffmpeg options------管道、重定向、变量、通配符一律拒绝,绝不模拟。它翻译的是 ffmpeg,不是你的 shell。 - 严格 AVOption。 CLI 发起的流水线跑在严格模式下:任何组件都没消费掉的选项会让整条命令失败(对齐 fftools 的
check_avoptions),而不是像默认 builder 路径那样只打个警告。"这个参数其实没生效"不会被你忽略。 - 运行时 profile 门。 执行还要求链接的 FFmpeg 是验证过的运行时 profile(当前只认 7.1;8.1 等它版本匹配的金样 lane 过了再加)。别的版本在任何 I/O 之前就报
UnverifiedRuntimeProfile。
命令布局也是钉死的:恰好一个 -i 输入、一个输出路径,顺序固定;- 这种 stdin/stdout 伪路径不收------管道 I/O 是进程接线,不属于进程内子集。
子集之外:builder 才是全集
from_cli / emit_rust_code 是个上匝道,不是全部。子集只覆盖最常见的那些形态;真正的全集是 builder API 本身。而从 CLI 迁到 builder,只有三条换算规则要记:
- 秒换微秒 :
-ss 10→set_start_time_us(10_000_000)(方法名后缀_us就是提醒)。 - 参数名去
-原样用 :-crf 23→set_video_codec_opt("crf", "23"),-movflags +faststart→set_format_opt("movflags", "faststart")------直通 FFmpeg 的 AVOption,CLI 认什么名字这里就认什么。 - 滤镜串原样照搬 :
-vf后那串一字不改填进.filter_desc(...)。
比如加水印,-filter_complex "overlay=10:10" 就是多个 .input() 顺序对应 [0]/[1]、滤镜串照抄:
rust
FfmpegContext::builder()
.input("input.mp4").input("logo.png")
.filter_desc("[0:v][1:v]overlay=10:10")
.output("watermarked.mp4")
.build()?.start()?.wait()?;约 50 个 CLI 参数与模式的完整映射(含每条的实现方式和已知 gap)在 docs.rs 的 CLI-to-API mapping 一节。emit 出的脚手架 + 这张映射表,合起来就是"任意常见命令 → 可维护的 Rust 代码"的完整路径。
什么时候别用它
- 一次性的活,直接用 CLI。 转一个文件、试一个滤镜、验一个参数,开终端敲命令是最短路径,为它引 crate、写 Rust 程序反而绕远。这套兼容层的场景是:命令要在程序里反复跑,或要接着改成 Rust 代码继续扩展。
- 要 ffmpeg 的全部能力,
from_cli给不了。 它是个刻意窄 的可信子集------6 个验证形态、7.1 运行时。两遍编码、复杂-filter_complex、硬件加速、设备采集,都不在子集里,会被明确拒绝。要全部命令行能力,老老实实 shell out,或直接写 builder。 - 诚实三连 :编译/链接 libav 的痛这套层一点不消除;
cli是可选特性,得显式开;整个 CLI 兼容层还年轻,manifest 会随版本扩。
写在最后
把命令粘进去,它要么替你跑、要么给你代码,但绝不假装它翻译了它没验证过的东西------一个会说"这条我没对过账,你自己审"的工具,比一个什么都敢跑的工具可信得多。手写 CLI→API 对照表这件事,从此只在子集之外才需要。
cli 特性的用法见仓库 examples/cli_emitted_*(6 个验证形态的 pin 住的翻译产物)与 docs.rs 的 CLI-to-API 映射。项目地址:github.com/YeautyYE/ez-ffmpeg。
你最想让哪条 ffmpeg 命令能直接粘进 Rust 跑?欢迎评论区甩命令;如有描述不准之处,欢迎指正。