Communitygithub.com

reel: 動画制作

Claude Code 向けの動画制作プラグイン。素材の選定、構成の計画、編集、レンダリング、納品までをコードで管理します。

reel: 動画制作 とは?

reel は、Claude Code 等のAIエージェントが動画制作を体系的に遂行するためのツールです。エージェントが素材を分析し、構成を決定し、編集計画を立案します。ffmpeg をベースに、フレーミング、レンダリング、チェックを自動化します。対応プラットフォームは Claude Code で、縦1080x1920がデフォルト出力サイズです。特徴は「まず方向性、次に編集」という厳格なワークフローと、必須の納品ゲートです。エージェントは brief.json の登録、ボイスオーディション、レンダリングチェック、最終確認・納品の各ステップをコードで実施。プロジェクト管理やショットカット連携、ビートに合わせたカット編集など高度な機能も備え、AIと人間の協働による高品質な動画制作を実現します。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/shuaige121/reel/tree/HEAD/skills/reel

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

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

ドキュメント

/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つでもスキップすると最終カットを納品できません。

  1. 最初にブリーフを書く ($P/brief.json、テンプレートは下記) に登録: reel register brief.json。納品言語、最終版かサンプルか、納品フォルダ、変更してはいけないものについて、これらを記入できない場合はユーザーに尋ねてください。登録されると、Bash ガードフックが cp/mv/ffmpeg による納品フォルダへの書き込みを拒否します。
  2. 音声をオーディションする。 デフォルトの音声はありません。ブリーフに合ったものを選び、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 音声は内部ドラフト専用で、納品する動画には決して使用しないでください。
  3. レンダリングをチェック: 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がありません)。それらの項目がチェックされたと決して言わないでください。
  4. レビュー。 すべての needs_review 項目 (reel scrub、フレームグラブ) を確認し、各項目に対するタイムコード付きの観察事項を含むレビューレコードを1つ書いてください。カット全体を自分で視聴し final_watch に署名してください (ショットごとに少なくとも1フレーム)。最初から最後まで聴き、final_listen に署名してください (エージェントの署名にはタイムコード付きの観察事項が必要です。ユーザーが聴いた場合は、ユーザーの正確な言葉を quote として記録してください)。両方に署名したら、最終版として納品します。レシートには approved_by: agent と表示され、あなたの返信には「最終版、Claude レビュー済み、まだあなたはご覧になっていません」と記載されます。ユーザーのフィードバックは次のバージョンに反映されます。reviews.json の形式は docs/ENGINE.md にあります。
  5. 納品: 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 を実行し、削除してから再登録します。
  6. 「完了」と言うには status: final のレシートが必要です (reel receipt <receipt.json> で再検証されます)。そうでない場合は実際のステータスを述べてください:「未完了」、「レビュー待ちサンプル」、「音声未オーディション」。Stop フックは、一致するレシートがない完了の主張をブロックします。
  7. プロジェクト独自のレンダースクリプト (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 にあります。

  1. 素材 を $P に配置 (アセット、observations.json、plan.json、プレビュー、レンダリング、チェックレポートはすべてそこに格納されます。フォルダごとに1つの plan)。
  2. スクリプトと音声。 ナレーションスクリプトを作成し、ブリーフに合った音声を選び、オーディションに合格します (ゲートステップ2)。voice.mp3 (または .wav) を生成し、字幕が必要な場合は voice.vtt も生成します。公開作品には実際の録音または使用範囲をカバーするライセンスの音声を推奨します。音楽のみの作品の場合は audio.voice に音楽トラックを指定します (これがタイムラインのアンカーになります)。
  3. 確認とターゲットの選択: reel inspect (各ファイルをリスト) → reel frame (0-1グリッドで画像を読み、被写体のボックスを読み取る) → reel observe で登録、または reel locate --query ... --check-png ... (OWLv2; 検出を使用する前にチェック画像を確認)。
  4. plan.json を書く (EditPlan v1): camera: [] はフレームを静止させます。zoom_to と observation_id で登録された被写体にズームインします。動画内で被写体が動く場合は track を使用します。transition_out はトランジション用です。inspect によって報告されたシーンカットを動画ショットがまたがないようにします。audio.voice は必須で、src_dir に対して解決されます。
  5. 検証とプレビュー: reel validate → reel compile → reel preview plan.json s2 --out preview/s2.mp4 --sheet preview/s2.png、その後コンタクトシートを読んでカメラの動きを判断します。
  6. レンダリング: 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、ブリーフ、レビュー、レシート、プロファイル。

関連スキル