@jadujoel/web-audio-clip-node 0.1.6 → 0.1.8

package/dist/workers/webm-opus-parser.js

@@ -0,0 +1,369 @@
+import { createFallbackOpusHead, parseOpusHead, } from "./opus-worker-common.js";
+const EMPTY_BYTES = new Uint8Array(0);
+const UTF8_DECODER = new TextDecoder();
+const ASCII_DECODER = new TextDecoder("ascii");
+const WEBM_ELEMENTS = new Map([
+    [0x1a45dfa3, { name: "EBML", type: "m" }],
+    [0x18538067, { name: "Segment", type: "m" }],
+    [0x114d9b74, { name: "SeekHead", type: "m" }],
+    [0x1549a966, { name: "Info", type: "m" }],
+    [0x1654ae6b, { name: "Tracks", type: "m" }],
+    [0x1f43b675, { name: "Cluster", type: "m" }],
+    [0x1c53bb6b, { name: "Cues", type: "m" }],
+    [0xae, { name: "TrackEntry", type: "m" }],
+    [0xe1, { name: "Audio", type: "m" }],
+    [0x2ad7b1, { name: "TimestampScale", type: "u" }],
+    [0xe7, { name: "Timestamp", type: "u" }],
+    [0xd7, { name: "TrackNumber", type: "u" }],
+    [0x83, { name: "TrackType", type: "u" }],
+    [0x86, { name: "CodecID", type: "s" }],
+    [0x63a2, { name: "CodecPrivate", type: "b" }],
+    [0x56aa, { name: "CodecDelay", type: "u" }],
+    [0x9f, { name: "Channels", type: "u" }],
+    [0xa3, { name: "SimpleBlock", type: "b" }],
+    [0xa1, { name: "Block", type: "b" }],
+]);
+export function createWebmOpusParserState() {
+    return {
+        timestampScaleNs: 1_000_000,
+        clusterTimestamp: 0,
+        currentTrack: null,
+        activeTrack: null,
+        inAudio: false,
+        buffer: EMPTY_BYTES,
+        byteOffset: 0,
+        elementStack: [],
+    };
+}
+function concatBytes(left, right) {
+    if (left.length === 0)
+        return right;
+    if (right.length === 0)
+        return left;
+    const combined = new Uint8Array(left.length + right.length);
+    combined.set(left, 0);
+    combined.set(right, left.length);
+    return combined;
+}
+function toUint8Array(bytes) {
+    return new Uint8Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+}
+function readEbmlId(bytes, offset) {
+    if (offset >= bytes.length)
+        return null;
+    const firstByte = bytes[offset];
+    if (firstByte === 0)
+        return null;
+    let length = 1;
+    while (length <= 4 && (firstByte & (1 << (8 - length))) === 0) {
+        length += 1;
+    }
+    if (length > 4 || offset + length > bytes.length)
+        return null;
+    let value = 0;
+    for (let index = 0; index < length; index++) {
+        value = (value << 8) | (bytes[offset + index] ?? 0);
+    }
+    return { length, value };
+}
+function readVint(bytes, offset, signed = false) {
+    if (offset >= bytes.length)
+        return null;
+    const firstByte = bytes[offset];
+    if (firstByte === 0)
+        return null;
+    let length = 1;
+    while (length <= 8 && (firstByte & (1 << (8 - length))) === 0) {
+        length += 1;
+    }
+    if (length > 8 || offset + length > bytes.length)
+        return null;
+    let value = firstByte & ((1 << (8 - length)) - 1);
+    for (let index = 1; index < length; index++) {
+        value = value * 256 + (bytes[offset + index] ?? 0);
+    }
+    const maxValue = 2 ** (7 * length) - 1;
+    if (!signed && value === maxValue) {
+        return { length, value: -1 };
+    }
+    if (signed) {
+        value -= 2 ** (7 * length - 1) - 1;
+    }
+    return { length, value };
+}
+function readUnsigned(bytes) {
+    let value = 0;
+    for (const byte of bytes) {
+        value = value * 256 + byte;
+    }
+    return value;
+}
+function decodeElementValue(info, data) {
+    if (info.type === "u") {
+        return {
+            name: info.name,
+            type: info.type,
+            value: readUnsigned(data),
+            data,
+        };
+    }
+    if (info.type === "s") {
+        return {
+            name: info.name,
+            type: info.type,
+            value: ASCII_DECODER.decode(data),
+            data,
+        };
+    }
+    if (info.type === "8") {
+        return {
+            name: info.name,
+            type: info.type,
+            value: UTF8_DECODER.decode(data),
+            data,
+        };
+    }
+    return { name: info.name, type: info.type, data };
+}
+function drainCompletedMasters(state, absoluteOffset, elements) {
+    while (state.elementStack.length > 0) {
+        const top = state.elementStack[state.elementStack.length - 1];
+        if (!top)
+            break;
+        if (top.end == null || absoluteOffset < top.end) {
+            break;
+        }
+        state.elementStack.pop();
+        elements.push({
+            name: top.name,
+            type: "m",
+            isEnd: true,
+            data: EMPTY_BYTES,
+        });
+    }
+}
+function parseBlockFrames(payload, lacing) {
+    if (lacing === 0) {
+        return [toUint8Array(payload)];
+    }
+    if (payload.length === 0) {
+        return [];
+    }
+    let cursor = 0;
+    const frameCount = (payload[cursor++] ?? 0) + 1;
+    const sizes = [];
+    if (lacing === 2) {
+        const size = Math.floor((payload.length - cursor) / frameCount);
+        for (let index = 0; index < frameCount; index++)
+            sizes.push(size);
+        return sizes.map((frameSize, index) => {
+            const start = cursor + index * frameSize;
+            return toUint8Array(payload.subarray(start, start + frameSize));
+        });
+    }
+    if (lacing === 1) {
+        let total = 0;
+        for (let index = 0; index < frameCount - 1; index++) {
+            let size = 0;
+            while (cursor < payload.length) {
+                const value = payload[cursor++] ?? 0;
+                size += value;
+                if (value !== 0xff)
+                    break;
+            }
+            sizes.push(size);
+            total += size;
+        }
+        sizes.push(payload.length - cursor - total);
+    }
+    else {
+        const firstSize = readVint(payload, cursor, false);
+        if (!firstSize)
+            return [];
+        cursor += firstSize.length;
+        sizes.push(firstSize.value);
+        let total = firstSize.value;
+        for (let index = 1; index < frameCount - 1; index++) {
+            const delta = readVint(payload, cursor, true);
+            if (!delta)
+                return [];
+            cursor += delta.length;
+            const nextSize = (sizes[index - 1] ?? 0) + delta.value;
+            sizes.push(nextSize);
+            total += nextSize;
+        }
+        sizes.push(payload.length - cursor - total);
+    }
+    const frames = [];
+    for (const size of sizes) {
+        frames.push(toUint8Array(payload.subarray(cursor, cursor + size)));
+        cursor += size;
+    }
+    return frames;
+}
+function parseBlock(data) {
+    const track = readVint(data, 0, false);
+    if (!track) {
+        throw new Error("Invalid WebM block: missing track number");
+    }
+    let cursor = track.length;
+    if (data.length < cursor + 3) {
+        throw new Error("Invalid WebM block: truncated header");
+    }
+    let timecode = ((data[cursor] ?? 0) << 8) | (data[cursor + 1] ?? 0);
+    if (timecode & 0x8000) {
+        timecode -= 0x10000;
+    }
+    cursor += 2;
+    const flags = data[cursor++] ?? 0;
+    const lacing = (flags >> 1) & 0x03;
+    const frames = parseBlockFrames(data.subarray(cursor), lacing);
+    return {
+        trackNumber: track.value,
+        timecode,
+        frames,
+    };
+}
+function parseWebmElements(chunk, state) {
+    state.buffer = concatBytes(state.buffer, chunk);
+    const elements = [];
+    let cursor = 0;
+    while (true) {
+        drainCompletedMasters(state, state.byteOffset + cursor, elements);
+        const id = readEbmlId(state.buffer, cursor);
+        if (!id)
+            break;
+        const size = readVint(state.buffer, cursor + id.length, false);
+        if (!size)
+            break;
+        const headerSize = id.length + size.length;
+        if (state.buffer.length < cursor + headerSize)
+            break;
+        const info = WEBM_ELEMENTS.get(id.value) ?? {
+            name: "unknown",
+            type: "b",
+        };
+        const dataSize = size.value;
+        const absoluteContentStart = state.byteOffset + cursor + headerSize;
+        cursor += headerSize;
+        if (info.type === "m") {
+            elements.push({
+                name: info.name,
+                type: "m",
+                isEnd: false,
+                data: EMPTY_BYTES,
+            });
+            state.elementStack.push({
+                name: info.name,
+                end: dataSize >= 0 ? absoluteContentStart + dataSize : null,
+            });
+            continue;
+        }
+        if (dataSize < 0 || state.buffer.length < cursor + dataSize) {
+            cursor -= headerSize;
+            break;
+        }
+        const data = toUint8Array(state.buffer.subarray(cursor, cursor + dataSize));
+        elements.push(decodeElementValue(info, data));
+        cursor += dataSize;
+    }
+    state.byteOffset += cursor;
+    state.buffer = toUint8Array(state.buffer.subarray(cursor));
+    drainCompletedMasters(state, state.byteOffset, elements);
+    return elements;
+}
+export function processWebmOpusElements(elements, state) {
+    const packets = [];
+    let head = null;
+    for (const element of elements) {
+        if (element.type === "m") {
+            if (!element.isEnd) {
+                if (element.name === "TrackEntry") {
+                    state.currentTrack = {};
+                }
+                else if (element.name === "Audio") {
+                    state.inAudio = true;
+                }
+            }
+            else {
+                if (element.name === "TrackEntry") {
+                    if (state.activeTrack == null &&
+                        state.currentTrack?.trackType === 2 &&
+                        state.currentTrack.codecId === "A_OPUS" &&
+                        state.currentTrack.trackNumber != null) {
+                        const channels = state.currentTrack.channels ?? 2;
+                        const codecPrivate = state.currentTrack.codecPrivate ?? null;
+                        state.activeTrack = {
+                            trackNumber: state.currentTrack.trackNumber,
+                            channels,
+                            codecPrivate,
+                            codecDelayNs: state.currentTrack.codecDelayNs ?? 0,
+                        };
+                        head =
+                            codecPrivate != null
+                                ? (parseOpusHead(codecPrivate) ??
+                                    createFallbackOpusHead(channels))
+                                : createFallbackOpusHead(channels);
+                    }
+                    state.currentTrack = null;
+                }
+                else if (element.name === "Audio") {
+                    state.inAudio = false;
+                }
+            }
+            continue;
+        }
+        if (element.name === "TimestampScale" || element.name === "TimecodeScale") {
+            state.timestampScaleNs = element.value;
+            continue;
+        }
+        if (element.name === "Timestamp" || element.name === "Timecode") {
+            state.clusterTimestamp = element.value;
+            continue;
+        }
+        if (state.currentTrack != null) {
+            switch (element.name) {
+                case "TrackNumber":
+                    state.currentTrack.trackNumber = element.value;
+                    continue;
+                case "TrackType":
+                    state.currentTrack.trackType = element.value;
+                    continue;
+                case "CodecID":
+                    state.currentTrack.codecId = element.value;
+                    continue;
+                case "CodecPrivate":
+                    state.currentTrack.codecPrivate = element.data;
+                    continue;
+                case "CodecDelay":
+                    state.currentTrack.codecDelayNs = element.value;
+                    continue;
+                case "Channels":
+                    if (state.inAudio) {
+                        state.currentTrack.channels = element.value;
+                    }
+                    continue;
+            }
+        }
+        if (state.activeTrack != null &&
+            (element.name === "SimpleBlock" || element.name === "Block")) {
+            const block = parseBlock(element.data);
+            if (block.trackNumber !== state.activeTrack.trackNumber) {
+                continue;
+            }
+            const baseTimestampUs = Math.max(0, Math.round(((state.clusterTimestamp + block.timecode) * state.timestampScaleNs -
+                state.activeTrack.codecDelayNs) /
+                1_000));
+            for (let index = 0; index < block.frames.length; index++) {
+                packets.push({
+                    packet: block.frames[index] ?? new Uint8Array(0),
+                    timestampUs: baseTimestampUs + index,
+                });
+            }
+        }
+    }
+    return { packets, head };
+}
+export function appendWebmOpusBytes(chunk, state) {
+    return processWebmOpusElements(parseWebmElements(chunk, state), state);
+}

