whisperX - GitLite

KO | EN

gitlite — search

#typescript #go #android #rust #linux #docker #macos #windows #awesome #cli #kubernetes #pytorch #mcp #openai

whisperX

(★ 23,680)

WhisperX: 단어 수준의 타임스탬프(& 화자 분리)를 지원하는 자동 음성 인식

파일 탐색기

최종 버전 다운로드 (.zip)

- - build-and-release.yml
  - python-compatibility.yml
  - tests.yml
  - zizmor.yml
- FUNDING.yml
- pipeline.png
- test_word_timestamp_interpolation.py
- - mel_filters.npz
  - pytorch_model.bin
- - __init__.py
  - pyannote.py
  - silero.py
  - vad.py
- __init__.py
- __main__.py
- alignment.py
- asr.py
- audio.py
- conjunctions.py
- diarize.py
- log_utils.py
- schema.py
- SubtitlesProcessor.py
- transcribe.py
- utils.py
.gitignore
.python-version
CUDNN_TROUBLESHOOTING.md
EXAMPLES.md
LICENSE
MANIFEST.in
pyproject.toml
README.md
uv.lock

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/m-bain/whisperX

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd whisperX

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. 공식 설치 스크립트

쉬움 추천

사전 준비물

Python 3 pip 명령어를 쓰려면 Python이 필요합니다.

pip install whisperx

PyPI에 배포된 패키지를 바로 설치합니다. 소스 클론이 필요 없습니다.

✅ 설치 후 새 터미널을 열고, 프로그램의 버전 확인 명령(예: --version)으로 정상 설치됐는지 확인하세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

3. Python

쉬움

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Python 3 설치 시 'Add Python to PATH' 옵션을 꼭 체크하세요 (Windows).

pip install whisperx

PyPI에 배포된 패키지를 바로 설치합니다. 소스 클론이 필요 없습니다.

✅ 에러 메시지 없이 실행되고 터미널에 안내 문구가 출력되면 정상입니다.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# WhisperX

