Skip to content

Add browser documentation and update main site references #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rossarmstrong merged 1 commit into from
Apr 6, 2026
Merged

Add browser documentation and update main site references #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
347 changes: 347 additions & 0 deletions docs/docs/browser/api-reference.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,347 @@
<!DOCTYPE html>
<html lang="en" data-theme="dark">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="theme-color" content="#0a0a0f" media="(prefers-color-scheme: dark)">
<meta name="theme-color" content="#f8f8fb" media="(prefers-color-scheme: light)">
<script>
(function() {
var t = localStorage.getItem('decibri-theme');
if (t) document.documentElement.setAttribute('data-theme', t);
else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: light)').matches) document.documentElement.setAttribute('data-theme', 'light');
})();
</script>
<title>API Reference | decibri docs</title>
<meta name="description" content="decibri-web API reference. Constructor options, methods, events, types, and differences from decibri for Node.js.">
<meta name="robots" content="index, follow">
<meta property="og:title" content="API Reference | decibri docs">
<meta property="og:description" content="decibri-web API reference. Constructor options, methods, events, types, and differences from decibri for Node.js.">
<meta property="og:type" content="article">
<meta property="og:url" content="https://decibri.dev/docs/browser/api-reference.html">
<link rel="canonical" href="https://decibri.dev/docs/browser/api-reference.html">
<link rel="icon" href="/favicon.ico" type="image/x-icon">
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Outfit:wght@300;400;500;600;700&display=swap" rel="stylesheet">
<link rel="stylesheet" href="../styles.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css">
</head>
<body>

<nav class="docs-nav">
<div class="nav-inner">
<a href="/docs/index.html" class="nav-logo">deci<span>bri</span> docs</a>
<div class="mobile-nav">
<a href="https://github.com/analyticsinmotion/decibri-web" class="nav-cta" target="_blank" rel="noopener noreferrer" aria-label="GitHub"><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg></a>
<button class="mobile-nav-btn" onclick="toggleTheme()" aria-label="Toggle theme" title="Toggle theme">
<svg class="icon-moon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>
<svg class="icon-sun" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/><line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/></svg>
</button>
<button class="mobile-nav-btn" onclick="toggleMobileMenu()" aria-label="Open menu">
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="3" y1="6" x2="21" y2="6"/><line x1="3" y1="12" x2="21" y2="12"/><line x1="3" y1="18" x2="21" y2="18"/></svg>
</button>
</div>
</div>
</nav>
<div class="mobile-menu-overlay" onclick="toggleMobileMenu()"></div>
<div class="mobile-menu"></div>
<div class="sidebar-overlay"></div>
<aside id="sidebar" class="sidebar"></aside>

<div class="doc-content">
<div class="doc-container">

<div class="breadcrumb">
<a href="/docs/index.html">Docs</a>
<span class="sep">/</span>
<a href="/docs/browser/index.html">Browser</a>
<span class="sep">/</span>
<span class="current">API Reference</span>
</div>

<h1>API Reference</h1>
<p class="lead">Complete reference for the decibri-web browser API. For installation and basic usage, see <a href="index.html">Getting Started</a>.</p>

<h2>Constructor</h2>
<h3><code>new Decibri(options?)</code></h3>
<p>Creates a new capture instance. Does not start capture. Call <code>start()</code> to begin.</p>
<pre><code class="language-javascript">import { Decibri } from 'decibri-web';
const mic = new Decibri(options?);</code></pre>

