WhisperX Transcribe — a Claude Code skill for meeting & video transcription

A Claude Code skill that transcribes local audio and video files — meetings, interviews, podcasts, lectures, standups, recorded calls — into a clean, speaker-labeled Markdown transcript, using WhisperX (Whisper + forced alignment + speaker diarization) under the hood.

The problem this solves: a one-hour meeting recording is far too long to hand an LLM directly, and raw Whisper/WhisperX output is a flat wall of timestamped JSON segments that's expensive and awkward for an LLM to read. This skill lets Claude offload the actual transcription to WhisperX, then hands itself back a tidy, skimmable Markdown document it can summarize, search, or quote from — without ever touching the raw audio or the raw JSON.

# Transcript: Q3 Planning Call
**Duration:** 05:50
**Language:** en
**Speakers:** 2 (Priya, Sam)

### [00:00] Priya
Hey everyone, thanks for joining the call today...

### [00:09] Sam
Sounds good, can you share your screen?

Why this exists

• Long recordings don't fit in an LLM's context window as raw audio or raw transcripts. Transcribing first and handing back structured Markdown lets Claude work with an hour-long meeting the same way it'd work with any other document.
• Raw WhisperX/Whisper JSON is not LLM-friendly. It's a flat list of 3–10 second segments with no higher-level structure — no sense of "who was talking", no skimmable sections, just timestamps and text.
• Speaker diarization turns a transcript into a conversation. Knowing that Speaker 2 raised an objection at 14:32 is far more useful than an undifferentiated stream of text.

Features

• 🎬 Any audio/video format ffmpeg supports — mp4, mov, mp3, wav, m4a, and more, no manual audio extraction needed
• 🗣️ Speaker diarization — optional speaker labels (Speaker 1, Speaker 2, ...), relabel with real names once you know who's who
• ⏱️ Word-accurate timestamps via wav2vec2 forced alignment (WhisperX's core contribution over vanilla Whisper)
• 📝 Clean Markdown output — speaker turns or time-chunked sections instead of a flat transcript wall, built specifically to be easy for an LLM (or a human) to skim
• ⚙️ Configurable — model size, language, device (CPU/CUDA), diarization, speaker count hints, chunk size
• 🛡️ Fails loud, not silent — a setup checker verifies ffmpeg/whisperx/torch/HF token before attempting a transcription, with actionable fixes instead of a cryptic crash halfway through

Installation

Option 1: Claude Code plugin marketplace (recommended)

/plugin marketplace add abubakarsiddik31/whisperx-transcribe
/plugin install whisperx-transcribe@whisperx-transcribe

Then /reload-plugins (or restart Claude Code) to activate it.

Option 2: Manual install script

curl -fsSL https://raw.githubusercontent.com/abubakarsiddik31/whisperx-transcribe/main/install.sh | bash

This clones the skill straight into ~/.claude/skills/whisperx-transcribe, no plugin system required. Re-run it any time to pull updates.

Option 3: Clone it yourself

git clone https://github.com/abubakarsiddik31/whisperx-transcribe.git ~/.claude/skills/whisperx-transcribe

Use one install method, not several — installing via both the plugin marketplace and a manual copy will register the skill twice.

WhisperX setup (one-time, separate from installing the skill)

Installing this skill does not install WhisperX itself — that's a separate, heavier dependency (ffmpeg, PyTorch, the whisperx Python package, and optionally a HuggingFace token for diarization). Check what's missing with:

python3 ~/.claude/skills/whisperx-transcribe/scripts/check_setup.py --diarize

Full install steps, the Apple Silicon / CUDA device gotcha, and troubleshooting are in references/SETUP.md.

Usage

Once installed, just ask Claude Code naturally — no need to say "WhisperX" or "transcribe" explicitly:

"Here's the recording from our standup, standup.mp4 — what did we decide about the release date?"

"Summarize this interview.mp4 and pull out the best quotes about pricing."

"This meeting is 90 minutes, way too long to read — give me the transcript and the action items."

Claude will run the setup check, transcribe with sensible defaults for your hardware, format the result into Markdown, and then answer your actual question from that Markdown instead of the raw audio.

You can also drive the scripts directly:

# 1. Transcribe (CPU example — see SETUP.md for GPU flags)
python3 scripts/transcribe.py meeting.mp4 --model medium --device cpu --compute_type int8

# 2. Format into clean Markdown
python3 scripts/format_transcript.py meeting.whisperx.json --speaker-names "Priya,Sam"

# Or batch-process a whole folder in one command (loads the model once, reuses it for every file)
python3 scripts/batch_transcribe.py --input-dir calls --pattern "*.mp3" \
    --diarize --min-speakers 2 --max-speakers 2 --output-dir transcripts

Heads up on first run: WhisperX downloads the model weights (and pyannote's diarization models, if you pass --diarize) the first time a given model is used. That can take several minutes and looks like nothing is happening — every run after that reuses the cached weights.

Model size guide

On CPU (which includes every Mac — WhisperX's backend doesn't support Apple Silicon's GPU), model size is the main lever on wall-clock time. Default to medium unless you have a GPU or need maximum accuracy and can wait.

How it works

video/audio file
      │  ffmpeg decode
      ▼
  Whisper (batched, via faster-whisper)  →  raw segments
      │  wav2vec2 forced alignment
      ▼
  word-accurate timestamps
      │  pyannote diarization (optional)
      ▼
  speaker-labeled segments  →  format_transcript.py  →  clean Markdown

See scripts/transcribe.py and scripts/format_transcript.py for the implementation, and SKILL.md for the full instructions Claude follows when it invokes this skill.

Repository structure

whisperx-transcribe/
├── .claude-plugin/
│   ├── plugin.json        # Claude Code plugin manifest
│   └── marketplace.json   # lets this repo self-host as a plugin marketplace
├── SKILL.md                # the skill definition Claude Code loads
├── scripts/
│   ├── check_setup.py      # dependency/environment checker
│   ├── transcribe.py       # WhisperX wrapper → raw JSON
│   ├── format_transcript.py # raw JSON → clean Markdown
│   └── batch_transcribe.py # transcribe + format many files in one run, model loaded once
├── references/
│   └── SETUP.md            # full install & troubleshooting guide
└── install.sh               # manual installer (non-plugin fallback)

Contributing

Issues and pull requests are welcome — in particular, real-world feedback on transcript formatting for long or unusual recordings (multi-language calls, heavy cross-talk, very long meetings) is the most useful kind.

Acknowledgments

• WhisperX by Max Bain et al. — the transcription, alignment, and diarization engine this skill wraps. See their paper for technical details.
• pyannote-audio for speaker diarization.
• faster-whisper / CTranslate2 for the inference backend.

License

MIT — this repository (the Claude Code skill/plugin wrapper). WhisperX itself is licensed separately by its authors; see the WhisperX repository for its license.