embedded-captions

Embedded Captions

單一目錄，前期選定 (CATALOG.md — 17 種視覺風格；背後的引擎只是後端實作細節)。Standard（預設）會建立乾淨的逐字軌道字幕 (rail)（位於下三分之一的字幕，承載大部分文字）+ 在高潮時刻合成至場景中、位於主體背後的嵌入字幕 (embed)。Cinematic 則是純嵌入模式 — 沒有軌道字幕，每句字幕都合成在主體背後（聚焦字體視覺、文字累積，並以遮蔽為效果）。Theme 則是完整的主題憲章 — 主體範式 × 亮點展演 (setpiece) × 前景特效 × 背景板反應 (plate reaction)，由註冊表組合而成 (themes/README.md)：ordnance terminal neonsign stardust stomp。大多數解說/旁白影片適合 Standard；嵌入字幕是稀有且精心營造的高潮點 — 每個字都做嵌入是常見的誤用；Theme 則適用於特效級的需求（"炸"、"特效"、"像 AE 做的"）。

---

運作流程 (TL;DR)

雖然下面的工藝說明很長，但流水線本身非常短 — 且所有確定性的步驟都是計算或編譯出來的，絕不手寫：

1. 決策關卡（拒絕不合適的片段）→ 從 CATALOG.md 中選擇一種視覺風格 (identity)（17 種風格；引擎/編譯器透過查表取得 — 絕不向使用者提出模式/類別的選擇問題）
2. hyperframes init（若專案目錄已存在且包含影片則可跳過 — matte.cjs/transcribe.cjs 會自動採用目錄內的任何影片作為 source.mp4）→ bash scripts/prepare.sh <project>（並行執行去背 ∥ 語音轉文字 ∥ 音訊包絡線，接著生成結合場景調色盤/光學/照明的 safe-zones v2 — 單一指令，無一遺漏）
3. 撰寫一份包含創意選擇的小型 JSON（請先閱讀 safe-zones.json）：
   Cinematic → plan.json → fill-timings.cjs → fit-fonts.cjs → make-composition.cjs；
   Theme → theme.json → make-theme.cjs（軌道/面板/詩歌/接管範式；anchor 是安靜的軌道預設值）
4. 視覺 QA：node scripts/preview-frames.cjs <project> → 在約 2 秒/影格內生成忠實的合成預覽（無需正式算圖）。付費算圖前請先確認 § 視覺 QA。
5. render-and-composite.sh → 檢驗關卡（時間軸 / 遮蔽+主標 / 溢出 / 交付）→ final.mp4

大家容易忽略的核心規則：

