WhisperX: install, diarization and word timestamps

by Max Bain

WhisperX is a free Whisper pipeline that adds word timestamps and speaker labels. Skip the install: WhipScribe transcribes it in your browser. Packs: $4 for 500 minutes, $12 for 2,000, $24 for 5,000; Workspace $19 a month. Up to 10 hours or 5 GB per file. Measured turnaround: about 2 minutes per audio hour. 99 languages. Checked 25 Oct 2026.

Don’t want to install whisperX? Drop the file here.

Every recording starts with a free preview of its opening minutes. Credits never expire.

Whisper plus word-aligned timestamps plus speaker labels in a single Python CLI. Max Bain's pipeline — faster-whisper for ASR, wav2vec2 forced alignment, pyannote diarization. Pick a recipe.

Linux, Windows, macOS (CPU)  ·  free

whisperX on your computer, or upload the file to WhipScribe

whisperXWhipScribe
Installpip install whisperx (or uvx whisperx) on Python 3.10 to 3.13; for a GPU, the CUDA toolkit 12.8 first12Nothing to install: upload the file in a browser. Transcribed on our own servers.
Model downloadA Whisper model, a language-specific wav2vec2 alignment model, and for speakers the gated pyannote model, downloaded on first run1None
PlatformsLinux and Windows with an NVIDIA GPU; CPU mode (--device cpu --compute_type int8) on any machine, including a Mac1Web, API, MCP
Speakers--diarize with a Hugging Face read token, after accepting the speaker-diarization-community-1 terms; the README says diarization is far from perfect13Named in the summary, key quotes and chapters
LanguagesAlignment models built in for en, fr, de, es, it, many more via Hugging Face; other languages need a phoneme model you find and test199+, detected automatically
PriceFree, BSD-2-Clause licence1A free preview of the opening minutes, then $4 for 500 minutes, $12 for 2,000 minutes, $24 for 5,000 minutes; Workspace $19 a month. Credits never expire.

whisperX column: the project’s own pages, numbered in the table.

  1. m-bain/whisperX · README (GitHub), fetched 26 Oct 2026
  2. whisperX · pyproject.toml (Python and torch versions), fetched 26 Oct 2026
  3. pyannote/speaker-diarization-community-1 (Hugging Face), fetched 26 Oct 2026

WhipScribe column: pricing and measured turnaround.

WhisperX install and speaker diarization, step by step

From the WhisperX README and pyproject.toml as of 26 Oct 2026 (latest stable release v3.8.6, 25 May 2026).

  1. GPU only: install the CUDA toolkit 12.8 first (Linux or Windows). Skip this on CPU.

  2. Install WhisperX in a fresh environment on Python 3.10 to 3.13.

    pip install whisperx
# or, without installing it globally
uvx whisperx

  3. Transcribe a file. The default model is Whisper small; --highlight_words True marks word timings in the .srt.

    whisperx path/to/audio.wav
whisperx path/to/audio.wav --model large-v2 --align_model WAV2VEC2_ASR_LARGE_LV60K_960H --batch_size 4

  4. For speaker labels: create a Hugging Face read token, accept the user agreement for pyannote/speaker-diarization-community-1, then pass the token. Set the speaker count if you know it.

    export HF_TOKEN="hf_..."
whisperx path/to/audio.wav --model large-v2 --diarize --hf_token "$HF_TOKEN" --min_speakers 2 --max_speakers 2

  5. No NVIDIA GPU, or on a Mac: run on the CPU with int8.

    whisperx path/to/audio.wav --compute_type int8 --device cpu

  6. Out of GPU memory: lower the batch size, pick a smaller model, or use int8 (the last two can cost accuracy).

    whisperx path/to/audio.wav --batch_size 4 --model base --compute_type int8

Sources:

  1. m-bain/whisperX · README (GitHub), fetched 26 Oct 2026
  2. whisperX · pyproject.toml (Python and torch versions), fetched 26 Oct 2026
  3. m-bain/whisperX · releases (v3.8.6, 25 May 2026), fetched 26 Oct 2026
  4. pyannote/speaker-diarization-community-1 (Hugging Face), fetched 26 Oct 2026

