Communitygithub.com

reel — 動画制作/編集ツール

動画、リール、プロモーション、歌詞ビデオ、MVなどの制作・編集を行うためのエントリポイントです。必ず reel check → reel deliver のプロセスを経て、完了レシートを受け取ることで初めて「完了」とみなされます。

編集ツール とは?

reelは、ffmpegをコアとしたAIエージェント向け動画制作・編集ツールです。エージェントは素材を確認し、目標を設定し、planを記述します。コードがフレーミング、レンダリング、検収を担当し、縦型(1080×1920)をデフォルトとしつつ、プロファイルで任意のアスペクト比に対応します。主にClaude CodeやCursor、CodexなどのAIコーディングエージェントで使用することを想定しており、Bash スクリプトとして動作します。制作開始時には必ずbrief.jsonを登録し、音声の試聴承認を得た上で、plan に従ってレンダリング、reel check による技術チェックと人間によるレビュー、そして reel deliver で納品します。最後に受け取った final ステータスのレシートをもってのみ完了とみなされ、それ以外の状態では「未完了」と報告する必要があります。Webページの読み上げハイライト動画や、リモートGPUレンダリングにも対応しており、複雑な映像制作の各工程をコードで管理・自動化できます。

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

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

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

ドキュメント

reel — agent の動画制作 / 編集ツール

ffmpeg を中核とした階層型ツール:agent が素材を確認し、目標を定め、plan を記述。コードがフレーミング、レンダリング、検収を担当。アスペクト比は設定可能(デフォルトは縦型 1080×1920)。 コマンドとフォーマットの詳細はエンジン README と docs/engine.zh.md にあるので、作業前に必ず読むこと。

納品ゲート(必須)

ルールは実行されなければ意味がありません。以下の各ステップはコードで強制され、従わなければ「完成品」を納品できません。

  1. 作業開始前に 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 を使う。
  2. 音声は先に試聴:固定のデフォルト音声はない。最初に 10~20 秒のサンプルを人間に聴かせ、承認を得たら、その発言、サンプルパス、サンプルの sha256 を brief.voice.approved に記録。音声を変更する場合は再試聴が必要。
  3. 出力後にチェック:reel check 完成品.mp4 --plan plan.json --brief brief.json [--profile default|social-vertical|プロジェクト.json]。exit 1 = 納品不可。result.gate.blockers(技術的不合格)と pending_review(人間の確認が必要)を確認。not_covered はチェックされなかった項目なので「チェック済み」とは言えない。
  4. レビュー:needs_review の各項目を確認(reel scrub / コマ送り)。各項目にタイムコード付きのレビュー記録を記述。全体を通して見たら final_watch、聴いたら final_listen を記録。
  5. 納品:reel deliver 完成品.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json。完成品の条件を満たさない場合は DELIVERY_NOT_FINAL が報告され、--sample のみ許可、ファイル名には「確認用サンプル」と付与。同一バージョン番号で再納品不可。旧バージョンは削除も上書きもしない。
  6. 「完了」と言える条件:status: final のレシートを受け取ること(reel receipt <レシート> で確認可能)。そうでなければ「未完了 / 確認用サンプル / 試聴待ち」と正直に報告する。hooks/deliver_gate.py(ストップフック)はレシートなしで「完了」と言うのを防ぐ。レシートは該当する作品と対応している必要がある(作品名とバージョン番号でマッチ)。このフックはデフォルトでは登録済みプロジェクトと reel を呼び出したターン内のみ有効。REEL_GATE_SCOPE=global を設定すると全マシン範囲で有効。
  7. プロジェクト独自のレンダリングスクリプトで出力した動画も同様に 3~6 のプロセスを踏む。
  8. MV:--contract mv.json を追加。歌詞チェックは契約に記述された歌詞テキストレイヤー(各歌詞行の歌唱中のみテキストレイヤーに文字があり、歌唱開始前は空)を読み取る。完成動画のピクセルから歌詞を読み取るわけではないので、「画面の歌詞を確認した」と言うことはできない。song_level はコンピレーションと policy: "trim" に対して、各曲ごとにラウドネスとトゥルーピークを比較、許容差はシングル曲と同じ。
  9. パラメータエラーも 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 には置かない

標準ワークフロー

  1. 素材を準備してプロジェクトディレクトリ $P に配置(素材、observations.json、plan.json、プレビュー、完成品はすべてここに配置。1 ディレクトリ 1 plan。.reel-history/ にリビジョン履歴を記録)。
  2. 素材を確認、目標を設定:
    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 が必要
    
  3. plan.json を記述(EditPlan v1):camera: [] は完全静止。zoom_to は observation を参照して目標にズーム。track は複数の時点の observation を追跡。transition_out はトランジション。ビデオのカットは inspect で表示されたカットポイントを超えてはいけない。
  4. 検証 + プレビュー:reel validate plan.json;reel compile plan.json;reel preview plan.json s2 --out "$P/preview/s2.mp4" --sheet "$P/preview/s2.png"、コンポジット画像でカメラワークを確認。
  5. 出力: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 から読み取り、カメラワークとハイライトはブラウザがフレームごとに描画。

  1. Webページの原文に従って読み上げ原稿を書く(ハイライトしたい文とページの文は一字一句同じ)。TTS で voice.mp3 を生成。
  2. reel words voice.mp3 --out words.json(ローカルの whisper で単語単位のタイミングを取得)。
  3. plan で kind: "web" のカット、camera: [{"op": "follow"}]、highlight: [{"text": "ページの原文…", "sync": "voice"}] を使用。audio.words に words.json を指定。
  4. 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)を構築。

関連スキル