quibex/reel-subs

reel-subs — 為 Reels 加入字幕與動畫

你已完成的 talking-head 剪輯（從 CapCut、Premiere 或手機匯出）變成一個具備逐句字幕和簡潔動畫的 Reel。所有操作都在使用者的機器上本地執行。

運作方式： 語音 → 帶有時間戳的文字（sherpa-onnx，離線）→ 你撰寫 edit.json（字幕 + 圖形項目）→ Remotion 僅渲染透明圖形層 → ffmpeg 將該圖層疊在未經處理的原始影片上，並保留原始影片的色彩標籤。絕不透過 Remotion 渲染整個影片：那樣會用不同的色彩矩陣重新編碼，導致膚色偏移。

以下 SKILL_DIR 指包含此檔案的資料夾。ENGINE = ~/.reel-subs/engine（在 Windows 上為 %USERPROFILE%\.reel-subs\engine；或如果設定了 $REELS_HOME/engine 環境變數則使用該路徑）。所有腳本都是純 Node 程式 — 用 node 執行，在 macOS、Windows 和 Linux 上都一樣。

用使用者的語言與他們交談。 以使用者撰寫給你的語言（通常是俄文）回覆，即使此檔案是英文：進度行、問題、錯誤、最終摘要。指令、路徑和 JSON 鍵保持不變。

先讀取使用者的偏好設定。 如果 ~/.reel-subs/preferences.md（或 $REELS_HOME/preferences.md）存在，請在步驟 1 之前讀取它並遵循：它記錄了使用者之前在對話中要求的內容，並會覆蓋此檔案中的預設值。請參閱下方的「學習使用者的品味」。

0. 設定（首次執行，或當 doctor 顯示 NOT READY 時）

node SKILL_DIR/scripts/setup.mjs            # 俄文語音模型（預設）
node SKILL_DIR/scripts/setup.mjs --lang multi   # 英文 + 24 種歐洲語言

僅需要 Node.js 18+。如果缺少 node，請告訴使用者從 nodejs.org 安裝 LTS 版本（macOS：brew install node 也可行；Windows：winget install OpenJS.NodeJS.LTS）並停止。設定會將引擎複製到 ENGINE，執行 npm install（Remotion、ffmpeg/ffprobe 二進位檔、sherpa-onnx），下載語音模型（~170 MB 俄文 / ~490 MB 多語言）和無頭 Chrome。此操作是冪等的。第一次需要 2–5 分鐘 — 用一句話說明。它會以 READY 結束。

如果顯示 ✗ headless browser：Remotion 的 Chrome 下載在此網路受阻，且未找到已安裝的 Chrome/Edge → 請使用者安裝 Google Chrome，然後重新執行設定。

1. 準備

node ENGINE/scripts/prepare.mjs "<video>" [--lang ru|multi] [--audio clean_voice.wav]

• --lang：ru（GigaAM，最適合俄文）或 multi（英文、德文、西班牙文、法文、烏克蘭文…）。根據影片中使用的語言來選擇；只有在不明確時才詢問。缺少的模型會自動下載。
• --audio：如果使用者有已清理的人聲軌道（Auphonic、Adobe Podcast…），請使用它 — 辨識效果更好，而且渲染時會將其放入最終影片。
• 在影片旁建立 <video name>.reels/ 資料夾：transcript.txt、words.json、edit.json（草稿）。
• 遇到 HDR 影片時會停止並附上說明（疊加在 HDR 上會導致色彩偏移）— 將其轉達給使用者。

2. 理解影片

1. 讀取 transcript.txt（含時間碼的短語）並略讀 words.json 以取得確切的單詞時間。
2. 查看畫面：node ENGINE/scripts/look.mjs "<video>" --every 1 → 打開縮圖圖像。 注意臉部位置（上方 / 中間）、手勢位置、螢幕 / 產品顯示位置、剪輯發生的位置。對於較長的影片，分段顯示（--from 0 --to 30）。

3. 修正字幕（edit.json → captions）

草稿頁面已按短語分割（~2 秒，≤ 32 個字元）。你的工作：

• 修正辨識錯誤：產品名稱、英文術語、數字（четыре бакса → $4）、品牌拼寫。辨識結果沒有標點符號 — 僅添加有助於閱讀的標點，通常大多數都不需要。
• 保留說話者自己的用詞和語言；除非被要求，否則不要翻譯。
• 合併/分割頁面，使每個頁面都是一個自然的短語。保持 startMs/endMs 與 words.json 對齊。
• 字幕文字內的標記：*word* → 強調色（很少使用，用於關鍵詞），~word~ → 紅色（說話者開玩笑的口誤）。
• 在你最終的回覆中列出你不確定的詞彙，而不是默默猜測。

4. 規劃圖形（edit.json → items）

完整的欄位參考與範例：SKILL_DIR/reference/edit-schema.md — 在撰寫項目前請先閱讀。

