auditok 0.1.0

package/dist/tokenizer.js

@@ -0,0 +1,312 @@
+/**
+ * StreamTokenizer: the event-shaping state machine at the heart of
+ * auditok, ported line for line from the Python implementation. It is
+ * generic over the frame type — frames can be analysis windows of
+ * audio, characters, booleans from another VAD's frame decisions —
+ * and turns per-frame valid/invalid decisions into tokens with
+ * min/max length and silence semantics.
+ */
+const SILENCE = 0;
+const POSSIBLE_SILENCE = 1;
+const POSSIBLE_NOISE = 2;
+const NOISE = 3;
+const TRAILING_COLLECTION = 4;
+export class StreamTokenizer {
+    constructor(validator, options) {
+        this.state = SILENCE;
+        this.data = [];
+        this.leadingBuffer = [];
+        this.contiguousToken = false;
+        this.initCount = 0;
+        this.silenceLength = 0;
+        this.startFrame = 0;
+        this.currentFrame = -1;
+        if (typeof validator === "function") {
+            this.isValid = validator;
+        }
+        else if (validator && typeof validator.isValid === "function") {
+            this.isValid = validator.isValid.bind(validator);
+        }
+        else {
+            throw new TypeError("'validator' must be a function or an object with an isValid method");
+        }
+        const { minLength, maxLength, maxContinuousSilence, maxLeadingSilence = 0, maxTrailingSilence = null, strictMinLength = false, initMin = 0, initMaxSilence = 0, } = options;
+        if (maxLength <= 0) {
+            throw new RangeError(`'maxLength' must be > 0 (value=${maxLength})`);
+        }
+        if (minLength <= 0 || minLength > maxLength) {
+            throw new RangeError(`'minLength' must be > 0 and <= 'maxLength' (value=${minLength})`);
+        }
+        if (maxContinuousSilence >= maxLength) {
+            throw new RangeError(`'maxContinuousSilence' must be < 'maxLength' ` +
+                `(value=${maxContinuousSilence})`);
+        }
+        if (initMin >= maxLength) {
+            throw new RangeError(`'initMin' must be < 'maxLength' (value=${initMin})`);
+        }
+        this.minLength = minLength;
+        this.maxLength = maxLength;
+        this.maxContinuousSilence = maxContinuousSilence;
+        this.maxLeadingSilence = maxLeadingSilence;
+        this.maxTrailingSilence = maxTrailingSilence;
+        this.strictMinLength = strictMinLength;
+        this.initMin = initMin;
+        this.initMaxSilence = initMaxSilence;
+        this.needsTrailingExtension =
+            maxTrailingSilence !== null &&
+                maxTrailingSilence > maxContinuousSilence;
+    }
+    /**
+     * Tokenize `source` frame by frame, yielding tokens as soon as their
+     * end is decided. Accepts both sync and async iterables.
+     */
+    async *tokenize(source) {
+        this.reinitialize();
+        for await (const frame of source) {
+            this.currentFrame += 1;
+            const token = this.process(frame);
+            if (token !== undefined) {
+                yield token;
+            }
+        }
+        this.currentFrame += 1;
+        const token = this.postProcess();
+        if (token !== undefined) {
+            yield token;
+        }
+    }
+    /** Convenience wrapper collecting all tokens into an array. */
+    async tokenizeAll(source) {
+        const tokens = [];
+        for await (const token of this.tokenize(source)) {
+            tokens.push(token);
+        }
+        return tokens;
+    }
+    reinitialize() {
+        this.contiguousToken = false;
+        this.data = [];
+        this.state = SILENCE;
+        this.currentFrame = -1;
+        this.initCount = 0;
+        this.silenceLength = 0;
+        this.startFrame = 0;
+        this.leadingBuffer = [];
+    }
+    pushLeading(frame) {
+        if (this.maxLeadingSilence <= 0) {
+            return;
+        }
+        this.leadingBuffer.push(frame);
+        if (this.leadingBuffer.length > this.maxLeadingSilence) {
+            this.leadingBuffer.shift();
+        }
+    }
+    startToken(frame) {
+        const leading = this.leadingBuffer;
+        this.leadingBuffer = [];
+        this.initCount = 1;
+        this.silenceLength = 0;
+        this.startFrame = this.currentFrame - leading.length;
+        this.data = [...leading, frame];
+    }
+    process(frame) {
+        const frameIsValid = this.isValid(frame);
+        if (this.state === SILENCE) {
+            if (frameIsValid) {
+                // seems we got a valid frame after a silence
+                this.startToken(frame);
+                if (this.initCount >= this.initMin) {
+                    this.state = NOISE;
+                    if (this.data.length >= this.maxLength) {
+                        return this.processEndOfDetection(true);
+                    }
+                }
+                else {
+                    this.state = POSSIBLE_NOISE;
+                }
+            }
+            else {
+                this.pushLeading(frame);
+            }
+            return undefined;
+        }
+        if (this.state === POSSIBLE_NOISE) {
+            if (frameIsValid) {
+                this.silenceLength = 0;
+                this.initCount += 1;
+                this.data.push(frame);
+                if (this.initCount >= this.initMin) {
+                    this.state = NOISE;
+                    if (this.data.length >= this.maxLength) {
+                        return this.processEndOfDetection(true);
+                    }
+                }
+            }
+            else {
+                this.silenceLength += 1;
+                if (this.silenceLength > this.initMaxSilence ||
+                    this.data.length + 1 >= this.maxLength) {
+                    // either initMaxSilence or maxLength is reached before
+                    // initCount, back to silence
+                    this.data = [];
+                    this.state = SILENCE;
+                }
+                else {
+                    this.data.push(frame);
+                }
+            }
+            return undefined;
+        }
+        if (this.state === NOISE) {
+            if (frameIsValid) {
+                this.data.push(frame);
+                if (this.data.length >= this.maxLength) {
+                    return this.processEndOfDetection(true);
+                }
+            }
+            else if (this.maxContinuousSilence <= 0) {
+                if (this.needsTrailingExtension) {
+                    this.data.push(frame);
+                    this.silenceLength = 1;
+                    this.state = TRAILING_COLLECTION;
+                    if (this.data.length >= this.maxLength) {
+                        this.state = SILENCE;
+                        return this.processEndOfDetection();
+                    }
+                }
+                else {
+                    this.state = SILENCE;
+                    const token = this.processEndOfDetection();
+                    this.pushLeading(frame);
+                    return token;
+                }
+            }
+            else {
+                // this is the first silent frame following a valid one and it
+                // is tolerated
+                this.silenceLength = 1;
+                this.data.push(frame);
+                this.state = POSSIBLE_SILENCE;
+                if (this.data.length === this.maxLength) {
+                    return this.processEndOfDetection(true);
+                    // don't reset silenceLength because we still need to know
+                    // the total number of silent frames
+                }
+            }
+            return undefined;
+        }
+        if (this.state === POSSIBLE_SILENCE) {
+            if (frameIsValid) {
+                this.data.push(frame);
+                this.silenceLength = 0;
+                this.state = NOISE;
+                if (this.data.length >= this.maxLength) {
+                    return this.processEndOfDetection(true);
+                }
+            }
+            else {
+                if (this.silenceLength >= this.maxContinuousSilence) {
+                    if (this.needsTrailingExtension &&
+                        this.silenceLength < this.data.length) {
+                        // continue collecting trailing beyond maxContinuousSilence
+                        this.data.push(frame);
+                        this.silenceLength += 1;
+                        this.state = TRAILING_COLLECTION;
+                        if (this.silenceLength >= this.maxTrailingSilence ||
+                            this.data.length >= this.maxLength) {
+                            this.state = SILENCE;
+                            return this.processEndOfDetection();
+                        }
+                    }
+                    else {
+                        this.state = SILENCE;
+                        if (this.silenceLength < this.data.length) {
+                            const token = this.processEndOfDetection();
+                            this.pushLeading(frame);
+                            return token;
+                        }
+                        this.data = [];
+                        this.silenceLength = 0;
+                        this.pushLeading(frame);
+                    }
+                }
+                else {
+                    this.data.push(frame);
+                    this.silenceLength += 1;
+                    if (this.data.length >= this.maxLength) {
+                        return this.processEndOfDetection(true);
+                        // don't reset silenceLength because we still need to know
+                        // the total number of silent frames
+                    }
+                }
+            }
+            return undefined;
+        }
+        // state === TRAILING_COLLECTION
+        if (frameIsValid) {
+            // event is over: deliver with collected trailing, then start a
+            // new token from this valid frame
+            const token = this.processEndOfDetection();
+            this.startToken(frame);
+            this.state = this.initCount >= this.initMin ? NOISE : POSSIBLE_NOISE;
+            return token;
+        }
+        this.data.push(frame);
+        this.silenceLength += 1;
+        if (this.silenceLength >= this.maxTrailingSilence ||
+            this.data.length >= this.maxLength) {
+            this.state = SILENCE;
+            return this.processEndOfDetection();
+        }
+        return undefined;
+    }
+    postProcess() {
+        if (this.state === NOISE ||
+            this.state === POSSIBLE_SILENCE ||
+            this.state === TRAILING_COLLECTION) {
+            if (this.data.length > 0 && this.data.length > this.silenceLength) {
+                return this.processEndOfDetection();
+            }
+        }
+        return undefined;
+    }
+    processEndOfDetection(truncated = false) {
+        if (!truncated &&
+            this.maxTrailingSilence !== null &&
+            this.silenceLength > this.maxTrailingSilence) {
+            // Trim trailing silence beyond the allowed amount. Happens if
+            // maxContinuousSilence is reached or maxLength is reached at a
+            // silent frame. Trimmed frames are seeded into the leading
+            // buffer so they can become leading silence for the next token.
+            const excess = this.silenceLength - this.maxTrailingSilence;
+            const trimStart = Math.max(0, this.data.length - excess);
+            const trimmed = this.data.splice(trimStart);
+            for (const frame of trimmed) {
+                this.pushLeading(frame);
+            }
+        }
+        if (this.data.length >= this.minLength ||
+            (this.data.length > 0 && !this.strictMinLength && this.contiguousToken)) {
+            const token = {
+                frames: this.data,
+                start: this.startFrame,
+                end: this.startFrame + this.data.length - 1,
+            };
+            this.data = [];
+            if (truncated) {
+                // next token (if any) will start at currentFrame + 1 and is
+                // contiguous with the just delivered one
+                this.startFrame = this.currentFrame + 1;
+                this.contiguousToken = true;
+            }
+            else {
+                this.contiguousToken = false;
+            }
+            return token;
+        }
+        this.contiguousToken = false;
+        this.data = [];
+        return undefined;
+    }
+}

