signalk-openwakeword 0.0.1 → 0.1.0

package/README.md

@@ -1,16 +1,130 @@
 # 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 doestn.
 
-[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.
+Wake word detection for Signal K boats. This plugin runs
+[rhasspy/wyoming-openwakeword](https://github.com/rhasspy/wyoming-openwakeword)
+as a managed container and exposes it as a [Wyoming
+protocol](https://github.com/rhasspy/wyoming) service on your network, so
+voice satellites (cockpit Pis, the `signalk-wyoming` local satellite, or any
+Wyoming client such as Home Assistant) can stream microphone audio to it and
+get "wake word heard" events back. It is one of the
+[signalk-wyoming](https://github.com/hoeken/signalk-wyoming) voice family:
+`signalk-wyoming` (orchestrator + webapp), `signalk-whisper` (speech to
+text), `signalk-piper` (text to speech), and this plugin (wake words).
 
-| 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 |
+**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.js ≥ 24
+- The [signalk-container](https://www.npmjs.com/package/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 (plus
+signalk-container if you don't have it), enable it in Plugin Config, and the
+plugin pulls and starts `rhasspy/wyoming-openwakeword` pinned to a tested
+release. The plugin reports `ready` only once the service answers a Wyoming
+`describe` request — proof the detector is actually up, not just the
+container.
+
+## Configuration
+
+| Setting                      | Default          | Notes                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `wakeWords`                  | `["okay_nabu"]`  | Wake words your satellites use. Built-ins: `okay_nabu`, `hey_jarvis`, `hey_mycroft`, `alexa`, `hey_rhasspy`. **Not** passed to the container — Wyoming clients select models per connection (`Detect` event); this list is validated against the running service and shared with the orchestrator. ⚠️ upstream 2.0.0 renamed `ok_nabu` → `okay_nabu`; the old name silently matches nothing. |
+| `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` pins the tested upstream release (currently `2.1.0`); set an explicit Docker tag to override.                                                                                                                                                                                                                                                                                         |
+| `memoryLimit`                | `384m`           | Container memory cap (swap disabled).                                                                                                                                                                                                                                                                                                                                                        |
+| `restartPolicy`              | `unless-stopped` | Container restart policy.                                                                                                                                                                                                                                                                                                                                                                    |
+| `advanced.refractorySeconds` | _(unset)_        | `--refractory-seconds` — minimum seconds between re-detections (upstream default 2.0).                                                                                                                                                                                                                                                                                                       |
+| `advanced.customModels`      | `false`          | Mounts the shared signalk-container data directory at `/data` and passes `--custom-model-dir /data/custom`. 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).                                                                                                                                                                                                                                                                                            |
+
+## Using it from other software
+
+The service speaks plain Wyoming over TCP at `tcp://<boat-server>:10400`.
+The `signalk-wyoming` orchestrator discovers it automatically via the
+`wyoming-service` PropertyValues convention:
+
+```js
+{ plugin: 'signalk-openwakeword', type: 'wake', uri: 'tcp://127.0.0.1:10400', status: 'ready' }
+```
+
+Standalone use works too: point Home Assistant's Wyoming integration, a
+`wyoming-satellite` (`--wake-uri tcp://<boat-server>:10400
+--wake-word-name okay_nabu`), or any other Wyoming client at the URI — no
+Signal K required on the client side.
+
+## Health & notifications
+
+- Readiness and liveness are protocol-native: a periodic Wyoming `describe`
+  ping must return a valid `info` response. Three consecutive failures set a
+  plugin error, emit `wyoming-service` status `error`, and raise the
+  `notifications.voice.openwakeword` notification with `state: 'alarm'`
+  (method `['visual']` — deliberately not `'sound'`, so notification-to-speech
+  bridges don't narrate voice-stack outages). Recovery clears it back to
+  `normal`.
+- Plugin status shows what's happening at each stage (image pull, waiting
+  for the service, running).
+- `GET /plugins/signalk-openwakeword/api/status` returns
+  `{ status, uri, tag, containerState, lastHealth, info }` (readonly access).
+  `GET /api/update/check` / `POST /api/update/apply` (admin) manage container
+  image updates.
+
+## 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`.
+
+## Custom wake words
+
+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) and restart the plugin. The mount is provided
+by signalk-container's `signalkDataMount`, which always maps `/data` to
+signalk-container's _own_ data directory (shared by every plugin that uses
+it), **not** to this plugin's `plugin-config-data/signalk-openwakeword/`
+directory. If Signal K itself runs in a container with a volume-backed data
+directory, put the files in the corresponding location inside that volume.
+The container loads them via `--custom-model-dir /data/custom`; 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.
+
+## Development
+
+```bash
+npm install
+npm run build                 # tsc → dist/
+npm test                      # typecheck + vitest (mock Wyoming server, fake container manager)
+npm run ci-lint               # eslint + prettier --check
+```
+
+Tests never touch docker: the container manager is faked and the Wyoming
+endpoint is the scriptable `signalk-wyoming/mock` server (a devDependency
+on the [signalk-wyoming](https://github.com/hoeken/signalk-wyoming)
+package). Production code has no runtime dependency on it — the plugin
+embeds its own ~150-line `describe` client.
 
 ## 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,EAKL,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;AAID,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,CAoHpB"}