WhisperX vs Whisper: what WhisperX adds

Is WhisperX free? Yes: BSD-2-Clause. The pyannote diarization model is CC-BY-4.0 and gated behind its terms on Hugging Face.

WhisperX online: the README links Replicate demos for people without a GPU. To get a transcript without Python, upload the file at the top of this page instead.

OpenAI WhisperWhisperX
TimestampsPer utterance, and can be off by several secondsPer word, from wav2vec2 forced alignment
SpeedNo native batchingBatched faster-whisper backend: 70x realtime with large-v2 on a GPU, under 8 GB of GPU memory with beam_size 5
Speaker labelsNonepyannote diarization with --diarize
Segmenting long audioBuffered transcriptionVoice-activity segments; condition_on_prev_text off by default, which the README says reduces hallucination

Sources:

  1. m-bain/whisperX · README (GitHub), fetched 26 Oct 2026
  2. pyannote/speaker-diarization-community-1 (Hugging Face), fetched 26 Oct 2026

WhisperX: Python version, where models are cached, GitHub

QuestionAnswer
Does WhisperX need Python 3.12?No. pyproject.toml allows Python 3.10, 3.11, 3.12 and 3.13 (requires-python >=3.10, <3.14).
Where is the Hugging Face token used?Only for speaker labels: --hf_token is the token for the gated pyannote model, speaker-diarization-community-1.
Where is the wav2vec2 alignment model cached?In --model_dir when you pass it. Otherwise en, fr, de, es and it use torchaudio checkpoints, saved in the PyTorch hub folder (~/.cache/torch/hub, or $TORCH_HOME/hub); other languages use Hugging Face models in ~/.cache/huggingface/hub (or $HF_HOME).
Can it run without downloading?--model_cache_only True uses only models already in --model_dir.
Where is the code?github.com/m-bain/whisperX

Sources:

  1. whisperX · pyproject.toml (Python and torch versions), fetched 26 Oct 2026
  2. whisperX · __main__.py (CLI flags), fetched 26 Oct 2026
  3. whisperX · alignment.py (load_align_model), fetched 26 Oct 2026
  4. PyTorch docs · torch.hub, where downloaded models are saved, fetched 26 Oct 2026
  5. Hugging Face docs · cache layout, fetched 26 Oct 2026
TL;DR

WhisperX is a three-stage pipeline glued into one CLI and Python API. Stage 1 transcribes with faster-whisper (CTranslate2-backed Whisper, batched decode). Stage 2 runs wav2vec2 forced alignment so every word lands on a real audio boundary, not Whisper's drifted segment-level timestamps. Stage 3 calls pyannote.audio (the speaker-diarization-community-1 model) for speaker diarization and assigns each aligned word to a speaker label.

Best for anywhere who said what when matters: podcast post-production, interview transcripts, meeting recordings, captioning workflows that need karaoke-style word highlighting, and research datasets with speaker turns. License: BSD-2-Clause on WhisperX itself; the pyannote models it downloads are gated on Hugging Face and have their own terms — read those before commercial deployment. Latest stable: v3.8.6 (25 May 2026), paper at arXiv:2303.00747 (INTERSPEECH 2023).

Category
Open source
License
BSD-2-Clause
Stars
★ 23.9k
Last push
2026-08-30
Pricing
free
Platforms
Linux, Windows, macOS (CPU)

What it is

whisperX combines faster-whisper with forced alignment (wav2vec2) for word-accurate timestamps and pyannote for speaker diarization. If your audio has more than one speaker and you care about proper "Speaker 1 / Speaker 2" labeling, this is the open-source default. BSD-2 licensed.

Best for: Multi-speaker content (podcasts, interviews, meetings) where "who said what" matters.
Watch out for: Diarization needs a Hugging Face token and the pyannote model terms accepted; words without characters in the alignment dictionary ("2014.", "£13.60") get no timing; overlapping speech is weak.

Install / use

pip install whisperx

Setting whisperX up or fixing an error? whisperX setup guide and common fixes.

Use cases · pick the workflow that matches

