@aelionsdk/audio 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FoyonaCZY and AelionSDK contributors
+
+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/README.md

@@ -0,0 +1,7 @@
+# @aelionsdk/audio
+
+AudioWorklet clock, PCM buffering and audio mixing for AelionSDK
+
+Install with `npm install @aelionsdk/audio@next`.
+
+Version 0.1.0-beta.1 is a prerelease and its API may change before the first stable release. This package is part of [AelionSDK](https://github.com/FoyonaCZY/AelionSDK); see the repository README for supported browsers, examples and deployment requirements.

package/dist/device-state.d.ts

@@ -0,0 +1,28 @@
+import { type Disposable } from '@aelionsdk/core';
+export type AudioRuntimeState = 'idle' | 'running' | 'interrupted' | 'switching-device' | 'failed' | 'disposed';
+export interface AudioOutputBackend {
+    readonly state: string;
+    resume(): Promise<void>;
+    suspend(): Promise<void>;
+    setSinkId?(sinkId: string): Promise<void>;
+    addEventListener(type: 'statechange', listener: () => void): void;
+    removeEventListener(type: 'statechange', listener: () => void): void;
+}
+export interface AudioRuntimeSnapshot {
+    readonly state: AudioRuntimeState;
+    readonly outputDeviceId: string;
+    readonly generation: number;
+    readonly errorCode?: string;
+}
+/** Serializes device changes and browser interruption recovery without losing mixer state. */
+export declare class AudioRuntimeStateMachine implements Disposable {
+    #private;
+    constructor(backend: AudioOutputBackend);
+    get disposed(): boolean;
+    snapshot(): AudioRuntimeSnapshot;
+    start(signal?: AbortSignal): Promise<void>;
+    switchOutputDevice(deviceId: string, signal?: AbortSignal): Promise<void>;
+    recover(signal?: AbortSignal): Promise<void>;
+    dispose(): void;
+}
+//# sourceMappingURL=device-state.d.ts.map

package/dist/device-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-state.d.ts","sourceRoot":"","sources":["../src/device-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE/E,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,SAAS,GACT,aAAa,GACb,kBAAkB,GAClB,QAAQ,GACR,UAAU,CAAC;AAEf,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,SAAS,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,gBAAgB,CAAC,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAClE,mBAAmB,CAAC,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CACtE;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAMD,8FAA8F;AAC9F,qBAAa,wBAAyB,YAAW,UAAU;;gBAQtC,OAAO,EAAE,kBAAkB;IAK9C,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAEM,QAAQ,IAAI,oBAAoB;IAS1B,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBhD,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAyCnE,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlD,OAAO,IAAI,IAAI;CA6BvB"}

package/dist/device-state.js

@@ -0,0 +1,119 @@
+import { AelionError, throwIfAborted } from '@aelionsdk/core';
+function diagnostic(code, message, recoverable) {
+    return new AelionError([{ code, severity: 'error', message, recoverable }]);
+}
+/** Serializes device changes and browser interruption recovery without losing mixer state. */
+export class AudioRuntimeStateMachine {
+    #backend;
+    #state = 'idle';
+    #deviceId = 'default';
+    #generation = 0;
+    #errorCode;
+    #switchTask = Promise.resolve();
+    constructor(backend) {
+        this.#backend = backend;
+        backend.addEventListener('statechange', this.#handleStateChange);
+    }
+    get disposed() {
+        return this.#state === 'disposed';
+    }
+    snapshot() {
+        return {
+            state: this.#state,
+            outputDeviceId: this.#deviceId,
+            generation: this.#generation,
+            ...(this.#errorCode === undefined ? {} : { errorCode: this.#errorCode }),
+        };
+    }
+    async start(signal) {
+        this.#requireActive();
+        throwIfAborted(signal, 'Audio runtime start');
+        try {
+            await this.#backend.resume();
+            throwIfAborted(signal, 'Audio runtime start');
+            this.#state = this.#backend.state === 'running' ? 'running' : 'interrupted';
+            this.#errorCode = undefined;
+        }
+        catch (error) {
+            this.#fail('AUDIO_CONTEXT_RESUME_FAILED');
+            throw diagnostic('AUDIO_CONTEXT_RESUME_FAILED', error instanceof Error ? error.message : 'AudioContext resume failed', true);
+        }
+    }
+    switchOutputDevice(deviceId, signal) {
+        this.#requireActive();
+        if (deviceId.length === 0)
+            return Promise.reject(new TypeError('AUDIO_DEVICE_ID_INVALID'));
+        const generation = ++this.#generation;
+        const task = this.#switchTask.then(async () => {
+            this.#requireActive();
+            throwIfAborted(signal, 'Audio output device switch');
+            if (generation !== this.#generation)
+                return;
+            if (this.#backend.setSinkId === undefined) {
+                throw diagnostic('AUDIO_OUTPUT_DEVICE_UNSUPPORTED', 'The active browser does not support AudioContext output device selection', true);
+            }
+            const wasRunning = this.#state === 'running';
+            this.#state = 'switching-device';
+            try {
+                if (wasRunning)
+                    await this.#backend.suspend();
+                throwIfAborted(signal, 'Audio output device switch');
+                await this.#backend.setSinkId(deviceId);
+                throwIfAborted(signal, 'Audio output device switch');
+                if (wasRunning)
+                    await this.#backend.resume();
+                if (generation !== this.#generation)
+                    return;
+                this.#deviceId = deviceId;
+                this.#state = this.#backend.state === 'running' ? 'running' : 'interrupted';
+                this.#errorCode = undefined;
+            }
+            catch (error) {
+                if (generation === this.#generation)
+                    this.#fail('AUDIO_OUTPUT_DEVICE_SWITCH_FAILED');
+                if (error instanceof AelionError)
+                    throw error;
+                throw diagnostic('AUDIO_OUTPUT_DEVICE_SWITCH_FAILED', error instanceof Error ? error.message : 'Audio output device switch failed', true);
+            }
+        });
+        this.#switchTask = task.catch(() => undefined);
+        return task;
+    }
+    async recover(signal) {
+        this.#requireActive();
+        if (this.#state !== 'interrupted' && this.#state !== 'failed')
+            return;
+        await this.start(signal);
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.#generation++;
+        this.#backend.removeEventListener('statechange', this.#handleStateChange);
+        this.#state = 'disposed';
+        this.#errorCode = undefined;
+    }
+    #handleStateChange = () => {
+        if (this.disposed || this.#state === 'switching-device')
+            return;
+        if (this.#backend.state === 'running') {
+            this.#state = 'running';
+            this.#errorCode = undefined;
+        }
+        else if (this.#backend.state === 'suspended' || this.#backend.state === 'interrupted') {
+            this.#state = 'interrupted';
+            this.#errorCode = 'AUDIO_CONTEXT_INTERRUPTED';
+        }
+        else if (this.#backend.state === 'closed') {
+            this.#fail('AUDIO_CONTEXT_CLOSED');
+        }
+    };
+    #fail(code) {
+        this.#state = 'failed';
+        this.#errorCode = code;
+    }
+    #requireActive() {
+        if (this.disposed)
+            throw new ReferenceError('Audio runtime is disposed');
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from './ir-mixer.js';
+export * from './processing.js';
+export * from './pcm-ring.js';
+export * from './worklet-clock.js';
+export * from './video-scheduler.js';
+export * from './transferable-pcm-queue.js';
+export * from './transferable-worklet-clock.js';
+export * from './device-state.js';
+export * from './time-stretch.js';
+export * from './resampler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from './ir-mixer.js';
+export * from './processing.js';
+export * from './pcm-ring.js';
+export * from './worklet-clock.js';
+export * from './video-scheduler.js';
+export * from './transferable-pcm-queue.js';
+export * from './transferable-worklet-clock.js';
+export * from './device-state.js';
+export * from './time-stretch.js';
+export * from './resampler.js';

package/dist/ir-mixer.d.ts

@@ -0,0 +1,30 @@
+import { type RenderIr } from '@aelionsdk/render-ir';
+export interface PcmSourceBlock {
+    readonly sampleRate: number;
+    readonly channelCount: number;
+    readonly frameCount: number;
+    readonly interleaved: Float32Array;
+}
+export interface IrPcmSource {
+    pcmRange(assetId: string, streamIndex: number, startUs: number, durationUs: number, signal?: AbortSignal): Promise<PcmSourceBlock>;
+}
+export interface RenderIrAudioOptions {
+    readonly ir: RenderIr;
+    readonly startFrame: number;
+    readonly frameCount: number;
+    readonly channelCount: number;
+    readonly source: IrPcmSource;
+    /** Optional stem selection used by waveform, silence removal and sidechain export. */
+    readonly trackIds?: readonly string[];
+    readonly itemIds?: readonly string[];
+    readonly signal?: AbortSignal;
+}
+export declare function renderIrAudio(options: RenderIrAudioOptions): Promise<Float32Array>;
+export interface AvSyncSample {
+    readonly videoTimestampUs: number;
+    readonly audioFrame: number;
+    readonly audioTimestampUs: number;
+    readonly driftUs: number;
+}
+export declare function measureAvSync(videoTimestampUs: number, audioFrame: number, sampleRate: number): AvSyncSample;
+//# sourceMappingURL=ir-mixer.d.ts.map

package/dist/ir-mixer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir-mixer.d.ts","sourceRoot":"","sources":["../src/ir-mixer.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,QAAQ,EACd,MAAM,sBAAsB,CAAC;AAI9B,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;CACpC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CACN,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAqID,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,CAyLxF;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,aAAa,CAC3B,gBAAgB,EAAE,MAAM,EACxB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,YAAY,CAQd"}

package/dist/ir-mixer.js

@@ -0,0 +1,235 @@
+import { sampleBoundaryUs, throwIfAborted } from '@aelionsdk/core';
+import { evaluateAnimatableNumber, evaluateAudioState, mapIrSourceTime, } from '@aelionsdk/render-ir';
+import { pitchPreservingTimeStretch } from './time-stretch.js';
+function gains(gain, pan) {
+    const angle = ((pan + 1) * Math.PI) / 4;
+    return [gain * Math.cos(angle), gain * Math.sin(angle)];
+}
+function objectProperty(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function fadeEnvelope(audio, localTimeUs, durationUs) {
+    const fadeInUs = typeof audio.fadeInUs === 'number' ? audio.fadeInUs : 0;
+    const fadeOutUs = typeof audio.fadeOutUs === 'number' ? audio.fadeOutUs : 0;
+    const fadeIn = fadeInUs > 0 ? Math.max(0, Math.min(1, localTimeUs / fadeInUs)) : 1;
+    const remainingUs = durationUs - localTimeUs;
+    const fadeOut = fadeOutUs > 0 ? Math.max(0, Math.min(1, remainingUs / fadeOutUs)) : 1;
+    return Math.min(fadeIn, fadeOut);
+}
+function interpolatedChannel(block, sourceFrame, nextSourceFrame, fraction, channel) {
+    if (channel >= block.channelCount)
+        return 0;
+    const first = block.interleaved[sourceFrame * block.channelCount + channel] ?? 0;
+    const next = block.interleaved[nextSourceFrame * block.channelCount + channel] ?? first;
+    return first + (next - first) * fraction;
+}
+function sampleBoundaryCeilUs(sampleIndex, sampleRate) {
+    const floorUs = sampleBoundaryUs(sampleIndex, sampleRate);
+    const remainder = (BigInt(sampleIndex) * 1000000n) % BigInt(sampleRate);
+    const result = floorUs + (remainder === 0n ? 0 : 1);
+    if (!Number.isSafeInteger(result)) {
+        throw new RangeError('PCM request boundary exceeds the safe integer range');
+    }
+    return result;
+}
+function pcmRequestSegments(active, startFrame, frameCount, sampleRate) {
+    const source = active.clip.source;
+    const activeEndUs = active.sequenceStartUs + active.durationUs;
+    const mappedFrames = [];
+    for (let outputOffset = 0; outputOffset < frameCount; outputOffset += 1) {
+        const sequenceTimeUs = sampleBoundaryUs(startFrame + outputOffset, sampleRate);
+        if (sequenceTimeUs < active.sequenceStartUs || sequenceTimeUs >= activeEndUs)
+            continue;
+        const sourceTimeUs = mapIrSourceTime(source, active.clip.range.durationUs, sequenceTimeUs - active.clip.range.startUs);
+        if (sourceTimeUs !== null)
+            mappedFrames.push({ outputOffset, sourceTimeUs });
+    }
+    if (mappedFrames.length === 0)
+        return [];
+    const groups = [];
+    let current = [];
+    let direction = 0;
+    let minimum = Number.POSITIVE_INFINITY;
+    let maximum = Number.NEGATIVE_INFINITY;
+    for (const frame of mappedFrames) {
+        const previous = current.at(-1);
+        const difference = previous === undefined ? 0 : frame.sourceTimeUs - previous.sourceTimeUs;
+        const nextDirection = Math.sign(difference);
+        const nextMinimum = Math.min(minimum, frame.sourceTimeUs);
+        const nextMaximum = Math.max(maximum, frame.sourceTimeUs);
+        const discontinuity = previous !== undefined &&
+            ((direction !== 0 && nextDirection !== 0 && direction !== nextDirection) ||
+                Math.abs(difference) > 250_000 ||
+                nextMaximum - nextMinimum > 1_000_000);
+        if (discontinuity) {
+            groups.push(current);
+            current = [];
+            direction = 0;
+            minimum = Number.POSITIVE_INFINITY;
+            maximum = Number.NEGATIVE_INFINITY;
+        }
+        const groupPrevious = current.at(-1);
+        current.push(frame);
+        minimum = Math.min(minimum, frame.sourceTimeUs);
+        maximum = Math.max(maximum, frame.sourceTimeUs);
+        if (groupPrevious !== undefined) {
+            const groupDirection = Math.sign(frame.sourceTimeUs - groupPrevious.sourceTimeUs);
+            if (groupDirection !== 0)
+                direction = groupDirection;
+        }
+    }
+    if (current.length > 0)
+        groups.push(current);
+    const sourceRangeEndUs = source.sourceRange.startUs + source.sourceRange.durationUs;
+    const sampleDurationUs = sampleBoundaryCeilUs(1, sampleRate);
+    const segments = [];
+    for (const frames of groups) {
+        const times = frames.map(frame => frame.sourceTimeUs);
+        const sourceStartUs = Math.min(...times);
+        const sourceEndUs = Math.max(...times);
+        const durationUs = Math.max(1, Math.min(sourceRangeEndUs - sourceStartUs, sourceEndUs - sourceStartUs + sampleDurationUs));
+        segments.push({ sourceStartUs, durationUs, frames });
+    }
+    return segments;
+}
+export async function renderIrAudio(options) {
+    throwIfAborted(options.signal, 'Render IR audio');
+    if (!Number.isSafeInteger(options.startFrame) || options.startFrame < 0) {
+        throw new RangeError('startFrame must be a non-negative safe integer');
+    }
+    if (!Number.isSafeInteger(options.frameCount) || options.frameCount <= 0) {
+        throw new RangeError('frameCount must be a positive safe integer');
+    }
+    if (!Number.isSafeInteger(options.channelCount) ||
+        options.channelCount < 1 ||
+        options.channelCount > 8) {
+        throw new RangeError('Audio mixer supports between 1 and 8 output channels');
+    }
+    const startUs = sampleBoundaryUs(options.startFrame, options.ir.sampleRate);
+    // A microsecond range whose end is floored can be one source sample short
+    // whenever the target frame boundary is fractional in microseconds (for
+    // example most 48 kHz block boundaries). Cover the complete final target
+    // sample; per-segment copy bounds below discard any provider over-read.
+    const endUs = sampleBoundaryCeilUs(options.startFrame + options.frameCount, options.ir.sampleRate);
+    const selectedTracks = options.trackIds === undefined ? undefined : new Set(options.trackIds);
+    const selectedItems = options.itemIds === undefined ? undefined : new Set(options.itemIds);
+    const evaluatedState = evaluateAudioState(options.ir, startUs, endUs - startUs);
+    const state = {
+        ...evaluatedState,
+        clips: evaluatedState.clips.filter(active => (selectedTracks === undefined || selectedTracks.has(active.clip.trackId)) &&
+            (selectedItems === undefined || selectedItems.has(active.clip.id))),
+    };
+    const output = new Float32Array(options.frameCount * options.channelCount);
+    await Promise.all(state.clips.map(async (active) => {
+        const trackAudio = objectProperty(active.trackAudio);
+        const clipAudio = objectProperty(active.clip.audio);
+        for (const segment of pcmRequestSegments(active, options.startFrame, options.frameCount, options.ir.sampleRate)) {
+            const block = await options.source.pcmRange(active.clip.source.assetId, active.clip.source.streamIndex, segment.sourceStartUs, segment.durationUs, options.signal);
+            throwIfAborted(options.signal, 'Render IR audio');
+            if (!Number.isSafeInteger(block.sampleRate) || block.sampleRate <= 0) {
+                throw new RangeError('PCM source returned an invalid sample rate');
+            }
+            if (!Number.isSafeInteger(block.channelCount) ||
+                block.channelCount < 1 ||
+                block.channelCount > 8) {
+                throw new RangeError('PCM source returned an invalid channel count');
+            }
+            if (block.interleaved.length !== block.frameCount * block.channelCount) {
+                throw new RangeError('PCM source returned an inconsistent interleaved block');
+            }
+            if (block.frameCount < 1)
+                continue;
+            const linearMapping = active.clip.source.timeMapping?.type === 'linear'
+                ? active.clip.source.timeMapping
+                : undefined;
+            const preservePitch = clipAudio.pitchPolicy === 'preserve' &&
+                linearMapping !== undefined &&
+                linearMapping.rate.numerator !== linearMapping.rate.denominator;
+            const stretched = preservePitch
+                ? pitchPreservingTimeStretch({
+                    input: block.interleaved,
+                    inputFrames: block.frameCount,
+                    outputFrames: segment.frames.length,
+                    channelCount: block.channelCount,
+                    reverse: linearMapping.reverse,
+                })
+                : undefined;
+            for (const [segmentFrame, mapped] of segment.frames.entries()) {
+                const targetFrame = options.startFrame + mapped.outputOffset;
+                const sequenceTimeUs = sampleBoundaryUs(targetFrame, options.ir.sampleRate);
+                const gainDb = evaluateAnimatableNumber(trackAudio.gainDb, sequenceTimeUs, 0, 0) +
+                    evaluateAnimatableNumber(clipAudio.gainDb, sequenceTimeUs, active.clip.range.startUs, 0);
+                const pan = Math.max(-1, Math.min(1, evaluateAnimatableNumber(trackAudio.pan, sequenceTimeUs, 0, 0) +
+                    evaluateAnimatableNumber(clipAudio.pan, sequenceTimeUs, active.clip.range.startUs, 0)));
+                const envelope = fadeEnvelope(clipAudio, sequenceTimeUs - active.clip.range.startUs, active.clip.range.durationUs);
+                const [leftGain, rightGain] = gains(10 ** (gainDb / 20) * envelope, pan);
+                const masterGain = 10 ** (gainDb / 20) * envelope;
+                const sourcePosition = ((mapped.sourceTimeUs - segment.sourceStartUs) * block.sampleRate) / 1_000_000;
+                const sourceFrame = Math.max(0, Math.min(block.frameCount - 1, Math.floor(sourcePosition)));
+                const nextSourceFrame = Math.min(block.frameCount - 1, sourceFrame + 1);
+                const fraction = Math.max(0, Math.min(1, sourcePosition - sourceFrame));
+                const channelSample = (channel) => stretched === undefined
+                    ? interpolatedChannel(block, sourceFrame, nextSourceFrame, fraction, channel)
+                    : (stretched[segmentFrame * block.channelCount + channel] ?? 0);
+                const sourceLeft = channelSample(0);
+                const sourceRight = block.channelCount === 1 ? sourceLeft : channelSample(1);
+                const target = mapped.outputOffset * options.channelCount;
+                const channelMap = Array.isArray(clipAudio.channelMap) ? clipAudio.channelMap : undefined;
+                if (channelMap !== undefined) {
+                    if (channelMap.length !== options.channelCount ||
+                        channelMap.some(row => !Array.isArray(row) ||
+                            row.length !== block.channelCount ||
+                            row.some(value => typeof value !== 'number' || !Number.isFinite(value)))) {
+                        throw new RangeError(`Audio channelMap for ${active.clip.id} must be outputChannels × sourceChannels`);
+                    }
+                    for (let outputChannel = 0; outputChannel < options.channelCount; outputChannel += 1) {
+                        const row = channelMap[outputChannel];
+                        let sample = 0;
+                        for (let inputChannel = 0; inputChannel < block.channelCount; inputChannel += 1) {
+                            sample += channelSample(inputChannel) * (row[inputChannel] ?? 0);
+                        }
+                        const channelGain = outputChannel === 0 ? leftGain : outputChannel === 1 ? rightGain : masterGain;
+                        output[target + outputChannel] =
+                            (output[target + outputChannel] ?? 0) + sample * channelGain;
+                    }
+                }
+                else if (options.channelCount === 1) {
+                    output[target] =
+                        (output[target] ?? 0) +
+                            (sourceLeft * leftGain + sourceRight * rightGain) / Math.SQRT2;
+                }
+                else if (options.channelCount === 2) {
+                    output[target] = (output[target] ?? 0) + sourceLeft * leftGain;
+                    output[target + 1] = (output[target + 1] ?? 0) + sourceRight * rightGain;
+                }
+                else {
+                    for (let channel = 0; channel < options.channelCount; channel += 1) {
+                        const sourceSample = channel < block.channelCount
+                            ? channelSample(channel)
+                            : channel < 2
+                                ? sourceLeft
+                                : 0;
+                        const channelGain = channel === 0 ? leftGain : channel === 1 ? rightGain : masterGain;
+                        output[target + channel] =
+                            (output[target + channel] ?? 0) + sourceSample * channelGain;
+                    }
+                }
+            }
+        }
+    }));
+    for (let index = 0; index < output.length; index += 1) {
+        output[index] = Math.max(-1, Math.min(1, output[index] ?? 0));
+    }
+    return output;
+}
+export function measureAvSync(videoTimestampUs, audioFrame, sampleRate) {
+    const audioTimestampUs = sampleBoundaryUs(audioFrame, sampleRate);
+    return {
+        videoTimestampUs,
+        audioFrame,
+        audioTimestampUs,
+        driftUs: videoTimestampUs - audioTimestampUs,
+    };
+}

package/dist/pcm-message-player.worklet.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pcm-message-player.worklet.d.ts.map

package/dist/pcm-message-player.worklet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pcm-message-player.worklet.d.ts","sourceRoot":"","sources":["../src/pcm-message-player.worklet.ts"],"names":[],"mappings":""}

package/dist/pcm-message-player.worklet.js

@@ -0,0 +1,119 @@
+/// <reference lib="webworker" />
+class AelionMessagePcmPlayerProcessor extends AudioWorkletProcessor {
+    #channelCount;
+    #reportEveryFrames;
+    #queue = [];
+    #generation;
+    #lastReportFrame = 0;
+    #playedFrames = 0;
+    #underrunFrames = 0;
+    #closed = false;
+    #playing = false;
+    constructor(options) {
+        super(options);
+        const processorOptions = options?.processorOptions;
+        if (processorOptions === undefined) {
+            throw new TypeError('Aelion message PCM processor requires options');
+        }
+        this.#channelCount = processorOptions.channelCount;
+        this.#generation = processorOptions.generation;
+        this.#reportEveryFrames = processorOptions.reportEveryFrames;
+        this.port.addEventListener('message', this.#onMessage);
+        this.port.start();
+        this.port.postMessage({ type: 'ready', sampleRate });
+    }
+    process(inputs, outputs, parameters) {
+        void inputs;
+        void parameters;
+        const output = outputs[0];
+        if (output === undefined)
+            return !this.#closed;
+        for (const plane of output)
+            plane.fill(0);
+        if (!this.#playing)
+            return !this.#closed;
+        const requestedFrames = output[0]?.length ?? 0;
+        let writtenFrames = 0;
+        while (writtenFrames < requestedFrames) {
+            const block = this.#queue[0];
+            if (block === undefined)
+                break;
+            if (block.generation !== this.#generation) {
+                this.#queue.shift();
+                this.port.postMessage({ type: 'ack', id: block.id, generation: block.generation });
+                continue;
+            }
+            const available = block.frameCount - block.offsetFrames;
+            const frames = Math.min(available, requestedFrames - writtenFrames);
+            for (let frame = 0; frame < frames; frame += 1) {
+                for (let channel = 0; channel < this.#channelCount; channel += 1) {
+                    const plane = output[channel];
+                    if (plane !== undefined) {
+                        plane[writtenFrames + frame] =
+                            block.samples[(block.offsetFrames + frame) * block.channelCount + channel] ?? 0;
+                    }
+                }
+            }
+            block.offsetFrames += frames;
+            writtenFrames += frames;
+            if (block.offsetFrames >= block.frameCount) {
+                this.#queue.shift();
+                this.port.postMessage({ type: 'ack', id: block.id, generation: block.generation });
+            }
+        }
+        this.#playedFrames += requestedFrames;
+        this.#underrunFrames += requestedFrames - writtenFrames;
+        if (currentFrame - this.#lastReportFrame >= this.#reportEveryFrames) {
+            this.#lastReportFrame = currentFrame;
+            this.port.postMessage({
+                type: 'clock',
+                currentFrame,
+                currentTime,
+                generation: this.#generation,
+                playedFrames: this.#playedFrames,
+                underrunFrames: this.#underrunFrames,
+                queuedBlocks: this.#queue.length,
+            });
+        }
+        return !this.#closed;
+    }
+    #onMessage = (event) => {
+        const value = event.data;
+        if (value === null || typeof value !== 'object')
+            return;
+        const type = Reflect.get(value, 'type');
+        if (type === 'block') {
+            const block = value;
+            if (block.generation !== this.#generation) {
+                this.port.postMessage({ type: 'ack', id: block.id, generation: block.generation });
+                return;
+            }
+            this.#queue.push({ ...block, offsetFrames: 0 });
+            return;
+        }
+        if (type === 'start') {
+            this.#playing = true;
+            return;
+        }
+        if (type === 'seek') {
+            for (const block of this.#queue) {
+                this.port.postMessage({ type: 'ack', id: block.id, generation: block.generation });
+            }
+            this.#queue.length = 0;
+            const generation = Reflect.get(value, 'generation');
+            if (typeof generation !== 'number' || !Number.isSafeInteger(generation))
+                return;
+            this.#generation = generation;
+            this.#playedFrames = 0;
+            this.#underrunFrames = 0;
+            return;
+        }
+        if (type === 'close') {
+            this.#playing = false;
+            this.#closed = true;
+            this.#queue.length = 0;
+        }
+    };
+}
+registerProcessor('aelion-message-pcm-player', AelionMessagePcmPlayerProcessor);
+export {};

package/dist/pcm-player.worklet.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pcm-player.worklet.d.ts.map

package/dist/pcm-player.worklet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pcm-player.worklet.d.ts","sourceRoot":"","sources":["../src/pcm-player.worklet.ts"],"names":[],"mappings":""}

package/dist/pcm-player.worklet.js

@@ -0,0 +1,36 @@
+/// <reference lib="webworker" />
+import { SharedPcmRingBuffer } from './pcm-ring.js';
+class AelionPcmPlayerProcessor extends AudioWorkletProcessor {
+    #ring;
+    #reportEveryFrames;
+    #lastReportFrame = 0;
+    constructor(options) {
+        super(options);
+        const processorOptions = options?.processorOptions;
+        if (processorOptions === undefined) {
+            throw new TypeError('Aelion PCM processor requires a ring descriptor');
+        }
+        this.#ring = new SharedPcmRingBuffer(processorOptions.ring);
+        this.#reportEveryFrames = processorOptions.reportEveryFrames ?? sampleRate;
+        this.port.postMessage({ type: 'ready', sampleRate });
+    }
+    process(inputs, outputs, parameters) {
+        void inputs;
+        void parameters;
+        const output = outputs[0];
+        if (output === undefined)
+            return true;
+        this.#ring.readPlanar(output);
+        if (currentFrame - this.#lastReportFrame >= this.#reportEveryFrames) {
+            this.#lastReportFrame = currentFrame;
+            this.port.postMessage({
+                type: 'clock',
+                currentFrame,
+                currentTime,
+                snapshot: this.#ring.snapshot(),
+            });
+        }
+        return this.#ring.snapshot().state !== 'closed';
+    }
+}
+registerProcessor('aelion-pcm-player', AelionPcmPlayerProcessor);