decibri 0.0.1 → 3.0.0-rc.1

package/package.json

@@ -1,11 +1,85 @@
 {
   "name": "decibri",
-  "version": "0.0.1",
-  "description": "Cross-platform audio capture for Node.js. Placeholder - full release coming soon.",
-  "keywords": ["audio", "microphone", "capture", "portaudio", "stream", "pcm"],
+  "version": "3.0.0-rc.1",
+  "description": "Cross-platform audio capture, output, and processing for Node.js and browsers",
+  "main": "src/decibri.js",
+  "types": "src/decibri.d.ts",
+  "browser": "./src/browser/index.js",
+  "exports": {
+    ".": {
+      "node": {
+        "types": "./src/decibri.d.ts",
+        "require": "./src/decibri.js",
+        "import": "./src/decibri.js"
+      },
+      "browser": {
+        "types": "./src/browser/index.d.ts",
+        "default": "./src/browser/index.js"
+      },
+      "default": "./src/decibri.js"
+    }
+  },
   "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "win32",
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "keywords": [
+    "audio",
+    "microphone",
+    "capture",
+    "sound",
+    "voice",
+    "speech",
+    "recording",
+    "pcm",
+    "stream",
+    "real-time"
+  ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/analyticsinmotion/micstream.git"
+    "url": "git+https://github.com/decibri/decibri.git"
+  },
+  "homepage": "https://decibri.com",
+  "bugs": {
+    "url": "https://github.com/decibri/decibri/issues"
+  },
+  "napi": {
+    "binaryName": "decibri",
+    "targets": [
+      "x86_64-pc-windows-msvc",
+      "aarch64-apple-darwin",
+      "x86_64-unknown-linux-gnu",
+      "aarch64-unknown-linux-gnu"
+    ]
+  },
+  "files": [
+    "src/",
+    "models/",
+    "index.js",
+    "index.d.ts"
+  ],
+  "optionalDependencies": {
+    "decibri-win32-x64-msvc": "3.0.0-rc.1",
+    "decibri-darwin-arm64": "3.0.0-rc.1",
+    "decibri-linux-x64-gnu": "3.0.0-rc.1",
+    "decibri-linux-arm64-gnu": "3.0.0-rc.1"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.0.0"
+  },
+  "scripts": {
+    "build": "napi build --platform --release -p decibri-node --manifest-path ../../bindings/node/Cargo.toml -o .",
+    "artifacts": "napi artifacts",
+    "prepublishOnly": "napi prepublish -t npm",
+    "version": "napi version"
   }
 }

package/src/browser/decibri-browser.js

