ffmpeg による動画編集

あなたはマウスとタイムラインではなく、トランスクリプトとフィルターグラフで作業する編集者です。パイプラインは決定論的です。すべてがテキストとして編集され、単一のコマンドで再構築されます。

footage → 単語レベルのタイミング付きトランスクリプト → EDL（編集リスト） → ffmpeg → 完成動画
                    ↑                               ↑
             faster-whisper                 手作業で編集 — これが編集そのものです

中核となる原則：動画をピクセル単位で分析することはなく、編集はタイムスタンプ付きテキストによって駆動されます。 スピーチが構造を定義し、映像はそれに従います。

1リールか、それとも複数リールか？

最初にこれを決定してください。これにより、以降のすべてが変わります。

1～2リール → 以下のステップ順に対話的に従います。
3リール以上 → バッチパイプラインに切り替えます：references/batch-pipeline.md。各ステージはプロジェクト全体に対して一度だけ実行され、入力ハッシュによってキャッシュされます。10リールを対話的に処理すると、おおよそ10倍のコンテキストを消費し、それに見合うメリットはありません。

作業の順序

常にステップに従い、先に進まないでください。各ステップが次のステップへの入力を生成します。

環境を確認する。 ffmpeg / faster-whisper / Chrome がない場合 → references/setup.md。クリーンなマシンでは10分かかります。
ソースを取得する。 ユーザーがファイルではなくURLを渡した場合は、最初に download.py で取得します。
ソースを検査する — ffprobe、シーン検出、コンタクトシート。 Read を使って自分の目でフレームを確認します。 テキストだけを見て盲目的に編集しないでください。
文字起こし を単語レベルのタイミングで行い、結果を校正する。音声認識は、クリーンな音声でも単語を誤認識します。ローカルモデルがない場合？ transcribe_cloud.py は Groq/OpenAI から同じ出力を取得します。
コンセプトについてユーザーと合意する（ユーザーが指定していない場合）：フォーマット、グラフィックスに含める内容、ターゲットプラットフォーム。質問は一つで、アンケートではありません。
EDL を構築する — 間をカットし、アイデアを決してカットしない。
base を構築し、カットをフレーム単位で確認します。
字幕とオーバーレイを生成し、final を構築します。
受入チェックリストを実行し、SendUserFile でファイルを納品します。

各ステップの完全なコマンドについては、references/pipeline.md を参照してください。

このパイプラインでできること、できないこと

できること：意味的なカット、間の削除、カットポイントへのズームイン、カラーグレーディング（.cube LUT を含む）、単語レベルの字幕、HTML/CSS による任意の複雑なインフォグラフィック、手ぶれ補正、ソーシャルプラットフォーム向けラウドネスノーマライゼーション、バッチ処理。Remotion プラグインがインストールされている場合は、React からレンダリングされたアニメーショングラフィックスも可能です — references/remotion.md を参照してください。

まったくできないこと — ユーザーが要求した場合、最初に伝えてください：オブジェクトトラッキング（動く手にキャプションを固定する）とマスクされたグレーディング。これらには依然として Premiere / DaVinci / After Effects が必要です。

単独ではできないが、FableCut がインストールされていれば可能なこと： フレーム正確なクリエイティブカット、キーフレームアニメーション、トランジション、スピードランプ、クロマキー、音楽のビートに合わせたカット。FableCut は、エージェントが MCP を通じて操作するブラウザタイムラインです — references/fablecut.md を参照してください。これには音声認識機能はなく、書き出しには人間のクリックが必要なため、音声主導の構造化と無人バッチ処理はこのパイプラインに残ります。

既製のツール

assets/tools/ には12の実用的なスクリプトが含まれています — プロジェクトにコピーして使用し、ゼロから書き直さないでください：

スクリプト	機能
`download.py`	URL からソース映像を取得（yt-dlp）— ローカルファイルが既にある場合はスキップ
`transcribe.py`	faster-whisper → 単語レベルのタイミング + `.srt` を持つ `transcript.json`
`transcribe_cloud.py`	同じ出力を Groq/OpenAI Whisper API 経由で取得 — モデルのダウンロード不要、API キーが必要
`pauses.py`	スピーチ内の間をリスト化 — EDL の基礎
`dump_words.py`	インデックスと信頼度付きのすべての単語 — 校正用
`make_ass.py`	単語レベルの ASS 字幕、カット後のタイムラインに再調整
`render_overlays.py`	HTML/CSS → ヘッドレス Chrome → アルファチャンネル付き 1080×1920 PNG
`build.py`	アセンブリ：`base`（カット + グレード）、`final`（オーバーレイ + 字幕 + 音声）
`build_vo.py`	同上、ただし別のナレーショントラック用 — 複数のソースからのビデオを音声に合わせる
`batch_vo.py`	すべてのナレーションを1回のモデルロードで文字起こし
`mute_subs.py`	フルスクリーンカードが表示されている場合に字幕を削除
`pipeline.py`	バッチドライバー — すべてのリールのすべてのステージを、キャッシュ付きで処理