<div class="table-wrap">
<table>
<thead>
<tr>
<th>Option</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>sampleRate</code></td>
<td><code>number</code></td>
<td><code>16000</code></td>
<td>Target sample rate in Hz (1,000 to 384,000)</td>
</tr>
<tr>
<td><code>channels</code></td>
<td><code>number</code></td>
<td><code>1</code></td>
<td>Number of channels (browsers reliably support 1)</td>
</tr>
<tr>
<td><code>framesPerBuffer</code></td>
<td><code>number</code></td>
<td><code>1600</code></td>
<td>Frames per chunk. 1,600 at 16 kHz = 100 ms chunks (64 to 65,536)</td>
</tr>
<tr>
<td><code>device</code></td>
<td><code>string</code></td>
<td>system default</td>
<td><code>deviceId</code> string from <code>Decibri.devices()</code></td>
</tr>
<tr>
<td><code>format</code></td>
<td><code>'int16' | 'float32'</code></td>
<td><code>'int16'</code></td>
<td>Sample encoding format</td>
</tr>
<tr>
<td><code>vad</code></td>
<td><code>boolean</code></td>
<td><code>false</code></td>
<td>Enable voice activity detection</td>
</tr>
<tr>
<td><code>vadThreshold</code></td>
<td><code>number</code></td>
<td><code>0.01</code></td>
<td>RMS energy threshold for speech detection (0 to 1)</td>
</tr>
<tr>
<td><code>vadHoldoff</code></td>
<td><code>number</code></td>
<td><code>300</code></td>
<td>Milliseconds of sub-threshold audio before <code>'silence'</code> is emitted</td>
</tr>
<tr>
<td><code>echoCancellation</code></td>
<td><code>boolean</code></td>
<td><code>true</code></td>
<td>Browser echo cancellation. Set <code>false</code> for music/tuner apps</td>
</tr>
<tr>
<td><code>noiseSuppression</code></td>
<td><code>boolean</code></td>
<td><code>true</code></td>
<td>Browser noise suppression. Set <code>false</code> for raw signal</td>
</tr>
<tr>
<td><code>workletUrl</code></td>
<td><code>string</code></td>
<td>(inline Blob URL)</td>
<td>URL for AudioWorklet processor file. Override if CSP blocks <code>blob:</code> URLs</td>
</tr>
</tbody>
</table>
</div>

<h2>Methods</h2>

<h3><code>mic.start()</code></h3>
<p>Returns <code>Promise&lt;void&gt;</code>. Requests microphone permission and begins capture. Must be called from a user gesture in Safari. No-op if already started. Rejects with a clear error on permission denial.</p>

<h3><code>mic.stop()</code></h3>
<p>Stops capture and releases all resources (tracks, context, nodes). Safe to call anytime, including before <code>start()</code> or multiple times. Emits <code>'end'</code> then <code>'close'</code>.</p>

<h2>Properties</h2>

<h3><code>mic.isOpen</code></h3>
<p><code>boolean</code> (read-only). Returns <code>true</code> while actively capturing audio.</p>

<h2>Static methods</h2>

<h3><code>Decibri.devices()</code></h3>
<p>Returns <code>Promise&lt;DeviceInfo[]&gt;</code>. Lists available audio input devices. Labels may be empty before microphone permission is granted.</p>
<pre><code class="language-javascript">const devices = await Decibri.devices();
console.log(devices);
// [
// { deviceId: 'abc123', label: 'Built-in Microphone', groupId: 'g1' },
// ...
// ]</code></pre>

<h3><code>Decibri.version()</code></h3>
<p>Returns version information for decibri-web.</p>
<pre><code class="language-javascript">Decibri.version();
// { decibriWeb: '0.1.0' }</code></pre>

<h2>Events</h2>

<div class="table-wrap">
<table>
<thead>
<tr>
<th>Event</th>
<th>Payload</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>'data'</code></td>
<td><code>Int16Array</code> or <code>Float32Array</code></td>
<td>Audio chunk. Format depends on <code>format</code> option. Emitted ~10 times/sec at default settings.</td>
</tr>
<tr>
<td><code>'error'</code></td>
<td><code>Error</code></td>
<td>Permission denied, worklet load failure, AudioContext creation failure.</td>
</tr>
<tr>
<td><code>'end'</code></td>
<td>(none)</td>
<td>Emitted after <code>stop()</code>.</td>
</tr>
<tr>
<td><code>'close'</code></td>
<td>(none)</td>
<td>Emitted after <code>stop()</code>, after <code>'end'</code>.</td>
</tr>
<tr>
<td><code>'speech'</code></td>
<td>(none)</td>
<td>VAD: RMS energy crossed threshold. Requires <code>vad: true</code>.</td>
</tr>
<tr>
<td><code>'silence'</code></td>
<td>(none)</td>
<td>VAD: sub-threshold audio for <code>vadHoldoff</code> ms. Requires <code>vad: true</code>.</td>
</tr>
</tbody>
</table>
</div>

