decibri 1.0.0 → 3.0.0-rc.2

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;