外掛安裝： 在執行設定或更新命令之前，當此技能位於 HyperFrames 外掛中時，請遵循外掛執行規則。獨立安裝請保留下方的更新說明。

首先，保持此技能為最新狀態 — 在使用前請與使用者確認後再執行： npx hyperframes skills update embedded-captions。如果一切已是最新，則執行快速且無操作；否則它會更新此技能及其依賴的核心領域技能。

嵌入式字幕是做什麼的？

一個目錄，預先選取（CATALOG.md — 35 種身分；其背後的引擎是後端細節）。標準（預設）建立一個乾淨的逐字軌道（承載大部分文字的下方三分之一字幕）+ 一個在關鍵時刻複合到主體後方場景中的嵌入高潮。電影感則是純嵌入 — 沒有軌道，每個字幕都複合在主體後方（英雄排版、累積、遮蔽作為效果）。主題是一個完整的主題化構成 — 主體典範 × 英雄主打 × 前景特效 × 幀面反應，從註冊表中組成（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]

保留專案的鎖定檔案。如果這些依賴項已存在，則使用其鎖定的版本，而不是覆蓋它們。Bash 和 FFmpeg/ffprobe 必須在 PATH 上。去背和轉錄可能在下載其自身模型後才可使用。

渲染會等待 CLI 成功退出後再進行合成。舊的 HF_TIMEOUT_S shell 監視器不再使用：大的部分檔案並不能證明渲染已完成。一個明確的內建檢出參數或 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>（平行進行去背 ∥ 轉錄 ∥ 音訊包絡，然後使用場景色板/光學/光線進行安全區域 v2 — 一個命令，無遺漏）
編寫一個小的創意選擇 JSON（先閱讀 safe-zones.json）：電影感 → cinematic.json → make-cinematic.cjs（推導出 plan.json 並編譯它）；主題 → theme.json → make-theme.cjs（軌道/面板/詩句/接管典範；anchor 是安靜的軌道預設）
視覺 QA：node scripts/preview-frames.cjs <project> → 約 2秒/幀的忠實合成預覽（無需渲染）。在付費渲染前檢查 § 視覺 QA。
render-and-composite.sh → 閘門（時序 / 遮蔽+英雄 / 溢出 / 交接）→ final.mp4

人們常遺漏的承載規則：

軌道（預設）+ 嵌入（提升）。 drop（填充詞，不顯示）/ rail（逐字下方三分之一字幕，在前景，承載大部分文字）/ embed（一個峰值詞語複合在主體後方）。標準模式同時執行兩者，僅嵌入亮點。參見 § 字幕模型。
影片以「未經處理」的方式交付（標準/電影感；主題模式的幀面預算是唯一獲准的例外 — 按每個主題 DNA 定義的、經註冊表閘控的反應節拍（充電-變暗、衝擊、搖晃、顆粒）在遮罩合成之後應用，使主體+文字+幀面作為一幀移動） — 字幕是唯一添加的東西；遮罩只是讓主體遮蔽嵌入軌道。永遠不要對素材進行調色/重新著色/掃描線。
兩本規則書：軌道 → references/rail.md（簡短），嵌入工藝 → references/composition-craft.md（豐富，僅嵌入）。按需瀏覽。

字幕模型 — 軌道 + 嵌入

每個口頭短語是以下三種之一：

	是什麼	如何顯示
drop	填充詞 — 呃/嗯、結巴、自我修正	不顯示
rail	預設 — 一般口頭內容（逐字）	乾淨的下方三分之一字幕，在前景，可讀。一個關鍵字可以獲得內聯 `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 中的「縮減候選啟發法」 — 它們是身分層級的（例如，「炸」會縮小到 ordnance/stomp/terminal/loud 並根據什麼應該爆炸來選擇），絕不是類別層級。不確定 → anchor。

電影感 → 為一個鎖定模板編寫 cinematic.json，由 make-cinematic.cjs 編譯。
主題 → 閱讀 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% 處

閱讀範例。在以下情況拒絕：

多個說話者 / 硬切接（分割並渲染每個鏡頭，或拒絕）
沒有人類主體（此技能適用於談話頭）
少於 3 秒，沒有語音，或面部從未清晰可見 — transcribe.cjs 會在音訊接近靜音時發出警告（Whisper 會在靜音上憑空想像出像「謝謝你。」這樣的詞語）；注意它並拒絕，而不是為虛構的詞語加上字幕
來源已經有燒錄的字幕 / 旁白 / 大量文字圖形 — 添加第二個字幕系統會衝突，且素材原封不動地交付（無法覆蓋/修復）。燒錄的文字通常只在剪輯中間出現：請取樣一個 1fps 的聯繫表（ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png），不要相信 3 個定點幀。
轉錄稿是垃圾 — 非母語/重口音語音可能被轉錄成自信的亂碼。在編寫前理智地閱讀 transcript.json；如果它不能被解析為語言，請嘗試 WHISPER_MODEL=medium 一次，否則拒絕（一個虛構詞語的逐字軌道比沒有字幕更糟）。
忙碌的手持拍攝且快速移動（遮罩閃爍）

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

鏡頭切探測。 在 20%、50%、80% 處取樣幀。如果出現不同的主體/場景，在切接之前裁剪剪輯。
信箱/立柱信箱探測。 第一幀有黑邊？計算安全內容矩形並將字幕放置限制在其中。
亮度探測。 取樣字幕區域的平均亮度 — 低於 60 → 淺色文字直接可讀，60-180 → 添加字形遮罩，180+ → 不透明文字 + 遮罩（絕不要裸露的淺色文字）。電影感模板是奶油色+螢幕 且被鎖定 — 使用此探測來_選擇一個合適的身分_（明亮場景 → 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.json → node scripts/make-cinematic.cjs <project>
   主題：     編寫 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 — 電影感模式（純嵌入）

先閱讀 safe-zones.json。 旁白平面進入 zones.hugLeft/hugRight — 緊貼輪廓的乾淨條帶（遠離身體的文字讀起來像浮動的，而不是嵌入的；遠角是備用方案，不是預設值）。英雄預設為 heroAnchor/heroBands.best（居中在主體上，約 30-55% 遮蔽）。recommendation:"fg" 將旁白移到前景以提高可讀性；只要 heroBands.feasible，英雄就保持在嵌入狀態 — 英雄-前景是最後的手段。
DNA 是您在步驟 0 選擇的身分。

嵌入式字幕