# Analyze Footage

> Analyzes source footage to generate structured analysis artifacts including assets, segments, transcripts, and gap reports for video editing workflows.

- Skill: `mocchalera/analyze-footage` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds add mocchalera/analyze-footage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mocchalera/analyze-footage/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, Data & Analytics, Data Analysis
- Tags: Ffmpeg, Media Analysis, Stt, Transcription, Tsx, Video Analysis, Vlm
- Author: mocchalera (https://skillmd.com/u/mocchalera)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/mocchalera/analyze-footage

---

# 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: 実行する

```bash
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 は別途読むこと