## Recall.ai - Meeting Transcription API
미팅용 음성 텍스트 변환(transcription) API를 찾고 계신다면, Zoom, Google Meet, Microsoft Teams 등과 연동되는 [Recall.ai's Meeting Transcription API](https://www.recall.ai/product/meeting-transcription-api?utm\_source=github&utm\_medium=sponsorship&utm\_campaign=mbain-whisperx)를 확인해 보세요. Recall.ai는 미팅 플랫폼에서 화자 데이터와 개별 오디오 스트림을 가져와 화자 분할(diarization)을 수행하므로, 실제 화자 이름을 포함하여 100% 정확한 화자 분할이 가능합니다.

[![GitHub stars](https://img.shields.io/github/stars/m-bain/whisperX.svg?colorA=orange&colorB=orange&logo=github)](https://github.com/m-bain/whisperX/stargazers)
[![GitHub issues](https://img.shields.io/github/issues/m-bain/whisperx.svg)](https://github.com/m-bain/whisperX/issues)
[![GitHub license](https://img.shields.io/github/license/m-bain/whisperX.svg)](https://github.com/m-bain/whisperX/blob/master/LICENSE)
[![ArXiv paper](http://img.shields.io/badge/Arxiv-2303.00747-B31B1B.svg)](https://arxiv.org/abs/2303.00747)
[![Twitter](https://img.shields.io/twitter/url/https/github.com/m-bain/whisperX.svg?style=social)](https://twitter.com/intent/tweet?text=&url=https%3A%2F%2Fgithub.com%2Fm-bain%2FwhisperX)

![whisperx-arch](https://raw.githubusercontent.com/m-bain/whisperX/refs/heads/main/figures/pipeline.png)

이 저장소는 단어 수준의 타임스탬프와 화자 분할 기능을 갖춘 고속 자동 음성 인식(large-v2 기준으로 실시간 대비 70배 속도)을 제공합니다.
- ⚡️ whisper large-v2를 사용한 일괄(batched) 추론으로 실시간 대비 70배 빠른 텍스트 변환
- 🪶 [faster-whisper](https://github.com/guillaumekln/faster-whisper) 백엔드 사용, large-v2 및 beam\_size=5 기준 8GB 미만의 GPU 메모리 필요
- 🎯 wav2vec2 정렬을 사용한 정확한 단어 수준 타임스탬프
- 👯‍♂️ [pyannote-audio](https://github.com/pyannote/pyannote-audio)의 화자 분할을 이용한 다중 화자 ASR (화자 ID 레이블)
- 🗣️ VAD 전처리, WER 저하 없이 환각(hallucination) 현상 감소 및 배치 처리 지원
\*\*Whisper\*\*는 다양한 오디오로 구성된 대규모 데이터셋으로 학습된, [OpenAI가 개발한](https://github.com/openai/whisper) ASR 모델입니다. 매우 정확한 텍스트 변환 결과를 생성하지만, 해당 타임스탬프는 단어별이 아닌 발화(utterance) 수준이므로 수 초 정도의 오차가 발생할 수 있습니다. OpenAI의 Whisper는 네이티브 배치 처리를 지원하지 않습니다.
\*\*음소 기반 ASR (Phoneme-Based ASR)\*\* 한 단어를 다른 단어와 구별하는 최소 음성 단위(예: "tap"의 'p' 요소)를 인식하도록 미세 조정된 모델 모음입니다. 널리 사용되는 예시 모델로는 [wav2vec2.0](https://huggingface.co/facebook/wav2vec2-large-960h-lv60-self)이 있습니다.
\*\*강제 정렬 (Forced Alignment)\*\*은 음성 녹음물에 정형화된 텍스트 변환을 정렬하여 음소 수준의 세분화를 자동으로 생성하는 프로세스를 말합니다.
\*\*음성 구간 검출 (Voice Activity Detection, VAD)\*\*은 인간의 음성 존재 여부를 감지하는 기술입니다.
\*\*화자 분할 (Speaker Diarization)\*\*은 인간의 음성이 포함된 오디오 스트림을 각 화자의 신원에 따라 동질적인 구간으로 분할하는 프로세스입니다.

## 새로운 기능 🚨

- [Ego4d transcription challenge](https://eval.ai/web/challenges/challenge-page/1637/leaderboard/3931/WER) 1위 수상 🏆
- \_WhisperX\_, INTERSPEECH 2023 채택
- v3 문장별 텍스트 세그먼트: 더 나은 자막 생성과 화자 분할을 위해 nltk sent\_tokenize 사용
- v3 출시, 70배 속도 향상 오픈소스 공개. [faster-whisper](https://github.com/guillaumekln/faster-whisper) 백엔드를 사용하는 일괄 처리 Whisper 적용!
- v2 출시, 코드 정리, whisper 라이브러리 임포트, 논문과 동일하게 VAD 필터링이 기본적으로 활성화됨.
- 논문 공개🎓👨‍🏫! 벤치마크 및 WhisperX에 대한 자세한 내용은 [ArxiV 프리프린트](https://arxiv.org/abs/2303.00747)를 참조해 주세요. 또한 large-v2에서 \\*실시간 대비 60-70배 빠른 속도를 내는 더 효율적인 배치 추론 기능을 소개합니다.

## 설치 ⚙️

### 0. CUDA 설치
GPU 가속을 사용하여 WhisperX를 사용하려면, WhisperX 설치 전에 CUDA toolkit 12.8을 설치해야 합니다. CPU만 사용하는 경우 이 단계를 건너뛰세요.
- \*\*Linux\*\* 사용자의 경우, 다음 가이드에 따라 CUDA toolkit 12.8을 설치하세요:
[CUDA Installation Guide for Linux](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/).
- \*\*Windows\*\* 사용자의 경우, CUDA toolkit 12.8을 다운로드하여 설치하세요:
[CUDA Downloads](https://developer.nvidia.com/cuda/cuda-12-8-1-download-archive).

### 1. 간편 설치 (권장)
WhisperX를 설치하는 가장 쉬운 방법은 PyPI를 통하는 것입니다:
```bash
pip install whisperx
```
또는 [uvx](https://docs.astral.sh/uv/guides/tools/#running-tools)를 사용하는 경우:
```bash
uvx whisperx
```

### 2. 고급 설치 옵션
이 설치 방법들은 개발자나 특정 요구사항이 있는 사용자를 위한 것입니다. 확실하지 않다면 위의 간편 설치를 유지하세요.

#### 옵션 A: GitHub에서 설치
GitHub 저장소에서 직접 설치하려면:
```bash
uvx git+https://github.com/m-bain/whisperX.git
```

#### 옵션 B: 개발자 설치
코드를 수정하거나 프로젝트에 기여하고 싶은 경우:
```bash
git clone https://github.com/m-bain/whisperX.git
cd whisperX
uv sync --all-extras --dev
```
> \*\*참고\*\*: 개발 버전에는 실험적인 기능과 버그가 포함되어 있을 수 있습니다. 프로덕션 환경에서는 안정적인 PyPI 릴리스를 사용하세요.

ffmpeg, rust 등도 설치해야 할 수 있습니다. https://github.com/openai/whisper#setup의 OpenAI 지침을 따르세요.

### 화자 분리 (Speaker Diarization)
\*\*화자 분리(Speaker Diarization)를 활성화하려면\*\*, `--hf\_token` 인수 뒤에 [여기](https://huggingface.co/settings/tokens)에서 생성할 수 있는 Hugging Face 액세스 토큰(읽기 권한)을 포함하고 [speaker-diarization-community-1](https://huggingface.co/pyannote/speaker-diarization-community-1) 모델의 이용 약관에 동의해야 합니다.

## 사용법 💬 (명령 줄)

### English
기본 매개변수(whisper small)를 사용하여 예제 세그먼트에서 whisper를 실행하고, `.srt` 파일에서 단어 타이밍을 시각화하려면 `--highlight\_words True`를 추가하세요.
whisperx path/to/audio.wav
wav2vec2.0 large를 사용한 강제 정렬(forced alignment)을 적용한 _WhisperX_ 결과:
https://user-images.githubusercontent.com/36994049/208253969-7e35fe2a-7541-434a-ae91-8e919540555d.mp4
많은 전사(transcription) 결과가 싱크가 맞지 않는 기본 whisper의 결과와 비교해 보세요:
https://user-images.githubusercontent.com/36994049/207743923-b4f0d537-29ae-4be2-b404-bb941db73652.mov
더 높은 타임스탬프 정확도를 원하고 GPU 메모리를 더 사용하는 대신, 더 큰 모델을 사용하세요(더 큰 정렬 모델이 그렇게 유용하지는 않은 것으로 나타났습니다, 논문 참조). 예:
whisperx path/to/audio.wav --model large-v2 --align\_model WAV2VEC2\_ASR\_LARGE\_LV60K\_960H --batch\_size 4
전사 결과에 화자 ID를 레이블로 지정하려면 (알고 있는 경우 화자 수를 설정하세요. 예: `--min\_speakers 2` `--max\_speakers 2`):
whisperx path/to/audio.wav --model large-v2 --diarize --highlight\_words True
GPU 대신 CPU에서 실행하려면 (그리고 Mac OS X에서 실행하려면):
whisperx path/to/audio.wav --compute\_type int8 --device cpu
### Other languages
음소(phoneme) ASR 정렬 모델은 _언어별(language-specific)_이며, 테스트된 언어의 경우 이 모델들은 [torchaudio 파이프라인 또는 huggingface에서 자동으로 선택됩니다](https://github.com/m-bain/whisperX/blob/f2da2f858e99e4211fe4f64b5f2938b007827e17/whisperx/alignment.py#L24-L58).
`--language` 코드를 전달하고 whisper `--model large`를 사용하기만 하면 됩니다.
현재 torchaudio 파이프라인을 통해 `{en, fr, de, es, it}`용 기본 모델이 제공되며, Hugging Face를 통해 다른 많은 언어들이 제공됩니다. 현재 지원되는 언어 목록은 [alignment.py](https://github.com/m-bain/whisperX/blob/main/whisperx/alignment.py)의 `DEFAULT\_ALIGN\_MODELS\_HF`에서 확인할 수 있습니다. 감지된 언어가 이 목록에 없는 경우, [huggingface model hub](https://huggingface.co/models)에서 음소 기반 ASR 모델을 찾아 데이터로 테스트해야 합니다.
#### E.g. German
whisperx --model large-v2 --language de path/to/audio.wav
https://user-images.githubusercontent.com/36994049/208298811-e36002ba-3698-4731-97d4-0aebd07e0eb3.mov
다른 언어의 더 많은 예제는 [여기](EXAMPLES.md)에서 확인하세요.
## Python usage 🐍
```python
import whisperx
import gc
from whisperx.diarize import DiarizationPipeline
device = "cuda"
audio\_file = "audio.mp3"
batch\_size = 16 # reduce if low on GPU mem
compute\_type = "float16" # change to "int8" if low on GPU mem (may reduce accuracy)
# 1. Transcribe with original whisper (batched)
model = whisperx.load\_model("large-v2", device, compute\_type=compute\_type)
# save model to local path (optional)
# model\_dir = "/path/"
# model = whisperx.load\_model("large-v2", device, compute\_type=compute\_type, download\_root=model\_dir)
audio = whisperx.load\_audio(audio\_file)
result = model.transcribe(audio, batch\_size=batch\_size)
print(result["segments"]) # before alignment
# delete model if low on GPU resources
# import gc; import torch; gc.collect(); torch.cuda.empty\_cache(); del model
# 2. Align whisper output
model\_a, metadata = whisperx.load\_align\_model(language\_code=result["language"], device=device)
result = whisperx.align(result["segments"], model\_a, metadata, audio, device, return\_char\_alignments=False)
print(result["segments"]) # after alignment
# delete model if low on GPU resources
# import gc; import torch; gc.collect(); torch.cuda.empty\_cache(); del model\_a
# 3. Assign speaker labels
diarize\_model = DiarizationPipeline(token=YOUR\_HF\_TOKEN, device=device)
# add min/max number of speakers if known
diarize\_segments = diarize\_model(audio)
# diarize\_model(audio, min\_speakers=min\_speakers, max\_speakers=max\_speakers)
result = whisperx.assign\_word\_speakers(diarize\_segments, result)
print(diarize\_segments)
print(result["segments"]) # segments are now assigned speaker IDs
```
## Demos 🚀
[![Replicate (large-v3](https://img.shields.io/static/v1?label=Replicate+WhisperX+large-v3&message=Demo+%26+Cloud+API&c

olor=blue)](https://replicate.com/victor-upmeet/whisperx)
[![Replicate (large-v2](https://img.shields.io/static/v1?label=Replicate+WhisperX+large-v2&message=Demo+%26+Cloud+API&color=blue)](https://replicate.com/daanelson/whisperx)
[![Replicate (medium)](https://img.shields.io/static/v1?label=Replicate+WhisperX+medium&message=Demo+%26+Cloud+API&color=blue)](https://replicate.com/carnifexer/whisperx)
자체 GPU가 없는 경우, 위의 링크를 사용하여 WhisperX를 체험해 보세요.

## 기술적 세부사항 👷‍♂️

배치 처리(batching) 및 정렬(alignment), VAD의 영향, 그리고 선택된 정렬 모델에 대한 구체적인 내용은 사전 인쇄 [논문](https://www.robots.ox.ac.uk/~vgg/publications/2023/Bain23/bain23.pdf)을 참고하세요.
GPU 메모리 요구 사항을 줄이려면 다음 방법 중 하나를 시도해 보세요 (2번과 3번은 품질에 영향을 줄 수 있습니다):
1. 배치 크기 줄이기, 예: `--batch\_size 4`
2. 더 작은 ASR 모델 사용 `--model base`
3. 더 가벼운 연산 타입 사용 `--compute\_type int8`
openai의 whisper와의 전사(Transcription) 차이점:
1. 타임스탬프가 없는 전사. 단일 패스 배치 처리를 활성화하기 위해 whisper 추론은 `--without\_timestamps True`로 수행되며, 이는 배치 내 샘플당 1회의 순방향 전파(forward pass)를 보장합니다. 하지만 이로 인해 기본 whisper 출력과 차이가 발생할 수 있습니다.
2. openai의 버퍼링된 전사와 달리, VAD 기반 세그먼트 전사를 사용합니다. WhisperX 논문에서 이것이 WER을 낮추고 정확한 배치 추론을 가능하게 함을 보여줍니다.
3. `--condition\_on\_prev\_text`는 기본적으로 `False`로 설정되어 있습니다 (환각 현상 감소).

## 한계점 ⚠️

- 정렬 모델의 사전(dictionary)에 문자가 포함되지 않은 전사 단어들(예: "2014." 또는 "£13.60")은 정렬할 수 없으므로 타이밍이 부여되지 않습니다.
- 겹치는 음인은 whisper나 whisperx 모두에서 그다지 잘 처리되지 않습니다.
- 화자 다이어리제이션(diarization)은 완벽과는 거리가 멉니다.
- 언어별 wav2vec2 모델이 필요합니다.

## 기여하기 🧑‍🏫

다국어를 구사하신다면, 이 프로젝트에 기여할 수 있는 주요 방법은 huggingface에서 음소(phoneme) 모델을 찾거나(또는 직접 학습시키고) 타겟 언어의 음성으로 테스트해 보는 것입니다. 결과가 좋다면 풀 리퀘스트(pull request)와 성공을 보여주는 몇 가지 예시를 보내주세요.
이 프로젝트가 이미 원래의 연구 범위를 벗어나 계속 진행될 수 있도록 버그 제보와 풀 리퀘스트도 매우 감사히 받고 있습니다.

## 할 일 🗓

- [x] 다국어 초기화
- [x] 언어 감지 기반 자동 정렬 모델 선택
- [x] Python 사용법
- [x] 화자 다이어리제이션 통합
- [x] 낮은 GPU 메모리 자원을 위한 모델 플러시(flush)
- [x] Faster-whisper 백엔드
- [x] max-line 등 추가 (openai의 whisper utils.py 참고)
- [x] 문장 수준 세그먼트 (nltk 툴박스)
- [x] 정렬 로직 개선
- [ ] 다이어리제이션 및 단어 강조 기능이 포함된 예시 업데이트
- [ ] 자막 .ass 출력 <- 다시 추가 (v3에서 제거됨)
- [ ] 벤치마킹 코드 추가 (속도/WER 및 단어 세분화를 위한 TEDLIUM)
- [ ] 대안적인 VAD 옵션으로 silero-vad 허용
- [ ] 다이어리제이션 개선 (단어 수준). \_생각보다 어렵습니다...\_

## 연락처/지원 📇

문의 사항은 maxhbain@gmail.com으로 연락 주세요.
[![Buy Me A Coffee](https://cdn.buymeacoffee.com/buttons/default-orange.png)](https://www.buymeacoffee.com/maxhbain)

## 감사의 말 🙏

이 연구와 저의 박사 과정은 [VGG (Visual Geometry Group)](https://www.robots.ox.ac.uk/~vgg/)과 옥스퍼드 대학교의 지원을 받았습니다.
물론, 이 작업은 [openAI의 whisper](https://github.com/openai/whisper)를 기반으로 구축되었습니다.
[강제 정렬에 관한 PyTorch 튜토리얼](https://pytorch.org/tutorials/intermediate/forced\_alignment\_with\_torchaudio\_tutorial.html)에서 중요한 정렬 코드를 가져왔습니다.
그리고 훌륭한 pyannote VAD / 다이어리제이션 https://github.com/pyannote/pyannote-audio 을 사용합니다.
유용한 VAD 및 다이어리제이션 모델 출처:
- [pyannote-audio](https://github.com/pyannote/pyannote-audio) — [pyannoteAI](https://www.pyannote.ai)가 [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) 라이선스로 배포하는 [speaker-diarization-community-1](https://huggingface.co/pyannote/speaker-diarization-community-1) 모델 기반의 화자 다이어리제이션
- [silero-vad](https://github.com/snakers4/silero-vad)
[faster-whisper](https://github.com/guillaumekln/faster-whisper)와 [CTranslate2](https://github.com/OpenNMT/CTranslate2)의 훌륭한 백엔드
[재정적으로 이 연구를 지원해 주신 분들](https://www.buymeacoffee.com/maxhbain) 🙏
마지막으로, 이 프로젝트를 계속 이어가며 버그를 찾아주는 오픈소스 [기여자(contributors)](https://github.com/m-bain/whisperX/graphs/contributors)분들께 감사드립니다.

## 인용

본 연구를 사용할 때는 다음 논문을 인용해 주세요:
```bibtex
@article{bain2022whisperx,
title={WhisperX: Time-Accurate Speech Transcription of Long-Form Audio},
author={Bain, Max and Huh, Jaesung and Han, Tengda and Zisserman, Andrew},
journal={INTERSPEECH 2023},
year={2023}
}
```