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

package/examples/react/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/react/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 {};

package/examples/react/node_modules/@jadujoel/web-audio-clip-node/dist/App.js

@@ -0,0 +1,179 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useState } from "react";
+import { isTempoRelativeSnap, remapTempoRelativeValue } from "./audio/utils.js";
+import { ControlSection } from "./components/ControlSection.js";
+import { DetuneControl } from "./components/DetuneControl.js";
+import { DisplayPanel } from "./components/DisplayPanel.js";
+import { FilterControl } from "./components/FilterControl.js";
+import { GainControl } from "./components/GainControl.js";
+import { PanControl } from "./components/PanControl.js";
+import { PlaybackRateControl } from "./components/PlaybackRateControl.js";
+import { PlayheadSlider } from "./components/PlayheadSlider.js";
+import { TransportButtons } from "./components/TransportButtons.js";
+import { controlDefs, loopControlDefs } from "./controls/controlDefs.js";
+import { getActiveLinkedControls, getLinkedControlPairForControl, getLinkedControlUpdates, loopLinkedControlPairs, transportLinkedControlPairs, } from "./controls/linkedControlPairs.js";
+import { useClipNode } from "./hooks/useClipNode.js";
+import { useClipControls } from "./store/clipStore.js";
+function buildControlUpdates(keys, value) {
+    return Object.fromEntries(keys.map((key) => [key, value]));
+}
+export function App({ useClipNodeImpl = useClipNode } = {}) {
+    const controls = useClipControls();
+    const node = useClipNodeImpl({
+        values: controls.values,
+        enabled: controls.enabled,
+        loop: controls.loop,
+        setValue: controls.setValue,
+    });
+    const [tempoDraft, setTempoDraft] = useState(() => String(controls.tempo));
+    const [isEditingTempo, setIsEditingTempo] = useState(false);
+    // Persist audioDuration into maxs state for locked controls (for localStorage persistence)
+    useEffect(() => {
+        if (node.audioDuration == null)
+            return;
+        for (const key of Object.keys(controls.maxLocked)) {
+            if (controls.maxLocked[key]) {
+                controls.setMax(key, node.audioDuration);
+            }
+        }
+    }, [node.audioDuration, controls.maxLocked, controls.setMax]);
+    useEffect(() => {
+        if (isEditingTempo)
+            return;
+        setTempoDraft(String(controls.tempo));
+    }, [controls.tempo, isEditingTempo]);
+    const handleValueChange = useCallback((key, val) => {
+        const linkedPair = getLinkedControlPairForControl(key);
+        if (linkedPair && controls.linkedPairs[linkedPair.key]) {
+            const effectiveMaxs = { ...controls.maxs };
+            for (const linkedKey of linkedPair.controls) {
+                if (controls.maxLocked[linkedKey] && node.audioDuration != null) {
+                    effectiveMaxs[linkedKey] = node.audioDuration;
+                }
+            }
+            const nextValues = getLinkedControlUpdates({
+                pair: linkedPair,
+                changedKey: key,
+                nextValue: val,
+                values: controls.values,
+                mins: controls.mins,
+                maxs: effectiveMaxs,
+            });
+            controls.setValuesPartial(nextValues);
+            node.applyValues(nextValues);
+            return;
+        }
+        node.applyValue(key, val);
+    }, [
+        controls.linkedPairs,
+        controls.maxLocked,
+        controls.maxs,
+        controls.mins,
+        controls.setValuesPartial,
+        controls.values,
+        node.applyValue,
+        node.applyValues,
+        node.audioDuration,
+    ]);
+    const handleTempoChange = useCallback((nextTempo) => {
+        if (!Number.isFinite(nextTempo) || nextTempo <= 0)
+            return;
+        const previousTempo = controls.tempo;
+        if (nextTempo === previousTempo)
+            return;
+        const changedValues = {};
+        for (const key of Object.keys(controls.values)) {
+            const snap = controls.snaps[key];
+            if (!isTempoRelativeSnap(snap))
+                continue;
+            const effectiveMax = controls.maxLocked[key] && node.audioDuration != null
+                ? node.audioDuration
+                : controls.maxs[key];
+            const nextValue = remapTempoRelativeValue(controls.values[key], snap, previousTempo, nextTempo, controls.mins[key], effectiveMax);
+            if (nextValue !== controls.values[key]) {
+                changedValues[key] = nextValue;
+            }
+        }
+        controls.setTempoAndValues(nextTempo, changedValues);
+        node.applyValues(changedValues);
+    }, [
+        controls.maxLocked,
+        controls.maxs,
+        controls.mins,
+        controls.setTempoAndValues,
+        controls.snaps,
+        controls.tempo,
+        controls.values,
+        node.applyValues,
+        node.audioDuration,
+    ]);
+    const commitTempoDraft = useCallback(() => {
+        const nextTempo = Number(tempoDraft.trim());
+        setIsEditingTempo(false);
+        if (!Number.isFinite(nextTempo) || nextTempo <= 0) {
+            setTempoDraft(String(controls.tempo));
+            return;
+        }
+        handleTempoChange(nextTempo);
+        setTempoDraft(String(nextTempo));
+    }, [controls.tempo, handleTempoChange, tempoDraft]);
+    const handleSnapChange = useCallback((key, snap) => {
+        const linkedKeys = getActiveLinkedControls(key, controls.linkedPairs);
+        controls.setSnapsPartial(buildControlUpdates(linkedKeys, snap));
+    }, [controls.linkedPairs, controls.setSnapsPartial]);
+    const handleToggle = useCallback((key, on) => {
+        const linkedKeys = getActiveLinkedControls(key, controls.linkedPairs);
+        controls.setEnabledPartial(buildControlUpdates(linkedKeys, on));
+        for (const linkedKey of linkedKeys) {
+            node.applyToggle(linkedKey, on);
+        }
+    }, [controls.linkedPairs, controls.setEnabledPartial, node.applyToggle]);
+    const handleMinChange = useCallback((key, val) => {
+        const linkedKeys = getActiveLinkedControls(key, controls.linkedPairs);
+        controls.setMinsPartial(buildControlUpdates(linkedKeys, val));
+    }, [controls.linkedPairs, controls.setMinsPartial]);
+    const handleMaxChange = useCallback((key, val) => {
+        const linkedKeys = getActiveLinkedControls(key, controls.linkedPairs);
+        controls.setMaxsPartial(buildControlUpdates(linkedKeys, val));
+    }, [controls.linkedPairs, controls.setMaxsPartial]);
+    const handleLoopChange = useCallback((checked) => {
+        controls.setLoop(checked);
+        node.setLoopOnNode(checked);
+    }, [controls.setLoop, node.setLoopOnNode]);
+    const handleMaxLockedChange = useCallback((key, locked) => {
+        const linkedKeys = getActiveLinkedControls(key, controls.linkedPairs);
+        controls.setMaxLockedPartial(buildControlUpdates(linkedKeys, locked));
+        if (locked && node.audioDuration != null) {
+            controls.setMaxsPartial(buildControlUpdates(linkedKeys, node.audioDuration));
+        }
+    }, [
+        controls.linkedPairs,
+        controls.setMaxLockedPartial,
+        controls.setMaxsPartial,
+        node.audioDuration,
+    ]);
+    const handlePlayheadChange = useCallback((v) => handleValueChange("playhead", v), [handleValueChange]);
+    const handlePlaybackRateChange = useCallback((v) => handleValueChange("playbackRate", v), [handleValueChange]);
+    const handlePlaybackRateToggle = useCallback((on) => handleToggle("playbackRate", on), [handleToggle]);
+    const handleDetuneChange = useCallback((v) => handleValueChange("detune", v), [handleValueChange]);
+    const handleDetuneToggle = useCallback((on) => handleToggle("detune", on), [handleToggle]);
+    const handleGainChange = useCallback((v) => handleValueChange("gain", v), [handleValueChange]);
+    const handleGainToggle = useCallback((on) => handleToggle("gain", on), [handleToggle]);
+    const handlePanChange = useCallback((v) => handleValueChange("pan", v), [handleValueChange]);
+    const handlePanToggle = useCallback((on) => handleToggle("pan", on), [handleToggle]);
+    const handleLowpassChange = useCallback((v) => handleValueChange("lowpass", v), [handleValueChange]);
+    const handleLowpassToggle = useCallback((on) => handleToggle("lowpass", on), [handleToggle]);
+    const handleHighpassChange = useCallback((v) => handleValueChange("highpass", v), [handleValueChange]);
+    const handleHighpassToggle = useCallback((on) => handleToggle("highpass", on), [handleToggle]);
+    return (_jsxs("main", { children: [_jsx(DisplayPanel, { nodeState: node.nodeState, statusMessage: node.statusMessage, soundName: node.soundName, currentTime: node.infoCurrentTime, currentFrame: node.infoCurrentFrame, timesLooped: node.infoTimesLooped, latency: node.infoLatency, timeTaken: node.infoTimeTaken }), _jsx(TransportButtons, { nodeState: node.nodeState, onStart: node.start, onStop: node.stop, onPause: node.pause, onResume: node.resume, onDispose: node.dispose, onLog: node.logState, onLoadSound: node.loadSound }), _jsxs("fieldset", { className: "control-group tempo-group", children: [_jsx("legend", { children: "Tempo" }), _jsx("label", { htmlFor: "tempo", className: "tempo-label", children: "BPM" }), _jsx("input", { id: "tempo", type: "number", min: 20, max: 999, step: 1, value: tempoDraft, onFocus: () => setIsEditingTempo(true), onChange: (e) => setTempoDraft(e.target.value), onBlur: commitTempoDraft, onKeyDown: (e) => {
+                            if (e.key === "Enter") {
+                                commitTempoDraft();
+                                e.currentTarget.blur();
+                            }
+                            if (e.key === "Escape") {
+                                setIsEditingTempo(false);
+                                setTempoDraft(String(controls.tempo));
+                                e.currentTarget.blur();
+                            }
+                        }, style: { width: 70 } })] }), _jsx(PlayheadSlider, { value: controls.values.playhead, audioDuration: node.audioDuration, disabled: node.nodeState === "initial" || node.nodeState === "disposed", onChange: handlePlayheadChange }), _jsxs("section", { id: "controls", children: [_jsx(ControlSection, { legend: "Transport", defs: controlDefs, values: controls.values, snaps: controls.snaps, enabled: controls.enabled, mins: controls.mins, maxs: controls.maxs, maxLocked: controls.maxLocked, linked: controls.linkedPairs, linkedPairs: transportLinkedControlPairs, tempo: controls.tempo, audioDuration: node.audioDuration, onValueChange: handleValueChange, onToggle: handleToggle, onLinkedChange: controls.setLinkedPair, onSnapChange: handleSnapChange, onMinChange: handleMinChange, onMaxChange: handleMaxChange, onMaxLockedChange: handleMaxLockedChange }), _jsxs("fieldset", { className: "control-group", children: [_jsx("legend", { children: "Loop" }), _jsxs("div", { className: "loop-row", children: [_jsx("label", { htmlFor: "loop", children: "Loop" }), _jsx("input", { type: "checkbox", id: "loop", checked: controls.loop, onChange: (e) => handleLoopChange(e.target.checked) })] }), controls.loop && (_jsx(ControlSection, { legend: "Controls", defs: loopControlDefs, values: controls.values, snaps: controls.snaps, enabled: controls.enabled, mins: controls.mins, maxs: controls.maxs, maxLocked: controls.maxLocked, linked: controls.linkedPairs, linkedPairs: loopLinkedControlPairs, tempo: controls.tempo, audioDuration: node.audioDuration, onValueChange: handleValueChange, onToggle: handleToggle, onLinkedChange: controls.setLinkedPair, onSnapChange: handleSnapChange, onMinChange: handleMinChange, onMaxChange: handleMaxChange, onMaxLockedChange: handleMaxLockedChange }))] }), _jsxs("fieldset", { className: "control-group", children: [_jsx("legend", { children: "Parameters" }), _jsx(PlaybackRateControl, { value: controls.values.playbackRate, defaultValue: 1, enabled: controls.enabled.playbackRate, onChange: handlePlaybackRateChange, onToggle: handlePlaybackRateToggle }), _jsx(DetuneControl, { value: controls.values.detune, defaultValue: 0, enabled: controls.enabled.detune, onChange: handleDetuneChange, onToggle: handleDetuneToggle }), _jsx(GainControl, { value: controls.values.gain, defaultValue: 0, enabled: controls.enabled.gain, onChange: handleGainChange, onToggle: handleGainToggle }), _jsx(PanControl, { value: controls.values.pan, defaultValue: 0, enabled: controls.enabled.pan, onChange: handlePanChange, onToggle: handlePanToggle }), _jsx(FilterControl, { label: "Lowpass", controlKey: "lowpass", value: controls.values.lowpass, defaultValue: 16384, enabled: controls.enabled.lowpass, onChange: handleLowpassChange, onToggle: handleLowpassToggle }), _jsx(FilterControl, { label: "Highpass", controlKey: "highpass", value: controls.values.highpass, defaultValue: 32, enabled: controls.enabled.highpass, onChange: handleHighpassChange, onToggle: handleHighpassToggle })] })] })] }));
+}

