decibri 4.0.0 → 4.2.0

package/CHANGELOG.md

@@ -11,6 +11,19 @@ For other decibri packages, see:
 
 ## [Unreleased]
 
+## [4.2.0] - 2026-05-31
+
+### Added
+
+- Browser `Speaker` for audio playback through the Web Audio API: `start()`, async `write(chunk)`, async `drain()`, `stop()`, and an `isPlaying` getter, with `int16` and `float32` input and resampling from the source rate to the output rate. Playback is started from a user gesture, as browsers require. This adds playback to the browser build alongside the existing browser `Microphone` capture. The release is browser-only and additive: the Node.js API and behavior are unchanged.
+
+## [4.1.0] - 2026-05-31
+
+### Added
+
+- Async factories `Microphone.open(options)` and `Speaker.open(options)`, each returning a `Promise` that resolves to a constructed instance. They perform the blocking open work (the Silero VAD model load for the microphone; device resolution for both) on the native thread pool instead of the event loop, so latency-sensitive callers do not stall during construction. A failed open rejects with the matching error (`RangeError` / `TypeError` for invalid options, `DeviceError` / `OrtError` / `OrtPathError` for native failures). The synchronous `new Microphone(...)` and `new Speaker(...)` constructors are unchanged; the factories are an additive, non-blocking alternative that mirrors the Python `AsyncMicrophone.open()` / `AsyncSpeaker.open()` surface.
+- Non-blocking `Speaker.writeAsync(chunk)` and `Speaker.drainAsync()` methods, each returning a `Promise`. They run the blocking parts of playback off the event loop: `writeAsync` performs the backpressure wait when the native playback queue is full, and `drainAsync` performs the wait for queued audio to finish playing. The audio stream stays on its own thread; only the thread-safe sample channel and drain state are used off the event loop. A failed write or drain rejects with the matching error class. The synchronous `write()` / `pipe()` / `end()` Writable interface is unchanged; the async methods are an additive, direct alternative (do not interleave the two paths on one instance).
+
 ## [4.0.0] - 2026-05-30
 
 ### Changed

package/MIGRATION.md

@@ -5,6 +5,37 @@ vocabulary that matches the Rust and Python packages, and tidies several option
 and return shapes. This guide lists every breaking change with before and after
 code.
 
+## New in 4.2.0 (additive, nothing to migrate)
+
+decibri 4.2.0 is a browser-only, additive release. Code written for 4.1.0 keeps
+working unchanged; there is nothing to migrate. The release adds audio playback
+to the browser build:
+
+- A browser `Speaker` that plays audio through the Web Audio API: `start()`,
+  async `write(chunk)`, async `drain()`, `stop()`, and `isPlaying`, with int16
+  and float32 input and resampling from the source rate to the output rate. It
+  is started from a user gesture, as browsers require. The browser `Microphone`
+  (capture) and the entire Node.js API are unchanged.
+
+See the browser Speaker section of the README for examples.
+
+## New in 4.1.0 (additive, nothing to migrate)
+
+decibri 4.1.0 is a non-breaking, additive release. Code written for 4.0.0 keeps
+working unchanged; there is nothing to migrate. The release adds an opt-in
+non-blocking API for event-loop-sensitive code:
+
+- `Microphone.open(options)` and `Speaker.open(options)`: async factories that
+  construct an instance without blocking the event loop and resolve to a ready
+  instance. The synchronous `new Microphone(...)` and `new Speaker(...)`
+  constructors are unchanged.
+- `speaker.writeAsync(chunk)` and `speaker.drainAsync()`: write and drain
+  without blocking the event loop. The synchronous `write()` / `pipe()` /
+  `end()` interface is unchanged.
+
+See the Non-blocking API section of the README for examples. The rest of this
+guide covers the 4.0.0 changes from 3.x.
+
 ## Named exports
 
 The package no longer has a single default export. Destructure what you need.

package/README.md

