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:シナリオ検出
| ユーザーが言及した場合 | 参照ドキュメントをロード |
|---|---|
| 「フォーマット変換」「リマックス」「トリミング」「リサイズ」「クロップ」「シンプル」 | 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」「キャプション」「字幕焼き込み」「hardsub」「ass」「vtt」「ネイティブ字幕」「libassなし」「no libass」 | subtitles.md |
| 「AV1」「AVIF」「HDR」「10-bit」「最新コーデック」「HDR to SDR」「トーンマッピング」「tonemap」「色あせ」「PQ」「HLG」 | modern_codecs.md |
| 「デバッグ」「ffprobe」「検査」「メタデータ」「エラー」「トラブルシュート」「プローブ」「duration」「resolution」「破損」「整合性」 | debugging.md |
| 「黒フレーム検出」「無音検出」「シーン検出」「シーンチェンジ」「cropdetect」「EBU R128」「LUFS」「ラウドネス計測」「true peak」「コンテンツ分析」「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_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コンテキスト」「生の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」「verified shape」 | cli_compat.md(cli機能);手動マッピング:cli_migration.md |
| 「バージョン互換性」「FFmpeg 7 vs 8」「リンクエラー」「ビルド失敗」「links = ffmpeg」「インストール」「vcpkg」 | installation.md |
| 「どのライブラリ」「比較」「vs」「移行先」「移植先」「変換先」「切り替え元」「リライト」「実現可能性」「使用すべきライブラリ」「最良のライブラリ」「評価」「FFmpegコードのレビュー」「これで動作するか」 | library_selection.md |
複数の行が1つのリクエストにマッチする場合があります — 該当する参照先をすべてロードし、最初に最も具体的な行のターゲットに従ってください。
レイヤー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:4つのライブラリすべてが、上記の現在のクレートバージョンで両方のメジャーバージョンに対してビルドされます — クレートのメジャーバージョンとシステムのメジャーバージョンのマッチングは不要。注意:ez-ffmpegと一緒に ffmpeg-next をプルする場合、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 はシェルで設定する必要があり、build.rs 内で std::env::set_var を使用してはならない)
Claudeのためのガイドライン
このスキルがアクティブになったとき、以下のワークフローに従ってください:
実装タスクの場合:
- タスクを特定 — ビデオ/オーディオ/ストリーミング/検査? シンプルか複雑か?
- ライブラリを選択 — レイヤー3の決定ロジックを適用。どのライブラリとその理由を一文で述べる
- 参照をロード — レイヤー2のシナリオ検出に従って適切な参照ファイルをロードする
- コードを生成 — プロダクション対応:適切なエラーハンドリング、...
... [翻訳のために切り詰められました]