@@ -0,0 +1,312 @@
+'use strict';
+
+const { Emitter } = require('./emitter.js');
+const { WORKLET_SOURCE } = require('./worklet-inline.js');
+
+const VERSION = '3.0.0-rc.1';
+
+/**
+ * Browser microphone capture.
+ *
+ * Uses getUserMedia + AudioWorklet for real-time audio capture in browsers.
+ * Emits 'data' events with Int16Array or Float32Array chunks.
+ *
+ * Ported from decibri-web decibri.ts. Logic identical, types removed.
+ *
+ * @example
+ * const { Decibri } = require('decibri'); // browser entry via conditional export
+ * const mic = new Decibri({ sampleRate: 16000 });
+ * mic.on('data', (chunk) => { // chunk is Int16Array });
+ * await mic.start();
+ * // later...
+ * mic.stop();
+ */
+class Decibri extends Emitter {
+  constructor(options = {}) {
+    super();
+
+    // ── Private state ─────────────────────────────────────────────────────
+    this._audioContext = null;
+    this._stream = null;
+    this._sourceNode = null;
+    this._workletNode = null;
+    this._started = false;
+    this._starting = null;
+    this._stopRequested = false;
+
+    // ── VAD state ─────────────────────────────────────────────────────────
+    this._vad = options.vad ?? false;
+    this._vadThreshold = options.vadThreshold ?? 0.01;
+    this._vadHoldoff = options.vadHoldoff ?? 300;
+    this._isSpeaking = false;
+    this._silenceTimer = null;
+
+    // ── Options ───────────────────────────────────────────────────────────
+    this._sampleRate = options.sampleRate ?? 16000;
+    this._channels = options.channels ?? 1;
+    this._framesPerBuffer = options.framesPerBuffer ?? 1600;
+    this._device = options.device;
+    this._format = options.format ?? 'int16';
+    this._echoCancellation = options.echoCancellation ?? true;
+    this._noiseSuppression = options.noiseSuppression ?? true;
+    this._workletUrl = options.workletUrl;
+
+    // ── Validate ──────────────────────────────────────────────────────────
+    if (this._sampleRate < 1000 || this._sampleRate > 384000) {
+      throw new TypeError(`sampleRate must be between 1000 and 384000, got ${this._sampleRate}`);
+    }
+    if (this._channels < 1 || this._channels > 32) {
+      throw new TypeError(`channels must be between 1 and 32, got ${this._channels}`);
+    }
+    if (this._framesPerBuffer < 64 || this._framesPerBuffer > 65536) {
+      throw new TypeError(`framesPerBuffer must be between 64 and 65536, got ${this._framesPerBuffer}`);
+    }
+    if (this._format !== 'int16' && this._format !== 'float32') {
+      throw new TypeError("format must be 'int16' or 'float32'");
+    }
+    if (this._vadThreshold < 0 || this._vadThreshold > 1) {
+      throw new TypeError(`vadThreshold must be between 0 and 1, got ${this._vadThreshold}`);
+    }
+    if (this._vadHoldoff < 0) {
+      throw new TypeError(`vadHoldoff must be >= 0, got ${this._vadHoldoff}`);
+    }
+  }
+
+  // ── Public API ──────────────────────────────────────────────────────────
+
+  /**
+   * Start microphone capture.
+   * Requests microphone permission and sets up the audio pipeline.
+   * Must be called from a user gesture context in Safari.
+   * No-op if already started. Returns the existing promise if a start
+   * is already in progress.
+   */
+  start() {
+    if (this._started) return Promise.resolve();
+    if (this._starting) return this._starting;
+
+    this._starting = this._doStart().finally(() => {
+      this._starting = null;
+    });
+
+    return this._starting;
+  }
+
+  /**
+   * Stop microphone capture and release all resources.
+   * Safe to call multiple times or before start().
+   * After stop(), calling start() again creates a fresh session.
+   */
+  stop() {
+    if (!this._started) {
+      if (this._starting) {
+        this._stopRequested = true;
+      }
+      return;
+    }
+    this._started = false;
+
+    // Stop media tracks
+    if (this._stream) {
+      this._stream.getTracks().forEach(t => t.stop());
+    }
+
+    // Disconnect audio nodes
+    if (this._sourceNode) this._sourceNode.disconnect();
+    if (this._workletNode) {
+      this._workletNode.disconnect();
+      this._workletNode.port.close();
+    }
+
+    // Close audio context
+    if (this._audioContext) this._audioContext.close();
+
+    // Clear VAD
+    if (this._silenceTimer !== null) {
+      clearTimeout(this._silenceTimer);
+      this._silenceTimer = null;
+    }
+    this._isSpeaking = false;
+
+    // Release references
+    this._audioContext = null;
+    this._stream = null;
+    this._sourceNode = null;
+    this._workletNode = null;
+
+    this.emit('end');
+    this.emit('close');
+  }
+
+  /** Whether the microphone is currently capturing. */
+  get isOpen() {
+    return this._started;
+  }
+
+  /**
+   * List available audio input devices.
+   * Device labels may be empty until microphone permission is granted.
+   */
+  static async devices() {
+    const all = await navigator.mediaDevices.enumerateDevices();
+    return all
+      .filter(d => d.kind === 'audioinput')
+      .map(d => ({
+        deviceId: d.deviceId,
+        label: d.label,
+        groupId: d.groupId,
+      }));
+  }
+
+  /** Version information. */
+  static version() {
+    return { decibri: VERSION };
+  }
+
+  // ── Private ─────────────────────────────────────────────────────────────
+
+  async _doStart() {
+    // 1. Create AudioContext at native sample rate
+    this._audioContext = new AudioContext();
+    const nativeSampleRate = this._audioContext.sampleRate;
+
+    // Safari fix: resume suspended AudioContext
+    await this._audioContext.resume();
+
+    // 2. Request microphone access
+    const audioConstraints = {
+      channelCount: this._channels,
+      echoCancellation: this._echoCancellation,
+      noiseSuppression: this._noiseSuppression,
+    };
+    if (this._device) {
+      audioConstraints.deviceId = { exact: this._device };
+    }
+
+    try {
+      this._stream = await navigator.mediaDevices.getUserMedia({ audio: audioConstraints });
+    } catch (err) {
+      await this._audioContext.close();
+      this._audioContext = null;
+      const error = this._mapError(err);
+      this.emit('error', error);
+      throw error;
+    }
+
+    // 3. Load AudioWorklet processor
+    let blobUrl = null;
+    const workletUrl = this._workletUrl ?? (blobUrl = this._createBlobUrl());
+
+    try {
+      await this._audioContext.audioWorklet.addModule(workletUrl);
+    } catch (err) {
+      if (blobUrl) URL.revokeObjectURL(blobUrl);
+      this._stream.getTracks().forEach(t => t.stop());
+      this._stream = null;
+      await this._audioContext.close();
+      this._audioContext = null;
+      const error = new Error('Failed to load audio worklet: ' + (err instanceof Error ? err.message : String(err)));
+      this.emit('error', error);
+      throw error;
+    }
+
+    if (blobUrl) URL.revokeObjectURL(blobUrl);
+
+    // 4. Build audio graph
+    this._sourceNode = this._audioContext.createMediaStreamSource(this._stream);
+    this._workletNode = new AudioWorkletNode(this._audioContext, 'decibri-processor', {
+      processorOptions: {
+        framesPerBuffer: this._framesPerBuffer,
+        format: this._format,
+        nativeSampleRate,
+        targetSampleRate: this._sampleRate,
+      },
+    });
+
+    // 5. Wire up data from worklet
+    this._workletNode.port.onmessage = (event) => {
+      const buffer = event.data;
+      const chunk = this._format === 'int16'
+        ? new Int16Array(buffer)
+        : new Float32Array(buffer);
+
+      this.emit('data', chunk);
+
+      if (this._vad) {
+        this._processVad(chunk);
+      }
+    };
+
+    // 6. Connect (source → worklet, NOT to destination)
+    this._sourceNode.connect(this._workletNode);
+
+    this._started = true;
+
+    // If stop() was called while start() was in-flight, tear down now
+    if (this._stopRequested) {
+      this._stopRequested = false;
+      this.stop();
+    }
+  }
+
+  _createBlobUrl() {
+    const blob = new Blob([WORKLET_SOURCE], { type: 'application/javascript' });
+    return URL.createObjectURL(blob);
+  }
+
+  _mapError(err) {
+    if (err instanceof DOMException) {
+      switch (err.name) {
+        case 'NotAllowedError':
+          return new Error('Microphone permission denied');
+        case 'NotFoundError':
+          return new Error('No microphone found');
+        default:
+          return new Error('Microphone access failed: ' + err.message);
+      }
+    }
+    return err instanceof Error ? err : new Error(String(err));
+  }
+
+  // ── VAD ─────────────────────────────────────────────────────────────────
+
+  _processVad(chunk) {
+    const rms = this._computeRms(chunk);
+
+    if (rms >= this._vadThreshold) {
+      if (this._silenceTimer !== null) {
+        clearTimeout(this._silenceTimer);
+        this._silenceTimer = null;
+      }
+      if (!this._isSpeaking) {
+        this._isSpeaking = true;
+        this.emit('speech');
+      }
+    } else if (this._isSpeaking && this._silenceTimer === null) {
+      this._silenceTimer = setTimeout(() => {
+        this._isSpeaking = false;
+        this._silenceTimer = null;
+        this.emit('silence');
+      }, this._vadHoldoff);
+    }
+  }
+
+  _computeRms(chunk) {
+    let sum = 0;
+    const n = chunk.length;
+    if (n === 0) return 0;
+
+    if (chunk instanceof Float32Array) {
+      for (let i = 0; i < n; i++) sum += chunk[i] * chunk[i];
+    } else {
+      for (let i = 0; i < n; i++) {
+        const s = chunk[i] / 32768;
+        sum += s * s;
+      }
+    }
+
+    return Math.sqrt(sum / n);
+  }
+}
+
+module.exports = { Decibri };

