signalk-openwakeword 0.0.1 → 0.2.0

package/README.md

@@ -1,16 +1,159 @@
 # signalk-openwakeword
 
-> **Status: pre-release placeholder.** This package reserves the name — nothing is functional yet. The design is under community review at **[hoeken/signalk-wyoming](https://github.com/hoeken/signalk-wyoming)** — read the spec there and leave feedback.
+> **Status: ALPHA.** This SignalK Wyoming system is 100% vibecoded slop. I
+> don't have the right hardware yet to test it, so I'm putting it out there
+> for people to test in the meantime. It _should_ work. File issues for
+> anything that doesn't.
 
-[Wyoming](https://github.com/rhasspy/wyoming) [openWakeWord](https://github.com/rhasspy/wyoming-openwakeword) wake word detection service for [Signal K](https://signalk.org), running as a managed container. Part of the **signalk-wyoming** offline voice assistant family, but fully standalone: any Wyoming client (including Home Assistant) can use it.
+## What is this?
 
-| Plugin | Role |
-|--------|------|
-| [signalk-wyoming](https://github.com/hoeken/signalk-wyoming) | Orchestrator — spec and discussion live here |
-| [signalk-whisper](https://github.com/hoeken/signalk-whisper) | Speech-to-text |
-| [signalk-piper](https://github.com/hoeken/signalk-piper) | Text-to-speech |
-| **signalk-openwakeword** | Wake word detection |
+Wake word detection for [Signal K](https://signalk.org) — the part of a
+voice assistant that listens for "okay nabu" (or "hey jarvis", "alexa", …)
+so the rest of the stack knows when to start paying attention. The plugin
+runs [openWakeWord](https://github.com/rhasspy/wyoming-openwakeword) as a
+background service and takes care of everything around it: starting it in a
+container (via the
+[signalk-container](https://www.npmjs.com/package/signalk-container)
+plugin), checking that it stays healthy, and telling the rest of the voice
+stack where to find it. You never have to touch docker or podman yourself.
+
+It is the wake-word building block of the
+[signalk-wyoming voice-assistant family](https://github.com/hoeken/signalk-wyoming)
+— install it together with the `signalk-wyoming` orchestrator,
+`signalk-whisper` (speech to text), and `signalk-piper` (text to speech) to
+get voice commands on your boat. Because it speaks the standard
+[Wyoming protocol](https://github.com/rhasspy/wyoming), it also works as a
+standalone wake word server for other software such as Home Assistant.
+
+**Fully offline:** all wake word models ship inside the container image.
+First start pulls the ~90 MB image and nothing else — no model downloads,
+no surprises at sea.
+
+## Requirements
+
+- Signal K server ≥ 2.x on **Node 24+**
+- The **signalk-container** plugin with a working podman or docker runtime
+- ~384 MB RAM headroom for the container (the default memory cap)
+- amd64 or arm64 (no armv7 — upstream stopped publishing it)
+
+## Install
+
+Install **signalk-openwakeword** from the Signal K App Store (or
+`npm install signalk-openwakeword` in your server directory), enable it in
+Plugin Config, and enable the signalk-container plugin if you have not
+already. The plugin pulls and starts a pinned, tested release of the
+service and reports `ready` once the detector actually answers — not just
+once the container is up.
+
+## Configuration
+
+The plugin ships a graphical configuration panel (Server → Plugin Config →
+openWakeWord) with a live container status card, a one-click image update
+check/apply, a version dropdown fed by Docker Hub, wake word checkboxes
+driven by the models the running service actually advertises, and all the
+settings below — with inline warnings when a selected wake word is missing
+or the service is open to the network. On servers without custom-panel
+support you get a plain settings form with the same options.
+
+| Setting                      | Default          | Notes                                                                                                                                     |
+| ---------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `wakeWords`                  | `["okay_nabu"]`  | Wake words your satellites use. See [Wake words & sensitivity](#wake-words--sensitivity).                                                 |
+| `threshold`                  | `0.5`            | Wake probability threshold (0–1). Lower = more sensitive, more false wakes.                                                               |
+| `triggerLevel`               | `1`              | Activations above the threshold before a detection fires. Raise it in noisy cabins.                                                       |
+| `port`                       | `10400`          | Host TCP port the Wyoming service is published on.                                                                                        |
+| `bind`                       | `0.0.0.0`        | Host interface for the published port. See [Security](#security).                                                                         |
+| `imageTag`                   | `auto`           | `auto` runs the pinned, tested upstream release (**2.1.0**) and follows plugin updates. Set an explicit Docker tag to pin something else. |
+| `memoryLimit`                | `384m`           | Container memory cap (swap disabled).                                                                                                     |
+| `restartPolicy`              | `unless-stopped` | Container restart policy.                                                                                                                 |
+| `advanced.refractorySeconds` | _(unset)_        | Minimum seconds between re-detections (upstream default 2.0).                                                                             |
+| `advanced.customModels`      | `false`          | Load your own model files. See [Custom wake words](#custom-wake-words).                                                                   |
+| `advanced.advertiseHost`     | _(unset)_        | Overrides the host part of the advertised `tcp://` URI (containerized Signal K, multi-NIC hosts).                                         |
+
+### Wake words & sensitivity
+
+The built-in wake words are `okay_nabu` (default), `hey_jarvis`,
+`hey_mycroft`, `alexa`, and `hey_rhasspy`. The `wakeWords` list is what
+your satellites will listen for — it is validated against the running
+service and shared with the `signalk-wyoming` orchestrator, and the config
+panel warns you if a selected word is not available (note: upstream 2.0.0
+renamed `ok_nabu` to `okay_nabu`; the old name silently matches nothing).
+
+Tuning for your boat:
+
+- **Missing wakes** (it doesn't hear you): lower `threshold` a little, e.g.
+  `0.4`.
+- **False wakes** (it triggers on engine noise or conversation): raise
+  `threshold`, or raise `triggerLevel` to `2`–`3` so a single borderline
+  hit isn't enough.
+- **Double triggers** from one utterance: set
+  `advanced.refractorySeconds` (upstream default is 2 seconds between
+  re-detections).
+
+## Custom wake words
+
+Want your boat to answer to its own name? Enable
+`advanced.customModels`, then drop openWakeWord `.tflite` model files into
+the `custom/` folder inside the **signalk-container** plugin's data
+directory (`<signalk>/plugin-config-data/signalk-container/custom/` —
+create `custom/` if it doesn't exist; note this is signalk-container's
+directory, shared by all plugins that use it, not this plugin's own) and
+restart the plugin. If Signal K itself runs in a container with a
+volume-backed data directory, put the files in the corresponding location
+inside that volume. A `_v1.0`-style filename suffix is stripped for the
+model id. A webapp upload UI is planned for v1.x; the manual drop works
+today.
+
+## Using it from other software
+
+Once ready, the service is a plain Wyoming wake word server at
+`tcp://<boat-server>:10400`:
+
+- **signalk-wyoming** discovers it automatically — nothing to configure.
+- **Remote satellites** (cockpit Pis running `wyoming-satellite`) point at
+  it with `--wake-uri tcp://<boat-server>:10400 --wake-word-name okay_nabu`.
+- **Home Assistant** (or any other Wyoming client) can use it via the
+  Wyoming integration at the same URI — no Signal K required on the client
+  side.
+
+## HTTP API
+
+| Endpoint                                              | Access                 | Purpose                                                                                        |
+| ----------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------- |
+| `GET /plugins/signalk-openwakeword/api/status`        | any authenticated user | Current state: `{ status, uri, tag, containerState, lastHealth, info }`                        |
+| `GET /plugins/signalk-openwakeword/api/versions`      | any authenticated user | Available image versions from Docker Hub (feeds the config panel; works while plugin disabled) |
+| `GET /plugins/signalk-openwakeword/api/update/check`  | admin                  | Check whether a newer image is available                                                       |
+| `POST /plugins/signalk-openwakeword/api/update/apply` | admin                  | Pull and switch to the newer image                                                             |
+
+## Health & notifications
+
+The plugin checks the service every 30 seconds. If it stops answering,
+after three consecutive failures (about 90 seconds) it raises the Signal K
+notification **`notifications.voice.openwakeword`** with `state: "alarm"`
+and shows an error in Plugin Config. When the service answers again
+everything clears back to normal automatically — no action needed.
+
+The alarm is visual-only by design: plugins that read notifications aloud
+won't try to _speak_ the voice stack's own failure.
+
+## Security
+
+Wyoming has **no authentication.** Unlike whisper/piper (loopback-only by
+default), the wake word service must be reachable from your LAN so remote
+satellites can stream audio to it — that is why `bind` defaults to
+`0.0.0.0`. The exposure is modest (openWakeWord only ever sees audio a
+client chooses to send it, and only ever answers with detections), but the
+_satellites_ on the same network are open live microphones — treat every
+satellite port like a baby monitor. On marina wifi, put the boat network
+behind a firewall or VLAN, or use WireGuard between boat segments. If every
+satellite runs on the server itself, set `bind` to `127.0.0.1`.
+
+## Development
+
+See [DEVELOPERS.md](DEVELOPERS.md) for the code layout, build/test
+commands, architecture notes, and the service-discovery contract.
 
 ## License
 
-Apache-2.0
+Apache-2.0 © hoeken. The container image it runs is
+[rhasspy/wyoming-openwakeword](https://github.com/rhasspy/wyoming-openwakeword)
+(MIT).

package/dist/config.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Configuration: settings type, defaults, JSON schema for the Signal K
+ * Plugin Config UI, and the pure settings → container-config mapping.
+ */
+import type { ContainerConfig } from "signalk-container-helper";
+export declare const PLUGIN_ID = "signalk-openwakeword";
+export declare const PLUGIN_NAME = "openWakeWord (Wyoming)";
+export declare const IMAGE = "rhasspy/wyoming-openwakeword";
+/** Tag that `imageTag: "auto"` resolves to. */
+export declare const PINNED_TAG = "2.1.0";
+/** Wyoming port inside the container (baked into the image's ENTRYPOINT). */
+export declare const WYOMING_PORT = 10400;
+/** Container name (unprefixed; runtime name is `<namespace>-openwakeword`). */
+export declare const CONTAINER_NAME = "openwakeword";
+/** Short service name used in `notifications.voice.<service>`. */
+export declare const SERVICE_NAME = "openwakeword";
+/**
+ * Wake word models bundled with wyoming-openwakeword 2.x. Note the 2.0.0
+ * breaking rename: `ok_nabu` → `okay_nabu`.
+ */
+export declare const BUILTIN_WAKE_WORDS: string[];
+export interface AdvancedSettings {
+    /** → --refractory-seconds (upstream default 2.0 when omitted). */
+    refractorySeconds?: number;
+    /**
+     * Mount the shared signalk-container data dir at /data and pass
+     * --custom-model-dir /data/custom.
+     */
+    customModels: boolean;
+    /** Replaces the host part of the advertised wyoming-service uri. */
+    advertiseHost?: string;
+}
+export interface OpenWakeWordSettings {
+    imageTag: string;
+    /** Host TCP port the container's Wyoming port is published on. */
+    port: number;
+    /** Host interface the port binds to. LAN-reachable by default (see §8). */
+    bind: "0.0.0.0" | "127.0.0.1";
+    /**
+     * Wake words satellites may use. NOT passed to the container (2.x selects
+     * models per client via the Wyoming `Detect` event) — validated against
+     * the service's `info` response and surfaced for orchestrator/docs use.
+     */
+    wakeWords: string[];
+    /** → --threshold (0–1). */
+    threshold: number;
+    /** → --trigger-level (activations above threshold before a detection). */
+    triggerLevel: number;
+    memoryLimit: string;
+    restartPolicy: "no" | "unless-stopped" | "always";
+    advanced: AdvancedSettings;
+}
+export declare const DEFAULT_SETTINGS: OpenWakeWordSettings;
+/**
+ * Merge raw plugin config over the defaults. Signal K does NOT seed schema
+ * defaults into a plugin's saved configuration, so every field must be
+ * defaulted here. Tolerates missing/malformed input.
+ */
+export declare function withDefaults(raw: unknown): OpenWakeWordSettings;
+/** Map `auto` to the pinned upstream release; explicit tags pass through. */
+export declare function resolveTag(requested: string): string;
+/** True for plain numeric semver tags like "2.1.0" (update-check filter). */
+export declare function isSemverTag(tag: string): boolean;
+/**
+ * Container CLI args, appended after the image's baked-in
+ * `--uri tcp://0.0.0.0:10400`. Always present and deterministic so
+ * signalk-container's drift detection never sees a phantom change.
+ */
+export declare function buildCommand(settings: OpenWakeWordSettings): string[];
+/**
+ * Pure settings → ContainerConfig mapping (helper `buildConfig`).
+ *
+ * openWakeWord must be LAN-reachable for remote satellites (SPEC §8), so the
+ * port is published explicitly via `ports` with a default bind of 0.0.0.0 —
+ * NOT via `signalkAccessiblePorts` (the two must never share a container
+ * port: the loopback mapping would overwrite the explicit binding).
+ */
+export declare function buildContainerConfig(settings: OpenWakeWordSettings, tag: string): ContainerConfig;
+export declare const CONFIG_SCHEMA: {
+    type: string;
+    properties: {
+        wakeWords: {
+            type: string;
+            title: string;
+            items: {
+                type: string;
+            };
+            default: string[];
+            description: string;
+        };
+        threshold: {
+            type: string;
+            title: string;
+            minimum: number;
+            maximum: number;
+            default: number;
+            description: string;
+        };
+        triggerLevel: {
+            type: string;
+            title: string;
+            minimum: number;
+            default: number;
+            description: string;
+        };
+        port: {
+            type: string;
+            title: string;
+            default: number;
+            description: string;
+        };
+        bind: {
+            type: string;
+            title: string;
+            enum: string[];
+            default: "0.0.0.0" | "127.0.0.1";
+            description: string;
+        };
+        imageTag: {
+            type: string;
+            title: string;
+            default: string;
+            description: string;
+        };
+        memoryLimit: {
+            type: string;
+            title: string;
+            default: string;
+            description: string;
+        };
+        restartPolicy: {
+            type: string;
+            title: string;
+            enum: string[];
+            default: "no" | "unless-stopped" | "always";
+            description: string;
+        };
+        advanced: {
+            type: string;
+            title: string;
+            properties: {
+                refractorySeconds: {
+                    type: string;
+                    title: string;
+                    description: string;
+                };
+                customModels: {
+                    type: string;
+                    title: string;
+                    default: boolean;
+                    description: string;
+                };
+                advertiseHost: {
+                    type: string;
+                    title: string;
+                    description: string;
+                };
+            };
+        };
+    };
+};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,eAAO,MAAM,SAAS,yBAAyB,CAAC;AAChD,eAAO,MAAM,WAAW,2BAA2B,CAAC;AACpD,eAAO,MAAM,KAAK,iCAAiC,CAAC;AACpD,+CAA+C;AAC/C,eAAO,MAAM,UAAU,UAAU,CAAC;AAClC,6EAA6E;AAC7E,eAAO,MAAM,YAAY,QAAQ,CAAC;AAClC,+EAA+E;AAC/E,eAAO,MAAM,cAAc,iBAAiB,CAAC;AAC7C,kEAAkE;AAClE,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,kBAAkB,UAM9B,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;IACtB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,IAAI,EAAE,SAAS,GAAG,WAAW,CAAC;IAC9B;;;;OAIG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,IAAI,GAAG,gBAAgB,GAAG,QAAQ,CAAC;IAClD,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED,eAAO,MAAM,gBAAgB,EAAE,oBAY9B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,oBAAoB,CA4B/D;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAiBrE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,oBAAoB,EAC9B,GAAG,EAAE,MAAM,GACV,eAAe,CAsBjB;AAuBD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkHzB,CAAC"}

package/dist/config.js

@@ -0,0 +1,255 @@
+/**
+ * Configuration: settings type, defaults, JSON schema for the Signal K
+ * Plugin Config UI, and the pure settings → container-config mapping.
+ */
+export const PLUGIN_ID = "signalk-openwakeword";
+export const PLUGIN_NAME = "openWakeWord (Wyoming)";
+export const IMAGE = "rhasspy/wyoming-openwakeword";
+/** Tag that `imageTag: "auto"` resolves to. */
+export const PINNED_TAG = "2.1.0";
+/** Wyoming port inside the container (baked into the image's ENTRYPOINT). */
+export const WYOMING_PORT = 10400;
+/** Container name (unprefixed; runtime name is `<namespace>-openwakeword`). */
+export const CONTAINER_NAME = "openwakeword";
+/** Short service name used in `notifications.voice.<service>`. */
+export const SERVICE_NAME = "openwakeword";
+/**
+ * Wake word models bundled with wyoming-openwakeword 2.x. Note the 2.0.0
+ * breaking rename: `ok_nabu` → `okay_nabu`.
+ */
+export const BUILTIN_WAKE_WORDS = [
+    "okay_nabu",
+    "hey_jarvis",
+    "hey_mycroft",
+    "alexa",
+    "hey_rhasspy",
+];
+export const DEFAULT_SETTINGS = {
+    imageTag: "auto",
+    port: WYOMING_PORT,
+    bind: "0.0.0.0",
+    wakeWords: ["okay_nabu"],
+    threshold: 0.5,
+    triggerLevel: 1,
+    memoryLimit: "384m",
+    restartPolicy: "unless-stopped",
+    advanced: {
+        customModels: false,
+    },
+};
+/**
+ * Merge raw plugin config over the defaults. Signal K does NOT seed schema
+ * defaults into a plugin's saved configuration, so every field must be
+ * defaulted here. Tolerates missing/malformed input.
+ */
+export function withDefaults(raw) {
+    const cfg = isObject(raw) ? raw : {};
+    const adv = isObject(cfg.advanced) ? cfg.advanced : {};
+    const settings = {
+        imageTag: str(cfg.imageTag) ?? DEFAULT_SETTINGS.imageTag,
+        port: num(cfg.port) ?? DEFAULT_SETTINGS.port,
+        bind: cfg.bind === "127.0.0.1" ? "127.0.0.1" : DEFAULT_SETTINGS.bind,
+        wakeWords: strArray(cfg.wakeWords) ?? [...DEFAULT_SETTINGS.wakeWords],
+        threshold: num(cfg.threshold) ?? DEFAULT_SETTINGS.threshold,
+        triggerLevel: num(cfg.triggerLevel) ?? DEFAULT_SETTINGS.triggerLevel,
+        memoryLimit: str(cfg.memoryLimit) ?? DEFAULT_SETTINGS.memoryLimit,
+        restartPolicy: cfg.restartPolicy === "no" || cfg.restartPolicy === "always"
+            ? cfg.restartPolicy
+            : DEFAULT_SETTINGS.restartPolicy,
+        advanced: {
+            customModels: adv.customModels === true,
+        },
+    };
+    const refractory = num(adv.refractorySeconds);
+    if (refractory !== undefined) {
+        settings.advanced.refractorySeconds = refractory;
+    }
+    const advertiseHost = str(adv.advertiseHost);
+    if (advertiseHost !== undefined && advertiseHost.trim() !== "") {
+        settings.advanced.advertiseHost = advertiseHost.trim();
+    }
+    return settings;
+}
+/** Map `auto` to the pinned upstream release; explicit tags pass through. */
+export function resolveTag(requested) {
+    return requested === "auto" ? PINNED_TAG : requested;
+}
+/** True for plain numeric semver tags like "2.1.0" (update-check filter). */
+export function isSemverTag(tag) {
+    return /^\d+\.\d+\.\d+$/.test(tag);
+}
+/**
+ * Container CLI args, appended after the image's baked-in
+ * `--uri tcp://0.0.0.0:10400`. Always present and deterministic so
+ * signalk-container's drift detection never sees a phantom change.
+ */
+export function buildCommand(settings) {
+    const command = [
+        "--threshold",
+        String(settings.threshold),
+        "--trigger-level",
+        String(settings.triggerLevel),
+    ];
+    if (settings.advanced.refractorySeconds !== undefined) {
+        command.push("--refractory-seconds", String(settings.advanced.refractorySeconds));
+    }
+    if (settings.advanced.customModels) {
+        command.push("--custom-model-dir", "/data/custom");
+    }
+    return command;
+}
+/**
+ * Pure settings → ContainerConfig mapping (helper `buildConfig`).
+ *
+ * openWakeWord must be LAN-reachable for remote satellites (SPEC §8), so the
+ * port is published explicitly via `ports` with a default bind of 0.0.0.0 —
+ * NOT via `signalkAccessiblePorts` (the two must never share a container
+ * port: the loopback mapping would overwrite the explicit binding).
+ */
+export function buildContainerConfig(settings, tag) {
+    const config = {
+        image: IMAGE,
+        tag,
+        command: buildCommand(settings),
+        ports: {
+            [String(WYOMING_PORT)]: `${settings.bind}:${settings.port}`,
+        },
+        restart: settings.restartPolicy,
+        resources: {
+            memory: settings.memoryLimit,
+            memorySwap: settings.memoryLimit,
+        },
+    };
+    if (settings.advanced.customModels) {
+        // signalkDataMount resolves to the signalk-container plugin's OWN data
+        // directory (one globally-cached app.getDataDirPath() of that plugin,
+        // shared by every consumer) — NOT this plugin's. Users drop .tflite
+        // files in <signalk>/plugin-config-data/signalk-container/custom/.
+        config.signalkDataMount = "/data";
+    }
+    return config;
+}
+function isObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function str(v) {
+    return typeof v === "string" && v !== "" ? v : undefined;
+}
+function num(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+function strArray(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const out = v
+        .filter((x) => typeof x === "string")
+        .map((x) => x.trim())
+        .filter((x) => x !== "");
+    return out.length > 0 ? out : undefined;
+}
+export const CONFIG_SCHEMA = {
+    type: "object",
+    properties: {
+        wakeWords: {
+            type: "array",
+            title: "Wake words",
+            items: { type: "string" },
+            default: [...DEFAULT_SETTINGS.wakeWords],
+            description: "Wake word models your satellites will use. Built-ins: " +
+                `${BUILTIN_WAKE_WORDS.join(", ")}. NOTE: version 2.0.0 renamed ` +
+                "ok_nabu to okay_nabu — old configs using ok_nabu silently match " +
+                "nothing. This list is not passed to the container (clients select " +
+                "models per connection); it is checked against the running service " +
+                "and used by the signalk-wyoming orchestrator.",
+        },
+        threshold: {
+            type: "number",
+            title: "Detection threshold",
+            minimum: 0,
+            maximum: 1,
+            default: DEFAULT_SETTINGS.threshold,
+            description: "Wake probability required to activate (0–1). Lower = more " +
+                "sensitive but more false wakes.",
+        },
+        triggerLevel: {
+            type: "integer",
+            title: "Trigger level",
+            minimum: 1,
+            default: DEFAULT_SETTINGS.triggerLevel,
+            description: "Number of activations above the threshold before a detection " +
+                "fires. Raise to reduce false wakes in noisy cabins.",
+        },
+        port: {
+            type: "number",
+            title: "Host port",
+            default: DEFAULT_SETTINGS.port,
+            description: "Host TCP port the Wyoming service is published on " +
+                "(remote satellites connect to tcp://<boat-server>:<this port>).",
+        },
+        bind: {
+            type: "string",
+            title: "Bind address",
+            enum: ["0.0.0.0", "127.0.0.1"],
+            default: DEFAULT_SETTINGS.bind,
+            description: "SECURITY: the default 0.0.0.0 makes the wake word service " +
+                "reachable from your whole network — required for remote " +
+                "satellites, and safe-ish (it only ever sees audio that clients " +
+                "send it), but Wyoming has no authentication, so firewall or VLAN " +
+                "the boat network on marina wifi. Set 127.0.0.1 if every satellite " +
+                "runs on this machine.",
+        },
+        imageTag: {
+            type: "string",
+            title: "Image tag",
+            default: DEFAULT_SETTINGS.imageTag,
+            description: `Docker tag of ${IMAGE} to run. "auto" pins the tested release ` +
+                `(${PINNED_TAG}) and follows plugin updates; set an explicit tag ` +
+                "to stay on a specific upstream version.",
+        },
+        memoryLimit: {
+            type: "string",
+            title: "Memory limit",
+            default: DEFAULT_SETTINGS.memoryLimit,
+            description: 'Container memory cap (e.g. "384m", "1g"). Swap is disabled by ' +
+                "setting the swap limit to the same value.",
+        },
+        restartPolicy: {
+            type: "string",
+            title: "Restart policy",
+            enum: ["no", "unless-stopped", "always"],
+            default: DEFAULT_SETTINGS.restartPolicy,
+            description: "Container restart policy passed to docker/podman.",
+        },
+        advanced: {
+            type: "object",
+            title: "Advanced",
+            properties: {
+                refractorySeconds: {
+                    type: "number",
+                    title: "Refractory seconds",
+                    description: "Minimum seconds between repeated detections of the same wake " +
+                        "word (--refractory-seconds). Upstream default: 2.0.",
+                },
+                customModels: {
+                    type: "boolean",
+                    title: "Enable custom wake word models",
+                    default: DEFAULT_SETTINGS.advanced.customModels,
+                    description: "Mount the shared signalk-container plugin data directory into " +
+                        "the container and load custom .tflite models from its custom/ " +
+                        "subdirectory (--custom-model-dir /data/custom). Drop model " +
+                        "files into plugin-config-data/signalk-container/custom/ (NOT " +
+                        "this plugin's own data directory) and restart the plugin.",
+                },
+                advertiseHost: {
+                    type: "string",
+                    title: "Advertise host",
+                    description: "Overrides the host part of the tcp:// URI advertised to the " +
+                        "signalk-wyoming orchestrator (for containerized Signal K or " +
+                        "multi-NIC hosts where 127.0.0.1 is not what consumers should " +
+                        "dial). Leave empty for automatic.",
+                },
+            },
+        },
+    },
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * signalk-openwakeword — Signal K plugin entry point.
+ *
+ * Runs rhasspy/wyoming-openwakeword (pinned 2.1.0) as a managed container via
+ * signalk-container-helper, gates readiness on a Wyoming `describe` exchange,
+ * advertises the service on the shared `wyoming-service` PropertyValues
+ * convention, and keeps a protocol-native health loop running.
+ */
+import { type RouterLike } from "signalk-container-helper";
+import { type RunnerTiming, type ServiceApp } from "./service.js";
+export interface PluginApp extends ServiceApp {
+    savePluginOptions(configuration: object, callback: (err: unknown) => void): void;
+    readPluginOptions?(): {
+        configuration?: Record<string, unknown>;
+    } | undefined;
+}
+export interface PluginRouter extends RouterLike {
+    /** Signal K ≥2.x permission registrar; feature-detected. */
+    access?(level: "readonly" | "readwrite"): RouterLike;
+}
+export interface OpenWakeWordPlugin {
+    id: string;
+    name: string;
+    description: string;
+    schema: () => object;
+    start: (config: object) => void;
+    stop: () => Promise<void>;
+    registerWithRouter: (router: PluginRouter) => void;
+}
+/**
+ * Plugin factory. The optional `timing` parameter is a test seam — the
+ * Signal K loader only ever passes `app`.
+ */
+export default function createPlugin(app: PluginApp, timing?: Partial<RunnerTiming>): OpenWakeWordPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAML,KAAK,UAAU,EAChB,MAAM,0BAA0B,CAAC;AAalC,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C,iBAAiB,CACf,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAC/B,IAAI,CAAC;IACR,iBAAiB,CAAC,IAAI;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,SAAS,CAAC;CAC/E;AAOD,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,4DAA4D;IAC5D,MAAM,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;CACtD;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,MAAM,CAAC;IACrB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,kBAAkB,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;CACpD;AAED;;;GAGG;AACH,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,GAAG,EAAE,SAAS,EACd,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,kBAAkB,CAgJpB"}