akari-video 0.1.33 → 0.1.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "description": "AKARI Video launcher CLI — start an AI-edited video project from any directory: scaffold, connection check, then hand over to Claude Code (or opencode). AKARI Video を opencode や Claude Code で、どのディレクトリからでも始めるための `akari` ランチャー CLI。接続確認（doctor）→ 未セットアップならプロジェクト雛形を作成 → AI エージェントを起動する。外部 npm 依存ゼロ（Node.js 組み込みモジュールのみ）。",
   "type": "module",
   "bin": {

package/vendor/.akari-capability-sources.json

@@ -51,10 +51,14 @@
     "docs/contract-2026-08-29-media-inspect-cli-v0.md",
     "docs/contract-2026-08-30-edit-json-v2-object-tree-v0.md",
     "docs/contract-2026-08-30-motion-and-keyframes-v0.md",
+    "docs/contract-2026-09-02-audio-clip-fx-v1.md",
+    "docs/contract-2026-09-02-audio-envelope-v1.md",
+    "docs/contract-2026-09-02-audio-insert-level-v1.md",
     "docs/contract-2026-09-02-captions-style-preset-v0.md",
     "docs/contract-2026-09-02-export-verify-declared-vs-measured-v0.md",
     "docs/contract-2026-09-02-item-caption-anchor-v0.md",
     "docs/contract-2026-09-02-transcript-unrecognized-spans-v0.md",
+    "docs/contract-2026-09-02-word-book-v0.md",
     "packages/akari-launcher/package.json",
     "packages/akari-launcher/README.md",
     "packages/akari-tools/package.json",
@@ -88,6 +92,8 @@
     "packages/intake-form/README.md",
     "packages/matte-rvm/package.json",
     "packages/media-bin/package.json",
+    "packages/media-bin/README.ja.md",
+    "packages/media-bin/README.md",
     "packages/osr-export/package.json",
     "packages/osr-export/README.md",
     "packages/overlay-runtime/package.json",
@@ -100,6 +106,7 @@
     "packages/template-render/package.json",
     "packages/template-render/README.ja.md",
     "packages/template-render/README.md",
+    "packages/word-book/package.json",
     "skills/address-review/SKILL.md",
     "skills/analyze-footage/analysis-json.md",
     "skills/analyze-footage/bin/face-expression/vendor/tasks-vision-0.10.17/README-AKARI.md",

package/vendor/docs/contract-2026-07-14-edit-json-v1-audio.md

@@ -87,6 +87,10 @@ edit.json の親ディレクトリを基準にした相対パス（絶対パス
 
 ## 4. ducking の v1 定義
 
+> 2026-09-02 更新: `sidechaincompress` 方式は廃止した。現在は narration と speech の宣言区間を鍵に、
+> attack / release を持つ共通決定論エンベロープをプレビューと書き出しの両方で使う。
+> 以下は当初 v1 の設計記録として残す。
+
 **採用: `sidechaincompress`（書き出し側のみ、ffmpeg 標準フィルタ）。**
 「字幕/発話区間ベースの単純 gain」は不採用。
 

package/vendor/docs/contract-2026-07-20-edit-json-v1-narration.md

@@ -99,6 +99,9 @@ edit.json の親ディレクトリを基準にした相対パス（絶対パス
 
 ## 3. ducking の主従
 
+2026-09-02 契約により sidechain 方式を廃止し、鍵を narration と speech の宣言区間の和集合とする
+決定論エンベロープ方式へ移行した。既定の鍵は両方であり、対象は `ducking:true` の bgm / sfx である。
+
 `contract-2026-07-14-edit-json-v1-audio.md` §4 は `audio.bgm.ducking: true` のサイドチェイン
 入力（トリガー）を「ダイアログ音声（source 由来の音声トラックそのもの）」と定義していた。
 本契約でナレーションが第一級データになったことに伴い、この入力の**主従**を以下のとおり正文化する:

package/vendor/docs/contract-2026-08-02-creator-root-v1.md

@@ -61,6 +61,7 @@ AKARI Video がマシン上に持ってよい場所は次の 3 つ**だけ**で
 ├── AGENTS.md                      # 橋渡し（akari.md / design.md へ誘導）。初回はスタブ生成
 ├── channels/
 │   └── <channel>/
+│       ├── .akari/memory/word-book.json # 任意。チャンネル単語帳（word book v0 契約）
 │       ├── design.md              # チャンネル設計書（任意。生成工程は非スコープ）
 │       └── videos/
 │           └── <project>/         # 動画プロジェクト（内部は project-structure-v0 のまま）
@@ -69,7 +70,7 @@ AKARI Video がマシン上に持ってよい場所は次の 3 つ**だけ**で
 └── .akari/
     ├── root.json                  # 作業場マニフェスト（版数・チャンネル一覧・生成日）
     ├── connections.json           # provider・モデル・コスト承認ポリシーの作業場既定
-    ├── memory/                    # スタイル学習・記憶（memory-connection の既定接続先 §7）
+    ├── memory/                    # スタイル学習・記憶（memory-connection の既定接続先 §7、word-book.json）
     └── cache/                     # 再生成可能物
 ```
 

package/vendor/docs/contract-2026-08-02-preview-parity.md

@@ -11,6 +11,7 @@
 | 2026-08-02 | v0 | Web UI と shell の挙動仕様を統合 |
 | 2026-08-28 | v2 | `packages/frame-engine` の意味論へ統合し、検収をゴールデンフレームへ一本化。出口を OSR と GPU 直結の 2 本に固定し、互換経路を退役節へ移動 |
 | 2026-08-31 | v2.1 | §5.2 に断片 CSS の `vw` / `vh` 系単位の出力サイズ基準化（`viewport-units.js`。プレビューがウィンドウ幅基準で解いていた実機報告の修正）を追記 |
+| 2026-09-02 | v2.2 | §2.8 に字幕時計の規約（active cue の判定は両プレビューとも出力秒。共有カーネル `caption-clock`）を追記。Web UI を shell に揃えた 4 点（字幕時計・字幕フォント名・`slot-params.js` の差し込み・最下段 cut の track 規則）の記録 |
 
 ## 1. 役割分担
 
@@ -128,6 +129,12 @@ finalFrameNumber **239**、lookahead hits **8**を要求する。
 shell のプレビューでは DOM 層として提示し、書き出しでは同じ DOM 規約から overlay sheet を構成する。
 器専用の字幕 HTML や出口専用の再レイアウトを持たない。
 
+active cue の判定は両プレビューとも**出力秒**で行う。source 秒の cue（`time_domain: "source"` と未宣言の
+legacy）は共有カーネル `packages/edit-store/src/caption-clock.ts` の `normalizeCaptionClock` が cut map
+で出力秒へ射影し、削除区間をまたぐ cue は 1 本ずつに分割する（`<id>-output-<n>`、元 id は
+`sourceCueId`）。shell は `normalizePreviewCaptionClock`、Web UI は `updateCaption` がこの正規化済み表を
+読み、描画層は domain 判定を行わない（2026-09-02。それまで Web UI は source 秒で判定していた）。
+
 **検収:** OSR ソフト描画の同一 fixture 2 走について、字幕を含む全コマ raw BGRA の SHA-256 一致を要求する。
 
 ### 2.9 overlays
@@ -161,6 +168,7 @@ SHA-256 一致を要求する。GPU は同一マシン一致率を診断値と
 | cuts の perspective | 🟡 未適用・warning のみ（issue #39） | 🟡 同左 | ✅ DOM 層 | 🟡 warning を run.json へ（seek の warning を回収） | 🟡 warning を run.json へ |
 | 5 transitions | ✅ 評価 | ✅ 完成 frame を提示 | ✅ 完成 frame を提示 | ✅ 完成 frame を捕捉 | ✅ canvas を直結 |
 | matte / chroma key | ✅ 評価 | ✅ stamp 同期 | ✅ stamp 同期 | ✅ stamp 同期・捕捉 | ✅ 同一 frame 評価 |
+| アルファ層の取り込み（`.webm` / `.mov` → color + mask mp4） | — 入力境界の外（media-bin `alpha-intake` が正本） | ✅ サーバ側 `prepareAlphaLayers`（`frameEngine.intake`） | ✅ node RPC `prepareAlphaIntake`（同一 media-bin・同一派生物、2026-09-02） | ✅ page-builder | ✅ page-builder |
 | LUT / `bt709-limited` | ✅ 評価 | ✅ 提示 | ✅ 提示 | ✅ 捕捉・encode | ✅ LUT 後 canvas を直結 |
 | 字幕 | — DOM 規約へ active state を供給 | ✅ DOM 層 | ✅ DOM 層 | ✅ 同規約の overlay sheet | 🟡 適格 cue を sprite 化 |
 | overlays / 3D | — DOM 規約へ時刻を供給 | ✅ DOM 層 | ✅ DOM 層 | ✅ 同規約の overlay sheet | 🟡 static / 宣言型 3D のみ |

package/vendor/docs/contract-2026-08-28-v2-audio-roles-v0.md

@@ -25,7 +25,7 @@ render-cut は最終成果物の音声品質を決める唯一の正である。
 
 | 項目 | プレビュー（Web Audio） | 書き出し（ffmpeg） | 差の性質 |
 |---|---|---|---|
-| ducking | narration の実効区間を矩形エンベロープ化し、区間内をカーネル既定の固定減衰にする | narration を主、素材ダイアログを fallback の sidechain とする `sidechaincompress` | プレビューは発話レベルに反応せず、attack / release も持たない。master 無しの実測差は 1.67 dB（§3.2） |
+| ducking | 共通決定論エンベロープを `exponentialRampToValueAtTime` で適用する | 同じエンベロープを f32le 化して `amultiply` する | デコーダとサンプル境界の差だけを許容する |
 | BGM fade | タイムライン上の `fadeIn` / `fadeOut` を線形 `AudioParam` automation にする | `afade` をマスター音声チェーン内で適用する | master 無しの実測差は ±0.034 dB 以内（§3.2）。後段処理後の振幅は一致しない場合がある |
 | SFX fade | クリップ実効尺に対する `fade_in` / `fade_out` を線形 automation にする | trim 後の実効尺へ `afade` を適用する | 基本形状は同じ。後段マスター処理の影響は書き出しだけに生じる |
 | ラウドネス | 個別 gain と fade / ducking の合成のみ。番組全体の規格化はしない | EBU R128 計測とマスター処理を適用する | I / LRA / TP は一致を保証しない |
@@ -105,7 +105,7 @@ ms へ換算し、絶対値で集計する。全 59 点の最大は 16.667 ms、
 
 **G3 裁定（2026-08-28）:**
 
-1. ducking は矩形近似を残す。カーネル共通エンベロープ化は別票とする。
+1. 2026-09-02 契約で共通決定論エンベロープ化した。`sidechaincompress` は廃止した。
 2. fade は時刻が一致しているため近似として残す。
 3. ループ境界 / trim 境界の追加測定は別票とする。
 4. SFX の true peak は書き出し確認必須のままとし、プレビューに保護を入れない。
@@ -115,8 +115,7 @@ ms へ換算し、絶対値で集計する。全 59 点の最大は 16.667 ms、
 
 - Web Audio と ffmpeg のデコーダ、サンプル境界、出力デバイスの差
 - プレビューで afftdn / loudnorm / true peak guard を実行しないこと
-- プレビュー ducking を固定区間で表すこと。ただし §3 の差が G3 の許容範囲を超える場合は、
-  §4.1 の共通エンベロープ案を採用してから G3 へ進む
+- ducking の共通エンベロープは両経路で同じで、デコーダとサンプル境界の差だけを残すこと
 - 聴感確認の即時性を優先し、プレビューでは最終マスター処理の計算コストを負わないこと
 
 これらの近似を残しても、タイムライン上の開始、trim、loop、gain、fade、ducking 対象区間は
@@ -124,10 +123,10 @@ ms へ換算し、絶対値で集計する。全 59 点の最大は 16.667 ms、
 
 ## 6. 撮影素材の台詞と ducking 側鎖
 
-`speech` は cuts[] の撮影素材に含まれる音声を表し、各カットの trim / speed / freeze を
-出力タイムラインへ投影して Web Audio プレビューへ供給する。ただし `speech` は ducking の
-側鎖へ入れない。書き出しの `sidechaincompress` で鍵入力になるのは narration のみであり、
-土台カット音声 `[0:a]` は鍵ではないため、プレビューも同じ対象区間を維持する。
+`speech` は cuts[] の撮影素材に含まれる音声を表し、各カットの trim / speed を出力タイムラインへ
+投影する。2026-09-02 契約では `analysis.json` の transcript 区間を同じ写像で ducking 鍵へ加える。
+書き出しはこの speech 鍵を消費する。プレビューサーバーへ speech 鍵を渡す配線は同契約の範囲外で、
+配線されるまでは narration 鍵だけへ劣化する。
 
 ## 7. 速度変更した台詞のピッチ保持サイドカー
 
@@ -157,6 +156,12 @@ FLAC（compression level 5）へ一度だけ切り出す。`transition_out` 境
 
 BGM / SFX / narration は、元ファイルが WAV かつ 8 MB 超のとき同じ FLAC サイドカーを使う。
 frame-engine は映像の ready を先に成立させ、その直後から予定表上の初回使用時刻順・同時 2 本で
-全音声を非同期にデコードする。デコード済み PCM は合計バイトで管理し、既定上限は 256 MB。
-上限超過時は次に使う時刻が最も遠い項目から退避する。再生開始は先読み済みの項目を再利用し、
-未着の項目だけを待つため、先読み処理は初期フレームの描画を止めない。
+全音声を非同期にデコードする。デコード済み PCM は合計バイトで管理し、既定予算は 256 MiB。
+予算を超えても buffer は捨てない（2026-09-02 改訂。以前は次に使う時刻が最も遠い項目から黙って
+退避し、その音源が予定表から消えて無音になっていた）。超過は警告 1 行と `debug().prefetch.overBudget`
+で示す。展開後のサイズが 64 MiB（48 kHz ステレオ約 2.9 分）を超えると見積もられる音源は、
+`OfflineAudioContext` で 24 kHz に落として decode しモノラルへ畳んで保持する（compact。
+プレビュー専用の近似で、納品マスターには影響しない）。見積もりは WAV / FLAC のヘッダから、
+他の圧縮音声は符号化サイズの 16 倍で行う。再生開始は先読み済みの項目を再利用し、未着の項目だけを
+待つため、先読み処理は初期フレームの描画を止めない。decode に失敗した項目は 5 秒空けて再試行し、
+それまで `debug().prefetch.failed` に載る。

package/vendor/docs/contract-2026-08-29-media-inspect-cli-v0.md

@@ -126,7 +126,7 @@ ffmpeg / ffprobe / whisper.cpp を直接叩いている。本契約はそれを
   transcribe の要否を決めるゲートに使い、字幕の根拠にはしない
 - 目安コスト: 秒。帳面には `tracks.waveform` として追記（§3）
 
-### 2.5 `akari media transcribe <target> [--in <time> --out <time>] [--backend <name>] [--lang <code>] [--no-unrecognized] [--unrecognized-min-gap <sec>] [--unrecognized-min-voiced <sec>]`
+### 2.5 `akari media transcribe <target> [--in <time> --out <time>] [--backend <name>] [--lang <code>] [--no-unrecognized] [--unrecognized-min-gap <sec>] [--unrecognized-min-voiced <sec>] [--no-word-book] [--word-book <path>]`
 
 何を喋っているかを、語ごとの時刻つきで返す。
 
@@ -144,6 +144,7 @@ ffmpeg / ffprobe / whisper.cpp を直接叩いている。本契約はそれを
 
 - `segments[]` の形は analysis.json v0 の `transcript[]` と同一（そのまま写せる）。時刻は **source 秒**
 - 各 segment は任意の `unrecognized: [{ start, end }]` に「音はあるが文字にできなかった区間」を持てる。既定は語の隙間 0.45 秒以上から無音を引いた残り 0.3 秒以上を採用し、`--unrecognized-min-gap` / `--unrecognized-min-voiced` で閾値を変え、`--no-unrecognized` で検出を止める。キャッシュ key は従来どおりで、古い cache hit に `unrecognized` が無い場合は仕様どおりそのまま返し、再 transcribe で付与する
+- 既定では STT 直後に作業場基底の単語帳を語境界で適用する。`--no-word-book` で無効化し、`--word-book <path>` で project より近い検証用の層を追加できる。文字起こしキャッシュは置換前の生出力を保存し、単語帳プリパスは cache hit / miss ともキャッシュ読み出し後・analysis.json 記録前に毎回適用する
 - バックエンドは analyze-footage の 3 層と同じ優先順: macOS SpeechAnalyzer（26+・swiftc 可）→ whisper.cpp → クラウド。
   **クラウドは `--backend cloud:<connection-id>` を明示したときだけ**で、`.akari/connections.json` に doctor `ok` で
   登録済みの接続に限る。既定で外部に音声を送らない。キーの値を stdout / stderr / 出力ファイルに出さない

package/vendor/docs/contract-2026-09-02-audio-clip-fx-v1.md

@@ -0,0 +1,56 @@
+# 音声クリップ FX v1
+
+- 日付: 2026-09-02
+- 状態: 実装契約
+- 対象: legacy `audio.*`、v2 audio item、render-cut、preview-audio sidecar
+
+## 1. 宣言
+
+| キー | 対象 | 型・範囲 | 既定 | v2 の位置 |
+|---|---|---|---|---|
+| `speed` | sfx / bgm | number `(0.25, 4]` | `1` | `item.source` |
+| `pitch_semitones` | sfx / bgm | number `[-24, 24]` | `0` | `item.source` |
+| `formant` | sfx / bgm | `preserve \| shift` | `preserve` | `item.source` |
+| `denoise` | sfx / bgm / narration | `{ method: fft \| nlm, strength: 0..1 }` | なし | item |
+| `lowcut_hz` | sfx / bgm / narration | number `[0, 400]` | `0` | item |
+
+`speed` はタイムライン上の `t` を変えず、実効尺を素材窓の尺 / `speed` とする。
+`pitch_semitones` は速度を変えない。narration の `speed` / `pitch_semitones` は TTS 側の責務なので
+lint warning として無視する。legacy と v2 の投影は上表の値を往復で保持する。
+
+## 2. フィルタチェーン
+
+クリップごとの順序は次で固定する。
+
+`atrim(in/out)` → `highpass=f=<lowcut_hz>:p=2` → `highpass=f=<lowcut_hz>:p=2` → denoise →
+`rubberband=tempo=<speed>:pitch=<2^(pitch_semitones/12)>:formant=<preserved|shifted>:pitchq=quality` →
+`volume` → `afade` → envelope `amultiply` → `adelay`
+
+lowcut は同一の 2 次 highpass を 2 段カスケードし、24 dB/oct の減衰特性で L1 ゲート
+（1 oct 下で 15 dB 以上の減衰）を満たすための裁定逸脱とする。
+
+denoise は `fft` なら `afftdn=nr=<12+strength*76>:nf=-30`、`nlm` なら
+`anlmdn=s=<0.00001+strength*0.0002>` とする。rubberband は `speed != 1` または
+`pitch_semitones != 0` のときだけ作る。全キーが既定なら入力もフィルタも追加せず、従来の
+filtergraph をバイト単位で維持する。
+
+fade、envelope、duck のクリップ窓は speed 適用後の実効尺を使う。BGM は素材先頭へ戻る既存の
+ループ意味論を保ち、ループした入力に同じ clip FX を適用してタイムライン尺へ切る。
+
+## 3. プレビューサイドカー
+
+recipe は `preview-audio-flac-v2`。対象クリップの `[in,out)` を `atrim` し、上記と同じ
+clip-FX フィルタ生成関数で処理して 48 kHz FLAC へ焼く。cache key は source の絶対パス・size・
+mtime・in/out・pad・recipe に加え、`atrim` を含む完全なフィルタ列を含む。同一入力・同一列は
+同じ FLAC を再利用し、列が変われば別 key にする。掃除は従来どおり keep key 以外の FLAC と
+旧 `speech-atempo/*.wav` を除く。
+
+サイドカー化された sfx / bgm / narration は Web Audio で `playbackRate = 1` とし、FLAC の実尺を
+予定表の実効尺にする。生成失敗時はプレビューを停止せず元ファイルへ退避し、書き出しとの近似が
+崩れる旨を warning 1 行で報告する。
+
+## 4. provenance と残す近似
+
+receipt の `provenance.audio.clip_fx` は `processed_items` と `filters` の件数を持つ。
+プレビューと書き出しで意図的に残す近似は、サイドカー FLAC の再圧縮とデコーダ／サンプル境界の
+差だけとする。

package/vendor/docs/contract-2026-09-02-audio-envelope-v1.md

@@ -0,0 +1,91 @@
+# 音声エンベロープ・カーネル v1
+
+- 日付: 2026-09-02
+- 状態: 実装契約
+- 対象: legacy `audio.*`、v2 audio item、Web Audio プレビュー、render-cut
+
+## 1. 共通 primitive
+
+`EnvelopePoint` は `{ t, gainDb, easing? }` とし、`t` はクリップ先頭を 0 とする秒、`gainDb` は
+基準ゲインへ加える dB である。点の前後は端点値を保持し、点間は overlay keyframe と同じ easing
+係数で dB 補間する。`hold` は前値保持、既定は `linear` とする。
+
+エンベロープ同士は dB 加算する。非線形区間は最大 20 ms 間隔の折線へ展開する。Web Audio では
+dB 線形区間を `exponentialRampToValueAtTime` へ変換し、線形ゲインの下限を `1e-4`（-80 dB）とする。
+書き出しでは同じ評価関数を 48 kHz の mono f32le に標本化する。
+
+## 2. 音量キーフレーム
+
+| 形式 | 宣言 | 時刻 | 範囲 |
+|---|---|---|---|
+| v2 audio item | `keyframes[].gain_db` | item 相対の整数フレーム | `[-60, 12]` dB |
+| legacy bgm / sfx / narration | `keyframes[].gain_db` | クリップ相対秒 | `[-60, 12]` dB |
+
+v2 の visual 用キーは audio item では無視し、lint warning を出す。legacy view は v2 のフレームを
+`output.fps` で秒へ変換する。キーフレーム値はクリップの `gain_db` に加算し、fade と ducking とは
+独立に線形領域で乗算する。
+
+## 3. ダッキング
+
+| キー | 型・範囲 | 既定 | 意味 |
+|---|---|---|---|
+| `ducking` | boolean | `false` | bgm / sfx を対象にする |
+| `duck_db` | `[-40, 0]` dB | `-12` | 減衰量 |
+| `duck_attack` | `[0, 2]` 秒 | `0.3` | 鍵開始前の下降時間 |
+| `duck_release` | `[0, 5]` 秒 | `0.8` | 鍵終了後の復帰時間 |
+| `audio.duck_keys` | `narration` / `speech` の配列 | 両方 | 鍵の選択 |
+
+2026-09-02 のオーナー実機フィードバック「切り替わりが急」を受け、既定の attack / release をよりなだらかに変更した。
+
+`narration` 鍵は配置時刻とデコード／probe 実尺から作る。`speech` 鍵はプロジェクト直下の
+`analysis.json` にある source 秒の transcript を、cut の in / out / speed と timeline map で写像する。
+source は analysis.json の所在ディレクトリ基準で正規化し、`sources[].path` と一致する cut だけを使う。
+350 ms 未満の発話間隔は結合し、150 ms 未満の孤立区間は捨てる。analysis 不在・空・source 不一致は
+空の鍵と warning 1 行へ劣化する。
+
+鍵区間の隙間が `attack + release` 未満なら結合する。各区間 `[s,e)` は `s-attack` の 0 dB から
+`s` の `duck_db` へ下降し、`e` まで保持して `e+release` で 0 dB に戻る。負時刻は 0 に固定し、
+対象クリップへ相対化して範囲外を切り詰める。実効ゲインは
+`gain_db + keyframes(t) + duck(t)` を線形化した値に fade を掛けたものとする。
+
+## 4. プレビュー
+
+`audio-schedule` は全音声 kind に `envelopeEvents` を出す。frame-engine はイベントがある場合だけ
+第 2 GainNode を作り、`setValueAtTime` または `exponentialRampToValueAtTime` で適用する。
+`duckIntervals` は UI 表示互換のため残す。
+
+現版では preview-server へ speech interval を供給する配線はスコープ外である。入力が無い場合は
+narration 鍵だけで動作し、共通カーネル自体と render-cut の speech 写像を正とする。
+
+## 5. 書き出し
+
+`sidechaincompress` と narration 分岐用 `asplit` は使用しない。keyframe または実際の duck 区間を持つ
+対象だけに `env-<label>.f32` を作り、48 kHz mono f32le 入力として読む。対象音声は `amultiply` の直前に
+`aformat=sample_fmts=fltp:sample_rates=48000:channel_layouts=stereo` で stereo/fltp に揃え、mono 素材には
+既定 rematrix の mono→stereo 係数を適用する。env は
+`aformat=sample_fmts=fltp:sample_rates=48000,pan=stereo|c0=c0|c1=c0` で左右へ単位ゲインの等倍複製を行う。
+これにより `amultiply` は素材のチャンネル数によらず常に stereo×stereo になる。挿入位置は `volume` と
+`afade` の後、`adelay` の前とする。全区間 0 dB なら envelope 入力を作らず、従来 filtergraph を維持する。
+
+音声クリップ FX v1 を持つ入力では、チェーンを `atrim` → `highpass` → `afftdn` / `anlmdn` →
+`rubberband` → `volume` → `afade` → envelope `amultiply` → `adelay` の順に固定する。したがって
+clip FX は envelope の前段に入り、speed 適用後の実効尺を envelope と duck のクリップ窓に使う。
+
+run / receipt の provenance は `audio.envelope` に `duck_keys`、`speech_intervals`、`ducked_items`、
+`keyframed_items` を記録する。plan は配列そのものを保持せず、path と点数だけを JSON 化する。
+
+## 6. 検証と互換
+
+schema と reader は型・範囲・時刻順を error にする。lint は実効尺超過、narration の
+`ducking:true`、v2 audio keyframe の visual キーを warning にする。legacy の
+`STATIC_DUCK_GAIN_DB`、`computeDuckIntervals`、`isWithinDuckInterval` は既存 shell 消費者の移行まで
+互換面として残す。
+
+| 処理 | プレビュー | 書き出し |
+|---|---|---|
+| keyframe / duck 補間 | 共通 dB envelope → exponential automation | 共通 dB envelope → f32le → `amultiply` |
+| fade | base GainNode | `afade` |
+| 鍵実尺 | decode 実尺 | ffprobe 実尺 |
+| 許容する差 | デコーダとサンプル境界 | デコーダとサンプル境界 |
+
+afftdn、loudnorm、true peak guard は最終マスターだけの責務であり、プレビューには実装しない。

package/vendor/docs/contract-2026-09-02-audio-insert-level-v1.md

@@ -0,0 +1,110 @@
+# 音声素材の挿入時レベル契約 v1
+
+- 日付: 2026-09-02
+- 状態: 実装済み（S1）
+- 前提: `contract-2026-07-14-edit-json-v1-audio.md`、
+  `contract-2026-07-20-edit-json-v1-narration.md`、
+  `contract-2026-08-28-v2-audio-roles-v0.md`
+- スコープ: 音声素材単体の決定論的なレベル計測、役割別挿入値の計算、
+  `akari media audio-level` による dry-run と edit.json への明示値保存
+
+## 1. 原則
+
+自動レベル合わせは再生中の追従処理ではない。素材を挿入するときに測定し、同じ入力から同じ
+`gain_db` と既定 fade を導出して edit.json に数値として残す。以後のプレビューと書き出しは
+その宣言値を消費する。素材カタログの既存ラウドネス値は使わず、外部素材と同じ実体計測を行う。
+
+## 2. 計測契約
+
+計測器の metric は `akari-audio-measure-v1` とし、次を返す。
+
+| フィールド | 単位 | 定義 |
+|---|---:|---|
+| `integrated_lufs` | LUFS | EBU R128 Summary の I。-70.0 LUFS 以下または解析不能は `null` |
+| `loudness_range_lu` | LU | EBU R128 Summary の LRA。I が無効なら `null` 可 |
+| `true_peak_dbtp` | dBTP | EBU R128 Summary の Peak。無音の `-inf` は `null` |
+| `sample_peak_dbfs` | dBFS | astats Overall の Peak level。無音の `-inf` は `null` |
+| `rms_dbfs` | dBFS | astats Overall の RMS level。無音の `-inf` は `null` |
+| `duration_sec` | 秒 | ffprobe format duration |
+| `sample_rate` | Hz | ffprobe の先頭 audio stream |
+| `channels` | — | ffprobe の先頭 audio stream |
+
+ffmpeg は音声ごとに 1 パスだけ実行し、次の引数を使う。
+
+```text
+-vn -sn -dn -af ebur128=peak=true:framelog=verbose,astats=measure_perchannel=none:measure_overall=Peak_level+RMS_level -f null -
+```
+
+duration / sample rate / channels は ffprobe で決定論的に取得する。パーサは最後の ebur128
+`Summary:` と astats `Overall` を読み、映像・字幕・data stream は計測対象にしない。
+
+### 2.1 キャッシュ
+
+素材の realpath、byte size、`mtimeMs`、metric を `|` で連結し、
+`sha1(realpath|size|mtimeMs|metric)` を key とする。保存先は
+`<cacheDir>/<key>.json`。`akari media audio-level` の cacheDir は
+`<projectRoot>/.akari/cache/audio-measure/` である。単体の `akari-audio-measure` CLI も素材の
+親から上へ辿って最初に `.akari` ディレクトリを持つ projectRoot を使い、見つからない場合だけ
+素材の親を projectRoot とみなす。`--no-cache` または `useCache: false` は
+必ず再計測し、同じ key の JSON を上書きする。
+
+## 3. 役割別の目標
+
+| role | integrated target (LUFS) | fade in (s) | fade out (s) |
+|---|---:|---:|---:|
+| narration | -16 | 0 | 0 |
+| sfx | -18 | 0 | 0 |
+| jingle | -18 | 0 | 0.3 |
+| music | -20 | 0.2 | 1.0 |
+| ambience | -26 | 0.5 | 0.5 |
+| bgm | -26 | 0 | 0 |
+
+true peak ceiling は -1.0 dBTP、短尺境界は 1.0 秒、短尺 sample peak target は -3.0 dBFS。
+未知 role は目標と fade の両方で sfx として扱う。
+
+## 4. 挿入値の式
+
+`computeInsertLevel` は次の順序で 1 回だけ値を決める。
+
+1. 計測値が無ければ `basis: none`、`gain_db: 0` と役割既定 fade を返す。
+2. `duration_sec < 1.0` または `integrated_lufs == null` なら `basis: peak` とし、
+   `gain = -3.0 - sample_peak_dbfs`。sample peak も無ければ 1 と同じ。
+3. それ以外は `basis: lufs` とし、`gain = role target - integrated_lufs`。
+4. true peak があれば `gain = min(gain, ceilingDbtp - true_peak_dbtp)` とする。
+   実際に gain を下げた場合だけ `peak_guard_applied: true`。
+5. gain を `[-60, 12]` へクランプした後、`Math.round(x * 10) / 10` で 0.1 dB に丸める。
+   `-0` は `0` に正規化する。
+
+`detail` は採用 target、計測値、peak guard 適用有無、クランプ有無を保持する。
+
+## 5. 役割判定
+
+v2 の明示 `role` が narration / bgm / jingle / music / ambience なら最優先し、そのまま使う。
+それ以外（sfx、未知、未指定）は legacy collection の bgm / narration を優先した後、SFX
+ヒューリスティクスへ進む。パスを小文字化し、`jingle` / `sting` を含めば jingle、
+`ambien` / `room` / `env` を含めば ambience、計測尺が 20 秒以上なら music、それ以外は sfx とする。
+
+## 6. CLI
+
+```text
+akari media audio-level <projectDir> [--write] [--targets '<json>'] [--ceiling <dBTP>] [--json] [--no-cache]
+```
+
+v2 の audio lane items と legacy `audio.bgm` / `audio.sfx[]` / `audio.narration[]` を読み、
+`gain_db` 未指定の項目だけを対象とする。素材パスは edit.json の親ディレクトリ基準。
+dry-run の標準出力は header と 1 クリップ 1 行の表で、path / role / basis / I / TP /
+`gain_db` / `fade_in` / `fade_out` を含む。`--json` は同じ結果の JSON 配列 1 つだけを返す。
+素材不在または計測不能は stderr の warning 1 行でその項目だけを省く。対象 0 件は exit 0。
+
+`--write` は `gain_db` と、未指定の `fade_in` / `fade_out` だけを書く。v2 は Project API の
+item patch、legacy は edit-store の既存書き込み API を使う。保存後に edit-lint を実行し、
+severity `error` が 1 件でもあれば退避した edit.json 全文を戻す。成功後の再実行は対象 0 件で
+あり、冪等である。
+
+legacy 形（version 0/1）は現行 edit-lint が「古い形式」として error にするため、`--write` は
+常に巻き戻される（dry-run / `--json` は利用できる）。書き込む場合は `akari migrate` で v2 にしてから実行する。
+
+## 7. 次段
+
+設定（`audio.level_targets` / アプリ設定）と shell 挿入フックは S2 / 別票とする。
+本契約では schema、設定画面、実行時追従、shell UI を追加しない。

package/vendor/docs/contract-2026-09-02-item-caption-anchor-v0.md

@@ -69,9 +69,15 @@ duration(own) = item.duration
 `resolveItemAnchors` を通してから内部モデルを構築する。渡されない場合は `at` / `duration` の
 キャッシュを従来どおり読み、アンカー導入前の挙動を変えない。
 
-本契約では render-cut / gpu / osr / shell preview / preview-server の呼び出しへ
-`options.captions` を配線しない。各出口はキャッシュを読むだけで同じ時刻を見る。字幕を書き換える側が
-保存前にアンカーを再解決する責務を持ち、この自動配線は T7b で行う。
+render-cut / gpu / osr / shell preview / preview-server の各出口は、captions.json を
+`toAnchorCaptions` で正規化して `readInternalEdit` の `options.captions` へ渡し、読込時にアンカーを
+再解決する。captions.json が無い場合は従来どおり `at` / `duration` のキャッシュを読む。
+
+字幕の時刻・参照集合を変える `setCaptionTiming` / `shiftCaption` / `insertCaption` /
+`removeCaption` は、captions.json の書き込み後に `refreshItemAnchors` でキャッシュを更新する。
+`writeEditSnapshot` と preview-server の captions PUT は呼び出し側が再解決の責務を持つ。
+captions.json と edit.json の 2 ファイル間に原子性はなく、途中で停止してキャッシュが古くなった場合は
+lint `v2.item-anchor-stale` が検出する。
 
 ## 4. mutation
 
@@ -94,8 +100,6 @@ duration(own) = item.duration
 ## 6. 非スコープ
 
 - 台本パネルの単語範囲ドラッグ、🎬 ボタンその他の UI
-- annotations の RPC / mutation wrapper
-- 出口側への `options.captions` 配線と字幕保存時の自動再解決
 - `itemAtV2` の string 拡張
 - 単語 index アンカー
 - `captions` / `caption` item へのアンカー

package/vendor/docs/contract-2026-09-02-transcript-unrecognized-spans-v0.md

@@ -55,3 +55,24 @@ schema と validator は配列、要素の exact keys、有限・非負の `star
 
 confidence、低確信の認識語を示すマーカー、未認識区間の自動置換・自動カットは本契約に含めない。
 SpeechAnalyzer や cloud バックエンド固有の非発話マーカー解釈も追加せず、語間隙からの検出だけを共通適用する。
+
+## 7. パネル側の約束（T5b）
+
+台本パネルは各未認識区間を `??` 固定で時刻順に表示する。表示位置は `span.start >= words[i].end` を
+満たす最後の語の直後とし、該当語が無ければ行頭、最後の語より後なら行末へ置く。`words[]` が無い行では
+本文の末尾へ並べる。`??` は字幕語やカラオケの語 index には含めない。
+
+聞き取った文字への置換は、`setCaptionFields` の `text` と `unrecognized` を 1 回の書き戻しで更新する。
+本文では `??` の直前にある語の直後へ文字を挿入し、対象区間だけを `unrecognized[]` から除く。新しい語の
+時刻は共通カーネル `rederiveCaptionWords` が前後の保持語の間へ配分し、既存の他語は変更しない。
+
+映像ごとのカットは対象の `[start, end]` をパディングせず、`kind: 'unrecognized'` として
+`applyCutRanges` へ渡す。カット成功後に対象区間を `unrecognized[]` から除き、字幕側の更新に失敗した場合は
+カット前の edit.json を復元する。
+
+文字起こしタブの再生成直列化器と edit-store の `insertCaptionLine` 直列化器は、どちらも非空の
+`unrecognized[]` を保全する。再生成では `edited: true` の行と対応 segment が無い行の既存値をそのまま保ち、
+`edited: false` の再生成行と新規行は analysis segment の区間を字幕の `[start, end]` へミリ秒単位で
+切り詰め、時刻順に並べて隣接・重複区間を結合して持ち越す。空になった配列は書かない。
+
+低確信の認識語を示すマーカー、1 個の `?`、および `???` の使い分けは T5b の非スコープとする。