baxtree/subaligner

什麼是 Subaligner？

Subaligner 是一個開源的 Python 工具，可將字幕檔案與對應的影片或音訊軌道進行同步。它可使用現代機器學習模型（例如 OpenAI Whisper、HuggingFace Transformers）及經典音訊處理函式庫，執行 對齊 現有字幕、產生 新字幕（透過轉錄媒體內容），甚至 翻譯 字幕。

---

核心功能

功能	工作原理（如 README 所述）	典型命令範例
單階段對齊	快速全域偏移估計（低延遲）。	subaligner -m single -v video.mp4 -s subtitle.srt
雙階段對齊	兩階段流程：先進行全域偏移，再對每個字幕段進行細微調整（高延遲，高準確度）。	subaligner -m dual -v video.mp4 -s subtitle.srt
轉錄	呼叫 Whisper（或其他基於 LLM 的語音轉文字模型）從音訊產生字幕。	subaligner -m transcribe -v video.mp4 -ml eng -mr whisper -mf small -o subtitle.srt
翻譯	在轉錄後（或對現有字幕）使用 Helsinki‑NLP、Facebook‑MBart 或 M2M100 等模型進行翻譯。	subaligner -m dual -v video.mp4 -s subtitle.srt -t eng,spa -tr helsinki-nlp
手動偏移	以秒為單位簡單增加或減少偏移量。	subaligner -m shift --subtitle_path subtitle.srt -os 5.5
批次處理	對目錄樹中的多個影片/字幕進行對齊。	subaligner_batch -m dual -vd videos/ -sd subtitles/ -od aligned_subtitles/
自訂模型訓練	使用自己的影片-字幕對訓練新的對齊模型。	subaligner_train -vd VIDEO_DIRECTORY -sd SUBTITLE_DIRECTORY -tod TRAINING_OUTPUT_DIRECTORY

---

安裝概覽

1. 系統相依性 – 必須安裝 FFmpeg（apt-get install ffmpeg 或 brew install ffmpeg）。
2. Python 套件 – pip install subaligner（建議在虛擬環境中安裝）。
3. 可選擴充：
   • subaligner[llm] – 包含 Whisper 和翻譯模型。
   • subaligner[stretch] – 添加強制對齊工具（需要 eSpeak）。
   • subaligner[dev] / subaligner[harmony] – 開發與完整功能集。
4. Docker – 使用預先建置的映像（docker pull baxtree/subaligner）可在無本地安裝的情況下執行 CLI。

---

快速入門範例

# 將現有的英文 SRT 與本地 MP4 檔案對齊（雙階段以取得最佳準確度）
subaligner -m dual -v video.mp4 -s subtitle.srt -o subtitle_aligned.srt

該命令讀取影片，提取音訊特徵，預測全域偏移，然後優化每行字幕。結果寫入 subtitle_aligned.srt。

---

工作原理（高階架構）

1. 特徵提取 – 使用 librosa 和 TensorFlow 基礎模型處理音訊，取得嵌入向量。
2. 全域對齊 – 訓練好的神經網路模型預測整個檔案的單一時間偏移。
3. 平行分段對齊 – 將影片分割為短片段，每個片段獨立對齊，實現細粒度修正。
4. 可選轉錄 – 選擇 -m transcribe 時，Whisper（或其他 LLM）將語音轉換為文字。
5. 可選翻譯 – HuggingFace Transformers 模型翻譯轉錄文字或原始字幕。

---

何時使用哪種模式

情況	推薦模式
需要 快速修復，字幕僅輕微不同步	single（全域偏移）
精確時間至關重要（如配音或字幕製作）	dual（全域 + 分段）
無字幕 – 需要 新轉錄	transcribe（透過 -mf 選擇 Whisper 模型大小）
有某語言的轉錄文字，需要 翻譯	dual/single + -t src,tgt + -tr <model>
需要自動處理 多個檔案	subaligner_batch

---

可擴展性

• 自訂模型 – 使用 subaligner_train 在自己的資料上訓練模型，然後在 CLI 中指向新模型。
• 提示工程 – -ip 標誌可為 Whisper 添加全域提示，--use_prior_prompting 可將前一行字幕作為下一行的上下文。
• 詞級時間戳 – 加入 --word_time_codes 可獲得 JSON 輸出，其中每個詞都有獨立的開始/結束時間，適用於後續編輯工具。

---

社群與支援

• 文件 – https://subaligner.readthedocs.io（從倉儲自動生成）。
• CI / 測試覆蓋率 – GitHub Actions 標記顯示持續整合；Codecov 標記顯示測試覆蓋率。
• 引用 – 提供 Zenodo DOI 供學術使用。
• 貢獻 – 使用 dev 擴充安裝可取得測試和 lint 工具。

---

TL;DR

Subaligner 是一個基於 Python 的 CLI（及 Docker 映像），結合經典音訊處理、TensorFlow 模型以及大語言模型的語音識別/翻譯後端，實現字幕對齊、生成與翻譯。支援幾乎所有字幕或媒體格式，提供快速全域對齊和高精度雙階段對齊，並可透過訓練自訂模型進行擴展。