baxtree/subaligner

What is Subaligner?

Subaligner は、対応するビデオまたはオーディオトラックと字幕ファイルを同期するオープンソースの Python ツールです。現代の機械学習モデル（例：OpenAI Whisper、HuggingFace Transformers）および古典的なオーディオ処理ライブラリを使用して、既存の字幕の同期、メディアから新しい字幕の生成（音声認識）、および翻訳をすべて実行できます。

---

Core Capabilities

Capability	How it works (as described in the README)	Typical command example
Single‑stage alignment	高速なグローバルシフト推定（低レイテンシ）。	subaligner -m single -v video.mp4 -s subtitle.srt
Dual‑stage alignment	二段階プロセス：グローバルオフセットの後にセグメントごとの微調整（高レイテンシ、高精度）。	subaligner -m dual -v video.mp4 -s subtitle.srt
Transcription	Whisper（または他のLLMベースの音声認識モデル）を呼び出して、オーディオから字幕を作成。	subaligner -m transcribe -v video.mp4 -ml eng -mr whisper -mf small -o subtitle.srt
Translation	音声認識後（または既存の字幕に対して）、Helsinki‑NLP、Facebook‑MBart、M2M100などのモデルを使用して翻訳。	subaligner -m dual -v video.mp4 -s subtitle.srt -t eng,spa -tr helsinki-nlp
Manual shifting	シンプルなオフセット（秒単位）の加算または減算。	subaligner -m shift --subtitle_path subtitle.srt -os 5.5
Batch processing	ディレクトリツリー内の多数のビデオ/字幕を一括処理。	subaligner_batch -m dual -vd videos/ -sd subtitles/ -od aligned_subtitles/
Custom model training	自分のビデオ・字幕ペアで新しい同期モデルを訓練。	subaligner_train -vd VIDEO_DIRECTORY -sd SUBTITLE_DIRECTORY -tod TRAINING_OUTPUT_DIRECTORY

---

Installation Overview

1. System dependency – FFmpeg が必要です（apt-get install ffmpeg または brew install ffmpeg）。
2. Python package – pip install subaligner（仮想環境内でのインストールを推奨）。
3. Optional extras:
   • subaligner[llm] – Whisper と翻訳モデルを含む。
   • subaligner[stretch] – 強制同期ユーティリティを追加（eSpeak が必要）。
   • subaligner[dev] / subaligner[harmony] – 開発用およびフル機能セット。
4. Docker – 事前構築済みイメージ（docker pull baxtree/subaligner）でローカルインストールなしでCLIを実行可能。

---

Quick‑Start Example

# 既存の英語SRTをローカルMP4に同期（最高精度のためdualステージ）
subaligner -m dual -v video.mp4 -s subtitle.srt -o subtitle_aligned.srt

このコマンドはビデオを読み込み、オーディオ特徴を抽出し、グローバルオフセットを予測してから、各字幕行を微調整します。結果は subtitle_aligned.srt に書き込まれます。

---

How It Works (High‑Level Architecture)

1. Feature extraction – オーディオは librosa と TensorFlow ベースのモデルで処理され、埋め込み表現が取得されます。
2. Global alignment – 訓練済みのニューラルモデルがファイル全体に適用される単一の時間シフトを予測します。
3. Parallel per‑segment alignment – ビデオを短いチャンクに分割し、各チャンクを独立して同期することで、細かい補正が可能になります。
4. Optional transcription – -m transcribe を選択すると、Whisper（または他のLLM）が音声をテキストに変換します。
5. Optional translation – HuggingFace Transformers モデルがトランスクリプトまたは元の字幕を翻訳します。

---

When to Use Which Mode

Situation	Recommended mode
高速な修正が必要で、字幕がわずかに同期していない	single（グローバルシフト）
時間の正確さが重要（例：吹き替えやキャプション）	dual（グローバル + セグメントごと）
字幕が存在しない – 新しいトランスクリプトが必要	transcribe（-mf でWhisperモデルサイズを選択）
ある言語のトランスクリプトがあり、翻訳が必要	dual/single + -t src,tgt + -tr <model>
複数のファイルを自動処理したい	subaligner_batch

---

Extensibility

• Custom models – subaligner_train で独自ドメインデータでモデルを訓練し、CLI で新しいモデルを指定可能。
• Prompt engineering – -ip フラグでWhisperにグローバルプロンプトを前置でき、--use_prior_prompting で前の字幕行を次の行のコンテキストとして提供可能。
• Word‑level timestamps – --word_time_codes を追加すると、各単語に独自の開始/終了時刻を持つJSON出力が得られ、後続の編集ツールに有用です。

---

Community & Support

• Documentation – https://subaligner.readthedocs.io（リポジトリから自動生成）。
• CI / Test coverage – GitHub Actions バッジで継続的インテグレーションを確認、Codecov バッジでテストカバレッジを確認。
• Citation – 学術利用向けにZenodo DOIが提供されています。
• Contributions – dev オプションでインストールすると、テストおよびLintツールが利用可能。

---

TL;DR

Subaligner は、古典的なオーディオ処理、TensorFlowモデル、大規模言語モデルによる音声認識/翻訳バックエンドを組み合わせた、PythonベースのCLI（およびDockerイメージ）です。ほぼすべての字幕やメディアフォーマットに対応し、高速グローバル同期と高精度の二段階同期の両方を提供し、独自モデルの訓練によって拡張可能です。