Routing & targets
Targets are named output destinations. Bindings tell voxctrl which target each hotkey should route to.
Delivery types
| Type | Mechanism | Use for |
|---|---|---|
| inject | wtype (Wayland) → xdotool (X11) → clipboard+Ctrl+V fallback; PowerShell clipboard paste on Windows | Default dictation into focused window |
| clipboard | System clipboard write only — no paste | Copy for manual paste |
| file | append or write, optional prefix & ISO timestamp | Voice journal, meeting notes |
| exec | shell command, transcript passed as argument | CLI agents, one-shot commands |
| http | HTTP POST, JSON body {"text": "..."} |
Webhooks, REST APIs |
| webhook | HTTP POST signed with HMAC-SHA256 (X-VoxCtrl-Signature header) |
Authenticated webhooks, n8n, Zapier |
| socket | Unix domain socket or TCP, newline-terminated | Remote or containerised agents |
| pipe | Named FIFO write | Persistent agent processes |
| dbus | text_injected signal on ai.voxctrl.Dictation |
Waybar, Rofi, desktop automation |
| mcp | Enqueues response to a pending transcribe_voice MCP tool call |
MCP client integrations |
| speak | Local TTS playback, no MCP/server required | Hands-free voice replies |
Per-target processing
Each target's [target.processing] block can override the global post-processing settings.
All fields are optional (null inherits the global config):
remove_fillers— strip filler words (um, uh, hmm, er, ah, ugh, mhm)spoken_punctuation— convert spoken punctuation ("period" → ., "comma" → ,)auto_format_lists— convert spoken ordinals into a numbered listapply_snippets— expand custom shorthand snippets into full textcode_mode— camelCase / spoken-operator formatting for dictating codequiet_mode— suppress overlay/sound feedback for this targetatspi_context— use AT-SPI2 to read surrounding context for this targetnoise_suppression— enable/disable noise suppression for this target
openai_enabled,
openai_model, openai_mode, openai_prompt,
openai_system_prompt) is configured per hotkey binding in
bindings.toml, not per target — so the same target can be reached by different bindings using
different rewrite styles. The model is served over the OpenAI API; legacy ollama_* field names
are still accepted as aliases.exec, pipe,
socket) should almost always use remove_fillers = true and
spoken_punctuation = false. Rewriting alters command semantics.
Common patterns
Agent command pipe
Send voice commands to a CLI agent via FIFO (pipe_path). Strip fillers so the agent gets clean
input. Use response_pipe to stream replies back as TTS.
Voice journal
Append timestamped entries to a markdown file with delivery = "file", file_prefix,
and file_timestamp = true. Apply an LLM rewrite on the triggering binding to format each
utterance as a concise note.
Shell command execution
Use delivery = "exec" with a command template. The transcript is passed as an
argument to the command.
TCP or Unix socket to remote agent
Forward transcripts to a socket for distributed or containerised setups. Set socket_host and
socket_port for TCP, or socket_unix for a Unix domain socket.
HTTP / webhook delivery
Use delivery = "http" for a simple JSON POST (http_url, http_method,
optional http_headers / http_json_template), or delivery = "webhook"
with webhook_url and webhook_secret to attach an HMAC-SHA256
X-VoxCtrl-Signature header for authenticated endpoints.
Multi-target routing
A binding's target_ids array can list multiple targets — voxctrl delivers to each
sequentially in order after a single recording session (e.g. inject into the focused window, then log to a
file).
Config file locations
~/.config/voxctrl/config.json— global settings (managed by Settings UI)~/.config/voxctrl/targets.toml— output target definitions~/.config/voxctrl/bindings.toml— hotkey → target bindings