https://github.com/user-attachments/assets/bbbe20c3-6802-4797-afc8-aa81d1b48415

🚀 Installation

Quick Install (Recommended)

Install with our automated installer that detects your system and downloads pre-built binaries:

curl -sSL https://raw.githubusercontent.com/jorge-menjivar/super-stt/main/install.sh | bash

You can also append -s -- --beta to the command to install the latest beta version.

Build from source

If you want the very latest changes, build locally:

git clone https://github.com/jorge-menjivar/super-stt.git
cd super-stt
just install                # CPU
just install --cuda         # NVIDIA GPU

just install builds and installs the daemon, CLI, consent helper, desktop app, and (on COSMIC) the panel applet, then enables the user systemd service. Run just install-daemon, just install-app, or just install-applet to install just one piece.

What gets installed

The install script does the following:

• Drop binaries in ~/.local/bin (super-stt-daemon, super-stt-cli, super-stt-app, plus super-stt-consent and super-stt-cosmic-applet where applicable)
• Set up a systemctl --user service for the daemon
• Detect CUDA/cuDNN and pick the right GPU build automatically
• Offer to wire up Super+Space → stt record --write on COSMIC

The installer's menu lets you pick a subset (daemon only, app only, applet only).

For protocol, auth, and security details, see docs/.

Recording Modes

Stop Mode

Controls how a recording session ends. Configurable via the app, CLI (--stop-mode), or daemon config. Assuming you have a shortcut mapped to execute stt record --write:

Mode	Behavior
Silence + Manual (default)	Stops on silence detection or a second shortcut press
Silence Only	Stops only when silence is detected
Manual Only	Stops only on a second shortcut press

Write Method

Controls how transcribed text is typed into the focused application. Auto-detection tries each method in order.

Method	Description
Auto (default)	Tries XDG Desktop Portal, then ydotool, then Wayland protocol
XDG Desktop Portal	Uses the desktop's RemoteDesktop portal (requires one-time authorization)
ydotool	Uses ydotool virtual input (requires ydotoold running)
Wayland Protocol	Direct Wayland input simulation via the compositor

Both settings can be changed in the desktop app under Settings. The stop mode can also be set per-recording on the CLI; the write method is configured only in the app or daemon config (it is not a per-recording flag):

stt record --write --stop-mode manual_only

🤖 Supported Models

Local Models

All processing happens on your device. No audio data leaves your machine.

Model	Notes
voxtral-mini	State-of-the-art. Recommended with GPU
voxtral-small	State-of-the-art
whisper-tiny	Default
whisper-base	Recommended with CPU
whisper-small
whisper-medium
whisper-large-v3

Online Models

If your computer does not have enough resources for local models, you can send your audio to third-party providers for transcription. Online models are disabled by default and require you to explicitly enable them.

Provider	Models
Mistral	voxtral-mini-latest
OpenAI	whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe
Deepgram	nova-3

Enabling Online Models

Online providers are installed as backends, then configured with an API key:

1. Open the Super STT app
2. Go to Library → Browse and install the provider's backend (Mistral, OpenAI, or Deepgram)
3. On the Installed tab, open that backend's Configure sheet and enter your API key (stored in your system keyring)
4. Go to Models, open the model selector, and choose an online model to load it

API keys are stored securely in your system keyring (GNOME Keyring, KWallet, etc.)

Online Models

Model Selection

Screenshots

Multiple Visualization Styles

Centered Bars

Equalizer

Waveform

Custom Colors

System Theme

Green

⌨️ Keyboard Shortcuts

Bind stt record --write to a key combo (Super+Space is the convention). On COSMIC the installer offers to do this for you. For other desktops, add a custom shortcut through Settings (the full command is ~/.local/bin/stt record --write).

Prerequisites

Debian/Ubuntu/Pop!_OS

You may need to install the following dependencies:

sudo apt install build-essential libxkbcommon-dev libasound2-dev pkg-config libssl-dev

If you find any missing make a pull request to update this list. Thanks!

Fedora

You may need to install the following dependencies:

sudo dnf install gcc gcc-c++ libxkbcommon-devel alsa-lib-devel pkgconf perl-FindBin perl-IPC-Cmd openssl-devel

If you find any missing make a pull request to update this list. Thanks!

Arch

You may need to install the following dependencies:

sudo pacman -S pkgconf openssl

If you find any missing make a pull request to update this list. Thanks!

CUDA GPU Acceleration

Super STT automatically detects and uses CUDA-enabled GPUs for acceleration. If you have an NVIDIA GPU, but the installation script cannot find the CUDA toolkit, you need to install it manually:

Ubuntu/PopOS/Debian

sudo apt-get install nvidia-cuda-toolkit nvidia-cuda-toolkit-gcc

Fedora

See https://rpmfusion.org/Howto/CUDA

Arch Linux

sudo pacman -S cuda

Note: If you already have the CUDA toolkit installed, but the installation script still cannot find it, please create a new issue. Thanks!

How it works

Note: On first run, Super STT downloads the required AI model (~1-2GB). This may take a few minutes.

When you press the shortcut:

1. stt asks the running daemon to start transcribing from your mic.
2. While you speak, the daemon types a live preview into whatever app is focused.
3. When you stop speaking (or press the shortcut again, depending on stop mode), the daemon does a final pass for accuracy and replaces the preview with the final text.

Usage

After installation, manage the daemon with:

# Start the daemon
systemctl --user start super-stt

# Enable auto-start with user session
systemctl --user enable super-stt

# Check status
systemctl --user status super-stt

# View logs
journalctl --user -u super-stt -f

Then use the stt command:

# Record and transcribe
stt record

# Record, transcribe, and auto-type the result
stt record --write

Troubleshooting

stt command not found

The installer adds ~/.local/bin to your PATH. Restart your terminal, or run export PATH="$HOME/.local/bin:$PATH".

Authorization popup shows "Path: " or never appears

A previously installed legacy build is shadowing the daemon. Run just uninstall from the source tree (or remove ~/.local/bin/super-stt* manually) and reinstall.

Daemon not starting

journalctl --user -u super-stt -n 50

"sg: group 'stt' does not exist" / "Operation not permitted"

This comes from an older install. The current daemon does not use an stt group — the socket lives in your per-user $XDG_RUNTIME_DIR and is same-user only. Remove the stale build and reinstall:

just uninstall   # or: rm -f ~/.local/bin/super-stt*
just install

🔧 Development

just run-daemon         # run the daemon in the foreground
just run-app            # run the settings app
just run-applet         # run the COSMIC applet
just setup-cosmic-shortcut  # add Super+Space binding on COSMIC
just audit              # security audit (cargo audit)

Architecture, protocol design, and security model live in docs/.

---