/reel: Claude Code 向け動画制作
ffmpeg をベースにした多層ツールです。あなた (Claude) が素材を確認し、何を表示するか決めて計画を書き、コードがフレーミング、レンダリング、チェックを行います。出力サイズは設定可能です(デフォルトは縦 1080x1920)。
コマンドとファイル形式は reel リポジトリの docs/ENGINE.md に文書化されています。最初のコマンドの前にこれを読んでください: cat "$(reel --root)/docs/ENGINE.md"。reel <command> --help ですべてのオプションが表示されます。各コマンドは1つのJSONオブジェクト ({"ok": true, "result": ...} または {"ok": false, "error": {"code": ..., ...}}) を出力し、失敗時は終了コード1で終了します。
作業順序: まず方向性、次に編集
ユーザー以外の誰かが見る動画については、SOP.md に従ってください: S0 受け入れ、S1 ソースパッケージ、S2 アセット棚卸し、S3-S4 で director エージェントが direction/BRIEF.md とストーリーボードを作成し、その後にすぐ編集します(承認ステップG1はデフォルトではブロックしません)。その後、下記の納品ゲートに進みます。S7では別の director エージェントがカットを BRIEF と照合してレビューします。プラグインとしてインストールされ、エージェント名は reel:director です。
- ディレクターには、あなた自身の結論ではなく、元の素材のパスを渡してください。
- 承認済みの BRIEF が存在し、目的、対象者、素材の範囲が変わっていない場合は、それに従ってください。
- ユーザーが動画が退屈または意味がないと言った場合は、S3に戻って作品を再考してください。単に再編集するだけではいけません。
納品ゲート (必須)
各ステップはコードで強制されます。1つでもスキップすると最終カットを納品できません。
- 最初にブリーフを書く (
$P/brief.json、テンプレートは下記) に登録:reel register brief.json。納品言語、最終版かサンプルか、納品フォルダ、変更してはいけないものについて、これらを記入できない場合はユーザーに尋ねてください。登録されると、Bash ガードフックがcp/mv/ffmpegによる納品フォルダへの書き込みを拒否します。 - 音声をオーディションする。 デフォルトの音声はありません。ブリーフに合ったものを選び、10〜20秒のサンプルをレンダリングし、
reel voice check sample.mp3 --script sample.txt --brief brief.jsonを実行します。ローカルの Whisper がサンプルを文字起こしし、テキストと比較します (--langはデフォルトでen、中国語のナレーションの場合は--lang zhを渡します。声調なしのピンインで比較するため、同音異字のスペルはエラーとしてカウントされません)。エラー率が10%以下の場合のみ、brief.voice.approvedに承認が書き込まれます (by: claude、トランスクリプトを証拠として)。ユーザーが聞いた場合は、代わりにユーザーの正確な言葉を記録してください。- STT は単語が正しく明確に読まれていることを証明します。声が作品に合っているかは証明しません。返信でその音声を選んだ理由を述べ、ユーザーが気に入らなければ次のバージョンで音声を切り替えてください。
- 新しい音声は新しいチェックが必要です。macOS の
say音声は内部ドラフト専用で、納品する動画には決して使用しないでください。
- レンダリングをチェック:
reel check final.mp4 --plan plan.json --brief brief.json [--profile vertical-strict|project-profile.json] [--text caption.txt]。- 終了コード1は納品不可を意味します。
result.gate.blockers(技術的な失敗: サンプルすら納品できない) とresult.gate.pending_review(レビューアーが確認すべき項目) を読んでください。 okだけに依存しないでください。result.gate.not_coveredはチェックされなかった項目をリストします(例: 画面上のテキスト、OCRがありません)。それらの項目がチェックされたと決して言わないでください。
- 終了コード1は納品不可を意味します。
- レビュー。 すべての
needs_review項目 (reel scrub、フレームグラブ) を確認し、各項目に対するタイムコード付きの観察事項を含むレビューレコードを1つ書いてください。カット全体を自分で視聴しfinal_watchに署名してください (ショットごとに少なくとも1フレーム)。最初から最後まで聴き、final_listenに署名してください (エージェントの署名にはタイムコード付きの観察事項が必要です。ユーザーが聴いた場合は、ユーザーの正確な言葉をquoteとして記録してください)。両方に署名したら、最終版として納品します。レシートにはapproved_by: agentと表示され、あなたの返信には「最終版、Claude レビュー済み、まだあなたはご覧になっていません」と記載されます。ユーザーのフィードバックは次のバージョンに反映されます。reviews.jsonの形式はdocs/ENGINE.mdにあります。 - 納品:
reel deliver final.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json。- 最終条件が満たされていない場合、
DELIVERY_NOT_FINALで失敗し、その理由をリストします。その場合は--sampleのみが可能です: ファイル名にはsample-pending-reviewが付加され、ユーザーに伝える際はサンプルと呼ぶ必要があります。 - バージョン番号は一度だけ納品できます。古いバージョンが削除されたり上書きされたりすることはありません。ユーザーが明示的に古いバージョンの削除を要求した場合のみ:
reel register brief.json --removeを実行し、削除してから再登録します。
- 最終条件が満たされていない場合、
- 「完了」と言うには
status: finalのレシートが必要です (reel receipt <receipt.json>で再検証されます)。そうでない場合は実際のステータスを述べてください:「未完了」、「レビュー待ちサンプル」、「音声未オーディション」。Stop フックは、一致するレシートがない完了の主張をブロックします。 - プロジェクト独自のレンダースクリプト (
build_*.pyなど) で作成された動画、または別のツールで構成されてエクスポートされた動画も、ステップ3〜6を経ます。
{"version": "reel.brief.v1", "name": "spring-promo", "language": "en", "deliverable": "final",
"delivery_root": "~/Videos/deliveries/spring-promo", "must_not_change": ["end card credit"],
"voice": {"mode": "recorded"}, "profile": "default"}
voice.mode:none(音声なし)、recorded(実際の録音)、ttsまたはclone(これらはreel voice checkによって書き込まれたvoice_idとapprovedブロック、またはquote、sample、sample_sha256を含む人間の承認が必要です)。delivery_rootは既存の絶対パスである必要があります(または~で始まる)。ホームフォルダ、Desktop、Documents、Downloads、iCloud Drive ルート、プロジェクトフォルダまたはその親であってはなりません。- 無音バージョンはプロジェクトプロファイルを使用します:
{"extends": "default", "audio": "silent"}。 - プロファイル:
default(一般的な開始しきい値) とvertical-strict(1080x1920 30 fps、-16 LUFS、厳格)。プロジェクトの違いはextendsを使用してプロジェクトプロファイルに記述します。意図的な長いホールドは理由とともにallowに登録します。禁止語句 (古い製品名、フィラーテキスト) をtext.extra_bannedに追加します。
各 Bash 呼び出しの先頭で
各 Bash 呼び出しは新しいシェルで開始されるため、すべての呼び出しは次のように始めてください:
REEL_PROJECT=spring-promo # このプロジェクトの名前
command -v reel >/dev/null || { echo "reel が PATH にありません (プラグインを有効にするか、./install.sh --link を実行してください)" >&2; return 1 2>/dev/null || exit 1; }
command -v ffmpeg >/dev/null || { echo "ffmpeg が見つかりません" >&2; return 1 2>/dev/null || exit 1; }
P="${REEL_PROJECTS_DIR:-$HOME/reel-projects}/$REEL_PROJECT"; mkdir -p "$P/preview" && cd "$P"
すべての出力は $P に配置され、一時フォルダには決して配置されません。以下の相対パスは $P からの相対パスです。
カットの作成
あなたが判断 (どのショット、どの被写体、カメラの動き、ペース) を行います。認識、ジオメトリ、レンダリング、チェックはコードが行います。完全なコマンド構文は docs/ENGINE.md にあります。
- 素材 を
$Pに配置 (アセット、observations.json、plan.json、プレビュー、レンダリング、チェックレポートはすべてそこに格納されます。フォルダごとに1つの plan)。 - スクリプトと音声。 ナレーションスクリプトを作成し、ブリーフに合った音声を選び、オーディションに合格します (ゲートステップ2)。
voice.mp3(または.wav) を生成し、字幕が必要な場合はvoice.vttも生成します。公開作品には実際の録音または使用範囲をカバーするライセンスの音声を推奨します。音楽のみの作品の場合はaudio.voiceに音楽トラックを指定します (これがタイムラインのアンカーになります)。 - 確認とターゲットの選択:
reel inspect(各ファイルをリスト) →reel frame(0-1グリッドで画像を読み、被写体のボックスを読み取る) →reel observeで登録、またはreel locate --query ... --check-png ...(OWLv2; 検出を使用する前にチェック画像を確認)。 plan.jsonを書く (EditPlan v1):camera: []はフレームを静止させます。zoom_toとobservation_idで登録された被写体にズームインします。動画内で被写体が動く場合はtrackを使用します。transition_outはトランジション用です。inspectによって報告されたシーンカットを動画ショットがまたがないようにします。audio.voiceは必須で、src_dirに対して解決されます。- 検証とプレビュー:
reel validate→reel compile→reel preview plan.json s2 --out preview/s2.mp4 --sheet preview/s2.png、その後コンタクトシートを読んでカメラの動きを判断します。 - レンダリング:
reel render plan.json --out "$P/final.mp4" --sheet "$P/preview/final.png" --where local(ユーザーがリモートGPUを設定して要求した場合のみ--where remoteを使用)。レンダリングチェックに合格したということは、ファイルが壊れていないことを意味するだけです。ゲートステップ3〜6に進んでください。
他のエントリポイント (各項目に docs/ENGINE.md 内のセクションがあります):
- タイムラインの検査と変更:
reel timeline(--format textまたは--pngマルチトラック画像)、reel scrub(各カットの周辺フレーム)、reel edit/undo/history、reel preview --range(音声付き低解像度プレビュー)。 - ビートに合わせたカット:
reel beats music.mp3 --out beats.json→reel snap plan.json --beats beats.json --mode downbeat。その後、各カットをreel timeline --png --beatsで確認します。./install.sh --beatsが必要です。 - ハイライト付きウェブページのナレーション:
kind: "web"のショット。テキスト位置は DOM から取得されます (OCR は使用しません)。そのため、ハイライトされる文はページのテキストと完全に一致している必要があります。reel words voice.mp3で単語ごとのタイミングが得られます。./install.sh --webが必要です。 - Shotcut プロジェクト:
reel mlt project.mlt --video-only;--dupesで2回使用されているソース映像を見つけます。
利用可能: プランアセンブリ、サブピクセルプッシュイン、動く被写体の追跡、xfade トランジション、焼き込み字幕、背景音楽、グレーディングと LUT、ウェブショット、OWLv2 被写体検索、技術チェック、ゲート付き納品。 組み込まれていないもの: イーズトランジション、フレーム補間、音声クローン。
リモート GPU (オプション)
--where remote の部分はコードで強制されます。
- ユーザーが
REEL_REMOTE(ssh 接続先) を設定し、それを要求した場合にのみ使用します。そうでない場合は--where localでレンダリングします。 - VRAM 使用量はデフォルトで80%に制限されています。ジョブがそれ以上必要とする場合、ツールは
NEED_USER_APPROVALを返します。まずユーザーに伝え、ユーザーの同意がある場合のみ--allow-over-80を追加してください。GPU 使用率が50%以上の場合は他の誰かが使用していることを意味します。使用しないでください。 - 1度に1つの reel GPU ジョブ (リモートファイルロック)。電力制限を変更しないでください。ホストを再起動またはシャットダウンしないでください。
reel remote probeでホスト情報を報告します。reel remote setup-visionでリモートホストに torch と OWLv2 重みを含む別の venv をインストールします。
付属ファイル
SOP.md: 方向性優先のワークフロー、役割、ステップ、終了条件。directorエージェント (リポジトリ内agents/director.md): ブリーフ、ストーリーボード、レビュー。- リポジトリ内
docs/ENGINE.md: コマンド、EditPlan、ブリーフ、レビュー、レシート、プロファイル。