baxtree/subaligner

Automatically synchronize and translate subtitles, or create new ones by transcribing, using pre-trained DNNs, Forced Alignments and Transformers. https://subaligner.readthedocs.io/

What is Subaligner?

Subaligner는 비디오 또는 오디오 트랙과 해당 자막 파일을 동기화하는 오픈소스 파이썬 도구입니다. 현대적인 머신러닝 모델(예: 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

System dependency – FFmpeg가 필요합니다(apt-get install ffmpeg 또는 brew install ffmpeg).
Python package – pip install subaligner (가상 환경 내 설치를 권장).
Optional extras:
- subaligner[llm] – Whisper 및 번역 모델 포함.
- subaligner[stretch] – 강제 동기화 유틸리티 추가(필요 시 eSpeak).
- subaligner[dev] / subaligner[harmony] – 개발용 및 전체 기능 세트.
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)

Feature extraction – 오디오는 librosa와 TensorFlow 기반 모델로 처리되어 임베딩을 얻습니다.
Global alignment – 훈련된 신경망 모델이 전체 파일에 대해 단일 시간 오프셋을 예측합니다.
Parallel per‑segment alignment – 비디오는 짧은 청크로 분할되며, 각 청크는 독립적으로 동기화되어 세밀한 보정이 가능합니다.
Optional transcription – -m transcribe 선택 시 Whisper(또는 다른 LLM)이 음성을 텍스트로 변환합니다.
Optional translation – HuggingFace Transformers 모델이 트랜스크립트 또는 원본 자막을 번역합니다.

When to Use Which Mode

Situation	Recommended mode
빠른 수정이 필요하고 자막이 약간 비동기화됨	`single` (전역 오프셋)
정확한 타이밍이 중요(예: 더빙 또는 자막 작업)	`dual` (전역 + 세그먼트별)
자막이 없음 – 새로운 트랜스크립트 필요	`transcribe` (모델 크기 `-mf`로 선택)
한 언어의 트랜스크립트가 있고 번역 필요	`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 확장으로 설치하면 테스트 및 린트 도구 사용 가능.

TL;DR

Subaligner는 고전적 오디오 처리, TensorFlow 모델, 대규모 언어 모델 기반 음성 인식/번역 백엔드를 결합한 파이썬 기반 CLI(및 Docker 이미지)입니다. 거의 모든 자막 및 미디어 형식과 호환되며, 빠른 전역 동기화와 고정밀 이중 단계 동기화를 제공하며, 자체 모델 훈련을 통해 확장 가능합니다.