為影片加字幕
使用者提供一段說話影片。他們從字幕樣式目錄中選擇，目錄中的樣式會預覽在他們自己的影片畫面上，然後您交付含字幕的 MP4。所有操作都在本機使用 HyperFrames 進行，完全不需要 After Effects。
Kit 路徑： 工作室儲存庫內的 .claude/skills/caption-video/kit/。專案建立在 videos/captions/<name>/ 中，完成的影片會輸出到 out/captions/<name>.mp4（兩者皆相對於工作室根目錄）。
從工作室根目錄，設定 K="$PWD/.claude/skills/caption-video/kit" 並執行 python3 "$K/caption.py" …（請加上引號；資料夾名稱可能包含空格）。如果系統的 Python 缺少 numpy/scipy，請使用工作室的虛擬環境 python（.venv/bin/python）——setup/setup.sh 會建立它。
流程
1. 取得影片
如果沒有提供影片路徑，請要求使用者提供。檢查影片是否存在且其中有說話的人。執行：
python3 "$K/caption.py" new "<video path>" <short-name>
這會複製影片、重新編碼為 H.264，並使用 WhisperX 進行逐字轉錄。首次執行可能需要一分鐘。長影片的處理時間約為影片長度的四分之一。
2. 顯示轉錄稿
從命令輸出中，將轉錄稿以易讀的區塊印出。指出任何可能的錯誤，特別是品牌名稱和專業術語（產品名稱、「HyperFrames」、縮寫），並請使用者確認或修正。修正內容在建置時以 --fix "wrong=right,…" 形式加入。如果轉錄稿看起來語無倫次，或音訊中沒有語音，請停止並告知使用者。不要為虛構的詞彙加字幕。
3. 在他們的影片上展示每種樣式
執行 python3 "$K/caption.py" styles 取得樣式列表，執行 python3 "$K/caption.py" preview <name> 取得視覺預覽表。預覽表位於 videos/captions/<name>/previews/styles.png。您自己先查看，然後使用 SendUserFile（以 render 模式顯示）傳送給使用者。在旁邊，提供帶有每種樣式「最適合用途」說明的編號列表：
- Lime Hook：範本外觀（Anton 大寫字母，萊姆綠色說話詞）
- Karaoke Pop：大型雙詞爆發，黃色說話詞
- One Word：一次一個巨型單字
- Clean Box：白色卡片上的深色文字，螢光筆標示說話詞
- Editorial：平靜的句子大小寫，關鍵詞以斜體襯線字體呈現
- Subtitle：小型完整句子字幕
- Neon：說話詞帶青色光芒
根據內容以一行推薦一種樣式：炒作或社交內容 → 1 或 2，解說或廣告 → 4，創辦人故事或高級內容 → 5，訪談或 Podcast → 6，科技或 AI → 7。然後請使用者選擇一個編號。如果 caption.py 中的目錄已變更，請列出 styles 輸出的內容，而非此處的副本。
4. 鉤子（可選）
根據說話者實際說的話，建議 3 個鉤子。以最令人驚訝的數字、結果或矛盾開頭，使用 4–8 個詞，並將重點保留為一個大詞。每個鉤子使用鉤子語法格式化，然後使用 AskUserQuestion 提問：三個鉤子選項加上「無鉤子」（使用者也可以自行輸入）。
鉤子語法的每一行以 | 分隔，每行以其樣式開頭：
s:斜體襯線引言（「How」、「Why」）c:白色緊湊大寫設定b:大而有環繞框的關鍵詞或數字（1–2 個詞）l:萊姆綠大寫轉折r:小型斜體標籤
範例：s:How|c:I reached|b:300k+|l:without ads|r:views。鉤子必須與影片前 10 秒內容一致。
4b. 後製（提供選項；當使用者要求評級、更清晰的音訊、修剪或音樂時執行）
python3 "$K/polish.py" <name> [--grade clean|cinematic|none] [--music calm|none] [--music-level 1.0] [--denoise 100]
- 修剪： 移除第一個詞之前和最後一個詞之後的靜音（分別保留 0.3 秒和 0.9 秒），並相應調整轉錄稿。
- 調色：
clean（預設）提供溫暖健康的膚色、溫和對比與柔和的暗角。cinematic則更深沉、色調更冷。選擇前，先比較每種設定與原始影像的其中一個畫面。 - 語音： DeepFilterNet3 降噪（位於
~/.venvs/dfn，由 setup.sh 建立；請勿全域安裝，它需要 numpy<2），然後是高通濾波、存在感提升、去噝聲和溫和的壓縮。 - 音樂： 合成平靜鋼琴與弦樂墊。音量為 1 時，在停頓處約比語音低 20 dB，說話時約低 25 dB。使用
--music-level 0.6降低音量，或1.5讓音樂更突出。 - 原始檔案會保留為
source_orig.mp4/transcript_orig.json，因此可以隨時以任何設定重新執行後製。後製完成後，再次執行build和render。 - 提及開場中的任何口誤或虛詞開頭（「目前、在這一刻……」）。刪除它們會造成一個小跳接，因此在執行前請先詢問。
5. 建置、檢查、渲染
python3 "$K/caption.py" build <name> --style <key> [--hook "…"] [--hot "word,word"] [--fix "a=b"]
cd "videos/captions/<name>" && npx --yes [email protected] check
python3 "$K/caption.py" render <name>
--hot列出保持在強調色中的詞語。選擇 2–5 個關鍵詞；數字會自動設為熱詞。check中，鉤子淡出時刻的對比度警告是預期的。請在渲染前修正任何真正的錯誤。- 在渲染鉤子之前，先擷取快照（
npx --yes [email protected] snapshot . --at 1.6 --no-end --describe false）並檢查它是否遮擋臉部。當臉部在畫面中位置較高（坐姿或中景）時，使用--hook-y 0.43將鉤子移至胸口位置；陰影會自動跟隨。 - 在傳送前，從
out/captions/<name>.mp4中擷取 3–4 個畫面進行檢查。字幕不得遮蓋嘴巴或眼睛。如果會遮擋，則使用--cap-y重建（數字越大表示字幕越低）。 - 如果影片是橫向拍攝（相機側放，且無旋轉中繼資料），聯絡表中的人物會側躺。首先使用
ffmpeg -vf transpose=2（逆時針旋轉 90 度）或transpose=1（順時針；檢查一個畫面）旋轉，放入videos/_caption-inputs/，然後對該檔案執行new。 - 使用
SendUserFile傳送 MP4，並提供其路徑作為連結。
6. 修改
設定會保存在 videos/captions/<name>/caption.json 中，因此修改只需執行 build <name> --<option> … 然後 render <name>。常見要求：
- 不同樣式：
--style。 - 放大或縮小：
--size 1.2。 - 提高或降低：
--cap-y 0.7。 - 減少每條字幕的字數：
--words 2。 - 不同顏色：
--accent "#FF4D3D"。 - 更改鉤子：
--hook；--hook ""移除鉤子。 - 鉤子長度：
--hook-dur 3.5。
他們也可以自行在 HyperFrames Studio 中開啟，使用 cd videos/captions/<name> && npm run dev。
設定資訊（若出現問題時）
- 轉錄呼叫
~/.claude/skills/embedded-captions/scripts/transcribe.cjs，使用HYPERFRAMES_ROOT=~/.hyperframes-root，並搭配 HyperFrames CLI 0.8.147 安裝（內含packages/cli/dist/cli.js符號連結）。如果其中任一項遺失，請重新安裝：npx hyperframes skills update embedded-captions，然後重建~/.hyperframes-root（npm install[email protected]並將node_modules/hyperframes/dist/cli.js符號連結至packages/cli/dist/cli.js）。 - 字型位於
kit/fonts/（皆為 SIL OFL 授權），並會複製到每個專案中。 setup/doctor.sh會檢查所有元件；setup/setup.sh會進行修復。- 若要讓字幕出現在人物後方，可以使用
/embedded-captions工作流程，但它慢得多（約每 10 秒處理 4 分鐘），且需要設定HYPERFRAMES_ROOT。僅在使用者要求時提供此選項。