config.example.toml

# voiceio configuration — ~/.config/voiceio/config.toml
#
# Every value shown is the default; set only what you want to change.
# Edit with `voiceio config edit`, or one key at a time:
#   voiceio config set output.streaming_freeze_secs 8

[hotkey]
key = "ctrl+alt+v"            # e.g. super+v, ctrl+shift+r
backend = "auto"              # auto | evdev | pynput | socket (bind `voiceio toggle` in your WM)
mode = "auto"                 # auto: tap toggles, hold = push-to-talk | toggle | hold
                              # (releases need evdev/pynput, or `voiceio toggle --press/--release`)
hold_ms = 1000                # auto: held at least this long = push-to-talk; shorter toggles
release_tail_ms = 250         # keep recording this long after release (last word)
cancel_key = ""               # e.g. "escape": abandon the dictation (evdev/pynput; the app
                              # gets the key too). Or bind `voiceio cancel`

[model]
name = "small"                # a size (small, medium, large-v3-turbo…), a path to a
                              # CTranslate2 model (`voiceio learn` fine-tunes), or
                              # sherpa:<dir> / whispercpp:<url> — see `voiceio models`
language = "en"               # ISO 639-1 code, or "auto"
device = "auto"               # auto | cpu | cuda
compute_type = "int8"         # int8 (fast) | float16 (GPU) | float32
cpu_threads = 0               # 0 = half your logical cores, 4–8
decode_lanes = 2              # 2 = separate preview process, so stopping never waits on it
decoding = ""                 # sherpa-onnx only: greedy_search | modified_beam_search
vocabulary_file = ""          # empty = ~/.config/voiceio/vocabulary.txt
screen_vocabulary = true      # bias each dictation toward rare names on screen: the focused
                              # window's title and the selected text, read locally at start
                              # (never stored or sent; window titles: X11 apps, Hyprland,
                              # sway, niri; GNOME/KDE Wayland only for X11 apps) and tmux
                              # session names (your terminal tabs; the visible pane too when
                              # only one tmux client is attached)
beam_size = 5                 # passes you keep; 1 = greedy, a faster stop
protect_languages = []        # other languages you dictate in: corrections must not rewrite their words

[audio]
sample_rate = 16000
device = "default"            # input device name or index
prebuffer_secs = 1.0          # audio kept from before you pressed the key
silence_threshold = 0.01      # RMS floor for the simple VAD
silence_duration = 0.6        # pause that triggers a preview update
auto_stop_silence_secs = 5.0  # stop after this much silence once you've spoken
auto_stop_no_speech_secs = 20.0  # stop if nothing is said at all
vad_backend = "silero"        # silero | rms
vad_threshold = 0.5
pause_media = false           # pause playing music/videos while recording
duck_volume = 1.0             # lower other sound to this fraction while recording; 1.0 = off
keep_warm = "auto"            # mic + chime open while idle: always | auto (on AC; on battery
                              # until warm_minutes after the last dictation) | never
warm_minutes = 5.0            # auto, on battery: close this long after the last dictation

[output]
method = "auto"               # auto | ibus | ydotool | wtype | xdotool | clipboard | pynput
streaming = true              # show text while you speak
punctuation_cleanup = true    # capitalization and spacing
number_conversion = true      # "twenty five" → "25"
remove_disfluencies = true    # drop "um", "uh" and duplicated sentences
voice_input_prefix = ""       # e.g. "[voice]" to mark dictated text
streaming_freeze_secs = 8.0   # finalize long dictations in chunks; 0 = all at stop
copy_to_clipboard = "final"   # off | final | live
paste_keys = "ctrl+v"         # Linux paste chord (clipboard typer, IBus in terminals): or ctrl+shift+v, shift+insert
terminal_paste_keys = "ctrl+shift+v"  # instead of ctrl+v while a terminal has focus
                              # (Hyprland, sway, niri, X11; not GNOME/KDE Wayland). "" = off
restore_clipboard = true      # clipboard typer: give back your clipboard text after pasting
                              # (only with copy_to_clipboard = "off"; text only, not images)

[commands]
enabled = true                # "new line", "period", "comma"…
editing = false               # also "scratch that" and "correct that"

[feedback]
sound_enabled = true
notify_clipboard = false

[tray]
enabled = false

[daemon]
log_level = "INFO"

[tts]
enabled = true                # read selected text aloud
engine = "auto"               # auto | piper | espeak | edge-tts (cloud)
hotkey = "ctrl+alt+s"
voice = ""
speed = 1.0
model = ""                    # piper voice model

[health]
auto_fallback = true          # switch backends when one breaks

[data]
# Local only. Retained audio + text is what `voiceio learn` trains on.
retain_audio = false
max_audio_mb = 4096
min_free_gb = 5.0
capture_context = false        # note the focused app's title per utterance
capture_intermediates = false  # every interim pass's text + timings, for debugging

[history]
enabled = true
max_entries = 0               # 0 = unlimited
max_age_days = 0

# ── Optional cloud LLM ────────────────────────────────────────────────────
# Off unless you enable it. Text only — audio never leaves the machine.

[postcorrect]
enabled = false               # fix misheard words at the end of each dictation
model = "google/gemini-2.5-flash-lite"
timeout_secs = 3.0            # past this the original text is kept
min_words = 4

[cloud]
# The endpoint for the opt-in cloud pass above; [autocorrect] before 1.0. Or set
# OPENROUTER_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY instead of a key here.
api_key = ""
base_url = "https://openrouter.ai/api/v1"
model = "moonshotai/kimi-k2-0905"
timeout_secs = 30.0

[llm]
enabled = false               # local Ollama cleanup pass
model = ""
base_url = "http://localhost:11434"
timeout_secs = 15.0

[learn]
on_promote = ""               # run after every model switch, model in $VOICEIO_MODEL (see scripts/push_model.sh)
at = "03:30"                  # when nightly learning runs (voiceio learn schedule on --at)
every = "day"                 # "day" or "week" (Sundays)
max_load = 0.25               # only start when 1-min load per CPU is at most this, on mains power...
wait_hours = 3.0              # ...waiting up to this long, else try again next time
base = "small"                # model to fine-tune: Whisper size (e.g. "medium.en") or HF checkpoint
teacher = ""                  # model that labels new clips; empty = large-v3-turbo
epochs = 4                    # training epochs per run
min_new = 50                  # new labeled clips needed before retraining