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 |
決策邏輯
第一層:整合方式
預設:函式庫整合 (ez-ffmpeg/ffmpeg-next/ffmpeg-sys-next)
- 更好的效能、型別安全的 API、可直接存取 Frame
替代方案:二進位方式 (ffmpeg-sidecar) — 考量時機:
- 無法安裝 FFmpeg 開發庫
- 受限的 CI/CD 環境,無管理員權限
- 純 CLI 批次處理(無即時需求)
若安裝受限 → 載入 ffmpeg_sidecar.md
第二層:場景偵測
| 使用者提到 | 載入參考文件 |
|---|---|
| "轉換格式"、"重新封裝"、"修剪"、"調整大小"、"裁剪"、"簡單" | video_transcoding.md |
| "提取音訊"、"僅音訊"、"音軌"、"mp3 提取"、"loudnorm"、"標準化音訊"、"音量" | audio_extraction.md |
| "縮圖"、"第一幀"、"快速縮圖"、"skip_frame"、"nokey"、"僅關鍵幀"、"多輸出"、"串接"、"浮水印"、"管線"、"濾波器圖" | pipelines_multi_output.md — 一次性縮圖請使用 image_sequences.md 中的 recipes::thumbnail;最快的僅關鍵幀路徑 (skip_frame=nokey,捕捉到下一個關鍵幀) 請見 ez_ffmpeg/video.md |
| "即時"、"RTMP"、"HLS"、"直播"、"串流"、"擷取"、"網路攝影機"、"緩衝"、"反壓力"、"抖動緩衝"、"網路抖動"、"ABR 階梯"、"HLS 階梯"、"自適應位元率"、"主播放清單"、"VOD 封裝" | streaming_rtmp_hls.md |
| "GPU"、"NVENC"、"VideoToolbox"、"硬體"、"VAAPI"、"QSV"、"wgpu"、"WGSL"、"自訂著色器"、"GPU 濾波器"、"計算著色器"、"libplacebo"、"美顏濾鏡"、"色鍵"、"綠幕" | hardware_acceleration.md |
| "批次"、"多個檔案"、"大量"、"並行" | batch_processing.md |
| "字幕"、"srt"、"字幕"、"燒錄字幕"、"燒入"、"硬字幕"、"ass"、"vtt"、"原生字幕"、"不使用 libass"、"無 libass" | subtitles.md |
| "AV1"、"AVIF"、"HDR"、"10-bit"、"現代編解碼器"、"HDR 轉 SDR"、"色調映射"、"tonemap"、"色彩過淡"、"PQ"、"HLG" | modern_codecs.md |
| "偵錯"、"ffprobe"、"檢查"、"中繼資料"、"錯誤"、"疑難排解"、"探測"、"時長"、"解析度"、"損毀"、"完整性" | debugging.md |
| "偵測黑畫面"、"靜音偵測"、"場景偵測"、"場景變化"、"cropdetect"、"EBU R128"、"LUFS"、"量測響度"、"真峰值"、"內容分析"、"QC"、"blackdetect"、"silencedetect" | detection_analysis.md (型別化的 analysis API) |
| "濾波器"、"特效"、"縮放"、"裁剪"、"疊加"、"浮水印"、"模糊"、"銳化"、"色彩"、"亮度"、"旋轉"、"翻轉"、"淡入淡出"、"速度"、"慢動作" | filters_effects.md |
| "影像序列"、"幀提取"、"影片轉圖片"、"圖片轉影片"、"縮時攝影"、"逐幀"、"精靈圖"、"故事板"、"聯絡表"、"縮圖網格" | image_sequences.md |
"一次性食譜"、"recipes 模組"、"快速縮圖"、"縮圖食譜"、"精靈圖食譜"、"gif 食譜"、"HLS 階梯食譜" (ez-ffmpeg recipes,無需特徵旗標) | image_sequences.md (縮圖/精靈圖)、gif_creation.md (gif)、streaming_rtmp_hls.md (HLS 階梯) |
| "測試"、"驗證"、"確認"、"黃金檔案"、"校驗和"、"產生測試影片"、"testsrc" | testing.md |
| "網頁伺服器"、"API"、"S3"、"非同步工作"、"整合"、"追蹤"、"日誌"、"日誌回呼"、"av_log"、"日誌重新導向" | integration.md |
| "gif"、"動畫 gif"、"影片轉 gif"、"從影片產生 gif"、"gif 迴圈"、"gif 色板" | gif_creation.md |
| "中繼資料"、"章節"、"標籤"、"媒體資訊"、"標題"、"藝術家"、"專輯"、"章節標記" | metadata_chapters.md |
| "螢幕錄製"、"網路攝影機"、"相機擷取"、"錄製螢幕"、"avfoundation"、"directshow"、"v4l2"、"裝置擷取" | capture.md |
| "AVPacket"、"AVFrame"、"關鍵幀"、"GOP"、"NALU"、"位元流"、"EAGAIN"、"解碼迴圈"、"記憶體"、"封包" | ffmpeg_next.md + ffmpeg_sys_next.md |
| "avformat_find_stream_info"、"AVSEEK_SIZE"、"AVFormatContext"、"AVCodecID"、"原始 C API"、"FFI" | ffmpeg_sys_next.md + custom_io.md |
| "自訂 io"、"讀取回呼"、"寫入回呼"、"StreamIo"、"記憶體輸入/輸出"、"Read/Write/Seek 來源" | 安全 API:advanced.md (ez-ffmpeg 回呼) 或 ffmpeg_next.md (StreamIo) |
| "AVIOContext"、"io context"、"原始 io 回呼"、"零拷貝自訂 io" | custom_io.md (不安全的 FFI) |
| "提取幀到記憶體"、"解碼為 RGB"、"用於 AI/ML 的幀"、"幀轉張量"、"幀匯出"、"影片轉幀供模型使用"、"FrameExtractor"、"whisper PCM"、"音訊轉 f32"、"SampleExtractor"、"ASR 輸入"、"均勻 N 幀" | frame_io.md (實驗性,ez-ffmpeg 0.14) |
| "VideoWriter"、"推送幀"、"從幀產生影片"、"程序化影片"、"將幀渲染為影片"、"記憶體內 mp4"、"從記憶體編碼"、"幀轉影片" | frame_io.md (實驗性,ez-ffmpeg 0.14) |
| "WHIP"、"WebRTC 輸出"、"SRT 輸出"、"功能探測"、"is_muxer_available"、"輸出協定可用"、"fMP4 HLS"、"分片 mp4 片段" | streaming.md (WHIP/SRT/功能) + streaming_rtmp_hls.md (fMP4 階梯) |
| "編碼封包匯出"、"封包接收器"、"PacketSink"、"webcodecs"、"EncodedVideoChunk"、"EncodedAudioChunk"、"H.264 存取單元"、"aac 幀"、"avcC"、"AudioSpecificConfig"、"rtp 封包器"、"fmp4 分段器"、"工作失敗"、"on_job_failed"、"JobFailureSummary" | packet_sink.md (實驗性,ez-ffmpeg 0.15;工作失敗摘要 0.16) |
| "進度"、"進度條"、"完成百分比"、"ETA"、"進度到哪了"、"編碼速度"、"progress_handle"、"ProgressHandle"、"進度快照" | advanced.md;批次每個檔案計數:batch_processing.md |
| "每個串流的編碼器"、"不同串流使用不同編解碼器"、"StreamMap"、"-c:v:0"、"索引串流選項"、"每個串流的編解碼器選項" | video.md (ez-ffmpeg 0.16) |
| "在 rust 中執行 ffmpeg 指令"、"from_cli_args"、"emit_rust_code"、"轉譯 ffmpeg 指令"、"cli 特徵"、"cli-compat"、"驗證形狀" | cli_compat.md (cli 特徵);手動對應:cli_migration.md |
| "版本相容性"、"FFmpeg 7 vs 8"、"連結錯誤"、"建構失敗"、"links = ffmpeg"、"安裝"、"vcpkg" | installation.md |
| "使用哪個函式庫"、"比較"、"vs"、"移植到"、"遷移到"、"轉換到"、"切換自"、"改寫使用"、"可行性"、"我應該用哪個"、"最佳函式庫"、"評估"、"審查 FFmpeg 程式碼"、"這個能與...一起運作嗎" | library_selection.md |
一個請求可能符合多行 — 載入 所有 適用的參考文件,然後優先遵循最特定行的目標。
第三層:函式庫選擇
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(需要 unsafe 程式碼)
- 無法安裝 FFmpeg 開發庫? → ffmpeg-sidecar(基於進程,僅限標準輸入/輸出,無自訂 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-major-to-system-major 配對。注意事項:當將 ffmpeg-next 與 ez-ffmpeg 一起拉取時,請將其保持在 8.1.0 — 混合 7.1.0 會因為 links = "ffmpeg" 鍵而發生衝突。關於 bindgen 機制、舊版 7.1-pin 的理由以及 rust-ffmpeg #246 的歷史,請參閱 installation.md。
安裝問題:installation.md — 包含 Windows vcpkg 靜態連結 unresolved external symbol 的修復方法(在應用程式的 build.rs 中添加額外的系統庫;VCPKG_ROOT 必須在 shell 中設定,而不是透過 build.rs 中的 std::env::set_var)
給 Claude 的指南
當此技能啟動時,請遵循以下工作流程:
對於實作任務:
- 識別任務 — 確定:影片/音訊/串流/檢查?簡單還是複雜?
- 選擇函式庫 — 應用第三層決策邏輯。用一句話說明選擇哪個函式庫及原因
- 載入參考文件 — 遵循第二層場景偵測來載入正確的參考文件
- 產生程式碼 — 生產就緒:適當的錯誤處理、
…
[因翻譯需求而截斷]