ffmpeg

FFmpeg エキスパート

FFmpeg を型付きメディアパイプラインとして扱い、メディア編集を根拠に基づくワークフローとして進めます。実際のソースを調査し、測定結果と解釈を分け、判断をレビュー可能にし、新しいパスにレンダリングして、意図した境界で検証します。

使用しない場合

• libav API のプログラミング、不透明な動画全体の意味理解、自動公開、権利処理、DRM の回避、プロ向けの放送／カラー認証、または HyperFrames で作成したコンポジションには、このスキルを使用しないでください。
• オンラインメディアやトランスクリプトの取得は、該当するソースを担当するスキルに引き継いでください。意味的なフレーム解釈は、ビジョン対応のレビュアーに依頼してください。プラットフォームへのアップロードや API 操作は、該当するプラットフォームスキルに引き継いでください。

境界とルーティング

• オンライン動画やトランスクリプトの取得には YouTube／トランスクリプト機能を使用してください。ローカルで提供されたメディアとトランスクリプトのアーティファクトがある場合に限り、ここに戻ってください。
• HTML で作成するモーショングラフィックスやコンポジションには HyperFrames を使用してください。メディア入力の調査や前処理、レンダリング結果の検証には、このスキルを使用してください。
• アップロード、公開、アカウント、API の操作には、該当するプラットフォームスキルを使用してください。
• FFmpeg は範囲を限定したフレームや音声セグメントを抽出できますが、その意味内容を解釈することはできません。映像の解釈はビジョン対応のレビュアーに依頼し、その観察結果を、誰のものか明示した根拠として保持してください。
• 技術メタデータ、まばらなフレーム、無音区間、または同期されていないトランスクリプトから、権利、同意、身元、意図、番組全体の意味を推測しないでください。

根拠の分類

異なる種類の根拠を混同しないよう、重要な主張にはラベルを付けてください。

• 技術仕様 — 公式の FFmpeg または標準規格の情報源に記載された動作です。
• 観測されたアーティファクト — このソース／出力についてのプローブ結果、測定された信号の結果、抽出フレーム、聴取したセグメント、または下流のテストです。
• 再現可能な実験 — 正確なバージョン、入力の識別情報／生成方法、コマンド、結果、制限事項を記録したものです。
• 編集上のヒューリスティック — 人によるレビューが必要な、取り消し可能な判断であり、FFmpeg によって確立された事実ではありません。
• ユーザー要件 — 要求された出力仕様、保持ポリシー、受け入れ基準です。

メディア編集のループ

1. 受け入れ。 権限とプライバシーの境界を確認し、すべてのソースを特定します。templates/media-intake.json のプライベートなワークスペースコピーを使用して、プローブの証拠、タイミング、出力仕様、保持ポリシー、未解決の前提を記録します。生のプローブ出力とメディアは制限されたタスクワークスペースに保管し、共有可能な派生物は最小限に抑えます。
2. 調査。 ストリームとフォーマットをプローブします。インベントリまたは scripts/ffmpeg-preflight を使って必要なローカル機能を確認します。フィルター、エンコーダー、ハードウェアバックエンドが存在すると決めつけないでください。
3. 範囲を限定して証拠を収集。 判断に必要なフレーム、クリップ、波形／信号の測定値、または文字起こしの範囲だけを抽出します。サンプルのタイムスタンプ、数、バイト数／サイズの上限、およびサンプルはサンプリングした時点のみをカバーする旨を記録します。
4. レンダリング前に計画。 編集上の変更については、レビュー可能な EDL またはポッドキャスト編集計画を作成します。重要なカットごとに、ソース範囲、理由、証拠、確信度、処理、対応関係、検証状況が必要です。曖昧な判断は即興で決めず、未解決のままにします。
5. 安全にレンダリング。 ストリームマッピングを明示します。-n と新しい出力パスを優先し、信頼できないシェル連結は避けます。キーフレームに制約されるストリームコピーと、デコード／再エンコードによる正確なカットを区別します。
6. 段階的に検証。 該当する場合は、終了ステータス、デコード可能性、出力のプローブ結果、ストリーム／タイミングの仕様、範囲を限定したフレーム／音声の証拠、編集上のレビュー、実際の下流コンシューマーを確認します。プローブ／デコードの成功と出力先での受け入れを別々のゲートとして扱います。ローカルファイルは前者を通過しても、後者に失敗することがあります。
7. 受け入れるか、停止する。 templates/media-acceptance-report.md のプライベートなワークスペースコピーを使用して、基準ごとの合格／不合格／保留を記録します。コンテナが有効であることやコマンドが成功したことだけでは、受け入れとはみなせません。

