Communitygithub.com

Rust FFmpeg 指南

Rust FFmpeg 综合指南:涵盖 ez-ffmpeg、ffmpeg-next、ffmpeg-sys-next 和 ffmpeg-sidecar 等库,用于编写、审查、对比(X vs Y)或迁移音视频代码,设计媒体结构体/特质,以及将 FFmpeg CLI 命令转换为 Rust 代码。

Rust FFmpeg 指南 是什么?

本技能为在 Rust 中实现 FFmpeg 功能提供了全面的指导:涵盖库选择(ez-ffmpeg、ffmpeg-next、ffmpeg-sys-next、ffmpeg-sidecar)、代码生成和问题解决。它支持几乎所有常见的音视频任务,包括转码、重新封装、裁剪、拼接、水印、缩略图/精灵图、字幕烧录(无需 libass)、响度标准化(EBU R128/LUFS)、比特流过滤器、流映射、GPU 加速(NVENC、VideoToolbox、VAAPI、QSV)、自定义 WGSL 着色器、黑场/静音/场景检测、从内存中提取帧/音频(用于 AI/ML/Whisper)、程序化视频生成(VideoWriter)、编码包导出(PacketSink)、RTMP/HLS/WHIP/SRT 流媒体、批量处理以及 ffprobe 集成。该技能有一个完整的选择框架,根据异步需求、自定义处理要求、GPU 着色器、字幕处理和部署约束(例如无法安装开发库)推荐合适的库。它还有一个场景驱动的决策逻辑,可自动加载最相关的文档参考文件,为所有支持的任务生成生产级 Rust 代码。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/YeautyYE/skill-rust-ffmpeg/tree/HEAD/plugin/skills/rust-ffmpeg

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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。根据以下约束进行选择。

  1. 需要 async/await? → ez-ffmpeg(唯一原生支持异步的库)
  2. 需要自定义 Rust 帧处理? → ez-ffmpeg FrameFilter(安全、简单的 API)
  3. 需要自定义 GPU 着色器 (WGSL)? → ez-ffmpeg wgpu 特性(WgpuFrameFilter,无头,无需显示服务器)—— 先检查内置的 wgpu_filter::effects 目录(13 种带类型效果,0.13+);对于原生硬件滤镜(scale_cuda/scale_vaapi/libplacebo)使用 get_gpu_filter_backends() 进行探测
  4. 需要无需 libass 烧录字幕? → ez-ffmpeg subtitle 特性(SubtitleFilter,纯 Rust ASS/SRT 渲染器,无需 --enable-libass)
  5. 需要带类型的检测/测量(黑场/静音/场景/裁剪/EBU R128)? → ez-ffmpeg analysis 模块(Analysis 一次性或 MetadataEventFilter 流式处理 —— 无需特性标志)
  6. 需要一次性缩略图/精灵图/GIF/HLS ABR 阶梯? → ez-ffmpeg recipes 模块(无需特性标志)
  7. 需要帧级编解码器控制? → ffmpeg-next 用于编解码器内部结构
  8. 需要来自内存的自定义 I/O? → ez-ffmpeg(读/写/查找回调),或 ffmpeg-next 安全流 I/O(input_from_stream/output_to_stream,任何 Read/Write/Seek);ffmpeg-sys-next 用于最低级别控制
  9. 需要零拷贝或最大性能? → ffmpeg-sys-next(需要不安全代码)
  10. 无法安装 FFmpeg 库? → ffmpeg-sidecar(基于进程,仅 stdin/stdout,无自定义 I/O)
  11. 需要将解码后的帧/音频存入内存以供 AI/CV/ASR 使用? → ez-ffmpeg frame_export(FrameExtractor → 打包 RGB,SampleExtractor::for_whisper → 16 kHz 单声道 f32;无需特性标志;实验性,0.14)—— 参见 frame_io.md
  12. 需要从 Rust 渲染的帧生成/推送视频? → ez-ffmpeg VideoWriter(将帧推入编码/复用/流式处理,无需解复用器;实验性,0.14)—— 参见 frame_io.md
  13. 需要直接从编码器馈送数据到 WebCodecs 解码器、RTP/SRT 打包器或自制 fMP4 分段器? → ez-ffmpeg packet_sink(PacketSink,严格仅 H.264/AAC 层级,无容器;无需特性标志;实验性,0.15)—— 参见 packet_sink.md
  14. 需要运行或自动翻译现有的 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 分钟设置。

库参考

版本兼容性

库版本FFmpegRust MSRV
ez-ffmpeg0.18.07.1–8.x1.80+ (wgpu: 1.85+)
ffmpeg-next8.1.07.0–8.x未指定
ffmpeg-sys-next8.1.07.0–8.x未指定
ffmpeg-sidecar2.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 使用指南

当此技能被激活时,请遵循以下工作流程:

对于实现任务:

  1. 识别任务 —— 确定:视频/音频/流式处理/检查?简单还是复杂?
  2. 选择库 —— 应用第 3 层决策逻辑。用一句话说明选择了哪个库及其原因
  3. 加载参考 —— 按照第 2 层场景检测加载正确的参考文件
  4. 生成代码 —— 生产就绪:正确的错误处理,

…

[为翻译而截断]

相关技能