reel — agent の動画制作 / 編集ツール
ffmpeg を中核とした階層型ツール:agent が素材を確認し、目標を定め、plan を記述。コードがフレーミング、レンダリング、検収を担当。アスペクト比は設定可能(デフォルトは縦型 1080×1920)。
コマンドとフォーマットの詳細はエンジン README と docs/engine.zh.md にあるので、作業前に必ず読むこと。
納品ゲート(必須)
ルールは実行されなければ意味がありません。以下の各ステップはコードで強制され、従わなければ「完成品」を納品できません。
- 作業開始前に brief を書く(
$P/brief.json)そして登録:reel register brief.json。納品言語、完成品かサンプルか、納品ディレクトリ、変更禁止事項を明記。書けない場合はユーザーに質問。登録後、Bash で cp/mv/ffmpeg を使って直接納品ディレクトリに書き込むか、reel … --out PATH/--out=PATH(--png、--sheet、--report、--check-pngも同様)で納品ディレクトリを指定しようとすると、hooks/guard_delivery.pyが拒否する。このガードはコマンドテキストを解析するベストエフォート方式。ワイルドカード、中括弧、コマンド置換、スクリプト内部、リモート書き込みは防げない可能性があるため、許可証とみなさないこと。納品は必ずreel deliverを使う。 - 音声は先に試聴:固定のデフォルト音声はない。最初に 10~20 秒のサンプルを人間に聴かせ、承認を得たら、その発言、サンプルパス、サンプルの sha256 を
brief.voice.approvedに記録。音声を変更する場合は再試聴が必要。 - 出力後にチェック:
reel check 完成品.mp4 --plan plan.json --brief brief.json [--profile default|social-vertical|プロジェクト.json]。exit 1 = 納品不可。result.gate.blockers(技術的不合格)とpending_review(人間の確認が必要)を確認。not_coveredはチェックされなかった項目なので「チェック済み」とは言えない。 - レビュー:
needs_reviewの各項目を確認(reel scrub/ コマ送り)。各項目にタイムコード付きのレビュー記録を記述。全体を通して見たらfinal_watch、聴いたらfinal_listenを記録。 - 納品:
reel deliver 完成品.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json。完成品の条件を満たさない場合はDELIVERY_NOT_FINALが報告され、--sampleのみ許可、ファイル名には「確認用サンプル」と付与。同一バージョン番号で再納品不可。旧バージョンは削除も上書きもしない。 - 「完了」と言える条件:
status: finalのレシートを受け取ること(reel receipt <レシート>で確認可能)。そうでなければ「未完了 / 確認用サンプル / 試聴待ち」と正直に報告する。hooks/deliver_gate.py(ストップフック)はレシートなしで「完了」と言うのを防ぐ。レシートは該当する作品と対応している必要がある(作品名とバージョン番号でマッチ)。このフックはデフォルトでは登録済みプロジェクトと reel を呼び出したターン内のみ有効。REEL_GATE_SCOPE=globalを設定すると全マシン範囲で有効。 - プロジェクト独自のレンダリングスクリプトで出力した動画も同様に 3~6 のプロセスを踏む。
- MV:
--contract mv.jsonを追加。歌詞チェックは契約に記述された歌詞テキストレイヤー(各歌詞行の歌唱中のみテキストレイヤーに文字があり、歌唱開始前は空)を読み取る。完成動画のピクセルから歌詞を読み取るわけではないので、「画面の歌詞を確認した」と言うことはできない。song_levelはコンピレーションとpolicy: "trim"に対して、各曲ごとにラウドネスとトゥルーピークを比較、許容差はシングル曲と同じ。 - パラメータエラーも JSON で出力(
ARG_INVALID、終了コード 2)。--helpはヘルプテキストを出力。reel voice checkで中国語(デフォルト--lang zh)をチェックする場合は別途pypinyinが必要(同じ venv にインストール)。不足している場合はBACKEND_UNAVAILABLEを報告。reel wordsはwhisper-cliとモデルのみ必要。
brief.json の例(MV の場合は "kind": "mv" を追加):
{"version": "reel.brief.v1", "name": "招生宣传", "language": "zh-CN", "deliverable": "final",
"delivery_root": "~/Deliveries/<プロジェクト>", "must_not_change": ["片尾署名"],
"voice": {"mode": "tts", "voice_id": "zh-CN-XiaoxiaoNeural",
"approved": {"voice_id": "zh-CN-XiaoxiaoNeural", "by": "user", "quote": "この声で大丈夫",
"sample": "voice_sample.mp3", "sample_sha256": "<shasum -a 256 の結果>"}},
"profile": "default"}
- brief の中でテキストスキャン対象となるフィールドは
name、must_not_change、およびキー名がtext/title/caption/labelのもののみ。language、delivery_root、voice.*はスキャン対象外。 - ナレーションなしの場合は
"voice": {"mode": "none"}。生録音の場合は"recorded"。無音版はプロジェクトプロファイルを使用:{"extends": "default", "audio": "silent"}。 - profile:
default(汎用しきい値)、social-vertical(縦型ソーシャルプラットフォーム:1080×1920 30fps、-16 LUFS)。プロジェクト固有の差分はプロジェクトプロファイル(extends)に記述。意図的に長い停留はallowに登録し理由を記述。テキストスキャンの単語リストは profile のtextセクション:bannedおよびextra_banned(大文字小文字区別なしの部分文字列、該当時は fail。プロジェクト固有の禁止語はextra_bannedに追加)、banned_words(大文字小文字を区別する大文字の完全単語TODO/TBD/FIXME、該当時は fail)、review(placeholder、lorem ipsum、完全単語、該当時は needs_review、text_scanのレビュー記録を記述)。
各 Bash 呼び出しブロックの先頭
agent の Bash 呼び出しは毎回新しいシェルで行われ、関数は保持されない。そのため reel は関数ではなく PATH 上のスクリプト(bin/reel)。インタープリタは REEL_PYTHON → ~/.local/share/reel/venv/bin/python → python3 の順で選択。環境に問題がある場合は最初に reel doctor を実行(必須・オプション依存関係と修復方法を一覧表示。必須項目が欠けている場合は exit 1):
command -v reel >/dev/null || export PATH="$HOME/.claude/plugins/reel/bin:$PATH"
P="$HOME/work/<プロジェクト>"; mkdir -p "$P/preview" && cd "$P" # 成果物はプロジェクトディレクトリに配置、/tmp には置かない
標準ワークフロー
- 素材を準備してプロジェクトディレクトリ
$Pに配置(素材、observations.json、plan.json、プレビュー、完成品はすべてここに配置。1 ディレクトリ 1 plan。.reel-history/にリビジョン履歴を記録)。 - 素材を確認、目標を設定:
reel inspect 素材/a.jpg 素材/b.mp4 reel frame 素材/a.jpg --out "$P/preview/a_grid.png" # 0–1 グリッド付きの画像を読み、目標フレームを読み取る reel observe --obs observations.json --src 素材 --asset a.jpg --bbox x0,y0,x1,y1 --label "目標" reel locate --obs observations.json --src 素材 --asset b.mp4 --t 2 --query "赤いカップ" --check-png "$P/preview/chk.png" # OWLv2、torch が必要 - plan.json を記述(EditPlan v1):
camera: []は完全静止。zoom_toは observation を参照して目標にズーム。trackは複数の時点の observation を追跡。transition_outはトランジション。ビデオのカットはinspectで表示されたカットポイントを超えてはいけない。 - 検証 + プレビュー:
reel validate plan.json;reel compile plan.json;reel preview plan.json s2 --out "$P/preview/s2.mp4" --sheet "$P/preview/s2.png"、コンポジット画像でカメラワークを確認。 - 出力:
reel render plan.json --out "$P/完成品.mp4" --sheet "$P/preview/final.png" --where mac。完成品の音声は固定で AAC 48 kHz。checksにサンプルレートのチェックを含む。checksがすべて合格しても、レンダリングが壊れていないことのみを示す。続けて納品ゲート 3~6 を実施。
タイムラインとビート
- 確認:
reel timeline plan.json --format text;reel timeline plan.json --png tl.png [--beats beats.json];reel scrub plan.json --cuts --render 完成品.mp4 --out ディレクトリ。 - 編集:
reel edit plan.json --op '{"op":"trim","id":"s3","duration":2.4}'(各ステップで検証後に書き込み)。reel undo plan.json --to r2;reel history plan.json。 - ビート合わせ:
reel beats 音楽.mp3 --out beats.json→reel snap plan.json --beats beats.json --mode downbeat(--dry-runで事前にレポートを確認)。
Webページ:読み上げに合わせてハイライト表示
素材がWebページの場合、OCRは行わない。文字位置は直接 DOM から読み取り、カメラワークとハイライトはブラウザがフレームごとに描画。
- Webページの原文に従って読み上げ原稿を書く(ハイライトしたい文とページの文は一字一句同じ)。TTS で
voice.mp3を生成。 reel words voice.mp3 --out words.json(ローカルの whisper で単語単位のタイミングを取得)。- plan で
kind: "web"のカット、camera: [{"op": "follow"}]、highlight: [{"text": "ページの原文…", "sync": "voice"}]を使用。audio.wordsにwords.jsonを指定。 TEXT_NOT_FOUND= ページにその原文がない。TEXT_NOT_IN_VOICE= ナレーションが一致しない。
リモート GPU(オプション)
REEL_REMOTE=user@gpu-host(スペース区切りで複数指定可能)を設定すると、reel render --where 5090/--where autoでレンダリングをリモートの NVIDIA ホスト(NVENC + libass)に送信。成果物をローカルに pull して再度検収。未設定の場合はローカルのみを使用。- VRAM はデフォルトで ≤80%。超過時は
NEED_USER_APPROVALを報告。ユーザーに伝え、承諾を得てから--allow-over-80を追加。GPU 使用率 ≥50% の場合はGPU_BUSYを報告し、割り込まない。リモートの flock により、同時に一つの reel GPU タスクのみ実行を保証。 reel remote probeで状態確認。reel remote setup-visionでリモートに独立した venv(torch + OWLv2)を構築。