package/src/browser/emitter.js

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * Minimal event emitter for browsers.
+ *
+ * Provides .on() / .off() / .once() / .emit() with the same API pattern
+ * as Node.js EventEmitter. Used instead of browser-native EventTarget to
+ * preserve API parity with the Node.js decibri (.on('data', cb) pattern).
+ *
+ * Ported from decibri-web emitter.ts. Logic identical, types removed.
+ */
+class Emitter {
+  constructor() {
+    this._listeners = new Map();
+  }
+
+  on(event, fn) {
+    let set = this._listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this._listeners.set(event, set);
+    }
+    set.add(fn);
+    return this;
+  }
+
+  off(event, fn) {
+    const set = this._listeners.get(event);
+    if (!set) return this;
+    if (set.delete(fn)) return this;
+    for (const listener of set) {
+      if (listener._original === fn) {
+        set.delete(listener);
+        return this;
+      }
+    }
+    return this;
+  }
+
+  once(event, fn) {
+    const wrapper = (...args) => {
+      this.off(event, wrapper);
+      fn(...args);
+    };
+    wrapper._original = fn;
+    return this.on(event, wrapper);
+  }
+
+  emit(event, ...args) {
+    const set = this._listeners.get(event);
+    if (!set || set.size === 0) return false;
+    for (const fn of set) fn(...args);
+    return true;
+  }
+
+  removeAllListeners(event) {
+    if (event !== undefined) {
+      this._listeners.delete(event);
+    } else {
+      this._listeners.clear();
+    }
+    return this;
+  }
+}
+
+module.exports = { Emitter };

package/src/browser/index.d.ts

@@ -0,0 +1,155 @@
+/** Information about an available audio input device (browser). */
+export interface DeviceInfo {
+  /** Opaque device identifier (pass to constructor as `device`). */
+  deviceId: string;
+  /** Human-readable device name. May be empty until permission is granted. */
+  label: string;
+  /** Group identifier. Devices sharing the same physical device. */
+  groupId: string;
+}
+
+/** Version information. */
+export interface VersionInfo {
+  /** decibri package version (e.g. `"3.0.0"`). */
+  decibri: string;
+}
+
+/** Constructor options for the browser `Decibri` class. */
+export interface DecibriOptions {
+  /**
+   * Target sample rate in Hz. Browser captures at native rate and resamples.
+   * @default 16000
+   * @range 1000–384000
+   */
+  sampleRate?: number;
+
+  /**
+   * Number of input channels.
+   * @default 1
+   * @range 1–32
+   */
+  channels?: number;
+
+  /**
+   * Frames per audio chunk. Controls chunk size and delivery interval.
+   * @default 1600
+   * @range 64–65536
+   */
+  framesPerBuffer?: number;
+
+  /**
+   * Audio input device. Pass a deviceId string from `Decibri.devices()`.
+   * Omit to use the system default input device.
+   */
+  device?: string;
+
+  /**
+   * Sample encoding format.
+   * - `'int16'`: Int16Array of PCM samples
+   * - `'float32'`: Float32Array of samples in [-1, 1]
+   * @default 'int16'
+   */
+  format?: 'int16' | 'float32';
+
+  /**
+   * Enable energy-based voice activity detection.
+   * @default false
+   */
+  vad?: boolean;
+
+  /**
+   * RMS energy threshold for speech detection (VAD mode only).
+   * @default 0.01
+   * @range 0–1
+   */
+  vadThreshold?: number;
+
+  /**
+   * Milliseconds of sub-threshold audio before emitting `'silence'`.
+   * @default 300
+   */
+  vadHoldoff?: number;
+
+  /**
+   * Enable browser echo cancellation.
+   * @default true
+   */
+  echoCancellation?: boolean;
+
+  /**
+   * Enable browser noise suppression.
+   * @default true
+   */
+  noiseSuppression?: boolean;
+
+  /**
+   * Custom URL for the AudioWorklet processor script.
+   * Use this for strict CSP environments that block blob URLs.
+   * Omit to use the default inline blob URL.
+   */
+  workletUrl?: string;
+}
+
+/**
+ * Browser microphone capture via getUserMedia + AudioWorklet.
+ *
+ * @example
+ * ```js
+ * import { Decibri } from 'decibri'; // browser entry via conditional export
+ *
+ * const mic = new Decibri({ sampleRate: 16000 });
+ * mic.on('data', (chunk) => {
+ *   // chunk is an Int16Array of PCM samples
+ * });
+ * await mic.start(); // call from a user gesture in Safari
+ * mic.stop();
+ * ```
+ */
+export declare class Decibri {
+  constructor(options?: DecibriOptions);
+
+  /**
+   * Start microphone capture.
+   * Requests permission and sets up the audio pipeline.
+   * Must be called from a user gesture context in Safari.
+   */
+  start(): Promise<void>;
+
+  /** Stop capture and release all resources. Safe to call multiple times. */
+  stop(): void;
+
+  /** Whether the microphone is currently capturing. */
+  readonly isOpen: boolean;
+
+  /**
+   * List available audio input devices.
+   * Labels may be empty until microphone permission is granted.
+   */
+  static devices(): Promise<DeviceInfo[]>;
+
+  /** Version information. */
+  static version(): VersionInfo;
+
+  // ── Event methods ──────────────────────────────────────────────────────
+
+  on(event: 'data', listener: (chunk: Int16Array | Float32Array) => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: 'end', listener: () => void): this;
+  on(event: 'close', listener: () => void): this;
+  on(event: 'speech', listener: () => void): this;
+  on(event: 'silence', listener: () => void): this;
+  on(event: string, listener: (...args: any[]) => void): this;
+
+  off(event: string, listener: (...args: any[]) => void): this;
+
+  once(event: 'data', listener: (chunk: Int16Array | Float32Array) => void): this;
+  once(event: 'error', listener: (err: Error) => void): this;
+  once(event: 'end', listener: () => void): this;
+  once(event: 'close', listener: () => void): this;
+  once(event: 'speech', listener: () => void): this;
+  once(event: 'silence', listener: () => void): this;
+  once(event: string, listener: (...args: any[]) => void): this;
+
+  emit(event: string, ...args: any[]): boolean;
+  removeAllListeners(event?: string): this;
+}

