kaylon-he/video-subtitle-skill

Video Subtitle

동영상에 자동으로 자막을 추가하고 자막을 화면에 입혀서, '자막 포함 MP4 + SRT'를 출력합니다.

파이프라인

1. 16kHz 모노 wav 추출 (ffmpeg)
2. whisper.cpp로 SRT 전사 (whisper-cli)
3. SRT → ASS: 화면 너비에 맞춰 자동 줄바꿈, CJK 폰트, 하단 중앙 반투명 배경
4. libass가 포함된 ffmpeg로 ASS를 입히고, 오디오 트리는 그대로 복사

사용법

bash scripts/add_subtitles.sh input.mp4 -o output.mp4 -l zh

• -l/--language 원본 언어, 기본값 zh, auto 입력 가능
• -f/--fontsize 글꼴 크기, 기본값 42
• -s/--srt-only SRT만 출력, 자막 입히지 않음

반드시 지켜야 할 사항

• 전사 결과를 먼저 확인한 후 전달: 스크립트가 SRT를 터미널에 출력합니다. 사람 이름, 지명, 관용구는 자주 잘못 인식됩니다 (예: '重阳姐' → '重阳节', '久久重扬' → '九九重阳'). 오류가 있으면 -s 옵션으로 다시 SRT를 생성하고, 수정한 후 자막을 입히세요.
• 최종 결과물 검증: 완성된 동영상에서 2-3프레임을 추출하여 (-ss <초> -frames:v 1) 자막이 완전하고, 잘리거나 화면 밖으로 나가지 않는지 확인하세요.
• Homebrew 경량 ffmpeg 사용 금지: 해당 빌드에는 libass가 포함되어 있지 않아 subtitles/ass/drawtext 필터가 모두 없습니다. 스크립트가 자동으로 libass가 포함된 ffmpeg를 선택하며, 설치 방법은 README.md를 참조하세요.
• 긴 문장은 반드시 줄바꿈: ASS는 WrapStyle: 2만 인식합니다 (\N만 인식). srt_to_ass.py가 이미 화면 너비 / 글꼴 크기에 따라 자동으로 \N을 삽입합니다. 특정 문장이 여전히 넘치면 -f 글꼴 크기를 줄이세요.

환경 의존성

ffmpeg (libass 포함) + whisper-cli + ggml 모델 + python3. 필수 구성 요소가 없으면 스크립트가 명확한 오류 메시지를 출력합니다. 전체 라이브러리 목록, 설치 명령어 및 문제 해결 설명은 README.md를 참조하세요.