사용 시점
사용자가 다음을 필요로 할 때 이 스킬을 사용하세요:
- 오디오 또는 비디오 파일에서 SRT 자막 생성 (오프라인, API 호출 없음)
- 미디어 파일에서 사용된 언어 자동 감지
- 제공된 원본 구술 스크립트(原口播文本)를 사용하여 Whisper 전사 오류 수정
- 여러 미디어 파일을 배치 처리하여 자막 생성
다음 경우에는 사용하지 마세요:
- 실시간/라이브 전사 (faster-whisper는 오프라인/배치 전용)
- SRT 이외의 출력 형식 (SRT만 지원)
- 클라우드 기반 전사 (로컬 전용)
절차
- 의존성 설치:
pip install faster-whisper. 운영 체제에 맞게 ffmpeg를 설치하세요:- macOS:
brew install ffmpeg - Linux:
sudo apt install ffmpeg(Debian/Ubuntu) 또는sudo dnf install ffmpeg(Fedora) - Windows:
choco install ffmpeg(Chocolatey) 또는scoop install ffmpeg(Scoop), 또는 https://ffmpeg.org에서 다운로드
- macOS:
- easy-subtitle 패키지가 설치되어 있는지 확인: 프로젝트 루트에서
pip install -e .실행 - 기본 전사:
easy-subtitle -i video.mp4실행하여 자동 감지된 언어로video.srt생성 - 언어 지정: 언어를 알고 있다면
easy-subtitle -i audio.wav -l zh실행 (자동 감지보다 빠르고 정확) - 원본 스크립트로 수정:
easy-subtitle -i video.mp4 --original-text script.txt실행하여 제공된 스크립트로 전사 정렬 및 보정 - 모델 크기 조정: 속도를 위해
-m small, 정확도를 위해-m large-v3사용. 기본값은medium - VAD 조정: 더 적극적인 무음 분할(조용한 콘텐츠)을 위해
--vad-min-silence 1000사용. 비활성화하려면--no-vad사용
주의 사항
- 첫 실행 시 모델을 다운로드합니다 (medium 기준 약 1.5GB) — 추가 시간과 디스크 공간을 확보하세요.
- Whisper의 자동 언어 감지는 매우 짧은 클립(<5초)에서는 신뢰도가 낮을 수 있습니다 — 수동으로
-l옵션을 사용하여 언어를 지정하세요. - 원본 스크립트 정렬은 스크립트가 오디오와 문자 그대로 일치할 때 가장 잘 작동합니다. 애드리브, 일시 중지, 즉흥 연기는 Whisper 출력으로 남겨집니다.
- faster-whisper는 CPU에서 기본적으로 INT8 양자화를 사용합니다 — 이는 빠르지만 GPU에서 FP16보다 약간 덜 정확합니다.
- ffmpeg는 별도로 설치해야 합니다 (Python 패키지가 아님).
- macOS:
brew install ffmpeg - Linux:
sudo apt install ffmpeg - Windows:
choco install ffmpeg또는 https://ffmpeg.org에서 다운로드
- macOS:
검증
easy-subtitle --version실행하여 설치 확인- 기본 전사 테스트:
easy-subtitle -i test_audio.mp3 -m tiny실행 시 빠르게 .srt 파일이 생성되어야 함 - SRT 출력 확인: 비디오 플레이어에서 열거나
HH:MM:SS,mmm --> HH:MM:SS,mmm형식의 타임스탬프가 포함된 번호 블록이 있는지 확인 - 원본 스크립트 정렬 테스트: 오디오와 일치하는 스크립트를 제공 — 출력에는 Whisper 전사 결과가 아닌 정확한 스크립트 텍스트가 포함되어야 함