Communitygithub.com

barefootford/buttercut

内部サブプロシージャ(スタンドアロンのエントリポイントではありません)— 共有フッテージ分析パイプラインであり、音声トランスクリプト、コンタクトシート、Sonnet による要約を生成します。process-library および reprocess-with-contact-sheets スキルによってエンドツーエンドで呼び出されます。単独で実行しないでください。

buttercut とは?

このスキルは、動画分析ワークフローの内部パイプラインとして機能し、主に「process-library」や「reprocess-with-contact-sheets」といった上位スキルから呼び出されることを想定しています。単独のエントリポイントとしては設計されていないため、直接実行することは避けるべきです。 処理の流れは、まず WhisperX を用いた音声トランスクリプトの生成(Step 2a)と、ffmpeg を使ったコンタクトシートの生成(Step 2b)を直列に実行します。これらの機械的な処理は idempotent であり、未完了のクリップのみを処理対象とします。その後、オプションでトランスクリプトのリファインメント(Step 3)を実施し、最後に Sonnet モデルを使用したサブエージェント群がバッチ処理で要約を生成します(Step 4)。 特に注目すべきは、Step 4 での並列処理パターンです。10クリップを1バッチとして最大10のサブエージェントを並列起動し、ローリングディスパッチ方式で効率的に処理を進めます。サブエージェントはコンタクトシートとトランスクリプトから要約マークダウンを生成し、親エージェントが順次 library.yaml を更新します。静止画像は別途処理され、直接画像を読み込んで説明文を生成します。 このスキルは Claude Code、Cursor、Codex などの AI エージェントプラットフォームで動作し、macOS および Windows(Git Bash)に対応しています。処理中はシステムのスリープを防止する機能や、ユーザーとの対話を通じたフッテージ内容の確認(Step 5)、ラフカットの早期リクエストへの対応など、実用的な UX 設計がなされています。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/barefootford/buttercut/tree/HEAD/skills/analyze-video

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

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

ドキュメント

スキル: 動画分析(親ブリーフ)

これはメインスレッドの 動画分析 ワークフローステップ用のプレイブックです。ライブラリセットアップ後、カット作業の前に実行します。各クリップに対して生成される3つのアーティファクト(音声 transcript、contact_sheet、マークダウン summary)をカバーします。ラフカットエージェントは、script_extractor.rb をトランスクリプト JSON に対して実行することで、必要に応じてダイアログを読み取ります。個別のスクリプトアーティファクトはありません。

SKILL.md は親のディスパッチブリーフです。サブエージェントのワーキングプロンプトは agent_prompt.md にあります。Task エージェントを起動する際は、その内容をインライン化してください。SKILL.md を渡さないでください。

用語

  • ユーザー向け: 「フッテージ分析」または「フッテージの分析」と呼びます。
  • 内部/ファイル名: 「transcription」(library.yaml のフィールド transcript など)。

前提条件

  • ライブラリセットアップが完了している (library.yaml が存在し、スキーマが最新である — そうでない場合は AGENTS.md からマイグレーションを実行すること)。
  • libraries/settings.yaml から whisper_model を直接読み取る。ライブラリフィールドについては、ruby lib/buttercut/library.rb <name> summary でスナップショットを読み取り、JSON から必要な値を取得してください。library.yaml をインラインでパースしないでください。

この時点で、ユーザーから見える形で todo リストを作成し、ライブラリ処理の全体的な計画をユーザーが追跡できるように、ハイレベルで非技術的なステップを記載してください。カフェイン化ステップは、ユーザーがオプトインした場合にのみ含めてください。例:

- [ ] コンピュータのスリープを防止
- [ ] トランスクリプトを作成 (0/30)
- [ ] フッテージを分析 (0/30)
- [ ] コンピュータを再びスリープさせる
- [ ] フッテージを一緒に確認

これらの公開 todo は以下のステップに対応しています。「コンピュータのスリープを防止」は Step 1、「コンピュータを再びスリープさせる」は Step 6 です。「トランスクリプトを作成」は Step 2 の機械的な実行と、Step 3 のオプションのリファインメントパスをカバーします(Step 2 の [transcript …] 進捗行からカウントを進めます。リファインメントが有効な場合は、Step 3 が完了するまで進行中とします)。「フッテージを分析」は Step 4 の要約を追跡します(コンタクトシートの後ではなく、クリップが要約されるたびにカウントを進めます)。「フッテージを一緒に確認」は Step 5 です。

