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

What is Super STT?

Super STT makes speech-to-text with automatic text input trivial on Linux, for everyone. Bind a shortcut (Super+Space by convention), speak, and your words are typed straight into whatever app is focused, e.g. your editor, browser, chat, terminal. No copy-paste, no fiddling.

Under the hood it's two things:

• A model-agnostic engine. A background daemon installs speech models from a library of backends (local or cloud), loads one, and keeps it warm for instant transcription. You pick the model that fits your hardware and swap it whenever you like.
• An open protocol. The daemon speaks a documented HTTP protocol over a local socket, so any app, in any language, can request transcriptions, stream live audio visualizations, or drive recording, with per-app consent. Super STT's own desktop app, CLI, and COSMIC applet are just the first clients. See Developers.

🚀 Installation

Quick install - detects your system and downloads pre-built binaries:

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

Append -s -- --beta for the latest beta.

Build from source - for the very latest changes (needs the build prerequisites):

bash
Copy code
git clone https://github.com/jorge-menjivar/super-stt.git
cd super-stt
just install

Either way you get the daemon, the stt CLI, a consent helper, the desktop app, and (on COSMIC) the panel applet, wired up as a systemctl --user service. Everything installs system-wide (root-owned, so the installer asks for sudo), while the daemon itself runs unprivileged in your user session. On COSMIC the installer offers to bind Super+Space → stt record --write for you. GPU acceleration comes from the model you run (see Models).

⌨️ Using it

bash
Copy code
stt record --write # Record and transcribes. Types the result after silence is detected or you run the command again.

Bind stt record --write to a key combo. Super+Space is the convention (the COSMIC installer does this for you; on other desktops add a custom shortcut for stt record --write). When you trigger it:

1. stt asks the running daemon to start transcribing from your mic.
2. You speak; the daemon transcribes your audio.
3. When you stop (on silence or a second trigger), it types the transcription into the focused app.

Manage the daemon with the usual systemd controls:

bash
Copy code
systemctl --user start super-stt      # or: enable / status / restart
journalctl --user -u super-stt -f     # follow logs

Recording modes

Two settings shape a session. Both live in the desktop app under Settings (or the daemon config); stop mode can also be set per-recording on the CLI.

Stop mode - how a recording ends:

bash
Copy code
stt record --write --stop-mode manual_only

Write method - how text is injected: Auto (default) tries the XDG Desktop Portal, then ydotool, then direct Wayland input. Force a specific one in Settings if auto-detection picks wrong.

🤖 Models

Models come from a library of backends you install on demand. Open the app, go to Library → Browse, install a backend, and it appears in the model selector. Some run locally (your audio never leaves your machine); others are online providers you reach with your own API, which is stored securely in your system keyring (GNOME Keyring, KWallet, …).

Recommended models

Local - everything stays on your device.

Online - bring your own API key.

GPU acceleration is a property of the model, not a separate build of the app. Install a GPU-capable backend (like Voxtral or Qwen3-ASR) and the daemon downloads the build matched to your NVIDIA GPU automatically. You just need an up-to-date driver.

This is a snapshot. The app always shows the current catalog, published live at jorge-menjivar.github.io/super-stt/index.json. Want a model that isn't there? Anyone can publish one.

🖼️ Screenshots

Models & backends — load a backend, choose a model, and pick where it runs.

Library — browse the catalog and manage what's installed.

Settings — tune audio feedback, recording behavior, and text input.

Panel visualizer — the COSMIC applet shows your mic input live in the panel, in three styles.

Waveforms

Equalizer

Centered bars

🩺 Troubleshooting

• stt: command not found: binaries are installed system-wide and are on PATH by default — restart your terminal so it rehashes, and check the installer finished without errors.
• Daemon won't start / misbehaves: check journalctl --user -u super-stt -n 50.
• Transcriptions seem less accurate than they should be: your microphone input volume may be set too high or too low. Adjust the mic volume in your system sound settings and try again.
• Typing doesn't work in some apps: ydotool types reliably across virtually all apps. Install it via your package manager, then try it out first by running sudo ydotoold --socket-path="$HOME/.ydotool_socket" --socket-own="$(id -u):$(id -g)" in a terminal and setting the write method to ydotool in Settings. If that fixes typing, make it permanent by enabling the service (e.g. systemctl --user enable --now ydotool).

🧑‍💻 Developers

Super STT is built to be built on. The details live in developer-facing docs:

• Build a client — get transcriptions, event streams, or recording control into your own app, in any language, over the documented HTTP protocol → docs/protocol/
• Add your own model — package a speech model as a backend the daemon can install and run, then publish it to the catalog → docs/protocol/ and registry/README.md
• Contribute — build from source, workspace layout, and the PR workflow → CONTRIBUTING.md

Architecture and the security model live in docs/.

---