外掛安裝： 在執行設定或更新命令前，當此技能位於 HyperFrames 外掛內時，請遵循外掛執行規則。獨立安裝則保留下列更新說明。
首先，保持此技能最新 — 先與使用者確認再執行：
npx hyperframes skills update embedded-captions。當一切為最新時會快速無操作；否則它會先更新此技能及其依賴的核心領域技能，然後您才能依賴它們。
嵌入式字幕 (Embedded Captions)
單一目錄，預先選定 (CATALOG.md — 35 種身分；其背後的引擎屬於後端細節)。標準 (Standard)（預設）建立一個乾淨的逐字軌道（承載大部分文字的 lower-third 字幕） + 一個內嵌高潮，在高峰時刻合成到主體_後方_的場景中。電影級 (Cinematic) 是純內嵌 — 無軌道，每個字幕合成在主體後方（英雄級排版、累積、遮擋作為效果）。主題 (Theme) 是完整的題材構成 — 主體典範 × 英雄級場景 × 前景效果 × 介面反應，由註冊表組合而成（參見 themes/README.md）：ordnance terminal neonsign stardust stomp。大多數解說 / 旁白使用標準；內嵌是稀缺、值得的巔峰 — 每個字都內嵌是常見錯誤；主題則用於 VFX 級的要求（「炸」、「特效」、「像 AE 做的」）。
執行時先決條件
外掛安裝使用捆綁的、manifest 鎖定的 CLI 來進行遮罩、轉錄和渲染；無需檢出原始碼。本機預覽和字幕測量輔助程式還需要 Sharp、Puppeteer（及其 Chromium 瀏覽器）和 GSAP。將這些安裝在字幕專案中，不要安裝在唯讀的外掛內：
npm install --prefix <project> --save-dev --save-exact [email protected] [email protected] [email protected]
保留專案的 lockfile。如果這些依賴項已存在，請使用其鎖定的版本而非覆蓋它們。Bash 和 FFmpeg/ffprobe 必須在 PATH 中。遮罩和轉錄可能會在首次使用時下載它們自己的模型。
渲染會等待 CLI 成功退出後再進行合成。舊的 HF_TIMEOUT_S shell 看門狗不再使用：一個大的部分檔案並不能證明渲染完成。使用明確的 built-checkout 參數或 HYPERFRAMES_ROOT 來選擇貢獻者 CLI 而非外掛鎖定。正常透過 CLI/終端機取消停滯的渲染；字幕輔助程式不會從進程快照強制終止或恢復渲染。
操作流程 (TL;DR)
透過 /hyperframes 路由，意圖層僅確認輸入（哪個片段）並宣布身分選擇作為延遲詢問 — 候選清單需要探測過的片段，因此它停留在下面的步驟 1；該層的運行形狀問題不適用（素材未經處理，沒有分鏡表需要審查）。當存在 BRIEF.md 時，它會攜帶已確認的輸入和使用者註記 — 請先閱讀它。
下面的工藝散文很長；管線本身很短 — 所有確定性的事物都是計算或編譯的，絕非手寫：
- 決策閘門（拒絕不良片段） → 從 CATALOG.md 中選擇一個身分（35 種身分；引擎/編譯器透過查表推導 — 絕不提出模式/類別的問題）
hyperframes init（如果專案目錄已存在且影片在裡面則跳過 —matte.cjs/transcribe.cjs會將目錄中的任何影片作為 source.mp4） →bash scripts/prepare.sh <project>（遮罩 ∥ 轉錄 ∥ 音訊包絡平行執行，然後是 safe-zones v2 搭配場景調色板/光學/照明 — 一個命令，無遺漏）- 撰寫一個小的創意選擇 JSON（先讀取
safe-zones.json）：Cinematic →cinematic.json→make-cinematic.cjs（推導plan.json並編譯它）；Theme →theme.json→make-theme.cjs（rail/panel/poem/takeover 典範；anchor是低調的軌道預設值） - 視覺 QA：
node scripts/preview-frames.cjs <project>→ 約 2 秒/幀的忠實合成預覽（無需渲染）。在支付渲染費用前檢查 § 視覺 QA。 render-and-composite.sh→ 閘門（時間/遮擋+英雄/溢位/交接） →final.mp4
人們會遺漏的承載規則：
- 軌道 (rail)（預設）+ 內嵌 (embed)（晉升）。
drop（填充詞，不顯示） /rail（逐字的 lower-third 字幕，在前景，承載大部分文字） /embed（合成在主體後方的峰值詞）。標準模式兩者都做，僅內嵌高峰。參見 § 字幕模型。 - 影片以 UNTOUCHED（未經處理）狀態交付（標準/電影級；主題模式的 PLATE 預算是唯一允許的例外 — 每個主題 DNA 定義的、由註冊表控制的反應拍（充電變暗、衝擊、震動、顆粒）在遮罩合成後應用，使主體+文字+介面作為一個畫面移動） — 僅添加字幕；遮罩只是讓主體遮擋內嵌軌道。切勿對素材進行調色/重新著色/掃描線處理。
- 兩本規則書：軌道 → references/rail.md（簡潔），內嵌工藝 → references/composition-craft.md（豐富，僅內嵌）。按需閱讀。
字幕模型 — 軌道 + 內嵌
每個口語短語是以下三種情況之一：
| 內容 | 顯示方式 | |
|---|---|---|
| drop | 填充詞 — 嗯/呃、口吃、自我修正 | 不顯示 |
| rail | 預設 — 一般口語內容（逐字） | 乾淨的 lower-third 字幕，在前景，可讀。一個關鍵字可以獲得內聯 emphasis 高亮（強調色 / 活動詞彈出）— 它仍保留在軌道上。 |
| embed | 晉升的峰值 — 頭條拍 | 一個大字合成在主體後方（遮罩遮擋），有設計的入場和出場 |
軌道承載大部分文字；內嵌是稀缺、值得的巔峰。 稀缺性是按拍/區塊，而非按片段：每個區塊（思想）≤1 個英雄，從不兩個同時可見，英雄視窗之間至少有一個拍的間隔（編譯器在低於 0.6 秒時會警告）。短的片段 → 通常 1–2 個；長的解說 → 大約每個章節一個。在多個英雄中，最大的一個是 APEX（它獨自獲得完整的鎖定內嵌 + 寬度適應提升）；較小的是次要峰值，它們在列中作為超大的強調行（前景，阻尼運動）— 並非每個拍都需要遮罩展示，這正是讓 apex 成為一個事件的原因。逐字內嵌仍然是常見錯誤。
軌道表面身分完全構建這個（軌道 = rail.html，內嵌 = index.html 中的高潮）。列流程身分會放下軌道並使所有內容都成為內嵌風格 — 僅在情緒優先於逐字的情況下推薦它們，切勿用於需要可讀文字的解說 / 旁白（CATALOG.md 中為每個身分編碼了這一點）。
步驟 0 — 從目錄中選擇一個身分
一個前端，三個後端引擎。 使用者從 CATALOG.md 中選擇一個身分（35 個條目：10 個經典 + 25 個主題）；引擎、編譯器和撰寫檔案透過從目錄行中查詢推導。絕不將「標準 vs 電影級 vs 主題」作為問題提出 — 這些是後端名稱（一個產品即使有多個引擎也有一個 UX）。目錄編碼了路由所需的一切：閱讀表面、語氣、推薦對象、場景需求、真正相近配對的鄰近註記（loud↔ordnance, neon↔neonsign, cream↔stardust）。
身分選擇是一個偏好閘門（../hyperframes/references/brief-contract.md § 1）：在自主模式下（「讓我很驚喜」/「幫我決定」），自行從你的候選清單中選擇並說明單行原因，而不是提問。
程序：探測片段 → 從目錄中選出 2–3 個身分 → 推薦一個並附上單行原因 → 由使用者選擇（自主模式：你選擇，說明原因） → 撰寫該身分的檔案。身分與引擎鎖定（無交叉組合；開啟一個是驗證事件 — 參見 dna/README.md）。
在您撰寫之前，始終提出您的推薦並讓使用者選擇。 不要默默使用預設值。
（完整的身分表位於 CATALOG.md — 路由的唯一真實來源。下面的引擎文件描述了每個後端的撰寫合約。）
CATALOG.md 是這裡的完整答案空間：此工作流程不搜尋 HyperFrames 元件註冊表。 合成工作流程在撰寫命名外觀之前會執行 npx hyperframes catalog；這個則不能。它的引擎是鎖定的編譯器，它們消費 cinematic.json / theme.json 並自行發出合成，因此註冊表項目 — 包括 caption-* 區塊 — 沒有可掛載的地方。註冊表區塊在設計好的畫布上設定文字樣式；此技能透過遮罩將字幕燒錄到某人的素材中。當沒有身分符合要求時，請說明並選擇最接近的，而不是求助於目錄之外。
推薦啟發法：使用 CATALOG.md 中的「Shortlisting heuristics」— 它們是身分層級的（例如「炸」會將 ordnance/stomp/terminal/loud 列入短名單，並根據 WHAT 應該爆炸來選擇），絕不是類別層級。不確定 → anchor。
- Cinematic → 為鎖定的模板撰寫
cinematic.json，由make-cinematic.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% 處
閱讀樣本。在以下情況拒絕：
- 多個說話者 / 硬切（分割並渲染每個鏡頭，或拒絕）
- 無人類主體（此技能專為 talking-head 設計）
- 少於 3 秒，無語音，或臉部從未清晰可見 —
transcribe.cjs在音訊接近靜音時會發出警告（Whisper 可能會在靜音上幻覺出「Thank you.」之類的詞）；注意它並拒絕，而不是為虛構的詞加上字幕 - 來源已包含內嵌字幕 / 隱藏式字幕 / 大量文字圖形 — 添加第二個字幕系統會衝突，且素材以 UNTOUCHED（未經處理）狀態交付（無覆蓋/修補）。內嵌文字通常僅在片段中間出現：抽樣一個 1fps 接觸表（
ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png），不要只相信 3 個點位幀。 - 轉錄稿是垃圾 — 非母語/口音重的語音可能被轉錄成自信的亂碼。在撰寫前理智閱讀
transcript.json；如果它無法解析為語言，可嘗試WHISPER_MODEL=medium一次，否則拒絕（逐字軌道上出現虛構的詞比沒有字幕更糟）。 - 手持晃動且快速移動（遮罩會閃爍）
前期探測（無成本，防止最嚴重的失敗）
- 鏡頭切探測。 在 20%、50%、80% 處抽樣幀。如果出現不同的主體/場景，在切點之前修剪片段。
- Letterbox / pillarbox 探測。 第一幀有黑邊？計算安全的內容矩形並限制字幕放置在其內。
- 亮度探測。 對字幕區域的平均亮度進行抽樣 —
低於 60→ 淺色文字可直接閱讀，60-180→ 添加字形遮罩，180+→ 不透明文字 + 遮罩（切勿使用裸露的淺色文字）。電影級模板是 cream+screen且 LOCKED（鎖定） — 使用此探測來_選擇一個合適的身分_（明亮場景 →ink，或不透明軌道的anchor主題），切勿重新著色其中一個。 - 根據語氣推薦身分（您推薦；使用者選擇 — 參見步驟 0 + CATALOG.md）。 解說 / 訪談 / 必須閱讀的文字 → 軌道/面板表面身分；詩意 / 社交 / 「電影級」 → 按註冊表的列流程身分；「炸 / 特效 / VFX」 / 命名世界 → 主題身分。不確定時 →
anchor（文字可讀，場景安全）— 但提供一個短名單並讓使用者選擇。
管線 — 5 個步驟
1. hyperframes init <project> --non-interactive --video <video.mp4> --skill=embedded-captions
2. bash scripts/prepare.sh <project> # 遮罩 ∥ 轉錄（平行）→ 安全區域。一個命令。
# → frames_fg/ transcript.json safe-zones.json
3. [代理步驟 — 唯一的創意步驟] 根據模式撰寫一個小的 JSON；見下方
Cinematic：撰寫 cinematic.json → node scripts/make-cinematic.cjs <project>
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/ 快照
（主題模式：跳過步驟 3b/5 — render-theme.sh 已經執行編譯 + render-and-composite
+ _postfx.sh；交付物是 final_fx.mp4，final.mp4 是介面反應前的版本）
步驟 1 的 init 會檢查已安裝技能與 GitHub 上的最新版本，並在有任何技能過時時更新全域集合。
步驟 3 因模式而異：
步驟 3 — Cinematic 模式（純內嵌）
- 首先讀取
safe-zones.json。 旁白平面放在zones.hugLeft/hugRight— 緊貼輪廓的乾淨條帶（遠離主體的文字看起來像浮動，而非內嵌；遠角是備用方案，而非預設）。英雄預設為heroAnchor/heroBands.best（居中在主體_上_，約 30–55% 被遮擋）。recommendation:"fg"將旁白移到前景以確保可讀性；只要heroBands.feasible，英雄就保持內嵌 — 英雄前景是最後的手段。 - DNA 是您在步驟 0 中選擇的身分