Speech-to-Text
Download audio from any URL and transcribe it to text using Faster-Whisper.
Pipeline
One command does everything:
python scripts/transcribe.py "https://example.com/audio-url"
- Downloads audio via
yt-dlp(supports 1000+ sites) - Converts to 16kHz mono WAV for best quality
- Transcribes via Faster-Whisper (CTranslate2 accelerated)
- Outputs plain text
Options
| Flag | Default | Description |
|---|---|---|
--model, -m |
base |
Model: tiny / base / small / medium / large |
--language, -l |
zh |
Language code (zh, en, auto) |
--quantization, -q |
int8 |
Quantization: int8 / float16 / float32 |
--output, -o |
temp dir | Directory to save downloaded audio |
--download-only |
— | Download only, skip transcription |
Examples
# Default (base model, Chinese)
python scripts/transcribe.py "https://www.xiaoyuzhoufm.com/episode/xxx"
# English audio, small model
python scripts/transcribe.py "https://youtube.com/watch?v=xxx" -l en -m small
# Download only (save audio file)
python scripts/transcribe.py "https://youtube.com/watch?v=xxx" --download-only -o "D:\audio"
# High quality (medium model, float16 on GPU)
python scripts/transcribe.py "https://example.com/podcast.mp3" -m medium -q float16
Architecture
URL → yt-dlp (download) → ffmpeg (16kHz mono WAV) → Faster-Whisper (transcribe) → text
- Download:
yt-dlpextracts direct audio URL and downloads - Preprocessing:
ffmpegconverts to format required by Whisper (16kHz mono) - Model: Faster-Whisper (CTranslate2) — 2-4x faster than openai-whisper, runs on CPU
- VAD: Voice Activity Detection filters out non-speech segments
Dependencies
Installed automatically on first run:
- faster-whisper — transcription engine
- yt-dlp — audio extraction
Manually pre-install:
pip install faster-whisper yt-dlp
Models
| Model | Size | Speed | Accuracy |
|---|---|---|---|
tiny |
~75 MB | Fastest | Basic |
base |
~140 MB | Fast | Good (default) |
small |
~470 MB | Medium | Better |
medium |
~1.5 GB | Slow | High |
large |
~2.9 GB | Slowest | Highest |
First run downloads the model from HuggingFace (HF mirror for China).
Environment
- Auto-selects GPU/CPU (
cudaif torch.cuda.is_available()) - HF mirror:
https://hf-mirror.com(configured for China users) - Model cache:
.models/subdirectory in scripts folder (reusesfast-whisperskill cache if present) - ffmpeg checked at: system PATH,
D:\soft\ffmpeg\...\bin\ffmpeg.exe
Offline / Restricted Networks
If the network cannot reach HuggingFace, see references/install-offline.md for pre-downloading models and handling environments without internet access.
