@framers/agentos-ext-openwakeword 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Framers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

package/SKILL.md

@@ -0,0 +1,17 @@
+# openwakeword — ONNX Wake-Word Extension Pack
+
+Provides wake-word detection using [OpenWakeWord](https://github.com/dscripka/openWakeWord) ONNX models via `onnxruntime-node`.
+
+## Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `modelPath` | `OPENWAKEWORD_MODEL_PATH` env or `~/.agentos/models/openwakeword/hey_mycroft.onnx` | Path to ONNX model file |
+| `threshold` | `0.5` | Detection probability threshold |
+| `keyword` | `'hey mycroft'` | Human-readable keyword label |
+
+## Features
+- Fully offline — no network required
+- Any ONNX-compatible wake-word model supported
+- Configurable detection threshold
+- Feature extraction: RMS energy + zero-crossing rate from 80 ms audio frames

package/dist/OpenWakeWordProvider.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @file OpenWakeWordProvider.ts
+ * @description Wake-word detection provider using OpenWakeWord ONNX models.
+ *
+ * [OpenWakeWord](https://github.com/dscripka/openWakeWord) is an open-source
+ * wake-word / wake-phrase detection framework.  This provider loads any
+ * compatible ONNX model via `onnxruntime-node` and processes 80 ms audio
+ * frames (1280 samples at 16 kHz).
+ *
+ * Feature extraction uses a simple but effective two-element vector:
+ * - **RMS energy**: root-mean-square amplitude of the frame, normalised to
+ *   INT16 range → [0, 1].
+ * - **Zero-crossing rate**: fraction of consecutive sample pairs whose sign
+ *   differs → [0, 1].
+ *
+ * These features capture both energy and spectral texture without requiring
+ * an additional mel-filterbank preprocessing step, making the implementation
+ * self-contained and dependency-free beyond `onnxruntime-node`.
+ *
+ * @module openwakeword
+ */
+/**
+ * A detected wake-word event returned by {@link OpenWakeWordProvider.detect}.
+ */
+export interface WakeWordDetection {
+    /** Human-readable keyword label (from constructor options). */
+    keyword: string;
+    /** Detection probability in [0, 1] as reported by the ONNX model. */
+    confidence: number;
+    /** Stable provider identifier. */
+    providerId: 'openwakeword';
+}
+/**
+ * Constructor options for {@link OpenWakeWordProvider}.
+ */
+export interface OpenWakeWordProviderOptions {
+    /**
+     * Absolute path to the ONNX wake-word model file.
+     * Resolved from `OPENWAKEWORD_MODEL_PATH` env var when omitted.
+     * @defaultValue `~/.agentos/models/openwakeword/hey_mycroft.onnx`
+     */
+    modelPath?: string;
+    /**
+     * Detection probability threshold.  The model output must exceed this value
+     * for a detection to be returned.
+     * @defaultValue `0.5`
+     */
+    threshold?: number;
+    /**
+     * Human-readable keyword label included in every {@link WakeWordDetection}.
+     * @defaultValue `'hey mycroft'`
+     */
+    keyword?: string;
+}
+/**
+ * OpenWakeWord ONNX wake-word provider.
+ *
+ * Implements the `WakeWordProvider` contract expected by the AgentOS voice
+ * pipeline without taking a hard runtime dependency on the interface types.
+ */
+export declare class OpenWakeWordProvider {
+    /** Stable provider identifier used by the AgentOS extension registry. */
+    readonly id = "openwakeword";
+    private readonly _modelPath;
+    private readonly _threshold;
+    private readonly _keyword;
+    /** Lazily loaded ONNX inference session. */
+    private _session;
+    /**
+     * Create a new {@link OpenWakeWordProvider}.
+     *
+     * @param options - Optional configuration.  All fields have sensible defaults.
+     */
+    constructor(options?: OpenWakeWordProviderOptions);
+    /**
+     * Lazily create the ONNX `InferenceSession`.
+     *
+     * Dynamic import keeps the peer dep truly optional at module-load time.
+     */
+    private _getSession;
+    /**
+     * Extract a two-element feature vector from a raw PCM frame.
+     *
+     * The features are:
+     * 1. **Normalised RMS energy** — captures overall loudness.
+     * 2. **Zero-crossing rate** — captures high-frequency content / spectral texture.
+     *
+     * Both values are in [0, 1] and are concatenated into a `Float32Array` of
+     * length 2 for consumption by the ONNX model.
+     *
+     * @param frame - 16-bit signed PCM samples (Int16Array).
+     * @returns A `Float32Array` with `[rmsNorm, zcr]`.
+     */
+    private _extractFeatures;
+    /**
+     * Process a single 80 ms audio frame and detect any wake-word.
+     *
+     * The frame should contain 1280 samples of 16-bit PCM at 16 kHz.  The method
+     * extracts RMS energy and zero-crossing rate as a two-element feature vector,
+     * runs ONNX inference, and returns a detection if the output probability
+     * exceeds the configured threshold.
+     *
+     * @param frame      - 16-bit PCM audio frame as an `Int16Array` (1280 samples).
+     * @param _sampleRate - Sample rate (informational; must be 16000).
+     * @returns A {@link WakeWordDetection} when a wake-word is detected, or `null`.
+     */
+    detect(frame: Int16Array, _sampleRate: number): Promise<WakeWordDetection | null>;
+    /**
+     * No-op reset.
+     *
+     * The simple feature extraction used here is stateless.  Call this method
+     * if you want to explicitly signal a context boundary (e.g. after a false
+     * positive), but it currently has no effect.
+     */
+    reset(): void;
+    /**
+     * Release the ONNX session resources.
+     *
+     * Call this when the provider is no longer needed.
+     */
+    dispose(): Promise<void>;
+    /** Returns the resolved model path. */
+    getModelPath(): string;
+    /** Returns the configured detection threshold. */
+    getThreshold(): number;
+    /** Returns the configured keyword label. */
+    getKeyword(): string;
+}
+//# sourceMappingURL=OpenWakeWordProvider.d.ts.map

package/dist/OpenWakeWordProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenWakeWordProvider.d.ts","sourceRoot":"","sources":["../src/OpenWakeWordProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,UAAU,EAAE,cAAc,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;GAKG;AACH,qBAAa,oBAAoB;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,kBAAkB;IAE7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,4CAA4C;IAE5C,OAAO,CAAC,QAAQ,CAAoB;IAEpC;;;;OAIG;gBACS,OAAO,GAAE,2BAAgC;IAarD;;;;OAIG;YAEW,WAAW;IAQzB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,gBAAgB;IAkCxB;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IA2BvF;;;;;;OAMG;IACH,KAAK,IAAI,IAAI;IAIb;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B,uCAAuC;IACvC,YAAY,IAAI,MAAM;IAEtB,kDAAkD;IAClD,YAAY,IAAI,MAAM;IAEtB,4CAA4C;IAC5C,UAAU,IAAI,MAAM;CACrB"}

package/dist/OpenWakeWordProvider.js

@@ -0,0 +1,180 @@
+/**
+ * @file OpenWakeWordProvider.ts
+ * @description Wake-word detection provider using OpenWakeWord ONNX models.
+ *
+ * [OpenWakeWord](https://github.com/dscripka/openWakeWord) is an open-source
+ * wake-word / wake-phrase detection framework.  This provider loads any
+ * compatible ONNX model via `onnxruntime-node` and processes 80 ms audio
+ * frames (1280 samples at 16 kHz).
+ *
+ * Feature extraction uses a simple but effective two-element vector:
+ * - **RMS energy**: root-mean-square amplitude of the frame, normalised to
+ *   INT16 range → [0, 1].
+ * - **Zero-crossing rate**: fraction of consecutive sample pairs whose sign
+ *   differs → [0, 1].
+ *
+ * These features capture both energy and spectral texture without requiring
+ * an additional mel-filterbank preprocessing step, making the implementation
+ * self-contained and dependency-free beyond `onnxruntime-node`.
+ *
+ * @module openwakeword
+ */
+import os from 'os';
+import path from 'path';
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+/**
+ * OpenWakeWord ONNX wake-word provider.
+ *
+ * Implements the `WakeWordProvider` contract expected by the AgentOS voice
+ * pipeline without taking a hard runtime dependency on the interface types.
+ */
+export class OpenWakeWordProvider {
+    /** Stable provider identifier used by the AgentOS extension registry. */
+    id = 'openwakeword';
+    _modelPath;
+    _threshold;
+    _keyword;
+    /** Lazily loaded ONNX inference session. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _session = null;
+    /**
+     * Create a new {@link OpenWakeWordProvider}.
+     *
+     * @param options - Optional configuration.  All fields have sensible defaults.
+     */
+    constructor(options = {}) {
+        this._modelPath =
+            options.modelPath ??
+                process.env['OPENWAKEWORD_MODEL_PATH'] ??
+                path.join(os.homedir(), '.agentos', 'models', 'openwakeword', 'hey_mycroft.onnx');
+        this._threshold = options.threshold ?? 0.5;
+        this._keyword = options.keyword ?? 'hey mycroft';
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Lazily create the ONNX `InferenceSession`.
+     *
+     * Dynamic import keeps the peer dep truly optional at module-load time.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async _getSession() {
+        if (!this._session) {
+            const ort = await import('onnxruntime-node');
+            this._session = await ort.InferenceSession.create(this._modelPath);
+        }
+        return this._session;
+    }
+    /**
+     * Extract a two-element feature vector from a raw PCM frame.
+     *
+     * The features are:
+     * 1. **Normalised RMS energy** — captures overall loudness.
+     * 2. **Zero-crossing rate** — captures high-frequency content / spectral texture.
+     *
+     * Both values are in [0, 1] and are concatenated into a `Float32Array` of
+     * length 2 for consumption by the ONNX model.
+     *
+     * @param frame - 16-bit signed PCM samples (Int16Array).
+     * @returns A `Float32Array` with `[rmsNorm, zcr]`.
+     */
+    _extractFeatures(frame) {
+        const n = frame.length;
+        if (n === 0) {
+            return new Float32Array([0, 0]);
+        }
+        // RMS energy, normalised to [0, 1] using the INT16 max (32768).
+        let sumSq = 0;
+        for (let i = 0; i < n; i++) {
+            const s = frame[i];
+            sumSq += s * s;
+        }
+        const rms = Math.sqrt(sumSq / n);
+        const rmsNorm = Math.min(rms / 32768, 1);
+        // Zero-crossing rate: count sign changes / (n - 1).
+        let crossings = 0;
+        for (let i = 1; i < n; i++) {
+            const prev = frame[i - 1];
+            const curr = frame[i];
+            if ((prev >= 0 && curr < 0) || (prev < 0 && curr >= 0)) {
+                crossings++;
+            }
+        }
+        const zcr = n > 1 ? crossings / (n - 1) : 0;
+        return new Float32Array([rmsNorm, zcr]);
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Process a single 80 ms audio frame and detect any wake-word.
+     *
+     * The frame should contain 1280 samples of 16-bit PCM at 16 kHz.  The method
+     * extracts RMS energy and zero-crossing rate as a two-element feature vector,
+     * runs ONNX inference, and returns a detection if the output probability
+     * exceeds the configured threshold.
+     *
+     * @param frame      - 16-bit PCM audio frame as an `Int16Array` (1280 samples).
+     * @param _sampleRate - Sample rate (informational; must be 16000).
+     * @returns A {@link WakeWordDetection} when a wake-word is detected, or `null`.
+     */
+    async detect(frame, _sampleRate) {
+        const ort = await import('onnxruntime-node');
+        const session = await this._getSession();
+        const features = this._extractFeatures(frame);
+        const inputTensor = new ort.Tensor('float32', features, [1, features.length]);
+        const outputs = await session.run({ input: inputTensor });
+        // The model is expected to output a single probability value.  We accept
+        // the first element of the first output tensor regardless of key name.
+        const outputValues = Object.values(outputs);
+        const firstOutput = outputValues[0];
+        const probability = firstOutput?.data != null ? Number(firstOutput.data[0] ?? 0) : 0;
+        if (probability > this._threshold) {
+            return {
+                keyword: this._keyword,
+                confidence: probability,
+                providerId: 'openwakeword',
+            };
+        }
+        return null;
+    }
+    /**
+     * No-op reset.
+     *
+     * The simple feature extraction used here is stateless.  Call this method
+     * if you want to explicitly signal a context boundary (e.g. after a false
+     * positive), but it currently has no effect.
+     */
+    reset() {
+        // Intentional no-op — feature extraction is stateless.
+    }
+    /**
+     * Release the ONNX session resources.
+     *
+     * Call this when the provider is no longer needed.
+     */
+    async dispose() {
+        if (this._session) {
+            // onnxruntime-node sessions do not expose a release/destroy API in all
+            // versions; attempt graceful release if the method exists.
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+            if (typeof this._session.release === 'function') {
+                await this._session.release();
+            }
+            this._session = null;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Accessors (for testing / diagnostics)
+    // ---------------------------------------------------------------------------
+    /** Returns the resolved model path. */
+    getModelPath() { return this._modelPath; }
+    /** Returns the configured detection threshold. */
+    getThreshold() { return this._threshold; }
+    /** Returns the configured keyword label. */
+    getKeyword() { return this._keyword; }
+}
+//# sourceMappingURL=OpenWakeWordProvider.js.map

package/dist/OpenWakeWordProvider.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the OpenWakeWord extension pack.
+ *
+ * Exports the main {@link createOpenWakeWord} factory function and the
+ * {@link createExtensionPack} bridge function that conforms to the AgentOS
+ * manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createOpenWakeWord } from '@framers/agentos-ext-openwakeword';
+ *
+ * const wakeWord = createOpenWakeWord({ modelPath: '/opt/models/hey_mycroft.onnx' });
+ * const detection = await wakeWord.detect(frame, 16000);
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-openwakeword" }] }
+ * ```
+ *
+ * @module openwakeword
+ */
+import { OpenWakeWordProvider } from './OpenWakeWordProvider.js';
+import type { OpenWakeWordProviderOptions } from './OpenWakeWordProvider.js';
+/** Subset of ExtensionDescriptor required by this pack. */
+interface ExtensionDescriptor {
+    id: string;
+    kind: string;
+    payload: unknown;
+    enableByDefault?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Subset of ExtensionPack required by this pack. */
+interface ExtensionPack {
+    id: string;
+    descriptors: ExtensionDescriptor[];
+}
+/** Subset of ExtensionPackContext required by this pack. */
+interface ExtensionPackContext {
+    getSecret?: (id: string) => string | undefined;
+    options?: Record<string, unknown>;
+}
+/**
+ * Create a standalone {@link OpenWakeWordProvider} instance.
+ *
+ * @param options - Optional constructor options.
+ * @returns Configured {@link OpenWakeWordProvider}.
+ */
+export declare function createOpenWakeWord(options?: OpenWakeWordProviderOptions): OpenWakeWordProvider;
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads optional configuration from the context `options` map and returns an
+ * {@link ExtensionPack} containing a single `wake-word-provider` descriptor
+ * backed by {@link OpenWakeWordProvider}.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export declare function createExtensionPack(context: ExtensionPackContext): ExtensionPack;
+export { OpenWakeWordProvider } from './OpenWakeWordProvider.js';
+export type { WakeWordDetection, OpenWakeWordProviderOptions } from './OpenWakeWordProvider.js';
+//# 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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAM7E,2DAA2D;AAC3D,UAAU,mBAAmB;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,qDAAqD;AACrD,UAAU,aAAa;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,mBAAmB,EAAE,CAAC;CACpC;AAED,4DAA4D;AAC5D,UAAU,oBAAoB;IAC5B,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AASD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,2BAA2B,GAAG,oBAAoB,CAE9F;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAoBhF;AAMD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,YAAY,EAAE,iBAAiB,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,73 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the OpenWakeWord extension pack.
+ *
+ * Exports the main {@link createOpenWakeWord} factory function and the
+ * {@link createExtensionPack} bridge function that conforms to the AgentOS
+ * manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createOpenWakeWord } from '@framers/agentos-ext-openwakeword';
+ *
+ * const wakeWord = createOpenWakeWord({ modelPath: '/opt/models/hey_mycroft.onnx' });
+ * const detection = await wakeWord.detect(frame, 16000);
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-openwakeword" }] }
+ * ```
+ *
+ * @module openwakeword
+ */
+import { OpenWakeWordProvider } from './OpenWakeWordProvider.js';
+/** Kind constant matching packages/agentos/src/extensions/types.ts. */
+const EXTENSION_KIND_WAKE_WORD = 'wake-word-provider';
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+/**
+ * Create a standalone {@link OpenWakeWordProvider} instance.
+ *
+ * @param options - Optional constructor options.
+ * @returns Configured {@link OpenWakeWordProvider}.
+ */
+export function createOpenWakeWord(options) {
+    return new OpenWakeWordProvider(options);
+}
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads optional configuration from the context `options` map and returns an
+ * {@link ExtensionPack} containing a single `wake-word-provider` descriptor
+ * backed by {@link OpenWakeWordProvider}.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export function createExtensionPack(context) {
+    const opts = context.options ?? {};
+    const provider = new OpenWakeWordProvider({
+        modelPath: opts['modelPath'],
+        threshold: opts['threshold'],
+        keyword: opts['keyword'],
+    });
+    return {
+        id: 'openwakeword',
+        descriptors: [
+            {
+                id: 'openwakeword',
+                kind: EXTENSION_KIND_WAKE_WORD,
+                payload: provider,
+                enableByDefault: true,
+                metadata: { providerId: 'openwakeword' },
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+export { OpenWakeWordProvider } from './OpenWakeWordProvider.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AA4BjE,uEAAuE;AACvE,MAAM,wBAAwB,GAAG,oBAAoB,CAAC;AAEtD,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAqC;IACtE,OAAO,IAAI,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA6B;IAC/D,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACnC,MAAM,QAAQ,GAAG,IAAI,oBAAoB,CAAC;QACxC,SAAS,EAAE,IAAI,CAAC,WAAW,CAAuB;QAClD,SAAS,EAAE,IAAI,CAAC,WAAW,CAAuB;QAClD,OAAO,EAAE,IAAI,CAAC,SAAS,CAAuB;KAC/C,CAAC,CAAC;IAEH,OAAO;QACL,EAAE,EAAE,cAAc;QAClB,WAAW,EAAE;YACX;gBACE,EAAE,EAAE,cAAc;gBAClB,IAAI,EAAE,wBAAwB;gBAC9B,OAAO,EAAE,QAAQ;gBACjB,eAAe,EAAE,IAAI;gBACrB,QAAQ,EAAE,EAAE,UAAU,EAAE,cAAc,EAAE;aACzC;SACF;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

package/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "@framers/agentos-ext-openwakeword",
+  "version": "0.1.0",
+  "description": "Wake-word detection via OpenWakeWord ONNX models",
+  "kind": "wake-word-provider",
+  "extensionId": "openwakeword",
+  "entryPoint": "./dist/index.js"
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@framers/agentos-ext-openwakeword",
+  "version": "0.2.0",
+  "description": "Wake-word detection via OpenWakeWord ONNX models for AgentOS voice pipeline",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "SKILL.md",
+    "manifest.json"
+  ],
+  "peerDependencies": {
+    "@framers/agentos": "^0.1.0",
+    "onnxruntime-node": "^1.17.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^1.6.0",
+    "@framers/agentos": "0.1.94"
+  },
+  "license": "MIT",
+  "author": "Frame.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/framersai/agentos-extensions.git",
+    "directory": "registry/curated/voice/openwakeword"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}

package/src/OpenWakeWordProvider.ts

@@ -0,0 +1,245 @@
+/**
+ * @file OpenWakeWordProvider.ts
+ * @description Wake-word detection provider using OpenWakeWord ONNX models.
+ *
+ * [OpenWakeWord](https://github.com/dscripka/openWakeWord) is an open-source
+ * wake-word / wake-phrase detection framework.  This provider loads any
+ * compatible ONNX model via `onnxruntime-node` and processes 80 ms audio
+ * frames (1280 samples at 16 kHz).
+ *
+ * Feature extraction uses a simple but effective two-element vector:
+ * - **RMS energy**: root-mean-square amplitude of the frame, normalised to
+ *   INT16 range → [0, 1].
+ * - **Zero-crossing rate**: fraction of consecutive sample pairs whose sign
+ *   differs → [0, 1].
+ *
+ * These features capture both energy and spectral texture without requiring
+ * an additional mel-filterbank preprocessing step, making the implementation
+ * self-contained and dependency-free beyond `onnxruntime-node`.
+ *
+ * @module openwakeword
+ */
+
+import os from 'os';
+import path from 'path';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * A detected wake-word event returned by {@link OpenWakeWordProvider.detect}.
+ */
+export interface WakeWordDetection {
+  /** Human-readable keyword label (from constructor options). */
+  keyword: string;
+  /** Detection probability in [0, 1] as reported by the ONNX model. */
+  confidence: number;
+  /** Stable provider identifier. */
+  providerId: 'openwakeword';
+}
+
+/**
+ * Constructor options for {@link OpenWakeWordProvider}.
+ */
+export interface OpenWakeWordProviderOptions {
+  /**
+   * Absolute path to the ONNX wake-word model file.
+   * Resolved from `OPENWAKEWORD_MODEL_PATH` env var when omitted.
+   * @defaultValue `~/.agentos/models/openwakeword/hey_mycroft.onnx`
+   */
+  modelPath?: string;
+  /**
+   * Detection probability threshold.  The model output must exceed this value
+   * for a detection to be returned.
+   * @defaultValue `0.5`
+   */
+  threshold?: number;
+  /**
+   * Human-readable keyword label included in every {@link WakeWordDetection}.
+   * @defaultValue `'hey mycroft'`
+   */
+  keyword?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+/**
+ * OpenWakeWord ONNX wake-word provider.
+ *
+ * Implements the `WakeWordProvider` contract expected by the AgentOS voice
+ * pipeline without taking a hard runtime dependency on the interface types.
+ */
+export class OpenWakeWordProvider {
+  /** Stable provider identifier used by the AgentOS extension registry. */
+  readonly id = 'openwakeword';
+
+  private readonly _modelPath: string;
+  private readonly _threshold: number;
+  private readonly _keyword: string;
+
+  /** Lazily loaded ONNX inference session. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private _session: any | null = null;
+
+  /**
+   * Create a new {@link OpenWakeWordProvider}.
+   *
+   * @param options - Optional configuration.  All fields have sensible defaults.
+   */
+  constructor(options: OpenWakeWordProviderOptions = {}) {
+    this._modelPath =
+      options.modelPath ??
+      process.env['OPENWAKEWORD_MODEL_PATH'] ??
+      path.join(os.homedir(), '.agentos', 'models', 'openwakeword', 'hey_mycroft.onnx');
+    this._threshold = options.threshold ?? 0.5;
+    this._keyword = options.keyword ?? 'hey mycroft';
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Lazily create the ONNX `InferenceSession`.
+   *
+   * Dynamic import keeps the peer dep truly optional at module-load time.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private async _getSession(): Promise<any> {
+    if (!this._session) {
+      const ort = await import('onnxruntime-node');
+      this._session = await ort.InferenceSession.create(this._modelPath);
+    }
+    return this._session;
+  }
+
+  /**
+   * Extract a two-element feature vector from a raw PCM frame.
+   *
+   * The features are:
+   * 1. **Normalised RMS energy** — captures overall loudness.
+   * 2. **Zero-crossing rate** — captures high-frequency content / spectral texture.
+   *
+   * Both values are in [0, 1] and are concatenated into a `Float32Array` of
+   * length 2 for consumption by the ONNX model.
+   *
+   * @param frame - 16-bit signed PCM samples (Int16Array).
+   * @returns A `Float32Array` with `[rmsNorm, zcr]`.
+   */
+  private _extractFeatures(frame: Int16Array): Float32Array {
+    const n = frame.length;
+
+    if (n === 0) {
+      return new Float32Array([0, 0]);
+    }
+
+    // RMS energy, normalised to [0, 1] using the INT16 max (32768).
+    let sumSq = 0;
+    for (let i = 0; i < n; i++) {
+      const s = frame[i]!;
+      sumSq += s * s;
+    }
+    const rms = Math.sqrt(sumSq / n);
+    const rmsNorm = Math.min(rms / 32768, 1);
+
+    // Zero-crossing rate: count sign changes / (n - 1).
+    let crossings = 0;
+    for (let i = 1; i < n; i++) {
+      const prev = frame[i - 1]!;
+      const curr = frame[i]!;
+      if ((prev >= 0 && curr < 0) || (prev < 0 && curr >= 0)) {
+        crossings++;
+      }
+    }
+    const zcr = n > 1 ? crossings / (n - 1) : 0;
+
+    return new Float32Array([rmsNorm, zcr]);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Process a single 80 ms audio frame and detect any wake-word.
+   *
+   * The frame should contain 1280 samples of 16-bit PCM at 16 kHz.  The method
+   * extracts RMS energy and zero-crossing rate as a two-element feature vector,
+   * runs ONNX inference, and returns a detection if the output probability
+   * exceeds the configured threshold.
+   *
+   * @param frame      - 16-bit PCM audio frame as an `Int16Array` (1280 samples).
+   * @param _sampleRate - Sample rate (informational; must be 16000).
+   * @returns A {@link WakeWordDetection} when a wake-word is detected, or `null`.
+   */
+  async detect(frame: Int16Array, _sampleRate: number): Promise<WakeWordDetection | null> {
+    const ort = await import('onnxruntime-node');
+    const session = await this._getSession();
+
+    const features = this._extractFeatures(frame);
+    const inputTensor = new ort.Tensor('float32', features, [1, features.length]);
+
+    const outputs = await session.run({ input: inputTensor });
+
+    // The model is expected to output a single probability value.  We accept
+    // the first element of the first output tensor regardless of key name.
+    const outputValues = Object.values(outputs) as Array<{ data: Float32Array | number[] }>;
+    const firstOutput = outputValues[0];
+    const probability: number =
+      firstOutput?.data != null ? Number(firstOutput.data[0] ?? 0) : 0;
+
+    if (probability > this._threshold) {
+      return {
+        keyword: this._keyword,
+        confidence: probability,
+        providerId: 'openwakeword',
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * No-op reset.
+   *
+   * The simple feature extraction used here is stateless.  Call this method
+   * if you want to explicitly signal a context boundary (e.g. after a false
+   * positive), but it currently has no effect.
+   */
+  reset(): void {
+    // Intentional no-op — feature extraction is stateless.
+  }
+
+  /**
+   * Release the ONNX session resources.
+   *
+   * Call this when the provider is no longer needed.
+   */
+  async dispose(): Promise<void> {
+    if (this._session) {
+      // onnxruntime-node sessions do not expose a release/destroy API in all
+      // versions; attempt graceful release if the method exists.
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      if (typeof this._session.release === 'function') {
+        await (this._session as { release(): Promise<void> }).release();
+      }
+      this._session = null;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Accessors (for testing / diagnostics)
+  // ---------------------------------------------------------------------------
+
+  /** Returns the resolved model path. */
+  getModelPath(): string { return this._modelPath; }
+
+  /** Returns the configured detection threshold. */
+  getThreshold(): number { return this._threshold; }
+
+  /** Returns the configured keyword label. */
+  getKeyword(): string { return this._keyword; }
+}

package/src/index.ts

@@ -0,0 +1,107 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the OpenWakeWord extension pack.
+ *
+ * Exports the main {@link createOpenWakeWord} factory function and the
+ * {@link createExtensionPack} bridge function that conforms to the AgentOS
+ * manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createOpenWakeWord } from '@framers/agentos-ext-openwakeword';
+ *
+ * const wakeWord = createOpenWakeWord({ modelPath: '/opt/models/hey_mycroft.onnx' });
+ * const detection = await wakeWord.detect(frame, 16000);
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-openwakeword" }] }
+ * ```
+ *
+ * @module openwakeword
+ */
+
+import { OpenWakeWordProvider } from './OpenWakeWordProvider.js';
+import type { OpenWakeWordProviderOptions } from './OpenWakeWordProvider.js';
+
+// ---------------------------------------------------------------------------
+// Local interface mirrors — avoids a hard runtime dep on @framers/agentos
+// ---------------------------------------------------------------------------
+
+/** Subset of ExtensionDescriptor required by this pack. */
+interface ExtensionDescriptor {
+  id: string;
+  kind: string;
+  payload: unknown;
+  enableByDefault?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+/** Subset of ExtensionPack required by this pack. */
+interface ExtensionPack {
+  id: string;
+  descriptors: ExtensionDescriptor[];
+}
+
+/** Subset of ExtensionPackContext required by this pack. */
+interface ExtensionPackContext {
+  getSecret?: (id: string) => string | undefined;
+  options?: Record<string, unknown>;
+}
+
+/** Kind constant matching packages/agentos/src/extensions/types.ts. */
+const EXTENSION_KIND_WAKE_WORD = 'wake-word-provider';
+
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a standalone {@link OpenWakeWordProvider} instance.
+ *
+ * @param options - Optional constructor options.
+ * @returns Configured {@link OpenWakeWordProvider}.
+ */
+export function createOpenWakeWord(options?: OpenWakeWordProviderOptions): OpenWakeWordProvider {
+  return new OpenWakeWordProvider(options);
+}
+
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads optional configuration from the context `options` map and returns an
+ * {@link ExtensionPack} containing a single `wake-word-provider` descriptor
+ * backed by {@link OpenWakeWordProvider}.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export function createExtensionPack(context: ExtensionPackContext): ExtensionPack {
+  const opts = context.options ?? {};
+  const provider = new OpenWakeWordProvider({
+    modelPath: opts['modelPath'] as string | undefined,
+    threshold: opts['threshold'] as number | undefined,
+    keyword: opts['keyword'] as string | undefined,
+  });
+
+  return {
+    id: 'openwakeword',
+    descriptors: [
+      {
+        id: 'openwakeword',
+        kind: EXTENSION_KIND_WAKE_WORD,
+        payload: provider,
+        enableByDefault: true,
+        metadata: { providerId: 'openwakeword' },
+      },
+    ],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+
+export { OpenWakeWordProvider } from './OpenWakeWordProvider.js';
+export type { WakeWordDetection, OpenWakeWordProviderOptions } from './OpenWakeWordProvider.js';