voxtype: Configuration & CLI

Configuration lives at ~/.config/voxtype/config.toml.

You never need CLI flags. Every flag is just an override of a config key, so the intended workflow is: put your preferences in the config once, then your daily command is plain voxtype — flags exist for one-off experiments (e.g. trying another engine) and always win over the file. The config also holds keys that have no flag at all (wake_word_aliases, submit_phrases, sound names, paste_hotkey, cancel_hotkey, copy_to_clipboard, parakeet_threads, …), so the file is the complete interface; the flags are a subset.

Two ways to create that file:

voxtype setup         # interactive walkthrough — asks, then writes
voxtype init          # write a fully commented sample to edit by hand
voxtype init --force  # overwrite an existing sample

voxtype setup is the quickest start: it asks a short series of explained questions (engine, mode, segmentation, hotkey, wake word, and optional extras), validates your choices, and writes a ready-to-use config — you can record the hotkey live during the walkthrough. init instead drops the fully commented template below for hand-editing.

The three independent axes

Three settings combine to define how voxtype behaves, and they answer different questions:

• mode — when is it listening? toggle: only between two presses of the hotkey. wake: always passively listening for the wake word (hotkey works as an override). vad: dictating from the moment it starts.
• segmentation — when does text appear? See “When does the text appear?” below — this is the axis people mean when they ask about “streaming” dictation.
• engine — what transcribes it? Pure speed/accuracy/platform trade-off; see the engine table below. Any engine works with any mode.

When does the text appear?

Dictation tools differ in how immediately the transcript shows up. The spectrum, from most to least immediate:

1. Word-by-word streaming (Apple-dictation style: words materialize and self-correct as you speak). voxtype deliberately does not do this into your apps: revising already-typed text in another application means blindly sending backspaces into whatever has focus — one desync and your document is mangled. Typed text should be final.
2. Per-pause typing — segmentation = "vad". Speak; roughly half a second after each natural pause, that utterance is typed. This is the closest voxtype comes to a streaming feel: text flows in sentence-sized pieces while you keep talking. Trade-off: the model transcribes each fragment with only that fragment’s context, so accuracy is a notch lower.
3. Whole-take — segmentation = "hold". Nothing appears while you speak (the ghost indicator is your feedback); on toggle-off the entire take is transcribed as one segment and typed in one go. Maximum accuracy — the model sees full sentence context — and most apps undo it as a single edit (keystrokes are synthesized, so undo grouping is up to the focused app). Requires toggle mode, since the wake word can only be heard by continuous per-utterance transcription.

Wake and vad modes always use per-pause typing (2); toggle mode lets you pick between (2) and (3).

Common setups

Push-to-talk dictation (recommended daily driver). No wake word involved at all; maximum accuracy; text lands in one go (a single edit to undo, in most apps):

mode = "toggle"
segmentation = "hold"
engine = "parakeet-mlx"

Toggle with live feedback. Same hotkey workflow, but text appears at every pause instead of at the end — useful when you want to see progress while dictating something long, at some cost in accuracy:

mode = "toggle"
segmentation = "vad"
engine = "parakeet-mlx"

Hands-free with a wake word. Say “hey claude …” to dictate, “stop listening” (or silence) to re-arm; the hotkey still toggles manually. Per-pause typing is inherent to this mode:

mode = "wake"
engine = "parakeet-mlx"
wake_word_aliases = ["hey cloud"]  # add what the model mishears

Always-on transcription. Types everything it hears while running — for captioning yourself or short bursts of use:

mode = "vad"
engine = "parakeet-mlx"

Engines

Selected with engine / --engine. All run 100% on-device.

Engine	Runs on	Speed*	Notes
parakeet-mlx	Apple GPU (MLX)	~40x realtime	Default on Apple Silicon. fp16 Parakeet-TDT v3: best accuracy and speed. Weights from HuggingFace on first run.
parakeet	CPU (sherpa-onnx)	~32x realtime	Default on other machines. int8 Parakeet-TDT v3 (or fp16 v2 via parakeet_model); ~490 MB download.
moonshine	CPU (ONNX)	streaming	Moonshine streaming models; smallest footprint. Opt-in: uv tool install "voxtype[moonshine]" (no Intel-macOS build).

Both parakeet engines ship with the base install; the default is chosen for your machine, so most people never set engine at all.

*measured on an M-series Mac; see parakeet_threads for CPU tuning.

Config reference

