decibri 4.1.0 → 4.3.0

package/CHANGELOG.md

@@ -11,6 +11,18 @@ For other decibri packages, see:
 
 ## [Unreleased]
 
+## [4.3.0] - Unreleased
+
+### Fixed
+
+- The Silero VAD never detected speech due to a missing 64-sample audio context required by Silero v5. VAD probabilities now reflect real speech activity. If you consume VAD output, expect meaningful probabilities where previously everything sat near zero.
+
+## [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

package/MIGRATION.md

@@ -5,6 +5,20 @@ 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

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
@@ -216,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
@@ -278,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>