技術調査は次のコマンドから始めます。

ffprobe -v error -show_format -show_streams -of json INPUT

提供されているヘルパーワークフローでは、スキルのルートから明示的な出力パスと上限を指定してヘルパーを実行します。JSON の結果は、それ自体を受け入れとみなさず、検証対象のレポートとして扱います。extract-review-frames を使う場合、タイムスタンプはカンマ区切りの値を 1 つ渡すのではなく、個別の値として渡します（--timestamps 0 5 9）。

関連するリファレンスを参照する

証拠に基づくメディア作業

• 提供または生成されたメディア、機密情報、複数のソース、または定義済みの納品仕様を扱う前に、references/media-intake-and-manifest.md を読みます。
• フレーム／クリップの抽出やレビュー、サンプルの選択、または視覚的な主張を行う場合は、references/video-inspection-and-visual-evidence.md を読みます。
• 文字起こしに基づく選択、シーケンス構成、ペーシング、トランジション、オーバーレイ、レビュー可能な編集判断については、references/editorial-video-editing.md を読みます。
• ポッドキャストのカット、信号のクリーンアップ、無音／ノイズ分析、ラウドネス測定、試聴ゲートについては、references/audio-and-podcast-editing.md を読みます。
• EDL の作成、検証、または EDL のコマンド計画への変換の前に、references/ffmpeg-edit-decision-lists.md を読みます。
• 出力が完成している、または互換性があると宣言する前に、references/media-verification-and-acceptance.md を読みます。
• 証拠に矛盾がある、カットがずれる、フィルターが見つからない、レビュー用サンプルがまばら、またはワークフローが繰り返し失敗する場合は、references/media-failure-modes.md を読みます。
• 主張の裏付け、バージョンに依存するガイダンスの更新、または技術的な実験の記録には、references/media-research-source-index.md を読みます。
• 受け入れ、証拠、EDL、レンダリング、受け入れ成果物が合成フィクスチャ上でエンドツーエンドに連携することを確認する場合は、references/editorial-workflow-example.md を読みます。
• カット、ケイデンス、連結、音声、字幕、または視覚的境界のサンプリングに対して、範囲を限定した実メディアのフィクスチャが必要な変更では、references/synthetic-media-fixtures.md を読みます。

FFmpeg のコア作業

• コンテナ、ストリーム、コーデック、オプションの適用範囲、マッピング、コピー／トランスコード、タイムスタンプについては、references/core-model-and-command-anatomy.md をお読みください。
• フィルターグラフ、ラベル、音声／動画の処理、段階的なグラフのデバッグについては、references/filters-and-transformations.md をお読みください。
• シーク、トリミング、連結、メタデータ、字幕、バッチ処理、パイプ、ストリーミングについては、references/intermediate-workflows.md をお読みください。
• ハードウェアアクセラレーション、同期、再現性、ネットワークの安全性、失敗時の境界については、references/advanced-operations-and-safety.md をお読みください。
• references/command-cookbook.md は、調査と機能の確認を行った後にのみお読みください。すべてのレシピには条件があります。
• 初心者向けのメンタルモデルについては、references/learning-summary.md をお読みください。
• FFmpeg の元のソース調査については、references/source-inventory.md をお読みください。ホスト固有の FFmpeg 8.1.2 に関する観察事項については、references/local-verification.md をお読みください。

テンプレート

• templates/media-intake.json — ソースの識別情報、プローブ、契約、プライバシー、保持、前提
• templates/edit-decision-list.json — レビュー可能なソース範囲と処理内容
• templates/video-inspection-report.md — 技術的な検査と範囲を限定したエビデンス台帳
• templates/visual-review-packet.md — フレーム／クリップの所見（出典付き）とカバレッジの限界
• templates/vision-review-observations.json — 準備済みパケット用の、解析可能で出典付きの所見ブロック
• templates/podcast-edit-plan.md — 音声に関する機械的、信号的、編集上の判断
• templates/media-acceptance-report.md — 階層的な検証と基準ごとの判定
• templates/media-acceptance-contract.json — ストリーム、フォーマット、エビデンス、ラウドネス、後続工程の要件を機械可読にしたもの
• templates/target-compatibility-manifest.json — 名前を指定した単一のターゲット、出典付きの要件、技術的制約、後続工程のレーン
• templates/research-experiment-record.md — 再現可能なバージョン／コマンド／結果の記録