公開チャットでは、これらの非技術的なステップを参照してください。技術的な作業(WhisperX、コンタクトシート生成、Sonnet 要約)は表に出さないでください。

Step 1 — 処理中のスリープ防止

分析を開始する前に、ユーザーに(AskUserQuestion 経由で)尋ねます:「処理には時間がかかる場合があります。完了するまでコンピュータを起動したままにしておきましょうか?」オプション:「はい(推奨)」および「いいえ」。

「はい」の場合、プラットフォームのスリープ防止ヘルパーをバックグラウンドで起動し、PID を保存します — 分析が完了した Step 6 でそれを終了します。(バックアップはこのスキルが戻った後、呼び出し元のスキル — process-library — が処理します。)

macOS:

caffeinate -i -w $$ &
KEEPAWAKE_PID=$!

Windows (Git Bash):

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/keep_awake.ps1 &
KEEPAWAKE_PID=$!

どちらもフッテージ処理中にアイドルスリープを防ぎます(ディスプレイはオフになる場合がありますが、問題ありません)。

Step 2 — フッテージの処理(トランスクリプト、次にコンタクトシート)

(process-library 経由ではなく、このスキルに直接到達した場合は、最初にユーザーに伝えます:「[N] 個の動画(合計サイズ [total size])が見つかりました。フッテージ分析を開始します...」)

これは 順番に実行する 2 つの機械的なコマンドです — 最初にトランスクリプト、次にコンタクトシート。決して同時に実行しないでください: WhisperX は RAM を大量に消費するため、両方を重複させるのは避けるべきことです。どちらもサブエージェントで手動実行しないでください。毎回同じように実行され、一度に約2クリップずつ処理し、各クリップが完了した時点で library.yaml に記録します。どちらも冪等性があります — そのアーティファクトがまだないクリップのみを処理するため、再実行では残りのみが完了します。これらはミニチュアの Sidekiq のようなジョブサービスで実行されます。コマンドを実行し、返されるログファイルを監視して進捗を確認します。

Step 2a — トランスクリプト。 Claude Code を使用している場合は、Bash ツールで run_in_background: true を指定して実行します。それ以外の場合は、正しいツール/引数を使用してバックグラウンドで実行します。

ruby lib/buttercut/process_footage.rb transcripts <library-name>

起動直後に、ログファイルに Monitor または同等のものを設定し、完了または失敗したクリップの通知を受け取ります:

tail -f tmp/logs/processing/<library-name>/$(date +%Y-%m-%d).log | grep --line-buffered -E "TranscribeJob  (done|error)|transcript: [0-9]+/[0-9]+|Error|error:|failed|Traceback"
ruby lib/buttercut/library.rb <name> pending transcript   # JSON リスト; done = N − その長さ

クリップが完了するたびに「トランスクリプトを作成 5/20」つまり number_of_clips_complete/total_number_of_clips を更新し、ユーザーが進捗を確認できるようにします。バックグラウンドタスクが完了すると、いずれかのクリップが失敗した場合は非ゼロで終了します。失敗した場合は、一度再実行します。再度失敗した場合は、調査し、エレガントに処理できるように修正を作成するか、問題のあるクリップについてユーザーに通知し、ライブラリから削除する可能性があります。

2a が完了するのを待ってから 2b を開始します。

Step 2b — コンタクトシート。 トランスクリプトが完了したら、シートをビルドします(高速な ffmpeg パス — フォアグラウンドで問題ありません):

ruby lib/buttercut/process_footage.rb contact-sheets <library-name>

コンタクトシートは表に出ません — 公開カウントとして表示しないでください。2a が完了し、リファインメント(Step 3)が完了したら、「トランスクリプトを作成」を完了としてマークします。

チューニング(オプション):両方のステップで libraries/settings.yaml から parallel_jobs を読み取ります(デフォルト 2)。1回の実行で上書きするには --jobs N を使用します。各ステップは、後で確認するために tmp/logs/processing/<library>/ の下にタイムスタンプ付きログを書き込みます。

