@aelionsdk/audio 0.1.0-beta.1

package/dist/time-stretch.js

@@ -0,0 +1,180 @@
+function positiveInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`${name} must be a positive safe integer`);
+    }
+}
+function concat(left, right) {
+    if (left.length === 0)
+        return right.slice();
+    if (right.length === 0)
+        return left;
+    const result = new Float32Array(left.length + right.length);
+    result.set(left);
+    result.set(right, left.length);
+    return result;
+}
+/**
+ * Stateful deterministic synchronous overlap-add time stretch.
+ *
+ * Input can arrive in arbitrary chunks. Grains and correlation searches stay
+ * anchored to the complete stream, and only samples that can no longer be
+ * affected by a later grain are emitted. This makes adjacent offline mixer
+ * blocks continuous without retaining the whole source or output.
+ */
+export class StreamingPitchPreservingTimeStretch {
+    #inputFrames;
+    #outputFrames;
+    #channelCount;
+    #grainFrames;
+    #synthesisHop;
+    #searchRadius;
+    #maximumInputStart;
+    #accumulator;
+    #normalization;
+    #input = new Float32Array();
+    #inputStartFrame = 0;
+    #receivedFrames = 0;
+    #nextOutputStart = 0;
+    #previousGrain;
+    #sealed = false;
+    constructor(options) {
+        positiveInteger(options.inputFrames, 'inputFrames');
+        positiveInteger(options.outputFrames, 'outputFrames');
+        positiveInteger(options.channelCount, 'channelCount');
+        if (options.channelCount > 8)
+            throw new RangeError('channelCount must not exceed 8');
+        const requestedGrain = options.grainFrames ?? 1_024;
+        positiveInteger(requestedGrain, 'grainFrames');
+        this.#inputFrames = options.inputFrames;
+        this.#outputFrames = options.outputFrames;
+        this.#channelCount = options.channelCount;
+        this.#grainFrames = Math.min(options.inputFrames, requestedGrain);
+        this.#synthesisHop = Math.max(1, Math.floor(this.#grainFrames / 4));
+        this.#searchRadius = Math.min(256, this.#synthesisHop);
+        this.#maximumInputStart = Math.max(0, options.inputFrames - this.#grainFrames);
+        this.#accumulator = new Float32Array(this.#grainFrames * options.channelCount);
+        this.#normalization = new Float32Array(this.#grainFrames);
+    }
+    push(interleaved, final = false) {
+        if (this.#sealed)
+            throw new ReferenceError('Time stretch is sealed');
+        if (interleaved.length % this.#channelCount !== 0) {
+            throw new RangeError('PCM length must be divisible by channelCount');
+        }
+        const addedFrames = interleaved.length / this.#channelCount;
+        if (this.#receivedFrames + addedFrames > this.#inputFrames) {
+            throw new RangeError('Time stretch received more frames than declared');
+        }
+        this.#input = concat(this.#input, interleaved);
+        this.#receivedFrames += addedFrames;
+        if (final && this.#receivedFrames !== this.#inputFrames) {
+            throw new RangeError('Final time-stretch chunk does not complete inputFrames');
+        }
+        const emitted = [];
+        while (this.#nextOutputStart < this.#outputFrames) {
+            const expected = this.#expectedInputStart(this.#nextOutputStart);
+            const lastCandidate = Math.min(this.#maximumInputStart, expected + this.#searchRadius);
+            if (!final && lastCandidate + this.#grainFrames > this.#receivedFrames)
+                break;
+            const firstCandidate = Math.max(0, expected - this.#searchRadius);
+            let selected = expected;
+            if (this.#previousGrain !== undefined) {
+                let bestScore = Number.NEGATIVE_INFINITY;
+                for (let candidate = firstCandidate; candidate <= lastCandidate; candidate += 1) {
+                    let cross = 0;
+                    let previousEnergy = 0;
+                    let candidateEnergy = 0;
+                    const overlapFrames = this.#grainFrames - this.#synthesisHop;
+                    for (let frame = 0; frame < overlapFrames; frame += 1) {
+                        const previous = this.#previousGrain[(frame + this.#synthesisHop) * this.#channelCount] ?? 0;
+                        const next = this.#source(candidate + frame, 0);
+                        cross += previous * next;
+                        previousEnergy += previous * previous;
+                        candidateEnergy += next * next;
+                    }
+                    const score = cross / Math.sqrt(Math.max(Number.EPSILON, previousEnergy * candidateEnergy));
+                    if (score > bestScore) {
+                        bestScore = score;
+                        selected = candidate;
+                    }
+                }
+            }
+            const grain = new Float32Array(this.#grainFrames * this.#channelCount);
+            for (let frame = 0; frame < this.#grainFrames; frame += 1) {
+                const phase = (frame + 0.5) / this.#grainFrames;
+                const window = 0.5 - 0.5 * Math.cos(2 * Math.PI * phase);
+                this.#normalization[frame] = (this.#normalization[frame] ?? 0) + window;
+                for (let channel = 0; channel < this.#channelCount; channel += 1) {
+                    const sample = this.#source(selected + frame, channel);
+                    grain[frame * this.#channelCount + channel] = sample;
+                    const index = frame * this.#channelCount + channel;
+                    this.#accumulator[index] = (this.#accumulator[index] ?? 0) + sample * window;
+                }
+            }
+            this.#previousGrain = grain;
+            const emitFrames = Math.min(this.#synthesisHop, this.#outputFrames - this.#nextOutputStart);
+            for (let frame = 0; frame < emitFrames; frame += 1) {
+                const scale = this.#normalization[frame] ?? 0;
+                for (let channel = 0; channel < this.#channelCount; channel += 1) {
+                    const value = this.#accumulator[frame * this.#channelCount + channel] ?? 0;
+                    emitted.push(scale > 1e-6 ? value / scale : this.#source(selected + frame, channel));
+                }
+            }
+            this.#shiftAccumulator(this.#synthesisHop);
+            this.#nextOutputStart += this.#synthesisHop;
+            const nextMinimum = Math.max(0, this.#expectedInputStart(this.#nextOutputStart) - this.#searchRadius);
+            const discardFrames = Math.max(0, Math.min(this.#input.length / this.#channelCount, nextMinimum - this.#inputStartFrame));
+            if (discardFrames > 0) {
+                this.#input = this.#input.slice(discardFrames * this.#channelCount);
+                this.#inputStartFrame += discardFrames;
+            }
+        }
+        if (final) {
+            this.#sealed = true;
+            this.#input = new Float32Array();
+        }
+        return Float32Array.from(emitted);
+    }
+    #expectedInputStart(outputStart) {
+        return Math.max(0, Math.min(this.#maximumInputStart, Math.round((outputStart * this.#inputFrames) / this.#outputFrames)));
+    }
+    #source(frame, channel) {
+        const bounded = Math.max(0, Math.min(this.#receivedFrames - 1, frame));
+        const local = bounded - this.#inputStartFrame;
+        if (local < 0)
+            throw new Error('Time stretch discarded a required source grain');
+        return this.#input[local * this.#channelCount + channel] ?? 0;
+    }
+    #shiftAccumulator(frames) {
+        const retainedFrames = Math.max(0, this.#grainFrames - frames);
+        this.#accumulator.copyWithin(0, frames * this.#channelCount);
+        this.#accumulator.fill(0, retainedFrames * this.#channelCount);
+        this.#normalization.copyWithin(0, frames);
+        this.#normalization.fill(0, retainedFrames);
+    }
+}
+export function pitchPreservingTimeStretch(options) {
+    positiveInteger(options.inputFrames, 'inputFrames');
+    positiveInteger(options.outputFrames, 'outputFrames');
+    positiveInteger(options.channelCount, 'channelCount');
+    if (options.input.length !== options.inputFrames * options.channelCount) {
+        throw new RangeError('input length does not match inputFrames × channelCount');
+    }
+    let input = options.input;
+    if (options.reverse === true) {
+        input = new Float32Array(options.input.length);
+        for (let frame = 0; frame < options.inputFrames; frame += 1) {
+            for (let channel = 0; channel < options.channelCount; channel += 1) {
+                input[frame * options.channelCount + channel] =
+                    options.input[(options.inputFrames - 1 - frame) * options.channelCount + channel] ?? 0;
+            }
+        }
+    }
+    const processor = new StreamingPitchPreservingTimeStretch({
+        inputFrames: options.inputFrames,
+        outputFrames: options.outputFrames,
+        channelCount: options.channelCount,
+        ...(options.grainFrames === undefined ? {} : { grainFrames: options.grainFrames }),
+    });
+    return processor.push(input, true);
+}

package/dist/transferable-pcm-queue.d.ts

@@ -0,0 +1,30 @@
+export interface TransferablePcmQueueSnapshot {
+    readonly capacityFrames: number;
+    readonly queuedFrames: number;
+    readonly availableWriteFrames: number;
+    readonly submittedBlocks: number;
+    readonly acknowledgedBlocks: number;
+    readonly peakQueuedFrames: number;
+    readonly closed: boolean;
+}
+export interface TransferablePcmBlock {
+    readonly id: number;
+    readonly generation: number;
+    readonly frameCount: number;
+    readonly channelCount: number;
+    readonly samples: Float32Array<ArrayBuffer>;
+}
+/** Main-thread ownership and backpressure for the non-SAB AudioWorklet path. */
+export declare class TransferablePcmQueue {
+    #private;
+    readonly capacityFrames: number;
+    readonly channelCount: number;
+    constructor(capacityFrames: number, channelCount: number);
+    enqueue(input: Float32Array, generation: number): TransferablePcmBlock | undefined;
+    acknowledge(id: number): void;
+    flush(): void;
+    close(): void;
+    availableWriteFrames(): number;
+    snapshot(): TransferablePcmQueueSnapshot;
+}
+//# sourceMappingURL=transferable-pcm-queue.d.ts.map

package/dist/transferable-pcm-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transferable-pcm-queue.d.ts","sourceRoot":"","sources":["../src/transferable-pcm-queue.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC;CAC7C;AAED,gFAAgF;AAChF,qBAAa,oBAAoB;;aAUb,cAAc,EAAE,MAAM;aACtB,YAAY,EAAE,MAAM;gBADpB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM;IAU/B,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAoBlF,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAQ7B,KAAK,IAAI,IAAI;IAKb,KAAK,IAAI,IAAI;IAKb,oBAAoB,IAAI,MAAM;IAI9B,QAAQ,IAAI,4BAA4B;CAWhD"}

package/dist/transferable-pcm-queue.js

@@ -0,0 +1,73 @@
+/** Main-thread ownership and backpressure for the non-SAB AudioWorklet path. */
+export class TransferablePcmQueue {
+    capacityFrames;
+    channelCount;
+    #pending = new Map();
+    #nextId = 1;
+    #queuedFrames = 0;
+    #submittedBlocks = 0;
+    #acknowledgedBlocks = 0;
+    #peakQueuedFrames = 0;
+    #closed = false;
+    constructor(capacityFrames, channelCount) {
+        this.capacityFrames = capacityFrames;
+        this.channelCount = channelCount;
+        if (!Number.isSafeInteger(capacityFrames) || capacityFrames <= 0) {
+            throw new RangeError('Transferable PCM capacityFrames must be a positive safe integer');
+        }
+        if (!Number.isSafeInteger(channelCount) || channelCount <= 0) {
+            throw new RangeError('Transferable PCM channelCount must be a positive safe integer');
+        }
+    }
+    enqueue(input, generation) {
+        if (this.#closed)
+            return undefined;
+        if (input.length % this.channelCount !== 0) {
+            throw new RangeError('Interleaved PCM length must be divisible by channelCount');
+        }
+        if (!Number.isSafeInteger(generation) || generation < 0) {
+            throw new RangeError('PCM generation must be a non-negative safe integer');
+        }
+        const frameCount = input.length / this.channelCount;
+        if (frameCount <= 0 || frameCount > this.availableWriteFrames())
+            return undefined;
+        const id = this.#nextId;
+        this.#nextId += 1;
+        const samples = input.slice();
+        this.#pending.set(id, frameCount);
+        this.#queuedFrames += frameCount;
+        this.#submittedBlocks += 1;
+        this.#peakQueuedFrames = Math.max(this.#peakQueuedFrames, this.#queuedFrames);
+        return { id, generation, frameCount, channelCount: this.channelCount, samples };
+    }
+    acknowledge(id) {
+        const frames = this.#pending.get(id);
+        if (frames === undefined)
+            return;
+        this.#pending.delete(id);
+        this.#queuedFrames -= frames;
+        this.#acknowledgedBlocks += 1;
+    }
+    flush() {
+        this.#pending.clear();
+        this.#queuedFrames = 0;
+    }
+    close() {
+        this.#closed = true;
+        this.flush();
+    }
+    availableWriteFrames() {
+        return this.capacityFrames - this.#queuedFrames;
+    }
+    snapshot() {
+        return {
+            capacityFrames: this.capacityFrames,
+            queuedFrames: this.#queuedFrames,
+            availableWriteFrames: this.availableWriteFrames(),
+            submittedBlocks: this.#submittedBlocks,
+            acknowledgedBlocks: this.#acknowledgedBlocks,
+            peakQueuedFrames: this.#peakQueuedFrames,
+            closed: this.#closed,
+        };
+    }
+}

package/dist/transferable-worklet-clock.d.ts

@@ -0,0 +1,51 @@
+import type { Disposable } from '@aelionsdk/core';
+import { TransferablePcmQueue, type TransferablePcmQueueSnapshot } from './transferable-pcm-queue.js';
+export interface TransferableClockReport {
+    readonly currentFrame: number;
+    readonly currentTime: number;
+    readonly generation: number;
+    readonly playedFrames: number;
+    readonly underrunFrames: number;
+    readonly queuedBlocks: number;
+}
+export interface TransferableAudioClockOptions {
+    readonly context?: AudioContext;
+    /** Host-resolved module URL for non-Vite or CDN deployments. */
+    readonly moduleUrl?: string | URL;
+    /** Requested hardware context rate when the clock owns its AudioContext. */
+    readonly sampleRate?: number;
+    readonly capacityFrames?: number;
+    readonly channelCount?: number;
+    readonly reportEveryFrames?: number;
+}
+export declare class TransferableAudioWorkletClock implements Disposable {
+    #private;
+    readonly context: AudioContext;
+    readonly queue: TransferablePcmQueue;
+    constructor(options?: TransferableAudioClockOptions);
+    get disposed(): boolean;
+    get ownsContext(): boolean;
+    get generation(): number;
+    get lastReport(): TransferableClockReport | undefined;
+    initialize(reportEveryFrames?: number): Promise<void>;
+    start(): Promise<void>;
+    enqueueInterleaved(input: Float32Array): boolean;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    seek(timeUs: number): number;
+    nowUs(): number;
+    snapshot(): TransferablePcmQueueSnapshot;
+    dispose(): Promise<void>;
+}
+export type BrowserAudioClockSelection = {
+    readonly mode: 'shared-ring';
+    readonly reason: 'cross-origin-isolated';
+} | {
+    readonly mode: 'transferable-queue';
+    readonly reason: 'shared-array-buffer-unavailable';
+};
+export declare function selectBrowserAudioTransport(environment: {
+    readonly crossOriginIsolated: boolean;
+    readonly sharedArrayBufferAvailable: boolean;
+}): BrowserAudioClockSelection;
+//# sourceMappingURL=transferable-worklet-clock.d.ts.map

package/dist/transferable-worklet-clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transferable-worklet-clock.d.ts","sourceRoot":"","sources":["../src/transferable-worklet-clock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,OAAO,EACL,oBAAoB,EACpB,KAAK,4BAA4B,EAClC,MAAM,6BAA6B,CAAC;AAoBrC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC,gEAAgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,qBAAa,6BAA8B,YAAW,UAAU;;IAC9D,SAAgB,OAAO,EAAE,YAAY,CAAC;IACtC,SAAgB,KAAK,EAAE,oBAAoB,CAAC;gBAazB,OAAO,GAAE,6BAAkC;IAa9D,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAED,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED,IAAW,UAAU,IAAI,uBAAuB,GAAG,SAAS,CAE3D;IAEY,UAAU,CACrB,iBAAiB,SAA2C,GAC3D,OAAO,CAAC,IAAI,CAAC;IAwDH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO;IAkB1C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAY5B,KAAK,IAAI,MAAM;IAQf,QAAQ,IAAI,4BAA4B;IAIxC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAyBhC;AAED,MAAM,MAAM,0BAA0B,GAClC;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,iCAAiC,CAAA;CAAE,CAAC;AAEhG,wBAAgB,2BAA2B,CAAC,WAAW,EAAE;IACvD,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,0BAA0B,EAAE,OAAO,CAAC;CAC9C,GAAG,0BAA0B,CAI7B"}

package/dist/transferable-worklet-clock.js

@@ -0,0 +1,185 @@
+import { TransferablePcmQueue, } from './transferable-pcm-queue.js';
+async function withTimeout(promise, timeoutMs, operation) {
+    let timeoutId;
+    const timeout = new Promise((_resolve, reject) => {
+        timeoutId = globalThis.setTimeout(() => {
+            reject(new Error(`${operation} timed out after ${timeoutMs.toString()} ms`));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        if (timeoutId !== undefined)
+            globalThis.clearTimeout(timeoutId);
+    }
+}
+export class TransferableAudioWorkletClock {
+    context;
+    queue;
+    #ownsContext;
+    #node;
+    #initializeTask;
+    #disposeTask;
+    #disposed = false;
+    #lifecycleGeneration = 0;
+    #generation = 0;
+    #timelineOriginUs = 0;
+    #contextOriginTime;
+    #lastReport;
+    #moduleUrl;
+    constructor(options = {}) {
+        this.#moduleUrl =
+            options.moduleUrl ?? new URL('./pcm-message-player.worklet.js', import.meta.url);
+        this.context =
+            options.context ??
+                new AudioContext({ latencyHint: 'playback', sampleRate: options.sampleRate ?? 48_000 });
+        this.#ownsContext = options.context === undefined;
+        this.queue = new TransferablePcmQueue(options.capacityFrames ?? this.context.sampleRate * 4, options.channelCount ?? 2);
+    }
+    get disposed() {
+        return this.#disposed;
+    }
+    get ownsContext() {
+        return this.#ownsContext;
+    }
+    get generation() {
+        return this.#generation;
+    }
+    get lastReport() {
+        return this.#lastReport;
+    }
+    async initialize(reportEveryFrames = Math.round(this.context.sampleRate / 20)) {
+        if (this.#disposed)
+            throw new ReferenceError('TransferableAudioWorkletClock is disposed');
+        if (this.#node !== undefined)
+            return;
+        const existing = this.#initializeTask;
+        if (existing !== undefined)
+            return existing;
+        const generation = this.#lifecycleGeneration;
+        const task = this.#initialize(reportEveryFrames, generation).finally(() => {
+            if (this.#initializeTask === task)
+                this.#initializeTask = undefined;
+        });
+        this.#initializeTask = task;
+        return task;
+    }
+    async #initialize(reportEveryFrames, generation) {
+        await withTimeout(this.context.audioWorklet.addModule(this.#moduleUrl), 5_000, 'AudioWorklet module initialization');
+        this.#throwIfInitializationStale(generation);
+        const node = new AudioWorkletNode(this.context, 'aelion-message-pcm-player', {
+            numberOfInputs: 0,
+            numberOfOutputs: 1,
+            outputChannelCount: [this.queue.channelCount],
+            processorOptions: {
+                channelCount: this.queue.channelCount,
+                generation: this.#generation,
+                reportEveryFrames,
+            },
+        });
+        let connected = false;
+        try {
+            node.port.addEventListener('message', event => {
+                const value = event.data;
+                if (value === null || typeof value !== 'object')
+                    return;
+                const type = Reflect.get(value, 'type');
+                if (type === 'ack') {
+                    const id = Reflect.get(value, 'id');
+                    if (typeof id === 'number')
+                        this.queue.acknowledge(id);
+                }
+                else if (type === 'clock') {
+                    this.#lastReport = value;
+                }
+            });
+            node.port.start();
+            node.connect(this.context.destination);
+            connected = true;
+            this.#throwIfInitializationStale(generation);
+            this.#contextOriginTime = this.context.currentTime;
+            this.#node = node;
+        }
+        catch (error) {
+            if (connected)
+                node.disconnect();
+            node.port.close();
+            throw error;
+        }
+    }
+    async start() {
+        await this.initialize();
+        this.#node?.port.postMessage({ type: 'start', generation: this.#generation });
+        await this.context.resume();
+    }
+    enqueueInterleaved(input) {
+        if (this.#disposed)
+            throw new ReferenceError('TransferableAudioWorkletClock is disposed');
+        const block = this.queue.enqueue(input, this.#generation);
+        if (block === undefined)
+            return false;
+        this.#node?.port.postMessage({
+            type: 'block',
+            id: block.id,
+            generation: block.generation,
+            frameCount: block.frameCount,
+            channelCount: block.channelCount,
+            samples: block.samples,
+        }, [block.samples.buffer]);
+        return true;
+    }
+    async pause() {
+        if (this.context.state === 'running')
+            await this.context.suspend();
+    }
+    async resume() {
+        if (this.context.state !== 'running')
+            await this.context.resume();
+    }
+    seek(timeUs) {
+        if (!Number.isSafeInteger(timeUs) || timeUs < 0) {
+            throw new RangeError('Seek target must be a non-negative safe integer microsecond value');
+        }
+        this.#generation += 1;
+        this.#timelineOriginUs = timeUs;
+        this.#contextOriginTime = this.context.currentTime;
+        this.queue.flush();
+        this.#node?.port.postMessage({ type: 'seek', generation: this.#generation });
+        return this.#generation;
+    }
+    nowUs() {
+        const origin = this.#contextOriginTime ?? this.context.currentTime;
+        return (this.#timelineOriginUs +
+            Math.max(0, Math.round((this.context.currentTime - origin) * 1_000_000)));
+    }
+    snapshot() {
+        return this.queue.snapshot();
+    }
+    dispose() {
+        this.#disposeTask ??= this.#dispose();
+        return this.#disposeTask;
+    }
+    async #dispose() {
+        this.#disposed = true;
+        this.#lifecycleGeneration += 1;
+        this.queue.close();
+        this.#node?.port.postMessage({ type: 'close' });
+        this.#node?.disconnect();
+        this.#node?.port.close();
+        this.#node = undefined;
+        if (this.#ownsContext && this.context.state !== 'closed')
+            await this.context.close();
+        await this.#initializeTask?.catch(() => undefined);
+    }
+    #throwIfInitializationStale(generation) {
+        if (this.#disposed || generation !== this.#lifecycleGeneration) {
+            throw new DOMException('TransferableAudioWorkletClock initialization became stale', 'AbortError');
+        }
+    }
+}
+export function selectBrowserAudioTransport(environment) {
+    return environment.crossOriginIsolated && environment.sharedArrayBufferAvailable
+        ? { mode: 'shared-ring', reason: 'cross-origin-isolated' }
+        : { mode: 'transferable-queue', reason: 'shared-array-buffer-unavailable' };
+}

package/dist/video-scheduler.d.ts

@@ -0,0 +1,39 @@
+import { type Disposable, type Rational } from '@aelionsdk/core';
+export interface PlaybackClock {
+    nowUs(): number;
+}
+export interface ScheduledVideoFrame {
+    readonly generation: number;
+    readonly frameIndex: number;
+    readonly timestampUs: number;
+    readonly droppedFrames: number;
+}
+export interface AudioDrivenVideoSchedulerSnapshot {
+    readonly disposed: boolean;
+    readonly scheduled: boolean;
+    readonly rendering: boolean;
+    readonly ended: boolean;
+    readonly generation: number;
+}
+export interface AudioDrivenVideoSchedulerOptions {
+    readonly clock: PlaybackClock;
+    readonly frameRate: Rational;
+    readonly durationUs: number;
+    readonly onFrame: (frame: ScheduledVideoFrame) => void | Promise<void>;
+    readonly onEnd?: () => void;
+    readonly onError?: (error: unknown) => void;
+    readonly schedule?: (callback: FrameRequestCallback) => number;
+    readonly cancel?: (handle: number) => void;
+}
+export declare class AudioDrivenVideoScheduler implements Disposable {
+    #private;
+    constructor(options: AudioDrivenVideoSchedulerOptions);
+    get generation(): number;
+    get disposed(): boolean;
+    snapshot(): AudioDrivenVideoSchedulerSnapshot;
+    start(): void;
+    pause(): void;
+    seek(): number;
+    dispose(): void;
+}
+//# sourceMappingURL=video-scheduler.d.ts.map

package/dist/video-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-scheduler.d.ts","sourceRoot":"","sources":["../src/video-scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEjG,MAAM,WAAW,aAAa;IAC5B,KAAK,IAAI,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,oBAAoB,KAAK,MAAM,CAAC;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAED,qBAAa,yBAA0B,YAAW,UAAU;;gBAgBvC,OAAO,EAAE,gCAAgC;IAc5D,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAEM,QAAQ,IAAI,iCAAiC;IAU7C,KAAK,IAAI,IAAI;IAOb,KAAK,IAAI,IAAI;IAMb,IAAI,IAAI,MAAM;IAOd,OAAO,IAAI,IAAI;CAiDvB"}