decibri 0.0.1 → 1.0.0

package/examples/websocket-stream.js

@@ -0,0 +1,44 @@
+'use strict';
+// Streams raw PCM audio to a WebSocket server.
+// Requires: npm install ws
+// Usage:    node examples/websocket-stream.js [ws://localhost:8080]
+
+const { WebSocket } = require('ws');
+// In your own project: const Decibri = require('decibri');
+const Decibri       = require('../index');
+
+const url = process.argv[2] || 'ws://localhost:8080';
+const ws  = new WebSocket(url);
+const mic = new Decibri({ sampleRate: 16000, channels: 1 });
+
+ws.on('open', () => {
+  console.log(`Connected to ${url} — streaming audio. Ctrl+C to stop.`);
+
+  mic.on('data', (chunk) => {
+    if (ws.readyState === WebSocket.OPEN) ws.send(chunk);
+  });
+
+  mic.on('error', (err) => {
+    console.error('Mic error:', err.message);
+    ws.close();
+  });
+
+  mic.on('backpressure', () => {
+    console.warn('Backpressure — consumer too slow');
+  });
+});
+
+ws.on('close', () => {
+  mic.stop();
+  console.log('WebSocket closed.');
+});
+
+ws.on('error', (err) => {
+  console.error('WebSocket error:', err.message);
+  mic.stop();
+});
+
+process.on('SIGINT', () => {
+  mic.stop();
+  ws.close();
+});

package/index.js

@@ -0,0 +1,190 @@
+'use strict';
+
+const { Readable } = require('stream');
+
+// Load the pre-built binary (falls back to compiled build/ output)
+const binding = require('node-gyp-build')(__dirname);
+
+const { Decibri: NativeDecibri } = binding;
+
+// ─── 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) ─────────────────────────────────────────────────────
+
+/**
+ * A Node.js Readable stream that emits raw PCM audio from the default
+ * microphone as Buffer chunks.
+ *
+ * Audio format:
+ *   - Encoding:    16-bit signed integer (Int16), little-endian
+ *   - Sample rate: 16000 Hz  (default — ideal for speech/wake-word)
+ *   - Channels:    1 (mono)  (default)
+ *
+ * @fires Decibri#backpressure - Emitted when the stream's internal buffer is
+ *   full and the consumer is reading too slowly. The microphone cannot be
+ *   paused, so chunks will continue to arrive; callers should drain or drop
+ *   data as appropriate.
+ *
+ * @example
+ * const mic = new Decibri();
+ * mic.on('data', (chunk) => {
+ *   // chunk is a Buffer of Int16 PCM samples
+ * });
+ * mic.on('error', (err) => console.error(err));
+ * mic.on('backpressure', () => console.warn('Consumer too slow'));
+ *
+ * // Stop after 5 seconds
+ * setTimeout(() => mic.stop(), 5000);
+ */
+class Decibri extends Readable {
+  /**
+   * @param {object} [options]
+   * @param {number} [options.sampleRate=16000]           Samples per second (1000–384000)
+   * @param {number} [options.channels=1]                 Number of input channels (1–32)
+   * @param {number} [options.framesPerBuffer=1600]       Frames per audio callback (64–65536)
+   * @param {number|string} [options.device]              Device index from Decibri.devices() or case-insensitive name substring
+   * @param {'int16'|'float32'} [options.format='int16']  Sample encoding format
+   * @param {boolean} [options.vad=false]                 Enable voice activity detection
+   * @param {number}  [options.vadThreshold=0.01]         RMS energy threshold for speech (0–1)
+   * @param {number}  [options.vadHoldoff=300]            ms of silence before 'silence' event fires
+   */
+  constructor(options = {}) {
+    const {
+      sampleRate      = 16000,
+      channels        = 1,
+      framesPerBuffer = 1600,
+      device,
+      format,
+      vad             = false,
+      vadThreshold    = 0.01,
+      vadHoldoff      = 300,
+      ...streamOptions
+    } = options;
+
+    // Resolve device name → index
+    let resolvedDevice = device;
+    if (typeof device === 'string') {
+      const lower = device.toLowerCase();
+      const matches = NativeDecibri.devices().filter(d =>
+        d.name.toLowerCase().includes(lower)
+      );
+      if (matches.length === 0) {
+        throw new TypeError(`No audio input device found matching "${device}"`);
+      }
+      if (matches.length > 1) {
+        const names = matches.map(d => `  [${d.index}] ${d.name}`).join('\n');
+        throw new TypeError(
+          `Multiple devices match "${device}":\n${names}\nUse a more specific name or pass the device index directly.`
+        );
+      }
+      resolvedDevice = matches[0].index;
+    }
+
+    super({ ...streamOptions, objectMode: false });
+
+    const nativeOpts = { sampleRate, channels, framesPerBuffer };
+    if (resolvedDevice !== undefined) nativeOpts.device = resolvedDevice;
+    if (format !== undefined) nativeOpts.format = format;
+
+    this._native       = new NativeDecibri(nativeOpts);
+    this._started      = false;
+    this._vad          = vad;
+    this._vadThreshold = vadThreshold;
+    this._vadHoldoff   = vadHoldoff;
+    this._format       = format || 'int16';
+    this._isSpeaking   = false;
+    this._silenceTimer = null;
+  }
+
+  // Called by the stream machinery when it wants data
+  _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) {
+        const rms = computeRMS(chunk, this._format);
+        if (rms >= 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 NativeDecibri.devices();
+  }
+
+  /**
+   * Version information for decibri and the bundled PortAudio.
+   * @returns {{ decibri: string, portaudio: string }}
+   */
+  static version() {
+    return NativeDecibri.version();
+  }
+}
+
+module.exports = Decibri;