package/src/browser/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const { Decibri } = require('./decibri-browser.js');
+const { Emitter } = require('./emitter.js');
+
+module.exports = { Decibri, Emitter };

package/src/browser/worklet-inline.js

@@ -0,0 +1,14 @@
+'use strict';
+
+/**
+ * Minified AudioWorklet processor source, embedded as a string for Blob URL loading.
+ *
+ * THIS IS THE CODE THAT ACTUALLY RUNS IN THE BROWSER.
+ * The readable version is in worklet-processor.js (documentation/reference only).
+ * If worklet-processor.js logic changes, this string MUST be regenerated.
+ *
+ * Generated from decibri-web v0.1.1 build output. Logic identical to worklet-processor.js.
+ */
+const WORKLET_SOURCE = "var u=class extends AudioWorkletProcessor{constructor(r){super();let e=r.processorOptions;this.framesPerBuffer=e.framesPerBuffer,this.format=e.format,this.ratio=e.nativeSampleRate/e.targetSampleRate,this.needsResample=e.nativeSampleRate!==e.targetSampleRate,this.position=0,this.buffer=new Float32Array(this.framesPerBuffer),this.bufferIndex=0}process(r,e,s){let t=r[0]?.[0];if(!t||t.length===0)return!0;let f;this.needsResample?f=this.resample(t):f=t;let a=0;for(;a<f.length;){let i=this.framesPerBuffer-this.bufferIndex,o=f.length-a,n=Math.min(i,o);this.buffer.set(f.subarray(a,a+n),this.bufferIndex),this.bufferIndex+=n,a+=n,this.bufferIndex>=this.framesPerBuffer&&this.flush()}return!0}resample(r){let e=r.length,s=0,t=this.position;for(;t<e-1;)s++,t+=this.ratio;let f=new Float32Array(s);t=this.position;for(let a=0;a<s;a++){let i=Math.floor(t),o=t-i;f[a]=r[i]*(1-o)+r[i+1]*o,t+=this.ratio}return this.position=Math.max(0,t-e),f}flush(){let r;if(this.format===\"int16\"){let e=new Int16Array(this.framesPerBuffer);for(let s=0;s<this.framesPerBuffer;s++)e[s]=Math.max(-32768,Math.min(32767,Math.round(this.buffer[s]*32768)));r=e.buffer}else r=this.buffer.slice(0,this.framesPerBuffer).buffer;this.port.postMessage(r,[r]),this.buffer=new Float32Array(this.framesPerBuffer),this.bufferIndex=0}};registerProcessor(\"decibri-processor\",u);\n";
+
+module.exports = { WORKLET_SOURCE };

package/src/browser/worklet-processor.js