@@ -50,6 +50,19 @@ mic.on('data', (chunk) => { /* Int16Array of PCM samples */ });
 await mic.start(); // requires user gesture in Safari
 ```
 
+### Browser playback
+
+```javascript
+import { Speaker } from 'decibri'; // browser entry via conditional export
+
+const speaker = new Speaker({ sampleRate: 16000 });
+playButton.onclick = async () => {
+  await speaker.write(int16Chunk); // Int16Array of PCM samples
+  await speaker.drain();           // resolves when playback finishes
+  speaker.stop();
+};
+```
+
 ### Pipe capture to playback (echo)
 
 ```javascript
@@ -87,6 +100,7 @@ Standard `ReadableOptions` (e.g. `highWaterMark`) are also accepted.
 | Method | Description |
 | --- | --- |
 | `mic.stop()` | Stop capture and end stream. Safe to call multiple times |
+| `Microphone.open(options?)` | Construct without blocking the event loop. Returns a `Promise<Microphone>`. See [Non-blocking API](#non-blocking-api) |
 | `Microphone.devices()` | List available input devices |
 | `Microphone.version()` | Version info: `{ decibri, audioBackend, binding }` |
 
@@ -128,14 +142,47 @@ Standard `WritableOptions` (e.g. `highWaterMark`) are also accepted.
 | Method / Property | Description |
 | --- | --- |
 | `speaker.write(chunk)` | Write PCM data for playback |
+| `speaker.writeAsync(chunk)` | Write without blocking the event loop. Returns a `Promise`. See [Non-blocking API](#non-blocking-api) |
 | `speaker.end()` | Signal end. Drains remaining audio, then emits `'finish'` |
+| `speaker.drainAsync()` | Wait for queued audio to finish without blocking the event loop. Returns a `Promise` |
 | `speaker.stop()` | Immediate stop. Discards remaining audio |
 | `speaker.isPlaying` | `true` while audio is being output |
+| `Speaker.open(options?)` | Construct without blocking the event loop. Returns a `Promise<Speaker>` |
 | `Speaker.devices()` | List available output devices |
 | `Speaker.version()` | Same as `Microphone.version()` |
 
 The module-level `outputDevices()` free function is equivalent to `Speaker.devices()`.
 
+## Non-blocking API
+
+The synchronous constructors and `write` / `drain` do their work on the event loop, which is fine for most apps. For event-loop-sensitive code (servers, real-time voice pipelines), 4.1.0 adds async variants that perform the blocking work without stalling the event loop. They are additive: the synchronous API is unchanged, and you opt in only where you need it.
+
+### Non-blocking construction
+
+`Microphone.open(options?)` and `Speaker.open(options?)` are async factories that return a Promise of a ready instance. They take the same options as the constructors. For a microphone with Silero VAD, the model load that the constructor does inline runs without blocking the event loop.
+
+```javascript
+const { Microphone, Speaker } = require('decibri');
+
+const mic = await Microphone.open({ sampleRate: 16000, vad: 'silero' });
+const speaker = await Speaker.open({ sampleRate: 16000, channels: 1 });
+```
+
+The synchronous `new Microphone(...)` and `new Speaker(...)` still work unchanged. A failed open rejects the Promise with the same typed error a failed constructor throws.
+
+### Non-blocking playback
+
+`speaker.writeAsync(chunk)` resolves once the audio is queued, performing the backpressure wait (when the playback buffer is full) without blocking the event loop. `speaker.drainAsync()` resolves when all queued audio has finished playing, again without blocking.
+
+```javascript
+const speaker = await Speaker.open({ sampleRate: 16000, channels: 1 });
+
+await speaker.writeAsync(pcmBuffer);
+await speaker.drainAsync(); // resolves when playback finishes
+```
+
+These are a direct alternative to the synchronous `write()` / `pipe()` / `end()` stream interface, which is unchanged. Use one path per instance (the stream methods or the async methods, not both at once), and await calls in sequence to keep samples in order.
+
 ## Errors
 
 Construction errors come as typed classes you can catch:
@@ -182,6 +229,37 @@ The browser runs energy-mode VAD only, so its `vad` option accepts `false` or `'
 | Sample rate | Native device rate | Resampled from native rate |
 | VAD | `'silero'` or `'energy'` | `'energy'` only |
 
+### `new Speaker(options?)` (browser)
+
+Browser audio playback through the Web Audio API. Playback is async (Promise based) and must be started from a user gesture so the browser allows audio.
+
+```javascript
+import { Speaker } from 'decibri'; // browser entry via conditional export
+
+const speaker = new Speaker({ sampleRate: 16000 });
+
+playButton.onclick = async () => {
+  await speaker.write(int16Chunk); // Int16Array of PCM samples
+  await speaker.drain();           // resolves when playback finishes
+  speaker.stop();
+};
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sampleRate` | number | 16000 | Sample rate of the audio you write (resampled to the output rate) |
+| `channels` | number | 1 | Output channels (a mono stream plays on every channel) |
+| `dtype` | `'int16'` \| `'float32'` | `'int16'` | Encoding of the samples you write |
+| `workletUrl` | string | inline blob | Custom worklet URL for strict CSP |
+
+- `start()` creates and resumes the audio output. Optional: `write()` starts it on the first call. Either must run in a user gesture (a click or tap); a context blocked by the autoplay policy surfaces a clear error.
+- `write(chunk)` resolves when the samples are queued. It waits when the buffer is full, so awaiting it paces playback. Await calls sequentially to preserve order.
+- `drain()` resolves when the queued audio has finished playing, immediately if nothing is queued.
+- `stop()` halts immediately and discards anything queued.
+- `isPlaying` reports whether audio is currently queued and playing.
+
+To verify playback in real browsers, open `examples/browser-speaker-test.html` (see `examples/README.md`).
+
 ## Voice Activity Detection
 
 ### Energy mode
@@ -244,6 +322,8 @@ node node_modules/decibri/examples/websocket-server.js   # terminal 1
 node node_modules/decibri/examples/websocket-stream.js   # terminal 2
 ```
 
+For the browser, `examples/browser-speaker-test.html` is a page for manually verifying audio playback in each browser. See `examples/README.md` for how to serve it on desktop and mobile.
+
 ## Migrating from 3.x
 
 decibri 4.0.0 renames the API to a microphone and speaker vocabulary and switches to named exports. See [MIGRATION.md](./MIGRATION.md) for a complete before-and-after guide.

package/examples/README.md

@@ -0,0 +1,79 @@
+# decibri examples
+
+Runnable examples for decibri. The Node.js examples run with `node`; the browser
+example is an HTML page you open in a browser.
+
+## Node.js examples
+
+| File | What it does | Notes |
+| --- | --- | --- |
+| `wav-capture.js` | Captures audio and writes a valid WAV file | No extra dependencies |
+| `websocket-server.js` | Receives raw PCM chunks and logs byte counts | Requires `npm install ws` |
+| `websocket-stream.js` | Streams raw PCM audio to a WebSocket server | Requires `npm install ws` |
+
+```bash
+node wav-capture.js
+node websocket-server.js   # terminal 1
+node websocket-stream.js   # terminal 2
+```
+
+## Browser audio playback test (`browser-speaker-test.html`)
+
+A page for manually verifying that the browser Speaker plays real audio in each
+browser. It loads the real browser build (`decibri.browser.js`, a bundle of the
+package's browser entry) and plays generated tones so you can listen for a clean
+signal, glitches, correct pitch after resampling, and immediate stop.
+
+Browser audio needs a secure context, so the page must be served over
+`localhost` or `https`. Opening it as a `file://` URL will not load the audio
+engine.
+
+### Desktop
+
+From this `examples` directory, serve it over localhost and open the printed URL
+in each browser you want to test:
+
+```bash
+npx serve .
+# or
+npx http-server . -p 8080
+```
+
+Then open `http://localhost:<port>/browser-speaker-test.html` in Chrome, Firefox,
+Edge, and Safari, and tap the buttons.
+
+### Mobile (same WiFi)
+
+Serve on your computer as above, find your machine's LAN IP, and open
+`http://<machine-ip>:<port>/browser-speaker-test.html` on the phone (on the same
+network).
+
+iOS Safari treats a plain `http://<LAN-IP>` address as an insecure context and
+will refuse to start audio. For iOS, expose the local server over `https` with a
+tunnel and open the tunnel URL on the phone:
+
+```bash
+npx localtunnel --port 8080
+# open the printed https://... URL on the phone, then add /browser-speaker-test.html
+```
+
+### What to check in each browser
+
+- 440 Hz tone: a clean, steady tone with no buzz or distortion.
+- Continuous (3 s): smooth, with no gaps, clicks, or dropouts.
+- Resampled from 16 kHz: the same pitch as the 440 Hz tone button (confirms
+  resampling does not shift pitch).
+- Stop: playback halts immediately when tapped mid-playback.
+- Gesture requirement: nothing plays until you tap a button; if the browser
+  blocks audio, a clear error appears in the on-page log.
+- Both formats: repeat with the int16 and float32 toggle.
+
+### Regenerating the browser bundle
+
+`decibri.browser.js` is generated from the package's browser entry
+(`../src/browser/index.js`). Regenerate it after changing the browser source
+with any bundler that resolves the package's `browser` entry, for example:
+
+```bash
+npx esbuild ../src/browser/index.js --bundle --format=iife --global-name=decibri --outfile=decibri.browser.js
+```

package/examples/browser-speaker-test.html

@@ -0,0 +1,159 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>decibri browser audio playback test</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: system-ui, sans-serif; max-width: 680px; margin: 40px auto; padding: 0 20px; color: #222; }
+    h1 { font-size: 1.4rem; margin-bottom: 8px; }
+    p.intro { font-size: 0.9rem; color: #555; margin-bottom: 16px; line-height: 1.5; }
+    .format-toggle { margin-bottom: 16px; font-size: 0.9rem; }
+    .format-toggle label { margin-right: 12px; cursor: pointer; }
+    .controls { display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 16px; }
+    button { padding: 10px 16px; font-size: 0.9rem; border: 1px solid #ccc; border-radius: 4px; cursor: pointer; background: #f8f8f8; }
+    button:hover { background: #e8e8e8; }
+    button.stop { border-color: #f44336; color: #c62828; }
+    .hint { display: block; font-size: 0.75rem; color: #888; margin-top: 2px; }
+    .stats { font-size: 0.85rem; color: #666; margin-bottom: 12px; }
+    #log { background: #1a1a1a; color: #0f0; font-family: monospace; font-size: 0.8rem; padding: 12px; border-radius: 4px; height: 320px; overflow-y: auto; white-space: pre-wrap; word-break: break-all; }
+  </style>
+</head>
+<body>
+  <h1>decibri browser audio playback test</h1>
+  <p class="intro">
+    Tap a button to play audio through the browser Speaker, then listen and watch the log.
+    Playback must start from a tap (the browser only allows audio after a user gesture), so
+    nothing plays until you tap. Serve this page over <strong>localhost</strong> or
+    <strong>https</strong>; opening it as a <code>file://</code> URL will not work. See
+    <code>examples/README.md</code> for serve and mobile instructions.
+  </p>
+
+  <div class="format-toggle">
+    <strong>Format:</strong>
+    <label><input type="radio" name="dtype" value="int16" checked> int16</label>
+    <label><input type="radio" name="dtype" value="float32"> float32</label>
+  </div>
+
+  <div class="controls">
+    <div>
+      <button id="btn-tone">Play 440 Hz tone</button>
+      <span class="hint">about 1.5 s. Should be a clean, steady tone.</span>
+    </div>
+    <div>
+      <button id="btn-continuous">Play 3 s continuous</button>
+      <span class="hint">Listen for any gaps, clicks, or dropouts.</span>
+    </div>
+    <div>
+      <button id="btn-resampled">Play 440 Hz from 16 kHz</button>
+      <span class="hint">Forces resampling. Should match the first button's pitch.</span>
+    </div>
+    <div>
+      <button id="btn-stop" class="stop">Stop</button>
+      <span class="hint">Should halt immediately.</span>
+    </div>
+  </div>
+
+  <div class="stats" id="stats">Idle.</div>
+  <div id="log"></div>
+
+  <!--
+    This page loads the real browser Speaker from examples/decibri.browser.js, a
+    generated bundle of the package's browser entry (src/browser/index.js). It is
+    the actual shipped code, not a copy. See examples/README.md to regenerate it.
+  -->
+  <script src="./decibri.browser.js"></script>
+  <script>
+    const { Speaker } = decibri;
+
+    const logEl = document.getElementById('log');
+    const statsEl = document.getElementById('stats');
+
+    let current = null;
+
+    function log(msg) {
+      const ts = new Date().toISOString().slice(11, 23);
+      logEl.textContent += `[${ts}] ${msg}\n`;
+      logEl.scrollTop = logEl.scrollHeight;
+    }
+
+    function setStats(text) {
+      const playing = current ? current.isPlaying : false;
+      statsEl.textContent = `${text}  |  isPlaying: ${playing}`;
+    }
+
+    function getDtype() {
+      return document.querySelector('input[name="dtype"]:checked').value;
+    }
+
+    // Generate a sine tone at `rate` Hz with short fades to avoid edge clicks.
+    function genTone(freq, seconds, rate, dtype) {
+      const n = Math.floor(rate * seconds);
+      const amp = 0.25;
+      const fade = Math.min(Math.floor(rate * 0.005), Math.floor(n / 2));
+      const f32 = new Float32Array(n);
+      for (let i = 0; i < n; i++) {
+        let env = 1;
+        if (i < fade) env = i / fade;
+        else if (i >= n - fade) env = (n - 1 - i) / fade;
+        f32[i] = Math.sin(2 * Math.PI * freq * i / rate) * amp * env;
+      }
+      if (dtype === 'float32') return f32;
+      const i16 = new Int16Array(n);
+      for (let i = 0; i < n; i++) {
+        i16[i] = Math.max(-32768, Math.min(32767, Math.round(f32[i] * 32767)));
+      }
+      return i16;
+    }
+
+    function stopCurrent() {
+      if (current) {
+        current.stop();
+        log('stop()');
+        current = null;
+        setStats('Stopped.');
+      }
+    }
+
+    async function play(label, freq, seconds, srcRate) {
+      stopCurrent();
+      const dtype = getDtype();
+      log(`${label}: ${seconds}s of ${freq} Hz, source ${srcRate} Hz, dtype=${dtype}`);
+      setStats('Starting...');
+      const speaker = new Speaker({ sampleRate: srcRate, dtype });
+      current = speaker;
+      try {
+        const tone = genTone(freq, seconds, srcRate, dtype);
+        await speaker.write(tone);
+        log(`queued ${tone.length} samples, waiting for playback to finish...`);
+        setStats('Playing...');
+        await speaker.drain();
+        log('drained (playback finished)');
+        setStats('Finished.');
+        // Only tear down if a newer play has not replaced this one.
+        if (current === speaker) {
+          speaker.stop();
+          current = null;
+        }
+      } catch (err) {
+        log('ERROR: ' + (err && err.message ? err.message : String(err)));
+        setStats('Error (see log).');
+      }
+    }
+
+    document.getElementById('btn-tone').addEventListener('click', () => {
+      play('440 Hz tone', 440, 1.5, 44100);
+    });
+    document.getElementById('btn-continuous').addEventListener('click', () => {
+      play('continuous', 440, 3, 44100);
+    });
+    document.getElementById('btn-resampled').addEventListener('click', () => {
+      play('resampled from 16 kHz', 440, 1.5, 16000);
+    });
+    document.getElementById('btn-stop').addEventListener('click', stopCurrent);
+
+    log('Ready. Tap a button to play.');
+  </script>
+</body>
+</html>