@aelionsdk/media 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/media
+
+Range I/O, media indexing, decoding and exact seek for AelionSDK
+
+Install with `npm install @aelionsdk/media@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/cache-store.d.ts

@@ -0,0 +1,65 @@
+export interface CacheAddress {
+    readonly namespace: 'sample-index' | 'thumbnail' | 'waveform' | 'proxy' | 'derived';
+    readonly contentHash: string;
+    readonly version: string;
+    readonly variant?: string;
+}
+export interface CacheStoreSnapshot {
+    readonly entries: number;
+    readonly bytes: number;
+    readonly maxBytes: number;
+    readonly hits: number;
+    readonly misses: number;
+    readonly evictions: number;
+}
+export interface CacheStore {
+    get(address: CacheAddress, signal?: AbortSignal): Promise<Uint8Array | undefined>;
+    put(address: CacheAddress, value: Uint8Array, signal?: AbortSignal): Promise<void>;
+    delete(address: CacheAddress, signal?: AbortSignal): Promise<void>;
+    clear(signal?: AbortSignal): Promise<void>;
+    snapshot(): CacheStoreSnapshot;
+}
+export declare function cacheAddressKey(address: CacheAddress): string;
+export declare class MemoryCacheStore implements CacheStore {
+    #private;
+    constructor(maxBytes?: number);
+    get(address: CacheAddress, signal?: AbortSignal): Promise<Uint8Array | undefined>;
+    put(address: CacheAddress, value: Uint8Array, signal?: AbortSignal): Promise<void>;
+    delete(address: CacheAddress, signal?: AbortSignal): Promise<void>;
+    clear(signal?: AbortSignal): Promise<void>;
+    snapshot(): CacheStoreSnapshot;
+}
+export declare class TieredCacheStore implements CacheStore {
+    readonly memory: CacheStore;
+    readonly persistent: CacheStore;
+    constructor(memory: CacheStore, persistent: CacheStore);
+    get(address: CacheAddress, signal?: AbortSignal): Promise<Uint8Array | undefined>;
+    put(address: CacheAddress, value: Uint8Array, signal?: AbortSignal): Promise<void>;
+    delete(address: CacheAddress, signal?: AbortSignal): Promise<void>;
+    clear(signal?: AbortSignal): Promise<void>;
+    snapshot(): CacheStoreSnapshot;
+}
+export interface SegmentedIndexChunk<T> {
+    readonly segment: number;
+    readonly startUs: number;
+    readonly durationUs: number;
+    readonly value: T;
+}
+export interface SegmentedIndexOptions<T> {
+    readonly durationUs: number;
+    readonly segmentDurationUs?: number;
+    readonly maxResidentSegments?: number;
+    readonly load: (startUs: number, durationUs: number, signal?: AbortSignal) => Promise<T>;
+}
+/** Lazy, bounded time segmentation for long-media indexes and derived data. */
+export declare class SegmentedIndex<T> {
+    #private;
+    constructor(options: SegmentedIndexOptions<T>);
+    segmentAt(timeUs: number, signal?: AbortSignal): Promise<SegmentedIndexChunk<T>>;
+    clear(): void;
+    snapshot(): {
+        readonly residentSegments: number;
+        readonly inFlightSegments: number;
+    };
+}
+//# sourceMappingURL=cache-store.d.ts.map

package/dist/cache-store.d.ts.map

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

package/dist/cache-store.js

@@ -0,0 +1,202 @@
+import { throwIfAborted } from '@aelionsdk/core';
+export function cacheAddressKey(address) {
+    if (!/^[0-9a-f]{64}$/u.test(address.contentHash) ||
+        address.version.length === 0 ||
+        address.version.length > 128) {
+        throw new TypeError('Cache address requires a SHA-256 content hash and bounded version');
+    }
+    return [address.namespace, address.contentHash, address.version, address.variant ?? ''].join(':');
+}
+export class MemoryCacheStore {
+    #entries = new Map();
+    #maxBytes;
+    #bytes = 0;
+    #clock = 0;
+    #hits = 0;
+    #misses = 0;
+    #evictions = 0;
+    constructor(maxBytes = 64 * 1_024 * 1_024) {
+        if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+            throw new RangeError('maxBytes must be a positive safe integer');
+        }
+        this.#maxBytes = maxBytes;
+    }
+    get(address, signal) {
+        throwIfAborted(signal, 'Cache read');
+        const entry = this.#entries.get(cacheAddressKey(address));
+        if (entry === undefined) {
+            this.#misses += 1;
+            return Promise.resolve(undefined);
+        }
+        this.#hits += 1;
+        entry.lastAccess = ++this.#clock;
+        return Promise.resolve(entry.value.slice());
+    }
+    put(address, value, signal) {
+        throwIfAborted(signal, 'Cache write');
+        if (value.byteLength > this.#maxBytes) {
+            throw new RangeError('Cache entry exceeds the store byte budget');
+        }
+        const key = cacheAddressKey(address);
+        const previous = this.#entries.get(key);
+        if (previous !== undefined)
+            this.#bytes -= previous.value.byteLength;
+        const copy = value.slice();
+        this.#entries.set(key, { value: copy, lastAccess: ++this.#clock });
+        this.#bytes += copy.byteLength;
+        while (this.#bytes > this.#maxBytes) {
+            let oldestKey;
+            let oldestAccess = Number.POSITIVE_INFINITY;
+            for (const [candidateKey, entry] of this.#entries) {
+                if (entry.lastAccess < oldestAccess) {
+                    oldestKey = candidateKey;
+                    oldestAccess = entry.lastAccess;
+                }
+            }
+            if (oldestKey === undefined)
+                break;
+            const oldest = this.#entries.get(oldestKey);
+            if (oldest !== undefined)
+                this.#bytes -= oldest.value.byteLength;
+            this.#entries.delete(oldestKey);
+            this.#evictions += 1;
+        }
+        return Promise.resolve();
+    }
+    delete(address, signal) {
+        throwIfAborted(signal, 'Cache delete');
+        const key = cacheAddressKey(address);
+        const entry = this.#entries.get(key);
+        if (entry !== undefined)
+            this.#bytes -= entry.value.byteLength;
+        this.#entries.delete(key);
+        return Promise.resolve();
+    }
+    clear(signal) {
+        throwIfAborted(signal, 'Cache clear');
+        this.#entries.clear();
+        this.#bytes = 0;
+        return Promise.resolve();
+    }
+    snapshot() {
+        return {
+            entries: this.#entries.size,
+            bytes: this.#bytes,
+            maxBytes: this.#maxBytes,
+            hits: this.#hits,
+            misses: this.#misses,
+            evictions: this.#evictions,
+        };
+    }
+}
+export class TieredCacheStore {
+    memory;
+    persistent;
+    constructor(memory, persistent) {
+        this.memory = memory;
+        this.persistent = persistent;
+    }
+    async get(address, signal) {
+        const hot = await this.memory.get(address, signal);
+        if (hot !== undefined)
+            return hot;
+        const cold = await this.persistent.get(address, signal);
+        if (cold !== undefined)
+            await this.memory.put(address, cold, signal);
+        return cold;
+    }
+    async put(address, value, signal) {
+        await this.persistent.put(address, value, signal);
+        await this.memory.put(address, value, signal);
+    }
+    async delete(address, signal) {
+        await Promise.all([
+            this.memory.delete(address, signal),
+            this.persistent.delete(address, signal),
+        ]);
+    }
+    async clear(signal) {
+        await Promise.all([this.memory.clear(signal), this.persistent.clear(signal)]);
+    }
+    snapshot() {
+        const memory = this.memory.snapshot();
+        const persistent = this.persistent.snapshot();
+        return {
+            entries: persistent.entries,
+            bytes: persistent.bytes,
+            maxBytes: persistent.maxBytes,
+            hits: memory.hits + persistent.hits,
+            misses: memory.misses + persistent.misses,
+            evictions: memory.evictions + persistent.evictions,
+        };
+    }
+}
+/** Lazy, bounded time segmentation for long-media indexes and derived data. */
+export class SegmentedIndex {
+    #options;
+    #segmentDurationUs;
+    #maxResidentSegments;
+    #segments = new Map();
+    #inFlight = new Map();
+    #clock = 0;
+    constructor(options) {
+        const segmentDurationUs = options.segmentDurationUs ?? 60_000_000;
+        const maxResidentSegments = options.maxResidentSegments ?? 8;
+        if (!Number.isSafeInteger(options.durationUs) ||
+            !Number.isSafeInteger(segmentDurationUs) ||
+            !Number.isSafeInteger(maxResidentSegments) ||
+            options.durationUs <= 0 ||
+            segmentDurationUs <= 0 ||
+            maxResidentSegments <= 0) {
+            throw new RangeError('Invalid segmented index limits');
+        }
+        this.#options = { ...options, segmentDurationUs, maxResidentSegments };
+        this.#segmentDurationUs = segmentDurationUs;
+        this.#maxResidentSegments = maxResidentSegments;
+    }
+    async segmentAt(timeUs, signal) {
+        if (!Number.isSafeInteger(timeUs) || timeUs < 0 || timeUs >= this.#options.durationUs) {
+            throw new RangeError('Segment time is outside the media duration');
+        }
+        throwIfAborted(signal, 'Segmented index');
+        const segmentDurationUs = this.#segmentDurationUs;
+        const segment = Math.floor(timeUs / segmentDurationUs);
+        const resident = this.#segments.get(segment);
+        if (resident !== undefined) {
+            resident.access = ++this.#clock;
+            return resident.chunk;
+        }
+        const pending = this.#inFlight.get(segment);
+        if (pending !== undefined)
+            return pending;
+        const startUs = segment * segmentDurationUs;
+        const durationUs = Math.min(segmentDurationUs, this.#options.durationUs - startUs);
+        const task = this.#options
+            .load(startUs, durationUs, signal)
+            .then(value => {
+            throwIfAborted(signal, 'Segmented index');
+            const chunk = { segment, startUs, durationUs, value };
+            this.#segments.set(segment, { chunk, access: ++this.#clock });
+            this.#evict();
+            return chunk;
+        })
+            .finally(() => this.#inFlight.delete(segment));
+        this.#inFlight.set(segment, task);
+        return task;
+    }
+    clear() {
+        this.#segments.clear();
+    }
+    snapshot() {
+        return { residentSegments: this.#segments.size, inFlightSegments: this.#inFlight.size };
+    }
+    #evict() {
+        const limit = this.#maxResidentSegments;
+        while (this.#segments.size > limit) {
+            const oldest = [...this.#segments.entries()].sort((left, right) => left[1].access - right[1].access)[0];
+            if (oldest === undefined)
+                return;
+            this.#segments.delete(oldest[0]);
+        }
+    }
+}

package/dist/image-adapter.d.ts

@@ -0,0 +1,35 @@
+import type { RangeReader } from './types.js';
+export interface DecodedStillImage {
+    readonly frame: VideoFrame;
+    readonly width: number;
+    readonly height: number;
+    readonly colorSpace: VideoColorSpaceInit;
+    close(): void;
+}
+export declare function decodeStillImage(blob: Blob, signal?: AbortSignal): Promise<DecodedStillImage>;
+export interface DecodeStillImageFromReaderOptions {
+    readonly mimeType?: string;
+    readonly maxBytes?: number;
+    readonly signal?: AbortSignal;
+}
+/** Decode a bounded still image from any registered range-backed source. */
+export declare function decodeStillImageFromReader(reader: RangeReader, options?: DecodeStillImageFromReaderOptions): Promise<DecodedStillImage>;
+export interface AnimatedImageInfo {
+    readonly mimeType: string;
+    readonly frameCount: number;
+    readonly repetitionCount: number;
+    readonly durationUs: number;
+    readonly frameDurationsUs: readonly number[];
+}
+export declare class AnimatedImageSource {
+    #private;
+    private constructor();
+    static open(blob: Blob, options?: {
+        readonly maxFrames?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<AnimatedImageSource>;
+    get info(): AnimatedImageInfo;
+    frameAt(timeUs: number, signal?: AbortSignal): Promise<VideoFrame>;
+    dispose(): void;
+}
+//# sourceMappingURL=image-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"image-adapter.d.ts","sourceRoot":"","sources":["../src/image-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;IACzC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,IAAI,EACV,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAyB5B;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,4EAA4E;AAC5E,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,iBAAiB,CAAC,CAqB5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,qBAAa,mBAAmB;;IAK9B,OAAO;WAKa,IAAI,CACtB,IAAI,EAAE,IAAI,EACV,OAAO,GAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GAC3E,OAAO,CAAC,mBAAmB,CAAC;IAyC/B,IAAW,IAAI,IAAI,iBAAiB,CAEnC;IAEY,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IA6BxE,OAAO,IAAI,IAAI;CAKvB"}

package/dist/image-adapter.js

@@ -0,0 +1,138 @@
+import { throwIfAborted } from '@aelionsdk/core';
+export async function decodeStillImage(blob, signal) {
+    throwIfAborted(signal, 'Still image decode');
+    const bitmap = await createImageBitmap(blob, {
+        imageOrientation: 'from-image',
+        premultiplyAlpha: 'none',
+        colorSpaceConversion: 'default',
+    });
+    try {
+        throwIfAborted(signal, 'Still image decode');
+        const frame = new VideoFrame(bitmap, { timestamp: 0 });
+        return {
+            frame,
+            width: frame.displayWidth,
+            height: frame.displayHeight,
+            colorSpace: {
+                primaries: frame.colorSpace.primaries,
+                transfer: frame.colorSpace.transfer,
+                matrix: frame.colorSpace.matrix,
+                fullRange: frame.colorSpace.fullRange,
+            },
+            close: () => frame.close(),
+        };
+    }
+    finally {
+        bitmap.close();
+    }
+}
+/** Decode a bounded still image from any registered range-backed source. */
+export async function decodeStillImageFromReader(reader, options = {}) {
+    const maxBytes = options.maxBytes ?? 64 * 1_024 * 1_024;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+        throw new RangeError('maxBytes must be a positive safe integer');
+    }
+    throwIfAborted(options.signal, 'Still image range decode');
+    const size = await reader.size(options.signal);
+    if (!Number.isSafeInteger(size) || size <= 0) {
+        throw new RangeError('Still image source must have a positive safe integer size');
+    }
+    if (size > maxBytes) {
+        throw new RangeError(`Still image exceeds the ${maxBytes.toString()} byte decode limit`);
+    }
+    const read = await reader.read({ offset: 0, length: size }, options.signal);
+    throwIfAborted(options.signal, 'Still image range decode');
+    return decodeStillImage(new Blob([read.bytes], {
+        type: options.mimeType ?? 'application/octet-stream',
+    }), options.signal);
+}
+export class AnimatedImageSource {
+    #decoder;
+    #info;
+    #disposed = false;
+    constructor(decoder, info) {
+        this.#decoder = decoder;
+        this.#info = info;
+    }
+    static async open(blob, options = {}) {
+        throwIfAborted(options.signal, 'Animated image open');
+        if (typeof ImageDecoder !== 'function') {
+            throw new DOMException('WebCodecs ImageDecoder is unavailable', 'NotSupportedError');
+        }
+        const supported = await ImageDecoder.isTypeSupported(blob.type);
+        if (!supported)
+            throw new DOMException(`Unsupported image type ${blob.type}`, 'NotSupportedError');
+        const decoder = new ImageDecoder({ type: blob.type, data: blob.stream() });
+        try {
+            await decoder.tracks.ready;
+            throwIfAborted(options.signal, 'Animated image open');
+            const track = decoder.tracks.selectedTrack;
+            if (track === null)
+                throw new Error('Animated image has no selected track');
+            const maxFrames = options.maxFrames ?? 10_000;
+            if (track.frameCount > maxFrames) {
+                throw new RangeError(`Animated image exceeds the ${maxFrames.toString()} frame limit`);
+            }
+            const frameDurationsUs = [];
+            for (let frameIndex = 0; frameIndex < track.frameCount; frameIndex += 1) {
+                throwIfAborted(options.signal, 'Animated image indexing');
+                const decoded = await decoder.decode({ frameIndex, completeFramesOnly: true });
+                try {
+                    frameDurationsUs.push(Math.max(1, decoded.image.duration ?? 1));
+                }
+                finally {
+                    decoded.image.close();
+                }
+            }
+            return new AnimatedImageSource(decoder, {
+                mimeType: blob.type,
+                frameCount: track.frameCount,
+                repetitionCount: track.repetitionCount,
+                durationUs: frameDurationsUs.reduce((sum, value) => sum + value, 0),
+                frameDurationsUs,
+            });
+        }
+        catch (error) {
+            decoder.close();
+            throw error;
+        }
+    }
+    get info() {
+        return this.#info;
+    }
+    async frameAt(timeUs, signal) {
+        if (this.#disposed)
+            throw new ReferenceError('AnimatedImageSource is disposed');
+        if (!Number.isSafeInteger(timeUs) || timeUs < 0) {
+            throw new RangeError('timeUs must be a non-negative safe integer');
+        }
+        throwIfAborted(signal, 'Animated image decode');
+        const loopDurationUs = this.#info.durationUs;
+        const localUs = this.#info.repetitionCount === 0
+            ? timeUs % loopDurationUs
+            : Math.min(timeUs, loopDurationUs * (this.#info.repetitionCount + 1) - 1) % loopDurationUs;
+        let accumulatedUs = 0;
+        let frameIndex = this.#info.frameCount - 1;
+        for (let index = 0; index < this.#info.frameDurationsUs.length; index += 1) {
+            accumulatedUs += this.#info.frameDurationsUs[index] ?? 0;
+            if (localUs < accumulatedUs) {
+                frameIndex = index;
+                break;
+            }
+        }
+        const decoded = await this.#decoder.decode({ frameIndex, completeFramesOnly: true });
+        try {
+            throwIfAborted(signal, 'Animated image decode');
+            return decoded.image.clone();
+        }
+        finally {
+            decoded.image.close();
+        }
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#decoder.close();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './cache-store.js';
+export * from './image-adapter.js';
+export * from './opfs-cache.js';
+export * from './proxy.js';
+export * from './range-reader.js';
+export * from './mediabunny-adapter.js';
+export * from './seek.js';
+export * from './types.js';
+export * from './resource-governor.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,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from './cache-store.js';
+export * from './image-adapter.js';
+export * from './opfs-cache.js';
+export * from './proxy.js';
+export * from './range-reader.js';
+export * from './mediabunny-adapter.js';
+export * from './seek.js';
+export * from './types.js';
+export * from './resource-governor.js';

package/dist/mediabunny-adapter.d.ts

@@ -0,0 +1,95 @@
+import { type Diagnostic } from '@aelionsdk/core';
+import type { MediaProbeOptions, SampleIndex, RangeReader } from './types.js';
+export declare function videoDecoderResourceSnapshot(): {
+    readonly activeDecoders: number;
+    readonly retainedFrames: number;
+};
+export declare function createSampleIndex(bytes: Uint8Array, options?: MediaProbeOptions): Promise<SampleIndex>;
+export declare function createSampleIndexFromReader(reader: RangeReader, options?: MediaProbeOptions): Promise<SampleIndex>;
+export declare function probeSampleIndex(bytes: Uint8Array, options?: MediaProbeOptions): Promise<{
+    readonly ok: true;
+    readonly index: SampleIndex;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+}>;
+export interface VideoDecodeResult {
+    readonly frame: VideoFrame;
+    readonly timestampUs: number;
+    readonly durationUs: number;
+    readonly decodedPackets: number;
+    readonly plannedPackets: number;
+    readonly decodeStartUs: number;
+    readonly targetUs: number;
+    close(): void;
+}
+export interface VideoDecodeOptions {
+    readonly signal?: AbortSignal;
+    readonly maxDecodeQueueSize?: number;
+    /** Zero-based index within the container's video tracks. */
+    readonly streamIndex?: number;
+    /** A caller-owned immutable index may be reused to avoid cold re-indexing on warm seeks. */
+    readonly sampleIndex?: SampleIndex;
+}
+export interface VideoFrameDecodeSessionOptions {
+    /** Zero-based index within the container's video tracks. */
+    readonly streamIndex?: number;
+    /** Maximum decoded frames retained by this session. */
+    readonly maxCachedFrames?: number;
+    /** Maximum decoded frame bytes retained by this session. */
+    readonly maxCachedBytes?: number;
+    /**
+     * Forward jumps larger than this restart at the nearest GOP instead of
+     * decoding every intervening frame.
+     */
+    readonly maxSequentialGapUs?: number;
+}
+export interface VideoFrameDecodeSessionSnapshot {
+    readonly streamIndex: number;
+    readonly cachedFrames: number;
+    readonly cachedBytes: number;
+    readonly maxCachedFrames: number;
+    readonly maxCachedBytes: number;
+    readonly maxSequentialGapUs: number;
+    readonly cacheHits: number;
+    readonly cacheMisses: number;
+    readonly seeks: number;
+    readonly sequentialFrames: number;
+    readonly resets: number;
+    readonly active: boolean;
+    readonly disposed: boolean;
+}
+export interface AudioPcmBlock {
+    readonly sampleRate: number;
+    readonly channelCount: number;
+    readonly startUs: number;
+    readonly durationUs: number;
+    readonly frameCount: number;
+    readonly interleaved: Float32Array;
+}
+export interface AudioDecodeOptions {
+    readonly signal?: AbortSignal;
+    readonly streamIndex?: number;
+}
+export declare function decodeAudioPcmRange(bytes: Uint8Array, startUs: number, durationUs: number, options?: AudioDecodeOptions): Promise<AudioPcmBlock>;
+/** Decode an audio interval without first loading the complete media resource. */
+export declare function decodeAudioPcmRangeFromReader(reader: RangeReader, startUs: number, durationUs: number, options?: AudioDecodeOptions): Promise<AudioPcmBlock>;
+/**
+ * A bounded, persistent video decoder session.
+ *
+ * Sequential requests share one Input, decoder and packet iterator. Backward
+ * seeks and large forward jumps restart at the nearest verified key packet.
+ * Returned frames are caller-owned; cached frames remain session-owned.
+ */
+export declare class VideoFrameDecodeSession {
+    #private;
+    constructor(reader: RangeReader, index: SampleIndex, options?: VideoFrameDecodeSessionOptions);
+    frameAt(targetUs: number, signal?: AbortSignal): Promise<VideoDecodeResult>;
+    snapshot(): VideoFrameDecodeSessionSnapshot;
+    dispose(): void;
+}
+export declare function createVideoFrameDecodeSessionFromReader(reader: RangeReader, index: SampleIndex, options?: VideoFrameDecodeSessionOptions): VideoFrameDecodeSession;
+export declare function decodeVideoFrameAt(bytes: Uint8Array, targetUs: number, options?: VideoDecodeOptions): Promise<VideoDecodeResult>;
+/** Decode an exact video frame using demand-driven byte-range reads. */
+export declare function decodeVideoFrameAtFromReader(reader: RangeReader, targetUs: number, options?: VideoDecodeOptions): Promise<VideoDecodeResult>;
+//# sourceMappingURL=mediabunny-adapter.d.ts.map

package/dist/mediabunny-adapter.d.ts.map

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