Faster Whisper
faster-whisper를 이용한 로컬 음성-텍스트 변환 — OpenAI Whisper의 CTranslate2 기반 재구현으로 4~6배 빠른 속도에 동일한 정확도를 제공합니다. GPU 가속 시 실시간의 약 20배 속도로 전사합니다(10분 오디오 파일을 약 30초에 처리).
사용 시기
다음과 같은 경우에 이 스킬을 사용하세요:
- 오디오/비디오 파일 전사 — 회의, 인터뷰, 팟캐스트, 강의, YouTube 동영상
- 음성을 로컬에서 텍스트로 변환 — API 비용 없음, 모델 다운로드 후 오프라인 작동
- 여러 오디오 파일 일괄 처리 — 대규모 컬렉션에 효율적
- 자막/캡션 생성 — 단어 수준 타임스탬프 지원
- 다국어 전사 — 자동 감지로 99개 이상의 언어 지원
트리거 문구: "이 오디오를 텍스트로 변환해줘", "음성을 텍스트로 변환", "그들이 뭐라고 말했지?", "대본 만들어줘", "오디오를 텍스트로", "이 비디오 자막 만들어줘"
사용하지 말아야 할 경우:
- 실시간/스트리밍 전사 (스트리밍 최적화 도구 사용)
- 로컬 컴퓨팅 자원이 없는 클라우드 전용 환경
- 10초 미만 파일 (API 호출 지연이 문제되지 않는 경우)
빠른 참조
| 작업 | 명령어 | 비고 |
|---|---|---|
| 기본 전사 | ./scripts/transcribe audio.mp3 | 기본 distil-large-v3 사용 |
| 더 빠른 영어 | ./scripts/transcribe audio.mp3 --model distil-medium.en --language en | 영어 전용, 6.8배 빠름 |
| 최고 정확도 | ./scripts/transcribe audio.mp3 --model large-v3-turbo --beam-size 10 | 느리지만 최고 품질 |
| 단어 타임스탬프 | ./scripts/transcribe audio.mp3 --word-timestamps | 자막/캡션용 |
| JSON 출력 | ./scripts/transcribe audio.mp3 --json -o output.json | 프로그래밍 방식 접근 |
| 다국어 | ./scripts/transcribe audio.mp3 --model large-v3-turbo | 언어 자동 감지 |
| 묵음 제거 | ./scripts/transcribe audio.mp3 --vad | 음성 활동 감지 |
모델 선택
필요에 맞는 모델을 선택하세요:
digraph model_selection {
rankdir=LR;
node [shape=box, style=rounded];
start [label="시작", shape=doublecircle];
need_accuracy [label="최대 정확도가
필요한가요?", shape=diamond];
multilingual [label="다국어
콘텐츠인가요?", shape=diamond];
resource_constrained [label="리소스
제약이 있나요?", shape=diamond];
large_v3 [label="large-v3
또는
large-v3-turbo", style="rounded,filled", fillcolor=lightblue];
large_turbo [label="large-v3-turbo", style="rounded,filled", fillcolor=lightblue];
distil_large [label="distil-large-v3
(기본값)", style="rounded,filled", fillcolor=lightgreen];
distil_medium [label="distil-medium.en", style="rounded,filled", fillcolor=lightyellow];
distil_small [label="distil-small.en", style="rounded,filled", fillcolor=lightyellow];
start -> need_accuracy;
need_accuracy -> large_v3 [label="예"];
need_accuracy -> multilingual [label="아니오"];
multilingual -> large_turbo [label="예"];
multilingual -> resource_constrained [label="아니오 (영어)"];
resource_constrained -> distil_small [label="모바일/엣지"];
resource_constrained -> distil_medium [label="약간 제한"];
resource_constrained -> distil_large [label="제약 없음"];
}
모델 표
표준 모델 (전체 Whisper)
| 모델 | 크기 | 속도 | 정확도 | 사용 사례 |
|---|---|---|---|---|
tiny / tiny.en | 39M | 가장 빠름 | 기본 | 빠른 초안 |
base / base.en | 74M | 매우 빠름 | 좋음 | 일반 용도 |
small / small.en | 244M | 빠름 | 더 좋음 | 대부분의 작업 |
medium / medium.en | 769M | 보통 | 높음 | 고품질 전사 |
large-v1/v2/v3 | 1.5GB | 느림 | 최고 | 최대 정확도 |
large-v3-turbo | 809M | 빠름 | 우수함 | 정확도 권장 |
증류 모델 (~6배 빠름, 약 1% WER 차이)
| 모델 | 크기 | 표준 대비 속도 | 정확도 | 사용 사례 |
|---|---|---|---|---|
distil-large-v3 | 756M | ~6.3배 빠름 | 9.7% WER | 기본값, 최적의 균형 |
distil-large-v2 | 756M | ~5.8배 빠름 | 10.1% WER | 대체용 |
distil-medium.en | 394M | ~6.8배 빠름 | 11.1% WER | 영어 전용, 리소스 제약 환경 |
distil-small.en | 166M | ~5.6배 빠름 | 12.1% WER | 모바일/엣지 디바이스 |
.en 모델은 영어 전용이며 영어 콘텐츠에서 약간 더 빠르고 정확합니다.
설정
Linux / macOS / WSL2
# 설정 스크립트 실행 (venv 생성, 종속성 설치, GPU 자동 감지)
./setup.sh
Windows (네이티브)
# PowerShell에서 실행 (winget으로 Python 및 ffmpeg 자동 설치)
.\setup.ps1
Windows 설정 스크립트는 다음을 수행합니다:
- Python 3.12를 찾을 수 없으면 winget으로 자동 설치
- ffmpeg를 찾을 수 없으면 winget으로 자동 설치
- NVIDIA GPU를 감지하고 CUDA 지원 PyTorch 설치
- venv 생성 및 모든 종속성 설치
요구 사항:
- Linux/macOS/WSL2: Python 3.10+, ffmpeg
- Windows: 없음! 설정이 winget으로 필수 구성 요소를 자동 설치합니다.
플랫폼 지원
| 플랫폼 | 가속 | 속도 | 자동 설치 |
|---|---|---|---|
| Windows + NVIDIA GPU | CUDA | 실시간의 ~20배 🚀 | ✅ 전체 |
| Linux + NVIDIA GPU | CUDA | 실시간의 ~20배 🚀 | 수동 필수 요소 |
| WSL2 + NVIDIA GPU | CUDA | 실시간의 ~20배 🚀 | 수동 필수 요소 |
| macOS Apple Silicon | CPU* | 실시간의 ~3-5배 | 수동 필수 요소 |
| macOS Intel | CPU | 실시간의 ~1-2배 | 수동 필수 요소 |
| Windows (GPU 없음) | CPU | 실시간의 ~1배 | ✅ 전체 |
| Linux (GPU 없음) | CPU | 실시간의 ~1배 | 수동 필수 요소 |
*faster-whisper는 macOS에서 CTranslate2를 사용하며 CPU 전용이지만, Apple Silicon은 실용적인 사용에 충분히 빠릅니다.
GPU 지원 (중요!)
설정 스크립트가 GPU를 자동 감지하고 CUDA 지원 PyTorch를 설치합니다. 가능하면 항상 GPU를 사용하세요 — CPU 전사는 매우 느립니다.
| 하드웨어 | 속도 | 9분 동영상 |
|---|---|---|
| RTX 3070 (GPU) | 실시간의 ~20배 | 약 27초 |
| CPU (int8) | 실시간의 ~0.3배 | 약 30분 |
설정이 GPU를 감지하지 못한 경우, CUDA 지원 PyTorch를 수동으로 설치하세요:
Linux/macOS/WSL2:
# CUDA 12.x 용
uv pip install --python .venv/bin/python torch --index-url https://download.pytorch.org/whl/cu121
# CUDA 11.x 용
uv pip install --python .venv/bin/python torch --index-url https://download.pytorch.org/whl/cu118
Windows:
# CUDA 12.x 용
.venv\Scripts\pip install torch --index-url https://download.pytorch.org/whl/cu121
# CUDA 11.x 용
.venv\Scripts\pip install torch --index-url https://download.pytorch.org/whl/cu118
- Windows 사용자: NVIDIA 드라이버가 설치되어 있는지 확인하세요
- WSL2 사용자: Windows에 WSL용 NVIDIA CUDA 드라이버가 설치되어 있는지 확인하세요
사용법
Linux/macOS/WSL2:
# 기본 전사
./scripts/transcribe audio.mp3
# 특정 모델 사용
./scripts/transcribe audio.wav --model large-v3-turbo
# 단어 타임스탬프 포함
./scripts/transcribe audio.mp3 --word-timestamps
# 언어 지정 (자동 감지보다 빠름)
./scripts/transcribe audio.mp3 --language en
# JSON 출력
./scripts/transcribe audio.mp3 --json
Windows (cmd 또는 PowerShell):
# 기본 전사
.\scripts\transcribe.cmd audio.mp3
# 특정 모델 사용
.\scripts\transcribe.cmd audio.wav --model large-v3-turbo
# 단어 타임스탬프 포함 (PowerShell 네이티브 구문도 작동)
.\scripts\transcribe.ps1 audio.mp3 -WordTimestamps
# JSON 출력
.\scripts\transcribe.cmd audio.mp3 --json
옵션
--model, -m 모델 이름 (기본값: distil-large-v3)
--language, -l 언어 코드 (예: en, es, fr - 생략 시 자동 감지)
--word-timestamps 단어 수준 타임스탬프 포함
--beam-size 빔 검색 크기 (기본값: 5, 높을수록 정확하지만 느림)
--vad 음성 활동 감지 활성화 (묵음 제거)
--json, -j JSON 형식으로 출력
--output, -o 대본을 파일로 저장
--device cpu 또는 cuda (자동 감지)
--compute-type int8, float16, float32 (기본값: 자동 최적화)
--quiet, -q 진행 메시지 숨기기
예제
# YouTube 오디오 전사 (yt-dlp로 추출 후)
yt-dlp -x --audio-format mp3 <URL> -o audio.mp3
./scripts/transcribe audio.mp3
# JSON 출력으로 일괄 전사
for file in *.mp3; do
./scripts/transcribe "$file" --json > "${file%.mp3}.json"
done
# 더 큰 빔 크기로 고정밀 전사
./scripts/transcribe audio.mp3 \
--model large-v3-turbo --beam-size 10 --word-timestamps
# 빠른 영어 전용 전사
./scripts/transcribe audio.mp3 \
--model distil-medium.en --language en
# VAD를 사용한 전사 (묵음 제거)
./scripts/transcribe audio.mp3 --vad
흔한 실수
| 실수 | 문제 | 해결책 |
|---|---|---|
| GPU가 있는데 CPU 사용 | 10~20배 느린 전사 | Windows/Linux에서 nvidia-smi 확인; CUDA 설치 확인 |
| 언어를 지정하지 않음 | 알려진 콘텐츠에서 자동 감지에 시간 낭비 | 언어를 알고 있으면 --language en 사용 |
| 잘못된 모델 사용 | 불필요한 느림 또는 낮은 정확도 | 기본 distil-large-v3가 우수함; 정확도 문제 시에만 large-v3 사용 |
| 증류 모델 무시 | 1% 미만 정확도 손실로 6배 속도 향상 포기 | 표준 모델 전에 distil-large-v3 시도 |
| ffmpeg 누락 | 설정 실패 또는 오디오 처리 불가 | 설정 스크립트가 처리; 수동 설치 시 ffmpeg 별도 필요 |
| 메모리 부족 오류 | 모델이 VRAM/RAM에 비해 너무 큼 | 더 작은 모델 또는 --compute-type int8 사용 |
| 빔 크기 과잉 엔지니어링 | 빔 크기 5~7 이상에서 수확 체감 | 기본 5로 충분; 중요한 대본에만 10 시도 |
성능 참고 사항
- 첫 실행:
~/.cache/huggingface/에 모델 다운로드 (최초 1회) - GPU: 사용 가능하면 CUDA 자동 사용 (
1020배 빠름) - 양자화: CPU에서 INT8 사용으로 최소한의 정확도 손실로 약 4배 속도 향상
- 메모리:
distil-large-v3: 약 2GB RAM / 약 1GB VRAMlarge-v3-turbo: 약 4GB RAM / 약 2GB VRAMtiny/base: <1GB RAM
왜 faster-whisper인가?
- 속도: OpenAI 원본 Whisper보다 약 4~6배 빠름
- 정확도: 동일 (동일한 모델 가중치 사용)
- 효율성: 양자화를 통한 낮은 메모리 사용량
- 프로덕션 준비: 안정적인 C++ 백엔드 (CTranslate2)
- 증류 모델: 1% 미만 정확도 손실로 약 6배 빠름
문제 해결
"CUDA를 사용할 수 없음 — CPU 사용": CUDA 지원 PyTorch 설치 (위의 GPU 지원 참조)
설정 실패: Python 3.10+가 설치되어 있는지 확인
메모리 부족: 더 작은 모델 또는 --compute-type int8 사용
CPU에서 느림: 예상된 현상 — 실용적인 전사를 위해 GPU 사용
모델 다운로드 실패: Linux/macOS에서 ~/.cache/huggingface/ 권한 확인 또는 Windows에서 %USERPROFILE%\.cache\huggingface\ 확인
Windows 관련
"winget을 찾을 수 없음": Microsoft Store에서 앱 설치 관리자 설치 또는 Python/ffmpeg 수동 설치
"설치 후 Python이 PATH에 없음": 터미널을 닫고 다시 연 후 setup.ps1 다시 실행
PowerShell 실행 정책 오류: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned 실행 또는 transcribe.cmd 사용
GPU가 있는데 nvidia-smi를 찾을 수 없음: NVIDIA 드라이버 설치 — Game Ready 또는 Studio 드라이버에 nvidia-smi 포함