外掛安裝: 在執行設定或更新命令之前,如果此技能位於 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(它單獨獲得完整的鎖定嵌入 + 寬度適合提升);較小的則是次要亮點,它們在自己的欄位中以特大的強調線(前景,阻尼運動)形式運作 — 並非每個節拍都需要遮罩展示,這正是讓頂點成為一個事件的原因。嵌入每個詞仍然是常見錯誤。
軌道表面身份正是這樣建構的(軌道 = 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. [AI 代理步驟 — 唯一創意步驟] 編寫一個小的 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 選擇的身份。
make-cinematic.cjs會從cinematic.json中查找身份 DNA,並相應地編譯plan.json。
...(以下為截斷內容)