# ~/.config/voxtype/config.toml — all keys optional; these are defaults

# Activation: "toggle" (hotkey), "vad" (hands-free), "wake" (wake word)
mode = "toggle"

# Engine: "parakeet-mlx" | "parakeet" | "moonshine"
# (default: parakeet-mlx on Apple Silicon, parakeet elsewhere)
engine = "parakeet-mlx"

# "vad" types each utterance when you pause; "hold" records everything
# between toggle-on/off and transcribes the whole take at once
# (parakeet engines + toggle mode only)
segmentation = "vad"

# parakeet (CPU) build: "v3-int8" | "v2-fp16"; and decode threads
parakeet_model = "v3-int8"
parakeet_threads = 4

# parakeet-mlx model (HuggingFace id)
mlx_model = "mlx-community/parakeet-tdt-0.6b-v3"

# moonshine model: tiny | base | tiny-streaming | base-streaming |
# small-streaming | medium-streaming
model_arch = "medium-streaming"

language = "en"

# Hotkeys (pynput or bracket-less syntax; `voxtype hotkey` records one)
hotkey = "<ctrl>+;"          # toggle recording
cancel_hotkey = "<esc>"      # cancel recording (only intercepted WHILE recording)
paste_hotkey = ""            # re-type last transcript, e.g. "<cmd>+<ctrl>+v"

# Wake mode
wake_word = "claude"
wake_word_aliases = []       # misspellings the model produces, e.g. ["hey cloud"]
stop_phrase = "stop listening"
idle_timeout = 20.0          # seconds of silence before wake mode re-arms

# Spoken submit: saying one of these as an ENTIRE utterance presses Enter
submit_phrases = ["over", "go", "submit"]

# Transcript cleanup: strip standalone fillers (uh, um, ...) and
# collapse 3+ word stutters ("I I I think" -> "I think")
strip_fillers = true

trailing_space = true        # append a space after each typed utterance

# Toggle chimes. sounds = false silences the start/stop chime entirely
# (or run with --no-sounds). Names are system sounds
# (/System/Library/Sounds) or file paths.
sounds = true            # false = no chime when recording toggles on/off
sound_start = "Glass"
sound_stop = "Bottle"

# Keep each session's text on the clipboard too
copy_to_clipboard = false

# Floating ghost indicator while recording (macOS): a little blue
# ghost whose mouth opens with your voice.
overlay = true
overlay_flex = 1.0   # how much the face flexes its shape (higher = more)
overlay_speed = 1.0  # animation speed (lower = slower/gentler)

CLI

voxtype [flags]           run with config + flag overrides
voxtype setup [--force]   interactive walkthrough -> writes config
voxtype init [--force]    write the commented sample config to edit
voxtype hotkey            press a chord; prints the config line
voxtype skill             install the voxtype skill into Claude + Codex
voxtype --help            full flag reference

New here? voxtype setup asks a handful of questions (engine, mode, hotkey, …) — each explained, with sensible defaults — and writes a valid config for you. init instead drops a fully commented sample file to edit by hand.

Flags mirror the config keys: --mode, --engine, --segmentation, --parakeet-model, --model-arch, --language, --hotkey, --wake-word, --stop-phrase, --no-sounds, --no-overlay, --config PATH.

Hotkey notation

Both spellings work everywhere a chord is accepted:

hotkey = "<ctrl>+;"          # pynput style
hotkey = "ctrl+;"            # bracket-less
hotkey = "cmd+shift+f5"      # named keys too

Easiest of all: run voxtype hotkey, press the combo you want, and paste the printed line into your config. On macOS matched chords are fully suppressed — the focused app never sees them — and context-dependent keys like Esc are only intercepted while recording.

macOS permissions

Grant these to your terminal app (System Settings → Privacy & Security), once each:

• Microphone — to hear you
• Accessibility — to type into other apps
• Input Monitoring — for the global hotkeys

Troubleshooting

• Every utterance’s fate is logged to the terminal (typed: ..., heard (awaiting wake word): ..., dropped, decoded to empty text) — nothing is discarded silently. Read these lines first.
• Wake word not firing? Check the heard lines for how the model actually spelled it and add that to wake_word_aliases; prefer a two-word phrase (“hey claude”) over a bare word.
• Quiet dynamic mic (Shure MV7 class)? Automatic gain control is built in; if speech still isn’t detected, move closer to the mic.
• Dictated into the wrong window? Set paste_hotkey and re-type the last session anywhere.