WhisperX earns its place when alignment and diarization both matter. These are the workflows the README, Discussions, and the paper authors call out as primary fits — each card links the relevant section so you can jump straight to the right recipe.

Podcast post-production
Speaker turns + word timestamps for show notes and chapters

Two-host or guest interviews where you need accurate speaker labels for show notes, transcript pages, and chapter markers. WhisperX gives you per-word speaker attribution out of the box — drop it into a post-prod script and you get a publishable transcript without manual labeling.


Pair --diarize with --min_speakers and --max_speakers when you already know how many voices to expect.
Interview and meeting recordings
Single-channel mic captures with overlapping speech

Field interviews, sales calls, customer-research sessions, internal meetings — typically recorded on one channel with no per-speaker isolation. WhisperX runs VAD-based segmentation before transcribe, then pyannote (speaker-diarization-community-1) for clustering, which holds up reasonably on 2–6 speakers without per-mic separation.


VAD cuts long silences; batched faster-whisper decodes the chunks; pyannote labels them. Set HF_TOKEN once for diarization.
Subtitles with word highlighting
SRT/VTT with --highlight_words for karaoke captions

Word-by-word karaoke captioning needs every word boundary to match the audio. Whisper's native segment-level timestamps are too coarse — they drift by hundreds of milliseconds. The wav2vec2 alignment pass fixes this, and --highlight_words emits an SRT with the current word boldened per frame.


Output formats: srt, vtt, txt, tsv, json, aud. Use --highlight_words True for karaoke SRTs.
Video editor handoff
Premiere / DaVinci / Final Cut compatible exports

Word-accurate timestamps are the input format text-based video editors expect. Export WhisperX's per-word JSON, then feed it into Premiere's caption track or DaVinci Resolve's subtitle import. Speaker labels survive the round-trip so editors can color-code talking heads on the timeline.


JSON output preserves word-level start/end + speaker fields. tsv is the easiest to inspect by hand.
Research and dataset prep
ASR training data with speaker turns + forced alignment

Building speech datasets, training a downstream model, or running linguistics analysis on conversational corpora. WhisperX is the closest open-source pipeline to a one-shot dataset annotator — Whisper transcript, wav2vec2 alignment for word boundaries, pyannote turns. Cite arXiv:2303.00747.


Per-language --align_model override: WAV2VEC2_ASR_LARGE_LV60K_960H for English, language-specific checkpoints for non-English.
Batch transcription on a GPU box
70× realtime on large-v2 · <8 GB VRAM at beam 5

Throughput-mode on a single GPU. The README's own benchmarks show ~70× realtime on large-v2 with batched faster-whisper and under 8 GB of VRAM at beam_size=5. Drop --compute_type int8 for half the VRAM at a small WER cost, useful on 6–8 GB consumer cards.


Tune --batch_size to fit VRAM (4 on 6 GB, 8 on 8 GB, 16+ on 16 GB). --compute_type int8 for laptops.
The stack underneath: WhisperX is glue. Read faster-whisper for the transcription engine and openai/whisper for the reference model. Streaming is out of scope — try Vosk or Deepgram for that.

Setup recipes · pick one and copy

Three runnable configurations covering the most common WhisperX deployments. All blocks target whisperx 3.8.x (CUDA toolkit 12.8 for a GPU). Replace ${HF_TOKEN} with your own Hugging Face access token from hf.co/settings/tokens ↗.

1Install + first transcript (CLI)

pip install · single command CLI · SRT subtitles in one shot. The fastest way to verify the install works.

# whisperx 3.8.x · Python 3.10–3.13 · CUDA toolkit 12.8 for GPU
pip install whisperx

# transcribe a file, write subtitles
whisperx input.mp3 \
  --model large-v3 \
  --compute_type float16 \
  --batch_size 16 \
  --output_format srt

# CPU-only laptop fallback
whisperx input.mp3 \
  --model medium \
  --device cpu \
  --compute_type int8 \
  --batch_size 4
Source: m-bain/whisperX · Setup ↗. PyPI: whisperx ↗
2With speaker diarization (CLI)

