# niri and Dank Material Shell

Dictation on the [niri](https://github.com/YaLTeR/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](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`):

```bash
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):

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

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

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

The shipped bind:

```kdl
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](../packaging/flatpak/README.md#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:

```bash
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.