audio-mic 1.0.0

package/README.md

@@ -0,0 +1,109 @@
+# audio-mic
+
+Capture audio from microphone in node or browser.
+
+## Usage
+
+```js
+import mic from 'audio-mic'
+
+let read = mic({
+  sampleRate: 44100,
+  channels: 1,
+  bitDepth: 16,
+  // bufferSize: 50,       // ring buffer ms (default 50)
+  // backend: 'miniaudio', // force backend
+})
+
+read((err, pcmBuffer) => {
+  // process chunk
+})
+read(null) // stop capture
+```
+
+### Node Readable
+
+```js
+import MicReadable from 'audio-mic/stream'
+
+MicReadable({ sampleRate: 44100, channels: 1 }).pipe(dest)
+```
+
+## Backends
+
+Tried in order; first successful one wins.
+
+| Backend | How | Latency | Install |
+|---|---|---|---|
+| `miniaudio` | N-API addon wrapping [miniaudio.h](https://github.com/mackron/miniaudio) | Low | Prebuilt via `@audio/mic-*` packages |
+| `process` | Pipes from ffmpeg/sox/arecord | High | System tool must be installed |
+| `null` | Silent, maintains timing contract | — | Built-in (CI/headless fallback) |
+| `mediastream` | getUserMedia + AudioWorklet (browser) | Low | Built-in |
+
+## API
+
+### `read = mic(opts?)`
+
+Returns a source function. Options:
+
+- `sampleRate` — default `44100`
+- `channels` — default `1`
+- `bitDepth` — `8`, `16` (default), `24`, `32`
+- `bufferSize` — ring buffer in ms, default `50`
+- `backend` — force a specific backend
+
+### `read(cb)`
+
+Read PCM data. Callback fires with each captured chunk: `(err, buffer) => {}`.
+
+### `read(null)`
+
+Stop capture. Closes the audio device.
+
+### `read.close()`
+
+Immediately close the audio device.
+
+### `read.backend`
+
+Name of the active backend (`'miniaudio'`, `'process'`, `'null'`, `'mediastream'`).
+
+## Building
+
+```sh
+npm run build          # compile native addon locally
+npm test               # run tests
+```
+
+## Publishing
+
+```sh
+# JS-only change (no native code changed):
+npm version patch && git push && git push --tags
+npm publish
+
+# Native code changed — rebuild platform packages:
+npm version patch && git push && git push --tags
+gh run watch                    # wait for CI
+rm -rf artifacts
+gh run download --dir artifacts \
+  -n mic-darwin-arm64 -n mic-darwin-x64 \
+  -n mic-linux-x64 -n mic-linux-arm64 -n mic-win32-x64
+
+# (fallback) If darwin-x64 CI is unavailable, cross-compile locally:
+npx node-gyp@latest rebuild --arch=x64
+mkdir -p artifacts/mic-darwin-x64
+cp build/Release/mic.node artifacts/mic-darwin-x64/
+
+for pkg in packages/mic-*/; do
+  cp artifacts/$(basename $pkg)/mic.node $pkg/
+  (cd $pkg && npm publish)
+done
+npm publish
+```
+
+## License
+
+MIT
+
+<a href="https://github.com/krishnized/license/">ॐ</a>

package/binding.gyp

@@ -0,0 +1,38 @@
+{
+  "targets": [{
+    "target_name": "mic",
+    "sources": ["native/mic.c"],
+    "include_dirs": ["native"],
+    "cflags": ["-std=c99", "-O2"],
+    "xcode_settings": {
+      "OTHER_CFLAGS": ["-std=c99", "-O2"],
+      "MACOSX_DEPLOYMENT_TARGET": "10.13"
+    },
+    "msvs_settings": {
+      "VCCLCompilerTool": {
+        "AdditionalOptions": ["/O2"]
+      }
+    },
+    "conditions": [
+      ["OS=='mac'", {
+        "libraries": [
+          "-framework CoreAudio",
+          "-framework AudioToolbox",
+          "-framework CoreFoundation"
+        ]
+      }],
+      ["OS=='linux'", {
+        "libraries": [
+          "-lpthread",
+          "-lm",
+          "-ldl"
+        ]
+      }],
+      ["OS=='win'", {
+        "libraries": [
+          "ole32.lib"
+        ]
+      }]
+    ]
+  }]
+}

package/browser.d.ts

@@ -0,0 +1,19 @@
+export interface BrowserMicOptions {
+  sampleRate?: number
+  channels?: number
+  bitDepth?: 8 | 16 | 32
+  context?: AudioContext
+  echoCancellation?: boolean
+  noiseSuppression?: boolean
+  autoGainControl?: boolean
+}
+
+export interface ReadFn {
+  (cb: (err: Error | null, chunk?: Uint8Array | null) => void): void
+  (cb: null): void
+  end(): void
+  close(): void
+  backend: 'mediastream'
+}
+
+export default function mic(opts?: BrowserMicOptions): Promise<ReadFn>

package/browser.js

@@ -0,0 +1,132 @@
+/**
+ * @module audio-mic/browser
+ *
+ * Browser audio capture via getUserMedia + AudioWorklet.
+ * Falls back to ScriptProcessorNode if AudioWorklet unavailable.
+ *
+ * Note: unlike node, browser mic() is async because getUserMedia requires permission.
+ */
+export default async function mic(opts = {}) {
+  const channels = opts.channels || 1
+  const sampleRate = opts.sampleRate || 44100
+  const bitDepth = opts.bitDepth || 16
+
+  const constraints = {
+    audio: {
+      sampleRate: { ideal: sampleRate },
+      channelCount: { ideal: channels },
+      echoCancellation: opts.echoCancellation ?? false,
+      noiseSuppression: opts.noiseSuppression ?? false,
+      autoGainControl: opts.autoGainControl ?? false,
+    }
+  }
+
+  const stream = await navigator.mediaDevices.getUserMedia(constraints)
+
+  const ownCtx = !opts.context
+  const ctx = opts.context || new AudioContext({ sampleRate })
+  const source = ctx.createMediaStreamSource(stream)
+
+  let closed = false
+  let pending = null
+
+  // try AudioWorklet, fall back to ScriptProcessor
+  let node
+  if (ctx.audioWorklet) {
+    const workletCode = `
+      class MicProcessor extends AudioWorkletProcessor {
+        process(inputs) {
+          const input = inputs[0]
+          if (input && input.length > 0) {
+            const channels = []
+            for (let i = 0; i < input.length; i++) channels.push(input[i].slice())
+            this.port.postMessage(channels)
+          }
+          return true
+        }
+      }
+      registerProcessor('mic-processor', MicProcessor)
+    `
+    const blob = new Blob([workletCode], { type: 'application/javascript' })
+    const url = URL.createObjectURL(blob)
+    await ctx.audioWorklet.addModule(url)
+    URL.revokeObjectURL(url)
+
+    node = new AudioWorkletNode(ctx, 'mic-processor', {
+      numberOfInputs: 1,
+      numberOfOutputs: 0,
+      channelCount: channels
+    })
+    source.connect(node)
+
+    node.port.onmessage = (e) => {
+      if (closed || !pending) return
+      const cb = pending
+      pending = null
+      cb(null, float32ToPCM(e.data, bitDepth))
+    }
+  } else {
+    // ScriptProcessorNode fallback (deprecated but wider support)
+    const bufSize = 2048
+    node = ctx.createScriptProcessor(bufSize, channels, 1)
+    source.connect(node)
+    node.connect(ctx.destination) // required for processing to run
+
+    node.onaudioprocess = (e) => {
+      if (closed || !pending) return
+      const cb = pending
+      pending = null
+      const chans = []
+      for (let i = 0; i < channels; i++) chans.push(e.inputBuffer.getChannelData(i).slice())
+      cb(null, float32ToPCM(chans, bitDepth))
+    }
+  }
+
+  read.close = close
+  read.end = close
+  read.backend = 'mediastream'
+
+  return read
+
+  function read(cb) {
+    if (cb == null || closed) {
+      close()
+      return
+    }
+    // resume suspended context (autoplay policy)
+    if (ctx.state === 'suspended') ctx.resume()
+    pending = cb
+  }
+
+  function close() {
+    if (closed) return
+    closed = true
+    pending = null
+    source.disconnect()
+    stream.getTracks().forEach(t => t.stop())
+    if (ownCtx) ctx.close?.()
+  }
+
+  function float32ToPCM(channelData, bits) {
+    const ch = channelData.length
+    const len = channelData[0].length
+    const bps = bits / 8
+    const buf = new Uint8Array(len * ch * bps)
+    const view = new DataView(buf.buffer)
+
+    for (let i = 0; i < len; i++) {
+      for (let c = 0; c < ch; c++) {
+        const sample = channelData[c][i]
+        const offset = (i * ch + c) * bps
+        if (bits === 16) {
+          view.setInt16(offset, Math.max(-32768, Math.min(32767, Math.round(sample * 32767))), true)
+        } else if (bits === 32) {
+          view.setFloat32(offset, sample, true)
+        } else if (bits === 8) {
+          buf[offset] = Math.max(0, Math.min(255, Math.round((sample + 1) * 127.5)))
+        }
+      }
+    }
+    return buf
+  }
+}

package/index.d.ts

@@ -0,0 +1,17 @@
+export interface MicOptions {
+  sampleRate?: number
+  channels?: number
+  bitDepth?: 8 | 16 | 24 | 32
+  bufferSize?: number
+  backend?: 'miniaudio' | 'process' | 'null'
+}
+
+export interface ReadFn {
+  (cb: (err: Error | null, chunk?: Buffer | Uint8Array | null) => void): void
+  (cb: null): void
+  end(): void
+  close(): void
+  backend: string
+}
+
+export default function mic(opts?: MicOptions): ReadFn

package/index.js

@@ -0,0 +1,35 @@
+/**
+ * @module audio-mic
+ *
+ * Capture audio data from microphone.
+ * let read = mic({ sampleRate: 44100 })
+ * read((err, chunk) => {})
+ * read(null) // stop
+ */
+import { open } from './src/backend.js'
+
+const defaults = {
+  sampleRate: 44100,
+  channels: 1,
+  bitDepth: 16,
+  bufferSize: 50
+}
+
+export default function mic(opts) {
+  const config = { ...defaults, ...opts }
+  const { name, device } = open(config, config.backend)
+
+  read.close = () => { device.close() }
+  read.end = () => { device.close() }
+  read.backend = name
+
+  return read
+
+  function read(cb) {
+    if (cb == null) {
+      device.close()
+      return
+    }
+    device.read(cb)
+  }
+}

package/native/mic.c

@@ -0,0 +1,346 @@
+/*
+ * audio-mic native addon
+ * Minimal miniaudio N-API binding: capture device → ring buffer → JS reads
+ *
+ * Architecture:
+ * - Capture callback pushes frames into ring buffer
+ * - readSync: non-blocking memcpy from ring buffer (for polling)
+ * - readAsync: blocks on worker thread until data available, then fires callback
+ * - JS calls readAsync in a loop — callback fires with each captured chunk
+ */
+
+#define MA_NO_DECODING
+#define MA_NO_ENCODING
+#define MA_NO_RESOURCE_MANAGER
+#define MA_NO_NODE_GRAPH
+#define MA_NO_ENGINE
+#define MA_NO_GENERATION
+#define MINIAUDIO_IMPLEMENTATION
+#include "miniaudio.h"
+
+#include <node_api.h>
+#include <string.h>
+
+#define NAPI_CALL(env, call)                                          \
+  do {                                                                \
+    napi_status status = (call);                                      \
+    if (status != napi_ok) {                                          \
+      const napi_extended_error_info* error_info = NULL;              \
+      napi_get_last_error_info((env), &error_info);                   \
+      const char* msg = (error_info && error_info->error_message)     \
+        ? error_info->error_message : "Unknown N-API error";          \
+      napi_throw_error((env), NULL, msg);                             \
+      return NULL;                                                    \
+    }                                                                 \
+  } while (0)
+
+/* Mic instance */
+typedef struct {
+  ma_device device;
+  ma_pcm_rb ring_buffer;
+  ma_uint32 channels;
+  ma_uint32 sample_rate;
+  ma_format format;
+  int started;
+  volatile int closed;
+} mic_t;
+
+/* Async read work */
+typedef struct {
+  mic_t* mic;
+  void* data;
+  size_t byte_length;
+  ma_uint32 frames_read;
+  napi_async_work work;
+  napi_ref callback_ref;
+  napi_ref buffer_ref;
+} read_work_t;
+
+/* Capture callback — pushes into ring buffer */
+static void capture_callback(ma_device* device, void* output, const void* input, ma_uint32 frame_count) {
+  mic_t* mic = (mic_t*)device->pUserData;
+  ma_uint32 bpf = ma_get_bytes_per_frame(mic->format, mic->channels);
+
+  ma_uint32 total_written = 0;
+  while (total_written < frame_count) {
+    ma_uint32 to_write = frame_count - total_written;
+    void* write_buf;
+    if (ma_pcm_rb_acquire_write(&mic->ring_buffer, &to_write, &write_buf) != MA_SUCCESS || to_write == 0) break;
+    memcpy(write_buf, (const ma_uint8*)input + total_written * bpf, to_write * bpf);
+    ma_pcm_rb_commit_write(&mic->ring_buffer, to_write);
+    total_written += to_write;
+  }
+
+  (void)output;
+}
+
+/* GC destructor */
+static void mic_destructor(napi_env env, void* data, void* hint) {
+  mic_t* mic = (mic_t*)data;
+  if (!mic) return;
+  if (!mic->closed) {
+    mic->closed = 1;
+    if (mic->started) {
+      ma_device_stop(&mic->device);
+      mic->started = 0;
+    }
+    ma_device_uninit(&mic->device);
+  }
+  /* Ring buffer freed here, not in close — avoids race with async worker */
+  ma_pcm_rb_uninit(&mic->ring_buffer);
+  free(mic);
+  (void)env;
+  (void)hint;
+}
+
+/* mic_open(sampleRate, channels, bitDepth, bufferMs) → external */
+static napi_value mic_open(napi_env env, napi_callback_info info) {
+  size_t argc = 4;
+  napi_value argv[4];
+  NAPI_CALL(env, napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+  if (argc < 3) {
+    napi_throw_error(env, NULL, "mic_open requires (sampleRate, channels, bitDepth[, bufferMs])");
+    return NULL;
+  }
+
+  ma_uint32 sample_rate, channels, bit_depth, buffer_ms;
+  NAPI_CALL(env, napi_get_value_uint32(env, argv[0], &sample_rate));
+  NAPI_CALL(env, napi_get_value_uint32(env, argv[1], &channels));
+  NAPI_CALL(env, napi_get_value_uint32(env, argv[2], &bit_depth));
+
+  buffer_ms = 50;
+  if (argc > 3) NAPI_CALL(env, napi_get_value_uint32(env, argv[3], &buffer_ms));
+  if (buffer_ms < 10) buffer_ms = 10;
+  if (buffer_ms > 2000) buffer_ms = 2000;
+
+  ma_format format;
+  switch (bit_depth) {
+    case 8:  format = ma_format_u8;  break;
+    case 16: format = ma_format_s16; break;
+    case 24: format = ma_format_s24; break;
+    case 32: format = ma_format_f32; break;
+    default:
+      napi_throw_error(env, NULL, "Unsupported bitDepth (use 8, 16, 24, 32)");
+      return NULL;
+  }
+
+  mic_t* mic = (mic_t*)calloc(1, sizeof(mic_t));
+  if (!mic) {
+    napi_throw_error(env, NULL, "Failed to allocate mic");
+    return NULL;
+  }
+
+  mic->channels = channels;
+  mic->sample_rate = sample_rate;
+  mic->format = format;
+
+  /* ring buffer — power of 2 sized */
+  ma_uint32 rb_frames = (sample_rate * buffer_ms) / 1000;
+  ma_uint32 rb_pow2 = 1;
+  while (rb_pow2 < rb_frames) rb_pow2 <<= 1;
+
+  ma_result result = ma_pcm_rb_init(format, channels, rb_pow2, NULL, NULL, &mic->ring_buffer);
+  if (result != MA_SUCCESS) {
+    free(mic);
+    napi_throw_error(env, NULL, "Failed to init ring buffer");
+    return NULL;
+  }
+
+  /* capture device */
+  ma_device_config config = ma_device_config_init(ma_device_type_capture);
+  config.capture.format = format;
+  config.capture.channels = channels;
+  config.sampleRate = sample_rate;
+  config.dataCallback = capture_callback;
+  config.pUserData = mic;
+  config.performanceProfile = ma_performance_profile_low_latency;
+
+  result = ma_device_init(NULL, &config, &mic->device);
+  if (result != MA_SUCCESS) {
+    ma_pcm_rb_uninit(&mic->ring_buffer);
+    free(mic);
+    napi_throw_error(env, NULL, "Failed to init capture device");
+    return NULL;
+  }
+
+  /* start capturing immediately */
+  result = ma_device_start(&mic->device);
+  if (result != MA_SUCCESS) {
+    ma_device_uninit(&mic->device);
+    ma_pcm_rb_uninit(&mic->ring_buffer);
+    free(mic);
+    napi_throw_error(env, NULL, "Failed to start capture device");
+    return NULL;
+  }
+  mic->started = 1;
+
+  napi_value external;
+  NAPI_CALL(env, napi_create_external(env, mic, mic_destructor, NULL, &external));
+  return external;
+}
+
+/*
+ * mic_readSync(handle, buffer) → framesRead
+ * Non-blocking: reads as many frames as available right now.
+ */
+static napi_value mic_read_sync(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  NAPI_CALL(env, napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+  mic_t* mic;
+  NAPI_CALL(env, napi_get_value_external(env, argv[0], (void**)&mic));
+
+  if (mic->closed) {
+    napi_value result;
+    NAPI_CALL(env, napi_create_int32(env, 0, &result));
+    return result;
+  }
+
+  void* data;
+  size_t byte_length;
+  NAPI_CALL(env, napi_get_buffer_info(env, argv[1], &data, &byte_length));
+
+  ma_uint32 bpf = ma_get_bytes_per_frame(mic->format, mic->channels);
+  if (bpf == 0) {
+    napi_value result;
+    NAPI_CALL(env, napi_create_int32(env, 0, &result));
+    return result;
+  }
+
+  ma_uint32 max_frames = (ma_uint32)(byte_length / bpf);
+  ma_uint32 frames_read = 0;
+
+  while (frames_read < max_frames) {
+    ma_uint32 to_read = max_frames - frames_read;
+    void* read_buf;
+    ma_result res = ma_pcm_rb_acquire_read(&mic->ring_buffer, &to_read, &read_buf);
+    if (res != MA_SUCCESS || to_read == 0) break;
+    memcpy((ma_uint8*)data + frames_read * bpf, read_buf, to_read * bpf);
+    ma_pcm_rb_commit_read(&mic->ring_buffer, to_read);
+    frames_read += to_read;
+  }
+
+  napi_value result;
+  NAPI_CALL(env, napi_create_uint32(env, frames_read, &result));
+  return result;
+}
+
+/* Async read — blocks on worker thread until data available */
+static void read_execute(napi_env env, void* data) {
+  read_work_t* w = (read_work_t*)data;
+  mic_t* mic = w->mic;
+  ma_uint32 bpf = ma_get_bytes_per_frame(mic->format, mic->channels);
+  if (bpf == 0) { w->frames_read = 0; return; }
+
+  ma_uint32 max_frames = (ma_uint32)(w->byte_length / bpf);
+  ma_uint32 frames_read = 0;
+
+  /* Wait until we have data or device is closed.
+   * Read whatever is available once data arrives — don't wait to fill the whole buffer.
+   * This gives lowest latency: callback fires as soon as any data is captured. */
+  while (frames_read == 0 && !mic->closed) {
+    ma_uint32 to_read = max_frames - frames_read;
+    void* read_buf;
+    ma_result res = ma_pcm_rb_acquire_read(&mic->ring_buffer, &to_read, &read_buf);
+    if (res == MA_SUCCESS && to_read > 0) {
+      memcpy((ma_uint8*)w->data + frames_read * bpf, read_buf, to_read * bpf);
+      ma_pcm_rb_commit_read(&mic->ring_buffer, to_read);
+      frames_read += to_read;
+    } else {
+      ma_sleep(1);
+    }
+  }
+
+  w->frames_read = frames_read;
+  (void)env;
+}
+
+static void read_complete(napi_env env, napi_status status, void* data) {
+  read_work_t* w = (read_work_t*)data;
+
+  napi_value callback, global, argv[2];
+  napi_get_reference_value(env, w->callback_ref, &callback);
+  napi_get_global(env, &global);
+
+  napi_get_null(env, &argv[0]);
+  napi_create_uint32(env, w->frames_read, &argv[1]);
+  napi_call_function(env, global, callback, 2, argv, NULL);
+
+  napi_delete_reference(env, w->callback_ref);
+  napi_delete_reference(env, w->buffer_ref);
+  napi_delete_async_work(env, w->work);
+  free(w);
+  (void)status;
+}
+
+/* mic_readAsync(handle, buffer, callback) */
+static napi_value mic_read_async(napi_env env, napi_callback_info info) {
+  size_t argc = 3;
+  napi_value argv[3];
+  NAPI_CALL(env, napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+  mic_t* mic;
+  NAPI_CALL(env, napi_get_value_external(env, argv[0], (void**)&mic));
+
+  if (mic->closed) {
+    napi_throw_error(env, NULL, "Mic is closed");
+    return NULL;
+  }
+
+  void* data;
+  size_t byte_length;
+  NAPI_CALL(env, napi_get_buffer_info(env, argv[1], &data, &byte_length));
+
+  read_work_t* w = (read_work_t*)calloc(1, sizeof(read_work_t));
+  w->mic = mic;
+  w->data = data;
+  w->byte_length = byte_length;
+
+  NAPI_CALL(env, napi_create_reference(env, argv[2], 1, &w->callback_ref));
+  NAPI_CALL(env, napi_create_reference(env, argv[1], 1, &w->buffer_ref));
+
+  napi_value work_name;
+  NAPI_CALL(env, napi_create_string_utf8(env, "mic_read", NAPI_AUTO_LENGTH, &work_name));
+  NAPI_CALL(env, napi_create_async_work(env, NULL, work_name, read_execute, read_complete, w, &w->work));
+  NAPI_CALL(env, napi_queue_async_work(env, w->work));
+
+  return NULL;
+}
+
+/* mic_close(handle) */
+static napi_value mic_close(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value argv[1];
+  NAPI_CALL(env, napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+  mic_t* mic;
+  NAPI_CALL(env, napi_get_value_external(env, argv[0], (void**)&mic));
+
+  if (!mic->closed) {
+    mic->closed = 1;
+    if (mic->started) {
+      ma_device_stop(&mic->device);
+      mic->started = 0;
+    }
+    ma_device_uninit(&mic->device);
+    /* Ring buffer freed by GC destructor — worker may still be blocked */
+  }
+
+  return NULL;
+}
+
+/* Module init */
+static napi_value init(napi_env env, napi_value exports) {
+  napi_property_descriptor props[] = {
+    { "open",      NULL, mic_open,       NULL, NULL, NULL, napi_default, NULL },
+    { "readSync",  NULL, mic_read_sync,  NULL, NULL, NULL, napi_default, NULL },
+    { "readAsync", NULL, mic_read_async, NULL, NULL, NULL, napi_default, NULL },
+    { "close",     NULL, mic_close,      NULL, NULL, NULL, napi_default, NULL },
+  };
+  NAPI_CALL(env, napi_define_properties(env, exports, 4, props));
+  return exports;
+}
+
+NAPI_MODULE(NODE_GYP_MODULE_NAME, init)