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

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

• 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:

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

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.