scribe-cli 0.17.0

Speech-to-text CLI and system-tray app for dictating into any focused window. Local (vosk, faster-whisper) or cloud (groq, openai) backends, batch or streaming.

Scribe

Talk. It types. Scribe is a speech-to-text CLI and tray app that pipes transcribed text straight into the focused window. It supports local and cloud-based APIs, batch and streaming workflows.

What it does

• Records from your mic and transcribes via one of four backends — Vosk (local, streaming), Whisper (local, batch), OpenAI (cloud, batch or streaming), Groq (cloud, batch).
• Delivers the transcript three ways: paste into the focused window (default), copy to clipboard, or print to the terminal.
• Runs as a system tray icon with a single Record button, or as an interactive terminal TUI — same menu in both.
• Hooks into your DE's keyboard shortcuts via SIGUSR1 (toggle recording) and SIGUSR2 (cancel).
• Cross-platform: tested on Ubuntu (X11 and Wayland), macOS, Windows; works under Termux for clipboard / terminal output.

Install

sudo apt-get install portaudio19-dev xclip   # Ubuntu; macOS: brew install portaudio
pip install scribe-cli[all]
export GROQ_API_KEY=YOURAPIKEY                # or OPENAI_API_KEY, or skip and run local

See documentation below for setting up keyboard input on Ubuntu Wayland.

Usage

In a terminal:

scribe

This launches the system tray icon. Press Record, speak, press Stop — the transcription lands in the focused window. Scribe picks the first backend whose key / dependency is present, in order groq → openai → whisper → vosk, so with GROQ_API_KEY set the command above is equivalent to:

scribe --backend groq --model whisper-large-v3-turbo

You can override the defaults or drop the tray entirely:

scribe --backend openai --model gpt-4o-mini-transcribe # OpenAI sweet spot
scribe --backend openai --model gpt-realtime-whisper   # OpenAI streaming
scribe --backend whisper --model small                 # local, no API key
scribe --frontend terminal                             # interactive TUI menu
scribe --frontend terminal --no-interactive            # record immediately, no menu
scribe --mode clipboard                                # copy to clipboard, no keystroke
scribe --mode terminal                                 # only print to stdout
scribe -o transcript.txt                               # also append to a file

With --no-interactive (terminal frontend only), scribe skips the interactive menu and starts recording right away — handy for scripted, one-shot transcriptions. --no-prompt is kept as a deprecated alias.

Bias the recogniser toward names, jargon, or a domain glossary with --prompt "free text hint" and --words word1 word2 ... (each also accepts a --prompt-file / --words-file companion). See docs/backends.md › Vocabulary biasing for what each backend does with them.

Backends at a glance

Backend	--backend	Default model	Streaming model(s)	Requires
Groq (cloud)	groq	whisper-large-v3-turbo	—	GROQ_API_KEY
OpenAI (cloud)	openai	gpt-4o-mini-transcribe	gpt-realtime-whisper	OPENAI_API_KEY
Whisper (local)	whisper	small	—	pip install scribe-cli[whisper]
Vosk (local)	vosk	language-dependent	all Vosk models	pip install scribe-cli[vosk]

Whether a transcription appears live as you speak or all at once when you stop depends on the model picked — see docs/backends.md.

Getting an API key

Groq is a good cloud backend to start with — very fast, quite accurate, and the free tier is generous enough for everyday dictation. Sign up at console.groq.com, create an API key under Settings → API Keys, and export it as GROQ_API_KEY.

I personally use OpenAI with gpt-4o-mini-transcribe as it is also fast and perhaps more accurate for my accent-tainted English.

Documentation

• Installation & dependencies — PortAudio, extras, Ubuntu / GNOME tray libs.
• Backends in detail — model lists, when to pick which, the realtime model.
• Keyboard modes & typer backends — keystroke vs clipboard, Wayland / eitype, --type-direct.
• System tray & global hotkeys — menu tree, icon states, SIGUSR1/SIGUSR2.
• Desktop entry & autostart (scribe-install) — GNOME / KDE launcher integration.
• Fine tuning & CLI reference — every scribe --help flag with examples.

Compatibility

Initially developed for Python 3 on Ubuntu 24.04 (GNOME + Wayland); works on macOS and Windows too. Wayland keystroke injection is convoluted but solved. For dependencies of individual subsystems, check pynput (keyboard) and pystray (tray icon).