akari-video 0.1.33 → 0.1.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "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/src/cli.mjs

@@ -24,6 +24,7 @@ import {
 import { applySelfUpdate, isRunningFromAppDir, rollbackSelfUpdate } from './self-update.mjs';
 import { runCaptureCommand } from './capture-command.mjs';
 import { runMediaCommand } from './media-command.mjs';
+import { runWordBookCommand } from './word-book-command.mjs';
 import { resolveRuntimePaths } from './runtime-diagnostics.mjs';
 
 /**
@@ -44,6 +45,7 @@ export async function run(args, options = {}) {
   }
   if (args[0] === 'capture') return runCaptureCommand(args.slice(1), options);
   if (args[0] === 'media') return runMediaCommand(args.slice(1), options);
+  if (args[0] === 'word-book') return runWordBookCommand(args.slice(1), options);
 
   const log = options.log ?? ((line) => console.log(line));
   const assets = options.assets ?? resolveLauncherAssets();

package/src/repo-assets.mjs

@@ -55,6 +55,7 @@ export function resolveRepoAssets(repoRoot = DEFAULT_REPO_ROOT_CANDIDATE) {
   const renderWhenIdleScript = path.join(repoRoot, RENDER_WHEN_IDLE_SCRIPT_RELATIVE);
   const eyeBarScript = path.join(repoRoot, EYE_BAR_SCRIPT_RELATIVE);
   const mediaScript = path.join(repoRoot, 'packages', 'akari-tools', 'bin', 'media.mjs');
+  const wordBookScript = path.join(repoRoot, 'packages', 'akari-tools', 'bin', 'word-book.mjs');
 
   return {
     repoRoot,
@@ -71,7 +72,8 @@ export function resolveRepoAssets(repoRoot = DEFAULT_REPO_ROOT_CANDIDATE) {
     captureScript: existsSync(path.join(repoRoot, CAPTURE_SCRIPT_RELATIVE)) ? path.join(repoRoot, CAPTURE_SCRIPT_RELATIVE) : null,
     renderWhenIdleScript: existsSync(renderWhenIdleScript) ? renderWhenIdleScript : null,
     eyeBarScript: existsSync(eyeBarScript) ? eyeBarScript : null,
-    mediaScript: existsSync(mediaScript) ? mediaScript : null
+    mediaScript: existsSync(mediaScript) ? mediaScript : null,
+    ...(existsSync(wordBookScript) ? { wordBookScript } : {})
   };
 }
 
@@ -105,6 +107,9 @@ export function resolveLauncherAssets({
     ...(candidate.captureScript ?? vendor.captureScript ? { captureScript: candidate.captureScript ?? vendor.captureScript } : {}),
     renderWhenIdleScript: candidate.renderWhenIdleScript ?? vendor.renderWhenIdleScript,
     eyeBarScript: candidate.eyeBarScript ?? vendor.eyeBarScript,
-    mediaScript: candidate.mediaScript ?? vendor.mediaScript
+    mediaScript: candidate.mediaScript ?? vendor.mediaScript,
+    ...(candidate.wordBookScript ?? vendor.wordBookScript
+      ? { wordBookScript: candidate.wordBookScript ?? vendor.wordBookScript }
+      : {})
   };
 }

package/src/word-book-command.mjs

@@ -0,0 +1,16 @@
+import { spawnSync } from "node:child_process";
+
+import { resolveLauncherAssets } from "./repo-assets.mjs";
+
+export async function runWordBookCommand(args, options = {}) {
+  const logError = options.logError ?? ((line) => console.error(line));
+  const assets = options.assets ?? resolveLauncherAssets();
+  const spawn = options.spawn ?? spawnSync;
+  if (!assets.wordBookScript) {
+    logError("akari word-book の実行スクリプトが見つかりません。完全な AKARI Video を再導入してください:");
+    logError("  npm install -g akari-video");
+    return { exitCode: 1 };
+  }
+  const result = spawn(process.execPath, [assets.wordBookScript, ...args], { stdio: "inherit" });
+  return { exitCode: typeof result?.status === "number" ? result.status : 1 };
+}

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

@@ -51,10 +51,16 @@
     "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-asset-reference-model.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-shape-item-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 +94,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 +108,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-07-22-render-basics.md

@@ -73,6 +73,7 @@
 ### 4-1. 画角（`cuts[].framing`）
 
 - **crop と keyframes の併存**: 両方宣言された場合は `keyframes` を優先する。`crop` は「1 点ズームの縮退形」であり、両立させる意味論が無いため（複製 drift の温床にもなる）
+- **幾何の基準（2026-09-02 追記・相互参照）**: `output.geometry` は未指定 = fit 互換 / `"source"` = 実寸基準を表すマーカーで、正本は `docs/contract-2026-08-02-preview-parity.md` §2.2（G1 は描画無変更・framing の再定義は G2）。
 - **scale < 1 の扱い**: `keyframes[].scale` は仕組み上「クロップ窓を縮めて拡大する」ため 1 未満（キャンバスの外まで見せる＝リビール）は原理的に表現できない。レンダ側で `max(1, scale)` にクランプする（silent drop ではなく仕組み上の上限として契約に明記）
 - **crop.w/h が init 一度しか評価されない**: ffmpeg の `crop` フィルタは `x`/`y` は `t` を使った毎フレーム再評価に対応するが、`w`/`h` は（この ffmpeg ビルドで）フィルタ初期化時の一度きりの評価に固定されており `eval` オプション自体が存在しない（実機検証: `t` を含む `w`/`h` 式は `crop=... w='...t...'` で `Error when evaluating the expression` を返す）。そのため実装は「`scale` を `eval=frame` で `width*scale(t) : height*scale(t)` に広げてから固定サイズ `width:height` で `crop` する」方式を採る（クロップ窓の拡大 = `scale` 側の時間関数、パン位置 = `crop` の `x`/`y` の時間関数、という役割分担）
 - **`crop` の `x`/`y` は上流フレームの実サイズを見ない**: 同フィルタの `iw`/`ih` 定数は（動的サイズの上流から来ていても）negotiate 済みの固定リンクサイズを指し、最初のフレームのサイズに固定されたままになることを実機検証で確認した。そのため `crop` の `x`/`y` 式は `iw`/`ih` を参照せず、`scale` 側と同じ `scale(t)` 式をそのまま再計算する（対称的だが唯一 crop から見て正しい現在値）

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. 役割分担
 
@@ -69,6 +70,13 @@ cut 境界の選択は宣言順ではなく解決済みタイムラインと z-o
   `cut <id>: perspective is not applied by the frame-engine base path yet (issue #39)` を warning に出す（無警告で捨てない）。
 - `freeze = {at_sec, duration_sec}` は指定 frame を保持し、cut の出力尺を `duration_sec` だけ伸ばして
   後続の逐次 cut を移動する。freeze の画と独立音声予定表を混同しない。
+- **`output.geometry`（幾何の基準。2026-09-02 追記）**: 未指定 = **fit 互換**（cut は出力へ contain fit した後に
+  transform。上記の従来どおり）、`"source"` = **実寸基準**（ソース実寸 × scale の box。layer・layer-style cut と同じ幾何）。
+  語彙は `"source"` の 1 つだけで、マーカーが立つのは「今 fit 基準で描かれている全 media item に `scale × fit`
+  （`fit = min(outputW / srcW, outputH / srcH)`・srcW / srcH は表示回転後）を一度だけ焼き込んだ」ことを意味する
+  （部分適用は禁止。移行は `packages/edit-store/bin/normalize-geometry.mjs`）。x / y / rotate は両基準で同じ意味なので触らない。
+  **G1（マーカー・移行・lint の warning `geometry.fit-compat`）ではエンジンはこのマーカーを読まず、描画は 1 バイトも変わらない。
+  描画へ反映するのは G2**。cross ref: `docs/contract-2026-07-22-render-basics.md` §4-1（#6 画角操作）。
 
 **検収:** framing / transform / opacity / freeze を含む base parity **28 点**、freeze をまたぐ
 frame lifetime **1000 コマ**、故意の **1 px** 差分を必ず FAIL させる否定点で判定する。
@@ -128,6 +136,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 +175,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 のみ |
@@ -269,6 +284,11 @@ lint 実行系が見つからない場合は **fail-open**（2026-08-02 オー
 保存を続行する。書き込みは tmp ファイルへの出力と rename による atomic 更新とする。実装は
 `packages/edit-store` に一本化し、器や入口ごとの独自書き込み実装を追加してはならない。
 
+本編 cut の `crop` 書き戻し（選択枠の辺バー）は **edit.json version 2 の文書だけ**が対象で、legacy の
+`cuts[]` schema には席が無いため読み込み層が拒否する。`output.geometry` を宣言していない文書では、crop の
+無い cut は出力キャンバスへ contain fit されて描かれるので、**初回の crop と同一 patch で `transform.scale`
+へ fit 係数を焼き込む**（ソース実寸基準の layer-style へ移っても画面上の位置・大きさが変わらないため）。
+
 ### 5.4 ペン
 
 ペン描画の単一正本は `packages/pen-visuals` の `PEN_TUNING` と描画プリミティブである。器や overlay

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-asset-reference-model.md

@@ -0,0 +1,57 @@
+# contract — 素材の参照モデル v0（共有ライブラリ参照の台帳と解決規則）
+
+- 状態: 実装済み（機械層のみ。シェル UI の採用は後続）
+- 決定日: 2026-09-02
+- 実装: `packages/asset-resolver`（記帳・実体化）/ `packages/render-cut`・`packages/edit-lint`（解決）
+
+## 1. 目的
+
+カタログ素材をプロジェクトごとに実体コピーすると、同じ素材が何度もダウンロード・複製されて
+プロジェクトが肥大する。実体は**マシン単位の共有ライブラリ**（`~/.akari/assets/<category>/<id>/`）に
+1 部だけ置き、プロジェクトには**参照だけを記録**できるようにする。
+
+## 2. 設計の要点
+
+- **edit.json は変えない**。参照素材も従来どおり `assets/<category>/<id>/<file>` の
+  プロジェクト相対パスで宣言される。実体がプロジェクトに無いことは参照台帳が説明する。
+- 参照台帳 = プロジェクトの `.akari/asset-references.json`:
+
+  ```json
+  { "version": 0, "references": [ { "id": "<素材 id>", "category": "<カテゴリ>" } ] }
+  ```
+
+  references は category → id の安定ソート・重複なし。読み手は寛容（無い / 壊れは空扱い）、
+  書き込みは tmp + rename の原子的更新。`version` は台帳自身のスキーマ版数であり
+  edit.json の version とは無関係。
+- **解決規則**: 宣言されたプロジェクト相対パスが `assets/<category>/<id>/<rest>` の形で、
+  (1) プロジェクト実体が存在せず、(2) 台帳に `{category, id}` があるとき、
+  `<AKARI_HOME>/assets/<category>/<id>/<rest>`（AKARI_HOME 既定 `~/.akari`・env で上書き可）へ
+  フォールバックする。解決先は realpath 後も `<AKARI_HOME>/assets` 配下に収まる正規ファイルで
+  あること（`..` 等の脱出は fail-closed で拒否）。
+- render-cut は解決した入力を render inputs 記録に `scope: "library"` として残す
+  （既存 `scope: "akari"` と同列の additive 記録）。edit-lint は解決できる参照を欠落と報告せず、
+  台帳にあるが実体が無い参照は「共有ライブラリ参照（未取得）」として欠落報告する。
+- render-cut / edit-lint は依存ゼロ CLI のため、解決ロジックは各パッケージ内に**同一実装を重複**して
+  持つ（`src/library-reference.mjs`）。挙動同一性は両テストの同一ケース表で担保する。
+
+## 3. 使い方（CLI）
+
+```sh
+# 参照モードで取得（コピーせず台帳へ記帳。既定は従来どおりコピー）
+akari-assets fetch <id> --project <dir> --reference
+
+# 「素材をまとめる」— 参照の実体化（持ち出し・アーカイブ用）
+akari-assets bundle --project <dir> [--dry-run]
+```
+
+bundle は台帳の各参照をキャッシュから `assets/<category>/<id>/` へ実体化して台帳から除去する。
+未取得の参照は resolve（取得）を試み、取得できないものは台帳に残して部分成功（exit 非 0）で報告する。冪等。
+
+## 4. スコープ外（後続）
+
+- シェル UI の採用（取り込みフローの reference 既定化・プロジェクト面の「参照」バッジ・
+  プレビュー経路のフォールバック）
+- 共有キャッシュの容量管理 UI
+
+出自: 2026-09-02 の素材パネル再設計ラウンドの裁定 3（実体 = 共有キャッシュ・プロジェクトには参照・
+持ち出しは「素材をまとめる」で閉じる）。

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 を追加しない。