再処理。 各ステップは、すでにそのアーティファクトを持っているクリップをスキップします。例えば、名前を聞き間違えたトランスクリプトをやり直すには、--force --clips NAME.mov を指定してそのステップを再実行します。--force のみですべてのクリップを再ビルドします。

Step 3 — トランスクリプトのリファインメント(判断 — transcript_refinement: true の場合のみ)

リファインメントは、トランスクリプションの中で判断を要する唯一の部分です — ライブラリコンテキストから聞き間違えた固有名詞を修正する — そのため、モデルステップとして、機械的なパスの 後 に実行されます。ライブラリの transcript_refinement が false の場合は、このステップ全体をスキップします。

true の場合は、Step 2a で書き込まれたトランスクリプトに対して、リファインメントサブエージェント(2〜4並列、ローリング)をディスパッチします。各サブエージェントのプロンプトとして skills/transcribe-audio/refine_instructions.md をインライン化し、以下をインラインで渡します:

  • transcript_path — libraries/<library>/transcripts/ の下にあるクリップのトランスクリプト JSON への絶対パス
  • user_context と footage_summary — ruby lib/buttercut/library.rb <name> summary からの現在の値(空文字でも問題ありません。リファインメントはそれでもナンセンストークン修正と自己 witness 修正をキャッチします)

サブエージェントはトランスクリプト JSON をインプレースで編集し、修正点の短いリストを返します。library.yaml は触りません — Step 2a ですでに transcript フィールドが設定されています。リファインメントが完了したら、公開の「トランスクリプトを作成」todo を完了としてマークします。

Step 4 — 要約(Sonnet サブエージェント、バッチ処理、ローリング)

analyze-video サブエージェントを Sonnet モデル でディスパッチします。Sonnet は Haiku よりも顕著に視覚的に具体的にコンタクトシートを読み取ります(服、建築、カメラフレーミングをキャッチ)— 要約は後続のすべてのカット判断に影響を与えるため、それだけの価値があります。

サブエージェントあたり 10 クリップをバッチ処理し、最大 10 サブエージェントを並列、ローリングディスパッチで実行します。 各サブエージェントは割り当てられた 10 クリップを順次処理します。バッチ処理により、エージェントあたりのディスパッチオーバーヘッド(約5〜10秒)を償却します。93クリップのライブラリの場合、93ではなく合計約10サブエージェントになります。1つが戻り次第、次のサブエージェントを開始します — 10個の波全体が完了するのを待たないでください。そうしないと、最も遅いエージェントに壁時計の約30%を明け渡すことになります。

各サブエージェントに対して、10クリップのレコードリストをインラインで渡します。各クリップレコードには以下が必要です:

  • video_filename — 動画のベース名(要約ヘッダーと応答行で使用)
  • duration — library.yaml からの duration 文字列(例:00:01:19)。エージェントはこれを要約ヘッダーにレンダリングします。
  • contact_sheet_path — _full.jpg への絶対パス(Step 2 から)
  • transcript_path — 音声トランスクリプト JSON への絶対パス(Step 2 から)。サブエージェントは script_extractor.rb を介して必要に応じてダイアログを抽出します。
  • summary_output_path — エージェントが要約マークダウンを書き込むべき絶対パス。このファイル名を手動で構築しないでください。ライブラリに正規パスを尋ねてください:ruby lib/buttercut/library.rb <name> field_path summary <clip>(summaries/summary_<clip>.md 規則を処理し、ファイル拡張子の有無にかかわらず処理します)

各サブエージェントがそのバッチを戻すと、そのバッチ内のすべてのクリップについて library.yaml を summary で更新します:

ruby lib/buttercut/library.rb <name> complete summary <filename> [<filename>...]

contact_sheet フィールドは Step 2 ですでに設定されているため、サブエージェントの戻り値は要約のみを提供します。

サブエージェントが要約をディスクに書き込む代わりにインラインで返す場合(Sonnet が「Write ツールがブロックされました」と幻覚を見て、マークダウンを応答にダンプすることがあります)、盲目的に再試行しないでください — エージェントの応答から各要約を抽出し、親スレッドから対応する summary_output_path に Write するだけです。その後、通常どおり complete summary コマンドを実行します。再ディスパッチよりも高速で、コンテンツはすでにそこにあります。

