@jadujoel/web-audio-clip-node 0.1.7 → 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/esm-bundler/node_modules/@jadujoel/web-audio-clip-node/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joel Löf
+
+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/examples/esm-bundler/node_modules/@jadujoel/web-audio-clip-node/README.md

@@ -0,0 +1,197 @@
+# @jadujoel/web-audio-clip-node
+
+AudioWorklet clip playback for the Web Audio API with pause/resume, reusable start, buffer hot-swap, loop callbacks, loop crossfade, real-time sample playhead control, and sample-accurate fades — without extra nodes.
+
+Live demo: https://jadujoel.github.io/web-audio-clip-node/
+
+## Why this library
+
+`AudioBufferSourceNode` is good at one-shot playback, but it does not give you some things clip-based apps usually need:
+
+- **Pause and resume** — `AudioBufferSourceNode` has no pause; you must stop and recreate
+- **Reusable start** — call `start()` again after `stop()` without creating a new node
+- **Buffer hot-swap** — assign a new `AudioBuffer` to a playing node and it switches seamlessly
+- **Loop callback** when the playhead wraps (`onlooped`)
+- **Loop crossfade** built into the source itself
+- **Real-time playhead** get/set access in samples
+- **Sample-accurate fade in / fade out** without wiring extra gain nodes around every source
+
+`ClipNode` is aimed at those missing pieces while staying small enough to drop into a plain browser app.
+
+## Try It Fast
+
+- Open the live playground: https://jadujoel.github.io/web-audio-clip-node/
+- Run all local examples from the repo root with `bun run examples`
+- Try the zero-install example in [examples/cdn-vanilla](examples/cdn-vanilla/)
+
+## Features
+
+- AudioWorklet-based clip playback with explicit transport control
+- **Pause / resume** and **reusable start** — no need to recreate the node after stopping
+- **Buffer hot-swap** — assign `clip.buffer` on a live node and it switches immediately
+- `onlooped` callback support so you can react when the clip wraps
+- Loop start, loop end, and loop crossfade on the node itself
+- Real-time playhead readback and sample-accurate seeking via `clip.playhead`
+- Sample-accurate fade in and fade out without external helper nodes
+- Playback rate from `-2` to `2`, including reverse playback
+- Detune, gain, stereo pan, highpass, and lowpass controls
+- Streaming buffer support for incremental writes
+- Optional React hooks and ready-made controls
+
+## Install
+
+```sh
+npm install @jadujoel/web-audio-clip-node
+```
+
+## Quick Start
+
+```ts
+import { ClipNode, getProcessorBlobUrl } from "@jadujoel/web-audio-clip-node";
+
+const ctx = new AudioContext();
+await ctx.audioWorklet.addModule(getProcessorBlobUrl());
+
+const clip = new ClipNode(ctx);
+clip.connect(ctx.destination);
+
+const response = await fetch("/audio/clip.opus");
+const buffer = await ctx.decodeAudioData(await response.arrayBuffer());
+
+clip.buffer = buffer;
+clip.loop = true;
+clip.loopStart = 0.5;
+clip.loopEnd = 1.75;
+clip.loopCrossfade = 0.04;
+clip.fadeIn = 0.01;
+clip.fadeOut = 0.08;
+clip.onlooped = () => {
+  console.log("looped at sample", clip.playhead);
+};
+
+clip.playbackRate.value = 1;
+clip.playhead = 24_000;
+clip.start();
+```
+
+`clip.playhead` is read and written in samples, so you can scrub to an exact frame position while playback is active.
+
+## React Quick Start
+
+```tsx
+import {
+  GainControl,
+  PlaybackRateControl,
+  TransportButtons,
+  useClipControls,
+  useClipNode,
+} from "@jadujoel/web-audio-clip-node/react";
+import "@jadujoel/web-audio-clip-node/styles.css";
+
+function Player() {
+  const controls = useClipControls();
+  const clip = useClipNode({
+    values: controls.values,
+    enabled: controls.enabled,
+    loop: controls.loop,
+    setValue: controls.setValue,
+  });
+
+  return (
+    <>
+      <TransportButtons
+        nodeState={clip.nodeState}
+        onStart={clip.start}
+        onStop={clip.stop}
+        onPause={clip.pause}
+        onResume={clip.resume}
+        onDispose={clip.dispose}
+        onLog={clip.logState}
+        onLoadSound={clip.loadSound}
+      />
+      <PlaybackRateControl
+        value={controls.values.playbackRate}
+        defaultValue={1}
+        enabled={controls.enabled.playbackRate}
+        onChange={(value) => {
+          controls.setValue("playbackRate", value);
+          clip.applyValue("playbackRate", value);
+        }}
+        onToggle={(enabled) => {
+          controls.setEnabled("playbackRate", enabled);
+          clip.applyToggle("playbackRate", enabled);
+        }}
+      />
+      <GainControl
+        value={controls.values.gain}
+        defaultValue={0}
+        enabled={controls.enabled.gain}
+        onChange={(value) => {
+          controls.setValue("gain", value);
+          clip.applyValue("gain", value);
+        }}
+        onToggle={(enabled) => {
+          controls.setEnabled("gain", enabled);
+          clip.applyToggle("gain", enabled);
+        }}
+      />
+    </>
+  );
+}
+```
+
+## CDN Usage
+
+Use the bundled entry point when you want a single browser import and load the processor from jsDelivr with `getProcessorCdnUrl()`.
+
+```html
+<script type="module">
+  import {
+    ClipNode,
+    getProcessorCdnUrl,
+  } from "https://cdn.jsdelivr.net/npm/@jadujoel/web-audio-clip-node@0.1.6/dist/lib.bundle.js";
+
+  const ctx = new AudioContext();
+  await ctx.audioWorklet.addModule(getProcessorCdnUrl("0.1.6"));
+
+  const clip = new ClipNode(ctx);
+  clip.connect(ctx.destination);
+</script>
+```
+
+The full no-bundler demo lives in [examples/cdn-vanilla](examples/cdn-vanilla/).
+
+That demo foregrounds the non-standard capabilities: pause/resume, restarting without recreating the node, buffer hot-swap, loop count callbacks, loop crossfade, and direct playhead seeking in samples.
+
+## Processor Loading Options
+
+| Method | Function | Use case |
+|--------|----------|----------|
+| Blob URL | `getProcessorBlobUrl()` | Default for package consumers who want zero setup |
+| CDN | `getProcessorCdnUrl("0.1.6")` | Plain browser usage via jsDelivr |
+| Self-hosted | `getProcessorModuleUrl(baseUrl)` | You serve `processor.js` from your own app |
+
+## Entry Points
+
+| Entry point | Import path | Contents |
+|-------------|-------------|----------|
+| Core | `@jadujoel/web-audio-clip-node` | `ClipNode`, types, utilities, controls, processor kernel |
+| Bundle | `@jadujoel/web-audio-clip-node/bundle` | Single-file ESM bundle for CDN or browser module usage |
+| React | `@jadujoel/web-audio-clip-node/react` | Store, hooks, and UI components |
+| Processor | `@jadujoel/web-audio-clip-node/processor` | Standalone worklet script |
+| Styles | `@jadujoel/web-audio-clip-node/styles.css` | CSS for the React components |
+
+## Examples
+
+The [examples](examples/) directory covers the main integration styles.
+
+| Example | Description | Build step? |
+|---------|-------------|-------------|
+| [cdn-vanilla](examples/cdn-vanilla/) | Single HTML file using the CDN bundle and processor URL | No |
+| [esm-bundler](examples/esm-bundler/) | Vite + TypeScript app importing the package directly | Yes |
+| [react](examples/react/) | Vite + React with the included hooks and controls | Yes |
+| [self-hosted](examples/self-hosted/) | Vite app serving `processor.js` locally via `getProcessorModuleUrl()` | Yes |
+
+## License
+
+MIT

package/examples/esm-bundler/node_modules/@jadujoel/web-audio-clip-node/dist/App.d.ts

@@ -0,0 +1,6 @@
+import { useClipNode } from "./hooks/useClipNode";
+interface AppProps {
+    useClipNodeImpl?: typeof useClipNode;
+}
+export declare function App({ useClipNodeImpl }?: AppProps): import("react/jsx-runtime").JSX.Element;
+export {};