agent-caption：本機離線，任意語言精準字幕

agent-caption — SKILL

你是一個 AI 字幕代理。此 repo 可為任何影片或音訊，以任何語言（預設為英語）加上準確、完美時間軸的字幕/副標題，適用於語音和音樂，並提供一流的 Hinglish / 語言混合 支援。可在 Windows、macOS 和 Linux 上執行。

Repo: https://github.com/ahkamboh/agent-caption — 克隆：git clone https://github.com/ahkamboh/agent-caption 此檔案（原始版本，供聊天代理擷取）： https://raw.githubusercontent.com/ahkamboh/agent-caption/master/SKILL.md

核心原則：詞彙來自語音辨識，但時間點來自波形上的強制對齊 — 絕不使用原始的 ASR 時間戳。因此，即使轉寫有拼寫錯誤，字幕也絕不會提前/延遲。

一次性設定（Windows / macOS / Linux）

需求：Python 3.10+、ffmpeg、約 4 GB 磁碟空間。（torch 會提供到 3.14 版的 wheel；如果 whisperx 在全新的 Python 版本上缺少 wheel，請使用 3.11–3.12。）

python setup.py        # 跨平台：建立 ./.venv-whisperx 並安裝所有套件
# macOS/Linux 便捷方式：bash setup.sh      ·      Windows 便捷方式：setup.bat

ffmpeg：macOS brew install ffmpeg · Ubuntu sudo apt install ffmpeg · Windows winget install ffmpeg。 模型（Whisper large-v3 — 預設 — MMS_FA、whisperX）會在首次執行時自動下載。

最簡單的路徑 — 單一指令包裝器（建議優先使用此方式）

對於「為此影片加字幕」的請求，直接執行頂層包裝器。它會執行轉寫 → 對齊 → 使用自動比例的字幕（針對任何解析度校正大小/間距/對齊）內嵌，並在使用者的 ffmpeg 不支援字幕時 回退到無 libass 的渲染器（Pillow + overlay）：

python caption.py <video>                                  # 英語，簡潔，比例自動調整 -> <video>.captioned.mp4
python caption.py <video> --hinglish --style tiktok        # Hinglish + TikTok 方塊
python caption.py <video> --lang ur --pos center --size 6  # 其他語言 / 位置 / 大小
python caption.py <video> --srt                            # 僅產生 .srt（不內嵌）
python caption.py <video> --from-srt FILE                  # 以自動比例內嵌現有的 .srt

15 種風格（內建字型）：clean（預設） bold hormozi green beast impact bebas tiktok pill boxed yellow neon gradient minimal subtitle。僅在需要原始轉寫、自訂渲染或翻譯時，才使用以下 個別腳本。

模型： large-v3 是預設（最佳準確度）— 無需標記；setup.py 會預先擷取。 想要在乾淨的英文上追求速度？加上 --fast（小型模型）。--accurate 仍然存在，但現在已無關緊要。 Hinglish 路徑一律使用 large-v3。

自訂風格 — 建構使用者描述的任何外觀。 將使用者的詞彙對應到這些標記（它們會覆蓋 --style）：

• --font <名稱|路徑> — 內建字型（Poppins-Bold、Poppins-Black、Anton-Regular、BebasNeue-Regular、ArchivoBlack-Regular）或任何 .ttf 路徑
• --fill #hex（文字顏色）· --outline #hex · --box #hex|#hexAA|none（文字後方色塊）
• --caps / --no-caps · --gradient "#hex,#hex,#hex" · --glow · --ow N（輪廓粗細）
• --size <pct>（高度）· --pos bottom|center|top

範例 — 使用者說 「深色圓角方塊中的螢光粉紅色大寫文字，Anton 字型」 →

python caption.py v.mp4 --fill "#ff3da6" --box "#10141ae0" --caps --font Anton-Regular.ttf --size 6

若要將全新的命名風格永久加入，請在 caption.py 的 STYLES 字典中新增一個條目。

精準度 — 消除聽錯的字詞（免費，無需 token，無需人工檢查）

強制對齊使時間點天生正確。唯一無法修正的是字詞是否被聽對（"their"/"there"、名稱、俚語）。三個免費方法可將此誤差推向零：

• --glossary "..." — 提供名稱/品牌/俚語（一個清單或一個 .txt 路徑）。會偏向 ASR 的 初始提示，使專有名詞不再被聽錯。對於名稱來說是最大的單一勝利。一次性的清單。

  python caption.py talk.mp4 --glossary "Xaibridge, Hinglish, Xotion, Kamboh"
  

• --script FILE — 如果正確的字詞已存在（歌詞、劇本），直接傳入。此工具會 跳過 ASR，僅對提供的字詞進行強制對齊 → 100% 內容準確度。

  python caption.py song.mp4 --script lyrics.txt
  

• --grammar — 對字幕進行離線同音字/文法檢查（"their"→"there"、"your"→"you're"）。 在本地執行 LanguageTool（不上傳，無需 token）；絕不碰觸時間點。可選依賴項目 — 透過 python setup.py --grammar 啟用一次（需要 Java/JRE 8+）；若缺失則乾淨地跳過。

  python caption.py talk.mp4 --accurate --glossary names.txt --grammar    # 堆疊使用
  

CP值順序：--glossary（名稱）→ --script（當文字存在時）→ --grammar（同音字）。 基礎模型已預設為 large-v3。這些方法唯一無法捕捉的殘餘錯誤需要人類或 LLM 介入 — 這是 唯一值得花 token 的成本，且僅針對標記出來的字詞，而不是整個轉寫。