<h2>Types</h2>
<pre><code class="language-javascript">// DeviceInfo
{
deviceId: string,
label: string,
groupId: string,
}

// VersionInfo
{
decibriWeb: string,
}</code></pre>

<h2>Differences from decibri (Node.js)</h2>
<div class="table-wrap">
<table>
<thead>
<tr>
<th>Feature</th>
<th>Node.js <code>decibri</code></th>
<th><code>decibri-web</code></th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>Class name</td>
<td><code>Decibri</code></td>
<td><code>Decibri</code></td>
<td>Identical</td>
</tr>
<tr>
<td>Constructor</td>
<td>Sync, capture starts on read</td>
<td>Sync, requires <code>await start()</code></td>
<td>Browser needs async permission</td>
</tr>
<tr>
<td><code>'data'</code> payload</td>
<td><code>Buffer</code></td>
<td><code>Int16Array</code> / <code>Float32Array</code></td>
<td>Different types, same PCM data</td>
</tr>
<tr>
<td><code>devices()</code></td>
<td>Sync</td>
<td>Async (returns Promise)</td>
<td>Browser API is async</td>
</tr>
<tr>
<td><code>device</code> option</td>
<td>Number index or name substring</td>
<td>String <code>deviceId</code> only</td>
<td>Browser uses opaque device IDs</td>
</tr>
<tr>
<td><code>version()</code></td>
<td><code>{ decibri, portaudio }</code></td>
<td><code>{ decibriWeb }</code></td>
<td>Different runtime info</td>
</tr>
<tr>
<td><code>echoCancellation</code></td>
<td>N/A</td>
<td><code>boolean</code> (default <code>true</code>)</td>
<td>Browser-only option</td>
</tr>
<tr>
<td><code>noiseSuppression</code></td>
<td>N/A</td>
<td><code>boolean</code> (default <code>true</code>)</td>
<td>Browser-only option</td>
</tr>
<tr>
<td><code>'backpressure'</code> event</td>
<td>Available</td>
<td>Not available</td>
<td>No browser equivalent</td>
</tr>
<tr>
<td><code>pipe()</code> / streams</td>
<td>Full Readable stream</td>
<td>Not available</td>
<td>Browser has no Node streams</td>
</tr>
<tr>
<td><code>sampleRate</code></td>
<td>Any (PortAudio resamples)</td>
<td>Any (AudioWorklet resamples)</td>
<td>Same behavior</td>
</tr>
<tr>
<td><code>format</code></td>
<td><code>'int16'</code> or <code>'float32'</code></td>
<td><code>'int16'</code> or <code>'float32'</code></td>
<td>Identical</td>
</tr>
<tr>
<td>VAD (<code>speech</code>/<code>silence</code>)</td>
<td>RMS-based</td>
<td>RMS-based (same algorithm)</td>
<td>Identical</td>
</tr>
</tbody>
</table>
</div>

<footer class="doc-footer">
<p>Apache-2.0 &copy; <a href="https://analyticsinmotion.com" target="_blank" rel="noopener noreferrer">Analytics in Motion</a> &middot; <a href="https://github.com/analyticsinmotion/decibri-web" target="_blank" rel="noopener noreferrer">GitHub</a> &middot; <a href="https://www.npmjs.com/package/decibri-web" target="_blank" rel="noopener noreferrer">npm</a></p>
</footer>

</div>
</div>

<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-javascript.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-bash.min.js"></script>
<script src="../nav.js"></script>
</body>
</html>
Loading