(長いクリップ用に生成されたセグメントごとのコンタクトシートは、_full シートとともにディスク上に存在し、慣習により検出可能です — library.yaml にはリストされません。)

要約が完了するまで先に進まないでください。クリップが要約されるたびに「Analyze footage」カウントを進め、完了したら完了としてマークします。

静止画像。 静止画像は Step 2〜3 を完全にスキップします(トランスクリプトする音声がなく、ビルドするコンタクトシートもありません)— summary のみが必要なアーティファクトであり、ruby lib/buttercut/library.rb <name> pending summary に動画と一緒に表示されます。画像自体が確認する対象であるため、直接要約します:メインスレッドまたは Sonnet サブエージェントから画像ファイル(小さいです)を読み取り、ruby lib/buttercut/library.rb <name> field_path summary <image-filename> からの正規パスに3〜4文の説明(被写体、設定、構成、画像内のテキスト)を書き込みます。画像クリップキーには拡張子が含まれることに注意してください(title-card.png → summaries/summary_title-card_png.md)。field_path がこれを処理します。その後、同じ方法で記録します:ruby lib/buttercut/library.rb <name> complete summary <image-filename>。

Step 5 — ユーザーとフッテージの理解を確認する

(これは「フッテージを一緒に確認」todo です。)すべての要約が書き込まれたら、フッテージが実際に何を示しているかについて話し合います — キャラクター名、場所、ストーリーの流れ、迷子またはテーマから外れたクリップ、このライブラリに対するユーザーの創造的な意図を確認します。通常の会話を使用します。個別の選択肢を提供する場合にのみ AskUserQuestion に頼ります。学習した内容に応じて、以下を更新します:

  • footage_summary と user_context を ruby lib/buttercut/library.rb <name> update_metadata footage_summary "..." 経由で(そして user_context も同様に)
  • 要約が誰かを誤ってラベル付けしたり、重要な詳細を見逃したりした場合の個別の summary_*.md ファイル(例:「茶色のジャケットを着た男性」→ ユーザーの名前)

これはこの徹底的なパスを実行する唯一の場所です。後続のすべてのラフカット計画実行は、ライブラリを再調査するのではなく、結果のコンテキストを継承します。

Step 6 — スリープ防止ヘルパーを停止する

Step 1 で開始した場合は、今すぐ終了します(両プラットフォーム):

kill $KEEPAWAKE_PID 2>/dev/null

並列サブエージェントパターン(参考)

Step 3 および 4 で使用されます。

親エージェントの責任:

  • library.yaml と settings.yaml を一度読み取り、サブエージェントが必要とするすべての値を収集します。
  • 必要なすべての値を プロンプトにインライン で渡して Task エージェントを起動します。
  • エージェントが完了するたびに、library.yaml を順次更新します(Library API 経由 — AGENTS.md を参照)。
  • エラーと再試行を処理します。

子エージェントの責任:

  • 親からインラインで渡された入力のみを使用して、割り当てられたクリップを処理します。
  • トランスクリプト JSON をインプレースでリファインする(リファインメント)、または事前生成されたコンタクトシートを読み取り、script_extractor.rb を介してトランスクリプトからダイアログを抽出し、1回の Write 呼び出しで要約マークダウンを書き込みます(analyze-video)。(WhisperX はもはやサブエージェントではありません — process_footage.rb transcripts が Step 2a で実行します。)
  • ファイルパスを含む短い構造化された応答を返します。

各スキルの agent_prompt.md は、サブエージェントが library.yaml を読み取るか書き込むかを含む、独自の IO コントラクトを文書化しています。(ネタバレ:library.yaml を書き込むことはありません。Library API を介して書き込むのは親のみです。)

分析完了前にユーザーがラフカットをリクエストした場合

警告します:「今ラフカットを作成することもできますが、すべてのフッテージを分析した後により良い結果が得られます。それでも続けますか?」ユーザーが確認した場合は、続行します。それ以外の場合は、分析が完了するまで待機します。

関連スキル