zaddy99999/captions

captions 是做什麼的？

本地單詞級轉錄、短影音字幕樣式設定與燒錄。

腳本位於 scripts/：

腳本	功能
transcribe.py	使用 word_timestamps=True 的 faster-whisper 產生 words.json（已快取）
make-captions.mjs	從 words.json 產生 ASS（含當前單詞高亮）與 SRT
burn.mjs	使用 libass（ass / subtitles 濾鏡）燒錄 ASS/SRT
snap-to-words.mjs	將剪輯點移至最近的單詞間隙

工作流程

1. 轉錄（每個來源只需執行一次，結果會被快取）：

   pip install faster-whisper            # 一次
   python3 scripts/transcribe.py --input clip.mp4 --out edit/clip.words.json --model small --language en
   

   首次執行會從 Hugging Face 下載模型。若下載受阻，腳本會以代碼 4 退出並附上 JSON 格式的 fix 訊息，而非回傳錯誤堆疊；它絕不會寫入偽造的轉錄稿。將 --model 指向本機 CTranslate2 模型資料夾即可離線運作。
2. 建立字幕：

   node scripts/make-captions.mjs --words edit/clip.words.json --out-ass edit/clip.ass --out-srt edit/clip.srt
   

   樣式來自品牌包（captions 區塊：尺寸、邊距、輪廓、高亮；colors.accent 是當前單詞的顏色）。
3. 燒錄（作為最後的視覺步驟）：

   node scripts/burn.mjs --input edit/clip-hook.mp4 --subs edit/clip.ass --out edit/clip-captioned.mp4
   

   若字幕字型是檔案而非已安裝字型，請使用 --fonts-dir。
4. 驗證：使用 render-qc 校樣檢查單頁：確保字幕可讀、位於安全區內、且未覆蓋鉤板區域。

規則

• 切勿在單詞內部進行剪輯。分割語音前，請將剪輯點對齊到單詞間隙： node scripts/snap-to-words.mjs --words edit/clip.words.json --markers edit/cuts.json --out edit/cuts.json
• 字幕最後才加上：在剪輯、疊加與調色之後。若在轉錄後對片段進行修剪，請在 make-captions.mjs 傳入 --offset -<裁剪秒數>。
• 短影音每段字幕 1 到 3 個單詞（maxWords、maxChars）。段落依標點符號與停頓進行分割。
• 保持字幕避開底部約 15%（平台 UI）並遠離鉤板區域：調整 captions.marginV。
• 轉錄內容會被快取：僅在音檔變更時才使用 --force 重新執行。
• 務必將單詞與音檔進行抽樣比對；Whisper 可能誤認名稱與術語。必要時可手動修正 words.json。

若 ffmpeg 缺少 libass

如果 burn.mjs 回報缺少 ass 濾鏡，表示該 ffmpeg 版本未編譯 libass。請安裝完整版本（大多數套件管理員皆有提供），或將 SRT 作為獨立字幕軌上傳，而非直接燒錄嵌入。