자막 정렬
기존 스크립트 텍스트를 오디오에 정렬하여 가라오케 스타일의 자막을 생성합니다. Qwen3-ForcedAligner-0.6B (약 30ms 정밀도)와 jieba를 사용하여 중국어 단어 분할(문자를 자연스러운 단어로 그룹화)을 수행합니다.
파이프라인
스크립트 + 오디오
↓
Qwen3-ForcedAligner (문자 수준 타임스탬프)
↓
Jieba 단어 분할 (문자 → 중국어 단어)
↓
위치 기반 구문 매칭 (단어 → 구)
↓
출력: 단어 타임스탬프가 포함된 구
사용법
# 스크립트를 오디오에 정렬 (단어 타임스탬프가 포함된 구 수준 출력)
python skills/align-captions/align.py voiceover.wav --script "全世界都在追AI的时候..."
# 파일로 저장
python skills/align-captions/align.py voiceover.wav --script "..." --output captions.json
# 단어 수준만 출력 (구 그룹화 없음)
python skills/align-captions/align.py voiceover.wav --script "..." --word-level
출력 형식
Remotion 가라오케 렌더링에 최적화됨:
{
"segments": [
{
"text": "全世界...",
"startMs": 240, "endMs": 2080,
"words": [
{"text": "全", "startMs": 240, "endMs": 400},
{"text": "世界", "startMs": 400, "endMs": 880}
]
}
],
"word_segments": [...],
"language": "Chinese",
"model": "Qwen3-ForcedAligner-0.6B"
}
프로그래매틱 사용법
from align import align_captions
# 단어 타임스탬프가 포함된 구 가져오기
result = align_captions(
"voiceover.wav",
script="全世界都在追AI的时候...",
language="Chinese"
)
# 각 구에는 가라오케 하이라이팅을 위한 'words' 배열이 있음
for phrase in result["segments"]:
print(f"{phrase['text']}: {len(phrase['words'])} words")
make-video와의 통합
make_video.py 스크립트는 다음 조건을 만족하면 자동으로 자막 정렬을 사용합니다:
- voiceover 파일이 존재함
- project.json에 스크립트가 제공됨
caption_mode가 "auto" 또는 "asr"로 설정됨
출력은 Remotion의 RollingCaption 컴포넌트로 전달되어 가라오케 렌더링을 수행합니다.
오류 복구
- 오디오 파일을 찾을 수 없음: 호출 전에 경로가 존재하는지 확인하세요. 스크립트는
FileNotFoundError를 발생시킵니다.project.json에서 올바른 voiceover 경로를 확인하세요. - 모델 다운로드 실패: Qwen3-ForcedAligner(~1GB)는 첫 실행 시 다운로드됩니다. 다운로드가 실패하면(네트워크/디스크 문제) 재시도하거나 수동으로 HuggingFace 캐시(
~/.cache/huggingface/)에 다운로드하세요. - jieba가 설치되지 않음:
pip install jieba를 실행하세요. jieba가 없으면 중국어 텍스트는 문자 수준 타임스탬프로 대체됩니다(단어 그룹화 없음).
참고 사항
- 11개 언어 지원: 중국어, 영어, 광둥어, 프랑스어, 독일어, 이탈리아어, 일본어, 한국어, 포르투갈어, 러시아어, 스페인어