# Noko Local dictation through the speak_to_me speech engine, integrated into Nuguland. This is a human overview, not a binding spec. ## Capture Super + grave toggles capture: first press starts, second stops and types the text. Open `noko` in the bar to start or stop capture, browse the last transcripts, copy one, or clear them. Stopping from the popup closes it, so the text lands in the window that had the keyboard. While you speak, the capture tab at the top of the screen shows the newest words; the popup shows them too. The tab says starting until the engine hears, which takes a moment when the engine was not running. Only the final text is typed into the focused Wayland control, using `wtype -` with stdin, not text-bearing arguments. A capture left running stops itself after five minutes. Push-to-talk is unavailable because niri's normal bindings provide no release event. A dictation without text says why, in the overlay and in the popup: no speech heard, the microphone was unavailable or stopped, the engine stopped, or transcription failed. ## Wake word Config → noko → wake word turns listening for a phrase on; it is off by default. While it is on, the microphone stays open: the noko chip shows its activity dot, a microphone on a vertical bar, and says so in its tooltip. Saying the phrase starts a capture like the keybind; that capture ends by itself after about 2.5 s without speech, not at the first pause. Turning it off releases the microphone at once. Before listening, noko runs one discarded recognition, so the speech model is loaded and a hit captures without delay; the engine then stays in memory (about 1.5 GB) for as long as the wake word is on. ## Hotwords Config → noko → hotwords takes one term per line, e.g. names the engine should prefer. They are stored in noko's own state file and sent with every recognition start. Terms cannot contain `/`, `@`, `:` or `#`; there are at most 64. ## What is kept The last 20 transcripts stay in local history until cleared; nothing older is stored. Audio never reaches disk: the engine captures and recognises in memory. The `noko trigger` call and diagnostics report state only, never what was said, the live words, or the hotwords. ## Engine Noko runs `speak_to_me serve` from a release on pkg.bugabinga.net and speaks JSON-RPC lines to it over stdin and stdout. The engine starts with a dictation and exits a minute after the last one, unless the wake word is on. Everything on disk lives under `$XDG_DATA_HOME/nuguland/noko` (else `~/.local/share/nuguland/noko`): - `engine//speak_to_me/`: one unpacked release per revision, `engine/current` naming the one in use; - `models/`: the model cache, shared by every revision, so an update never discards downloaded models. `noko-engine.nu` owns every path, the release URL and the engine command line: ```text nu noko-engine.nu status # installed, previous and unpacked revisions, typing tool nu noko-engine.nu check # the latest published revision nu noko-engine.nu install # download, verify, unpack beside; one JSON progress event per line nu noko-engine.nu switch nu noko-engine.nu confirm # the current revision has run once: drop the previous one nu noko-engine.nu rollback # back to the previous revision; the failed one is never installed again nu noko-engine.nu serve ``` A download is checked against the published size and SHA-256 before anything is unpacked; a mismatch leaves the installed engine and no partial file behind. `NOKO_RELEASE_URL` points the script at another release directory, e.g. a local test server. ## Updates Noko looks for a new engine at shell start and, at most once a day, when its popup opens; nothing polls while it is closed. A new revision downloads by itself and switches only while no dictation runs. If it needs models the current engine does not have, the old engine keeps dictating and Config offers to install them, naming the download size; the switch happens once they are there. The previous revision stays until the new one has typed a dictation; one that fails to start rolls back. A first install waits for Config → noko → install noko, then asks for the models the same way. ## Troubleshooting Start with Config → noko: the engine, typing tool, downloads and the wake word show there. Development checks run from `quickshell/nuguland`: `just test noko-engine`, `just test noko-service`, `just load-test noko`, `just ui-test noko`. The service test drives the production service against `fixtures/scripted-engine.mjs`, a stand-in speaking the engine's protocol. Project contracts and verification boundaries live in [RULES](../../.system/RULES.md).