Communitygithub.com

YeautyYE/skill-rust-ffmpeg

Rust FFmpeg 指南:涵蓋 ez-ffmpeg、ffmpeg-next、ffmpeg-sys-next、ffmpeg-sidecar,用於編寫、審查、比較或移植影音程式碼,設計媒體結構體/trait,並將 FFmpeg CLI 指令轉譯為 Rust 程式碼。

skill-rust-ffmpeg 是什麼?

這是一個專為在 Rust 中實作 FFmpeg 功能而設計的 AI 技能指南。它涵蓋了四個主要的函式庫選擇:ez-ffmpeg(高階非同步、安全 API,適合一般任務與 CLI 移植)、ffmpeg-next(提供幀級控制與安全串流 I/O)、ffmpeg-sys-next(零拷貝、最大效能但需 unsafe 程式碼)以及 ffmpeg-sidecar(透過進程包裝,無需安裝 FFmpeg 開發庫)。該技能提供了一個多層次的決策框架:第一層決定整合方式(函式庫整合 vs. 二進位封裝),第二層根據使用者提及的關鍵字(例如「轉換格式」、「GPU」、「字幕」、「偵錯」)自動載入對應的場景參考文件,第三層根據特定需求(如需要 async/await、自訂 GPU 著色器、幀級控制、自訂 I/O 或無法安裝 FFmpeg)推薦最適合的函式庫。該技能支援跨平台(Windows、macOS、Linux),並提供版本相容性資訊(ez-ffmpeg 0.18.0 支援 FFmpeg 7.1–8.x,Rust MSRV 1.80+)。其運作方式是透過載入對應的 Markdown 參考文件(包含於技能目錄中)來產生生產就緒的程式碼,涵蓋轉碼、重封裝、串流、硬體加速、濾波器、偵測分析、批次處理、測試以及整合等各種場景。

相容平台✓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

決策邏輯

第一層:整合方式

預設:函式庫整合 (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。根據以下限制選擇。

  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(需要 unsafe 程式碼)
  10. 無法安裝 FFmpeg 開發庫? → ffmpeg-sidecar(基於進程,僅限標準輸入/輸出,無自訂 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-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 的指南

當此技能啟動時,請遵循以下工作流程:

對於實作任務:

  1. 識別任務 — 確定:影片/音訊/串流/檢查?簡單還是複雜?
  2. 選擇函式庫 — 應用第三層決策邏輯。用一句話說明選擇哪個函式庫及原因
  3. 載入參考文件 — 遵循第二層場景偵測來載入正確的參考文件
  4. 產生程式碼 — 生產就緒:適當的錯誤處理、

…

[因翻譯需求而截斷]

相關技能