Documentation

Comprehensive guide to installing, configuring, and using keyspeake for voice dictation and text-to-speech on Linux.

1. Installation

keyspeake is not publicly available to install yet. There is no release, no package, and no install command — and we'd rather say so here than publish one that fails halfway through.

When it ships, it installs as a single package that includes the background service, the desktop app, and the setup wizard together, so there is no manual terminal setup afterwards. It targets Linux on x86_64, across Wayland and X11 — Hyprland, Sway, Niri, GNOME, and KDE.

Join the waitlist and you'll get one email the moment there's something real to install. The rest of this page describes how keyspeake works and how it's configured, which is accurate today.

2. First-Run Setup

After installing, run the interactive onboarding wizard to configure your backend, verify audio input, set up device permissions, and bind global hotkeys:

keyspeake setup

The interactive setup guides you through six step-by-step checks:

Transcription Backend Selection: Choose between cloud transcription (Groq, Deepgram Streaming/REST, OpenAI Realtime/REST) or fully offline local transcription (local whisper.cpp or generic ASR sidecar).
API Keys & Model Downloads: Enter required provider credentials or automatically download GGUF whisper models (e.g. base.en at 142 MB).
Microphone Selection & Audio Test: Select active input hardware and run an immediate audio capture test via ALSA / PipeWire.
Device & Virtual Keyboard Permissions: Configures /dev/uinput permissions and checks user membership in the input group to enable layout-aware keystroke injection into focused windows.
Background Service Configuration: Generates and enables the user-level systemd service (keyspeake.service) to auto-start the daemon on login.
Compositor Keybinding Helper: Provides copy-paste keybind snippets for your active window manager (Hyprland, Sway, GNOME, X11).

3. Configuration

Configuration settings are stored in TOML format at ~/.config/keyspeake/config.toml (restricted permissions 0600). You can edit this file directly, use the interactive terminal command keyspeake config, or run the desktop GUI application (gui/main.py).

Minimal Example

[general]
backend = "groq"   # groq | deepgram-streaming | deepgram | openai-realtime | openai | local-whisper | asr-sidecar
language = "en"    # ISO 639-1 code or "auto"
overlay = false    # bottom-screen recording indicator

[groq]
api_key = "gsk_..."

Configuration Reference Summary

The configuration file supports fine-grained control over dictation behavior, overlay appearance, audio feedback, and provider options:

[general]: Controls core behavior including backend selection, language, silence auto-stop timeout (silence_timeout_ms), desktop notifications (notify), filler word removal (remove_filler_words, filler_words), audio feedback tones (audio_feedback, audio_feedback_volume), custom domain terminology (vocabulary), prompt context (prompt), system tray icon (tray), and OSD overlay (overlay).
[overlay]: Customizes recording overlay appearance including theme presets ("carbon", "ember", "cyan", "custom"), dimensions (width, height), and custom hex colors ([overlay.colors]).
[audio]: Selects input device (device = "default" or specific ALSA device name).
[input]: Configures virtual keypress timing (key_delay_ms). Adjust this delay if fast character injection drops characters in raw TUIs like Claude Code.
Provider Sections ([groq], [deepgram], [openai], [local-whisper], [asr-sidecar]): Specifies API keys, model names (e.g. whisper-large-v3-turbo, nova-3, gpt-4o-mini-transcribe), model binary file paths, or custom sidecar endpoint URLs.
[llm]: Configures LLM provider credentials and model (gpt-4o-mini) used by command mode for voice-driven text transformation.
[tts]: Controls read-aloud speech synthesis (keyspeake speak), including backend selection (openai, groq, deepgram, tts-sidecar), model, voice ID, and response format.
[hotkeys]: Optional global built-in keybindings (toggle, cancel, command, speak) that work across desktop environments without external WM hotkey tools.

Environment Variable Overrides

API keys can also be provided via environment variables, which override file values in config.toml:

KEYSPEAKE_GROQ_API_KEY
KEYSPEAKE_DEEPGRAM_API_KEY
KEYSPEAKE_OPENAI_API_KEY
RUST_LOG (controls daemon log verbosity, e.g. RUST_LOG=debug keyspeaked)

4. CLI Commands

The keyspeake command-line utility controls the background daemon, triggers recording modes, queries status, and manages dictation logs.

Command	Description
`keyspeake setup`	Runs the interactive onboarding wizard for backend, API keys, audio test, permissions, and services.
`keyspeake config`	Opens an interactive terminal editor for `~/.config/keyspeake/config.toml`.
`keyspeake toggle`	Toggles dictation recording. Press once to start capturing audio; press again to stop and type text at cursor.
`keyspeake cancel`	Immediately cancels active recording and discards captured audio buffer.
`keyspeake status`	Queries operational state, active backend, and health of the background daemon process.
`keyspeake restart`	Restarts the background daemon using the systemd user service (`keyspeake.service`).
`keyspeake command`	Launches command mode: captures selected text and spoken instruction, sending both to LLM for text rewriting.
`keyspeake speak`	Reads selected text aloud via configured TTS engine (alias: `keyspeake read`; press again to stop).
`keyspeake log`	Displays recent dictation transcript history. Supports `-n 5` (last 5 entries) and `--clear` (wipes history).

5. Transcription Backends

keyspeake supports a broad array of cloud providers and local offline speech recognition engines. Select your preferred backend in config.toml under [general] backend.

Backend	Type	Streaming	Cost	Best For
Groq	Cloud	Batch	Free tier available	Default choice; extremely fast cloud transcription.
Deepgram Streaming	Cloud (WebSocket)	True streaming	$200 free credit	Low-latency live streaming transcription with free credits.
Deepgram REST	Cloud	Batch	$200 free credit	Simple batch requests supporting over 60 languages.
OpenAI Realtime	Cloud (WebSocket)	True streaming	Paid API	Premium experience; streams live text directly into cursor position as you speak.
OpenAI REST	Cloud	Batch	Paid API	Standard cloud fallback using Whisper endpoints.
Local whisper.cpp	Local (CPU/GPU)	Sliding window	Free / Offline	100% private, offline use. Recommended model: `base.en` (142 MB).
ASR Sidecar	Local HTTP Sidecar	Batch	Free / Offline	Bring-your-own local model (Moonshine, NVIDIA Parakeet, Microsoft VibeVoice-ASR).

For local offline dictation, run keyspeake setup and choose Local > whisper.cpp. Recommended model sizes: tiny.en (75 MB, low-resource hardware), base.en (142 MB, default recommendation), or small.en (466 MB, higher accuracy).

6. Supported Environments

Built natively in Rust for Linux desktop environments, keyspeake works across Wayland compositors, X11 window managers, and major Linux distributions.

Environment / Component	Support Status
Hyprland	Fully tested & daily-driven on Arch Linux. Native layer-shell OSD support.
GNOME Wayland	Tested on Ubuntu 24.04 & Arch. Overlay support provided via bundled GNOME Shell extension.
X11 (Any WM)	Tested on Ubuntu 24.04 (Xorg). Full support for layout auto-detection via `setxkbmap`.
Niri	Tested on Niri 26.04 (CachyOS).
Sway / i3	Native support implemented for Sway IPC & i3 window tracking.
KDE Wayland	Implemented via D-Bus protocol.
Audio Stack	PipeWire, PulseAudio, and ALSA (auto-detected via `cpal`).
Linux Distributions	Confirmed on Arch Linux, Ubuntu 24.04, CachyOS; compatible with any Linux distro meeting dependencies.