再現可能な合成統合テストの証明が必要な場合は、新規または空のタスク専用ディレクトリで scripts/editorial-workflow-example を実行してください。その PASS_WITH_UNVERIFIED_BOUNDARIES という結果は、編集上の承認や納品先での受け入れよりも意図的に範囲を狭めています。

テストで個人情報を含まない決定論的なメディアが必要な場合は、scripts/generate-media-fixtures を実行してください。生成されたバイナリとマニフェストはタスクのワークスペースに保管し、コミットするのはジェネレーターとアサーションのみで、生成物は含めないでください。

単一ソースまたは複数ソースのプランを実行せずに作成するには、scripts/render-edl を使用してください。デフォルトではデコード済みの concat-filter によるアセンブリを使用し、プローブから得たシグネチャと検証済みのパケット／キーフレーム境界が一致する場合にのみ、concat-demuxer によるストリームコピーを選択してください。サポートされていないトランジションは、明示的なエラーとして残してください。

範囲を限定した無音、EBU R128、ピーク／クリッピング、文字起こしとのアラインメントのエビデンスには、scripts/audio-inspect を使用してください。各測定を明示的に要求し、利用できないフィルターは UNAVAILABLE として保持し、すべての区間や文字起こし範囲を、試聴レビューの候補として扱ってください。レポートの出力先を任意で指定した場合、既存ファイルへの上書きは拒否されます。

宣言済みの受け入れ契約、FFprobe の出力 JSON、任意のエビデンス JSON を指定して、scripts/media-verify を使用してください。各基準について、PASS、FAIL、BLOCKED、UNVERIFIED、NOT_APPLICABLE のいずれかを個別に報告します。必須エビデンスの欠落や失敗がない場合に限り、レポート全体が合格となります。

受け入れ条件で実際のプレーヤー、エディター、ホスト、アーカイブ、サービスが指定されている場合は、scripts/target-compatibility を使用してください。出典付きの技術要件、ローカルのプローブ結果、その特定の利用先から得られたエビデンスは分けて管理してください。合格判定が適用されるのは、指定されたターゲット／バージョンに限られます。

権限を持つ人間またはビジョンレビュー担当者向けに、範囲を限定したプライバシー安全なフレームパケットを準備するには、scripts/vision-review-handoff を使用してください。出典が明記されたレビュー済み所見のみを scripts/import-vision-review で取り込み、提案された編集上の影響はレビュー用のエビデンスとして扱い、自動判断には使用しないでください。

テンプレートをタスクのワークスペースにコピーし、プレースホルダーや例の値を置き換えてください。公開されているスキルリポジトリには、非公開のパス、メディア、文字起こし、レビューエビデンスを含めないでください。

必ず守る確認事項

• 複数の入力／トラックや複雑なグラフが関わる場合は、ストリームの選択を明示してください。
• オプションの順序は重要です。オプションは通常、次の入力または出力に適用されます。
• 無音を無価値と決めつけないでください。silencedetect が報告するのはしきい値の超過であり、編集上の価値ではありません。
• ラウドネス、クリッピング、タイミング、キーフレームの状態を主張する場合は、利用可能な測定方法に基づくものに限り、その出力を保持してください。
• 文字起こしがエビデンスとなるのは、記載されたテキストと提供されたタイミング精度についてのみです。フレーム精度の編集を行う前に、メディアと照合して抜き取り確認してください。
• エビデンスが乏しい場合、曖昧さによって意味のある内容が削除されるおそれがある場合、任意のツール／フィルターが利用できない場合、プライバシー／権限が不明確な場合、または実質的に異なる二つの手法が失敗した場合は、レビューのために作業を止めてください。

完了

要求された成果物が新しいパスに存在し、必要なプローブと範囲を限定したレビューが記録され、関連する下流の境界で出力が検証され、すべての受け入れ基準に合格するか、明示的にブロックされるまで完了としないでください。未検証の主張や残る前提は、もっともらしい出力で穴埋めせずに報告してください。