package/dist/workers/worker-utils.d.ts

@@ -0,0 +1,11 @@
+export declare function concat(a: Uint8Array, b: Uint8Array): Uint8Array;
+interface EstimateTotalSamplesInput {
+    totalBytes: number | null;
+    bitrate: number | null;
+    sourceSampleRate: number;
+    targetSampleRate: number;
+}
+export declare function estimateTotalSamplesFromContentLength({ totalBytes, bitrate, sourceSampleRate, targetSampleRate, }: EstimateTotalSamplesInput): number | null;
+export declare function resampleChannel(src: Float32Array, srcRate: number, dstRate: number): Float32Array;
+export declare function createThrottleStream(bytesPerSec: number): TransformStream<Uint8Array, Uint8Array>;
+export {};

package/dist/workers/worker-utils.js

@@ -0,0 +1,55 @@
+export function concat(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a);
+    out.set(b, a.length);
+    return out;
+}
+const FALLBACK_BITRATE_BPS = 128_000;
+export function estimateTotalSamplesFromContentLength({ totalBytes, bitrate, sourceSampleRate, targetSampleRate, }) {
+    if (totalBytes == null || totalBytes <= 0)
+        return null;
+    if (sourceSampleRate <= 0 || targetSampleRate <= 0)
+        return null;
+    const safeBitrate = bitrate != null && Number.isFinite(bitrate) && bitrate > 0
+        ? bitrate
+        : FALLBACK_BITRATE_BPS;
+    const durationSeconds = (totalBytes * 8) / safeBitrate;
+    if (!Number.isFinite(durationSeconds) || durationSeconds <= 0)
+        return null;
+    const totalSamples = Math.ceil(durationSeconds * targetSampleRate);
+    return Number.isFinite(totalSamples) && totalSamples > 0
+        ? totalSamples
+        : null;
+}
+export function resampleChannel(src, srcRate, dstRate) {
+    if (srcRate === dstRate)
+        return src;
+    const ratio = srcRate / dstRate;
+    const dstLen = Math.round(src.length / ratio);
+    const dst = new Float32Array(dstLen);
+    for (let i = 0; i < dstLen; i++) {
+        const srcPos = i * ratio;
+        const idx = Math.floor(srcPos);
+        const frac = srcPos - idx;
+        const a = src[idx] ?? 0;
+        const b = src[Math.min(idx + 1, src.length - 1)] ?? 0;
+        dst[i] = a + frac * (b - a);
+    }
+    return dst;
+}
+export function createThrottleStream(bytesPerSec) {
+    let totalBytes = 0;
+    const startTime = performance.now();
+    return new TransformStream({
+        async transform(chunk, controller) {
+            totalBytes += chunk.length;
+            const elapsed = (performance.now() - startTime) / 1000;
+            const expected = totalBytes / bytesPerSec;
+            const delay = expected - elapsed;
+            if (delay > 0) {
+                await new Promise((resolve) => setTimeout(resolve, delay * 1000));
+            }
+            controller.enqueue(chunk);
+        },
+    });
+}

