@aelionsdk/export 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/export
+
+Streaming WebCodecs and WebM export pipeline for AelionSDK
+
+Install with `npm install @aelionsdk/export@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/audio-export.d.ts

@@ -0,0 +1,23 @@
+import type { StreamTargetChunk } from 'mediabunny';
+import type { OfflineAudioRequest } from './webm-export.js';
+export interface WavExportOptions {
+    readonly durationUs: number;
+    readonly sampleRate: number;
+    readonly channelCount: number;
+    readonly sampleFormat?: 's16' | 'f32';
+    readonly sink: WritableStream<StreamTargetChunk>;
+    readonly cleanupSink?: (reason: unknown) => void | Promise<void>;
+    readonly renderAudio: (request: OfflineAudioRequest, signal?: AbortSignal) => Promise<Float32Array>;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (progress: number) => void;
+    readonly blockFrames?: number;
+}
+export interface WavExportResult {
+    readonly mimeType: 'audio/wav';
+    readonly audioFrames: number;
+    readonly durationUs: number;
+    readonly bytesWritten: number;
+    readonly rf64: boolean;
+}
+export declare function exportWav(options: WavExportOptions): Promise<WavExportResult>;
+//# sourceMappingURL=audio-export.d.ts.map

package/dist/audio-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-export.d.ts","sourceRoot":"","sources":["../src/audio-export.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,QAAQ,CAAC,WAAW,EAAE,CACpB,OAAO,EAAE,mBAAmB,EAC5B,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAgED,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CA0EnF"}

package/dist/audio-export.js

@@ -0,0 +1,120 @@
+import { AelionError, throwIfAborted } from '@aelionsdk/core';
+function ascii(view, offset, value) {
+    for (let index = 0; index < value.length; index += 1) {
+        view.setUint8(offset + index, value.charCodeAt(index));
+    }
+}
+function wavHeader(frames, sampleRate, channelCount, bytesPerSample, floatingPoint) {
+    const dataBytes = frames * channelCount * bytesPerSample;
+    const rf64 = dataBytes + 36 > 0xffff_ffff;
+    const header = new Uint8Array(rf64 ? 80 : 44);
+    const view = new DataView(header.buffer);
+    ascii(view, 0, rf64 ? 'RF64' : 'RIFF');
+    view.setUint32(4, rf64 ? 0xffff_ffff : dataBytes + 36, true);
+    ascii(view, 8, 'WAVE');
+    let offset = 12;
+    if (rf64) {
+        ascii(view, offset, 'ds64');
+        view.setUint32(offset + 4, 28, true);
+        view.setBigUint64(offset + 8, BigInt(dataBytes + header.byteLength - 8), true);
+        view.setBigUint64(offset + 16, BigInt(dataBytes), true);
+        view.setBigUint64(offset + 24, BigInt(frames), true);
+        view.setUint32(offset + 32, 0, true);
+        offset += 36;
+    }
+    ascii(view, offset, 'fmt ');
+    view.setUint32(offset + 4, 16, true);
+    view.setUint16(offset + 8, floatingPoint ? 3 : 1, true);
+    view.setUint16(offset + 10, channelCount, true);
+    view.setUint32(offset + 12, sampleRate, true);
+    view.setUint32(offset + 16, sampleRate * channelCount * bytesPerSample, true);
+    view.setUint16(offset + 20, channelCount * bytesPerSample, true);
+    view.setUint16(offset + 22, bytesPerSample * 8, true);
+    ascii(view, offset + 24, 'data');
+    view.setUint32(offset + 28, rf64 ? 0xffff_ffff : dataBytes, true);
+    return { bytes: header, rf64 };
+}
+function encodePcm(pcm, sampleFormat) {
+    const bytesPerSample = sampleFormat === 's16' ? 2 : 4;
+    const bytes = new Uint8Array(pcm.length * bytesPerSample);
+    const view = new DataView(bytes.buffer);
+    for (let index = 0; index < pcm.length; index += 1) {
+        const sample = Math.max(-1, Math.min(1, pcm[index] ?? 0));
+        if (sampleFormat === 's16') {
+            view.setInt16(index * 2, sample < 0 ? Math.round(sample * 32_768) : Math.round(sample * 32_767), true);
+        }
+        else {
+            view.setFloat32(index * 4, sample, true);
+        }
+    }
+    return bytes;
+}
+export async function exportWav(options) {
+    if (!Number.isSafeInteger(options.durationUs) || options.durationUs <= 0) {
+        throw new RangeError('durationUs must be a positive safe integer');
+    }
+    if (!Number.isSafeInteger(options.sampleRate) || options.sampleRate <= 0) {
+        throw new RangeError('sampleRate must be a positive safe integer');
+    }
+    if (!Number.isSafeInteger(options.channelCount) || options.channelCount <= 0) {
+        throw new RangeError('channelCount must be a positive safe integer');
+    }
+    const sampleFormat = options.sampleFormat ?? 's16';
+    const bytesPerSample = sampleFormat === 's16' ? 2 : 4;
+    const totalFrames = Math.floor((options.durationUs * options.sampleRate) / 1_000_000);
+    const header = wavHeader(totalFrames, options.sampleRate, options.channelCount, bytesPerSample, sampleFormat === 'f32');
+    const writer = options.sink.getWriter();
+    let audioFrames = 0;
+    let position = header.bytes.byteLength;
+    try {
+        throwIfAborted(options.signal, 'WAV export');
+        await writer.write({ type: 'write', data: header.bytes, position: 0 });
+        const blockFrames = options.blockFrames ?? 4_096;
+        if (!Number.isSafeInteger(blockFrames) || blockFrames <= 0) {
+            throw new RangeError('blockFrames must be a positive safe integer');
+        }
+        while (audioFrames < totalFrames) {
+            throwIfAborted(options.signal, 'WAV export');
+            const frameCount = Math.min(blockFrames, totalFrames - audioFrames);
+            const pcm = await options.renderAudio({
+                startFrame: audioFrames,
+                frameCount,
+                sampleRate: options.sampleRate,
+                channelCount: options.channelCount,
+            }, options.signal);
+            if (pcm.length !== frameCount * options.channelCount) {
+                throw new RangeError('renderAudio returned an unexpected interleaved PCM length');
+            }
+            const data = encodePcm(pcm, sampleFormat);
+            await writer.write({ type: 'write', data, position });
+            position += data.byteLength;
+            audioFrames += frameCount;
+            options.onProgress?.(audioFrames / totalFrames);
+        }
+        await writer.close();
+        if (totalFrames === 0)
+            options.onProgress?.(1);
+        return {
+            mimeType: 'audio/wav',
+            audioFrames,
+            durationUs: options.durationUs,
+            bytesWritten: position,
+            rf64: header.rf64,
+        };
+    }
+    catch (cause) {
+        await writer.abort(cause).catch(() => undefined);
+        await Promise.resolve(options.cleanupSink?.(cause)).catch(() => undefined);
+        if (cause instanceof AelionError || cause instanceof RangeError)
+            throw cause;
+        throw new AelionError([
+            {
+                code: 'EXPORT_AUDIO_WRITE_FAILED',
+                severity: 'error',
+                message: cause instanceof Error ? cause.message : 'Audio export failed',
+                recoverable: true,
+                cause,
+            },
+        ]);
+    }
+}

package/dist/checkpoint.d.ts

@@ -0,0 +1,58 @@
+import type { ExportProfileId } from './profiles.js';
+export interface ExportCheckpoint {
+    readonly version: 1;
+    readonly contentId: string;
+    readonly profileId: ExportProfileId;
+    readonly totalUnits: number;
+    readonly completedUnits: number;
+    readonly outputBytes: number;
+    readonly state?: Readonly<Record<string, string | number | boolean | null>>;
+    readonly updatedAtMs: number;
+}
+export interface ExportCheckpointStore {
+    load(key: string, signal?: AbortSignal): Promise<ExportCheckpoint | undefined>;
+    save(key: string, checkpoint: ExportCheckpoint, signal?: AbortSignal): Promise<void>;
+    delete(key: string, signal?: AbortSignal): Promise<void>;
+}
+export declare class MemoryExportCheckpointStore implements ExportCheckpointStore {
+    #private;
+    load(key: string, signal?: AbortSignal): Promise<ExportCheckpoint | undefined>;
+    save(key: string, checkpoint: ExportCheckpoint, signal?: AbortSignal): Promise<void>;
+    delete(key: string, signal?: AbortSignal): Promise<void>;
+}
+/**
+ * Durable browser checkpoint store. A new instance with the same namespace
+ * resumes committed units after a page reload; callers may inject sessionStorage
+ * or a test double instead of localStorage.
+ */
+export declare class BrowserStorageExportCheckpointStore implements ExportCheckpointStore {
+    #private;
+    constructor(options?: {
+        readonly storage?: Storage;
+        readonly namespace?: string;
+    });
+    load(key: string, signal?: AbortSignal): Promise<ExportCheckpoint | undefined>;
+    save(key: string, checkpoint: ExportCheckpoint, signal?: AbortSignal): Promise<void>;
+    delete(key: string, signal?: AbortSignal): Promise<void>;
+}
+export interface CheckpointedExportUnitResult {
+    readonly outputBytes: number;
+    readonly state?: ExportCheckpoint['state'];
+}
+export interface RunCheckpointedExportOptions {
+    readonly key: string;
+    readonly contentId: string;
+    readonly profileId: ExportProfileId;
+    readonly totalUnits: number;
+    readonly store: ExportCheckpointStore;
+    readonly processUnit: (unitIndex: number, checkpoint: ExportCheckpoint | undefined, signal?: AbortSignal) => Promise<CheckpointedExportUnitResult>;
+    readonly signal?: AbortSignal;
+    readonly now?: () => number;
+    readonly onProgress?: (completedUnits: number, totalUnits: number) => void;
+}
+/**
+ * Runs independently committable export units. A unit must be idempotent for
+ * `(contentId, profileId, unitIndex)`; the checkpoint is advanced only after it commits.
+ */
+export declare function runCheckpointedExport(options: RunCheckpointedExportOptions): Promise<ExportCheckpoint>;
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":"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"}

package/dist/checkpoint.js

@@ -0,0 +1,119 @@
+import { throwIfAborted } from '@aelionsdk/core';
+export class MemoryExportCheckpointStore {
+    #entries = new Map();
+    load(key, signal) {
+        throwIfAborted(signal, 'Load export checkpoint');
+        return Promise.resolve(this.#entries.get(key));
+    }
+    save(key, checkpoint, signal) {
+        throwIfAborted(signal, 'Save export checkpoint');
+        this.#entries.set(key, structuredClone(checkpoint));
+        return Promise.resolve();
+    }
+    delete(key, signal) {
+        throwIfAborted(signal, 'Delete export checkpoint');
+        this.#entries.delete(key);
+        return Promise.resolve();
+    }
+}
+/**
+ * Durable browser checkpoint store. A new instance with the same namespace
+ * resumes committed units after a page reload; callers may inject sessionStorage
+ * or a test double instead of localStorage.
+ */
+export class BrowserStorageExportCheckpointStore {
+    #storage;
+    #namespace;
+    constructor(options = {}) {
+        const storage = options.storage ?? globalThis.localStorage;
+        this.#storage = storage;
+        this.#namespace = options.namespace ?? 'aelion-export-checkpoint';
+    }
+    load(key, signal) {
+        throwIfAborted(signal, 'Load export checkpoint');
+        const value = this.#storage.getItem(this.#key(key));
+        if (value === null)
+            return Promise.resolve(undefined);
+        try {
+            const parsed = JSON.parse(value);
+            if (parsed === null ||
+                typeof parsed !== 'object' ||
+                Reflect.get(parsed, 'version') !== 1 ||
+                typeof Reflect.get(parsed, 'contentId') !== 'string' ||
+                typeof Reflect.get(parsed, 'profileId') !== 'string') {
+                this.#storage.removeItem(this.#key(key));
+                return Promise.resolve(undefined);
+            }
+            return Promise.resolve(parsed);
+        }
+        catch {
+            this.#storage.removeItem(this.#key(key));
+            return Promise.resolve(undefined);
+        }
+    }
+    save(key, checkpoint, signal) {
+        throwIfAborted(signal, 'Save export checkpoint');
+        this.#storage.setItem(this.#key(key), JSON.stringify(checkpoint));
+        return Promise.resolve();
+    }
+    delete(key, signal) {
+        throwIfAborted(signal, 'Delete export checkpoint');
+        this.#storage.removeItem(this.#key(key));
+        return Promise.resolve();
+    }
+    #key(key) {
+        if (key.length === 0)
+            throw new TypeError('Checkpoint key must not be empty');
+        return `${this.#namespace}:${encodeURIComponent(key)}`;
+    }
+}
+function compatibleCheckpoint(checkpoint, options) {
+    if (checkpoint === undefined)
+        return undefined;
+    if (checkpoint.contentId !== options.contentId ||
+        checkpoint.profileId !== options.profileId ||
+        checkpoint.totalUnits !== options.totalUnits ||
+        checkpoint.completedUnits < 0 ||
+        checkpoint.completedUnits > checkpoint.totalUnits) {
+        return undefined;
+    }
+    return checkpoint;
+}
+/**
+ * Runs independently committable export units. A unit must be idempotent for
+ * `(contentId, profileId, unitIndex)`; the checkpoint is advanced only after it commits.
+ */
+export async function runCheckpointedExport(options) {
+    if (!Number.isSafeInteger(options.totalUnits) || options.totalUnits <= 0) {
+        throw new RangeError('totalUnits must be a positive safe integer');
+    }
+    throwIfAborted(options.signal, 'Checkpointed export');
+    let checkpoint = compatibleCheckpoint(await options.store.load(options.key, options.signal), options);
+    if (checkpoint === undefined) {
+        await options.store.delete(options.key, options.signal);
+        checkpoint = {
+            version: 1,
+            contentId: options.contentId,
+            profileId: options.profileId,
+            totalUnits: options.totalUnits,
+            completedUnits: 0,
+            outputBytes: 0,
+            updatedAtMs: (options.now ?? Date.now)(),
+        };
+    }
+    options.onProgress?.(checkpoint.completedUnits, checkpoint.totalUnits);
+    for (let unitIndex = checkpoint.completedUnits; unitIndex < options.totalUnits; unitIndex += 1) {
+        throwIfAborted(options.signal, 'Checkpointed export');
+        const result = await options.processUnit(unitIndex, checkpoint, options.signal);
+        checkpoint = {
+            ...checkpoint,
+            completedUnits: unitIndex + 1,
+            outputBytes: checkpoint.outputBytes + result.outputBytes,
+            ...(result.state === undefined ? {} : { state: result.state }),
+            updatedAtMs: (options.now ?? Date.now)(),
+        };
+        await options.store.save(options.key, checkpoint, options.signal);
+        options.onProgress?.(checkpoint.completedUnits, checkpoint.totalUnits);
+    }
+    return checkpoint;
+}

