aiden-runtime 4.0.2 → 4.1.1

package/dist/core/v4/voice/audioStream.js

@@ -0,0 +1,373 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/voice/audioStream.ts — Phase v4.1-voice-cli
+ *
+ * Streaming microphone capture with lazy-loaded backend.
+ * Two-tier fallback:
+ *
+ *   1. PRIMARY: `decibri` — Rust/cpal via napi-rs, prebuilt binaries
+ *      for Win/mac/Linux. Zero compile, zero system bin, true
+ *      streaming Readable, 16k PCM native.
+ *   2. FALLBACK: `node-record-lpcm16` — shells out to `sox`/`rec`.
+ *      Used when decibri's prebuilt binary is unavailable for the
+ *      target arch (rare).
+ *   3. UNAVAILABLE: neither installs — `startStream()` returns null
+ *      and the caller surfaces a clear "install sox or check mic
+ *      drivers" hint via `aiden voice doctor`.
+ *
+ * Lazy import is mandatory — eager loading the audio library breaks
+ * SSH-only / Docker / WSL boots where no audio device exists. We
+ * import at first use, cache the resolved backend, and never
+ * re-probe.
+ *
+ * Idle-timeout 5min auto-close mirrors `core/playwrightBridge.ts`
+ * — no use of mic for 5 minutes → release the device handle. Voice
+ * mode re-acquires on next `startStream()`.
+ *
+ * The stream emits Int16 PCM frames at 16 kHz / mono. Each frame is
+ * a Buffer the consumer can compute RMS over (cliVoice does this
+ * for VAD).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAudioBackend = resolveAudioBackend;
+exports.__resetAudioBackend = __resetAudioBackend;
+exports.computeRms = computeRms;
+exports.computePeakRms = computePeakRms;
+exports.startAudioStream = startAudioStream;
+exports.getAudioDiagnostics = getAudioDiagnostics;
+const node_events_1 = require("node:events");
+const factory_1 = require("../logger/factory");
+// ── Idle-timeout state ────────────────────────────────────────────────────
+const IDLE_MS = 5 * 60 * 1000;
+let _activeBackend = null;
+let _idleTimer = null;
+let _activeHandle = null;
+function resetIdleTimer(logger) {
+    if (_idleTimer)
+        clearTimeout(_idleTimer);
+    _idleTimer = setTimeout(() => {
+        logger.info('audio stream: idle 5min — releasing backend');
+        _activeBackend = null;
+        _idleTimer = null;
+    }, IDLE_MS);
+}
+// ── Backend probing ───────────────────────────────────────────────────────
+let _resolvedBackend = null;
+/**
+ * Probe which mic backend is usable on this system. Cached after
+ * first call. Pass `force` to re-probe (rare; only useful after the
+ * user installs a missing dep mid-session).
+ */
+async function resolveAudioBackend(logger = (0, factory_1.noopLogger)(), force = false) {
+    if (_resolvedBackend && !force)
+        return _resolvedBackend;
+    // Tier 1: decibri prebuilt
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        require.resolve('decibri');
+        _resolvedBackend = 'decibri';
+        logger.info('audio stream: backend = decibri (prebuilt)');
+        return _resolvedBackend;
+    }
+    catch { /* not installed */ }
+    // Tier 2: node-record-lpcm16 (requires sox on PATH)
+    try {
+        require.resolve('node-record-lpcm16');
+        _resolvedBackend = 'node-record-lpcm16';
+        logger.info('audio stream: backend = node-record-lpcm16 (requires sox)');
+        return _resolvedBackend;
+    }
+    catch { /* not installed */ }
+    _resolvedBackend = 'unavailable';
+    logger.warn('audio stream: no backend available — install `decibri` (npm) or `sox` + `node-record-lpcm16`');
+    return _resolvedBackend;
+}
+/** Test-only: clear the cached backend so the next call re-probes. */
+function __resetAudioBackend() {
+    _resolvedBackend = null;
+}
+// ── RMS helper ────────────────────────────────────────────────────────────
+/** Root-mean-square of a 16-bit signed PCM buffer. Returns 0 for
+ *  empty buffers. Used by the VAD in `cliVoice.ts`. */
+function computeRms(pcm) {
+    if (pcm.length < 2)
+        return 0;
+    let sum = 0;
+    let count = 0;
+    for (let i = 0; i + 1 < pcm.length; i += 2) {
+        const sample = pcm.readInt16LE(i);
+        sum += sample * sample;
+        count += 1;
+    }
+    if (count === 0)
+        return 0;
+    return Math.round(Math.sqrt(sum / count));
+}
+/** Peak amplitude (absolute value) over a 16-bit signed PCM buffer.
+ *  Peak RMS check on stop — rejects "no speech ever" recordings
+ *  whose mean RMS is dragged down by trailing silence. */
+function computePeakRms(pcm) {
+    if (pcm.length < 2)
+        return 0;
+    let peak = 0;
+    for (let i = 0; i + 1 < pcm.length; i += 2) {
+        const sample = Math.abs(pcm.readInt16LE(i));
+        if (sample > peak)
+            peak = sample;
+    }
+    return peak;
+}
+// ── Stream factory ────────────────────────────────────────────────────────
+/**
+ * Start streaming microphone PCM. Returns null when no backend is
+ * available — caller surfaces a friendly error.
+ */
+async function startAudioStream(opts = {}) {
+    const logger = (opts.logger ?? (0, factory_1.noopLogger)()).child('audio-stream');
+    const sampleRate = opts.sampleRate ?? 16000;
+    const channels = opts.channels ?? 1;
+    const backend = await resolveAudioBackend(logger);
+    if (backend === 'unavailable')
+        return null;
+    // Refuse a second concurrent stream — the audio device handle is
+    // singleton (mirrors `playwrightBridge` invariant).
+    if (_activeHandle && !_activeHandle.closed) {
+        logger.warn('audio stream: already active — refusing concurrent claim');
+        return null;
+    }
+    _activeBackend = backend;
+    resetIdleTimer(logger);
+    const handle = backend === 'decibri'
+        ? await startDecibri({ sampleRate, channels, logger })
+        : await startNodeRecord({ sampleRate, channels, logger });
+    if (!handle)
+        return null;
+    _activeHandle = handle;
+    return handle;
+}
+// ── decibri backend ───────────────────────────────────────────────────────
+async function startDecibri(args) {
+    const { logger, sampleRate, channels } = args;
+    let mod;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        mod = require('decibri');
+    }
+    catch (err) {
+        logger.warn('audio stream: decibri load failed', {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return null;
+    }
+    // The decibri public surface is `Recorder` or `Input`; the exact
+    // shape varies by minor version. We accept either via a tiny
+    // adapter so this module survives a v0.x → v1.x bump.
+    const factory = mod.Recorder
+        ?? mod.Input;
+    if (typeof factory !== 'function') {
+        logger.warn('audio stream: decibri exports unrecognised shape — falling back');
+        return null;
+    }
+    let buffers = [];
+    const events = new node_events_1.EventEmitter();
+    let closed = false;
+    let recorder = null;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        recorder = new factory({ sampleRate, channels });
+        // Decibri exposes a Readable on `.stream` or directly is one.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const stream = recorder.stream ?? recorder;
+        if (stream && typeof stream.on === 'function') {
+            stream.on('data', (pcm) => {
+                if (closed)
+                    return;
+                buffers.push(pcm);
+                const rms = computeRms(pcm);
+                events.emit('frame', { pcm, rms });
+            });
+            stream.on('error', (err) => {
+                logger.warn('audio stream: decibri stream error', { error: err.message });
+                events.emit('error', err);
+            });
+        }
+    }
+    catch (err) {
+        logger.warn('audio stream: decibri init failed', {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return null;
+    }
+    return {
+        events,
+        get closed() { return closed; },
+        async stop() {
+            if (closed)
+                return Buffer.concat(buffers);
+            closed = true;
+            try {
+                recorder?.stop?.();
+            }
+            catch { /* ignore */ }
+            try {
+                recorder?.close?.();
+            }
+            catch { /* ignore */ }
+            _activeHandle = null;
+            const out = Buffer.concat(buffers);
+            buffers = [];
+            return out;
+        },
+        cancel() {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                recorder?.stop?.();
+            }
+            catch { /* ignore */ }
+            try {
+                recorder?.close?.();
+            }
+            catch { /* ignore */ }
+            _activeHandle = null;
+            buffers = [];
+        },
+    };
+}
+// ── node-record-lpcm16 backend ────────────────────────────────────────────
+async function startNodeRecord(args) {
+    const { logger, sampleRate, channels } = args;
+    let mod;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        mod = require('node-record-lpcm16');
+    }
+    catch (err) {
+        logger.warn('audio stream: node-record-lpcm16 load failed', {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return null;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const recordFn = mod.record;
+    if (typeof recordFn !== 'function') {
+        logger.warn('audio stream: node-record-lpcm16 exports unrecognised shape');
+        return null;
+    }
+    let buffers = [];
+    const events = new node_events_1.EventEmitter();
+    let closed = false;
+    let recording = null;
+    try {
+        recording = recordFn({
+            sampleRate,
+            channels,
+            audioType: 'wav',
+            threshold: 0,
+        });
+        const stream = recording.stream?.();
+        if (stream) {
+            stream.on('data', (pcm) => {
+                if (closed)
+                    return;
+                buffers.push(pcm);
+                const rms = computeRms(pcm);
+                events.emit('frame', { pcm, rms });
+            });
+            stream.on('error', (err) => {
+                logger.warn('audio stream: node-record-lpcm16 stream error', { error: err.message });
+                events.emit('error', err);
+            });
+        }
+    }
+    catch (err) {
+        logger.warn('audio stream: node-record-lpcm16 init failed', {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return null;
+    }
+    return {
+        events,
+        get closed() { return closed; },
+        async stop() {
+            if (closed)
+                return Buffer.concat(buffers);
+            closed = true;
+            try {
+                recording?.stop?.();
+            }
+            catch { /* ignore */ }
+            _activeHandle = null;
+            const out = Buffer.concat(buffers);
+            buffers = [];
+            return out;
+        },
+        cancel() {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                recording?.stop?.();
+            }
+            catch { /* ignore */ }
+            _activeHandle = null;
+            buffers = [];
+        },
+    };
+}
+async function getAudioDiagnostics(logger = (0, factory_1.noopLogger)()) {
+    const resolved = await resolveAudioBackend(logger);
+    let soxOnPath = false;
+    try {
+        const { execSync } = await Promise.resolve().then(() => __importStar(require('node:child_process')));
+        const probe = process.platform === 'win32' ? 'where sox' : 'which sox';
+        execSync(probe, { stdio: 'ignore', timeout: 2000 });
+        soxOnPath = true;
+    }
+    catch { /* sox not on PATH */ }
+    return {
+        resolved,
+        active: !!_activeHandle && !_activeHandle.closed,
+        soxOnPath,
+    };
+}