simple-stt

Hotkey-driven audio capture for Ubuntu/Pop!_OS (X11/GNOME-style setup) that records to a tiny .opus, transcribes it, saves both files to ~/Transcripts, and copies the transcript directly to your clipboard.

What it does

• Press Ctrl+Shift+Alt+3 to start recording
• Press Ctrl+Shift+Alt+3 again to stop recording and transcribe
• Saves audio as ~/Transcripts/YYYY-MM-DD_HH-MM-SS.opus
• Saves text as ~/Transcripts/YYYY-MM-DD_HH-MM-SS.txt
• Copies the transcription to the clipboard automatically

Install from source

cd simple-stt
bash install.sh

That installs simple-stt to /usr/local/bin. Run the interactive setup wizard to configure everything:

simple-stt --setup

Note: If the keyboard shortcut doesn't work immediately after setup, restart GNOME Shell: Alt+F2 → type r → Enter. This is often required for GNOME to pick up new custom keybindings.

STT backends

The recorder supports three transcription paths, in this order:

1. SIMPLE_STT_COMMAND custom command
2. local whisper CLI
3. OpenAI transcription API via OPENAI_API_KEY

Option 1: custom command

Set a command that prints the transcript to stdout. The script exposes these env vars:

• SIMPLE_STT_INPUT — path to the recorded .opus
• SIMPLE_STT_OUTPUT — target .txt path

Example:

export SIMPLE_STT_COMMAND='whisper "$SIMPLE_STT_INPUT" --model base --task transcribe --language en --fp16 False --output_format txt --output_dir "$(dirname "$SIMPLE_STT_OUTPUT")" >/dev/null && cat "$SIMPLE_STT_OUTPUT"'

Option 2: local whisper CLI

If you already have whisper installed, simple-stt will use it automatically.

Option 3: faster-whisper (local, faster)

Uses faster-whisper (CTranslate2) for significantly faster local transcription.

Run simple-stt --setup and select it, or configure manually:

export SIMPLE_STT_BACKEND=faster-whisper
export SIMPLE_STT_FASTER_MODEL=base
export SIMPLE_STT_FASTER_DEVICE=cpu
export SIMPLE_STT_FASTER_COMPUTE=int8
export SIMPLE_STT_LANGUAGE=en

For CUDA: set SIMPLE_STT_FASTER_DEVICE=cuda and SIMPLE_STT_FASTER_COMPUTE=float16.

Option 4: OpenAI API (or Cloudflare AI Gateway)

export OPENAI_API_KEY=your_key_here

Optional:

export SIMPLE_STT_OPENAI_MODEL=whisper-1

To route requests through Cloudflare AI Gateway instead of hitting OpenAI directly, set your gateway base URL:

export SIMPLE_STT_API_BASE="https://gateway.ai.cloudflare.com/v1/YOUR_ACCOUNT_ID/YOUR_GATEWAY/openai"

If your gateway requires a different key than your OpenAI key, you can override it:

export SIMPLE_STT_API_KEY="your-gateway-or-openai-key"

Runtime knobs

export SIMPLE_STT_OUTPUT_DIR="$HOME/Transcripts"
export SIMPLE_STT_BITRATE=24k
export SIMPLE_STT_SOURCE=default

Transcription prompt

You can seed the model with an initial prompt to guide style, spelling, or vocabulary:

mkdir -p ~/.config/simple-stt
printf 'Use slash commands like /db:query\n' > ~/.config/simple-stt/prompt.txt

This works with OpenAI API, Cloudflare AI Gateway, faster-whisper, and local whisper CLI. The setup wizard creates this file for you and prints the path at the end. Edit it any time:

$EDITOR ~/.config/simple-stt/prompt.txt

If you want a different location, set SIMPLE_STT_PROMPT_FILE. If no prompt file exists, SIMPLE_STT_PROMPT is still supported as a fallback.

For example, saying "DB query" will more likely be transcribed as /db:query when this prompt is set.

Build a Debian package

bash build.sh 1.0.0
sudo apt install ./simple-stt_1.0.0_all.deb
simple-stt --setup