GETTING STARTED / CORE CONCEPTS

Core concepts

How voxctrl models voice input, routing, and processing. Read this once and the rest of the docs make sense.

The five abstractions

Binding

A hotkey gesture mapped to one or more targets. Specifies keys, gesture type (hold / toggle / double-tap / double-tap & hold / chord), and which named target(s) receive the transcript.

Target

A named output destination with its own delivery type and post-processing pipeline. There are nine delivery types — inject, clipboard, exec, pipe, socket, file, dbus, http, webhook — plus an MCP response queue and a speak type that plays the transcript aloud via TTS. You can have many targets and switch between them by using different hotkeys.

Pipeline

An ordered sequence of processing stages applied to the raw Whisper transcript before delivery. Stages: filler removal (remove_fillers), snippet expansion, spoken-punctuation conversion, auto-format lists, custom vocabulary fuzzy correction, code mode, and an optional LLM rewrite (openai_rewrite) through any OpenAI-compatible API server.

AT-SPI2

The Linux accessibility bus. When atspi.context_prompt is enabled, voxctrl reads the surrounding text from the focused widget via AT-SPI2 to prime the Whisper initial prompt with relevant context. When atspi.injection is enabled, AT-SPI2 is also used as the primary text-injection method, falling back to wtype (Wayland), xdotool (X11), or clipboard+paste if unavailable.

MCP server

voxctrl's built-in Model Context Protocol server. Exposes transcribe_voice, speak_text, and get_status as tools any MCP-capable AI (Claude Desktop, Cursor, etc.) can call.

The broker model

voxctrl is not a dictation app — it is a voice input broker. A dictation app types what you say into the focused window. A broker can send the same utterance — or differently processed versions — to multiple independent systems simultaneously.

← previousInstallation next →Hotkeys & gestures