Local speech-to-text using faster-whisper. 4-6x faster than OpenAI Whisper with identical accuracy; GPU acceleration enables ~20x realtime transcription. Supports standard and distilled models with word-level timestamps.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Local speech-to-text using faster-whisper. 4-6x faster than OpenAI Whisper with identical accuracy; GPU acceleration enables ~20x realtime transcription. Supports standard and distilled models with word-level timestamps.
Local speech-to-text using faster-whisper โ a CTranslate2 reimplementation of OpenAI's Whisper that runs 4-6x faster with identical accuracy. With GPU acceleration, expect ~20x realtime transcription (a 10-minute audio file in ~30 seconds).
.en models are English-only and slightly faster/better for English content.
Setup
Linux / macOS / WSL2
# Run the setup script (creates venv, installs deps, auto-detects GPU)
./setup.sh
Windows (Native)
# Run from PowerShell (auto-installs Python & ffmpeg if missing via winget)
.\setup.ps1
The Windows setup script will:
Auto-install Python 3.12 via winget if not found
Auto-install ffmpeg via winget if not found
Detect NVIDIA GPU and install CUDA-enabled PyTorch
Create venv and install all dependencies
Requirements:
Linux/macOS/WSL2: Python 3.10+, ffmpeg
Windows: Nothing! Setup auto-installs prerequisites via winget
Platform Support
Platform
Acceleration
Speed
Auto-Install
Windows + NVIDIA GPU
CUDA
~20x realtime ๐
โ Full
Linux + NVIDIA GPU
CUDA
~20x realtime ๐
Manual prereqs
WSL2 + NVIDIA GPU
CUDA
~20x realtime ๐
Manual prereqs
macOS Apple Silicon
CPU*
~3-5x realtime
Manual prereqs
macOS Intel
CPU
~1-2x realtime
Manual prereqs
Windows (no GPU)
CPU
~1x realtime
โ Full
Linux (no GPU)
CPU
~1x realtime
Manual prereqs
*faster-whisper uses CTranslate2 which is CPU-only on macOS, but Apple Silicon is fast enough for practical use.
GPU Support (IMPORTANT!)
The setup script auto-detects your GPU and installs PyTorch with CUDA. Always use GPU if available โ CPU transcription is extremely slow.
Hardware
Speed
9-min video
RTX 3070 (GPU)
~20x realtime
~27 sec
CPU (int8)
~0.3x realtime
~30 min
If setup didn't detect your GPU, manually install PyTorch with CUDA:
Linux/macOS/WSL2:
# For CUDA 12.x
uv pip install --python .venv/bin/python torch --index-url https://download.pytorch.org/whl/cu121
# For CUDA 11.x
uv pip install --python .venv/bin/python torch --index-url https://download.pytorch.org/whl/cu118
Windows:
# For CUDA 12.x
.venv\Scripts\pip install torch --index-url https://download.pytorch.org/whl/cu121
# For CUDA 11.x
.venv\Scripts\pip install torch --index-url https://download.pytorch.org/whl/cu118
# Basic transcription
./scripts/transcribe audio.mp3
# With specific model
./scripts/transcribe audio.wav --model large-v3-turbo
# With word timestamps
./scripts/transcribe audio.mp3 --word-timestamps
# Specify language (faster than auto-detect)
./scripts/transcribe audio.mp3 --language en
# JSON output
./scripts/transcribe audio.mp3 --json
Windows (cmd or PowerShell):
# Basic transcription
.\scripts\transcribe.cmd audio.mp3
# With specific model
.\scripts\transcribe.cmd audio.wav --model large-v3-turbo
# With word timestamps (PowerShell native syntax also works)
.\scripts\transcribe.ps1 audio.mp3 -WordTimestamps
# JSON output
.\scripts\transcribe.cmd audio.mp3 --json
Options
--model, -m Model name (default: distil-large-v3)
--language, -l Language code (e.g., en, es, fr - auto-detect if omitted)
--word-timestamps Include word-level timestamps
--beam-size Beam search size (default: 5, higher = more accurate but slower)
--vad Enable voice activity detection (removes silence)
--json, -j Output as JSON
--output, -o Save transcript to file
--device cpu or cuda (auto-detected)
--compute-type int8, float16, float32 (default: auto-optimized)
--quiet, -q Suppress progress messages
Examples
# Transcribe YouTube audio (after extraction with yt-dlp)
yt-dlp -x --audio-format mp3 <URL> -o audio.mp3
./scripts/transcribe audio.mp3
# Batch transcription with JSON outputfor file in *.mp3; do
./scripts/transcribe "$file" --json > "${file%.mp3}.json"done# High-accuracy transcription with larger beam size
./scripts/transcribe audio.mp3 \
--model large-v3-turbo --beam-size 10 --word-timestamps
# Fast English-only transcription
./scripts/transcribe audio.mp3 \
--model distil-medium.en --language en
# Transcribe with VAD (removes silence)
./scripts/transcribe audio.mp3 --vad
Common Mistakes
Mistake
Problem
Solution
Using CPU when GPU available
10-20x slower transcription
Check nvidia-smi on Windows/Linux; verify CUDA installation
Not specifying language
Wastes time auto-detecting on known content
Use --language en when you know the language
Using wrong model
Unnecessary slowness or poor accuracy
Default distil-large-v3 is excellent; only use large-v3 if accuracy issues
Ignoring distilled models
Missing 6x speedup with <1% accuracy loss
Try distil-large-v3 before reaching for standard models
Forgetting ffmpeg
Setup fails or audio can't be processed
Setup script handles this; manual installs need ffmpeg separately
Out of memory errors
Model too large for available VRAM/RAM
Use smaller model or --compute-type int8
Over-engineering beam size
Diminishing returns past beam-size 5-7
Default 5 is fine; try 10 for critical transcripts
Performance Notes
First run: Downloads model to ~/.cache/huggingface/ (one-time)
GPU: Automatically uses CUDA if available (~10-20x faster)
Quantization: INT8 used on CPU for ~4x speedup with minimal accuracy loss
Memory:
distil-large-v3: ~2GB RAM / ~1GB VRAM
large-v3-turbo: ~4GB RAM / ~2GB VRAM
tiny/base: <1GB RAM
Why faster-whisper?
Speed: ~4-6x faster than OpenAI's original Whisper
Accuracy: Identical (uses same model weights)
Efficiency: Lower memory usage via quantization
Production-ready: Stable C++ backend (CTranslate2)
Distilled models: ~6x faster with <1% accuracy loss
Troubleshooting
"CUDA not available โ using CPU": Install PyTorch with CUDA (see GPU Support above)
Setup fails: Make sure Python 3.10+ is installed
Out of memory: Use smaller model or --compute-type int8Slow on CPU: Expected โ use GPU for practical transcription
Model download fails: Check ~/.cache/huggingface/ permissions (Linux/macOS) or %USERPROFILE%\.cache\huggingface\ (Windows)
Windows-Specific
"winget not found": Install App Installer from Microsoft Store, or install Python/ffmpeg manually
"Python not in PATH after install": Close and reopen your terminal, then run setup.ps1 again
PowerShell execution policy error: Run Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned or use transcribe.cmd instead
nvidia-smi not found but have GPU: Install NVIDIA drivers โ the Game Ready or Studio drivers include nvidia-smi
