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.

First dictation

There is no permission prompt on niri. The RemoteDesktop portal is never used there, because no portal backend implements it, so your first dictation types straight into the focused window through wtype with nothing to approve or deny. Do not pin portal as a niri recommendation. IBus is excluded on niri as well. The GNOME and KDE first-run behaviour is described in USER_GUIDE.md.

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.