@@ -0,0 +1,110 @@
+/**
+ * AudioWorklet processor for decibri browser capture.
+ *
+ * THIS FILE IS THE READABLE SOURCE. It is NOT loaded at runtime.
+ * The minified version in worklet-inline.js is what actually runs.
+ * If you change logic here, you MUST regenerate worklet-inline.js.
+ *
+ * Runs in a dedicated audio thread. Receives Float32 samples at the
+ * browser's native sample rate, resamples to the target rate via linear
+ * interpolation, optionally converts to Int16, and posts chunks to the
+ * main thread.
+ *
+ * This file cannot import other modules (AudioWorklet restriction).
+ *
+ * Ported from decibri-web worklet-processor.ts. Logic identical, types removed.
+ */
+
+class DecibriProcessor extends AudioWorkletProcessor {
+  constructor(options) {
+    super();
+    const opts = options.processorOptions;
+    this.framesPerBuffer = opts.framesPerBuffer;
+    this.format = opts.format;
+    this.ratio = opts.nativeSampleRate / opts.targetSampleRate;
+    this.needsResample = opts.nativeSampleRate !== opts.targetSampleRate;
+    this.position = 0;
+    this.buffer = new Float32Array(this.framesPerBuffer);
+    this.bufferIndex = 0;
+  }
+
+  process(inputs, _outputs, _parameters) {
+    const input = inputs[0]?.[0];
+    if (!input || input.length === 0) return true;
+
+    let samples;
+
+    if (this.needsResample) {
+      samples = this.resample(input);
+    } else {
+      samples = input;
+    }
+
+    // Accumulate resampled frames into the buffer
+    let offset = 0;
+    while (offset < samples.length) {
+      const remaining = this.framesPerBuffer - this.bufferIndex;
+      const available = samples.length - offset;
+      const toCopy = Math.min(remaining, available);
+
+      this.buffer.set(samples.subarray(offset, offset + toCopy), this.bufferIndex);
+      this.bufferIndex += toCopy;
+      offset += toCopy;
+
+      if (this.bufferIndex >= this.framesPerBuffer) {
+        this.flush();
+      }
+    }
+
+    return true;
+  }
+
+  resample(input) {
+    const inputLength = input.length;
+
+    // Calculate how many output samples we can produce
+    let count = 0;
+    let pos = this.position;
+    while (pos < inputLength - 1) {
+      count++;
+      pos += this.ratio;
+    }
+
+    const output = new Float32Array(count);
+    pos = this.position;
+
+    for (let i = 0; i < count; i++) {
+      const idx = Math.floor(pos);
+      const frac = pos - idx;
+      output[i] = input[idx] * (1 - frac) + input[idx + 1] * frac;
+      pos += this.ratio;
+    }
+
+    // Carry fractional remainder relative to consumed input.
+    this.position = Math.max(0, pos - inputLength);
+
+    return output;
+  }
+
+  flush() {
+    let transferBuffer;
+
+    if (this.format === 'int16') {
+      const int16 = new Int16Array(this.framesPerBuffer);
+      for (let i = 0; i < this.framesPerBuffer; i++) {
+        int16[i] = Math.max(-32768, Math.min(32767, Math.round(this.buffer[i] * 32768)));
+      }
+      transferBuffer = int16.buffer;
+    } else {
+      transferBuffer = this.buffer.slice(0, this.framesPerBuffer).buffer;
+    }
+
+    this.port.postMessage(transferBuffer, [transferBuffer]);
+
+    // Reset accumulation buffer
+    this.buffer = new Float32Array(this.framesPerBuffer);
+    this.bufferIndex = 0;
+  }
+}
+
+registerProcessor('decibri-processor', DecibriProcessor);

package/src/decibri-output.js

@@ -0,0 +1,129 @@
+'use strict';
+
+const { Writable } = require('stream');
+const { DecibriOutputBridge } = require('../index.js');
+
+// ─── DecibriOutput (Writable) ───────────────────────────────────────────────
+
+class DecibriOutput extends Writable {
+  /**
+   * @param {import('./decibri').DecibriOutputOptions} [options]
+   */
+  constructor(options = {}) {
+    super({ highWaterMark: options.highWaterMark || 16384 });
+
+    // ── Validate options ───────────────────────────────────────────────────
+
+    const sampleRate = options.sampleRate ?? 16000;
+    if (sampleRate < 1000 || sampleRate > 384000) {
+      throw new RangeError('sampleRate must be between 1000 and 384000');
+    }
+
+    const channels = options.channels ?? 1;
+    if (channels < 1 || channels > 32) {
+      throw new RangeError('channels must be between 1 and 32');
+    }
+
+    const format = options.format ?? 'int16';
+    if (format !== 'int16' && format !== 'float32') {
+      throw new TypeError("format must be 'int16' or 'float32'");
+    }
+
+    // ── Resolve device ──────────────────────────────────────────────────────
+
+    let resolvedDevice = options.device;
+    if (typeof options.device === 'string') {
+      const lower = options.device.toLowerCase();
+      const matches = DecibriOutputBridge.devices().filter(d =>
+        d.name.toLowerCase().includes(lower)
+      );
+      if (matches.length === 0) {
+        throw new TypeError(`No audio output device found matching "${options.device}"`);
+      }
+      if (matches.length > 1) {
+        const names = matches.map(d => `  [${d.index}] ${d.name}`).join('\n');
+        throw new TypeError(
+          `Multiple devices match "${options.device}":\n${names}\nUse a more specific name or pass the device index directly.`
+        );
+      }
+      resolvedDevice = matches[0].index;
+    } else if (typeof options.device === 'number') {
+      const devices = DecibriOutputBridge.devices();
+      if (options.device < 0 || options.device >= devices.length) {
+        throw new RangeError('device index out of range — call DecibriOutput.devices() to list available devices');
+      }
+      resolvedDevice = options.device;
+    }
+
+    // ── Store config ───────────────────────────────────────────────────────
+
+    this._format = format;
+    this._started = false;
+
+    // ── Create native bridge ───────────────────────────────────────────────
+
+    this._native = new DecibriOutputBridge({
+      sampleRate,
+      channels,
+      format,
+      device: resolvedDevice,
+    });
+  }
+
+  /** @internal */
+  _write(chunk, encoding, callback) {
+    if (chunk.length === 0) {
+      callback();
+      return;
+    }
+    try {
+      this._native.write(chunk);
+      callback();
+    } catch (err) {
+      callback(err);
+    }
+  }
+
+  /** @internal Called by end() after all buffered writes complete. */
+  _final(callback) {
+    try {
+      this._native.drain();
+      callback();
+    } catch (err) {
+      callback(err);
+    }
+  }
+
+  /**
+   * Immediate stop. Discards remaining buffered audio.
+   */
+  stop() {
+    this._native.stop();
+  }
+
+  /**
+   * Whether audio is currently being output.
+   * @returns {boolean}
+   */
+  get isPlaying() {
+    return this._native.isPlaying;
+  }
+
+  /**
+   * List all available output devices on the system.
+   * @returns {Array<{index: number, name: string, maxOutputChannels: number, defaultSampleRate: number, isDefault: boolean}>}
+   */
+  static devices() {
+    return DecibriOutputBridge.devices();
+  }
+
+  /**
+   * Version information for decibri and the audio runtime.
+   * @returns {{ decibri: string, portaudio: string }}
+   */
+  static version() {
+    return DecibriOutputBridge.version();
+  }
+}
+
+module.exports = DecibriOutput;

