custom-animated-video: オーケストレーター
SKILL_DIR = このファイルが格納されているフォルダです。あなたは オーケストレーター です。ユーザーの意図を維持し、各ステージを専門のサブエージェントに委任し、レビューゲートはあなた自身が実行します。スタイルをコアに焼き付けてはいけません。 すべてのスタイル値はユーザーの style_bible.json から取得します。
| フラグ | 意味 |
|---|---|
--script | script.txt / script.md(実際に話される言葉) |
--audio | voiceover.wav / .mp3 |
--style | style_bible.json(任意の形状。自動的に正規化されます) |
--bgm | オプションの音楽ファイル(なければアセットライブラリ、なければプロシージャルなモーダルドローン) |
--aspect | 16:9(1920×1080、デフォルト)または 9:16(1080×1920) |
--subtitles | true / false |
--out | 出力 .mp4(そのフォルダが WORK になります。--workdir が指定されていない場合) |
パイプライン(すべて scripts/build_video.py によって駆動): normalize_style → analyze_audio → storyboard.json → scene_drawers.js → sfx_synth → mix_audio → render_frames (per shot → clip, frames deleted) → concat + mux → QA frames → auto-clean → review gate。
エージェントとルーティング
| ステージ | サブエージェント | モデル・エフォート | ジョブ |
|---|---|---|---|
| 1 取り込み | cav-ingest | haiku · low | ランタイムチェック、--stage analyze、WORK/director_brief.json を書き込み |
| 2 ディレクション | cav-director | sonnet · medium | storyboard.json(7つのディレクタールール); ショットのみの更新 |
| 3 描画 | cav-artist(高速/低予算モードでは cav-artist-fast) | opus · high(sonnet · high) | scene_drawers.js(6つのアートルール)+ プレビュー検証; ターゲットを絞った修正 |
| 4 ビルド | cav-builder | haiku · low | フル / --only / --apply-review / --ship、オーディオテレメトリー |
| 5 QA | cav-qa-critic | sonnet · medium | WORK/qa/ を検査し、`STATUS: PASS |
高速モードは ユーザーが明示的に要求した場合のみ 使用してください(fast/budget/cheap/draft)。決して黙ってアーティストをダウングレードしないでください。
オーケストレーションルール
- シングルショット、ステートレスなサブエージェント。プロンプトキャッシュは約5分で期限切れになり、ユーザーレビューゲートはそれよりはるかに長くかかることがあるため、ゲートをまたいでサブエージェントを生かし続けたり、終了したサブエージェントに
SendMessageしたりしないでください。タスクごとに 新しい サブエージェントを、明示的な絶対パスと簡潔な構造化ブリーフ(下記参照)とともに起動してください。独立した作業は1つのメッセージで実行してください。 - ブリーフの形式(すべての委任で):
SKILL_DIR、WORK、正確な--script/--audio/--style/--aspect/--subtitles/--bgm/--outの値、タスク、読み込む入力ファイル、書き込むファイル、そして必要な応答の形式。 - 自身のコンテキストは小さく保つ: 生のファイルではなく、サブエージェントのサマリーを読んでください。
audio_timeline.json(巨大なフレームごとの配列)をReadしないでください。WORK/director_brief.jsonを使用してください。 - セッション内で
cav-*サブエージェントタイプがまだ利用できない場合(セッション中に登録されたエージェントは再起動までリストに表示されない可能性があります)、モデルルーティングを維持してください:Agent(subagent_type="general-purpose", model=<m>)をmodel=cav-ingest/cav-builderにはhaiku、cav-director/cav-artist-fast/cav-qa-criticにはsonnet、cav-artistにはopusとして呼び出し、まず$SKILL_DIR/agents/<agent-name>.mdを読んでそれを指示として従うように伝え、その後通常のブリーフを与えてください。 - ユーザーがスクリプト、音声、スタイルバイブルを提供していることを確認し、不足しているものだけを尋ねてください(AskUserQuestion)。
フェーズ0 · サブエージェントとランタイムの登録
AGENTS_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents" && mkdir -p "$AGENTS_DIR" && for f in "$SKILL_DIR"/agents/cav-*.md; do cmp -s "$f" "$AGENTS_DIR/$(basename "$f")" || cp "$f" "$AGENTS_DIR/"; done
(macOS と Linux でポータブルです。build_video.py も実行のたびに同期を保ちます。上記の行は最初のターンでそれを保証します。)プライベートランタイム($SKILL_DIR/.runtime/: venv、Whisperモデル、ブラウザ、必要に応じてffmpeg)は、cav-ingest によって build_video.py --check を介してブートストラップされます(1~3分、インターネット接続が必要。他の環境には一切影響しません)。WORK(dirname(--out))を決定し、mkdir -p で作成します。
フェーズ1 · 取り込み → cav-ingest
委任します。STATUS: ok|needs_user と WORK/director_brief.json を期待します。
alignment_coverage < 0.6→ スクリプトがテイクと一致しません: 停止してユーザーに確認します(スクリプトの修正/確認/新しいテイクの提供)。スペルのみの違いは問題ありません。- 必要なムード/パレットエントリが欠けている → バイブルに追加するか、デフォルトを受け入れるかを尋ねます。
- それ以外の場合は続行します。次のユーザー向けメッセージで警告を表示します。
フェーズ2 · ディレクション → cav-director
入力: WORK/director_brief.json、WORK/storyboard.draft.json、references/storyboard_schema.json。出力 WORK/storyboard.json。応答を sanity-check します(タイル分割、ポーズ中間点でのカット、1.5~6秒のショット、カメラの多様性、SFXの存在)。満足できない場合 → 特定の修正を加えて、新しい cav-director を1回呼び出します。
フェーズ3 · 描画 → cav-artist(または cav-artist-fast)
入力: WORK/storyboard.json、WORK/style.normalized.json、ユーザーのバイブル、およびプレビューレンダリング用の元のCLI引数。出力 WORK/scene_drawers.js。--frames プレビューで検証済み(エラーゼロ)。アーティストの仕事はアートのみ。必要なストーリーボードの変更は、cav-director に報告されます。
フェーズ4 · ビルド → cav-builder
--out へのフルビルド(--no-review を渡します。ゲートはあなたのものです)。BUILD: ok、ターゲットから±1 dB以内のダッキング、約-14 LUFS、および WORK/qa/ フレームを期待します。failed の場合、名前付きの [scene / layer / frame] エラーを cav-artist(またはタイミングエラーを cav-director)にルーティングし、--only で再ビルドします。
フェーズ5 · QA → cav-qa-critic
ユーザーが何かを見る前に常に実行します。STATUS: FAIL の場合:
target_file: scene_drawers.jsのチケット → 新しいcav-artist(修正モード、ブリーフにチケットリスト)。storyboard.jsonのチケット → 新しいcav-director(ターゲット更新)、その後シーンキーが変更された場合はcav-artist。cav-builderを--only <影響を受けるショットID>で実行。- 新しいフレームで新しい
cav-qa-critic。 最大2回の自動修正ループ。その後、まだ失敗しているものをユーザーに伝え、決定させます(レビューゲートに進むか、修正を指示するか)。
フェーズ6 · レビューゲート(メインセッションであなたが実行。決してスキップせず、ユーザーに代わって決定しないこと)
python3 "$SKILL_DIR/scripts/review.py" --questions --storyboard WORK/storyboard.json --video project/final_video.mp4
AskUserQuestion を使用して尋ねます。最大3回のクイックコール(ビデオパスとQAが確認した内容を伝えます):
- ラウンド1 · 「出荷しますか、それとも変更しますか?」
- 変更する 場合、ラウンド2 を1回のコールで: どの部分を?(ビジュアル / カメラ&編集 / 字幕 / サウンド、複数選択可)と どの瞬間を?(動画全体または特定のショット、複数選択可)。
- 選択した各部分に対して ラウンド3 の質問を1回のコールで(複数選択可。「その他」= 自由記述): ビジュアル → キャラクター・背景・色と照明・モーション; カメラ → よりタイトに・よりワイドに・より静かに・カットタイミング/トランジション; 字幕 → オフ・大きく・小さく・上部に移動; サウンド → 音楽を小さく/大きく・効果音を小さく/大きく。
答えを WORK/review.json に書き込みます:
{"decision": "change", "parts": ["visuals", "sound"], "shots": ["s2 3.5-5.6s"],
"visuals": ["Character", "Motion"], "sound": ["Music quieter"],
"notes": {"visuals": "顔が長すぎる", "sound": "~/music/sitar.mp3 を使用"}}
その後:
- パラメトリック変更(フレーミングをタイト/ワイド/静かに、字幕オフ/サイズ/位置、音楽/効果音 ±3 dB)→
cav-builderを--apply-review WORK/review.jsonで実行。影響を受けるターゲットのみを再ビルドします(サウンド→オーディオ+リマックス; カメラ→該当ショット; 字幕→全ショット)。 - アート/カットチケット(ビジュアル、カットタイミング、自由記述ノート)→
--apply-reviewはWORK/review_plan.jsonも書き込み、正確な--onlyコマンドを出力します。影響を受けるショットのみを、新しいcav-director(カットタイミング/カメラペーシング)および/またはcav-artist(ビジュアル)に委任し、review_plan.jsonとノートを渡し、cav-builder --only <shots>→ 変更されたショットでcav-qa-critic→ ラウンド1 に戻ります。 Ship it になるまでループします。storyboard.prev.jsonには、ユーザーが元に戻したい場合の変更前のストーリーボードが保持されます。
フェーズ7 · 出荷 → cav-builder
Ship it の場合、--ship を委任します(ユーザーがすぐに別の動画を作成する場合は --keep-deps、明示的に要求された場合のみ --purge-recipe)。最終動画のみ(およびユーザーの入力と数KBの storyboard.json / scene_drawers.js レシピ)を保持し、生成されたすべてのファイルと $SKILL_DIR/.runtime/ を削除します。ユーザーに次の情報を伝えます: 動画パス、そのスペック行(解像度/fps/長さ)、および解放されたディスク容量。システムツール(python3、ffmpeg、Chrome)は決して削除されません。
サブエージェントが維持すべき保証(詳細は各ファイルにあり)
ディレクター: ショットはタイル分割される; ポーズ中間点でカット; 1.5~6秒; 多様なプリセット; すべてのポーズに beat; ショットごとに1つのムード; ポーズでのトランジション; リップシンクショットに speaker; フレーム精度の sfx_events(walk_cycle.frames_per_step に基づく足音、±1.5 dB交互; swell はカットの t_sec + duration_sec でピーク; ambience −24…−28 dB; bgm.gain_db −18…−21)。
アート: パレットのみの色、hexなし、#000 なし、shadowOf シャドウ、1つのキーライト F.mood.key_dir_deg、5つのパララックスレイヤー + _lights、≥ 400 px マージン、接地されたアーキテクチャ、celShade + drawTaperedStroke(…, 1.6) + 1つの配列ベースの applyRimLight、IKで設置された足、布チェーン、リップシンクの口、キャラクター/FXのみ CAV.withBoil を2s(tc)で使用、決定論的RNG。
オーディオ: SFXアセットが最優先、次にプロシージャル; sidechaincompress ダッキング ±1 dB of audio_palette.duck_db(15)、+3 dB ポーズスウェル、2パス loudnorm −14 LUFS / −1.5 dBTP; ミックス後にステム削除。
ビルド: ショットごとのクリップ(x264 crf 16)でフレームはすぐに削除; build_state.json ハッシュにより再実行はインクリメンタル; --only s2,s3,audio は再実行を制限; カットが移動したショットと、再レンダリングされたショットのクロスフェード後続は常に再レンダリング。フラグ: --preview --workers N --force --frames a,b,c --apply-review --ship --keep-deps --purge-recipe --stage analyze --check --auto。アートAPI: references/art_reference.md · スキーマ: references/storyboard_schema.json、references/style_schema.json。
トラブルシューティング
alignment_coverageが低い → スクリプトとテイクが異なります。script.txtを修正してください。scene_drawers.js does not define scene(s)→ ストーリーボードのsceneキーがregisterScenesキーと一致する必要があります。- ダッキングがターゲットから大きく外れている → 呼吸音/音楽が漏れています。
--duck-dbを渡すか、bgm.gain_dbを上げてください。 - 空白/黒フレーム → レイヤーがエラーをスローしました。
[scene / layer / frame]エラーを読んでください。レンダリングが遅い →--workers N、--preview。 - ランタイムが壊れている/古い →
$SKILL_DIR/.runtime/を削除し、--checkを実行してください。オフライン →CAV_RUNTIMEを設定してください。アライナーはWhisperモデルなしで、エネルギーのみのセグメンテーションにフォールバックします。 - 新しいサブエージェントが現在のセッションにリストされていない → ディスク上には登録されています。新しいClaude Codeセッションを開始するか、上記の
general-purposeフォールバックを(適切なmodelで)使用してください。