omni-transcriber

Transcribe anything from the command line: a YouTube link, an Instagram reel, any yt-dlp-supported URL, a local video or audio file, or a whole folder of media. Transcription runs locally via faster-whisper — no API key, no audio leaves your machine.

$ transcriber https://youtu.be/jNQXAC9IVRw
Alright, so here we are, one of the elephants...

$ transcriber lecture.mp4 -f srt -o lecture.srt
$ transcriber ~/podcasts -r -m turbo -o transcripts/

Install

Needs Python 3.10 or newer. uv is the smoothest route, but pipx and pip work too.

$ uv tool install omni-transcriber      # or: pipx install omni-transcriber
$ uvx omni-transcriber --help           # or run it without installing

With NVIDIA GPU acceleration:

$ uv tool install "omni-transcriber[gpu]"

The [gpu] extra is never required. On a machine with an NVIDIA card but no [gpu] install, --device cuda prints a warning and falls back to the CPU rather than failing.

Optional companions

• A JavaScript runtime — YouTube increasingly needs one. Deno is yt-dlp's preferred runtime; Node.js also works. transcriber enables whichever it finds on your PATH automatically. Without one, some videos lose formats or fail outright.
• ffmpeg — not used for transcription (the bundled PyAV decoder reads audio straight out of any container). yt-dlp needs it only for a few stream types; if it is missing when that happens, a static build is fetched automatically.

Usage

transcriber INPUTS...            files, folders, and/or URLs — mix freely

ots is installed as a shorter alias for the same command — ots lecture.mp4 does exactly what transcriber lecture.mp4 does. (If you also use OpenTimestamps, which ships its own ots, one will shadow the other on your PATH; transcriber always works.)

Where output goes

• One input, no -o → the transcript goes to stdout, so it pipes: transcriber talk.mp4 | wc -w. Progress bars and warnings all go to stderr.
• -o FILE → that exact file.
• Several inputs, a folder, a playlist, or -o DIR/ → one <title>.<format> file per item.

Existing transcripts are skipped with a notice rather than overwritten, so re-running an interrupted batch resumes it for free. Pass --overwrite to redo them. A batch keeps going when one item fails and prints a summary at the end; the exit code is 1 if anything failed.

Models

Whisper models are downloaded once, on first use, to the HuggingFace cache (~/.cache/huggingface).

Add .en to tiny/base/small/medium for slightly better English-only accuracy. Any HuggingFace CTranslate2 repo id or local model directory also works.

Speed: on an RTX 5070 Ti, small transcribes 468 s of audio in 3.7 s; the same job on CPU takes 122 s.

Authentication for private media

Instagram reels, members-only videos, and anything else behind a login need your browser's cookies:

$ transcriber <reel-url> --cookies-from-browser firefox -f md -t
$ transcriber <reel-url> --cookies cookies.txt

Windows note: Chrome's app-bound cookie encryption usually defeats --cookies-from-browser chrome. Use Firefox, or export a cookies.txt with a browser extension and pass --cookies.

Exit codes

Development

From a checkout:

$ uv sync                       # dev environment
$ uv run pytest                 # fast tests: no network, no models
$ uv run pytest -m slow         # real tiny-model smoke test (~75 MB, once)
$ uv run ruff check . && uv run ruff format .

CI runs the suite on Linux, macOS, and Windows across Python 3.10 and 3.12. Python 3.10 through 3.14 are verified locally on Linux.

License

MIT — see LICENSE.