• hook — 前 2–4 秒，直到第一個剪輯或笑點：用一句簡短的話濃縮影片的精華，使用說話者的語言。顯示時字幕自動隱藏。
• card — 一個關鍵點：label（小型大寫字母）+ title 和/或 chips，它們會在其說明的文字出現時顯示（at），on: true 用於結果晶片，strikeAt 用於劃掉某些內容。
• big — 說話者強調的一個數字或一個詞（"$1"、"5000"）。
• terminal — 僅在談論程式碼、代理、指令時使用。
• punch — 一個笑話 / 自嘲：a 被劃掉，b 以大字形出現。字幕自動隱藏。
• pop — 小型 HUD 小工具，在說話者做手勢時（「而這些動畫會…」）卡入到手部旁邊。將它們放置在大約 ~0.3 秒前：辨識的時間戳記會有延遲。
• badge — 一個持續顯示的標籤，位於左上角（例如集數編號），僅在使用者想要時使用。

規則：

• 絕不遮住臉。 資訊卡預設位於上方三分之一處（top: 260）。如果臉部在畫面上半部，請使用 top: 1110（低處）。同時不要遮蓋說話者正在指向的東西。
• 所有內容都保持在安全區域內（資訊卡寬 840 像素，置中）— 不要將東西移到邊緣。
• 密度：平均每 5–10 秒一個圖形，配合文字時間。不要使用重複說出內容的文字框，不要解釋顯而易見的東西，不要使用彈跳/幼稚的動畫。
• 首次提及產品/專案時：資訊卡應以幾個詞說明其內容 — 觀眾是新的。
• 時間是以原始影片中的秒為單位。項目可以與字幕重疊；hook/punch 會隱藏它們。
• 不要虛構事實：晶片和資訊卡必須準確反映說話者所說的內容。

5. 預覽 — 在完整渲染前一定要先查看

node ENGINE/scripts/preview.mjs "<work>/edit.json"            # 每個項目內的單一畫面
node ENGINE/scripts/preview.mjs "<work>/edit.json" --at 1.2,7,15

打開 previews/sheet.jpg（以及需要時的單張 at_<t>.jpg）。檢查：臉部清晰、文字可容納、無碰觸邊緣、字幕可讀。修正 edit.json 並再次預覽。每次執行約需 10–30 秒。

6. 渲染

node ENGINE/scripts/render.mjs "<work>/edit.json" [--out file.mp4]

每分鐘影片約需 1–4 分鐘渲染。輸出預設為原始影片旁的 <video name>_final.mp4。它會輸出輸出幀數與原始幀數的比較 — 如果顯示 MISMATCH，請告訴使用者。 然後提供使用者：輸出路徑、你添加內容的 2–3 行摘要、可疑的詞彙。

修訂

編輯 edit.json → 預覽變更的時刻 → 再次渲染。在使用者核准字幕後，絕不要重新執行 prepare.mjs --force（這會重置字幕）。在進行重大更改前先複製 edit.json。

學習使用者的品味

此技能應隨著每次使用而變得更好。使用者的筆記儲存在 ~/.reel-subs/preferences.md（如果設定了 $REELS_HOME/preferences.md 則使用該路徑）— 位於技能資料夾和 ENGINE 之外，因此更新技能或重新執行設定絕不會清除它們。

何時提供儲存選項：

• 使用者兩次修正同一類型的東西（字型、顏色、字幕大小或位置、圖形數量、鉤子用詞、哪些詞彙需要強調…）。
• 使用者說了類似「запомни」、「в следующий раз делай так」、「мне так больше нравится」的話。
• 在一個有修訂的對話結束時：用 2–4 行簡短列出修正內容，並詢問一次是否要為下次儲存。

如何做：

• 永遠先詢問，準確顯示你將寫的內容，只有在得到肯定答覆後才寫入。絕不擅自儲存。
• 寫規則，而不是歷史：「字幕字體放大：captionSize 60」、「鉤子不含表情符號」、「每 10 秒不超過一個資訊卡」。將它們歸類在簡短的標題下（風格、字幕、圖形、措辭）。更新或刪除舊規則，而不是添加矛盾的規則。
• edit.json → style 支援的樣式值以確切數值記錄，這樣你就可以將它們複製到每個新的 edit.json 中。
• 如果某個需求需要程式碼變更（新的字型、新的動畫、不同的資訊卡外觀），請在 ENGINE/src/ 中進行修改，並同時在 preferences.md 的 Engine changes 下記錄：哪個檔案、變更了什麼、原因。設定會重新複製引擎並覆蓋已編輯的檔案（新檔案會保留），因此在任何設定執行後，請檢查此列表並重新套用缺失的部分。
• 使用者也可以手動編輯 preferences.md，或直接告訴你要修改什麼。

自訂

• 顏色 / 大小：edit.json → style（accent、captionSize、captionTop、font）。
• 新型圖形：在 ENGINE/src/components/ 中新增一個元件，在 src/types.ts 中新增一個類型，並在 src/Overlay.tsx 中新增一個 case — 套件會在下次預覽時自動重建。保持圖層透明（Remotion 內無背景、無影片）。
• 在 ENGINE 內執行 npm run studio 可開啟 Remotion Studio 進行即時調整。

故障排除

• doctor：node ENGINE/scripts/doctor.mjs — 為每個依賴項顯示 ✓/✗。
• 可變幀率警告 → 請使用者以恆定 30 或 60 fps 匯出。
• 不是 9:16 → 圖形是為直式影片設計的；它們會縮放以適應，但請說明。
• Windows：使用相同的指令；用引號括住含空格的路徑。PowerShell 和 cmd 都適用。
• 任何東西都不會上傳到任何地方：模型和 Chrome 只下載一次，然後所有操作都在離線狀態下執行。