Download a YouTube video, transcribe the audio locally with mlx-whisper, save as Markdown.
Built for Apple Silicon (M-series). Tested on M3 Pro.
Requires ffmpeg on PATH and uv:
brew install ffmpeg uv
uv syncuv run yt-stt https://www.youtube.com/watch?v=VIDEO_IDOutput goes to output/<slug>.md. Audio is cached in cache/audio/<video-id>.m4a so re-running on the same URL skips the download.
| Flag | Default | Notes |
|---|---|---|
--model |
turbo |
One of turbo, large-v3, medium, small, tiny. |
--output-dir |
./output |
Where the .md is written. |
--cache-dir |
./cache/audio |
Where downloaded audio is kept. |
-v / --verbose |
off | DEBUG logging. |
A short Creative Commons clip suitable for a first run: https://www.youtube.com/watch?v=jNQXAC9IVRw (~19 s, "Me at the zoo"). The first run also downloads the model (~1.5 GB for turbo).
Quantized MLX checkpoints from mlx-community on Hugging Face:
--model |
Repo | Disk | Notes |
|---|---|---|---|
turbo (default) |
mlx-community/whisper-large-v3-turbo |
~1.5 GB | Sweet spot on M3 Pro. |
large-v3 |
mlx-community/whisper-large-v3-mlx |
~3 GB | Slowest; highest accuracy. |
medium |
mlx-community/whisper-medium-mlx |
~1.5 GB | |
small |
mlx-community/whisper-small-mlx |
~500 MB | |
tiny |
mlx-community/whisper-tiny-mlx |
~75 MB | Useful for sanity checks. |
Models are cached by huggingface_hub under ~/.cache/huggingface/hub/.
See CLAUDE.md for architecture and conventions.
uv run ruff check
uv run ruff format
uv run pytest