• 軌道 (rail，預設) + 嵌入 (embed，升格)。 drop（無意義填充詞，不顯示）/ rail（逐字下三分之一字幕，位於前方，承載大部分文字）/ embed（合成在主體背後的高潮關鍵字）。Standard 模式兼具兩者，僅將高潮詞彙進行嵌入。詳見 § 字幕模型。
• 原始影片保持原汁原味未經修改 (Standard/Cinematic 模式；Theme 模式的背景板 (PLATE) 預算為唯一獲准的例外 — 依主題 DNA 定義並在遮罩合成後套用的註冊管制反應節拍（蓄力變暗、擊打、震動、膠片顆粒），使主體+文字+背景板一體聯動）—— 字幕是唯一新增的元素；遮罩僅用於讓主體遮蔽嵌入軌道。絕不可對素材進行調色/重配色/添加掃描線。
• 兩份規則手冊：軌道 → references/rail.md（簡明），嵌入工藝 → references/composition-craft.md（豐富，僅限嵌入）。依需求查閱。

---

字幕模型 — 軌道 + 嵌入

每一句口播內容必為以下三者之一：

	內容	呈現方式
drop	填充詞 — 唔/嗯、口吃、自我修正	不顯示
rail	預設 — 一般口播內容（逐字）	乾淨的下三分之一字幕，位於前方，清晰易讀。強調詞可獲得行內 emphasis 高亮（強調色 / 當前詞彈出）— 仍保持在軌道上。
embed	升格的高潮點 — 頭條節拍	合成在主體背後的大字（遮罩遮蔽），具備精心設計的登場與退場

軌道承載大部分文字；嵌入則是稀有且精心營造的高潮點。 稀缺性是按節拍/區塊（block）計算，而非按影片片段：每個區塊（完整思考）≤1 個主標（hero），絕不同時出現兩個，主標時間視窗之間需保持 ≥ 一拍的空隙（編譯器會在小於 0.6 秒時發出警告）。短片段 → 通常 1–2 個；長解說影片 → 每段約一個。在多個主標中，作者設定的最大字體者為頂峰 (APEX)（唯有它能獲得完整的鎖定組合嵌入 + 寬度適應提升）；較小者為次要高潮 (MINOR)，在其欄位中作為超大強調行（前景、減震運動）呈現 — 並非每個節拍都需要遮罩展示，這正是保持頂峰具有儀式感的原因。將每個字都嵌入依然是常見的錯誤。

軌道介面風格（Rail-surface identities）正是建構此模式（軌道 = rail.html，嵌入 = index.html 中的高潮）。直排流動風格（Column-flow identities）則捨棄軌道，全數採用嵌入風格 — 僅在追求氛圍重於逐字可讀性的需求時推薦，絕不適用於必須清晰閱讀文字的解說/旁白影片（CATALOG.md 中已針對每種風格進行編碼）。

---

Step 0 — 從 CATALOG 中選擇一種視覺風格

單一前端，背後三大引擎。 使用者從 CATALOG.md 選擇一個視覺風格 (IDENTITY)（17 個條目：12 個經典 + 5 個主題）；引擎、編譯器與撰寫檔案皆透過目錄行查表得出。
絕不要把 "Standard vs Cinematic vs Theme" 當成問題提出 — 那些是後端名稱（一個產品即使有多個引擎，也應該只有一種使用者體驗）。目錄中編碼了路由所需的一切：閱讀介面、語調、推薦場景、場景需求，以及極度相似組合的鄰近說明（loud↔ordnance, neon↔neonsign, cream↔stardust）。

流程：探索影片片段 → 從目錄中篩選 2–3 個候選視覺風格 → 附上一句話理由推薦 ONE → 由使用者選擇 → 撰寫該視覺風格的檔案。視覺風格與引擎綁定（不可跨組合混用；開啟新組合屬驗證事件 — 參閱 dna/README.md）。

在撰寫檔案前，務必先提出您的推薦並由使用者選擇。 切勿默默使用預設值。

（完整的視覺風格表格位於 CATALOG.md — 路由的唯一真理來源。下方的引擎文件描述了各後端的撰寫規範。）

推薦啟發式規則：使用 CATALOG.md 中的 "Shortlisting heuristics" — 它們屬於視覺風格層級（例如 "炸" 會把 ordnance/stomp/terminal/loud 列入候選，並根據「什麼東西要爆炸」來挑選），絕非類別層級。不確定時 → anchor。

• Cinematic → 為鎖定範本撰寫 plan.json，由 make-composition.cjs 編譯。
• Theme → 閱讀 themes/README.md，撰寫 theme.json，執行 scripts/render-theme.sh（編譯 + 算圖 + 背景板反應 → final_fx.mp4）。

---

決策關卡 — 優先執行

在任一模式執行前，先探測影片並對場景進行分類。

ffprobe <video.mp4>                    # 規格
ffmpeg -ss <t> -i <video.mp4> -vframes 1 sample.png   # 於 20%/50%/80% 處採樣

檢視採樣畫面。若符合以下情況請拒絕：

• 多個講者 / 硬切鏡頭（分拆並分別算圖各鏡頭，或直接拒絕）
• 無人物主體（本 Skill 專為口播影片設計）
• 短於 3 秒、無語音，或人臉從未清晰可見 — 當音訊接近靜音時 transcribe.cjs 會發出警告（Whisper 會在靜音處憑空幻覺出像 "Thank you." 這樣的字眼）；請聽從警告並拒絕，而非為虛構的字眼製作字幕
• 來源影片已有內嵌/壓制字幕或重度文字圖形 — 疊加第二套字幕系統會產生衝突，素材應保持原狀交付（不進行遮蓋/去字幕處理）。壓制文字常僅在影片中段出現：請採樣 1fps 聯絡單/膠卷圖 (ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png)，不要輕信 3 張單點畫面。
• 逐字稿為垃圾內容 — 非母語/重口音語音可能被轉寫成看似自信的亂碼。撰寫前請先抽查閱讀 transcript.json；若無法解析成正常語言，可嘗試一次 WHISPER_MODEL=medium，否則拒絕（顯示虛構字眼的逐字軌道比沒有字幕更糟糕）。
• 快速移動的混亂手持鏡頭（遮罩會閃爍抖動）

飛前探測（零成本，防止最嚴重的失敗）

1. 分鏡切換探測。 在 20%、50%、80% 處採樣影格。若出現不同的主體/場景，請在剪輯點前裁切片段。
2. 黑邊探測（Letterbox / Pillarbox）。 第一格有黑邊？計算安全內容矩形，並將字幕位置限制在矩形範圍內。
3. 亮度探測。 採樣字幕區域的平均亮度 — 低於 60 → 淺色文字直接可讀，60-180 → 添加字形襯底 scrim，180+ → 不透明文字 + 襯底（絕不使用裸露的淺色文字）。Cinematic 範本為 cream+screen 且為鎖定狀態 — 使用此探測來_挑選合適的視覺風格_（明亮場景 → ink，或不透明軌道的 anchor 主題），絕不要手動重配色。
4. 依語調推薦視覺風格（由您推薦，使用者選擇 — 參閱 Step 0 + CATALOG.md）。 解說 / 訪談 / 必須清晰閱讀的文字 → 軌道/面板介面風格；詩意 / 社群 / "電影感" → 依語域劃分的直排流動風格；"炸 / 特效 / VFX" / 具名世界觀 → 主題風格。不確定時 → anchor（字字可讀，場景安全）— 但仍需提供候選清單供使用者選擇。

---

處理流程 — 5 大步驟

1. hyperframes init <project> --non-interactive --video <video.mp4> --skip-skills
2. bash scripts/prepare.sh <project>       # 去背 ∥ 語音轉文字（並行）→ safe-zones。單一指令。
                                           #   → frames_fg/ transcript.json safe-zones.json
3. [Agent 步驟 — 唯一的創意步驟] 撰寫一份小型 JSON；依模式參閱下方說明
   Cinematic: 撰寫 plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
   Theme:     撰寫 theme.json → bash scripts/render-theme.sh <project>   (編譯 + 算圖 + 背景板特效)
4. node scripts/preview-frames.cjs <project>   # ~2 秒/影格合成預覽 → § 視覺 QA（在算圖前執行）
5. bash scripts/render-and-composite.sh <project>  # 關卡檢驗 → final.mp4 + history/ 快照
   (Theme 模式：跳過步驟 3b/5 — render-theme.sh 已包含編譯 + render-and-composite
    + _postfx.sh；最終交付物為 final_fx.mp4，final.mp4 為背景板反應前版本)

步驟 3 依模式而異：

步驟 3 — Cinematic 模式（純嵌入）

1. 先閱讀 safe-zones.json。 旁白平面放置於 zones.hugLeft/hugRight — 緊貼剪影的乾淨帶狀區域（遠離身體的文字讀起來像懸浮而非嵌入；遠角是備用方案，非預設值）。主標預設為 heroAnchor/heroBands.best（居中於主體上，約 30–55% 遮蔽）。recommendation:"fg" 會將旁白移至前方以利閱讀；**只要 `heroBands.feasi