package/examples/react/node_modules/@jadujoel/web-audio-clip-node/dist/audio/ClipNode.d.ts

@@ -0,0 +1,88 @@
+import type { ClipNodeState, ClipWorkletOptions, FrameData } from "./types";
+export declare class ClipNode extends AudioWorkletNode {
+    onscheduled?: () => void;
+    onstarted?: () => void;
+    onpaused?: () => void;
+    onresumed?: () => void;
+    onended?: () => void;
+    onlooped?: () => void;
+    onstopped?: () => void;
+    onframe?: (data: FrameData) => void;
+    ondisposed?: () => void;
+    onstatechange?: (state: ClipNodeState) => void;
+    private _buffer?;
+    private _loopStart;
+    private _loopEnd;
+    private _loop;
+    private _offset;
+    private _playhead;
+    private _fadeIn;
+    private _fadeOut;
+    private _loopCrossfade;
+    private _duration;
+    private _previousState;
+    private _bufferWriteCursor;
+    private _hasStreamingPort;
+    timesLooped: number;
+    state: ClipNodeState;
+    cpu: number;
+    constructor(context: BaseAudioContext, options?: ClipWorkletOptions);
+    private handleMessage;
+    private setState;
+    toggleGain(value?: boolean): void;
+    togglePlaybackRate(value?: boolean): void;
+    toggleDetune(value?: boolean): void;
+    togglePan(value?: boolean): void;
+    toggleHighpass(value?: boolean): void;
+    toggleLowpass(value?: boolean): void;
+    toggleFadeIn(value?: boolean): void;
+    toggleFadeOut(value?: boolean): void;
+    toggleLoopCrossfade(value?: boolean): void;
+    toggleLoopStart(value?: boolean): void;
+    toggleLoopEnd(value?: boolean): void;
+    logState(): void;
+    get buffer(): AudioBuffer | undefined;
+    set buffer(ab: AudioBuffer);
+    transferPort(port: MessagePort): void;
+    initializeBuffer(totalLength: number, channels: number, options?: {
+        streaming?: boolean;
+    }): void;
+    replaceBufferRange(startSample: number, channelData: Float32Array[], options?: {
+        totalLength?: number | null;
+        streamEnded?: boolean;
+    }): void;
+    appendBufferRange(channelData: Float32Array[], options?: {
+        totalLength?: number | null;
+        streamEnded?: boolean;
+    }): void;
+    finalizeBuffer(totalLength?: number): void;
+    start(when?: number, offset?: number, duration?: number): void;
+    stop(when?: number, initialDelay?: number): void;
+    pause(when?: number): void;
+    resume(when?: number): void;
+    get loop(): boolean;
+    set loop(value: boolean);
+    get loopStart(): number;
+    set loopStart(value: number);
+    get loopEnd(): number;
+    set loopEnd(value: number);
+    get duration(): number;
+    set duration(value: number);
+    get offset(): number;
+    set offset(value: number);
+    get playhead(): number;
+    set playhead(value: number);
+    get playbackRate(): AudioParam;
+    get detune(): AudioParam;
+    get highpass(): AudioParam;
+    get lowpass(): AudioParam;
+    get gain(): AudioParam;
+    get pan(): AudioParam;
+    get fadeIn(): number;
+    set fadeIn(value: number);
+    get fadeOut(): number;
+    set fadeOut(value: number);
+    get loopCrossfade(): number;
+    set loopCrossfade(value: number);
+    dispose(): void;
+}