akari-video 0.1.0

package/vendor/skills/analyze-footage/events-and-hooks.md

@@ -0,0 +1,93 @@
+# イベント判定とフック採点
+
+## 原則
+
+event は「検出できそうな箇所」ではなく、後工程がカット・章立て・冒頭構成を判断するための証拠である。時刻は source 秒、区間 event は `end > start` とする。不確かな候補は無理に追加せず、空配列を許容する。
+
+## 5 種 event の判定
+
+| type | 記録する条件 | 境界の決め方 | 記録しない例 |
+|---|---|---|---|
+| `filler` | 言いよどみ、意味を足さない反復、言い直しなど、除去しても発話意図を保てる区間 | transcript の実発話境界と音声を根拠に `start` / `end` | 意味のある間、強調の反復、文字起こし誤りだけを根拠にした推測 |
+| `trouble` | 音声途切れ、映像停止、操作失敗、収録ミス、明示された撮り直しなど | 問題が始まり正常へ戻る source 区間 | 無音や transcript gap だけで断定した障害、単なる話題の難しさ |
+| `chapter` | 話題、目的、手順、画面状態が新しいまとまりへ切り替わる地点 | 切り替わりを最もよく表す source 時刻 `t` | 一文ごとの細分化、見た目だけの瞬間的なカット |
+| `highlight` | 決定事項、結論、数値・実績、強い主張、引用性の高い一言など、編集判断の根拠になる重要発言 | 該当発言を含む transcript segment の実発話境界に合わせた `start` / `end` | 話題の要約でしかない区間、発言の裏付けがない画面上の変化、単に長い説明 |
+| `hook` | 単独で提示でき、視聴継続の理由になる短い区間 | 理解に必要な最小の開始から、価値またはオチが成立する終了まで | 文脈依存が強い断片、誇張しないと成立しない場面 |
+
+`trouble.note` は「何が起きたか」と根拠を具体的に書く。`chapter.title` は transcript の内容に沿った短い名詞句または行動句にし、存在しない発言を引用しない。`filler` と `hook` に Schema 外の `note` を足さない。
+
+backend が whisper.cpp 由来の transcript は正規化でフィラーが脱落するため、filler 検出の再現率が低い。SpeechAnalyzer / Scribe 由来の transcript がある場合はそちらを優先して filler を判定し、whisper.cpp のみの場合は再現率の限界を完了報告に明記する。
+
+## highlight（重要発言）の判定
+
+契約根拠: [M5 契約の追記（2026-07-14）](../../docs/contract-2026-07-13-m5-analysis-report.md)。hook がショート切り出し向けの「見せ場」であるのに対し、highlight は**編集判断全般の根拠になる重要発言**の汎用枠である。同一区間が両方に該当する場合は両方登録してよい（目的が異なる）。
+
+- `quote` は transcript の**実発言に忠実**に書く。要約・言い換え・創作をしない。整形は句読点の補いまでとする
+- `reason` は「なぜ重要か」を根拠カテゴリ付きで書く（例: 「リリース日を明言（決定事項）」「導入効果を数値で提示（数値・実績）」）
+- `importance`（任意、1〜5 整数）: 3 = 編集で残す根拠になる / 4 = テロップ・チャプター見出し候補になる / 5 = サムネ文言・ショートの核になり得る。1〜2 は登録しない方がよい（インフレ防止）
+- 件数の目安: 60 分級の素材で 5〜15 件（**要検証の運用初期値**）。全発言の書き写しにしない
+- transcript が空の素材では作らない（`quote` 必須のため）。視覚のみの重要場面は `chapter` / `hook` で扱う
+- 確定した highlight の時刻は transcript 駆動キーフレーム抽出の入力になる（[keyframes-and-review.md](keyframes-and-review.md) 参照）
+
+## hook の 5 軸評価表
+
+1〜5 は `analysis.json` v0 が要求する整数尺度である。以下のアンカーは運用初期ルーブリックであり、プラットフォーム公式指標ではないため **要検証**。2 と 4 も含め、最も近い記述を 1 つ選ぶ。
+
+| 軸 | 1 | 2 | 3 | 4 | 5 |
+|---|---|---|---|---|---|
+| `hook` フック強度 | 導入だけで関心の入口がない | 軽い関心はあるが続きを促す問いが弱い | 問題、問い、意外性のいずれかが明確 | 結果、対立、強い便益を早く提示する | 一瞬で理解できる驚きや高い賭け金があり、続きが不可欠 |
+| `self_contained` 自己完結性 | 前後文脈なしでは意味不明 | 指示語や前提が多く補足が必要 | 短い前置きがあれば要点を理解できる | ほぼ単独で状況と価値が伝わる | 単独で状況・主張・到達点が明瞭 |
+| `emotion` 感情強度 | 感情変化が確認できない | 小さな反応だけがある | 喜び、驚き、焦り等が明確 | 強い自然な反応が区間を牽引する | 素材中の感情ピークで、映像・声・内容が一致する |
+| `density` 価値密度 | 待ちや重複が大半 | 有用部分より前置きが長い | 全体を通して一定の情報または変化がある | ほぼ各瞬間が理解や期待を進める | 無駄がなく高密度だが、理解可能性も保つ |
+| `punch` オチ・決め | 到達点がない | 弱い結論だけがある | 明確な結論、結果、学びがある | 記憶に残る結果または言い切りがある | 鮮明な反転、実証、決め台詞で再視聴価値がある |
+
+声量だけで emotion を上げず、情報量だけで density を上げない。各軸を独立して採点する。
+
+## 候補登録の初期閾値
+
+v0 契約は採用閾値を運用調整対象としている。このスキルでは初期選別として次を同時に満たす区間を hook 候補へ登録する。
+
+- `hook >= 3`
+- `self_contained >= 3`
+- 5 軸合計 `>= 16 / 25`
+
+この数値はプラットフォーム公式値ではなく **要検証の運用初期値** である。素材ジャンルや配信先に合わせて変更した場合は、元の値、変更後の値、理由を報告する。閾値未満でも人間へ提示すべき強い根拠がある場合は、黙って基準を曲げず、例外採用したことを報告する。
+
+候補同士は合計点で比較し、同点なら `hook`、`self_contained`、`density` の順で比較する。この順位規則も要検証の運用ルールであり、絶対的な品質評価ではない。
+
+尺度の契約根拠: [M5 analysis.json v0 契約](../../docs/contract-2026-07-13-m5-analysis-report.md)
+
+## 見せ場抽出の供給責務
+
+ここで作る event（`hook` / `chapter` / `highlight`）と hook の 5 軸スコアは、後工程
+（[edit-plan の beats.md](../edit-plan/beats.md)）が `edit.json` の見せ場マーカー `beats[]`
+（[データ契約](../../docs/contract-2026-07-22-edit-json-v1-beats.md)）を導出するときの**供給源**である。
+抽出手順そのものは上の節から変えないが、供給側の品質条件として次の 2 点を満たす。
+
+- **score の無い highlight を出さない**。`importance` を省いた highlight は後工程で強度を
+  決められず、既定値へ丸められる。編集判断の根拠として登録する以上、1〜5 のどれに当たるかを
+  判断して書く（判断できないほど弱い候補は、そもそも登録しない）。
+- **event の `t` は必ず source 秒**。区間 event の `start` / `end` も同じく未カット素材の
+  source 秒である。beats は source 秒アンカーで永続化されるため、ここに timeline 秒が
+  混ざると後工程では検出できない誤りになる。
+
+## event 整合性
+
+- event を source 時刻順に並べる。同時刻では `trouble`、`filler`、`chapter`、`highlight`、`hook` の順に固定してよい。
+- filler と trouble の同一区間を重複登録しない。主因に合う一方を選ぶ。
+- highlight と hook の重複は許す（目的が異なる）。highlight と filler の重複は矛盾なので登録前に見直す。
+- hook が trouble と重なる場合は、トラブル自体が価値ある内容でない限り候補から外す。
+- chapter は素材冒頭にも置けるが、機械的に必須にはしない。
+- transcript が空の場合、発話に依存する filler と highlight は作らない。視覚的に確認できる trouble、chapter、hook だけを根拠付きで判定する。
+
+## よくある間違い
+
+- 口癖を一律に filler とし、話者らしさや意味まで削る。
+- ASR の空白を音声トラブルと断定する。
+- chapter を一定時間ごとに機械生成する。
+- hook の総合印象を 5 軸すべてへ同じ点で写す。
+- 低い自己完結性を強い感情だけで相殺する。
+- 採用閾値をプラットフォーム公式の成功基準として説明する。
+- highlight の `quote` に要約や言い換えを書く（実発言に忠実でなければ引用ではない）。
+- 話題ごとに機械的に highlight を置き、importance 1〜2 の羅列でインフレさせる。
+- hook 相当の派手さがないという理由で、決定事項・数値発言を highlight に登録しない。

