voculinux/docs/NIRI.md

niri and Dank Material Shell

Dictation on the niri Wayland compositor, including sessions running Dank Material Shell (DMS). There is no compositor-specific code: activation reuses the standard external triggers over D-Bus, and the tray is the standard StatusNotifier item.

Prerequisites

1. Install Voculinux first: INSTALL.md.
2. Open Settings → Shortcuts and turn on External Activation (Desktop Shortcut). The built-in key listener stops, and a running instance answers these triggers on the session bus (com.voculinux.Voculinux):

voculinux --toggle   # start if idle, stop if active
voculinux --start    # start voice typing
voculinux --stop     # stop voice typing

Keybind: toggle once per press

Either paste the bind below into the binds {} section of ~/.config/niri/config.kdl, or copy the ready-made include file and reference it (easier to keep across config edits):

mkdir -p ~/.config/niri
cp resources/niri/voculinux.kdl ~/.config/niri/voculinux.kdl

then near the top of ~/.config/niri/config.kdl:

include "~/.config/niri/voculinux.kdl"

The shipped bind:

binds {
    Mod+Shift+D repeat=false hotkey-overlay-title="Toggle Voculinux dictation" {
        spawn "voculinux" "--toggle";
    }
}

repeat=false is what makes it toggle once per press: without it, holding the key repeats the spawn and toggles dictation back off before you let go. Pick any key you like (the overlay title keeps it discoverable under Mod+H), and uncomment the --start / --stop variants in the include file if you want dedicated keys.

A key is either a compositor bind or an in-app Voculinux shortcut — never both. With External Activation on, do not keep the same key configured under Settings → Shortcuts; with it off, remove the niri bind. A key claimed on both sides fires twice: the compositor toggles over D-Bus while the internal listener fires on its own.

Hold-to-talk stays in the app

A compositor bind only sends the key press; it never sees the release, so it can only toggle dictation. Push-to-talk (hold Right Alt, release to stop) keeps working only through the built-in Voculinux shortcut. This pack ships plain press binds only, so if you dictate with hold-to-talk, leave the in-app shortcut in place for it and use the niri bind for toggle.

Flatpak

voculinux is not on the host PATH from a sandbox, so bind the host D-Bus call instead (same toggle, no extra sandbox spawned per press). The include file carries a commented-out gdbus variant; background and the exact command live under Running without device access.

Tray under Dank Material Shell

Not yet observed on hardware: the StatusNotifier watcher bus name (or names) DMS owns will be recorded with ticket #32, the hardware acceptance run. The tray probe (_check_status_notifier_watcher in src/vocalinux/ui/tray_indicator.py) currently accepts only org.kde.StatusNotifierWatcher, and no probe code changed in this ticket.

The observation to record on #32, with a DMS session running:

busctl --user list | grep -i -E 'watcher|statusnotifier'

If DMS owns only org.freedesktop.StatusNotifierWatcher, the probe is widened to accept both watcher names so no false missing-tray warning appears, with behaviour tests covering both names. If org.kde.StatusNotifierWatcher is present, the current probe stands and the recorded output closes the question.