package/dist/image-export.d.ts

@@ -0,0 +1,40 @@
+import { type Rational } from '@aelionsdk/core';
+import type { StreamTargetChunk } from 'mediabunny';
+import type { OfflineFrameRequest } from './webm-export.js';
+export interface StillImageExportOptions {
+    readonly timeUs: number;
+    readonly width: number;
+    readonly height: number;
+    readonly format: 'png' | 'jpeg' | 'webp';
+    readonly quality?: number;
+    readonly sink: WritableStream<StreamTargetChunk>;
+    readonly cleanupSink?: (reason: unknown) => void | Promise<void>;
+    readonly renderFrame: (request: OfflineFrameRequest, signal?: AbortSignal) => Promise<VideoFrame>;
+    readonly signal?: AbortSignal;
+}
+export interface StillImageExportResult {
+    readonly mimeType: `image/${'png' | 'jpeg' | 'webp'}`;
+    readonly bytesWritten: number;
+    readonly timeUs: number;
+}
+export interface GifExportOptions {
+    readonly durationUs: number;
+    readonly width: number;
+    readonly height: number;
+    readonly frameRate: Rational;
+    readonly loopCount?: number;
+    readonly sink: WritableStream<StreamTargetChunk>;
+    readonly cleanupSink?: (reason: unknown) => void | Promise<void>;
+    readonly renderFrame: (request: OfflineFrameRequest, signal?: AbortSignal) => Promise<VideoFrame>;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (progress: number) => void;
+}
+export interface GifExportResult {
+    readonly mimeType: 'image/gif';
+    readonly videoFrames: number;
+    readonly durationUs: number;
+    readonly bytesWritten: number;
+}
+export declare function exportStillImage(options: StillImageExportOptions): Promise<StillImageExportResult>;
+export declare function exportGif(options: GifExportOptions): Promise<GifExportResult>;
+//# sourceMappingURL=image-export.d.ts.map

