外掛程式安裝： 在執行設定或更新命令前，若此技能位於 HyperFrames 外掛程式內，請遵循外掛程式執行規則。獨立安裝則保留以下更新說明。
首先，保持此技能最新 — 請在使用前與使用者確認後執行：
npx hyperframes skills update embedded-captions。若一切已是最新，則快速無操作；否則它會更新此技能及其依賴的核心領域技能。
嵌入式字幕
一個目錄，事先選定（CATALOG.md — 35 種身份；背後的引擎是後端細節）。標準（預設）會建立一個乾淨的逐字軌道（承載大部分文字的底部第三字幕）+ 一個在關鍵時刻合成到場景中、主體後方的嵌入高潮。電影感是純嵌入 — 沒有軌道，每個字幕都合成在主體後方（字體突出、堆疊、遮蔽效果）。主題是完整的風格化構成 — 主體範式 × 英雄場景 × 前端特效 × 底板反應，從註冊表中組合（themes/README.md）：ordnance terminal neonsign stardust stomp。大部分解說/旁白是標準；嵌入是稀缺的、應得的亮點 — 嵌入每個字是常見錯誤；主題適用於 VFX 等級的要求（「炸」、「特效」、「像 AE 做的」）。
執行環境需求
外掛程式安裝使用捆綁的、清單固定版本的 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/終端機正常取消停滯的渲染；字幕輔助工具不會強制終止或從程序快照恢復渲染。
操作流程（簡而言之）
透過 /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（合成在主體後方的重點詞）。標準模式兩者皆做，僅嵌入亮點。請參閱 § 字幕模型。 - 影片以未經編輯的狀態交付（標準/電影感；主題模式的 PLATE 預算是唯一批准的例外 — 註冊表控管的反應節拍（充電變暗、衝擊、搖晃、顆粒）根據每個主題 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+→ 不透明文字 + 遮罩（絕不單獨使用亮色文字）。電影感模板是奶油色 +screen且鎖定 — 使用此探查來_選擇合適的身份_（亮場景 →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 中選取的身份
…[為翻譯而截斷]