外掛安裝: 在執行設定或更新命令前,當此技能位於 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]
保留專案的 lockfile。如果這些依賴已存在,則使用其鎖定的版本,而不是覆蓋它們。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(合成在主體背後的巔峰詞彙)。標準模式兩者都做,僅嵌入巔峰。請參閱 § 字幕模型。 - 影片以「未經修改」的狀態交付(標準/電影級;主題模式的 PLATE 預算是唯一的例外 — 由註冊表閘控的反應拍(charge-dim、punch、shake、grain)根據每個主題的 DNA 定義,並在去背合成後應用,使主體+文字+底板作為一個框架移動) — 只添加字幕;去背只是為了讓主體遮擋嵌入軌道。切勿對素材進行調色/重新上色/掃描線處理。
- 兩本規則書:軌道 → references/rail.md(簡潔),嵌入工藝 → references/composition-craft.md(豐富,僅嵌入)。根據需求瀏覽。
字幕模型 — 軌道 + 嵌入
每個口語短語都是以下三種之一:
| 什麼 | 如何顯示 | |
|---|---|---|
| drop | 填充詞 — 嗯/呃、口吃、自我修正 | 不顯示 |
| rail | 預設 — 一般口語內容(逐字) | 乾淨的下方三分之一字幕,在前景,可讀。一個重點詞可以獲得內聯的 emphasis 高亮(強調色 / 動態詞彈出)— 它仍保留在軌道上。 |
| embed | 一個被升級的巔峰 — 標題性的節拍 | 一個大字合成在主體背後(去背遮擋),設計入場 + 出場 |
軌道承載大部分文字;嵌入是稀缺且應得的巔峰。 稀缺性是每個節拍/區塊,而非每個片段:每個區塊 ≤1 個英雄(想法),永不兩個同時可見,英雄窗口之間至少有一個節拍的間隔(編譯器會對低於 0.6 秒的間隔發出警告)。一個短片段 → 通常 1–2 個;一個長的說明 → 大約每個章節一個。在多個英雄中,最大的一個是 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 可能會在靜音上幻覺出像「Thank you.」這樣的詞);請注意並拒絕,而不是為虛構的文字加上字幕 - 來源已帶有內嵌字幕 / 說明文字 / 厚重的文字圖形 — 加上第二個字幕系統會造成衝突,且素材必須保持未經修改(無法遮蓋/修復)。燒錄的文字通常只在片段中間出現:取樣一個 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 中選取的識別
…
[已截斷以利翻譯]