Whisper
개요
OpenAI의 Whisper — 최신 음성 인식 모델을 사용하여 오디오를 텍스트로 변환합니다. 이 스킬은 로컬 Whisper(Python), faster-whisper(CTranslate2, 4배 빠름), whisper.cpp(CPU 최적화 C++), OpenAI Whisper API를 모두 다룹니다. 자막 생성(SRT/VTT/JSON), 다국어 전사, 영어 번역, 화자 분리, 단어 수준 타임스탬프, 팟캐스트/회의/비디오 자막을 위한 프로덕션 파이프라인 패턴을 포함합니다.
지침
1단계: 런타임 선택
옵션 A — OpenAI Whisper (원본 Python):
pip install openai-whisper
# 모델: tiny (39M), base (74M), small (244M), medium (769M), large-v3 (1.5G)
옵션 B — faster-whisper (로컬 권장, 4배 빠름):
pip install faster-whisper
# CTranslate2 사용 — INT8 양자화, CPU에서 우수한 성능
옵션 C — whisper.cpp (CPU에 최적, 최소 종속성):
git clone https://github.com/ggerganov/whisper.cpp
cd whisper.cpp && make
# 모델 다운로드
bash models/download-ggml-model.sh base.en
옵션 D — OpenAI API (로컬 GPU 불필요):
pip install openai
export OPENAI_API_KEY="sk-..."
2단계: 기본 전사
faster-whisper (권장):
from faster_whisper import WhisperModel
model = WhisperModel("base", device="cpu", compute_type="int8")
# GPU: model = WhisperModel("large-v3", device="cuda", compute_type="float16")
segments, info = model.transcribe("episode.mp3", beam_size=5)
print(f"언어: {info.language} (확률: {info.language_probability:.2f})")
for segment in segments:
print(f"[{segment.start:.2f}초 → {segment.end:.2f}초] {segment.text}")
OpenAI Whisper (원본):
import whisper
model = whisper.load_model("base") # tiny, base, small, medium, large-v3
result = model.transcribe("episode.mp3")
print(result["text"])
for segment in result["segments"]:
print(f"[{segment['start']:.1f}초 - {segment['end']:.1f}초] {segment['text']}")
whisper.cpp (CLI):
./main -m models/ggml-base.en.bin -f episode.wav -otxt -osrt -ovtt
# 출력: episode.txt, episode.srt, episode.vtt
OpenAI API:
from openai import OpenAI
client = OpenAI()
with open("episode.mp3", "rb") as f:
transcript = client.audio.transcriptions.create(
model="whisper-1",
file=f,
response_format="verbose_json",
timestamp_granularities=["segment", "word"],
)
print(transcript.text)
for segment in transcript.segments:
print(f"[{segment.start:.1f}초] {segment.text}")
3단계: 자막 생성 (SRT/VTT)
faster-whisper로 SRT 생성:
from faster_whisper import WhisperModel
model = WhisperModel("small", device="cpu", compute_type="int8")
segments, info = model.transcribe("episode.mp3", beam_size=5)
def format_timestamp(seconds):
h = int(seconds // 3600)
m = int((seconds % 3600) // 60)
s = int(seconds % 60)
ms = int((seconds % 1) * 1000)
return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
with open("episode.srt", "w") as f:
for i, seg in enumerate(segments, 1):
f.write(f"{i}\n")
f.write(f"{format_timestamp(seg.start)} --> {format_timestamp(seg.end)}\n")
f.write(f"{seg.text.strip()}\n\n")
print("episode.srt 생성됨")
VTT 생성 (HTML5 비디오용):
with open("episode.vtt", "w") as f:
f.write("WEBVTT\n\n")
for i, seg in enumerate(segments, 1):
start = format_timestamp(seg.start).replace(",", ".")
end = format_timestamp(seg.end).replace(",", ".")
f.write(f"{start} --> {end}\n")
f.write(f"{seg.text.strip()}\n\n")
단어 수준 타임스탬프 (노래방 스타일 자막):
segments, info = model.transcribe("episode.mp3", word_timestamps=True)
for segment in segments:
for word in segment.words:
print(f" [{word.start:.2f}초 → {word.end:.2f}초] {word.word}")
4단계: 언어 감지 및 번역
# 언어 자동 감지
segments, info = model.transcribe("foreign_audio.mp3")
print(f"감지된 언어: {info.language} ({info.language_probability:.0%})")
# 특정 언어 강제 지정
segments, info = model.transcribe("german.mp3", language="de")
# 영어로 번역 (모든 언어 → 영어)
segments, info = model.transcribe("german.mp3", task="translate")
for seg in segments:
print(seg.text) # 영어 번역
지원 언어: en, zh, de, es, ru, ko, fr, ja, pt, tr, pl, nl, ar, sv, it, hi 등 총 99개 언어.
5단계: 화자 분리
Whisper와 pyannote-audio를 결합하여 "누가 말했는지" 식별:
from faster_whisper import WhisperModel
from pyannote.audio import Pipeline
import torch
# 전사
model = WhisperModel("small", device="cpu", compute_type="int8")
segments, info = model.transcribe("meeting.wav", beam_size=5)
whisper_segments = list(segments)
# 화자 분리 (pyannote 접근 권한을 위한 HuggingFace 토큰 필요)
diarization = Pipeline.from_pretrained(
"pyannote/speaker-diarization-3.1",
use_auth_token="hf_YOUR_TOKEN"
)
diarization_result = diarization("meeting.wav")
# 병합: 각 whisper 세그먼트에 화자 할당
def get_speaker(start, end, diarization_result):
"""시간 범위 내에서 주요 화자 찾기."""
speakers = {}
for turn, _, speaker in diarization_result.itertracks(yield_label=True):
overlap_start = max(start, turn.start)
overlap_end = min(end, turn.end)
if overlap_start < overlap_end:
duration = overlap_end - overlap_start
speakers[speaker] = speakers.get(speaker, 0) + duration
return max(speakers, key=speakers.get) if speakers else "알 수 없음"
for seg in whisper_segments:
speaker = get_speaker(seg.start, seg.end, diarization_result)
print(f"[{speaker}] [{seg.start:.1f}초 → {seg.end:.1f}초] {seg.text}")
6단계: 배치 처리 및 파이프라인
디렉토리 내 모든 에피소드 전사:
import os
from pathlib import Path
from faster_whisper import WhisperModel
model = WhisperModel("small", device="cpu", compute_type="int8")
episodes_dir = Path("episodes")
output_dir = Path("transcripts")
output_dir.mkdir(exist_ok=True)
for audio_file in sorted(episodes_dir.glob("*.mp3")):
print(f"전사 중: {audio_file.name}")
segments, info = model.transcribe(str(audio_file), beam_size=5)
# 일반 텍스트
txt_path = output_dir / f"{audio_file.stem}.txt"
with open(txt_path, "w") as f:
for seg in segments:
f.write(seg.text.strip() + "\n")
# SRT
srt_path = output_dir / f"{audio_file.stem}.srt"
segments2, _ = model.transcribe(str(audio_file), beam_size=5) # 재반복
with open(srt_path, "w") as f:
for i, seg in enumerate(segments2, 1):
h, m = divmod(int(seg.start), 3600)
m, s = divmod(m, 60)
ms = int((seg.start % 1) * 1000)
start_ts = f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
h2, m2 = divmod(int(seg.end), 3600)
m2, s2 = divmod(m2, 60)
ms2 = int((seg.end % 1) * 1000)
end_ts = f"{h2:02d}:{m2:02d}:{s2:02d},{ms2:03d}"
f.write(f"{i}\n{start_ts} --> {end_ts}\n{seg.text.strip()}\n\n")
print(f" → {txt_path}, {srt_path}")
7단계: 모델 선택 가이드
| 모델 | 크기 | VRAM | 속도 (CPU) | 정확도 | 최적 용도 |
|---|---|---|---|---|---|
| tiny | 39M | ~1GB | 매우 빠름 | 낮음 | 빠른 초안, 실시간 |
| base | 74M | ~1GB | 빠름 | 중간 | CPU에서 좋은 균형 |
| small | 244M | ~2GB | 보통 | 좋음 | 팟캐스트, 깨끗한 오디오 |
| medium | 769M | ~5GB | 느림 | 매우 좋음 | 잡음이 있는 오디오, 악센트 |
| large-v3 | 1.5G | ~10GB | 매우 느림 | 최고 | 프로덕션 품질 |
권장 사항:
- CPU 전용, 속도 중요:
tiny또는base+ faster-whisper - CPU 전용, 정확도 중요:
small+ faster-whisper - GPU 사용 가능:
large-v3+ faster-whisper (float16) - 로컬 연산 불필요: OpenAI API (
whisper-1)
예제
예제 1: 팟캐스트 시즌 전사 및 SRT 자막 생성
사용자 프롬프트: "./episodes/ 디렉토리에 있는 모든 20개의 MP3 에피소드를 전사하고 일반 텍스트 대본과 SRT 자막 파일을 생성하세요. 10GB VRAM의 GPU가 있습니다."
에이전트는 다음을 수행합니다:
pip install faster-whisper로 faster-whisper를 설치합니다.- GPU를 활용하기 위해
device="cuda"와compute_type="float16"으로large-v3모델을 로드합니다. ./transcripts/출력 디렉토리를 생성합니다../episodes/디렉토리 내 모든.mp3파일을 반복하며 각각을beam_size=5로 전사합니다.- 각 에피소드에 대해
.txt파일(일반 텍스트)과.srt파일(올바른 타임스탬프 포함)을 작성합니다. - 각 에피소드의 감지된 언어와 총 처리 시간을 보고합니다.
예제 2: 독일어 인터뷰를 화자 레이블과 함께 영어로 번역
사용자 프롬프트: "meeting.wav에 두 명의 화자가 있는 45분 분량의 독일어 인터뷰 녹음 파일이 있습니다. 영어로 전사하고 누가 무엇을 말했는지 레이블을 지정하세요."
에이전트는 다음을 수행합니다:
- faster-whisper와 pyannote-audio를 설치합니다 (
pip install faster-whisper pyannote.audio). task="translate"로meeting.wav를 전사하여 독일어 오디오에서 영어 텍스트를 얻습니다.- pyannote 화자 분리를 실행하여 화자 세그먼트를 식별합니다 (pyannote 모델 접근 권한이 있는 HuggingFace 토큰 필요).
- 시간 범위를 일치시켜 Whisper 세그먼트와 화자 분리 결과를 병합하여 화자 레이블을 할당합니다.
- 각 세그먼트 앞에
[Speaker 1]및[Speaker 2]레이블이 있는 형식화된 대본을 출력합니다.
지침
- 로컬 전사에는 원본 OpenAI Whisper보다 faster-whisper를 사용하세요; CTranslate2를 통한 INT8 양자화로 4배 빠르고 메모리 사용량이 적습니다.
- 하드웨어에 따라 모델 크기를 선택하세요: CPU 속도용
tiny/base, CPU 정확도용small, GPU 프로덕션 품질용large-v3. - MP3/M4A 입력을 처리할 때는 항상 오디오를 WAV로 변환하거나 ffmpeg가 설치되어 있는지 확인하세요. Whisper는 비WAV 형식 디코딩을 위해 ffmpeg에 의존합니다.
- 화자 분리의 경우, pyannote 파이프라인은 허용된 모델 약관이 있는 HuggingFace 액세스 토큰이 필요합니다; 다중 화자 전사를 시도하기 전에 이를 설정하세요.
- SRT 파일을 생성할 때는
beam_size=5를 사용하여 더 정확한 세그먼트 경계를 얻으세요; 기본 그리디 디코딩은 타이밍이 좋지 않은 자막 분할을 생성할 수 있습니다.