<div align="center">
<picture>
<img src="https://github.com/ellite/anchor-sub-sync/raw/main/resources/anchorlogo.png" alt="Anchor logo" width="160"
</picture>
<p>Anchor Sub Sync</p>
Stars
Downloads
PyPi
GitHub contributors
GitHub Sponsors
</div>
⚓ Anchor Sub Sync
Anchor는 오디오 정렬(audio alignment)을 사용하여 자막 파일(.srt, .ass)을 비디오 파일에 자동으로 동기화하는 GPU 가속 도구입니다. 이 도구는 OpenAI의 Whisper(WhisperX를 통해) 또는 선택적으로 NVIDIA의 Parakeet을 사용하며, 여러 정렬 기술을 적용하여 모든 자막 라인을 완벽하게 정렬합니다.
⚡ 핵심 기능 (Core Capabilities)
- 🔊 오디오 동기화 (Audio Sync): Whisper 또는 선택적 Parakeet 엔진을 사용하여 자막을 비디오에 자동 정렬합니다. (참조 텍스트 불필요)
- 📑 참조 동기화 (Reference Sync): 완벽하게 타이밍된 참조 자막(reference subtitle)을 사용하여 자동 동기화를 수행합니다. 한 화면에서 전체 시즌을 처리할 수 있습니다.
- 📍 포인트 동기화 (Point Sync): 고유한 라인들을 참조 자막과 일치시켜 선형 드리프트(linear drift)를 수정합니다.
- 🎥 프레임 속도 변경 (Change Frame Rate): 자막을 한 프레임 속도에서 다른 프레임 속도로 재설정합니다(예: 23.976에서 25로). 선택기 또는
--from-fps / --to-fps를 사용하여 가능합니다.
- 🩺 동기화 확인 (Sync Check): 자막이 동기화되었는지, 오프셋(offset) 상태인지, 드리프트(drifting) 중인지를 파악하고 선택적으로 수정할 수 있습니다. 요청하지 않으면 아무것도 변경하지 않습니다.
- 🌐 번역 (Translation): NLLB를 사용하여 문맥을 인식하는 번역을 수행하며, 듀얼 스피커 보존(dual-speaker preservation) 및 자동 포맷팅 기능을 제공합니다.
- 📝 스크립트 생성 (Transcriptions): 비디오에서 직접 자막을 생성합니다.
📦 컨테이너 작업(Container Tasks): 미디어에서 자막 추출, 삽입 또는 제거
🔥 구워 넣기(Burn-in): 비디오에 자막을 영구적으로 구워 넣기
🧽 클린 및 수정(Clean & Fix): 자막 파일 복구 및 정리
🔄 변환(Convert): 자막 형식 간 변환
📥 다운로드(Download): 일치하는 자막을 자동으로 찾고 다운로드
🔌 API 모드(API Mode): Anchor의 번역 엔진을 로컬 API 서버로 노출하여 Subtitle Edit의 자동 번역(Auto-Translate) 기능과 호환되며, 다른 도구를 위해 HTTP를 통해 오디오 동기화(audio syncs)를 큐에 넣습니다.
🚀 요구 사항
- OS: Linux | Windows | MacOS
- GPU: 권장됨. CPU만 사용 가능하지만(속도가 느림), 제한적입니다.
- Python: 3.10 또는 3.11
- ffmpeg / ffprobe: 오디오 프로빙(audio probing), 메타데이터 언어 감지 및 오디오 추출에 필요합니다.
📦 설치
1. Anchor 설치
저장소에서 도구를 직접 설치합니다.
pip install anchor-sub-sync
⚠️ 중요: 이 도구는 하드웨어 가속(hardware acceleration)에 의존하므로, 표준 pip install은 종종 잘못된 드라이버(CPU 버전)를 가져옵니다. 즉시 작동하지 않는 경우, 다음 단계를 순서대로 따르십시오.
2. PyTorch 설치 (하드웨어별 선택)
PyTorch를 설치하기 전에, 하드웨어를 감지하기 위해 몇 가지 간단한 확인을 실행하십시오:
nvidia-smi || true
python3 -c "import torch; print('cuda', torch.cuda.is_available(), getattr(torch.cuda, 'get_device_name', lambda i: '')(0))"
...
그런 다음 적절한 빌드를 설치합니다:
- CUDA 드라이버가 설치된 NVIDIA GPU:
pip install torch torchaudio torchvision --index-url https://download.pytorch.org/whl/cu121
- Apple Silicon (MPS) - PyTorch MPS 지침을 따르십시오(예시):
pip install torch torchaudio torchvision --index-url https://download.pytorch.org/whl/mps
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm7.1
⚠️ AMD GPU 가속을 사용하려면 ROCm과 호환되는 CTranslate2 빌드가 필요합니다. 표준 pip install ctranslate2는 NVIDIA CUDA 및 CPU만 지원합니다. Anchor는 기본 빌드가 설치된 경우, 시작 시 이를 자동으로 감지하고 CPU로 폴백(fallback)됩니다. 전체 AMD GPU 가속을 활성화하려면 소스에서 ROCm 지원으로 CTranslate2를 직접 빌드해야 합니다 — AMD CTranslate2 ROCm 가이드를 참조하십시오. 그렇지 않아도 Anchor는 CPU에서 여전히 올바르게 작동합니다.
pip install torch torchaudio torchvision
참고 사항:
- NVIDIA GPU와 일치하는 드라이버가 있는 경우에만 CUDA 휠을 설치하십시오. CPU 전용 시스템에 GPU 휠을 설치하면 미묘한 런타임 오류를 발생시킬 수 있습니다.
torchvision::nms 오류가 발생하는 경우, 일치하는 PyTorch/TorchVision 휠을 강제 재설치하십시오 (아래 문제 해결 섹션 참조).
3. 의존성 최종 설정 (필수)
일부 라이브러리가 설치 과정에서 다운그레이드될 수 있습니다. 다음 명령을 실행하여 GPU 번역 엔진이 최신 상태이며 드라이버와 호환되는지 확인하십시오:
pip install --upgrade ctranslate2
⚠️ AMD ROCm 사용자: CTranslate2를 소스에서 ROCm 지원으로 빌드한 경우 이 단계를 건너뛰십시오. pip install --upgrade ctranslate2를 실행하면 커스텀 빌드가 표준 CUDA 전용 휠로 대체되어 GPU 가속이 CPU로 되돌아갑니다.
🔌 API 모드 (Subtitle Edit 통합)
Anchor는 로컬 API 서버로 실행될 수 있습니다. 이 서버는 두 가지 기능을 제공합니다:
- 번역: Subtitle Edit의 자동 번역(Auto-Translate) 기능과 호환되어, Subtitle Edit 내부에서 Anchor의 NLLB 번역 엔진을 직접 사용할 수 있습니다.
- 오디오 동기화 작업: 다른 프로그램(미디어 대시보드, 스크립트 등)이 Anchor에게 비디오에 맞춰 자막 시간을 재조정하도록 요청할 수 있습니다. 엔드포인트를 참조하십시오.
API 서버는 다음 명령으로 시작합니다:
서버는 VRAM 사용 없이 유휴 상태(idle)를 유지하며, 첫 번째 요청 시 번역 모델을 자동으로 로드하고 설정된 유휴 시간 초과 후 다시 언로드합니다. 동기화 작업(sync job)은 자체 프로세스에서 실행되며 먼저 번역 모델을 언로드하므로, 두 기능이 GPU 자원을 놓고 경쟁하는 일이 없습니다.
⚙️ 구성 (Configuration)
API 서버는 ~/.anchor/config.json을 통해 구성됩니다:
"api_server": {
"host": "127.0.0.1",
"port": 5000,
...
| 설정 (Setting) | 설명 (Description) |
|---|
host | 로컬 액세스 전용으로 127.0.0.1을 사용합니다. 네트워크상의 다른 장치에서도 접근할 수 있도록 하려면 0.0.0.0으로 변경하십시오. |
| ... | |
~/.anchor/config.json을 변경한 후 API 서버를 재시작하십시오.
⚠️ /sync는 주어진 파일 옆에 작성하며, "overwrite": true를 사용하면 자막을 덮어씁니다. allowed_dirs에는 미디어 폴더를 유지하고, token을 설정하며, 신뢰하는 네트워크 외부에 포트를 노출하지 마십시오.
📡 엔드포인트 (Endpoints)
| 메서드 (Method) | 경로 (Path) | 인증 (Auth) | 목적 (Purpose) |
|---|
GET | / | 없음 (none) | 상태 확인 (Health check). |
| ... | | | |
"token"은 api_server.token이 설정된 경우에만 해당 엔드포인트가 베어러 토큰(bearer token)을 요구한다는 의미입니다.
POST /sync
오디오 동기화(audio sync)를 큐에 추가하고 즉시 반환합니다 (동기화 작업은 몇 분이 걸리기 때문). 작업은 도착 순서대로 하나씩 실행됩니다.
curl -X POST http://localhost:8007/sync \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"video": "/media/TV/Show/S01E01.mkv", "subtitle": "/media/TV/Show/S01E01.en.srt", "overwrite": false}'
| 필드 (Field) | 타입 (Type) | 설명 (Description) |
|---|
video | 문자열, 필수 (string, required) | 비디오의 절대 경로입니다. |
| ... | | |
작업(job)을 포함하여 다음 응답을 반환합니다 (아래 참조). 이 응답에는 "state": "queued"가 포함됩니다.
| 상태 (Status) | 의미 (Meaning) |
|---|
400 | 경로는 절대 경로가 아닙니다. |
GET /jobs/{id}
{
"id": "2e4fcf68c735",
"state": "done",
...
}
| 필드 | 설명 |
|---|
state | queued, running, done 또는 error. done 또는 error가 될 때까지 폴링(Poll)합니다 (몇 초 간격으로 충분합니다). |
| ... | |
알 수 없는 ID의 경우 404를 반환합니다. 작업은 메모리에만 유지됩니다: 최근 200개의 작업이 기억되며 재시작 시에는 이를 잊어버리므로 서비스를 재시작하기 전에 결과를 읽으십시오. | |
🖥️ Subtitle Edit 설정
- Subtitle Edit에서 Auto-translate (Video → Auto-translate)를 엽니다.
- 엔진 드롭다운 메뉴에서 thammegowda-nllb-serve를 선택합니다.
- URL을
http://<host>:<port>/translate로 설정합니다 (예: 다른 기기에서 접근하는 경우 http://192.168.1.50:5000/translate).
- 소스 언어와 타겟 언어를 선택하고 Translate를 클릭합니다.
⚠️ Subtitle Edit과 다른 기기에서 Anchor를 실행하는 경우, 설정 파일의 host 값을 0.0.0.0으로 설정했는지 확인하십시오.
🔄 백그라운드 실행
Linux — nohup 사용:
nohup anchor --api > ~/.anchor/api.log 2>&1 &
echo $! > ~/.anchor/api.pid
중지하는 방법:
kill $(cat ~/.anchor/api.pid)
Linux — systemd 서비스로 실행 (부팅 시 자동 실행):
먼저, anchor 바이너리의 전체 경로를 찾습니다:
/etc/systemd/system/anchor-api.service 파일을 생성합니다:
[Unit]
description=Anchor Subtitle API
after=network.target
...
YOUR_USERNAME과 ExecStart 경로를 which anchor의 출력값으로 대체하십시오. 그런 다음 활성화합니다:
sudo systemctl daemon-reload
sudo systemctl enable --now anchor-api
Windows — PowerShell 사용:
Start-Process anchor --api -WindowStyle Hidden
작동 원리 - 내부 동작 방식
간단히 요약하자면: Anchor는 WhisperX(또는 선택적 Parakeet 엔진)를 사용하여 비디오에 귀 기울이고, 자막의 단어를 발화된 내용과 일치시키며, 이 매칭에서 나온 모든 라인(음소 정렬(phoneme alignment), 전역 단어 정렬(global word alignment), 드리프트 보정 및 타임라인 보간법)을 배치하여 밀리초 단위로 정확한 자막 동기화를 생성합니다.
• 스크립트 작성(Transcription): 고품질 스크립트와 강제 정렬(forced alignment)을 제공하는 WhisperX 또는 정확한 단어 시간 측정을 위한 Parakeet.
• 음소 정렬 (Phoneme Alignment): 오디오를 음소에 매핑하여 단어 수준의 타이밍을 측정합니다.
• 전역 정렬 (Global Alignment): 스크립트의 단어를 말하는 단어와 일치시키며, 라인이 추가되거나 잘리거나 반복되어도 매칭하고, 철자가 다르게 쓰인 이름도 허용하여 앵커(anchor)를 찾습니다.
• 드리프트 보정 (Drift Correction): 잘 매칭된 라인은 자체적으로 신뢰하며, 단어 하나만 매칭되는 경우 강한(strong) 매칭의 드리프트와 일치해야 하며, 이 드리프트 추세는 긴 장면과 양 끝에서 모두 따라갑니다.
• 정리 (Cleanup): 매칭되지 않은 라인에 대한 보간(Interpolation) 처리와 깔끔한 자막을 위한 오버랩 수정기("Zipper")를 사용합니다.
<details>
<summary>전체 설명 보기</summary>
많은 싱크 도구는 단순한 파형 매칭이나 표준 음성 인식(speech-to-text)에 의존하며, 이는 종종 '드리프트'(자막이 서서히 동기화에서 벗어나는 현상)를 초래하거나 배우가 대사를 변경할 때 실패합니다.
이 엔진은 WhisperX와 다단계 탄성 정렬 알고리즘(multi-stage Elastic Alignment Algorithm)을 결합합니다. 처리 단계에서 무슨 일이 일어나고 왜 중요한지 설명합니다.
- Faster-Whisper 대신 WhisperX를 사용하는 이유?
표준 faster-whisper는 스크립트 작성(transcription)에 놀랍지만, 종종 타임스탬프를 '환각'처럼 생성합니다. 문장이 언제 시작했는지 대략적으로 추측하며, 종종 0.5초에서 1.0초 정도의 오차가 발생합니다.
WhisperX는 강제 정렬(Forced Alignment)이라는 중요한 후처리 단계를 추가합니다.
차이점: 단순히 단어를 듣는 대신, 오디오를 특정 음소(Phonemes, 'cat'의 't'와 같은 명확한 소리의 단위)에 매핑합니다.
결과: 이 도구는 단순히 무엇이 말해졌는지 아는 것을 넘어, 밀리초 단위까지 단어 수준의 타이밍 정밀도를 식별합니다. 이는 완벽한 동기화의 기반을 제공합니다.
- 정렬 논리 (단계별)
스크립트 작성(transcription)이 완료되면, 맞춤형 싱크 파이프라인은 제공된 스크립트를 실제 오디오와 병합합니다.
📏 음소 정렬(Aligning Phonemes): 시스템은 원본 오디오 사운드를 텍스트 문자로 매핑합니다. 이를 통해 배우가 빠르게 말하거나 중얼거리더라도 도구가 소리가 발생하는 정확한 순간을 포착할 수 있도록 보장합니다.
📐 전역 정렬(Global Alignment) (예: 6153개 대 6063개 단어): 스크립트는 최종 오디오와 완벽하게 일치하는 경우가 드뭅니다. 배우가 즉흥 연기(add-lib)를 하거나, 장면이 잘리거나, 단어가 반복될 수 있습니다.
표준 도구들은 여기에서 실패하는데, 이는 1:1 매칭만을 찾기 때문입니다.
이 도구는 전역 정렬을 수행하며, 단어 수가 다르더라도 두 데이터셋 간의 최적 적합도를 수학적으로 계산합니다. 인식기가 철자가 다르게 표기한 이름(예: "Venetti"를 "Vanetti"로 듣는 경우)은 스크립트의 철자에 맞춰 매칭되며, 발음이 비슷한 단어("three"와 "these")는 분리하여 처리됩니다.