@aelionsdk/audio 0.1.0-beta.1

package/dist/video-scheduler.js

@@ -0,0 +1,111 @@
+import { frameIndexAtTime, frameStartUs } from '@aelionsdk/core';
+export class AudioDrivenVideoScheduler {
+    #clock;
+    #frameRate;
+    #durationUs;
+    #onFrame;
+    #onEnd;
+    #onError;
+    #schedule;
+    #cancel;
+    #handle;
+    #lastFrameIndex = -1;
+    #generation = 0;
+    #disposed = false;
+    #rendering = false;
+    #ended = false;
+    constructor(options) {
+        if (!Number.isSafeInteger(options.durationUs) || options.durationUs <= 0) {
+            throw new RangeError('Video scheduler duration must be a positive safe integer');
+        }
+        this.#clock = options.clock;
+        this.#frameRate = options.frameRate;
+        this.#durationUs = options.durationUs;
+        this.#onFrame = options.onFrame;
+        this.#onEnd = options.onEnd;
+        this.#onError = options.onError;
+        this.#schedule = options.schedule ?? (callback => globalThis.requestAnimationFrame(callback));
+        this.#cancel = options.cancel ?? (handle => globalThis.cancelAnimationFrame(handle));
+    }
+    get generation() {
+        return this.#generation;
+    }
+    get disposed() {
+        return this.#disposed;
+    }
+    snapshot() {
+        return {
+            disposed: this.#disposed,
+            scheduled: this.#handle !== undefined,
+            rendering: this.#rendering,
+            ended: this.#ended,
+            generation: this.#generation,
+        };
+    }
+    start() {
+        if (this.#disposed)
+            throw new ReferenceError('AudioDrivenVideoScheduler is disposed');
+        if (this.#handle !== undefined)
+            return;
+        this.#ended = false;
+        this.#handle = this.#schedule(this.#tick);
+    }
+    pause() {
+        if (this.#handle === undefined)
+            return;
+        this.#cancel(this.#handle);
+        this.#handle = undefined;
+    }
+    seek() {
+        this.#generation += 1;
+        this.#lastFrameIndex = -1;
+        this.#ended = false;
+        return this.#generation;
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.pause();
+        this.#disposed = true;
+        this.#generation += 1;
+    }
+    #tick = () => {
+        this.#handle = undefined;
+        if (this.#disposed)
+            return;
+        const clockTimeUs = Math.max(0, this.#clock.nowUs());
+        if (clockTimeUs >= this.#durationUs) {
+            this.pause();
+            if (!this.#ended) {
+                this.#ended = true;
+                this.#onEnd?.();
+            }
+            return;
+        }
+        const timeUs = Math.min(this.#durationUs - 1, clockTimeUs);
+        const frameIndex = frameIndexAtTime(timeUs, this.#frameRate);
+        if (!this.#rendering && frameIndex !== this.#lastFrameIndex) {
+            const generation = this.#generation;
+            const droppedFrames = Math.max(0, frameIndex - this.#lastFrameIndex - 1);
+            this.#lastFrameIndex = frameIndex;
+            this.#rendering = true;
+            void Promise.resolve(this.#onFrame({
+                generation,
+                frameIndex,
+                timestampUs: frameStartUs(frameIndex, this.#frameRate),
+                droppedFrames,
+            })).then(() => {
+                this.#rendering = false;
+            }, (error) => {
+                this.#rendering = false;
+                try {
+                    this.#onError?.(error);
+                }
+                catch {
+                    // Error observers cannot create an unhandled scheduler rejection.
+                }
+            });
+        }
+        this.#handle = this.#schedule(this.#tick);
+    };
+}

package/dist/worklet-clock.d.ts

@@ -0,0 +1,55 @@
+import type { Disposable } from '@aelionsdk/core';
+import { SharedPcmRingBuffer, type PcmRingSnapshot } from './pcm-ring.js';
+export interface AudioClockReport {
+    readonly currentFrame: number;
+    readonly currentTime: number;
+    readonly snapshot: PcmRingSnapshot;
+}
+export type AudioClockEvent = {
+    readonly type: 'started';
+    readonly timeUs: number;
+} | {
+    readonly type: 'paused';
+    readonly timeUs: number;
+} | {
+    readonly type: 'interrupted';
+    readonly timeUs: number;
+} | {
+    readonly type: 'resumed';
+    readonly timeUs: number;
+} | {
+    readonly type: 'seeked';
+    readonly timeUs: number;
+    readonly generation: number;
+};
+export interface AudioClockOptions {
+    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 type AudioContextRuntimeState = AudioContextState | 'interrupted';
+export declare function audioContextStateTransition(previous: AudioContextRuntimeState, current: AudioContextRuntimeState): 'interrupted' | 'resumed' | undefined;
+export declare class AudioWorkletClock implements Disposable {
+    #private;
+    readonly context: AudioContext;
+    readonly ring: SharedPcmRingBuffer;
+    constructor(options?: AudioClockOptions);
+    get disposed(): boolean;
+    get ownsContext(): boolean;
+    get lastReport(): AudioClockReport | undefined;
+    get generation(): number;
+    initialize(reportEveryFrames?: number): Promise<void>;
+    start(): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    subscribe(listener: (event: AudioClockEvent) => void): () => void;
+    resetForSeek(timeUs?: number): number;
+    nowUs(): number;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=worklet-clock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worklet-clock.d.ts","sourceRoot":"","sources":["../src/worklet-clock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,OAAO,EAAE,mBAAmB,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF,MAAM,WAAW,iBAAiB;IAChC,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,MAAM,MAAM,wBAAwB,GAAG,iBAAiB,GAAG,aAAa,CAAC;AAEzE,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,wBAAwB,EAClC,OAAO,EAAE,wBAAwB,GAChC,aAAa,GAAG,SAAS,GAAG,SAAS,CAIvC;AAoBD,qBAAa,iBAAkB,YAAW,UAAU;;IAClD,SAAgB,OAAO,EAAE,YAAY,CAAC;IACtC,SAAgB,IAAI,EAAE,mBAAmB,CAAC;gBAuBvB,OAAO,GAAE,iBAAsB;IAkBlD,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAED,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED,IAAW,UAAU,IAAI,gBAAgB,GAAG,SAAS,CAEpD;IAED,IAAW,UAAU,IAAI,MAAM,CAE9B;IAEY,UAAU,CAAC,iBAAiB,SAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;IAsDtE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAO7B,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAKjE,YAAY,CAAC,MAAM,SAAI,GAAG,MAAM;IAYhC,KAAK,IAAI,MAAM;IAQf,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CA+BhC"}

package/dist/worklet-clock.js

@@ -0,0 +1,193 @@
+import { SharedPcmRingBuffer } from './pcm-ring.js';
+export function audioContextStateTransition(previous, current) {
+    if (current === 'interrupted' && previous !== 'interrupted')
+        return 'interrupted';
+    if (previous === 'interrupted' && current === 'running')
+        return 'resumed';
+    return undefined;
+}
+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} ms`));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        if (timeoutId !== undefined)
+            globalThis.clearTimeout(timeoutId);
+    }
+}
+export class AudioWorkletClock {
+    context;
+    ring;
+    #node;
+    #initializeTask;
+    #disposeTask;
+    #ownsContext;
+    #disposed = false;
+    #lifecycleGeneration = 0;
+    #lastReport;
+    #contextOriginTime;
+    #timelineOriginUs = 0;
+    #generation = 0;
+    #lastContextState;
+    #listeners = new Set();
+    #moduleUrl;
+    #onStateChange = () => {
+        if (this.#disposed)
+            return;
+        const current = this.context.state;
+        const transition = audioContextStateTransition(this.#lastContextState, current);
+        this.#lastContextState = current;
+        if (transition !== undefined)
+            this.#emit(transition);
+    };
+    constructor(options = {}) {
+        this.#moduleUrl = options.moduleUrl ?? new URL('./pcm-player.worklet.js', import.meta.url);
+        this.context =
+            options.context ??
+                new AudioContext({
+                    latencyHint: 'interactive',
+                    sampleRate: options.sampleRate ?? 48_000,
+                });
+        this.#ownsContext = options.context === undefined;
+        this.#lastContextState = this.context.state;
+        this.ring = SharedPcmRingBuffer.allocate(options.capacityFrames ?? this.context.sampleRate * 2, options.channelCount ?? 2, this.context.sampleRate);
+        this.context.addEventListener('statechange', this.#onStateChange);
+    }
+    get disposed() {
+        return this.#disposed;
+    }
+    get ownsContext() {
+        return this.#ownsContext;
+    }
+    get lastReport() {
+        return this.#lastReport;
+    }
+    get generation() {
+        return this.#generation;
+    }
+    async initialize(reportEveryFrames = this.context.sampleRate) {
+        if (this.#disposed)
+            throw new ReferenceError('AudioWorkletClock 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-pcm-player', {
+            numberOfInputs: 0,
+            numberOfOutputs: 1,
+            outputChannelCount: [this.ring.channelCount],
+            processorOptions: {
+                ring: this.ring.descriptor(),
+                reportEveryFrames,
+            },
+        });
+        let connected = false;
+        try {
+            node.port.addEventListener('message', event => {
+                const value = event.data;
+                if (value !== null && typeof value === 'object' && Reflect.get(value, 'type') === 'clock') {
+                    this.#lastReport = value;
+                }
+            });
+            node.port.start();
+            // AudioContext.currentTime starts when the context starts running, which can
+            // be well before the worklet module has loaded.  The transport clock must
+            // instead start when this playback node joins the audio graph; otherwise
+            // module-loading latency appears as permanent A/V drift.
+            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();
+        await withTimeout(this.context.resume(), 5_000, 'AudioContext resume');
+        this.#emit('started');
+    }
+    async pause() {
+        if (this.context.state === 'running')
+            await this.context.suspend();
+        this.#emit('paused');
+    }
+    async resume() {
+        if (this.context.state !== 'running') {
+            await withTimeout(this.context.resume(), 5_000, 'AudioContext resume');
+        }
+        this.#emit('resumed');
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    resetForSeek(timeUs = 0) {
+        if (!Number.isSafeInteger(timeUs) || timeUs < 0) {
+            throw new RangeError('Seek target must be a non-negative safe integer microsecond value');
+        }
+        this.ring.flush();
+        this.#timelineOriginUs = timeUs;
+        this.#contextOriginTime = this.context.currentTime;
+        this.#generation += 1;
+        this.#emit('seeked');
+        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)));
+    }
+    dispose() {
+        this.#disposeTask ??= this.#dispose();
+        return this.#disposeTask;
+    }
+    async #dispose() {
+        this.#disposed = true;
+        this.#lifecycleGeneration += 1;
+        this.context.removeEventListener('statechange', this.#onStateChange);
+        this.ring.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);
+        this.#listeners.clear();
+    }
+    #throwIfInitializationStale(generation) {
+        if (this.#disposed || generation !== this.#lifecycleGeneration) {
+            throw new DOMException('AudioWorkletClock initialization became stale', 'AbortError');
+        }
+    }
+    #emit(type) {
+        const event = type === 'seeked'
+            ? { type, timeUs: this.nowUs(), generation: this.#generation }
+            : { type, timeUs: this.nowUs() };
+        for (const listener of this.#listeners)
+            listener(event);
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@aelionsdk/audio",
+  "version": "0.1.0-beta.1",
+  "description": "AudioWorklet clock, PCM buffering and audio mixing for AelionSDK",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FoyonaCZY/AelionSDK.git",
+    "directory": "packages/audio"
+  },
+  "keywords": [
+    "aelion",
+    "audio",
+    "audioworklet",
+    "video"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@aelionsdk/core": "0.1.0-beta.1",
+    "@aelionsdk/render-ir": "0.1.0-beta.1"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b --pretty false"
+  }
+}