package/dist/wav.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Environment-free WAV (RIFF) codec: works in Node and in the browser
+ * without an AudioContext. Decodes PCM 8/16/24/32-bit integer and
+ * 32-bit IEEE float (including WAVE_FORMAT_EXTENSIBLE); encodes 16-bit
+ * PCM or 32-bit float.
+ */
+export interface DecodedAudio {
+    channelData: Float32Array[];
+    sampleRate: number;
+}
+/** True if `data` starts with a RIFF/WAVE header. */
+export declare function isWav(data: Uint8Array | ArrayBuffer): boolean;
+/** Decode a WAV file into planar Float32Array channels in [-1, 1]. */
+export declare function decodeWav(data: Uint8Array | ArrayBuffer): DecodedAudio;
+export interface WavEncodeOptions {
+    /** 16 (PCM, default) or "float32" (IEEE float). */
+    bitDepth?: 16 | "float32";
+}
+/** Encode planar Float32Array channels as a WAV file. */
+export declare function encodeWav(audio: {
+    channelData: readonly Float32Array[];
+    sampleRate: number;
+}, options?: WavEncodeOptions): Uint8Array;

package/dist/wav.js

@@ -0,0 +1,141 @@
+/**
+ * Environment-free WAV (RIFF) codec: works in Node and in the browser
+ * without an AudioContext. Decodes PCM 8/16/24/32-bit integer and
+ * 32-bit IEEE float (including WAVE_FORMAT_EXTENSIBLE); encodes 16-bit
+ * PCM or 32-bit float.
+ */
+const WAVE_FORMAT_PCM = 1;
+const WAVE_FORMAT_IEEE_FLOAT = 3;
+const WAVE_FORMAT_EXTENSIBLE = 0xfffe;
+function toDataView(data) {
+    if (data instanceof ArrayBuffer) {
+        return new DataView(data);
+    }
+    return new DataView(data.buffer, data.byteOffset, data.byteLength);
+}
+/** True if `data` starts with a RIFF/WAVE header. */
+export function isWav(data) {
+    const view = toDataView(data);
+    return (view.byteLength >= 12 &&
+        view.getUint32(0, false) === 0x52494646 && // "RIFF"
+        view.getUint32(8, false) === 0x57415645 // "WAVE"
+    );
+}
+/** Decode a WAV file into planar Float32Array channels in [-1, 1]. */
+export function decodeWav(data) {
+    const view = toDataView(data);
+    if (!isWav(data)) {
+        throw new Error("not a RIFF/WAVE file");
+    }
+    let format = 0;
+    let channels = 0;
+    let sampleRate = 0;
+    let bitsPerSample = 0;
+    let dataOffset = -1;
+    let dataLength = 0;
+    let offset = 12;
+    while (offset + 8 <= view.byteLength) {
+        const chunkId = view.getUint32(offset, false);
+        const chunkSize = view.getUint32(offset + 4, true);
+        const body = offset + 8;
+        if (chunkId === 0x666d7420) {
+            // "fmt "
+            format = view.getUint16(body, true);
+            channels = view.getUint16(body + 2, true);
+            sampleRate = view.getUint32(body + 4, true);
+            bitsPerSample = view.getUint16(body + 14, true);
+            if (format === WAVE_FORMAT_EXTENSIBLE && chunkSize >= 40) {
+                // sub-format GUID starts with the actual format code
+                format = view.getUint16(body + 24, true);
+            }
+        }
+        else if (chunkId === 0x64617461) {
+            // "data"
+            dataOffset = body;
+            dataLength = Math.min(chunkSize, view.byteLength - body);
+        }
+        offset = body + chunkSize + (chunkSize % 2); // chunks are word-aligned
+    }
+    if (channels === 0 || sampleRate === 0) {
+        throw new Error("invalid WAV file: no fmt chunk");
+    }
+    if (dataOffset < 0) {
+        throw new Error("invalid WAV file: no data chunk");
+    }
+    const bytesPerSample = bitsPerSample / 8;
+    if (!((format === WAVE_FORMAT_PCM && [8, 16, 24, 32].includes(bitsPerSample)) ||
+        (format === WAVE_FORMAT_IEEE_FLOAT && bitsPerSample === 32))) {
+        throw new Error(`unsupported WAV format: format code ${format}, ` +
+            `${bitsPerSample} bits per sample`);
+    }
+    const frameCount = Math.floor(dataLength / (bytesPerSample * channels));
+    const channelData = Array.from({ length: channels }, () => new Float32Array(frameCount));
+    for (let i = 0; i < frameCount; i++) {
+        for (let c = 0; c < channels; c++) {
+            const at = dataOffset + (i * channels + c) * bytesPerSample;
+            let value;
+            if (format === WAVE_FORMAT_IEEE_FLOAT) {
+                value = view.getFloat32(at, true);
+            }
+            else if (bitsPerSample === 8) {
+                value = (view.getUint8(at) - 128) / 128;
+            }
+            else if (bitsPerSample === 16) {
+                value = view.getInt16(at, true) / 32768;
+            }
+            else if (bitsPerSample === 24) {
+                const raw = view.getUint8(at) |
+                    (view.getUint8(at + 1) << 8) |
+                    (view.getInt8(at + 2) << 16);
+                value = raw / 8388608;
+            }
+            else {
+                value = view.getInt32(at, true) / 2147483648;
+            }
+            channelData[c][i] = value;
+        }
+    }
+    return { channelData, sampleRate };
+}
+/** Encode planar Float32Array channels as a WAV file. */
+export function encodeWav(audio, options = {}) {
+    const { channelData, sampleRate } = audio;
+    const bitDepth = options.bitDepth ?? 16;
+    const float = bitDepth === "float32";
+    const bytesPerSample = float ? 4 : 2;
+    const channels = channelData.length;
+    const frameCount = channelData[0]?.length ?? 0;
+    const dataSize = frameCount * channels * bytesPerSample;
+    const buffer = new ArrayBuffer(44 + dataSize);
+    const view = new DataView(buffer);
+    view.setUint32(0, 0x52494646, false); // "RIFF"
+    view.setUint32(4, 36 + dataSize, true);
+    view.setUint32(8, 0x57415645, false); // "WAVE"
+    view.setUint32(12, 0x666d7420, false); // "fmt "
+    view.setUint32(16, 16, true);
+    view.setUint16(20, float ? WAVE_FORMAT_IEEE_FLOAT : WAVE_FORMAT_PCM, true);
+    view.setUint16(22, channels, true);
+    view.setUint32(24, sampleRate, true);
+    view.setUint32(28, sampleRate * channels * bytesPerSample, true);
+    view.setUint16(32, channels * bytesPerSample, true);
+    view.setUint16(34, float ? 32 : 16, true);
+    view.setUint32(36, 0x64617461, false); // "data"
+    view.setUint32(40, dataSize, true);
+    let at = 44;
+    for (let i = 0; i < frameCount; i++) {
+        for (let c = 0; c < channels; c++) {
+            const value = channelData[c][i];
+            if (float) {
+                view.setFloat32(at, value, true);
+            }
+            else {
+                // symmetric scale, clamped to the int16 range: values on the
+                // int16 grid (v / 32768) roundtrip exactly
+                const scaled = Math.round(value * 32768);
+                view.setInt16(at, Math.max(-32768, Math.min(32767, scaled)), true);
+            }
+            at += bytesPerSample;
+        }
+    }
+    return new Uint8Array(buffer);
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "auditok",
+  "version": "0.1.0",
+  "description": "Audio activity detection and segmentation: turn audio into events with min/max duration and silence semantics. JavaScript port of the Python auditok package. Zero dependencies.",
+  "keywords": [
+    "audio",
+    "vad",
+    "voice-activity-detection",
+    "audio-activity-detection",
+    "segmentation",
+    "silence-detection",
+    "silence-removal",
+    "speech",
+    "tokenizer",
+    "webaudio"
+  ],
+  "author": "Amine Sehili <amine.sehili@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amsehili/auditok.js.git"
+  },
+  "homepage": "https://github.com/amsehili/auditok.js",
+  "bugs": {
+    "url": "https://github.com/amsehili/auditok.js/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/browser/index.d.ts",
+        "default": "./dist/browser/index.js"
+      },
+      "node": {
+        "types": "./dist/node/index.d.ts",
+        "default": "./dist/node/index.js"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./core": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:webrtcvad": "tsc -p webrtcvad/tsconfig.json",
+    "test": "vitest run",
+    "demo:lib": "npm run build && npm run build:webrtcvad && rm -rf docs/lib && mkdir -p docs/lib/browser docs/lib/webrtcvad && cp dist/*.js docs/lib/ && cp dist/browser/*.js docs/lib/browser/ && cp webrtcvad/dist/*.js docs/lib/webrtcvad/",
+    "demo:serve": "npx serve docs",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^18.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.7"
+  }
+}