# M5 契約 v0 — 分析パイプライン + 編集判断レポート + 生成スキル

- 日付: 2026-07-13
- 状態: 設計確定（オーナーレビュー済み）。実装契約への昇格は
  M1〜M4 安定後 + 内部 research の反映後
- 先行例の参照方針: 外部先行実装は**パターン・構造の学習のみ。コード/文章の
  転写禁止**（分析は非公開の内部 research で管理）。数値ノウハウは出典（TikTok Creator Portal 等の一次資料）まで遡って自前で組む

## 全体像

```
素材群（録画 or 生成指示）
   │  素材ごとに subagent 並列分析（オーケストレーション）
   ▼
analysis.json（素材ごと・機械可読の中間契約）
   │  統合
   ▼
編集判断レポート（HTML・人間が読む顔。フレームアナリティクスラボ後継）
   │  人間の承認（チェックポイント型）
   ▼
edit.json + オーバーレイ HTML + サムネ確定（実行形 = エンジンが食う）
```

- レポートは**編集フローだけでなく生成フローにも使う**: 素材が録画なら「分析 → カット判断」、
  ゼロから作るなら「リサーチ → 台本 → 生成計画」。エンジン（edit.json + オーバーレイ）は
  クリップの出自（撮影/生成）を区別しないので、下流は共通
- 実装形態は**スキル**（`.claude/skills/`）。アプリのコードにしない
  （本体は合成だけ。判断は全部スキル側 = agent-native）

## analysis.json（素材ごとの中間契約）v0 素案

```jsonc
{
  "version": 0,
  "source": "raw/2026-07-13-recording.mp4",
  "transcript": [ { "start": 1.2, "end": 3.4, "text": "…", "speaker": "A", "words": [...] } ],
  "keyframes": [ { "t": 12.0, "path": "analysis/kf-0012.jpg", "note": "画面共有开始、資料タイトル表示" } ],
  "events": [
    { "type": "filler", "start": 5.0, "end": 5.8 },
    { "type": "trouble", "start": 40.0, "end": 55.0, "note": "音声途切れ" },
    { "type": "chapter", "t": 60.0, "title": "セットアップ手順" },
    { "type": "hook", "start": 12.0, "end": 24.0, "score": { "hook": 4, "self_contained": 5, "emotion": 3, "density": 4, "punch": 3 } }
  ],
  "tracks": {
    "speakers": [ { "id": "A", "spans": [[0, 65]] } ],
    "faces": [ { "speaker": "A", "t": 12.0, "box": [0.1, 0.2, 0.3, 0.5] } ],   // リフレーミング用
    "person_matte": null    // 人物切り抜き（text-behind-person 用）を生成済みならパス
  }
}
```

- フック候補の 5 軸スコアは claude-shorts の公開手法を参考（hook 強度/自己完結性/感情強度/
  価値密度/オチ）。閾値は運用で調整
- `tracks.faces` / `person_matte` は**リフレーミングと text-behind-person の共通基盤**。
  人物セグメンテーションの手: Apple Vision Person Segmentation（ローカル・高速）または
  Robust Video Matting。出力はアルファ付き HEVC（WKWebView が HW デコード可）
- 分析タイミング: 取り込み時にプロキシ生成と同時に裏で走らせるのを基本とする
  （粒度の適応・旧参照実装の分析研究の回収は実装時の TODO）

## 編集判断レポート規約

**形式**: HTML 1 枚（フレームアナリティクスラボの後継）。章立てを固定する:

1. **サムネイル案**（複数、タイトル文字バリエーション付き）— 先頭に置く（CTR 直結・
   人間が一番言いたい場所）
2. **分析サマリ** — 素材ごとの要点、根拠フレーム・transcript へのリンク
3. **編集方針** — 「こういう方向性でやります」+ 理由
4. **カット判断一覧** — keep/drop と根拠（event 参照）
5. **素材計画** — 全体で使うもの（BGM）とシーン単位（SFX / B ロール / テロップスタイル /
   特殊表現）を分け、各枠に**三択判断**を明記:
   - **あれば提案**: ライブラリ検索ヒット（プレビュー画像付き）
   - **なければ生成**: 生成案（プロンプト + 生成済み画像）
   - **だめなら使わない**: 無理に埋めない（明示的な非採用を許す）
6. **decision_log** — 追記専用の決定記録（(category, subject) キー、後から書き換えない）

**画像の扱い（確定ルール）**: **画像はレポートに込み、動画は承認後**。
- 静止画（サムネ案・B ロール案・タイトルカード案）は生成してレポートに貼った状態で出す
- i2v 動画生成・アバター等の高コスト生成は、対応する画像の承認後に実行
- サムネは 2 経路 + 混成: 経路 A = 実フレーム + HTML 文字組（日本語タイポ精度・
  Step 1 の「HTML シート → スクショ」技術）/ 経路 B = Codex 画像生成 /
  混成 = B で背景生成 → A で文字組