package/examples/README.md

@@ -1,10 +1,18 @@
 # Examples
 
-Each subdirectory demonstrates a different way to use `@jadujoel/web-audio-clip-node`.
+Each subdirectory demonstrates a different integration path for `@jadujoel/web-audio-clip-node`.
+
+From the repository root, run every example with:
+
+```sh
+bun run examples
+```
+
+That command builds the local package, links the examples that need it, and serves the demo entry points.
 
 | Example | Description | Build step? |
 |---------|-------------|-------------|
-| [cdn-vanilla](./cdn-vanilla/) | Pure HTML + `<script type="module">` via jsDelivr CDN | No |
-| [esm-bundler](./esm-bundler/) | Vite + TypeScript with `npm install` | Yes |
-| [react](./react/) | Vite + React using the built-in hooks & components | Yes |
+| [cdn-vanilla](./cdn-vanilla/) | Single HTML file using the jsDelivr bundle and a generated demo clip | No |
+| [esm-bundler](./esm-bundler/) | Vite + TypeScript importing the package directly | Yes |
+| [react](./react/) | Vite + React using the provided hooks and UI controls | Yes |
 | [self-hosted](./self-hosted/) | Vite + self-hosted `processor.js` via `getProcessorModuleUrl()` | Yes |

package/examples/cdn-vanilla/README.md

@@ -1,13 +1,17 @@
 # CDN Vanilla Example
 
-Zero-install example — serve `index.html` with any static file server.
+Single-file demo with no bundler and no local package install.
 
-Everything is loaded from [jsDelivr](https://www.jsdelivr.com/).
+Everything loads from [jsDelivr](https://www.jsdelivr.com/), including the worklet processor. The page synthesizes its own clip so you can see pause/resume, reusable `start()` without recreating the node, live buffer swapping, loop callbacks, loop crossfade, sample-accurate fades, pan, rate, detune, and live playhead seeking without fetching any assets.
 
-> **Note:** Opening the file directly (`file://`) won't work because browsers
-> treat `file:` URLs as unique security origins, blocking cross-origin module
-> imports.
+> **Note:** Opening the file directly with `file://` will not work because browsers treat local files as isolated origins and block the module/worklet loading path.
+
+Serve this directory with any static server, for example:
 
 ```sh
-bun index.html
+python3 -m http.server 4173
 ```
+
+Then open `http://localhost:4173`.
+
+If you are already in the repository root, `bun run examples` also serves this page.