analyze-footage

name	analyze-footage
description	MUST USE when source footage or a material folder is provided and material understanding or 03_analysis generation is needed. Trigger not only on explicit analysis requests ('分析して', '素材を見て') but also when the user points at footage and says things like 'この動画で', 'この素材で', or any request that requires understanding the provided media before planning or editing.
metadata	{"filePattern":["**/03_analysis/assets.json","**/03_analysis/segments.json","**/03_analysis/gap_report.yaml"],"bashPattern":["analyze\\.ts"]}

analyze-footage — 素材解析

いつ使うか（必ず発火する条件）

• ユーザーが素材フォルダや動画ファイルを渡し、「分析して」「素材を見て」「03_analysis を作って」と言ったとき
• ユーザーが素材を指して「この動画で」「この素材で」「この映像から」のように依頼し、クリップ内容の理解が必要なとき
• projects/<project>/03_analysis/ を初回生成するとき、または素材差し替え後に再解析するとき
• design-intent や full-pipeline から、素材理解の前提 artifact として analysis が必要なとき

前提条件

• npx tsx、ffmpeg、ffprobe が使えること
• 出力先 projects/<project> が決まっていること
• STT を使うなら GROQ_API_KEY か OPENAI_API_KEY を用意すること
• VLM を使うなら GEMINI_API_KEY を用意すること
• 相対素材パスは repo root ではなく --project で渡した project directory 基準で解決されること
• downstream で select-clips や peak ベースの判断をしたいなら --skip-peak を使わないこと

やること（ステップ）

Step 1: 素材と project を特定する

• 対象の source file 群と --project を確定する
• 既に 01_intent/creative_brief.yaml があるか確認する
• 再解析なら既存の 03_analysis/assets.json、segments.json、gap_report.yaml を読んで stale / 欠落理由を把握する

Step 2: content-hint を自動抽出する

references/content-hint-guide.md を参照する。

優先順位:

1. 01_intent/creative_brief.yaml に content_hint があればそれをそのまま使う
2. content_hint が無ければ message.primary を主軸にし、must_have、project.title、ユーザーの説明を足して 1-3 文で再構成する
3. brief 自体が無ければ、ユーザーの説明、素材フォルダ名、ファイル名、撮影時期の手掛かりから推定する

抽出ルール:

• 曖昧なラベルではなく、「誰が・何をしている・どんな文脈か」を入れる
• 編集意図だけでなく、映像に実際に映っている対象と文脈を書く
• 短すぎる単語 1-2 個で済ませない
• 確証のない固有名詞や出来事を捏造しない

Step 3: skip / provider オプションを決める

• --skip-stt セリフ不要の B-roll only、一括素材が無音中心、または今回は映像理解だけで十分なときに使う。asset 単位で無音を自動判定するのとは別で、CLI 全体の STT を止めるフラグ。
• --stt-provider groq 日本語素材を優先したいとき、または OpenAI で文字起こし品質が不安定だったときに first choice として使う。実装は whisper-large-v3-turbo を使い、--skip-diarize しなければ pyannote で話者推定を追加する。
• --stt-provider openai gpt-4o-transcribe-diarize の built-in diarization を使いたいときに選ぶ。pyannote 依存を増やしたくないときの選択肢。
• --skip-diarize single-speaker 素材、話者分離が不要、または pyannote が利用できないときに使う。Groq STT 経路でだけ意味があり、OpenAI STT では実質無効。
• --skip-vlm 速度優先の技術 ingest だけ欲しいときに使う。これを付けると summary / tags / interest_points / display_name / peak_analysis の品質が大きく落ちるので、後続で clip triage するなら基本は使わない。
• --skip-peak quick pass で assets.json / segments.json だけ先に作りたいときに使う。peak_analysis.recommended_in_out が後続で必要なら使わない。--skip-vlm 時は peak も走らないので、この flag はその場合ほぼ意味がない。
• --skip-media-link 02_media/source_map.json と symlink 生成が不要な単発解析時のみ使う。
• --language 言語が明確なときは与える。STT の初期推定を減らせる。

Step 4: 実行する

npx tsx scripts/analyze.ts <source-files...> \
  --project projects/<project> \
  --content-hint '子供の自転車練習の成長記録。公園での練習と上達の過程。' \
  --stt-provider groq

Step 5: 実行後に品質チェックする

references/analysis-quality-check.md を参照する。

最低限やること:

• 03_analysis/assets.json、03_analysis/segments.json、03_analysis/gap_report.yaml を読む
• STT 実行時は 03_analysis/transcripts/TR_<asset_id>.json を確認する
• VLM を使ったつもりなら segments.json.items[].summary / tags と assets.json.items[].display_name が埋まっているか見る
• peak を使ったつもりなら segments.json.items[].peak_analysis、peak_moments、recommended_in_out を確認する
• downstream gate に進める前に npx tsx scripts/validate-schemas.ts projects/<project> を走らせ、assets.json と segments.json の schema / runner check を通す

Step 6: 結果を要約して次の skill へ渡す

• gap の有無と severity を要約する
• generic な display_name や弱い peak が多い場合は content-hint 改善再実行を提案する
• 後続が select-clips なら peak_analysis の有無を明示する

出力 artifact

• 03_analysis/assets.json
• 03_analysis/segments.json
• 03_analysis/gap_report.yaml
• 03_analysis/transcripts/TR_<asset_id>.json ただし STT 実行時のみ
• 03_analysis/contact_sheets/*.png
• 03_analysis/posters/*.jpg
• 03_analysis/filmstrips/*.png
• 03_analysis/waveforms/*.png
• 02_media/source_map.json ただし --skip-media-link を使わない場合のみ

注意事項

• peak_analysis は別ファイルではなく segments.json.items[].peak_analysis に書き戻される
• 実装上の visual semantic field 名は visual_tags ではなく tags
• display_name は VLM の summary / tags から生成される。a_person_is、a_child_is、clip のような generic name は hint 不足や VLM 解像度不足の兆候
• GEMINI_API_KEY がない場合、scripts/analyze.ts は warning を出して VLM を自動スキップする。このとき gap_report.yaml が空でも VLM 成功とは限らないので artifact 本体を必ず見る
• gap_report.yaml は canonical artifact だが、blocking 判定は単純な件数ではない。runtime/mcp/gap-projection.ts では ingest / segment の error を主に blocking として扱う
• scripts/validate-schemas.ts は assets.json / segments.json を検証するが、gap_report.yaml 自体は検証対象ではない。gap は別途読むこと