package/src/decibri.d.ts

@@ -0,0 +1,237 @@
+import { Readable, ReadableOptions, Writable, WritableOptions } from 'stream';
+
+/** Information about an available audio input device. */
+export interface DeviceInfo {
+  /** Device index (pass to constructor as `device`). */
+  index: number;
+  /** Human-readable device name from the OS. */
+  name: string;
+  /** Maximum number of input channels the device supports. */
+  maxInputChannels: number;
+  /** Device's preferred sample rate in Hz. */
+  defaultSampleRate: number;
+  /** Whether this is the current system default input device. */
+  isDefault: boolean;
+}
+
+/** Version strings returned by `Decibri.version()`. */
+export interface VersionInfo {
+  /** decibri package version (e.g. `"3.0.0"`). */
+  decibri: string;
+  /** Audio runtime version string (e.g. `"cpal 0.17"`). */
+  portaudio: string;
+}
+
+/** Constructor options for `Decibri`. */
+export interface DecibriOptions extends ReadableOptions {
+  /**
+   * Sample rate in Hz.
+   * @default 16000
+   * @range 1000–384000
+   */
+  sampleRate?: number;
+
+  /**
+   * Number of input channels.
+   * @default 1
+   * @range 1–32
+   */
+  channels?: number;
+
+  /**
+   * Frames per audio callback buffer. Controls chunk size and delivery interval.
+   * At 16 kHz mono, 1600 frames = 100 ms chunks of 3200 bytes (int16).
+   * @default 1600
+   * @range 64–65536
+   */
+  framesPerBuffer?: number;
+
+  /**
+   * Audio input device. Pass a numeric index or a case-insensitive name
+   * substring. Omit to use the system default input device.
+   */
+  device?: number | string;
+
+  /**
+   * Sample encoding format.
+   * - `'int16'`: 16-bit signed integer, little-endian (2 bytes per sample)
+   * - `'float32'`: 32-bit IEEE 754 float, little-endian (4 bytes per sample)
+   * @default 'int16'
+   */
+  format?: 'int16' | 'float32';
+
+  /**
+   * Enable energy-based voice activity detection.
+   * When enabled, emits `'speech'` and `'silence'` events.
+   * @default false
+   */
+  vad?: boolean;
+
+  /**
+   * RMS energy threshold for speech detection (VAD mode only).
+   * @default 0.01
+   * @range 0–1
+   */
+  vadThreshold?: number;
+
+  /**
+   * Milliseconds of sub-threshold audio before emitting `'silence'` (VAD mode only).
+   * @default 300
+   */
+  vadHoldoff?: number;
+
+  /**
+   * VAD engine to use.
+   * - `'energy'`: RMS energy threshold (default, lightweight)
+   * - `'silero'`: Silero VAD v5 ML model (more accurate, ~1ms inference)
+   * @default 'energy'
+   */
+  vadMode?: 'energy' | 'silero';
+
+  /**
+   * Path to the Silero VAD ONNX model file.
+   * Only used when `vadMode` is `'silero'`.
+   * Defaults to `models/silero_vad.onnx` relative to the package.
+   */
+  modelPath?: string;
+}
+
+/**
+ * Cross-platform microphone audio capture as a Node.js Readable stream.
+ *
+ * @example
+ * ```js
+ * const Decibri = require('decibri');
+ * const mic = new Decibri({ sampleRate: 16000, channels: 1 });
+ * mic.on('data', (chunk) => {
+ *   // chunk is a Buffer of Int16 LE PCM samples
+ * });
+ * setTimeout(() => mic.stop(), 5000);
+ * ```
+ */
+declare class Decibri extends Readable {
+  constructor(options?: DecibriOptions);
+
+  /** Stop microphone capture and end the stream. Safe to call multiple times. */
+  stop(): void;
+
+  /** Whether the microphone is currently capturing audio. */
+  readonly isOpen: boolean;
+
+  /** List all available audio input devices. */
+  static devices(): DeviceInfo[];
+
+  /** Version information for decibri and the audio runtime. */
+  static version(): VersionInfo;
+
+  // ── Event overloads ──────────────────────────────────────────────────────
+
+  on(event: 'data', listener: (chunk: Buffer) => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: 'end', listener: () => void): this;
+  on(event: 'close', listener: () => void): this;
+  on(event: 'pause', listener: () => void): this;
+  on(event: 'resume', listener: () => void): this;
+  on(event: 'readable', listener: () => void): this;
+  on(event: 'backpressure', listener: () => void): this;
+  on(event: 'speech', listener: () => void): this;
+  on(event: 'silence', listener: () => void): this;
+  on(event: string | symbol, listener: (...args: any[]) => void): this;
+
+  once(event: 'data', listener: (chunk: Buffer) => void): this;
+  once(event: 'error', listener: (err: Error) => void): this;
+  once(event: 'end', listener: () => void): this;
+  once(event: 'close', listener: () => void): this;
+  once(event: 'backpressure', listener: () => void): this;
+  once(event: 'speech', listener: () => void): this;
+  once(event: 'silence', listener: () => void): this;
+  once(event: string | symbol, listener: (...args: any[]) => void): this;
+}
+
+/** Information about an available audio output device. */
+export interface OutputDeviceInfo {
+  /** Device index (pass to constructor as `device`). */
+  index: number;
+  /** Human-readable device name from the OS. */
+  name: string;
+  /** Maximum number of output channels the device supports. */
+  maxOutputChannels: number;
+  /** Device's preferred sample rate in Hz. */
+  defaultSampleRate: number;
+  /** Whether this is the current system default output device. */
+  isDefault: boolean;
+}
+
+/** Constructor options for `DecibriOutput`. */
+export interface DecibriOutputOptions extends WritableOptions {
+  /**
+   * Sample rate in Hz.
+   * @default 16000
+   * @range 1000–384000
+   */
+  sampleRate?: number;
+
+  /**
+   * Number of output channels.
+   * @default 1
+   * @range 1–32
+   */
+  channels?: number;
+
+  /**
+   * Sample encoding format of incoming data.
+   * - `'int16'`: 16-bit signed integer, little-endian (2 bytes per sample)
+   * - `'float32'`: 32-bit IEEE 754 float, little-endian (4 bytes per sample)
+   * @default 'int16'
+   */
+  format?: 'int16' | 'float32';
+
+  /**
+   * Audio output device. Pass a numeric index or a case-insensitive name
+   * substring. Omit to use the system default output device.
+   */
+  device?: number | string;
+}
+
+/**
+ * Cross-platform audio output (speaker playback) as a Node.js Writable stream.
+ *
+ * @example
+ * ```js
+ * const { DecibriOutput } = require('decibri');
+ * const speaker = new DecibriOutput({ sampleRate: 16000, channels: 1 });
+ * speaker.write(pcmBuffer);
+ * speaker.end();
+ * ```
+ */
+declare class DecibriOutput extends Writable {
+  constructor(options?: DecibriOutputOptions);
+
+  /** Immediate stop. Discards remaining buffered audio. */
+  stop(): void;
+
+  /** Whether audio is currently being output. */
+  readonly isPlaying: boolean;
+
+  /** List all available audio output devices. */
+  static devices(): OutputDeviceInfo[];
+
+  /** Version information for decibri and the audio runtime. */
+  static version(): VersionInfo;
+
+  // ── Event overloads ──────────────────────────────────────────────────────
+
+  on(event: 'drain', listener: () => void): this;
+  on(event: 'finish', listener: () => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: 'close', listener: () => void): this;
+  on(event: 'pipe', listener: (src: Readable) => void): this;
+  on(event: 'unpipe', listener: (src: Readable) => void): this;
+  on(event: string | symbol, listener: (...args: any[]) => void): this;
+}
+
+export = Decibri;
+
+declare namespace Decibri {
+  export { DecibriOutput };
+}

