Communitygithub.com

notque/vexjoy-agent

ビデオ編集パイプライン:FFmpegとRemotionを使用した映像のカット、クリップのアセンブル

vexjoy-agent とは?

このスキルは、AIによる判断(何を残すか、何をカットするか、ハイライトの選択)と、FFmpeg/Remotionによる決定論的な機械実行を組み合わせた、6層のビデオ編集パイプラインを実装します。ソース映像のインベントリ、AIによる構造化(トランスクリプトからEDLを作成)、FFmpegによるEDLに基づいた正確なカット、Remotionによるプログラム可能なオーバーレイやタイトルの合成、必要に応じてElevenLabsやfal.aiを使用した生成アセットの追加、そして最終的な人間の判断による仕上げの各フェーズで構成されています。このスキルは主にClaude CodeなどのAIエージェント向けに設計されており、エラーハンドリングやゲートチェックを含む詳細な手順が提供され、再現性と信頼性を保証します。特に、EDLファイルを唯一の情報源とし、シェルグロブではなくEDLの順序に従って連結リストを生成するなど、決定論的な動作を重視している点が特徴です。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/notque/vexjoy-agent/tree/HEAD/skills/content/video-editing

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

ビデオ編集スキル

概要

このスキルは、AIが判断タスク(何を残すか、何をカットするか、ハイライト選択)を処理し、FFmpeg/Remotionが決定論的に機械実行を行う6層パイプラインを実装します。

層名称メカニズム主要ツール
1キャプチャソース映像のインベントリBash + Glob
2AI構造化トランスクリプトからEDLへLLM判断
3FFMPEGカットEDLからセグメントファイルへFFmpeg(決定論的)
4REMOTION合成セグメントからTSX合成へRemotion + TypeScript
5AI生成生成アセットでギャップを埋めるElevenLabs / fal.ai(条件付き)
6最終仕上げ人間の審美眼レイヤー人間 + NLE

詳細リファレンス

シグナルロード内容
各フェーズのシェルコマンド、ゲートチェックreferences/phase-commands.mdフェーズ1〜6の完全なコマンドブロック
FFmpegレシピ:カット、連結、プロキシ、検出references/ffmpeg-commands.mdタイムスタンプ抽出、バッチカット、オーディオ正規化、シーン/無音検出
Remotion合成スキャフォールドreferences/remotion-scaffold.mdTSX合成テンプレート、レンダーコマンド、再利用パターン
画像から動画へのパイプラインreferences/image-to-video.md検証、準備、エンコード、確認ワークフロー
可視化のためのFFmpegフィルターグラフreferences/ffmpeg-filters.mdスケール/パッド、showwaves、showspectrum、オーバーレイ、完全なフィルターグラフ

手順

事前確認(フェーズ1の前に実行)

ハード要件(欠けている場合はブロック):ffmpeg(全フェーズ)、node(Remotion / npx)。 ソフト要件(欠けている場合は警告):remotion(フェーズ4でのみ必要)。

which ffmpeg >/dev/null 2>&1 || { echo "エラー: ffmpeg が見つかりません。インストール: brew install ffmpeg (macOS) | apt install ffmpeg (Linux)"; exit 1; }
which node >/dev/null 2>&1 || { echo "エラー: node が見つかりません。インストール: https://nodejs.org または nvm 経由"; exit 1; }
npx remotion --version >/dev/null 2>&1 || echo "警告: remotion CLI が見つかりません。フェーズ4は利用不可。インストール: npm install @remotion/cli"

フェーズ1: キャプチャ

目標: すべてのソース映像をインベントリし、処理前にファイルがディスク上に存在することを確認します。

制約: ソースファイルは読み取り専用です。すべてのFFmpegコマンドは新しいファイルにのみ書き込みます。ソース映像を上書きしないでください。

手順: ソースファイルの検索(find)、各ファイルをffprobeで検査、10分を超えるファイルのプロキシ生成(references/ffmpeg-commands.md -> プロキシ生成を参照)、作業ディレクトリ(segments/、assembled/)の作成。完全なコマンドブロック: references/phase-commands.md -> フェーズ1。

ゲート: ソースファイルがディスク上に確認されました。ファイルリストがsource-inventory.txtに書き込まれました。ゲートが通過した場合のみ次に進みます。


フェーズ2: AI構造化

目標: コンテンツを分析し、下流のすべてのカットを駆動する記述されたEDL(cuts.txt)を生成します。

制約: cuts.txtが契約です。EDLファイルは下流フェーズの唯一の情報源です。FFmpegコマンドを手動編集しないでください — EDLからコマンドを生成してください。

制約: EDLを手動で記述する前に、FFmpegのシーン/無音検出を実行してください。検出出力は判断を支援しますが、置き換えるものではありません。

手順: whisper/AssemblyAIで文字起こし、シーン/無音検出の実行、判断の適用(何がナレーションを進めるか、何がフィラーか、目標時間)、cuts.txtをEDL形式開始時間,終了時間,ラベルで記述、重複と合計時間の確認。完全なコマンドブロックとEDL形式の例: references/phase-commands.md -> フェーズ2。

ゲート: transcript.txtが存在します。cuts.txtがディスクに書き込まれました。両方のファイルが存在する場合のみ次に進みます。


フェーズ3: FFMPEGカット

目標: EDLを決定論的に実行 — cuts.txtのセグメントごとに1つのFFmpegカットを実行します。

制約: ループを使用してEDLからバッチカットします。カットごとに個別のFFmpegコマンドを作成しないでください。これにより、リストとしての再現性とレビュー可能性が保証されます。

