Rust FFmpeg
在 Rust 中实现 FFmpeg 功能的指南:库选择、代码生成和问题解决。
选择框架
| 库 | 使用场景 | 异步 | 安全性 | 权衡 |
|---|---|---|---|---|
| ez-ffmpeg | 通用任务、CLI 迁移、RTMP 服务器、自定义 Rust + WGSL GPU 滤镜、原生字幕烧录、检测/测量、一次性配方、自定义 I/O、内存帧/样本导出 + 帧推送 (VideoWriter)、带类型的每输出进度 | ✅ 是 | 安全 | 需要 FFmpeg 库 |
| ffmpeg-next | 帧级控制、编解码器内部结构、安全流 I/O(任何 Read/Write/Seek) | ❌ 否 | 安全 | 更多样板代码 |
| ffmpeg-sys-next | 零拷贝、自定义内存 I/O、最大性能 | ❌ 否 | 不安全 | 手动内存管理 |
| ffmpeg-sidecar | 无法安装 FFmpeg 时使用 | ❌ 否 | 安全 | 进程开销,无自定义 I/O |
决策逻辑
第 1 层:集成方法
默认:库集成(ez-ffmpeg/ffmpeg-next/ffmpeg-sys-next)
- 更好的性能,类型安全的 API,直接访问帧
备选:二进制方法(ffmpeg-sidecar)——在以下情况下考虑:
- 无法安装 FFmpeg 开发库
- 受限制的 CI/CD 环境且无管理员权限
- 纯 CLI 批处理(无实时需求)
如果安装受限 → 加载 ffmpeg_sidecar.md
第 2 层:场景检测
| 用户提及 | 加载参考 |
|---|---|
| "convert format"、"remux"、"trim"、"resize"、"crop"、"simple" | video_transcoding.md |
| "extract audio"、"audio only"、"audio track"、"mp3 extract"、"loudnorm"、"normalize audio"、"volume" | audio_extraction.md |
| "thumbnail"、"first frame"、"fast thumbnail"、"skip_frame"、"nokey"、"keyframe-only"、"multi-output"、"concat"、"watermark"、"pipeline"、"filter graph" | pipelines_multi_output.md —— 对于一次性缩略图,优先使用 image_sequences.md 中的 recipes::thumbnail;对于最快的仅关键帧路径(skip_frame=nokey,快照到下一个关键帧),请参阅 ez_ffmpeg/video.md |
| "real-time"、"RTMP"、"HLS"、"live"、"stream"、"capture"、"webcam"、"buffer"、"backpressure"、"jitter buffer"、"network jitter"、"ABR ladder"、"HLS ladder"、"adaptive bitrate"、"master playlist"、"VOD packaging" | streaming_rtmp_hls.md |
| "GPU"、"NVENC"、"VideoToolbox"、"hardware"、"VAAPI"、"QSV"、"wgpu"、"WGSL"、"custom shader"、"GPU filter"、"compute shader"、"libplacebo"、"beauty filter"、"chroma key"、"green screen" | hardware_acceleration.md |
| "batch"、"multiple files"、"bulk"、"parallel" | batch_processing.md |
| "subtitles"、"srt"、"captions"、"burn subs"、"burn-in"、"hardsub"、"ass"、"vtt"、"native subtitle"、"without libass"、"no libass" | subtitles.md |
| "AV1"、"AVIF"、"HDR"、"10-bit"、"modern codec"、"HDR to SDR"、"tone mapping"、"tonemap"、"washed out colors"、"PQ"、"HLG" | modern_codecs.md |
| "debug"、"ffprobe"、"inspect"、"metadata"、"error"、"troubleshoot"、"probe"、"duration"、"resolution"、"corrupt"、"integrity" | debugging.md |
| "detect black frames"、"silence detect"、"scene detect"、"scene change"、"cropdetect"、"EBU R128"、"LUFS"、"measure loudness"、"true peak"、"content analysis"、"QC"、"blackdetect"、"silencedetect" | detection_analysis.md (带类型的 analysis API) |
| "filter"、"effect"、"scale"、"crop"、"overlay"、"watermark"、"blur"、"sharpen"、"color"、"brightness"、"rotate"、"flip"、"fade"、"speed"、"slow motion" | filters_effects.md |
| "image sequence"、"frame extraction"、"video to images"、"images to video"、"timelapse"、"frame by frame"、"sprite sheet"、"storyboard"、"contact sheet"、"thumbnail grid" | image_sequences.md |
"one-shot recipe"、"recipes module"、"quick thumbnail"、"thumbnail recipe"、"sprite sheet recipe"、"gif recipe"、"HLS ladder recipe"(ez-ffmpeg recipes,无特性标志) | image_sequences.md(缩略图/精灵图)、gif_creation.md(gif)、streaming_rtmp_hls.md(HLS 阶梯) |
| "test"、"validate"、"verify"、"golden file"、"checksum"、"generate test video"、"testsrc" | testing.md |
| "web server"、"API"、"S3"、"async job"、"integration"、"tracing"、"logging"、"log callback"、"av_log"、"log redirect" | integration.md |
| "gif"、"animated gif"、"video to gif"、"gif from video"、"gif loop"、"gif palette" | gif_creation.md |
| "metadata"、"chapter"、"tag"、"media info"、"title"、"artist"、"album"、"chapter marker" | metadata_chapters.md |
| "screen capture"、"webcam"、"camera capture"、"record screen"、"avfoundation"、"directshow"、"v4l2"、"device capture" | capture.md |
| "AVPacket"、"AVFrame"、"keyframe"、"GOP"、"NALU"、"bitstream"、"EAGAIN"、"decode loop"、"memory"、"packet" | ffmpeg_next.md + ffmpeg_sys_next.md |
| "avformat_find_stream_info"、"AVSEEK_SIZE"、"AVFormatContext"、"AVCodecID"、"raw C API"、"FFI" | ffmpeg_sys_next.md + custom_io.md |
| "custom io"、"read callback"、"write callback"、"StreamIo"、"memory input/output"、"Read/Write/Seek source" | 安全 API:advanced.md(ez-ffmpeg 回调)或 ffmpeg_next.md(StreamIo) |
| "AVIOContext"、"io context"、"raw io callback"、"zero-copy custom io" | custom_io.md(不安全的 FFI) |
| "extract frames to memory"、"decode to RGB"、"frames for AI/ML"、"frame to tensor"、"frame export"、"video to frames for a model"、"FrameExtractor"、"whisper PCM"、"audio to f32"、"SampleExtractor"、"ASR ingest"、"uniform N frames" | frame_io.md(实验性,ez-ffmpeg 0.14) |
| "VideoWriter"、"push frames"、"generate video from frames"、"procedural video"、"render frames to video"、"in-memory mp4"、"encode from memory"、"frames to video" | frame_io.md(实验性,ez-ffmpeg 0.14) |
| "WHIP"、"WebRTC output"、"SRT output"、"capability probe"、"is_muxer_available"、"output protocol available"、"fMP4 HLS"、"fragmented mp4 segments" | streaming.md(WHIP/SRT/功能检测)+ streaming_rtmp_hls.md(fMP4 阶梯) |
| "encoded packet export"、"packet sink"、"PacketSink"、"webcodecs"、"EncodedVideoChunk"、"EncodedAudioChunk"、"h.264 access units"、"aac frames"、"avcC"、"AudioSpecificConfig"、"rtp packetizer"、"fmp4 segmenter"、"job failure"、"on_job_failed"、"JobFailureSummary" | packet_sink.md(实验性,ez-ffmpeg 0.15;任务失败摘要 0.16) |
| "progress"、"progress bar"、"percent complete"、"ETA"、"how far along"、"encoding speed"、"progress_handle"、"ProgressHandle"、"progress snapshot" | advanced.md;批量每个文件计数:batch_processing.md |
| "per-stream encoder"、"different codec per stream"、"StreamMap"、"-c:v:0"、"indexed stream options"、"per-stream codec options" | video.md(ez-ffmpeg 0.16) |
| "run ffmpeg command in rust"、"from_cli_args"、"emit_rust_code"、"translate ffmpeg command"、"cli feature"、"cli-compat"、"verified shape" | cli_compat.md(cli 特性);手动映射:cli_migration.md |
| "version compatibility"、"FFmpeg 7 vs 8"、"linking error"、"build fails"、"links = ffmpeg"、"install"、"vcpkg" | installation.md |
| "which library"、"compare"、"vs"、"migrate to"、"port to"、"convert to"、"switch from"、"rewrite using"、"feasibility"、"should I use"、"best library"、"evaluate"、"review FFmpeg code"、"can this work with" | library_selection.md |
单个请求可能匹配多行——加载所有适用的参考,然后首先遵循最具体行的目标。
第 3 层:库选择
CLI 迁移:ez-ffmpeg 和 ffmpeg-sidecar 都支持 CLI 风格的 API。根据以下约束进行选择。
- ez-ffmpeg:CLI 迁移指南 —— 库集成,原生性能
- ffmpeg-sidecar:CLI 到 Rust 迁移 —— 进程包装器,无需 FFmpeg 库
- 需要 async/await? → ez-ffmpeg(唯一原生支持异步的库)
- 需要自定义 Rust 帧处理? → ez-ffmpeg FrameFilter(安全、简单的 API)
- 需要自定义 GPU 着色器 (WGSL)? → ez-ffmpeg
wgpu特性(WgpuFrameFilter,无头,无需显示服务器)—— 先检查内置的wgpu_filter::effects目录(13 种带类型效果,0.13+);对于原生硬件滤镜(scale_cuda/scale_vaapi/libplacebo)使用get_gpu_filter_backends()进行探测 - 需要无需 libass 烧录字幕? → ez-ffmpeg
subtitle特性(SubtitleFilter,纯 Rust ASS/SRT 渲染器,无需--enable-libass) - 需要带类型的检测/测量(黑场/静音/场景/裁剪/EBU R128)? → ez-ffmpeg
analysis模块(Analysis一次性或MetadataEventFilter流式处理 —— 无需特性标志) - 需要一次性缩略图/精灵图/GIF/HLS ABR 阶梯? → ez-ffmpeg
recipes模块(无需特性标志) - 需要帧级编解码器控制? → ffmpeg-next 用于编解码器内部结构
- 需要来自内存的自定义 I/O? → ez-ffmpeg(读/写/查找回调),或 ffmpeg-next 安全流 I/O(
input_from_stream/output_to_stream,任何Read/Write/Seek);ffmpeg-sys-next 用于最低级别控制 - 需要零拷贝或最大性能? → ffmpeg-sys-next(需要不安全代码)
- 无法安装 FFmpeg 库? → ffmpeg-sidecar(基于进程,仅 stdin/stdout,无自定义 I/O)
- 需要将解码后的帧/音频存入内存以供 AI/CV/ASR 使用? → ez-ffmpeg
frame_export(FrameExtractor→ 打包 RGB,SampleExtractor::for_whisper→ 16 kHz 单声道 f32;无需特性标志;实验性,0.14)—— 参见 frame_io.md - 需要从 Rust 渲染的帧生成/推送视频? → ez-ffmpeg
VideoWriter(将帧推入编码/复用/流式处理,无需解复用器;实验性,0.14)—— 参见 frame_io.md - 需要直接从编码器馈送数据到 WebCodecs 解码器、RTP/SRT 打包器或自制 fMP4 分段器? → ez-ffmpeg
packet_sink(PacketSink,严格仅 H.264/AAC 层级,无容器;无需特性标志;实验性,0.15)—— 参见 packet_sink.md - 需要运行或自动翻译现有的 ffmpeg CLI 命令? → ez-ffmpeg
cli特性(from_cli_args/emit_rust_code,狭窄的黄金测试子集 —— 6 种已验证形状;0.15)—— 参见 cli_compat.md;该子集之外的任何内容仍需使用手动 cli_migration.md 表格
注意:FrameFilter(自定义 Rust 帧处理)与自定义 I/O 回调(自定义数据源/接收器)是分开的。ez-ffmpeg 两者都支持。
快速入门
首次接触 Rust FFmpeg?请参阅 quick_start.md 进行 5 分钟设置。
库参考
- ez-ffmpeg - 高级 API(同步和异步)
- ffmpeg-next - 中级 API,用于高级控制
- ffmpeg-sys-next - 低级不安全 FFI
- ffmpeg-sidecar - CLI 包装器
版本兼容性
| 库 | 版本 | FFmpeg | Rust MSRV |
|---|---|---|---|
| ez-ffmpeg | 0.18.0 | 7.1–8.x | 1.80+ (wgpu: 1.85+) |
| ffmpeg-next | 8.1.0 | 7.0–8.x | 未指定 |
| ffmpeg-sys-next | 8.1.0 | 7.0–8.x | 未指定 |
| ffmpeg-sidecar | 2.5.2 | 任意 | 1.79+ |
来源:crates.io
FFmpeg 7 vs 8:使用上述当前 crate 版本,所有四个库都可以针对两个主版本构建 —— 没有 crate 主版本到系统主版本的匹配。防范措施:当将 ffmpeg-next 与 ez-ffmpeg 一起拉取时,请将其保持在 8.1.0 —— 混入 7.1.0 会通过 links = "ffmpeg" 键发生冲突。有关 Bindgen 机制、遗留的 7.1 固定原因以及 rust-ffmpeg #246 历史:请参阅 installation.md。
安装问题:installation.md —— 包括 Windows vcpkg 静态链接 unresolved external symbol 修复(在应用程序的 build.rs 中添加额外的系统库;VCPKG_ROOT 必须在 shell 中设置,而不是通过 build.rs 中的 std::env::set_var 设置)
Claude 使用指南
当此技能被激活时,请遵循以下工作流程:
对于实现任务:
- 识别任务 —— 确定:视频/音频/流式处理/检查?简单还是复杂?
- 选择库 —— 应用第 3 层决策逻辑。用一句话说明选择了哪个库及其原因
- 加载参考 —— 按照第 2 层场景检测加载正确的参考文件
- 生成代码 —— 生产就绪:正确的错误处理,
…
[为翻译而截断]