assets/templates/ には、スターター用の edl.json、overlays.json、corrections.json が含まれています。

プロジェクトを次のようにレイアウトします：

<映像が入っているフォルダー>/    
├── IMG_XXXX.MOV
└── edit/
    ├── tools/        ← コピーしたスクリプト
    ├── work/         ← 中間ファイル、出荷しない
    ├── overlays/     ← レンダリングされた PNG
    ├── out/          ← 完成した動画
    ├── edl.json  overlays.json  corrections.json  subs.ass

リファレンスファイル

すべてを一度にロードせず、必要に応じてロードしてください：

references/setup.md — クリーンなマシンへのインストール（Windows/macOS）、ffmpeg ビルドの確認
references/pipeline.md — ワークフローのステップバイステップ、カットルール、コマンド
references/storyboard.md — ビデオフォーマット、パネルタイプ、トーキングヘッドのストーリーボードの作成方法
references/design-system.md — パレット、タイポグラフィスケール、セーフゾーン、オーバーレイ手法
references/batch-pipeline.md — 多数のリールをステージとして実行する方法と、コンテキストが実際に消費される場所
references/remotion.md — アニメーショングラフィックスの段階：React でレンダリングされたオーバーレイがコストに見合う場合
references/fablecut.md — タイムライン段階：編集を FableCut に引き継ぐタイミングと、2つのパイプラインの連携方法
references/ffmpeg-cookbook.md — グレーディング、エフェクト、トランジション、音声、エンコーディング
references/troubleshooting.md — 最初の ffmpeg 実行の前にこれを読んでください；17の失敗例、それぞれ1時間の費用がかかります

動画の成否を分けるルール

ドキュメントではなく、実際の制作から学んだことです。

フレームを確認する。 トランスクリプトは、その瞬間に話者が立ち上がっているか、髪を整えているかを教えてくれません。それらこそがまさに、カットが破綻する箇所です。
カードは顔の上ではなく、顔の上に配置する。 最初の試みでは、常にパネルをフレーム中央に配置してしまい、目を覆ってしまいます。話者の視線は、動画が獲得する信頼の半分です。
ストップウォッチではなく、フレーズの終わりでカットする。 「N秒ごと」にカットすると、アイデアが半分に分割されます。
すべての間の0.2～0.3秒は残す。 間をゼロに縮めると、どもっているように聞こえます。
劇的な間には決して触れない — 質問の後、結論の前。そこでは沈黙が機能しています。
セグメント間で zoom を交互に使用する。 そうすれば、カットはミスではなくアングルの変更として認識されます。
グラフィックスが一切ない部分を一つ残す。 視聴者には息抜きが必要です。カードの壁が続くと疲れます。
字幕を校正する。 認識エラーが映像に焼き付くと、永久に残ります。
信仰ではなく、見て確認する。 静止フレームを抽出し、hstack で積み重ね、Read で結果を開きます。
pipeline.md の受入チェックリストなしに出荷しない。
ツールに設定ファイルに書き戻させない。 独自の出力を EDL に追加するスクリプトは、ファイルサイズを2倍にし、その後の編集のたびに全体がコンテキストに反映されます。生成されたデータは work/ に属します。
トランスクリプトの最初と最後の行は自分で読む。 Whisper は沈黙中に捏造されたテキストを幻覚することがあります — 古典的にはロシア語音声に対する偽の字幕作成者クレジット行 — そしてそれはまったく正常に見える信頼度スコアを持つ可能性があります。両方の文字起こしスクリプトは明らかなケースを自動的にフィルタリングしますが、フィルターは完璧ではありません。troubleshooting.md #17 を参照してください。

オーケストレーション

タスクは複数ステップです — ステージ（トランスクリプト、EDL、グレード、グラフィックス、アセンブリ）に対して TaskCreate でタスクを作成し、それらのステータスを最新に保ちます。長時間の操作（モデルのダウンロード、base のレンダリング）はバックグラウンドで実行し、それらに依存しない作業に時間を使用します：モデルがダウンロードされている間に、オーバーレイをデザインし、静止フレームでグレードをテストします。

完成した動画は、SendUserFile と、変更点に関する短いメモを添えて納品します。

blazerior — 縦型EDL+カラオケ精錬