Accept the pyannote model terms on Hugging Face first, then pass --diarize with your HF_TOKEN. Outputs per-word speaker labels.

# 1. Sign in at https://hf.co and accept the user agreement on:
#      https://huggingface.co/pyannote/speaker-diarization-community-1
# 2. Create a read token at https://hf.co/settings/tokens
# 3. Export it (never hardcode):
export HF_TOKEN="hf_...your_token_here..."

# 4. Transcribe + align + diarize in one pass
whisperx input.mp3 \
  --model large-v3 \
  --diarize \
  --hf_token "${HF_TOKEN}" \
  --min_speakers 2 \
  --max_speakers 4 \
  --output_format srt

# karaoke-style word highlighting in the SRT
whisperx input.mp3 --model large-v3 --diarize \
  --hf_token "${HF_TOKEN}" --highlight_words True --output_format srt
Diarization runs on pyannote/speaker-diarization-community-1 ↗ (gated, CC-BY-4.0), per the WhisperX README checked 26 Oct 2026. Accept its terms on the model card before the token works.
3Python API · transcribe + align + diarize

Three-stage call: load_model → load_align_model + align → DiarizationPipeline + assign_word_speakers. The pattern from the README.

import os
import whisperx
from whisperx.diarize import DiarizationPipeline

device = "cuda"
batch_size = 16
compute_type = "float16"   # "int8" on low-VRAM GPUs
audio_file = "input.mp3"
HF_TOKEN = os.environ["HF_TOKEN"]   # never hardcode

# 1. Transcribe (faster-whisper under the hood)
model = whisperx.load_model("large-v3", device, compute_type=compute_type)
audio = whisperx.load_audio(audio_file)
result = model.transcribe(audio, batch_size=batch_size)

# 2. Forced alignment (wav2vec2)
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,
)

# 3. Diarize + assign speakers to each word
diarize_model = DiarizationPipeline(token=HF_TOKEN, device=device)
diarize_segments = diarize_model(audio, min_speakers=2, max_speakers=4)
result = whisperx.assign_word_speakers(diarize_segments, result)

for seg in result["segments"]:
    speaker = seg.get("speaker", "?")
    print(f"[{seg['start']:6.2f} -> {seg['end']:6.2f}] {speaker}: {seg['text']}")
Source: m-bain/whisperX · Python usage ↗. Returned result["segments"] carries per-word start, end, word, and speaker fields after step 3.

What people actually do with whisperX-style transcription

The tool is the means. These are the jobs — each one priced at published rates, each one wired up on its own page.

Transcribe a whole back catalogue in one runThe archive is the asset, but one-at-a-time upload means it never gets done.…1,000 hours ≈ $480, onceTranscribe every new file in a Drive folderFiles accumulate in a folder nobody opens, and the knowledge in them is invisible to search.…≈ $0.29 per audio hour on the $24 packCut short-form clips out of a webinar automaticallyThe clips worth posting are buried somewhere in a 60-minute recording and finding them by scrubbing costs more than the…60-min webinar ≈ $0.48

Wire it into Amazon S3n8nMake.comGoogle DriveZapierSlack

Features

Speaker diarizationYes
Word-level timestampsYes
Streaming / real-timeNo
Languages supported99
HIPAA eligibleNo

Links

whisperX vs Whipscribe

FeaturewhisperXWhipscribe
CategoryOpen sourceTranscription APIs
Pricingfree$4–$24 one-time packs (credits never expire) · free preview of the opening minutes
Speaker identificationYesNamed in the summary, key quotes and chapters
Word timestampsYesYes
StreamingNoNo
Languages9999
PlatformsLinux, Windows, macOS (CPU)Web, API, MCP

Alternatives to whisperX

OpenAI Whisper
OpenAI

The reference open-source multilingual ASR model from OpenAI.

OSS · MIT ★ 111.4k
whisper.cpp
Georgi Gerganov

C/C++ port of Whisper — runs on anything, from a Raspberry Pi to Apple Silicon.

OSS · MIT ★ 54.7k
faster-whisper
SYSTRAN

4× faster than reference Whisper using CTranslate2 — production sweet spot.

OSS · MIT ★ 26.2k