package/package.json

@@ -1,11 +1,60 @@
 {
   "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": "1.0.0",
+  "description": "Cross-platform microphone audio capture for Node.js with pre-built binaries. No build tools required.",
+  "main": "index.js",
+  "types": "types/index.d.ts",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/analyticsinmotion/micstream.git"
-  }
-}
+    "url": "git+https://github.com/analyticsinmotion/decibri.git"
+  },
+  "homepage": "https://decibri.dev",
+  "keywords": [
+    "microphone",
+    "audio",
+    "capture",
+    "stream",
+    "pcm",
+    "portaudio",
+    "native",
+    "prebuilt",
+    "voice-ai",
+    "speech-to-text",
+    "wake-word",
+    "real-time-audio"
+  ],
+  "files": [
+    "index.js",
+    "types/",
+    "examples/",
+    "binding.gyp",
+    "src/",
+    "prebuilds/",
+    "deps/"
+  ],
+  "scripts": {
+    "install": "node-gyp-build || node-gyp rebuild",
+    "build": "node-gyp rebuild",
+    "test": "node test/basic.js"
+  },
+  "dependencies": {
+    "node-gyp-build": "^4.6.0"
+  },
+  "devDependencies": {
+    "node-addon-api": "^8.6.0",
+    "node-gyp": "^12.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "win32",
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}

package/src/decibri.cc

