speechkit-wakeword

Overview ¶

speechkit-wakeword is the sidecar binary that hosts SpeechKit's on-device keyword spotter outside the main desktop process.

Build tag: requires cgo. The sherpa-onnx KWS engine is a native shared library bound via github.com/k2-fsa/sherpa-onnx-go, which cannot link when CGO_ENABLED=0. Production builds via scripts/build.ps1 enable cgo; for `go build ./...` clean compiles in cgo-disabled dev environments the package is correctly skipped.

Why a sidecar: github.com/k2-fsa/sherpa-onnx-go works correctly when it is the only ONNX consumer in a process and gets to control thread setup at startup. In SpeechKit's Wails-alpha host process the runtime initialisation races with whatever Wails has already set up and aborts natively. LiveKit's own wake-word reference (livekit/livekit-wakeword) resolves the same class of problem the same way — wake-word runs as a sibling process to the agent, not in-process.

IPC contract (stable across SpeechKit clients):

• stdout: JSON events, one per line. Schema in ipc.go (Event).
• stdin: JSON commands, one per line. Schema in ipc.go (Command).
• stderr: structured slog logs (json handler) — useful in CI and for tail-fanning into the main app's log surface.

Exit codes:

0 — clean shutdown after a shutdown command or stdin EOF.
2 — runtime / model error (host should restart with backoff).
3 — bad config (model assets missing; host should NOT restart until
    config changes).

The Windows reference adapter in cmd/speechkit/desktop_wakeword.go owns the process lifecycle: it spawns this binary, parses stdout line-by-line, forwards detections into the desktop's hotkey-event bus, and respawns the sidecar on unexpected exit. Other client adapters (Local-Target CLI, future Android/iOS gomobile shells) follow the same pattern.