package/dist/image-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-export.d.ts","sourceRoot":"","sources":["../src/image-export.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,QAAQ,EACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,mBAAmB,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAClG,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,SAAS,KAAK,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;IACtD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,mBAAmB,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAClG,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAkCD,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CA0CjC;AA+GD,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAuEnF"}

package/dist/image-export.js

@@ -0,0 +1,235 @@
+import { AelionError, frameDurationUs, frameStartUs, throwIfAborted, } from '@aelionsdk/core';
+function assertDimensions(width, height) {
+    if (!Number.isSafeInteger(width) ||
+        !Number.isSafeInteger(height) ||
+        width <= 0 ||
+        height <= 0 ||
+        width > 65_535 ||
+        height > 65_535) {
+        throw new RangeError('Image dimensions must be integers between 1 and 65535');
+    }
+}
+async function cleanupFailure(writer, cleanupSink, cause) {
+    await writer.abort(cause).catch(() => undefined);
+    await Promise.resolve(cleanupSink?.(cause)).catch(() => undefined);
+    if (cause instanceof AelionError || cause instanceof RangeError)
+        throw cause;
+    throw new AelionError([
+        {
+            code: 'EXPORT_IMAGE_WRITE_FAILED',
+            severity: 'error',
+            message: cause instanceof Error ? cause.message : 'Image export failed',
+            recoverable: true,
+            cause,
+        },
+    ]);
+}
+export async function exportStillImage(options) {
+    assertDimensions(options.width, options.height);
+    if (!Number.isSafeInteger(options.timeUs) || options.timeUs < 0) {
+        throw new RangeError('timeUs must be a non-negative safe integer');
+    }
+    if (options.quality !== undefined && (options.quality < 0 || options.quality > 1)) {
+        throw new RangeError('quality must be between 0 and 1');
+    }
+    const writer = options.sink.getWriter();
+    try {
+        throwIfAborted(options.signal, 'Still image export');
+        const frame = await options.renderFrame({
+            frameIndex: 0,
+            timestampUs: options.timeUs,
+            durationUs: 1,
+            width: options.width,
+            height: options.height,
+        }, options.signal);
+        const canvas = new OffscreenCanvas(options.width, options.height);
+        try {
+            const context = canvas.getContext('2d');
+            if (context === null)
+                throw new Error('2D canvas is unavailable');
+            context.drawImage(frame, 0, 0, options.width, options.height);
+        }
+        finally {
+            frame.close();
+        }
+        throwIfAborted(options.signal, 'Still image export');
+        const mimeType = `image/${options.format}`;
+        const blob = await canvas.convertToBlob({
+            type: mimeType,
+            ...(options.quality === undefined ? {} : { quality: options.quality }),
+        });
+        const bytes = new Uint8Array(await blob.arrayBuffer());
+        await writer.write({ type: 'write', data: bytes, position: 0 });
+        await writer.close();
+        return { mimeType, bytesWritten: bytes.byteLength, timeUs: options.timeUs };
+    }
+    catch (cause) {
+        return cleanupFailure(writer, options.cleanupSink, cause);
+    }
+}
+function littleEndian16(value) {
+    return [value & 0xff, (value >>> 8) & 0xff];
+}
+function gifPalette() {
+    const palette = new Uint8Array(256 * 3);
+    for (let index = 0; index < 256; index += 1) {
+        palette[index * 3] = Math.round((((index >>> 5) & 7) * 255) / 7);
+        palette[index * 3 + 1] = Math.round((((index >>> 2) & 7) * 255) / 7);
+        palette[index * 3 + 2] = Math.round(((index & 3) * 255) / 3);
+    }
+    return palette;
+}
+function quantize(image) {
+    const pixels = new Uint8Array(image.width * image.height);
+    for (let index = 0; index < pixels.length; index += 1) {
+        const offset = index * 4;
+        pixels[index] =
+            (((image.data[offset] ?? 0) >>> 5) << 5) |
+                (((image.data[offset + 1] ?? 0) >>> 5) << 2) |
+                ((image.data[offset + 2] ?? 0) >>> 6);
+    }
+    return pixels;
+}
+function lzwData(pixels) {
+    const codes = [256];
+    let literalsSinceClear = 0;
+    for (const pixel of pixels) {
+        if (literalsSinceClear >= 250) {
+            codes.push(256);
+            literalsSinceClear = 0;
+        }
+        codes.push(pixel);
+        literalsSinceClear += 1;
+    }
+    codes.push(257);
+    const packed = new Uint8Array(Math.ceil((codes.length * 9) / 8));
+    let bitOffset = 0;
+    for (const code of codes) {
+        for (let bit = 0; bit < 9; bit += 1) {
+            if ((code & (1 << bit)) !== 0) {
+                const byteIndex = bitOffset >>> 3;
+                packed[byteIndex] = (packed[byteIndex] ?? 0) | (1 << (bitOffset & 7));
+            }
+            bitOffset += 1;
+        }
+    }
+    const blocks = [8];
+    for (let offset = 0; offset < packed.length; offset += 255) {
+        const size = Math.min(255, packed.length - offset);
+        blocks.push(size, ...packed.subarray(offset, offset + size));
+    }
+    blocks.push(0);
+    return Uint8Array.from(blocks);
+}
+function gifHeader(width, height, loopCount) {
+    const [widthLow, widthHigh] = littleEndian16(width);
+    const [heightLow, heightHigh] = littleEndian16(height);
+    const [loopLow, loopHigh] = littleEndian16(loopCount);
+    return Uint8Array.from([
+        ...new TextEncoder().encode('GIF89a'),
+        widthLow,
+        widthHigh,
+        heightLow,
+        heightHigh,
+        0xf7,
+        0,
+        0,
+        ...gifPalette(),
+        0x21,
+        0xff,
+        0x0b,
+        ...new TextEncoder().encode('NETSCAPE2.0'),
+        3,
+        1,
+        loopLow,
+        loopHigh,
+        0,
+    ]);
+}
+function gifFrame(width, height, delayCs, pixels) {
+    const [widthLow, widthHigh] = littleEndian16(width);
+    const [heightLow, heightHigh] = littleEndian16(height);
+    const [delayLow, delayHigh] = littleEndian16(Math.max(1, Math.min(65_535, delayCs)));
+    const control = Uint8Array.from([0x21, 0xf9, 4, 0, delayLow, delayHigh, 0, 0]);
+    const descriptor = Uint8Array.from([
+        0x2c,
+        0,
+        0,
+        0,
+        0,
+        widthLow,
+        widthHigh,
+        heightLow,
+        heightHigh,
+        0,
+    ]);
+    const image = lzwData(pixels);
+    const result = new Uint8Array(control.length + descriptor.length + image.length);
+    result.set(control, 0);
+    result.set(descriptor, control.length);
+    result.set(image, control.length + descriptor.length);
+    return result;
+}
+export async function exportGif(options) {
+    assertDimensions(options.width, options.height);
+    if (!Number.isSafeInteger(options.durationUs) || options.durationUs <= 0) {
+        throw new RangeError('durationUs must be a positive safe integer');
+    }
+    const loopCount = options.loopCount ?? 0;
+    if (!Number.isSafeInteger(loopCount) || loopCount < 0 || loopCount > 65_535) {
+        throw new RangeError('loopCount must be an integer between 0 and 65535');
+    }
+    const frameCount = Math.ceil((options.durationUs * options.frameRate.numerator) /
+        (1_000_000 * options.frameRate.denominator));
+    const writer = options.sink.getWriter();
+    let position = 0;
+    let videoFrames = 0;
+    try {
+        const header = gifHeader(options.width, options.height, loopCount);
+        await writer.write({ type: 'write', data: header, position });
+        position += header.byteLength;
+        const canvas = new OffscreenCanvas(options.width, options.height);
+        const context = canvas.getContext('2d', { willReadFrequently: true });
+        if (context === null)
+            throw new Error('2D canvas is unavailable');
+        for (let frameIndex = 0; frameIndex < frameCount; frameIndex += 1) {
+            throwIfAborted(options.signal, 'GIF export');
+            const timestampUs = frameStartUs(frameIndex, options.frameRate);
+            const durationUs = Math.min(frameDurationUs(frameIndex, options.frameRate), options.durationUs - timestampUs);
+            if (durationUs <= 0)
+                break;
+            const frame = await options.renderFrame({
+                frameIndex,
+                timestampUs,
+                durationUs,
+                width: options.width,
+                height: options.height,
+            }, options.signal);
+            try {
+                context.clearRect(0, 0, options.width, options.height);
+                context.drawImage(frame, 0, 0, options.width, options.height);
+            }
+            finally {
+                frame.close();
+            }
+            const data = gifFrame(options.width, options.height, Math.round(durationUs / 10_000), quantize(context.getImageData(0, 0, options.width, options.height)));
+            await writer.write({ type: 'write', data, position });
+            position += data.byteLength;
+            videoFrames += 1;
+            options.onProgress?.(videoFrames / frameCount);
+        }
+        const trailer = Uint8Array.of(0x3b);
+        await writer.write({ type: 'write', data: trailer, position });
+        position += 1;
+        await writer.close();
+        return {
+            mimeType: 'image/gif',
+            videoFrames,
+            durationUs: options.durationUs,
+            bytesWritten: position,
+        };
+    }
+    catch (cause) {
+        return cleanupFailure(writer, options.cleanupSink, cause);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from './audio-export.js';
+export * from './checkpoint.js';
+export * from './image-export.js';
+export * from './memory-sink.js';
+export * from './opfs-sink.js';
+export * from './profiles.js';
+export * from './remote-export.js';
+export * from './resumable-muxed-export.js';
+export * from './session.js';
+export * from './webm-export.js';
+export * from './worker-export.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,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC"}