歌曲 — 先分離人聲（--content）

對於音樂，在 ASR 之前分離人聲音軌可讓歌詞轉寫更清晰（Whisper 不再與背景音樂對抗）。 這是條件性的 — 在乾淨的語音上執行無意義且緩慢 — 因此透過閘門控制：

python caption.py song.mp4 --content music                 # 強制人聲分離（demucs）
python caption.py clip.mp4                                  # --content auto（預設）：偵測到音樂則分離，否則不處理
python caption.py podcast.mp4 --content speech              # 永遠不分離（或 --no-isolate）
python caption.py song.mp4 --content music --script lyrics.txt   # 最乾淨的歌曲：已知歌詞，在人聲幹聲上對時

auto 會執行快速的音樂/語音探測，並僅在聽到音樂時才分離 — 因此 Podcast/訪談 絕不會變慢。內嵌時一律使用原始影片；只有轉寫/對齊的部分使用分離後的幹聲。 需要 demucs（由 python setup.py 安裝）；若缺失則回退到原始音訊。

一律使用 venv 的 python 執行腳本 — 在此寫為 PY：

• macOS / Linux： PY = ./.venv-whisperx/bin/python
• Windows： PY = .venv-whisperx\Scripts\python

腳本

• transcribe.py — Whisper → 單字層級轉寫（預設英語；其他語言加上 --lang xx）。
• align.py — 強制對齊，以獲得影格精確的時間點。--code-switch 用於 Hinglish/混合語言。
• cs_transcribe.py — 對語言混合穩健的語音辨識（基於段落語言 ID）。
• mms_align.py — 通用的 MMS_FA 強制對齊器（1100+ 種語言，任何文字系統）。
• validate_timing.py — 時間點合理性檢查，用於語言混合路徑。
• export-subs.py — 轉寫 → .srt + .vtt。
• multilang-subs.py — 離線將字幕翻譯成多種語言。
• grammar_fix.py — 對 .srt 進行離線同音字/文法修正（保留時間點）；由 --grammar 使用。
• isolate_vocals.py — Demucs 人聲分離，用於歌曲 + 音樂與語音探測；由 --content 使用。
• qa.py — 快速確定性的 QA 閘門（提示合理性 + ffprobe 輸出檢查）→ work/<base>.qa.json。每次內嵌後自動執行；--strict 使損毀的輸出以非零狀態碼結束。
• footprint.py — 渲染 <base>.footprint.svg：一個一目了然的字幕健康度地圖（每個字根據強制對齊信心度著色 + 間隙標記 + 結論）。每次字幕處理後自動執行；加上 --no-footprint 可跳過。
• benchmark.py — 測量實際的精準度提升：舊預設（small）與新預設（large-v3 [+ Demucs]）相對於參考轉寫的字詞錯誤率（WER）。PY scripts/benchmark.py CLIP --ref truth.txt [--music] [--hinglish]。
• caption.py — 全功能的帶樣式字幕（卡拉OK/單字/行；Hormozi/TikTok/霓虹...）→ 動畫 captions.js。

為影片加字幕（主要工作）— 預設語言 = 英語

若為其他語言，加上 --lang <代碼>。若為 Hinglish / 混合語言，使用 --code-switch。

1) 影格精確的單字時間點

語音（對話、Podcast、UGC）：

PY scripts/align.py INPUT --lang en --out work/transcript.json

Hinglish / 混合印地語-英語（或任何語言混合的音訊）：

PY scripts/align.py INPUT --code-switch --dual hi en --out work/transcript.json

任何其他語言（烏爾都語、西班牙語、阿拉伯語、中文...）：

PY scripts/align.py INPUT --lang ur --out work/transcript.json

2a) 字幕（.srt / .vtt）+ 內嵌到影片中

PY scripts/export-subs.py work/transcript.json --out work/subs
ffmpeg -i INPUT -vf "subtitles=work/subs.srt" -c:a copy captioned.mp4

.srt 也適合直接上傳到 YouTube（可選擇 + SEO）。

2b) 帶樣式 / 動畫字幕（Hormozi、TikTok、卡拉OK — 短影音）

PY scripts/caption.py INPUT --lang en --content speech --style karaoke --preset hormozi --out out/

預設集：hormozi、beast、pill、neon、gradient、minimal、tiktok。將 --content music 用於歌曲/歌詞。請參閱 docs/caption-styles.md。

3) 將字幕翻譯成任何語言（可選）

PY scripts/multilang-subs.py work/subs.srt --to "hi,ur,es,fr,ar,de" [--burn INPUT]

規則（內建 — 不可覆蓋）

• 時間點一律使用強制對齊，絕不使用原始 ASR 時間戳（無提前/延遲）。
• 預設字幕語言 = 英語；其他語言加上 --lang。
• 音樂/歌唱 → --content music；語音/對話 → --content speech。
• 使用 PY（venv 的 python）執行每個腳本，以確保有 whisperx/torch。
• 交付前，抽樣檢查幾個字幕的單字起始點，確認同步。

語言代碼

en（預設）、hi、ur、pa、es、fr、de、pt、ar、zh、ja、ko、ru、it、tr、id、nl、pl、uk... — Whisper 支援約 99 種語言；MMS_FA 可對齊 1100+ 種語言。