package/vendor/skills/analyze-footage/keyframes-and-review.md

@@ -0,0 +1,130 @@
+# キーフレーム抽出と視認
+
+## 原則
+
+抽出は 3 系統を併用する。scene 検出は映像の変化点を拾い、interval 抽出は変化の少ない長尺区間の見落としを防ぎ、transcript 駆動抽出は重要発言の瞬間に画を対応付ける。いずれか一方で代用しない。抽出結果は候補であり、Read で視認した画像だけを最終 `keyframes` に入れる。採用した keyframe には抽出系統を `origin`（`scene` / `interval` / `transcript`）として記録する。
+
+## 1. シーン変化候補を抽出する
+
+```bash
+mkdir -p "$OUT_DIR/work/scene"
+ffmpeg -hide_banner -nostdin -i "$OUT_DIR/proxy.mp4" \
+  -vf "select='gt(scene\,0.4)',showinfo" -fps_mode vfr \
+  "$OUT_DIR/work/scene/scene-%06d.jpg" \
+  2>"$OUT_DIR/work/scene.log"
+```
+
+FFmpeg 公式は scene score の比較例として `0.3`〜`0.5` を妥当な選択肢とし、`0.4` の例を示している。このスキルは `0.4` を初期値にするが、素材ごとの編集適合性は要検証である。候補が過多・過少なら範囲内で調整し、値と理由を報告する。
+
+### 0 候補時の終了コード判定
+
+閾値 0.4 に達する変化点が 1 つもない素材（無音・静止に近い映像など）では、`select` フィルタが 0 フレームを選択し、後段の mjpeg 画像エンコーダが 0 フレームで初期化できずに ffmpeg が **非ゼロ終了（実測: exit code 234）** し、`work/scene/` に画像が 1 枚も生成されない。これは「0 候補」の正常系であり、コマンド自体は破綻していない。
+
+ただし exit code 234 は、フィルタ式の構文ミスなど **コマンドが実際に破綻している場合にも同じ値になる**ため、終了コードの数値だけでは区別できない。`work/scene.log` の中身で判定する。
+
+1. ログに `Stream mapping:` の行があるかを確認する。**ない場合**は入力デコードまたはフィルタグラフの構築自体が失敗しているため「コマンド破綻」として扱い、直前の `Error opening input`・`Error while parsing expression`・`Error initializing filters` 等の行を根拠に原因を報告し、候補統合へは進まず先にコマンドを直す。
+2. `Stream mapping:` が**ある**場合、続けて `No filtered frames for output stream, trying to initialize anyway.` の行を探す。この行がある場合に限り「0 候補」と確定してよい。同時に `Error while opening encoder - maybe incorrect parameters such as bit_rate, rate, width or height.`（mjpeg エンコーダ宛て）と `Nothing was written into output file, because at least one of its streams received no packets.` も現れるのが通常の随伴症状であり、追加の異常ではない。
+3. `Stream mapping:` はあるが `No filtered frames for output stream` が**ない**場合は、原因不明のコマンド破綻として扱い、ログ全文を報告して停止する。
+
+```bash
+if ! grep -q '^Stream mapping:' "$OUT_DIR/work/scene.log"; then
+  echo "破綻: 入力デコード/フィルタグラフ構築が失敗" >&2
+elif grep -q 'No filtered frames for output stream' "$OUT_DIR/work/scene.log"; then
+  echo "0 候補: scene 検出は成立、閾値 0.4 に達する変化点なし"
+else
+  echo "破綻: 原因不明、ログ全文を報告" >&2
+fi
+```
+
+「0 候補」と確定した場合は scene 候補を空のまま、interval 候補だけで次節の統合へ進む。「破綻」と判定した場合は候補統合に進まず、入力パスやフィルタ式などコマンド側を先に修正する。
+
+実測記録（FFmpeg 8.1.1、2026-07-14）: 無音・単色で変化のない静止動画に `select='gt(scene\,0.4)'` を適用すると exit code 234 で `work/scene/` が空になり、上記 1〜3 のログ内容が再現する。対照実験として `select` 式の構文を意図的に壊した場合も exit code は同じ 234 だが、`Stream mapping:` より前でエラーが発生し `No filtered frames for output stream` は現れない。存在しない入力ファイルを指定した場合は exit code 254 で `Stream mapping:` にすら到達しない。exit code の数値だけを見て「破綻」と誤判定しないこと、逆に非ゼロ終了を無条件で「候補なし」と決めつけないことの両方に注意する。
+
+## 2. 一定間隔候補を抽出する
+
+```bash
+mkdir -p "$OUT_DIR/work/interval"
+ffmpeg -hide_banner -nostdin -i "$OUT_DIR/proxy.mp4" \
+  -vf "select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)',showinfo" -fps_mode vfr \
+  "$OUT_DIR/work/interval/interval-%06d.jpg" \
+  2>"$OUT_DIR/work/interval.log"
+```
+
+10 秒は FFmpeg 公式ドキュメントにある一定間隔選択の構文例を採用した運用初期値であり、編集上の最適値ではないため要検証とする。画面変化や発話密度に対して粗すぎる場合は間隔を短くし、候補が冗長なら長くして、変更を報告する。
+
+素材長に応じた間隔の目安（**要検証の運用初期値**。視認可能な候補総数を 30〜60 枚程度に収める意図）:
+
+| 素材長 | interval 目安 |
+|---|---|
+| 〜10 分 | 10 秒 |
+| 10〜30 分 | 30〜60 秒 |
+| 30 分〜 | 120 秒 |
+
+実測記録（2026-07-14）: 62 分素材に 10 秒間隔を適用すると 374 候補になり視認が非現実的だったため、120 秒（32 候補）へ調整した。transcript 駆動抽出（次節）が重要発言を直接拾うため、interval は「映像側の取りこぼし保険」として粗めでよい。
+
+一次資料: [FFmpeg Filters Documentation — select examples](https://ffmpeg.org/ffmpeg-filters.html#select_002c-aselect)
+
+## 3. transcript 駆動候補を抽出する
+
+[events-and-hooks.md](events-and-hooks.md) の手順で transcript から下書きした `highlight` 候補（および hook 候補）の時刻から、フレームを 1 枚ずつ抽出する。transcript が空の素材ではこの系統をスキップし、完了報告に明記する。
+
+```bash
+mkdir -p "$OUT_DIR/work/transcript"
+# highlight 候補ごとに、代表時刻 T（初期値: (start + end) / 2）で 1 枚
+ffmpeg -hide_banner -nostdin -ss "$T" -i "$OUT_DIR/proxy.mp4" \
+  -frames:v 1 "$OUT_DIR/work/transcript/tr-000001-t$T.jpg"
+```
+
+- 代表時刻の初期値は発言区間の中央とする。視認して発言内容と画が対応しない場合（画面切り替えの狭間、話者が映っていない等）は、同じ区間内で `start` / `end` 側へずらして再抽出してよい。区間外から取らない
+- 抽出元の highlight / hook 候補との対応（どの event のための画か）を `work/` 内の対応表に控える。視認後の note 記入と `origin: "transcript"` の記録に使う
+
+## 4. source 時刻を回収して統合する
+
+各ログの `showinfo` 行にある `pts_time` を、同じ実行で出力された画像の連番順に対応付ける。連番そのものを秒にしない。scale だけのプロキシは source 時刻を維持するが、原本とプロキシの duration・開始時刻も照合する。transcript 駆動候補は `-ss` に与えた時刻をそのまま使う。
+
+scene、interval、transcript の 3 系統の候補を source 時刻順に統合する。統合時に「最終連番 → 元候補ファイル名（系統込み）」の対応表を `work/mapping.txt` 等に書き残す（note との対応ずれを後から追跡できるようにする）。同一時刻または視覚的に同一の隣接画像は、Read で比較して情報量の高い方だけを残す。ただし transcript 駆動候補は重要発言の証拠なので、見た目が近くても安易に落とさず、落とす場合は対応する event との紐付けを残した方を優先する。最終画像は次のように安定した名前で `keyframes/` へ置く。
+
+```text
+keyframes/kf-0001-t12.000.jpg
+```
+
+ファイル名の時刻は検索補助であり、`keyframes[].t` の数値を正とする。小数 3 桁は命名上の初期精度であり、フレーム精度を保証する閾値ではない。採用した各 keyframe には、どの系統から来たかを `origin`（`scene` / `interval` / `transcript`）として記録する。
+
+## 5. Read で視認する
+
+最終採用前に各候補画像を Read で開く。長尺素材ではバッチに分けてよいが、未視認画像へ `note` を書かない。**note は必ず重複除外が確定した後の最終ファイル一覧に対して書く**（除外前の候補順で先読みして書くと、除外された枠の分だけ後続の note が前倒しでずれる連鎖事故が起きる。実測: 62 分素材で 5 件連鎖 + 入れ替わり 2 件）。**note は画像を Read した直後にその場で書き、`work/mapping.txt` の対応（連番・時刻・系統）と照合してから次の画像へ進む**。各 note は、画像だけから確認できる次の情報を日本語で簡潔に記す。
+
+- 人物・画面・資料などの主対象
+- UI、スライド、タイトル、エラー表示などの状態
+- 直前候補から生じた見た目上の変化
+- 後工程の根拠になる構図、顔の有無、文字の可読性
+
+「重要そう」「盛り上がっている」だけで終えず、そう判断できる可視事実を書く。音声内容や人物の意図をフレームだけから推測しない。
+
+取り違えリスクが高い箇所には追加の確認を掛ける。
+
+- **準重複クラスタ**（同一シーンで時刻差が数秒未満の候補が並ぶ区間、直前直後で候補除外が起きた区間）は隣接フレームとの note 取り違えが起きやすい。書いた直後にその区間だけ note と画像を再突合する。
+- ボタンラベル・件数などの**小さい UI 文字列**を note に引用する場合は、該当領域を拡大して読み取ってから書く（誤読・数値取り違えの実例あり）。
+- 全 note 記入後、`note[i]` と `path[i]` の画像を機械的な順走査でもう一周突合する self-review を行ってから確定する。
+
+Read が画像を開けない場合は note を捏造しない。`keyframes: []` に劣化するか、別の読み取り可能な画像形式へローカル変換して再試行し、未実施の視認工程を報告する。視認なしで分析完了とはしない。
+
+## 6. 人物情報へ反映する
+
+顔トラックを作る場合は、視認またはローカル検出で確認した時刻だけを記録する。box は `[x, y, width, height]` をフレーム幅・高さで正規化した値とし、各値を 0〜1、かつ `x + width <= 1`、`y + height <= 1` にする。話者と顔の対応を確認できなければ `tracks.faces: []` とし、見た目だけで speaker を断定しない。
+
+人物マットはこの工程で自動生成しない。既に生成済みで、対象 source と時刻対応を確認できる場合だけ `tracks.person_matte` に値を書き、それ以外は `null` とする。人物演出を使うと決めた素材で新たに生成する場合だけ、[person-matte.md](person-matte.md) の任意工程を実行する。
+
+## よくある間違い
+
+- scene 候補だけで、静止画面が続く重要区間を見落とす。
+- interval 候補だけで、短いエラー画面や切り替わりを見落とす。
+- transcript 駆動候補を作らず、重要発言の瞬間の画を interval の偶然に頼る。
+- `scene-000012.jpg` を 12 秒地点だと解釈する。
+- Read せずにファイル名や transcript から画像 note を作る。
+- 複数画像の note をまとめて後から書き、隣接候補と note を入れ替える。
+- transcript 駆動候補の代表時刻が画面切り替えの狭間に落ちたまま、区間内での再抽出をしない。
+- 同じ絵を大量に keyframes へ残し、レポートの根拠を薄める。
+- 顔 box の右端・下端が正規化座標 1 を越える。
+- scene 検出の exit code 234 を見ただけで「候補ゼロ」と即断し、ログ本文（`Stream mapping:` / `No filtered frames for output stream`）を確認しない。
+- 逆に非ゼロ終了を一律「コマンド破綻」として原因調査せず止める。

package/vendor/skills/analyze-footage/media-and-transcript.md

@@ -0,0 +1,219 @@
+# プロキシ生成と文字起こし
+
+## 目次
+
+- [720p プロキシ](#720p-プロキシ)
+- [文字起こしバックエンドを選ぶ（3 層）](#文字起こしバックエンドを選ぶ3-層)
+- [provenance（backend の記録）](#provenancebackend-の記録)
+- [文字起こし不能時の劣化](#文字起こし不能時の劣化)
+
+## 原則
+
+映像の時刻対応を変えずに軽量化し、発話は取得できた証拠だけを保存する。既定はローカルとし、登録済みクラウドは決定カードで人間が明示承認した場合だけ使う。ツール不足を推測で埋めない。
+
+## 720p プロキシ
+
+原本の縦横比を保ち、1280×720 の枠内へ収める。次の scale 構文は FFmpeg 公式ドキュメントの例に基づく。
+
+```bash
+ffmpeg -hide_banner -nostdin -y -i "$SOURCE" \
+  -map 0:v:0 -map '0:a?' \
+  -vf "scale=1280:720:force_original_aspect_ratio=decrease:force_divisible_by=2:reset_sar=1" \
+  -c:v libx264 -pix_fmt yuv420p -c:a aac -movflags +faststart \
+  "$OUT_DIR/proxy.mp4"
+```
+
+720p は AKARI Video のプロキシ契約値である。生成後に `ffprobe` で width、height、duration、映像・音声ストリームを確認し、幅 1280 以下かつ高さ 720 以下、duration が原本と対応していることを確かめる。縦動画を引き伸ばしたり、プロキシ生成時に trim したりしない。
+
+一次資料: [FFmpeg Filters Documentation — scale](https://ffmpeg.org/ffmpeg-filters.html#scale)
+
+## 文字起こしバックエンドを選ぶ（3 層）
+
+既定は層 1、利用できなければ層 2 へ進む。層 3 は層 1/2 の結果とは独立したオプトイン候補であり、接続条件を満たしても人間の明示承認なしには使わない。
+
+### 層 1: macOS SpeechAnalyzer（Mac 既定）
+
+- 使用条件は `sw_vers -productVersion` のメジャーが 26 以上で、`swiftc` を呼び出せること。`node bin/transcribe-sa.mjs --check` で判定し、`available:false` ならその `reason` を報告して層 2 へ進む。
+- ヘルパーは [bin/speechanalyzer-helper.swift](bin/speechanalyzer-helper.swift) に置く。非公開の内部記録で 3 方式比較の実測検証を済ませたソースを取り込んだものである。初回使用時に `swiftc -O` で自動ビルドし、バイナリはコミットしない（[.gitignore](.gitignore) 参照）。ネットワークから新しいツールを導入せず、既存の Command Line Tools だけを使う。
+- `node bin/transcribe-sa.mjs --input <mono 16kHz wav などデコード可能な音声>` で実行する。層 2 の「音声を入力形式へ変換する」で作る `whisper-input.wav` を共用してよい。
+- ヘルパーが `kAFAssistantErrorDomain Code=1101` などで失敗したら自動リトライせず、層 2 へフォールバックして理由を完了報告に書く。
+
+### 層 2: whisper.cpp（共通フォールバック）
+
+#### whisper.cpp の実行ファイルを探す
+
+ネットワークから自動導入せず、次の順で読み取り・実行可能なものを探す。
+
+1. `WHISPER_CPP_BIN` で明示されたパス
+2. `PATH` 上の `whisper-cli`（Homebrew の `whisper-cpp` フォーミュラを導入した開発機では `/opt/homebrew/bin/whisper-cli` が `Cellar/whisper-cpp/<version>/bin/whisper-cli` へのシンボリックリンクとしてここに乗り、この順位で見つかる。2026-07-14 時点で実在・動作確認済み）
+3. リポジトリ内または隣接する whisper.cpp checkout の `build/bin/whisper-cli`
+
+候補を見つけたら `-h` を実行し、`-m`、`-f`、`-l auto`、`-oj`、`-ojf`、`-of` を受け付ける版か確認する（`whisper-cpp 1.8.4` の `-h` 出力で全オプションの存在を確認済み）。名前が一般的すぎる `main` を由来確認なしで使わない。
+
+#### モデルを探す
+
+次の順に `ggml-*.bin` を探索する。
+
+1. `WHISPER_CPP_MODEL` で明示された読み取り可能なファイル
+2. リポジトリ内の `models/`、`whisper.cpp/models/`
+3. `$HOME/.cache/whisper.cpp/`
+4. `$HOME/Library/Caches/whisper.cpp/`
+5. Homebrew の `whisper-cpp` が導入済みなら、その share ディレクトリ
+6. VoiceInk（`com.prakashjoshipax.VoiceInk`）が保存した whisper.cpp モデル: `$HOME/Library/Application Support/com.prakashjoshipax.VoiceInk/WhisperModels/`
+
+6 は姉妹スキル `whisper-transcribe` が既定で再利用するモデル置き場と同じである。1〜5 のいずれかで見つかればそちらを優先し、6 はそれらが全て空のときだけ評価する。1〜5 が典型的な開発機ではどれも存在せず `transcript: []` へ不要に劣化していたため、この開発機で実際にモデルが手に入る場所を探索順の最後に加えた。実在確認: 2026-07-14 時点でこのパスに `ggml-large-v3-turbo-q5_0.bin`（約 574 MB）が存在することを確認済み。
+
+存在するルートだけを対象に、例えば zsh では次のように列挙する。
+
+```zsh
+MODEL_ROOTS=(
+  "$REPO_ROOT/models"
+  "$REPO_ROOT/whisper.cpp/models"
+  "$HOME/.cache/whisper.cpp"
+  "$HOME/Library/Caches/whisper.cpp"
+)
+if command -v brew >/dev/null && BREW_PREFIX="$(brew --prefix whisper-cpp 2>/dev/null)"; then
+  MODEL_ROOTS+=("$BREW_PREFIX/share/whisper-cpp")
+fi
+MODEL_ROOTS+=("$HOME/Library/Application Support/com.prakashjoshipax.VoiceInk/WhisperModels")
+
+for model_root in "${MODEL_ROOTS[@]}"; do
+  [[ -d "$model_root" ]] || continue
+  find "$model_root" -type f -name 'ggml-*.bin' -not -name 'for-tests-*' -print
+done
+```
+
+探索範囲をファイルシステム全体へ無制限に広げない。whisper.cpp の `for-tests-*` はテスト専用なので、広い探索で見えても本番文字起こしに使わない。複数候補がある場合は、明示指定を最優先し、次に上記の探索順で見つかったローカルの多言語モデルを使い、選択理由を報告する。英語専用の `*.en.bin` は、素材が英語だと確認できた場合だけ使う。
+
+#### 音声を入力形式へ変換する
+
+音声ストリームがある場合だけ、プロキシから mono 16 kHz PCM WAV を作る。
+
+```bash
+ffmpeg -hide_banner -nostdin -y -i "$OUT_DIR/proxy.mp4" \
+  -map 0:a:0 -ar 16000 -ac 1 -c:a pcm_s16le \
+  "$OUT_DIR/whisper-input.wav"
+```
+
+16 kHz PCM への変換手順と CLI オプションは whisper.cpp 公式資料に基づく。
+
+一次資料: [whisper.cpp CLI README](https://github.com/ggml-org/whisper.cpp/blob/master/examples/cli/README.md)
+
+#### ローカル文字起こしを実行する
+
+```bash
+"$WHISPER_BIN" \
+  -m "$WHISPER_MODEL" \
+  -f "$OUT_DIR/whisper-input.wav" \
+  -l auto -oj -ojf \
+  -of "$OUT_DIR/whisper.raw"
+```
+
+`-of` は拡張子を含まない出力 prefix であり、生成された JSON の実在パスを確認する。API キーを使うクラウド文字起こしへ勝手に切り替えない。
+
+#### whisper JSON を正規化する
+
+raw JSON をそのまま `analysis.json` に貼らない。公式 CLI 実装では segment と token の `offsets.from/to` はミリ秒整数、`timestamps.from/to` は表示用文字列である。数値時刻は `offsets` を 1000 で割って source 秒へ変換する。
+
+一次資料: [whisper.cpp CLI source](https://github.com/ggml-org/whisper.cpp/blob/master/examples/cli/cli.cpp)
+
+正規化ルール:
+
+- segment を必須の `{ start, end, text }` と、根拠がある場合だけ任意の `speaker`、`words` に正規化する。
+- `start` と `end` は `offsets.from / 1000`、`offsets.to / 1000` とし、`end > start` を確認する。
+- 通常実行には話者分離がないため `speaker` を省略する。実際に話者分離を実行して対応を確認できた場合だけ非空 ID を入れる。
+- `words` は次項の手順で**原則組み立てる**（word 単位のカット精度、字幕の文字追従表示、タイムスタンプを保った字幕修正など下流機能の基盤になるため）。信頼できる単語時刻をどうしても作れない segment に限り `words` を省略し、省略した segment 数と理由を完了報告に書く。
+- transcript を source 時刻の昇順に並べ、原本 duration 外へはみ出さないことを確認する。
+- `tracks.speakers` は話者分離を実際に行い、各 ID の区間を確認できた場合だけ作る。通常実行では空配列にする。
+
+1000 による換算は whisper.cpp のミリ秒出力を秒契約へ変える単位換算であり、編集上の閾値ではない。
+
+#### words（単語タイムスタンプ）を組み立てる
+
+full JSON の `tokens[]` は BPE 単位であり、日本語ではマルチバイト文字が token 境界で分断されて、**token 単体の `text` が不正なバイト列になる**ことがある（実測: 62 分の日本語実素材で該当。strict UTF-8 の `json.load` がファイル全体で失敗する）。raw JSON をバイト単位で読み、次の手順で word を復元する。
+
+1. segment 内の token を順に走査し、制御 token（`[_BEG_]` など `[` 始まり）と空文字を除く。
+2. 連続する token の `text` バイト列を連結し、**有効な UTF-8 になった時点で 1 word として確定**する。`start` は先頭 token の `offsets.from / 1000`、`end` は末尾 token の `offsets.to / 1000`。
+3. 末尾に不正バイトの端数が残った場合は直前の word に吸収し、それでも復元できないバイトは捨てて完了報告に書く。`U+FFFD`（置換文字）を `words[].text` に残さない。
+4. word の時刻が親 segment の区間からはみ出す場合は segment 区間へクランプする。クランプで `end > start` を保てない word は捨てる。
+
+日本語では「word」は形態素単位ではなく token 連結由来のかたまりになるが、字幕追従・カット精度の用途にはこの粒度で足りる。粒度の細かさより時刻の正確さを優先する。segment 単位の `text` しか使わない場合でも、raw JSON の読み込み自体が strict UTF-8 で失敗しうる点は同じなので、バイト単位読み（または `errors='replace'` での読み捨て）を最初から使う。
+
+### 層 3: クラウド（オプトイン・決定カード）
+
+- 層 1/2 のローカル結果とは独立に、`.akari/connections.json` の `elevenlabs`（ElevenLabs Scribe = 品質枠）または `groq`（Groq whisper = 速度枠）が `doctor.status === "ok"` で、credentials.env に対応キーが設定済みのときだけ決定カードを**提案してよい**。未設定または非 ok の provider は選択肢自体を出さない。既定はあくまでローカルである。
+- `node bin/transcribe-cloud.mjs --decision-card --project-root <.akari を持つプロジェクトルート> --duration <source 秒>` で決定カードを得る。速度（RTF・待ち時間見積）× 品質（所見）× 費用（概算）の 3 軸を SpeechAnalyzer の基準値とクラウド候補で提示する。実測値は internal 契約 §2 の表を引用する。
+- 人間の明示承認を得るまで音声を送信しない。
+- 送信前に音声を mono 32〜64k へ抽出する。Groq は 32k、Scribe は 64k を既定にする。
+
+  ```bash
+  ffmpeg -hide_banner -nostdin -y -i "$OUT_DIR/proxy.mp4" \
+    -map 0:a:0 -ac 1 -c:a aac -b:a "${BITRATE}k" \
+    "$OUT_DIR/cloud-input.m4a"
+  ```
+
+- 承認後だけ実送信する。
+
+  ```bash
+  node bin/transcribe-cloud.mjs --send --provider scribe|groq \
+    --input "$OUT_DIR/cloud-input.m4a" --duration <source秒> \
+    --project-root <...> --approved
+  ```
+
+- 単発送信を既定とする。プロバイダの上限（Groq 25MB・Scribe 10 時間相当）を超える場合だけ、無音検出を優先した境界で分割し**逐次**送信する（**並列同時送信は実装しない**。`grep -n "Promise.all\|allSettled\|worker_threads" bin/transcribe-cloud.mjs` で不在を確認できる）。各分割区間の word/segment 時刻は分割開始オフセットを加算してから 1 本の transcript へ縫合する。
+
+#### Scribe words の正規化（句読点への無音吸着を吸わない）
+
+Scribe（`scribe_v1`）は句読点を独立トークンとして返し、**文末の無音をその句読点トークンの `end` へ吸着させる**ことがある（v4.1 実測: 「。」トークン単体が 2〜4 秒に及ぶ例 — 「ね。」2822.84→2826.84 = 4.0s、「です。」相当 3728.939→3731.399 = 2.46s）。この `end` を末尾語へそのまま持ち込むと、実発話が終わったあとの無音区間まで `caption.end` が膨張し、下流で「隙間の原則」（実発話が終われば字幕も終わる。[edit-plan の execution.md](../edit-plan/execution.md) 参照）を破る。そのため `bin/transcribe-cloud.mjs` の `normalizeScribe` は**句読点のみのトークンを直前語のテキストへ結合し、直前語の `end` は据え置く**（句読点トークン自身の `end` を採用しない）。ゼロ幅・非ゼロ幅（無音吸着）どちらの句読点トークンも同じ規則で吸収する。この挙動は [test/normalize-scribe.test.mjs](test/normalize-scribe.test.mjs)（膨張ケースの fixture）で固定してある。
+
+## provenance（backend の記録）
+
+- 使用した backend（`speechanalyzer` / `whisper-cpp` / `scribe` / `groq`）は **analysis.json には書かない**。`packages/schemas/analysis.schema.json` の `transcriptSegment` は `additionalProperties: false` で `backend` を許可しておらず、このタスクの境界（`packages/**` は編集禁止）ではスキーマを変更できない。既存の「劣化理由は Schema 外のフィールドとして JSON に足さず、完了報告に書く」規約と同じ扱いとし、使用した backend と選定理由を完了報告に明記する（[workflow.md](workflow.md) の完了報告項目を参照）。
+- filler イベント検出は whisper.cpp 由来 transcript ではフィラーが正規化で脱落するため、SpeechAnalyzer / Scribe 由来 transcript がある場合はそちらを優先する（[events-and-hooks.md](events-and-hooks.md) 参照）。
+
+## 文字起こし不能時の劣化
+
+音声ストリームがない場合、または層 1/2 が失敗し、層 3 も非該当・未承認・失敗となって 3 層すべてから有効な結果を得られない場合は、`transcript: []` として視覚分析を続ける。ほかの根拠で確認済み話者 track がなければ `tracks.speakers: []` とする。次の原因を確認し、該当するものを報告する。
+
+- 音声ストリームがない。
+- SpeechAnalyzer の利用条件を満たさない、ビルドできない、またはヘルパーが失敗した。
+- `whisper-cli` がない、実行できない、または必要なオプションに非対応である。
+- 読み取り可能な適合モデルがない。
+- 音声変換または推論が失敗し、有効な時刻付き結果を回収できない。
+- 推論自体は成功したが、出力がハルシネーション（非発話区間への定型文出力等）と判定でき、実発話の記録として採用できない（判定基準は次項）。
+- 登録済みで doctor ok のクラウド provider がない、明示承認がない、または承認後の送信が失敗した。
+
+### ハルシネーション疑いの判定基準
+
+whisper.cpp は無音・環境音のみの区間に対しても、学習データ由来の短い定型英語フレーズ（"Thank you." "Thanks for watching." "Bye." 等）を確信度高く出力することがある。これは実行時エラーを起こさないため、上の 4 条件だけでは検出できない。次のいずれかに強く合致する segment は採用しない。
+
+- **音声エネルギー突合**: 該当区間の音声にエネルギーがあるかを ffmpeg の `volumedetect` で確認し、無音〜背景ノイズレベルの区間に発話が記録されていないか照合する。
+
+  ```bash
+  ffmpeg -hide_banner -nostdin -i "$OUT_DIR/whisper-input.wav" -af volumedetect -f null - 2>&1 \
+    | grep -E "mean_volume|max_volume"
+  ```
+
+- **短い定型文の反復**: 内容が変化しないまま同一・類似の短い定型文が複数 segment にわたって繰り返され、transcript 全体の文脈と噛み合わない。
+- **視認済みキーフレームとの矛盾**: [keyframes-and-review.md](keyframes-and-review.md) で視認した keyframe に人物・発話の兆候（口の動き、字幕、マイク等）がないのに、断定的な発言内容が記録されている。
+
+いずれかに合致する segment は transcript から除外する。全 segment が該当するなら `transcript: []` に確定する。一部 segment だけが該当する場合は、除外した segment を除いた残りで transcript を組み立て、除外理由を完了報告に書く。判断に迷うグレーな segment は黙って残さず、根拠とともに完了報告へ書いて人間の確認を仰ぐ。
+
+実測記録: testsrc 60 秒 + 440Hz 正弦波音声（実発話なし）の素材を whisper.cpp（`ggml-large-v3-turbo-q5_0.bin`）で文字起こしした際に "Thank you." が出力され、音声エネルギー突合（正弦波トーンのみで発話兆候なし）と視認済みキーフレーム（テストパターンのみで人物・字幕なし）の両方と矛盾することを確認して不採用にした事例がある。
+
+完了報告には `transcript_unavailable` と具体的理由、探索した実行ファイル・モデルの場所を書く。空配列を「発話なし」と断定せず、「文字起こし未取得」と明記する。ハルシネーション判定で除外した場合も、除外した segment の内容・時刻・根拠を完了報告に書く。
+
+## よくある間違い
+
+- モデルを見つけるために無断ダウンロードする。
+- 日本語素材へ英語専用モデルを使い、壊れた文字列を確定する。
+- `timestamps` の表示文字列を浮動小数として雑にパースする。
+- ミリ秒を秒として保存し、全 event 時刻を 1000 倍ずらす。
+- token の確率や内部 ID を Schema 外のフィールドとして残す。
+- token 1 個 = 1 word とみなし、分断されたマルチバイト文字を `U+FFFD` のまま `words` に残す。
+- 作れるのに `words` を省略し、word 精度のカット・字幕追従など下流機能の基盤を欠落させる。
+- whisper.cpp がないのに transcript を要約から捏造する。
+- ハルシネーション疑いの定型文を音声・視認と突合せず transcript として確定する。
+- クラウド決定カードの明示承認前に音声を送信する。
+- 分割送信を並列（`Promise.all` 等）で実装し、無料枠のレート制限へ配慮しない（契約 §3 で明示的に不採用と裁定済み）。
+- Scribe の句読点トークンの `end`（文末無音を吸着した膨張値）を末尾語の `end` にして、無音区間まで字幕を伸ばす。

package/vendor/skills/analyze-footage/person-matte.md

@@ -0,0 +1,121 @@
+# 人物マットを作る（任意工程）
+
+## 目次
+
+- [実行するかを先に決める](#実行するかを先に決める)
+- [道具を確認する](#道具を確認する)
+- [生成する](#生成する)
+- [analysis.json へ書く](#analysisjson-へ書く)
+- [劣化](#劣化)
+
+## 原則
+
+人物マットは**人物演出（text-behind-person など）を使うと決めた素材でだけ**作る。既定の分析
+フローはマットを作らず `tracks.person_matte` に `null` を書く。データ契約は
+[docs/contract-2026-07-23-analysis-person-matte.md](../../docs/contract-2026-07-23-analysis-person-matte.md) が正本である。
+
+## 実行するかを先に決める
+
+全素材で常時実行しない。実測コスト（8 秒 / 1280x720 / 24fps / `balanced`・負荷のあるマシン）:
+
+| 工程 | 実時間比 | 備考 |
+|---|---|---|
+| Vision セグメンテーション | 約 1.7 倍 | 58 ms/frame。マットは 512x384 固定 |
+| VP9 alpha エンコード | 残り全部 | **壁時計時間の支配項** |
+| 合計 | **約 7.7 倍**（8 秒 → 62 秒） | 10 分素材なら 1 時間強の目安 |
+
+次のすべてに当てはまるときだけ実行する。
+
+- その素材に人物が映っており、人物を切り抜く演出を使うと決まっている。
+- 素材の尺と上の実時間比から見積もった処理時間を許容できる。
+- 単に「顔が映っている」だけではない（顔トラック `tracks.faces` はマット無しで作れる）。
+
+品質の選び方:
+
+| quality | 用途 | 実測 |
+|---|---|---|
+| `fast` | 当たり付け・「この素材で切り抜けるか」の事前判定のみ | マット 256x192。輪郭が階段状で**本番不可** |
+| `balanced`（既定） | **本番**（text-behind-person / 切り抜き） | マット 512x384・58 ms/frame・実用輪郭 |
+| `accurate` | 寄りカット・最終仕上げ | マット 2016x1512・135 ms/frame・peak 638 MB |
+
+`fast` の出力を本番の成果物として `analysis.json` に載せない。
+
+## 道具を確認する
+
+```bash
+node bin/person-matte/person-matte.mjs --check
+```
+
+`{"available":true}` 以外なら `reason` を報告し、マットを作らずに `null` のまま進む。macOS、
+`swiftc`、`ffmpeg`／`ffprobe`、ffmpeg の `libvpx-vp9` エンコーダのいずれかが欠けていれば作れない。
+ネットワークからツールを導入しない。Swift ヘルパーは初回実行時に `swiftc -O` で自動ビルドされ、
+バイナリはコミットしない（[.gitignore](.gitignore) 参照）。
+
+## 生成する
+
+出力は analysis.json と同じディレクトリの `matte/person-matte.webm` に置く。
+
+```bash
+node bin/person-matte/person-matte.mjs \
+  --input "$SOURCE" \
+  --out "$OUT_DIR/matte/person-matte.webm"
+```
+
+オプション（既定のままで良ければ渡さない）:
+
+- `--quality fast|balanced|accurate`（既定 `balanced`）
+- `--fps <n>`（既定 24）。マット動画の fps。元素材と一致しなくてよい
+- `--decode-width <n>`（既定 1280）。Vision のマット解像度は quality だけで決まり入力解像度に
+  依存しないため、通常は変更しない。素材が 1280 幅未満なら拡大せずその幅を使う
+
+`--input` には**原本**を渡す。プロキシ（`proxy.mp4`）を渡してもよいが、その場合マットの RGB は
+720p の絵になる。原本と時刻対応が崩れた素材を入力にしない。
+
+成功時は 1 行の JSON が返る。`ok`、`frames`、`bytes`、`elapsed_seconds`、`vision_ms_per_frame`、
+`alpha_transparent_ratio`（完全透明画素の割合）、`probe`（ffprobe の実測）を含む。
+ヘルパーは書き出した WebM が `codec_name = vp9` かつ `alpha_mode = 1` であることを確認してから
+成功を返すので、`ok: true` はアルファが落ちていないことを含意する。
+
+`ok: false` なら `reason` を報告し、マットを諦めて `null` のまま分析を続ける。**マットが作れない
+ことを理由に分析全体を失敗扱いにしない。**
+
+## analysis.json へ書く
+
+返ってきた JSON の `person_matte` をそのまま使えるが、**`path` は analysis.json のディレクトリ
+基準の相対パスへ書き換える**（ヘルパーは呼び出し時の絶対パスを返す）。区切りは `/` を使う。
+
+```json
+"person_matte": {
+  "path": "matte/person-matte.webm",
+  "fps": 24,
+  "quality": "balanced",
+  "generated_at": "2026-07-23T01:33:30.069Z",
+  "tool": "vision-person-segmentation"
+}
+```
+
+`path` と `fps` が必須、`quality` / `generated_at` / `tool` は任意である。
+確定前に [analysis-json.md](analysis-json.md#schema-では表せない意味制約) の意味制約も検査する。
+
+- マット動画の時刻 0 が素材の時刻 0 と一致する（区間を切り出したマットを載せない）。
+- `fps` が実際に書き出したマット動画の fps と一致する。
+- `path` を analysis.json の位置から解決でき、実ファイルが存在する。
+
+## 劣化
+
+道具が無い、生成に失敗した、または品質が実用に達しない場合は `tracks.person_matte` を `null` に
+して分析を確定し、理由を完了報告に書く。未生成を空文字や欠落したパスで表さない。
+
+細い毛束を 1 本単位で分離することは Vision ではできない（セグメンテーションであってマット化では
+ない）。逆光・毛先の抜けが要求水準になる素材では、マットが取れても品質不足として `null` を選ぶ
+判断があり得る。その判断も完了報告に書く。
+
+## よくある間違い
+
+- 人物演出を使うと決まっていない素材にも一律で実行し、分析時間を何倍にもする。
+- `fast` の出力を本番の切り抜きとして確定する。
+- 出来上がったマット動画を ffmpeg で再エンコード・再変換する（アルファが無言で落ちる）。
+- マットを素材の途中区間から切り出し、時刻 0 の一致を壊す。
+- `--fps` を変えたのに `analysis.json` の `fps` を書き換え忘れる。
+- ヘルパーが返した絶対パスをそのまま `path` に書く。
+- マットが作れなかったことを理由に `analysis.json` 自体を出さない。

package/vendor/skills/analyze-footage/references/akari-data-contract.md

@@ -0,0 +1,18 @@
+# `.akari` data contract v1
+
+`workflow.json` declares canonical role paths, localized labels, normal-mode hidden entries, sidecar suffixes,
+and gate event types. Asset metadata lives at `sidecars/<asset-relative-path>.meta.json`; for example,
+`assets/interview.mp4` uses `sidecars/assets/interview.mp4.meta.json`.
+Full per-asset analysis output lives at `sidecars/<asset-relative-path>.analysis/analysis.json`; for example,
+`assets/interview.mp4` uses `sidecars/assets/interview.mp4.analysis/analysis.json`.
+
+An asset meta object has `version: 1`, `asset` (project-relative string), optional `thumbnail` (path or URI),
+optional non-negative `durationSeconds`, optional positive integer `width` and `height`, optional
+`transcript` (`available` boolean and optional `path`), optional `analysis` (`status` and `summary` strings),
+and optional inline `decisions` (`id`, `summary`, `status`). Missing inspection fields mean "未分析".
+
+An optional `<asset>.decisions.json` has `version: 1`, `asset`, and a `decisions` array. Each decision contains
+`id`, `summary`, `status` (`proposed`, `approved`, or `rejected`), and ISO-8601 `updatedAt`.
+
+Each immutable event has `version: 1`, unique `id`, `type`, and ISO-8601 `occurredAt`. Gate event types are
+declared by `workflow.json`; other event types such as `video-added` do not create a workflow snapshot.

package/vendor/skills/analyze-footage/references/asset.meta.example.json

@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "asset": "assets/interview.mp4",
+  "thumbnail": "thumbnails/interview.jpg",
+  "durationSeconds": 92.4,
+  "width": 1920,
+  "height": 1080,
+  "transcript": {
+    "available": true,
+    "path": "planning/interview.transcript.json"
+  },
+  "analysis": {
+    "status": "complete",
+    "summary": "製品紹介と導入効果を説明するインタビュー。"
+  },
+  "decisions": [
+    {
+      "id": "opening-hook",
+      "summary": "冒頭の結論を先に見せる",
+      "status": "approved"
+    }
+  ]
+}