Frequently asked about whisperX

How does whisperX forced alignment work?

whisperX transcribes with faster-whisper, then runs a second pass with a wav2vec2 phoneme model that aligns each word to the audio waveform. That forced-alignment pass is what turns Whisper's coarse segment timestamps into word-accurate ones, which is why whisperX is the standard pick for subtitles, karaoke-style highlighting, and clip cutting.

How do I use whisperX for alignment only, on an existing transcript?

whisperX exposes the aligner as a separate step: load an alignment model with load_align_model() for your language, then call align() with your existing segments and the audio. You can feed it segments from any Whisper variant — it does not need to have produced the transcript itself.

How do I download and install whisperX?

pip install whisperx (or uvx whisperx) on Python 3.10 to 3.13. For a GPU, install the CUDA toolkit 12.8 first. Diarization additionally needs a free Hugging Face read token and the speaker-diarization-community-1 terms accepted (README and pyproject.toml, checked 26 Oct 2026).

Can I use whisperX online without installing anything?

The WhisperX README links community demos on Replicate for people without a GPU. If you want a transcript without a GPU or Python setup, WhipScribe runs the transcription on its own servers: drop a file, download the result as SRT, VTT, DOCX, TXT, or JSON.

Does whisperX support streaming or real-time transcription?

No. whisperX is batch-only — the forced-alignment pass needs the completed audio. For live captioning look at whisper.cpp's stream mode, Vosk, or Deepgram.

Does whisperX do speaker diarization?

Yes — that's the headline feature. whisperX integrates pyannote for 'Speaker 1 / Speaker 2' labeling on top of faster-whisper transcription, producing per-word speaker-attributed output.

Why does whisperX need a HuggingFace token?

The pyannote diarization model it uses, speaker-diarization-community-1, is gated on Hugging Face: you accept its user agreement once and pass a read token with --hf_token. No cost, just an acceptance step.

How accurate are whisperX timestamps?

More accurate than vanilla Whisper at the word level. whisperX runs forced alignment (wav2vec2) over the transcript so word boundaries match the audio — good for subtitles, short-form clips, and speaker-attributed transcripts.

What license is whisperX?

BSD-2-Clause. Note that the pyannote models it downloads have their own terms; read those before commercial deployment.

Does whisperX support streaming?

No. whisperX is batch-only. For streaming ASR, look at Deepgram, Vosk, or whisper.cpp's stream example.

What is whisperX?

WhisperX is a three-stage pipeline glued into one CLI and Python API. Stage 1 transcribes with faster-whisper (CTranslate2-backed Whisper, batched decode). Stage 2 runs wav2vec2 forced alignment so every word lands on a real audio boundary, not Whisper's drifted segment-level timestamps. Stage 3 calls pyannote.audio (the speaker-diarization-community-1 model) for speaker diarization and assigns each aligned word to a speaker label.

Is whisperX free?

Yes. whisperX is free and open source.

Does whisperX work on Mac, Windows and Linux?

whisperX runs on Linux, Windows and macOS (CPU).

How many languages does whisperX support?

whisperX lists 99 languages. That is the Whisper-family multilingual set, so quality varies by language — English and the large European languages are strongest.

Is whisperX HIPAA compliant?

whisperX does not claim HIPAA compliance. For PHI, run it on infrastructure you control or choose a service that will sign a BAA.

Whipscribe is a hosted transcription service. If you want transcripts without running infrastructure, paste a URL or drop a file in the form below — you'll have a transcript in seconds.

Transcribe your recordings

Running whisperX yourself? Send the same file here and compare the transcript. Transcribe any language, any recording · Transcription services from $0.29 an hour · Transcribe from any meeting or recording platform · How to transcribe, step by step

Explore

All transcription tools · By language · By platform · By file format · How-to guides · Transcription services · Transcription API · Pricing

Related

Have the recording already?

Skip the setup and send the file or the link: see how to transcribe an MP3 of any length, how to transcribe a podcast and an SRT subtitle file from any recording.

Rather have it done for you?

Free tools cost setup time. When you want a finished transcript instead: see transcription services from $4.