package/src/decibri.js

@@ -0,0 +1,221 @@
+'use strict';
+
+const { Readable } = require('stream');
+const path = require('path');
+const fs = require('fs');
+const { DecibriBridge } = require('../index.js');
+
+// ─── RMS helper ──────────────────────────────────────────────────────────────
+
+function computeRMS(chunk, format) {
+  let sum = 0, n;
+  if (format === 'float32') {
+    const samples = new Float32Array(chunk.buffer, chunk.byteOffset, chunk.length / 4);
+    n = samples.length;
+    for (let i = 0; i < n; i++) sum += samples[i] * samples[i];
+  } else {
+    const samples = new Int16Array(chunk.buffer, chunk.byteOffset, chunk.length / 2);
+    n = samples.length;
+    for (let i = 0; i < n; i++) {
+      const s = samples[i] / 32768;
+      sum += s * s;
+    }
+  }
+  return n > 0 ? Math.sqrt(sum / n) : 0;
+}
+
+// ─── Decibri (Readable) ─────────────────────────────────────────────────────
+
+class Decibri extends Readable {
+  /**
+   * @param {import('./decibri').DecibriOptions} [options]
+   */
+  constructor(options = {}) {
+    super({ highWaterMark: options.highWaterMark, objectMode: false });
+
+    // ── Validate options ───────────────────────────────────────────────────
+
+    const sampleRate = options.sampleRate ?? 16000;
+    if (sampleRate < 1000 || sampleRate > 384000) {
+      throw new RangeError('sampleRate must be between 1000 and 384000');
+    }
+
+    const channels = options.channels ?? 1;
+    if (channels < 1 || channels > 32) {
+      throw new RangeError('channels must be between 1 and 32');
+    }
+
+    const framesPerBuffer = options.framesPerBuffer ?? 1600;
+    if (framesPerBuffer < 64 || framesPerBuffer > 65536) {
+      throw new RangeError('framesPerBuffer must be between 64 and 65536');
+    }
+
+    const format = options.format ?? 'int16';
+    if (format !== 'int16' && format !== 'float32') {
+      throw new TypeError("format must be 'int16' or 'float32'");
+    }
+
+    // ── Resolve device ──────────────────────────────────────────────────────
+
+    let resolvedDevice = options.device;
+    if (typeof options.device === 'string') {
+      const lower = options.device.toLowerCase();
+      const matches = DecibriBridge.devices().filter(d =>
+        d.name.toLowerCase().includes(lower)
+      );
+      if (matches.length === 0) {
+        throw new TypeError(`No audio input device found matching "${options.device}"`);
+      }
+      if (matches.length > 1) {
+        const names = matches.map(d => `  [${d.index}] ${d.name}`).join('\n');
+        throw new TypeError(
+          `Multiple devices match "${options.device}":\n${names}\nUse a more specific name or pass the device index directly.`
+        );
+      }
+      resolvedDevice = matches[0].index;
+    } else if (typeof options.device === 'number') {
+      const devices = DecibriBridge.devices();
+      if (options.device < 0 || options.device >= devices.length) {
+        throw new RangeError('device index out of range — call Decibri.devices() to list available devices');
+      }
+      resolvedDevice = options.device;
+    }
+
+    // ── Validate VAD options ─────────────────────────────────────────────────
+
+    const vadMode = options.vadMode ?? 'energy';
+    if (vadMode !== 'energy' && vadMode !== 'silero') {
+      throw new TypeError("vadMode must be 'energy' or 'silero'");
+    }
+
+    let modelPath = undefined;
+    if (vadMode === 'silero' && options.vad) {
+      modelPath = options.modelPath || path.join(__dirname, '..', 'models', 'silero_vad.onnx');
+      if (!fs.existsSync(modelPath)) {
+        throw new Error(`Silero VAD model not found at ${modelPath}. Ensure the models/ directory is included in your installation.`);
+      }
+    }
+
+    // ── Store config ───────────────────────────────────────────────────────
+
+    this._format = format;
+    this._vad = options.vad || false;
+    this._vadMode = vadMode;
+    this._vadThreshold = options.vadThreshold ?? (vadMode === 'silero' ? 0.5 : 0.01);
+    this._vadHoldoff = options.vadHoldoff ?? 300;
+    this._isSpeaking = false;
+    this._silenceTimer = null;
+    this._started = false;
+
+    // ── Create native bridge ───────────────────────────────────────────────
+
+    this._native = new DecibriBridge({
+      sampleRate,
+      channels,
+      framesPerBuffer,
+      format,
+      device: resolvedDevice,
+      vadMode: (options.vad && vadMode === 'silero') ? 'silero' : 'energy',
+      modelPath,
+    });
+  }
+
+  /** @internal */
+  _read() {
+    if (this._started) return;
+    this._started = true;
+
+    this._native.start((err, chunk) => {
+      if (err) {
+        this._started = false;
+        this.destroy(err);
+        return;
+      }
+
+      // push returns false when the consumer is slow. We can't pause a mic,
+      // but we surface the backpressure warning so callers can react.
+      if (!this.push(chunk)) {
+        this.emit('backpressure');
+      }
+
+      if (this._vad) {
+        if (this._vadMode === 'silero') {
+          const prob = this._native.vadProbability;
+          this._processVadSilero(prob);
+        } else {
+          this._processVadEnergy(chunk);
+        }
+      }
+    });
+  }
+
+  /** @internal Energy-based VAD (RMS threshold) */
+  _processVadEnergy(chunk) {
+    const rms = computeRMS(chunk, this._format);
+    this._processVadValue(rms);
+  }
+
+  /** @internal Silero ML-based VAD (reads probability from native) */
+  _processVadSilero(probability) {
+    this._processVadValue(probability);
+  }
+
+  /** @internal Common speech/silence state machine */
+  _processVadValue(value) {
+    if (value >= this._vadThreshold) {
+      clearTimeout(this._silenceTimer);
+      this._silenceTimer = null;
+      if (!this._isSpeaking) {
+        this._isSpeaking = true;
+        this.emit('speech');
+      }
+    } else if (this._isSpeaking && !this._silenceTimer) {
+      this._silenceTimer = setTimeout(() => {
+        this._isSpeaking = false;
+        this._silenceTimer = null;
+        this.emit('silence');
+      }, this._vadHoldoff);
+    }
+  }
+
+  /**
+   * Stop microphone capture and end the stream cleanly.
+   */
+  stop() {
+    if (!this._started) return;
+    this._started = false;
+    this._native.stop();
+    clearTimeout(this._silenceTimer);
+    this._silenceTimer = null;
+    this.push(null); // signals stream end
+  }
+
+  /**
+   * Whether the microphone is currently open.
+   * @returns {boolean}
+   */
+  get isOpen() {
+    return this._native.isOpen;
+  }
+
+  /**
+   * List all available input devices on the system.
+   * @returns {Array<{index: number, name: string, maxInputChannels: number, defaultSampleRate: number, isDefault: boolean}>}
+   */
+  static devices() {
+    return DecibriBridge.devices();
+  }
+
+  /**
+   * Version information for decibri and the audio runtime.
+   * @returns {{ decibri: string, portaudio: string }}
+   */
+  static version() {
+    return DecibriBridge.version();
+  }
+}
+
+const DecibriOutput = require('./decibri-output.js');
+Decibri.DecibriOutput = DecibriOutput;
+
+module.exports = Decibri;