**承認 UX**: チェックポイント型（方針 → 素材計画 → 実行、の段階承認。既定は明示承認）

**Decision Communication Contract**（先行例のパターンを自前実装）:
- 有償/重い生成の前に「どの手・なぜ」を宣言してから実行
- 選択肢が複数あるとき黙って既定を選ばない（両論併記）
- 決定は decision_log に追記（監査可能）

## 生成スキル契約

**手の優先順（確定）**:
1. **Codex の画像生成** — Codex がプロジェクトディレクトリへ直接ファイルを書き出す。
   認証は ChatGPT ログインに乗る（API キー管理問題が消える）
2. **Akari Cloud API / MCP** — アプリ経由ではなくエージェント層から
- **API キー直叩き（OpenAI / Gemini 等）はスコープ外**（漏洩リスクを個人に負わせない）
- アプリ本体は生成サービスと一切通信しない（「本体は合成だけ、生成は手」）
- すべての生成物に provenance（手・プロンプト・日時）を記録
- 画像 → i2v の二段フロー（画像承認で構図・スタイルが固定されてから動かす）

## スキル群の構成（ルーター + リーフ）

```
akari-video-skills/
  SKILL.md                 ← ルーター（薄い。FORBIDDEN 級ハードルールのみ）
  analyze-footage.md       ← 素材 1 本の分析 → analysis.json
  edit-plan-report.md      ← 統合 → レポート → 承認 → edit.json
  authoring/               ← オーバーレイ authoring 規約（CLAUDE.md の規約を skill 化）
    telop.md / table.md / 3d.md / motion.md
    thumbnail.md           ← 状況→型の対応表 + デザイン語彙 + 経路 A/B/混成の選択ルール
    text-behind-person.md  ← 人物切り抜き + z 順（切り抜きは analysis の person_matte を使う）
  harvest.md               ← 素材化（良い成果物 → ライブラリ収穫）
```

- 書式は調査で確認した勝ちパターン: **原則 + 数値閾値 + 「よくある間違い」節**、
  1 スキル = 1 判断領域、実知識はリーフに置き progressive disclosure
- サブエージェントは必要なリーフだけ読み込んで並列制作
- 外部公開する場合は単一エントリポイント（ルーター）の発見性に投資
  （skills.sh 実測: ルーター 424.9K vs リーフ 2K の一極集中）

## スコープ外（この契約では扱わない）

- スタイル学習（蓄積された edit.json + レポート + 素材が学習素材になる。基盤が先）
- ストック素材 API 統合（Pexels 等から段階的に。Storyblocks 系 EULA の
  「AI/ML 利用禁止」条項に注意。音源は Epidemic Sound が**公式 MCP** を提供しており
  BGM/SFX 枠の「ライセンス済み音源検索の手」の第一候補）
- コミュニティ配布・販売（素材ライブラリ契約 v0 参照）

## 追記（2026-07-14）— highlight event と transcript 駆動キーフレーム

長尺実素材（60 分級）での運用で判明した要求を受けた追加。analysis.json v0 の**後方互換を
保つ追加語彙**とする（既存 4 種 event・keyframe 必須フィールドは不変。version は 0 据え置き）。

### highlight event（重要発言の汎用枠）

hook はショート切り出し向けの「見せ場」に特化した物差しであり、決定事項・結論・数字・
強い主張のような**地味だが編集判断に効く発言**の置き場がなかった。これを `highlight` として
追加する。

```jsonc
{ "type": "highlight", "start": 312.0, "end": 318.5,
  "quote": "実発言に忠実な引用", "reason": "リリース日を明言（決定事項）", "importance": 4 }
```

- `quote` は transcript の実発言に忠実（要約・創作禁止）。`reason` はなぜ重要か。
  `importance` は 1〜5 の任意スコア
- 下流の用途: カット判断の keep 根拠 / テロップ引用 / チャプター見出し / サムネ文言 /
  ショート候補の種
- transcript が空の素材では作らない（`quote` 必須のため）

### transcript 駆動キーフレーム（第 3 の抽出系統）

キーフレーム抽出は従来 scene（映像変化）+ interval（一定間隔の保険）の映像側 2 系統のみで、
「重要発言の瞬間の画」を狙って拾えなかった。highlight の時刻からフレームを抽出する
第 3 系統を追加する。

- 効能: 発話と画の対応が取れる / interval を密にして取りこぼしを防ぐ必要が減り、
  長尺素材での候補数爆発（実測: 62 分 × 10 秒間隔 = 374 候補）を緩和する
- `keyframes[].origin`（`scene` / `interval` / `transcript`、任意）を追加し、
  どの系統から採用したかのトレーサビリティを持たせる