制約: 常にcuts.txtの順序からconcat-list.txtを生成し、シェルグロブからは生成しないでください。シェルグロブ(segments/*.mp4)はアルファベット順にソートされ、EDLの順序にはなりません。

手順: whileループでEDLからバッチカット(libx264/aac、-avoid_negative_ts make_zero)、セグメントの確認、EDL順にconcat-list.txtを生成、-f concat -safe 0 -c copyで連結。完全なコマンドブロック: references/phase-commands.md -> フェーズ3。references/ffmpeg-commands.md -> バッチカットも参照。

ゲート: すべてのセグメントファイルが存在します。assembled/rough-cut.mp4がディスクに書き込まれました。ゲートが通過した場合のみ次に進みます。


フェーズ4: REMOTION合成

目標: プログラムによるオーバーレイ、タイトル、またはトランジションのために、セグメントをRemotion TSX合成でラップします。

使用タイミング: rough-cut.mp4にプログラム要素(アニメーションタイトル、ローワーサード、キャプショントラック、ブランドオーバーレイ)が必要な場合のみ。rough-cut.mp4で十分な場合は、フェーズ6にスキップします。

制約: レイヤー4はTypeScript/Reactを必要とします。TSX作業はtypescript-frontend-engineerに委譲し、フェーズ5以降はpython-general-engineerに戻します。

手順: Remotionの初期化(初回はnpm create video@latest、それ以外はnpm install @remotion/cli @remotion/player remotion)、合成のスキャフォールド(references/remotion-scaffold.mdを参照)、npx remotion renderでレンダリング。完全なコマンドブロック: references/phase-commands.md -> フェーズ4。

ゲート: assembled/remotion-output.mp4が存在します。ゲートが通過した場合のみ次に進みます。


フェーズ5: AI生成

目標: ソース素材の真のギャップを生成アセットで埋める — 必要な場合のみ。

制約: 何かを生成する前に、既存の映像がギャップをカバーしているか確認してください。存在しないものだけを生成します。

判断ツリー: ギャップの周りをカット → cuts.txtを更新しフェーズ3を再実行;ナレーション → ElevenLabs(認証が必要);音楽 → fal.ai(fal-ai-mediaに委譲);Bロール → fal.ai(fal-ai-mediaに委譲)。ElevenLabs Pythonヘルパー、認証パターン、ディスク保存フロー: references/phase-commands.md -> フェーズ5。

ゲート: 必要な生成アセットがすべてassets/ディレクトリに保存されてから次に進みます。


フェーズ6: 最終仕上げ

目標: アセンブルされた出力を提供し、審美眼レイヤーを人間に引き継ぎます。

制約: レイヤー6は人間の領域です。スキルはアセンブルし、人間が仕上げます。以下は人間の判断を必要とし、プログラム的に試みるべきではありません:

  • クリップ間のカラーグレーディングとカラーマッチング
  • 音楽のタイミングと音量ダッキング
  • キャプションのスタイル、フォント、配置
  • トランジションのタイミングとスタイル
  • 最終オーディオミックスレベル

引き継ぎテンプレート(handoff-notes.txt、ソースリスト、EDL、ラフカットパス、人間に残されたチェックリストを含む): references/phase-commands.md -> フェーズ6。

ゲート: assembled/rough-cut.mp4(またはassembled/remotion-output.mp4)が存在します。handoff-notes.txtがディスクに書き込まれました。


ビデオ文字起こし抽出

動画の文字起こしを読みやすい段落として取得します。アップロード者の字幕を優先し、自動生成をフォールバックとして使用します。

# パス1: アップロード者字幕(正確)
yt-dlp --skip-download --write-subs --sub-langs en --sub-format vtt -o '<作業ディレクトリ>/%(id)s' '<URL>'
# パス2: 自動生成(パス1でファイルが書き込まれなかった場合のフォールバック)
yt-dlp --skip-download --write-auto-subs --sub-langs en --sub-format vtt -o '<作業ディレクトリ>/%(id)s' '<URL>'
# VTTを段落に変換
python3 skills/research/video-transcript/scripts/vtt_to_paragraph.py <作業ディレクトリ>/<id>.en.vtt

オプション: --timestampsで[mm:ss]マーカー、--keep-bracketsでキュータグ、-o FILEでファイル出力。他の言語: --sub-langsを変更。利用可能な言語を一覧表示: yt-dlp --list-subs '<URL>'。

エラーハンドリング

エラー原因解決策
ソースに対する「そのようなファイルやディレクトリはありません」cuts.txtのパスがファイル名と一致しないcat source-inventory.txtを実行。スペースを含むパスは引用符で囲む。
FFmpeg「無効なオプション」またはコーデックエラーコーデックが利用不可、またはフラグ構文エラー`ffmpeg -codecs
Remotion「コンポジションが見つかりません」コンポジションIDの不一致src/index.tsで登録されたIDを確認。レンダーコマンドで完全に一致させる。
セグメント連結の順序誤りシェルグロブがアルファベット順にソートされるため、EDL順にならないglobではなく、cuts.txtの順序からconcat-list.txtを生成する。
ElevenLabs 401ELEVENLABS_API_KEYが設定されていないフェーズ5の前にexport ELEVENLABS_API_KEY=your_keyを実行。
文字起こし抽出で.vttファイルがないビデオに要求された言語の字幕がないyt-dlp --list-subs '<URL>'を実行し、利用可能な言語を選択する。

関連スキル