auditok 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amine SEHILI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# auditok.js
+
+**Audio activity detection and segmentation for JavaScript** — the
+[auditok](https://github.com/amsehili/auditok) Python package, ported to run
+in Node and in the browser. Zero dependencies.
+
+`auditok` finds where the sound is. It splits audio into *events* — regions
+of acoustic activity shaped by duration and silence rules — rather than
+emitting raw per-frame speech/no-speech booleans:
+
+- **Event semantics, not frame booleans**: minimum and maximum event
+  duration, tolerated silence inside an event, leading/trailing silence
+  handling for natural onsets and fadeouts.
+- **Offline file segmentation and online streaming** with the same API:
+  events are yielded as soon as their end is decided, while the input is
+  still being read, decoded or recorded.
+- **Generic acoustic activity**, not speech-only — music, claps, beeps,
+  speech alike. For speech-specific detection, plug any frame-level VAD into
+  the tokenizer as a custom validator and get proper event shaping on top of
+  its decisions.
+- **A few KB of plain JS** — no ONNX runtime, no model downloads, no native
+  modules.
+
+The detection engine, energy scale and parameters are those of Python
+auditok: thresholds are in dB relative to 16-bit full scale, and the test
+suite replays fixtures generated by the Python implementation to keep the
+two in lockstep — same tokens, same event boundaries, same estimated
+thresholds.
+
+**[Try it in your browser](https://amsehili.github.io/auditok.js/)** — drop
+an audio file or record your microphone, tune the threshold, listen to the
+detected events. Everything runs client-side.
+
+## Install
+
+```sh
+npm install auditok
+```
+
+Node ≥ 18. In Node, WAV files are parsed natively; every other format
+(mp3, ogg, flac, aac, …) and microphone capture go through
+[ffmpeg](https://ffmpeg.org/), which must be on the `PATH`. In the browser,
+decoding and microphone input use the Web Audio API — nothing to install.
+
+## Quick start (Node)
+
+```js
+import { load, split } from "auditok";
+
+const audio = await load("audio.mp3"); // WAV parsed natively, rest via ffmpeg
+
+for await (const event of split(audio)) {
+  console.log(`event: ${event.start.toFixed(3)}s -> ${event.end.toFixed(3)}s`);
+}
+```
+
+Split a large compressed file *while it is being decoded*:
+
+```js
+import { decodeFileStream, split } from "auditok";
+
+const stream = decodeFileStream("podcast.mp3", { sampleRate: 16000 });
+for await (const event of split(stream.chunks, { sampleRate: stream.sampleRate })) {
+  console.log(event.start, event.end);
+}
+```
+
+Detect events from the microphone (captured through ffmpeg):
+
+```js
+import { microphone, split } from "auditok";
+
+const mic = microphone({ sampleRate: 16000 });
+for await (const event of split(mic.chunks, { sampleRate: mic.sampleRate })) {
+  console.log(`heard something: ${event.start.toFixed(2)}s, ${event.duration.toFixed(2)}s`);
+}
+```
+
+Save events or processed audio as WAV:
+
+```js
+import { load, fixPauses, save } from "auditok";
+
+const cleaned = await fixPauses(await load("interview.wav"), 0.4);
+await save("cleaned.wav", cleaned);
+```
+
+## Quick start (browser)
+
+Same core API; `load` uses the browser's own decoder and `microphone` uses
+getUserMedia + AudioWorklet:
+
+```js
+import { load, microphone, split } from "auditok";
+
+// from an <input type="file"> or drag-and-drop
+const audio = await load(fileInput.files[0]);
+for await (const event of split(audio)) {
+  highlight(event.start, event.end);
+}
+
+// live from the microphone (call from a user gesture)
+const mic = await microphone();
+for await (const event of split(mic.chunks, { sampleRate: mic.sampleRate })) {
+  console.log("speech-like activity", event.start, event.end);
+}
+// later: mic.stop()
+```
+
+A Web Audio `AudioBuffer` can be passed to `split` directly.
+
+## API
+
+### `split(input, options)` → `AsyncGenerator<AudioRegion>`
+
+`input` is one of: `Float32Array` (mono samples), `Float32Array[]` (planar
+channels), an `AudioRegion`, `{ channelData, sampleRate }`, an
+`AudioBuffer`, or a sync/async iterable of interleaved `Float32Array`
+chunks (the streaming path). Bare samples and chunk streams need
+`options.sampleRate`.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `minDur` | `0.2` | Minimum event duration in seconds |
+| `maxDur` | `5` | Maximum event duration (`null` = unlimited); longer events are truncated |
+| `maxSilence` | `0.3` | Maximum continuous silence *within* an event — controls when an event ends |
+| `maxLeadingSilence` | `0` | Silence kept before each event (natural attack) |
+| `maxTrailingSilence` | `null` | Trailing silence kept at the end of each event: `null` keeps all (up to `maxSilence`), `0` drops it, larger values extend collection past the boundary (natural fadeout) |
+| `strictMinDur` | `false` | Reject events shorter than `minDur` even right after a truncated event |
+| `analysisWindow` | `0.05` | Analysis window duration in seconds |
+| `energyThreshold` | `50` | Detection threshold in dB (relative to int16 full scale), used when no `validator` is given |
+| `validator` | — | `"otsu"`, `"percentile"`, `"pXX"` or a function — see below |
+| `useChannel` | `"any"` | Channel used for detection on multichannel audio: `"any"` (max over channels), `"mix"`, or a channel index |
+
+`splitAll(input, options)` returns the events as an array.
+
+### Automatic thresholding and custom validators
+
+If `validator` is set it is the whole story and `energyThreshold` is
+overlooked:
+
+- `"otsu"` splits the energy histogram in two classes (balanced,
+  parameter-free);
+- `"percentile"` (alias `"p10"`) or `"pXX"` reads the noise floor at the
+  XXth percentile of window energies and adds a 6 dB margin
+  (recall-oriented).
+
+For in-memory input the threshold is estimated from the whole input before
+detection starts. For chunk-stream input (e.g., a live microphone) it is
+**calibrated on the first `calibrationDur` seconds** (default 3), clamped to
+`minEnergyThreshold` (default 40 dB); the calibration audio is replayed, so
+no data is lost. A digitally silent calibration window (muted microphone)
+falls back to the floor and detection keeps running.
+
+A **function** validator receives each analysis window as planar
+per-channel samples and decides its validity — this is how you put proper
+event shaping on top of any frame-level VAD (an energy rule of your own, a
+WASM model, Silero frame decisions, …):
+
+```js
+for await (const event of split(audio, {
+  validator: ([samples]) => myFrameVad(samples), // true = active frame
+  maxSilence: 0.1,
+})) { ... }
+```
+
+To detect *speech* specifically rather than any acoustic activity, the
+[auditok-webrtcvad](https://www.npmjs.com/package/auditok-webrtcvad)
+add-on (in this repository under `webrtcvad/`) provides the WebRTC voice
+activity detector as such a validator — libfvad compiled to a ~30 KB
+WASM binary, the counterpart of Python auditok's `validator="webrtc:N"`:
+
+```js
+import { createWebrtcValidator } from "auditok-webrtcvad";
+
+const validator = await createWebrtcValidator({ sampleRate: 16000, mode: 1 });
+for await (const event of split(audio, { validator, maxSilence: 0.1 })) { ... }
+```
+
+### `trim(input, options)` → `Promise<AudioRegion>`
+
+Audio from the start of the first detection to the end of the last —
+leading and trailing silence removed. Streams are read once and recorded
+while being consumed.
+
+### `fixPauses(input, silenceDuration, options)` → `Promise<AudioRegion>`
+
+All detected events (never truncated) joined with exactly
+`silenceDuration` seconds of silence between them.
+
+### `AudioRegion`
+
+What `split` yields: `channelData` (planar `Float32Array` per channel),
+`sampleRate`, `start`, `end`, `duration`, `channels`, `sampleCount`, and
+`toWav()` for a WAV-encoded `Uint8Array`.
+
+### Lower level
+
+- `StreamTokenizer` — the generic event-shaping state machine, usable over
+  any frame type;
+- `calculateEnergy`, `windowEnergy`, `computeFrameEnergies`,
+  `estimateEnergyThreshold` — the energy/threshold toolbox;
+- `decodeWav`, `encodeWav` — dependency-free WAV codec (Node and browser);
+- Node: `load`, `save`, `decodeFileStream`, `microphone`;
+- browser: `load`, `microphone`.
+
+`import ... from "auditok/core"` gives the environment-free core only.
+
+## Demo
+
+The playground lives in `docs/` and is served by GitHub Pages straight from
+the main branch — plain ES modules, no bundler. It imports the built
+library from `docs/lib`; refresh that copy after changing the source with
+`npm run demo:lib`. To try it locally, serve the folder with any static
+server, e.g. `npm run demo:serve`.
+
+## Relationship to Python auditok
+
+Same algorithm, same parameters (camelCased), same dB scale — a threshold
+that works with one implementation works with the other, and the
+[Python documentation](https://auditok.readthedocs.io/) is a valid
+reference for the detection semantics. Parity is enforced by fixtures
+generated with the Python package (`tools/generate_fixtures.py`): the JS
+test suite replays ~300 recorded cases through the tokenizer, `split` and
+the threshold estimators.
+
+The WebRTC VAD validator (`validator="webrtc:N"` in Python) is available
+as the separate opt-in
+[auditok-webrtcvad](https://www.npmjs.com/package/auditok-webrtcvad)
+package, so the core keeps its size claim honest; its frame decisions are
+parity-tested bit for bit against Python's `webrtcvad`. Not (yet) ported:
+live threshold calibration for streams and the command-line tool.
+
+## License
+
+MIT — © Amine Sehili

package/dist/browser/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Browser entry point: everything from the core, plus decoding of
+ * compressed audio through the browser's own decoder
+ * (`decodeAudioData` handles mp3/aac/ogg/flac/wav in every browser)
+ * and microphone capture through getUserMedia + AudioWorklet. No
+ * external assets, no dependencies.
+ */
+import { AudioRegion } from "../region.js";
+export * from "../index.js";
+export interface BrowserLoadOptions {
+    /** Target sample rate for compressed formats (the browser resamples
+     * while decoding), default 16000. WAV files are parsed natively at
+     * their own rate unless `forceDecode` is set. */
+    sampleRate?: number;
+    /** Decode WAV files through the browser decoder too (resampling them
+     * to `sampleRate`) instead of parsing them natively. */
+    forceDecode?: boolean;
+}
+/**
+ * Load audio in the browser into an {@link AudioRegion}. Accepts a
+ * `File`/`Blob` (e.g. from a file input or drag-and-drop), an
+ * `ArrayBuffer`/`Uint8Array`, or a URL string (fetched with CORS
+ * rules applying).
+ */
+export declare function load(source: File | Blob | ArrayBuffer | Uint8Array | string, options?: BrowserLoadOptions): Promise<AudioRegion>;
+export interface BrowserMicrophoneOptions {
+    /** Sample rate of the capture AudioContext, default 16000. */
+    sampleRate?: number;
+}
+export interface BrowserAudioStream {
+    /** Mono Float32Array chunks — feed this to `split`. */
+    chunks: AsyncIterable<Float32Array>;
+    sampleRate: number;
+    channels: 1;
+    /** Stop the capture and release the microphone. */
+    stop(): void;
+}
+/**
+ * Capture the microphone as a stream of mono Float32Array chunks via
+ * an AudioWorklet (the worklet module is inlined — no asset files).
+ * Must be called from a user gesture in most browsers. Call `stop()`
+ * to release the microphone.
+ */
+export declare function microphone(options?: BrowserMicrophoneOptions): Promise<BrowserAudioStream>;

package/dist/browser/index.js

@@ -0,0 +1,118 @@
+/**
+ * Browser entry point: everything from the core, plus decoding of
+ * compressed audio through the browser's own decoder
+ * (`decodeAudioData` handles mp3/aac/ogg/flac/wav in every browser)
+ * and microphone capture through getUserMedia + AudioWorklet. No
+ * external assets, no dependencies.
+ */
+import { AudioRegion } from "../region.js";
+import { decodeWav, isWav } from "../wav.js";
+export * from "../index.js";
+/**
+ * Load audio in the browser into an {@link AudioRegion}. Accepts a
+ * `File`/`Blob` (e.g. from a file input or drag-and-drop), an
+ * `ArrayBuffer`/`Uint8Array`, or a URL string (fetched with CORS
+ * rules applying).
+ */
+export async function load(source, options = {}) {
+    let bytes;
+    if (typeof source === "string") {
+        const response = await fetch(source);
+        if (!response.ok) {
+            throw new Error(`failed to fetch '${source}': ${response.status}`);
+        }
+        bytes = await response.arrayBuffer();
+    }
+    else if (source instanceof Blob) {
+        bytes = await source.arrayBuffer();
+    }
+    else if (source instanceof Uint8Array) {
+        bytes = source.buffer.slice(source.byteOffset, source.byteOffset + source.byteLength);
+    }
+    else {
+        bytes = source;
+    }
+    if (options.forceDecode !== true && isWav(bytes)) {
+        const { channelData, sampleRate } = decodeWav(bytes);
+        return new AudioRegion(channelData, sampleRate);
+    }
+    const sampleRate = options.sampleRate ?? 16000;
+    const context = new OfflineAudioContext({
+        numberOfChannels: 1,
+        length: 1,
+        sampleRate,
+    });
+    const buffer = await context.decodeAudioData(bytes);
+    const channelData = Array.from({ length: buffer.numberOfChannels }, (_, c) => buffer.getChannelData(c));
+    return new AudioRegion(channelData, buffer.sampleRate);
+}
+const CAPTURE_WORKLET = `
+class AuditokCapture extends AudioWorkletProcessor {
+  process(inputs) {
+    const input = inputs[0];
+    if (input && input[0] && input[0].length > 0) {
+      this.port.postMessage(input[0].slice());
+    }
+    return true;
+  }
+}
+registerProcessor("auditok-capture", AuditokCapture);
+`;
+/**
+ * Capture the microphone as a stream of mono Float32Array chunks via
+ * an AudioWorklet (the worklet module is inlined — no asset files).
+ * Must be called from a user gesture in most browsers. Call `stop()`
+ * to release the microphone.
+ */
+export async function microphone(options = {}) {
+    const sampleRate = options.sampleRate ?? 16000;
+    const media = await navigator.mediaDevices.getUserMedia({
+        audio: { channelCount: 1 },
+    });
+    const context = new AudioContext({ sampleRate });
+    const workletUrl = URL.createObjectURL(new Blob([CAPTURE_WORKLET], { type: "application/javascript" }));
+    try {
+        await context.audioWorklet.addModule(workletUrl);
+    }
+    finally {
+        URL.revokeObjectURL(workletUrl);
+    }
+    const sourceNode = context.createMediaStreamSource(media);
+    const captureNode = new AudioWorkletNode(context, "auditok-capture");
+    sourceNode.connect(captureNode);
+    const pending = [];
+    let notify;
+    let done = false;
+    captureNode.port.onmessage = (event) => {
+        pending.push(event.data);
+        notify?.();
+    };
+    async function* chunks() {
+        while (!done || pending.length > 0) {
+            if (pending.length === 0) {
+                await new Promise((resolve) => {
+                    notify = resolve;
+                });
+                notify = undefined;
+                continue;
+            }
+            yield pending.shift();
+        }
+    }
+    return {
+        chunks: chunks(),
+        sampleRate: context.sampleRate,
+        channels: 1,
+        stop() {
+            done = true;
+            captureNode.port.onmessage = null;
+            sourceNode.disconnect();
+            captureNode.disconnect();
+            for (const track of media.getTracks()) {
+                track.stop();
+            }
+            void context.close();
+            notify?.();
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * auditok core: audio activity detection and segmentation over
+ * Float32Array samples. Environment-free and dependency-free — this
+ * entry point works in Node, browsers, workers and edge runtimes.
+ *
+ * Importing the package root (`import ... from "auditok"`) adds the
+ * platform io helpers (file loading, microphone) on top of this core;
+ * `import ... from "auditok/core"` gives exactly this module.
+ */
+export { split, splitAll, trim, fixPauses, type AudioInput, type AudioFrame, type AudioBufferLike, type SplitOptions, } from "./split.js";
+export { AudioRegion, makeSilence, concatRegions } from "./region.js";
+export { StreamTokenizer, type FrameValidator, type Token, type StreamTokenizerOptions, } from "./tokenizer.js";
+export { calculateEnergy, windowEnergy, computeFrameEnergies, estimateEnergyThreshold, EPSILON, INT16_SCALE, SILENCE_ENERGY, type ChannelSelection, type ThresholdMethod, type ThresholdMethodOptions, } from "./signal.js";
+export { decodeWav, encodeWav, isWav, type DecodedAudio, type WavEncodeOptions, } from "./wav.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * auditok core: audio activity detection and segmentation over
+ * Float32Array samples. Environment-free and dependency-free — this
+ * entry point works in Node, browsers, workers and edge runtimes.
+ *
+ * Importing the package root (`import ... from "auditok"`) adds the
+ * platform io helpers (file loading, microphone) on top of this core;
+ * `import ... from "auditok/core"` gives exactly this module.
+ */
+export { split, splitAll, trim, fixPauses, } from "./split.js";
+export { AudioRegion, makeSilence, concatRegions } from "./region.js";
+export { StreamTokenizer, } from "./tokenizer.js";
+export { calculateEnergy, windowEnergy, computeFrameEnergies, estimateEnergyThreshold, EPSILON, INT16_SCALE, SILENCE_ENERGY, } from "./signal.js";
+export { decodeWav, encodeWav, isWav, } from "./wav.js";

package/dist/node/ffmpeg.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ffmpeg-backed decoding and capture for Node. ffmpeg is the single
+ * external tool auditok relies on outside WAV files — the same policy
+ * as the Python package: it decodes every compressed format and also
+ * captures audio devices, so the package itself keeps zero runtime
+ * dependencies.
+ */
+export interface FfmpegStreamOptions {
+    /** Output sample rate in Hz (ffmpeg resamples), default 16000. */
+    sampleRate?: number;
+    /** Output channel count (ffmpeg up/downmixes), default 1. */
+    channels?: number;
+    /** ffmpeg executable, default "ffmpeg" (must be on PATH). */
+    ffmpegPath?: string;
+}
+export interface AudioStream {
+    /** Interleaved Float32Array chunks — feed this to `split`. */
+    chunks: AsyncIterable<Float32Array>;
+    sampleRate: number;
+    channels: number;
+    /** Stop reading and terminate ffmpeg (for device capture). */
+    stop(): void;
+}
+/**
+ * Decode an audio file with ffmpeg into a stream of interleaved
+ * Float32Array chunks. Handles every format ffmpeg can read (mp3, ogg,
+ * flac, aac, video containers, ...), with optional resampling and
+ * channel mixing. The stream starts as soon as ffmpeg produces data,
+ * so `split` can emit events while the file is still being decoded.
+ */
+export declare function decodeFileStream(path: string, options?: FfmpegStreamOptions): AudioStream;
+export interface MicrophoneOptions extends FfmpegStreamOptions {
+    /**
+     * Capture device. Defaults per platform: `"default"` with PulseAudio
+     * on Linux, `":default"` with AVFoundation on macOS. On Windows
+     * (DirectShow) there is no default: pass the device name shown by
+     * `ffmpeg -list_devices true -f dshow -i dummy`, without the
+     * `audio=` prefix.
+     */
+    device?: string;
+}
+/**
+ * Capture the microphone through ffmpeg's device support (PulseAudio /
+ * AVFoundation / DirectShow). Returns a stream of interleaved
+ * Float32Array chunks; call `stop()` to end the capture.
+ */
+export declare function microphone(options?: MicrophoneOptions): AudioStream;

package/dist/node/ffmpeg.js

@@ -0,0 +1,117 @@
+/**
+ * ffmpeg-backed decoding and capture for Node. ffmpeg is the single
+ * external tool auditok relies on outside WAV files — the same policy
+ * as the Python package: it decodes every compressed format and also
+ * captures audio devices, so the package itself keeps zero runtime
+ * dependencies.
+ */
+import { spawn } from "node:child_process";
+function runFfmpeg(inputArgs, options) {
+    const sampleRate = options.sampleRate ?? 16000;
+    const channels = options.channels ?? 1;
+    const ffmpegPath = options.ffmpegPath ?? "ffmpeg";
+    const args = [
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        ...inputArgs,
+        "-f",
+        "f32le",
+        "-acodec",
+        "pcm_f32le",
+        "-ac",
+        String(channels),
+        "-ar",
+        String(sampleRate),
+        "-",
+    ];
+    const child = spawn(ffmpegPath, args, {
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stderr = "";
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (text) => {
+        stderr += text;
+    });
+    let stopped = false;
+    async function* chunks() {
+        // carry bytes that don't end on a float32 boundary to the next chunk
+        let carry = Buffer.alloc(0);
+        try {
+            for await (const data of child.stdout) {
+                const buffer = carry.length > 0 ? Buffer.concat([carry, data]) : data;
+                const usable = buffer.length - (buffer.length % 4);
+                carry = buffer.subarray(usable);
+                if (usable === 0) {
+                    continue;
+                }
+                const samples = new Float32Array(usable / 4);
+                for (let i = 0; i < samples.length; i++) {
+                    samples[i] = buffer.readFloatLE(i * 4);
+                }
+                yield samples;
+            }
+        }
+        finally {
+            child.kill("SIGKILL");
+        }
+        const exitCode = await new Promise((resolve) => {
+            if (child.exitCode !== null || stopped) {
+                resolve(child.exitCode);
+            }
+            else {
+                child.once("close", resolve);
+            }
+        });
+        if (!stopped && exitCode !== 0) {
+            throw new Error(`ffmpeg exited with code ${exitCode}: ${stderr.trim()}`);
+        }
+    }
+    return {
+        chunks: chunks(),
+        sampleRate,
+        channels,
+        stop() {
+            stopped = true;
+            child.kill("SIGTERM");
+        },
+    };
+}
+/**
+ * Decode an audio file with ffmpeg into a stream of interleaved
+ * Float32Array chunks. Handles every format ffmpeg can read (mp3, ogg,
+ * flac, aac, video containers, ...), with optional resampling and
+ * channel mixing. The stream starts as soon as ffmpeg produces data,
+ * so `split` can emit events while the file is still being decoded.
+ */
+export function decodeFileStream(path, options = {}) {
+    return runFfmpeg(["-i", path], options);
+}
+/**
+ * Capture the microphone through ffmpeg's device support (PulseAudio /
+ * AVFoundation / DirectShow). Returns a stream of interleaved
+ * Float32Array chunks; call `stop()` to end the capture.
+ */
+export function microphone(options = {}) {
+    let inputArgs;
+    const { device } = options;
+    switch (process.platform) {
+        case "linux":
+            inputArgs = ["-f", "pulse", "-i", device ?? "default"];
+            break;
+        case "darwin":
+            inputArgs = ["-f", "avfoundation", "-i", device ?? ":default"];
+            break;
+        case "win32":
+            if (device === undefined) {
+                throw new Error("on Windows, pass the capture device name (see " +
+                    "`ffmpeg -list_devices true -f dshow -i dummy`)");
+            }
+            inputArgs = ["-f", "dshow", "-i", `audio=${device}`];
+            break;
+        default:
+            throw new Error(`microphone capture is not supported on platform ` +
+                `'${process.platform}'`);
+    }
+    return runFfmpeg(inputArgs, options);
+}

package/dist/node/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Node entry point: everything from the core, plus file loading
+ * (native WAV parser, ffmpeg for everything else), microphone capture
+ * through ffmpeg, and WAV saving. Zero npm runtime dependencies.
+ */
+import { AudioRegion } from "../region.js";
+import { type WavEncodeOptions } from "../wav.js";
+import { type FfmpegStreamOptions } from "./ffmpeg.js";
+export * from "../index.js";
+export { decodeFileStream, microphone, type AudioStream, type FfmpegStreamOptions, type MicrophoneOptions, } from "./ffmpeg.js";
+export interface LoadOptions extends FfmpegStreamOptions {
+    /**
+     * By default WAV files are parsed natively at their own sample rate
+     * and channel count, and other formats are decoded with ffmpeg
+     * (resampled to `sampleRate`, mixed to `channels`). Set to true to
+     * force the ffmpeg path for WAV files too, e.g. to resample them.
+     */
+    forceFfmpeg?: boolean;
+}
+/**
+ * Load an audio file into an {@link AudioRegion}. WAV files are parsed
+ * natively; every other format is decoded with ffmpeg (which must be
+ * on the PATH). To detect events while a large compressed file is
+ * still being decoded, use {@link decodeFileStream} with `split`
+ * instead of loading it fully.
+ */
+export declare function load(path: string, options?: LoadOptions): Promise<AudioRegion>;
+/** Save a region (or any `{ channelData, sampleRate }`) as a WAV file. */
+export declare function save(path: string, audio: {
+    channelData: readonly Float32Array[];
+    sampleRate: number;
+}, options?: WavEncodeOptions): Promise<void>;