@@ -0,0 +1,390 @@
+#include <napi.h>
+#include <portaudio.h>
+#include <vector>
+#include <atomic>
+#include <cstring>
+
+#ifdef PA_USE_WASAPI
+#include <pa_win_wasapi.h>
+#endif
+
+#ifdef PA_USE_COREAUDIO
+// Declared in src/mac_permission.mm (compiled on macOS only)
+extern "C" const char* CheckMicrophonePermission();
+#endif
+
+// ─── Defaults ────────────────────────────────────────────────────────────────
+// Optimised for speech/wake-word: 16kHz mono 16-bit
+#define DEFAULT_SAMPLE_RATE    16000
+#define DEFAULT_CHANNELS       1
+// 100ms of audio per chunk at 16kHz — low enough latency, not too chatty
+#define DEFAULT_FRAMES_PER_BUFFER 1600
+// -1 means "use the system default input device"
+#define DEFAULT_DEVICE         -1
+
+// ─── Decibri class ──────────────────────────────────────────────────────────
+
+class Decibri : public Napi::ObjectWrap<Decibri> {
+public:
+
+  static Napi::Object Init(Napi::Env env, Napi::Object exports) {
+    Napi::Function func = DefineClass(env, "Decibri", {
+      InstanceMethod("start",   &Decibri::Start),
+      InstanceMethod("stop",    &Decibri::Stop),
+      InstanceMethod("isOpen",  &Decibri::IsOpen),
+      StaticMethod("devices",   &Decibri::GetDevices),
+      StaticMethod("version",   &Decibri::GetVersion),
+    });
+
+    Napi::FunctionReference* constructor = new Napi::FunctionReference();
+    *constructor = Napi::Persistent(func);
+    env.SetInstanceData(constructor);
+
+    exports.Set("Decibri", func);
+    return exports;
+  }
+
+  // ── Constructor ──────────────────────────────────────────────────────────
+
+  Decibri(const Napi::CallbackInfo& info)
+      : Napi::ObjectWrap<Decibri>(info),
+        stream_(nullptr),
+        tsfn_(),
+        running_(false),
+        sampleRate_(DEFAULT_SAMPLE_RATE),
+        channels_(DEFAULT_CHANNELS),
+        framesPerBuffer_(DEFAULT_FRAMES_PER_BUFFER),
+        device_(DEFAULT_DEVICE),
+        sampleFormat_(paInt16),
+        bytesPerSample_(2) {
+
+    Napi::Env env = info.Env();
+
+    // Parse optional config object
+    if (info.Length() > 0 && info[0].IsObject()) {
+      Napi::Object opts = info[0].As<Napi::Object>();
+
+      if (opts.Has("sampleRate") && opts.Get("sampleRate").IsNumber()) {
+        sampleRate_ = opts.Get("sampleRate").As<Napi::Number>().Int32Value();
+        if (sampleRate_ < 1000 || sampleRate_ > 384000) {
+          Napi::RangeError::New(env, "sampleRate must be between 1000 and 384000").ThrowAsJavaScriptException();
+          return;
+        }
+      }
+      if (opts.Has("channels") && opts.Get("channels").IsNumber()) {
+        channels_ = opts.Get("channels").As<Napi::Number>().Int32Value();
+        if (channels_ < 1 || channels_ > 32) {
+          Napi::RangeError::New(env, "channels must be between 1 and 32").ThrowAsJavaScriptException();
+          return;
+        }
+      }
+      if (opts.Has("framesPerBuffer") && opts.Get("framesPerBuffer").IsNumber()) {
+        framesPerBuffer_ = opts.Get("framesPerBuffer").As<Napi::Number>().Int32Value();
+        if (framesPerBuffer_ < 64 || framesPerBuffer_ > 65536) {
+          Napi::RangeError::New(env, "framesPerBuffer must be between 64 and 65536").ThrowAsJavaScriptException();
+          return;
+        }
+      }
+      if (opts.Has("device") && opts.Get("device").IsNumber()) {
+        device_ = opts.Get("device").As<Napi::Number>().Int32Value();
+      }
+      if (opts.Has("format") && opts.Get("format").IsString()) {
+        std::string fmt = opts.Get("format").As<Napi::String>().Utf8Value();
+        if (fmt == "float32") {
+          sampleFormat_   = paFloat32;
+          bytesPerSample_ = 4;
+        } else if (fmt != "int16") {
+          Napi::TypeError::New(env, "format must be 'int16' or 'float32'")
+              .ThrowAsJavaScriptException();
+          return;
+        }
+      }
+    }
+
+    PaError err = Pa_Initialize();
+    if (err != paNoError) {
+      Napi::Error::New(env, std::string("PortAudio init failed: ") + Pa_GetErrorText(err))
+          .ThrowAsJavaScriptException();
+    }
+  }
+
+  // ── Destructor ───────────────────────────────────────────────────────────
+
+  ~Decibri() {
+    if (running_.exchange(false)) {
+      if (stream_) {
+        Pa_StopStream(stream_);
+        Pa_CloseStream(stream_);
+        stream_ = nullptr;
+      }
+    }
+    if (tsfn_) {
+      tsfn_.Release();
+    }
+    Pa_Terminate();
+  }
+
+private:
+
+  // ── PortAudio callback (audio thread — keep it fast) ─────────────────────
+
+  static int AudioCallback(
+      const void*                     inputBuffer,
+      void*                           outputBuffer,
+      unsigned long                   framesPerBuffer,
+      const PaStreamCallbackTimeInfo* timeInfo,
+      PaStreamCallbackFlags           statusFlags,
+      void*                           userData) {
+
+    (void)outputBuffer;
+    (void)timeInfo;
+    (void)statusFlags;
+
+    Decibri* self = static_cast<Decibri*>(userData);
+
+    if (!self->running_ || inputBuffer == nullptr) {
+      return paContinue;
+    }
+
+    // Copy raw bytes regardless of sample format (int16 or float32).
+    // Heap-allocate; ownership passes to the JS callback lambda below.
+    size_t byteLen = framesPerBuffer
+                     * static_cast<size_t>(self->channels_)
+                     * static_cast<size_t>(self->bytesPerSample_);
+    const uint8_t* src = static_cast<const uint8_t*>(inputBuffer);
+    auto* chunk = new std::vector<uint8_t>(src, src + byteLen);
+
+    napi_status status = self->tsfn_.NonBlockingCall(
+        chunk,
+        [](Napi::Env env, Napi::Function jsCallback, std::vector<uint8_t>* data) {
+          Napi::Buffer<uint8_t> buf = Napi::Buffer<uint8_t>::Copy(
+              env, data->data(), data->size());
+          delete data;
+          jsCallback.Call({env.Null(), buf});
+        });
+
+    if (status != napi_ok) {
+      delete chunk;
+    }
+
+    return paContinue;
+  }
+
+  // ── start(callback) ──────────────────────────────────────────────────────
+
+  Napi::Value Start(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+
+    if (running_) {
+      Napi::Error::New(env, "Decibri is already running. Call stop() first.")
+          .ThrowAsJavaScriptException();
+      return env.Undefined();
+    }
+    if (info.Length() < 1 || !info[0].IsFunction()) {
+      Napi::TypeError::New(env, "start(callback): callback function required")
+          .ThrowAsJavaScriptException();
+      return env.Undefined();
+    }
+
+    Napi::Function callback = info[0].As<Napi::Function>();
+
+    tsfn_ = Napi::ThreadSafeFunction::New(
+        env,
+        callback,
+        "DecibriCallback",
+        0,    // unlimited queue depth
+        1     // single producer (audio thread)
+    );
+
+    // Resolve the device index — use the caller-specified device if set,
+    // otherwise fall back to the system default input device.
+    PaDeviceIndex deviceIndex;
+    if (device_ >= 0) {
+      deviceIndex = static_cast<PaDeviceIndex>(device_);
+      if (deviceIndex >= Pa_GetDeviceCount()) {
+        tsfn_.Release();
+        Napi::RangeError::New(env,
+            "device index out of range — call Decibri.devices() to list available devices")
+            .ThrowAsJavaScriptException();
+        return env.Undefined();
+      }
+    } else {
+      deviceIndex = Pa_GetDefaultInputDevice();
+      if (deviceIndex == paNoDevice) {
+        tsfn_.Release();
+        Napi::Error::New(env, "No microphone found. Check system audio input settings.")
+            .ThrowAsJavaScriptException();
+        return env.Undefined();
+      }
+    }
+
+    const PaDeviceInfo* deviceInfo = Pa_GetDeviceInfo(deviceIndex);
+    if (deviceInfo == nullptr || deviceInfo->maxInputChannels < 1) {
+      tsfn_.Release();
+      Napi::Error::New(env, "Selected device is not a valid input device.")
+          .ThrowAsJavaScriptException();
+      return env.Undefined();
+    }
+
+    PaStreamParameters inputParams;
+    inputParams.device                    = deviceIndex;
+    inputParams.channelCount              = channels_;
+    inputParams.sampleFormat              = sampleFormat_;
+    inputParams.suggestedLatency          = deviceInfo->defaultLowInputLatency;
+#ifdef PA_USE_WASAPI
+    // Enable Windows Audio Session API automatic format conversion so that
+    // any requested sample rate is accepted even when it differs from the
+    // device's native mix format (e.g. 16kHz from a 48kHz webcam mic).
+    PaWasapiStreamInfo wasapiInfo = {};
+    wasapiInfo.size        = sizeof(PaWasapiStreamInfo);
+    wasapiInfo.hostApiType = paWASAPI;
+    wasapiInfo.version     = 1;
+    wasapiInfo.flags       = paWinWasapiAutoConvert;
+    inputParams.hostApiSpecificStreamInfo = &wasapiInfo;
+#else
+    inputParams.hostApiSpecificStreamInfo = nullptr;
+#endif
+
+#ifdef PA_USE_COREAUDIO
+    {
+      const char* permError = CheckMicrophonePermission();
+      if (permError != nullptr) {
+        tsfn_.Release();
+        Napi::Error::New(env, permError).ThrowAsJavaScriptException();
+        return env.Undefined();
+      }
+    }
+#endif
+
+    PaError err = Pa_OpenStream(
+        &stream_,
+        &inputParams,
+        nullptr,           // capture only, no output
+        sampleRate_,
+        framesPerBuffer_,
+        paClipOff,
+        AudioCallback,
+        this);
+
+    if (err != paNoError) {
+      stream_ = nullptr;
+      tsfn_.Release();
+      Napi::Error::New(env, std::string("Failed to open audio stream: ") + Pa_GetErrorText(err))
+          .ThrowAsJavaScriptException();
+      return env.Undefined();
+    }
+
+    err = Pa_StartStream(stream_);
+    if (err != paNoError) {
+      Pa_CloseStream(stream_);
+      stream_ = nullptr;
+      tsfn_.Release();
+      Napi::Error::New(env, std::string("Failed to start audio stream: ") + Pa_GetErrorText(err))
+          .ThrowAsJavaScriptException();
+      return env.Undefined();
+    }
+
+    running_ = true;
+    return env.Undefined();
+  }
+
+  // ── stop() ───────────────────────────────────────────────────────────────
+
+  Napi::Value Stop(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+
+    if (!running_.exchange(false)) {
+      return env.Undefined();   // already stopped — no-op
+    }
+
+    if (stream_) {
+      Pa_StopStream(stream_);
+      Pa_CloseStream(stream_);
+      stream_ = nullptr;
+    }
+
+    if (tsfn_) {
+      tsfn_.Release();
+      tsfn_ = Napi::ThreadSafeFunction();
+    }
+
+    return env.Undefined();
+  }
+
+  // ── isOpen() ─────────────────────────────────────────────────────────────
+
+  Napi::Value IsOpen(const Napi::CallbackInfo& info) {
+    return Napi::Boolean::New(info.Env(), running_.load());
+  }
+
+  // ── Decibri.devices() — static ───────────────────────────────────────────
+  //
+  // PortAudio v19 reference-counts Pa_Initialize / Pa_Terminate calls, so
+  // it is safe to call them here even when a Decibri instance is actively
+  // capturing. The instance's init increments the ref count to 1; this call
+  // bumps it to 2 then back to 1 at the end — the live stream is unaffected.
+
+  static Napi::Value GetDevices(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+
+    PaError err = Pa_Initialize();
+    if (err != paNoError) {
+      Napi::Error::New(env, std::string("PortAudio init failed: ") + Pa_GetErrorText(err))
+          .ThrowAsJavaScriptException();
+      return env.Null();
+    }
+
+    int numDevices = Pa_GetDeviceCount();
+    PaDeviceIndex defaultInput = Pa_GetDefaultInputDevice();
+    Napi::Array devices = Napi::Array::New(env);
+    uint32_t idx = 0;
+
+    for (int i = 0; i < numDevices; i++) {
+      const PaDeviceInfo* di = Pa_GetDeviceInfo(i);
+      if (di == nullptr || di->maxInputChannels < 1) continue;
+
+      Napi::Object device = Napi::Object::New(env);
+      device.Set("index",             Napi::Number::New(env, i));
+      device.Set("name",              Napi::String::New(env, di->name));
+      device.Set("maxInputChannels",  Napi::Number::New(env, di->maxInputChannels));
+      device.Set("defaultSampleRate", Napi::Number::New(env, di->defaultSampleRate));
+      device.Set("isDefault",         Napi::Boolean::New(env, i == defaultInput));
+      devices.Set(idx++, device);
+    }
+
+    Pa_Terminate();
+    return devices;
+  }
+
+  // ── Decibri.version() — static ───────────────────────────────────────────
+
+  static Napi::Value GetVersion(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    Napi::Object v = Napi::Object::New(env);
+    const PaVersionInfo* vi = Pa_GetVersionInfo();
+    v.Set("portaudio", Napi::String::New(env, vi ? vi->versionText : Pa_GetVersionText()));
+    v.Set("decibri",   Napi::String::New(env, DECIBRI_VERSION));
+    return v;
+  }
+
+  // ── Members ──────────────────────────────────────────────────────────────
+
+  PaStream*                stream_;
+  Napi::ThreadSafeFunction tsfn_;
+  std::atomic<bool>        running_;
+  int                      sampleRate_;
+  int                      channels_;
+  int                      framesPerBuffer_;
+  int                      device_;
+  PaSampleFormat           sampleFormat_;
+  int                      bytesPerSample_;
+};
+
+// ─── Module entry point ──────────────────────────────────────────────────────
+
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+  Decibri::Init(env, exports);
+  return exports;
+}
+
+NODE_API_MODULE(decibri, Init)