Files

T

HashingandGitHub 12e440ce1c feat(text-injection): let config.json pin the injection backend (#649 )

* feat(text-injection): let config.json pin the injection backend (#476)

Autodetection has to infer whether IBus commits actually reach the
focused application, and it cannot verify that: commit_text() reports
success even when the compositor drops the text. When the inference is
wrong the failure is silent, and dictation appears to work in XWayland
windows while doing nothing in native ones.

VOCALINUX_FORCE_BACKEND already provides an escape hatch, but it is an
environment variable: it covers a single run, is undocumented outside
the test suite, and a user whose compositor is misdetected has to wrap
the launcher in a shell script to make the choice stick.

Add a persistent `text_injection.backend` setting alongside it, accepting
the same ibus/wtype/ydotool/auto values. The environment variable still
wins so a backend can be A/B-tested for one run without touching the
saved configuration, and the startup log now names which of the two
pinned the choice so a stale setting is diagnosable from --debug output.

Reads the file directly rather than through ConfigManager, keeping this
package independent of the UI layer, exactly as _should_copy_to_clipboard
already does. An unreadable or corrupt config falls back to autodetection
instead of blocking startup, and an unrecognised value is ignored with a
warning so a typo cannot silently pin the wrong backend.

Defaults to "auto", so existing installs behave exactly as before.

* fix(text-injection): tell an explicit VOCALINUX_FORCE_BACKEND=auto from unset

The variable is meant to override the saved text_injection.backend pin for a
single run, which is what makes the two paths A/B-testable without editing
config. Setting it to auto -- the value that means "autodetect this time" --
did not do that: the reader collapsed unset and an explicit auto into the same
"auto" return, so the caller read both as "nothing was forced" and fell through
to the saved pin. The pin won, and there was no way to ask for autodetection
for one run short of editing the config file the variable exists to avoid.

Read the variable as three states instead: unset, an explicit auto, or a
backend name. Only the unset state consults config, so an explicit auto now
short-circuits to autodetection.

An unrecognised value is deliberately treated as unset rather than as auto. A
typo means the user failed to override their preference, not that they asked to
discard it, so falling through to a valid saved pin is the kinder reading.

_forced_backend() keeps its signature and its collapsed return, so its existing
callers and tests are untouched; the new three-state reading lives alongside it
and is what the preference resolver consumes.

* feat(text-injection): accept an xdotool pin and warn when ibus overrides the denylist

Two gaps in the pinnable backend set.

xdotool was not accepted, even though on X11 it is the tool that actually does
the typing. Users were told to pin a *Wayland* backend to mean "not IBus", and
get xdotool as a side effect. Naming it directly is what they were reaching for.
On Wayland it needs no special handling: the value skips IBus like any other
non-ibus pin and falls through to the existing XWayland fallback, so no branch
is added to the selection chain.

The accepted values now live in one tuple, because four places listed them --
both readers and both "expected ..." messages -- and a fifth value would have
had to be added to all four. The two messages derive from the tuple, so they
cannot fall behind it.

Pinning ibus also silently bypasses the compositor denylist. That check exists
because a denylisted compositor makes IBus report a commit as delivered while
the text never arrives (#478, #485), so a pin is the one setting that can put a
user back into a failure with no symptom other than nothing happening. The pin
is still honoured -- an override that ignores you is worse than one that warns
-- but it now says so at warning level, names the compositor, and gives the
remedy. It stays quiet when the compositor genuinely bridges IBus, including a
denylisted one running the ibus-wayland bridge, and on X11 where the denylist
does not apply.

The check is evaluated once. The guard chain short-circuits on the pin, so a
pinned run never reaches the existing compositor branch, and this is its first
and only call -- worth knowing because the check can shell out to pgrep or
gdbus. A test asserts the call count so that stays true.

Documents xdotool in the value table and rewrites the X11 paragraph, which
described xdotool as the implicit result of pinning something else rather than
as a value you can name.

* fix(text-injection): say so when the pinned backend is not the one in use

A pin could be quietly ignored. Pinning a tool that is not installed fell
through to autodetection and typed with whatever it found, under a log line
that had already announced the pin was overriding autodetection. Pinning
xdotool on Wayland did nothing at all, since the selection chain reaches
ydotool and wtype first. Pinning ibus where IBus support is unavailable skipped
the whole IBus branch. In each case the user set a preference, saw no
complaint, and got something else.

These are one condition, not three: whatever ended up doing the typing is not
what was pinned. The check compares the pin against the backend read back from
final state, so a cause nobody has thought of yet is covered without another
branch. It runs at the end of construction rather than inside
_check_dependencies, which returns early on two paths and which the wtype probe
can still override afterwards. The reason clause is added only where a generic
check answers it -- the binary is absent, or IBus is unavailable -- and omitted
otherwise rather than guessing.

Reporting the source separately was letting the environment variable and the
config setting disagree. _check_dependencies resolved the backend, then
re-derived which source had won by asking again -- so the environment was
parsed twice per construction, and a malformed value was reported to the user
twice. Resolution now returns the backend and its source together, which fixes
the duplicate warning and means the source named in a log line is the one that
actually chose the backend. _backend_preference() keeps its signature and reads
the first element.

Two log lines also claimed VOCALINUX_FORCE_BACKEND regardless of where the pin
came from, so a config-set backend was reported as an environment variable the
user had never set. They now name the real source.

The new warning is a startup diagnostic, not a live invariant: a tool switched
later by _try_recover_from_fallback is not reported again. Noted in the
docstring so the boundary is deliberate.

* docs(user-guide): file the injection-backend section under Troubleshooting

The section sat under Customization, directly beneath GPU Acceleration --
where the paragraph immediately above it reads "To check which backend is
being used" about Vulkan and CUDA. The word means something else there, and
two adjacent sections using it for different things is a bad place to explain
either.

It also is not a customization option. It exists because a compositor can make
IBus report a commit as delivered while nothing arrives (#478, #485), and
someone hitting that reads Troubleshooting, not Customization. The section
already opens on the symptom, so it needs no rewriting to belong there.

Pure reorder: no wording changes, and the heading text is unchanged so any
existing link still resolves.

* test(text-injection): cover the pin paths that skip the selection chain

_check_dependencies had three uncovered branches, all reachable by pinning a
backend and none of them exercised: the two early returns that hand over to
IBus before a tool is chosen, and the daemonless-ydotool fallback a wtype pin
lands on when wtype is absent. The early returns matter most, since the pin
check runs at the end of construction precisely so those paths cannot skip
it, and nothing proved that.

Adds the ydotool counterpart to the missing-binary case, so a check keyed on
one tool name cannot pass by coincidence; an X11 test for the guide's claim
that any non-ibus pin turns the IBus path off, with a control asserting IBus
is constructed without a pin so the assertion is the pin's doing; and an
end-to-end explicit-auto case, which until now was only proven at the
resolver rather than through selection.

The pin log line said it was "overriding backend autodetection" before
anything had been checked. An unavailable pin falls through to autodetection,
so that line announced an outcome it could not know and then read as
contradicting the "was not applied" warning. It now states the request only.

_run_with_pin gains ydotoold_ready, defaulting to the previous behaviour so
existing callers are unchanged.

* fix(text-injection): report a config file the backend pin cannot be read from

A corrupt config.json disappeared into logger.debug. The setting is
hand-edited -- that is the workflow the user guide documents -- so a stray
comma is a likely way to reach this, and staying quiet left the user with
autodetection and the silent IBus miss the pin was set to avoid, with nothing
to tell that apart from the pin not working. Unknown values already warned;
an unusable file now does too, naming the file and the parse error.

The bare handler was also catching AttributeError by accident. Valid JSON
that is not an object -- a bare list, string, number or null -- reaches the
lookup and raises there rather than at parse time, and so does a
text_injection section that is not an object, where the top level is a
mapping and the section is not. Both are now shape checks rather than
exception handling, which is what lets the handler narrow to OSError and
ValueError without those five shapes escaping it.

Locating the file moves out of the try. It fixes the handler being unable to
name the path it failed on, and it is a deliberate boundary: config_dir()
resolving a path is not a failure this should paper over, so it is no longer
guarded here at all.

A missing config.json stays silent, which is the default install.

* test(text-injection): stop the ibus-pin tests depending on an installed ydotoold

The bridged-compositor and X11 cases asserted that a run logs no warnings at
all. That is broader than what they are about, and _run_ibus_pin patches
shutil.which to claim every tool exists without patching the probe that then
shells out to one, so the real _ensure_ydotoold ran and warned whenever
/usr/bin/ydotoold was absent. The tests passed on a machine that happens to
have it installed and failed on the CI runners that do not.

The assertions now name the warning they are about, and the helper patches
_ensure_ydotoold the way its sibling _run_with_pin already did, so nothing in
this class of test reads the host's installed packages.

* fix(text-injection): report pending IBus initialization state

* docs(text-injection): clarify backend pin behavior

* fix(config): preserve a hand-edited backend across unrelated saves

ConfigManager writes its full in-memory configuration on every save. A user who edits text_injection.backend in config.json while Vocalinux is running therefore loses that choice when an unrelated Settings or tray save writes the stale default back.

Remember only the backend value observed at load or after a successful save. If the in-memory value is unchanged, preserve the current value from disk; if it changed through ConfigManager, treat that as the intentional write. Missing and explicit auto both reset to auto.

The save aborts rather than overwriting a file whose JSON or text_injection shape cannot be read safely. This is deliberately per-key: no recursive configuration merge or injection-layer dependency is added.

* style(text-injection): remove redundant typing suppression

* fix(config): keep invalid UTF-8 config from blocking startup

* fix(config): preserve malformed backend sections on unrelated saves

* fix(config): retain text setting changes after malformed config

* test(text-injection): annotate backend pin test helpers

2026-09-29 12:24:59 -07:00

10 KiB

Raw Blame History

User guide

How to use Vocalinux day to day. Install first: INSTALL.md.

Getting started

Launch Vocalinux (vocalinux or the application menu)
Find the microphone icon in the system tray
Start dictation with the tray menu or your keyboard shortcut
Speak into the focused application; text is injected when an utterance completes
Stop by releasing the key (push-to-talk, default on new installs) or with the same shortcut (toggle)

Enable Start on Login from the first-run dialog, tray menu, or Settings. Vocalinux writes an XDG autostart entry (~/.config/autostart/vocalinux.desktop) and starts as a normal user app (--start-minimized). It does not create a systemd service.

Works on common desktop environments (GNOME, KDE, Xfce, Cinnamon, MATE, LXQt). Minimal window-manager sessions may need their own autostart helper.

Status icons

Icon state	Meaning
Gray (off)	Inactive
Blue (on)	Listening
Orange	Processing speech

Dictation formatting

Vocalinux capitalizes the start of dictation and letters after ., !, or ?. Each completed utterance leaves a trailing space so the next session does not glue onto the previous sentence.

Dictating into terminals

When Vocalinux injects through the clipboard (the usual Wayland / ydotool path), it sends Ctrl+V in ordinary text fields and Ctrl+Shift+V in terminal emulator windows. Auto-detect works on X11 and on Hyprland, Sway, and niri. On GNOME or KDE Wayland, set Settings → Dictation → Clipboard Paste Shortcut to Ctrl+Shift+V.

On non-US layouts such as German Neo, that chord uses the key that types v on the active layout (not physical KEY_V). Nested terminal panels inside an IDE are often invisible to window-class detection. If paste lands as a literal ^V or does nothing, open Settings → Dictation → Clipboard Paste Shortcut and choose Ctrl+Shift+V.

Shortcuts

Configure under Settings → Shortcuts:

Mode	Behavior
Push-to-talk (default on new installs)	Hold Right Alt (Option on Mac-layout keyboards) while speaking; release to stop
Toggle	Double-tap the configured shortcut key to start/stop

Existing configs keep their saved shortcut. Left/right modifier keys and custom modifier+key combos (for example Alt+R) are supported.

Voice commands

Optional spoken commands for punctuation and editing (can be disabled in Settings). English phrases always work. With a non-English recognition language, matching punctuation and line-break phrases in that language are also recognized (Italian virgola / punto, French virgule / point, and similar).

Command	Action
"new line" / "new paragraph"	Line break
"period" / "full stop" / "dot"	`.`
"comma"	`,`
"question mark"	`?`
"exclamation point" / "exclamation mark"	`!`
"semicolon"	`;`
"colon"	`:`
"delete that" / "scratch that"	Delete last sentence
"capitalize" / "uppercase"	Capitalize next word
"all caps"	Next word in ALL CAPS

Editing and formatting action phrases (delete that, undo, capitalize, and similar) are currently English-only.

Engines and models

Open Settings → Speech Model. The page starts with a simple setup (language and speed/accuracy). Expand Advanced for engine, model size, and specialization. Sidebar search (Ctrl+F) works across pages.

Engines

Engine	Best for	GPU	Footprint
whisper.cpp (default)	Most users	Vulkan (AMD, Intel, NVIDIA)	~74MB default model
Whisper (OpenAI)	PyTorch/CUDA workflows	NVIDIA/CUDA	Large (PyTorch stack)
Faster Whisper	CPU Whisper (CTranslate2 / INT8)	Optional CUDA	Similar model sizes to Whisper
VOSK	Low RAM / older machines	CPU	~40MB
Parakeet	CPU dictation; 25 European languages	CPU	~639MB v3-european
Remote API	Offload to a server	N/A (server-side)	Opt-in; see HTTP_REMOTE.md

Parakeet runs NVIDIA NeMo ASR models through sherpa-onnx. The default bundle is v3-european (25 European languages). v2-english is English-only. Parakeet ignores the catalog language picker (language is treated as auto).

Language

Pick the language you dictate in from Language, or leave it on auto-detect.

If you work in more than one language and switch keyboard layouts to do it, turn on Follow keyboard layout instead. Vocalinux then reads your active layout at the start of every dictation and uses the matching language, so switching layout switches dictation language with it. The Language picker greys out while this is on and shows what your current layout resolves to; turning it off pins that language.

Available for whisper.cpp, Whisper, Faster Whisper, and Remote API. VOSK loads a separate model per language, so following a layout would mean a model reload on the hotkey; Parakeet does not use the language picker at all. Active-layout detection uses GNOME's input-source settings; on other desktops it falls back to the configured primary layout.

Model size (whisper.cpp / Whisper)

Size	Approx. size	Tradeoff
tiny	~74MB	Fastest; real-time friendly
base	~141MB	Balance of speed and accuracy
small	~465MB	Better accuracy
medium	~1.5GB	High accuracy
large	~3.0GB	Best accuracy; heavier

For whisper.cpp, also pick a Specialization: standard multilingual, English-only, quantized (lower memory), Turbo, or legacy large. English-only specializations limit the language selector to English. Exact IDs (for example medium.en-q5_0, large-v3-turbo) work with --model.

Removing unused models

If leftover files are on disk that are not the model currently selected, Unused downloads appears under the model info card. Expand it to delete leftovers one at a time. Confirming removes those files from ~/.local/share/vocalinux. Packaged system-wide VOSK models are left alone.

GPU

whisper.cpp prefers Vulkan when the bundled pywhispercpp libraries include it, then CUDA, then CPU. Host tools such as vulkaninfo only describe the machine. The engine follows the libraries actually loaded. On multi-GPU machines a discrete Vulkan device is preferred; override under Settings → Performance → Vulkan GPU. Check logs with vocalinux --debug.

Pip wheels of pywhispercpp are often CUDA builds. In that case Vocalinux uses CUDA device 0. install.sh rebuilds pywhispercpp with Vulkan or CUDA when it can.

Auto-pause and keep-alive

Under Settings:

Auto-pause apps: unload the model while listed apps run
Model keep-alive: unload after idle timeout to free GPU/CPU

Tips for better recognition

Use a decent microphone and reduce background noise when you can
Speak clearly at a natural pace
Prefer tiny/base for snappy dictation; larger models when accuracy matters more than latency
English-only or quantized specializations help when they match your use case
Confirm Vulkan/CUDA in debug logs if transcription is slower than expected

CLI

vocalinux --help
vocalinux --version
vocalinux --debug
vocalinux --engine whisper_cpp
vocalinux --engine faster_whisper
vocalinux --engine parakeet
vocalinux --model medium.en-q5_0
vocalinux --wayland
vocalinux --start-minimized

Troubleshooting

vocalinux --debug

See TROUBLESHOOTING.md for tray, audio, injection, and model issues. Distro notes: DISTRO_COMPATIBILITY.md. Updates: UPDATE.md. Help channels: SUPPORT.md.

Text injection backend

Vocalinux types your dictated text using one of several backends. It picks one automatically, and on most desktops the automatic choice is correct.

Autodetection can be wrong, though, and it fails in a way that is easy to misread: on a compositor that does not relay IBus commits to native Wayland applications, IBus reports the text as delivered while nothing appears. If dictation works in some windows (typically XWayland ones, like a browser) but silently does nothing in others, that is the symptom.

Pin the backend explicitly in ~/.config/vocalinux/config.json:

{
  "text_injection": {
    "backend": "wtype"
  }
}

Value	Backend
`auto`	Autodetect (default; autodetection may select IBus)
`ibus`	IBus input method; on Wayland, bypasses compositor checks and may silently do nothing in native Wayland apps
`wtype`	wtype virtual keyboard (Wayland)
`ydotool`	ydotool uinput (Wayland; needs `ydotoold`)
`xdotool`	xdotool (X11). On Wayland it only turns IBus off -- the Wayland tool is still picked automatically

The setting takes effect on the next start. auto leaves normal autodetection in place and may select IBus. An explicit non-IBus pin (wtype, ydotool, or xdotool) skips IBus selection.

On X11 the injection tool is xdotool regardless of which non-ibus value you pin, so xdotool is the name to use there when IBus is unreliable in a particular application. Pinning ibus keeps the IBus path; pinning anything else turns it off.

To try a backend for a single run without changing the saved setting, set VOCALINUX_FORCE_BACKEND, which overrides the config value. Set it to auto to ignore a saved pin for that run:

VOCALINUX_FORCE_BACKEND=wtype vocalinux --debug

The setting and environment override are read at startup, so restart Vocalinux after editing config.json. The startup log first records a backend pin request; it does not prove the backend was available or that text reached the focused application. Later logs identify a fallback when a pin was not applied.

If a pinned tool is unavailable, Vocalinux warns and continues with its normal fallback selection. ydotool also needs a usable /dev/uinput and a working ydotoold setup. xdotool types into X11/XWayland windows, not native Wayland windows. A live test in the target application is still the final confirmation that text is delivered.

10 KiB Raw Blame History