Whisper transcribe

whisper-transcribe — GPU meeting transcription

Batteries-included transcription for Steve's environment. Defaults tuned for 会议录音 on H100/H200 GPUs.

When to use

• User says "转录", "transcribe", "字幕", "会议录音", "听写", "记录一下这个录音"
• User provides an audio/video path (.m4a, .mp3, .wav, .mp4, .m4v, .mov)
• Need text from audio: meetings, podcasts, interviews, lectures, screen recordings

Quick start

# Default: WhisperX large-v3, bs=16, auto language (best for Chinese+English meetings)
~/.claude/skills/whisper-transcribe/scripts/transcribe.sh <audio_file>

# Output files written to same dir as input:
#   <input>.txt                 plain transcript
#   <input>.segments.txt        [timestamp] text lines
#   <input>.json                full WhisperX JSON

Common invocations

Use case	Command
Default (meeting, auto)	transcribe.sh meeting.m4a
Chinese only (faster, monolingual only)	transcribe.sh meeting.m4a --lang zh
English only (monolingual only)	transcribe.sh meeting.m4a --lang en
Fast mode (bs=32, nearly identical quality)	transcribe.sh meeting.m4a --fast
Quality mode (bs=8, slightly better)	transcribe.sh meeting.m4a --quality
Speaker diarization (who said what)	transcribe.sh meeting.m4a --diarize
SRT subtitles	transcribe.sh video.mp4 --srt
Word-level timestamps	transcribe.sh audio.wav --words

Performance (H100 80GB, benchmarked 2026-05-05)

Audio length	Expected wall time	Realtime factor
10 min	~7s	90x
30 min	~20s	90x
60 min	~40s	90x
2 hours	~80s	90x

• Model: Whisper large-v3 fp16 via CTranslate2
• VAD: Pyannote V3 (auto-splits silence, handles code-switching)
• GPU util: ~50% avg SM activity, ~26% compute utilization (memory-bound, normal)
• VRAM: ~10 GB at bs=16, ~15 GB at bs=32

Why this skill

Compared alternatives on 54-min Chinese-English meeting:

Method	Time	Quality	Notes
openai-whisper (stock)	18 min	❌ mixes zh/en	Baseline
faster-whisper bs=32	28s	⚠️ mixes zh/en in segments	Fastest
WhisperX bs=16 (this skill)	36s	✅ Correct zh/en segmentation	Best balance

WhisperX wins on quality: Pyannote VAD correctly segments Chinese-English code-switched speech into language-consistent chunks.

Requirements

Already installed in Steve's env (verified 2026-05-05):

• whisperx (pip) — includes faster-whisper + Pyannote
• ffmpeg at /opt/ffmpeg/bin/ffmpeg (for audio conversion)
• CUDA-capable GPU (H100/H200/A100)
• HuggingFace token cached (for Pyannote VAD model, only needed once)

If running on a fresh machine, the setup script handles everything:

~/.claude/skills/whisper-transcribe/scripts/setup.sh

Agent guidance

Default is the right answer 99% of the time. Just run:

~/.claude/skills/whisper-transcribe/scripts/transcribe.sh <audio>

Only add flags when the user explicitly asks:

• --lang zh / --lang en → only when audio is truly monolingual. Forcing a single language on code-switched audio causes hallucination loops. Leave blank for mixed zh/en — auto-detect + VAD handle it correctly.
• --diarize → user asks "谁说了什么", "who said what", speaker labels
• --srt → user asks for subtitles
• --fast → user says "快一点", "quick", "draft quality is fine"
• --quality → user says "最高质量", "highest accuracy"
• --words → user asks for word-level timestamps or karaoke-style output

After transcription:

• For short files (<5 min), show a preview of the text to user
• For long files, summarize + mention output file paths
• If the audio is a meeting, offer to summarize key points / extract TODOs

Troubleshooting

Problem	Fix
Failed to load audio	The raw WAV may lack a header; script auto-reconverts via ffmpeg
CUDA OOM	Use --fast with lower batch (8 or 4) via --bs 4
Poor quality on a single language	Explicitly set --lang zh or --lang en
Missing HF token (for diarization)	Run huggingface-cli login once
Model download slow	First run downloads ~3 GB to ~/.cache/huggingface/; subsequent runs are cached

Script contract

scripts/transcribe.sh behavior:

1. Accepts any audio/video path (m4a, mp3, wav, mp4, mov, mkv, webm)
2. Converts to 16kHz mono WAV via ffmpeg if needed (cached next to input)
3. Runs WhisperX large-v3 fp16 on CUDA
4. Writes 3 outputs next to input file:
   • <name>.txt — plain transcript (joined segments)
   • <name>.segments.txt — [NNNs] text timestamped lines
   • <name>.json — full WhisperX result (includes word timings if --words)
5. On stderr: progress, GPU utilization sample, final timing summary

Exit codes: 0 success, 1 bad input, 2 transcription error, 3 missing dependency.