@aelionsdk/media 0.1.0-beta.1

package/dist/mediabunny-adapter.js

@@ -0,0 +1,769 @@
+import { throwIfAborted } from '@aelionsdk/core';
+import { ALL_FORMATS, AudioSampleSink, BufferSource, CustomSource, EncodedPacketSink, Input, MP4, VideoSampleSink, WEBM, } from 'mediabunny';
+import { resolveVideoSeek } from './seek.js';
+const MICROSECONDS_PER_SECOND = 1_000_000;
+let activeVideoDecoders = 0;
+let retainedVideoFrames = 0;
+function inputFromReader(reader, signal) {
+    return new Input({
+        source: new CustomSource({
+            getSize: () => reader.size(signal),
+            read: async (start, end) => {
+                const result = await reader.read({ offset: start, length: end - start }, signal);
+                return result.bytes;
+            },
+            maxCacheSize: 8 * 1_024 * 1_024,
+            prefetchProfile: reader.kind === 'network' ? 'network' : 'fileSystem',
+        }),
+        formats: ALL_FORMATS,
+    });
+}
+export function videoDecoderResourceSnapshot() {
+    return { activeDecoders: activeVideoDecoders, retainedFrames: retainedVideoFrames };
+}
+function secondsToUs(value, context) {
+    const microseconds = Math.round(value * MICROSECONDS_PER_SECOND);
+    if (!Number.isSafeInteger(microseconds)) {
+        throw new RangeError(`${context} is outside the safe microsecond range`);
+    }
+    return microseconds;
+}
+function diagnostic(code, message) {
+    return {
+        code,
+        severity: 'warning',
+        message,
+        recoverable: true,
+    };
+}
+function adapterLimitDiagnostics() {
+    return [
+        diagnostic('MEDIA_RAW_DTS_UNAVAILABLE', 'The container adapter exposes decode order and PTS, but not raw container DTS.'),
+        diagnostic('MEDIA_SAMPLE_OFFSET_UNAVAILABLE', 'The container adapter exposes encoded sample size, but not a stable physical byte offset.'),
+    ];
+}
+function codecFamily(codec) {
+    return codec ?? 'unknown';
+}
+function description(config) {
+    const source = config?.description;
+    if (source === undefined)
+        return undefined;
+    if (source instanceof ArrayBuffer)
+        return new Uint8Array(source.slice(0));
+    return new Uint8Array(source.buffer.slice(source.byteOffset, source.byteOffset + source.byteLength));
+}
+function copyVideoDecoderConfig(config) {
+    const configDescription = description(config);
+    return {
+        ...config,
+        ...(configDescription === undefined ? {} : { description: configDescription }),
+    };
+}
+async function videoTrackInfo(track) {
+    const [codec, codecString, width, height, rotation, timeResolution, config] = await Promise.all([
+        track.getCodec(),
+        track.getCodecParameterString(),
+        track.getCodedWidth(),
+        track.getCodedHeight(),
+        track.getRotation(),
+        track.getTimeResolution(),
+        track.getDecoderConfig(),
+    ]);
+    const configDescription = description(config);
+    return {
+        kind: 'video',
+        id: track.id,
+        codec: codecString ?? codec ?? 'unknown',
+        codecFamily: codecFamily(codec),
+        codedWidth: width,
+        codedHeight: height,
+        rotation,
+        timeBase: { numerator: 1, denominator: timeResolution },
+        ...(configDescription === undefined ? {} : { description: configDescription }),
+    };
+}
+async function audioTrackInfo(track) {
+    if (!track.isAudioTrack())
+        throw new TypeError('Track is not audio');
+    const [codec, codecString, sampleRate, channelCount, timeResolution, config] = await Promise.all([
+        track.getCodec(),
+        track.getCodecParameterString(),
+        track.getSampleRate(),
+        track.getNumberOfChannels(),
+        track.getTimeResolution(),
+        track.getDecoderConfig(),
+    ]);
+    const configDescription = description(config);
+    return {
+        kind: 'audio',
+        id: track.id,
+        codec: codecString ?? codec ?? 'unknown',
+        codecFamily: codecFamily(codec),
+        sampleRate,
+        channelCount,
+        timeBase: { numerator: 1, denominator: timeResolution },
+        ...(configDescription === undefined ? {} : { description: configDescription }),
+    };
+}
+function packetEntry(track, packet, decodeOrder, normalizedDecodeTimeUs) {
+    return {
+        trackId: track.id,
+        sampleIndex: decodeOrder,
+        kind: track.isVideoTrack() ? 'video' : 'audio',
+        decodeOrder,
+        presentationOrder: -1,
+        sourceSequenceNumber: packet.sequenceNumber,
+        presentationTimestampUs: packet.microsecondTimestamp,
+        durationUs: packet.microsecondDuration,
+        // Normalize the decode timeline to zero and accumulate durations in
+        // strict decode order. Raw container DTS origin remains adapter-private.
+        normalizedDecodeTimeUs,
+        isSync: packet.type === 'key',
+        byteLength: packet.byteLength,
+    };
+}
+function assignPresentationOrder(samples) {
+    const order = samples
+        .map((_, index) => index)
+        .sort((left, right) => {
+        const leftSample = samples[left];
+        const rightSample = samples[right];
+        return ((leftSample?.presentationTimestampUs ?? 0) - (rightSample?.presentationTimestampUs ?? 0) ||
+            left - right);
+    });
+    const position = new Map(order.map((sampleIndex, presentationOrder) => [sampleIndex, presentationOrder]));
+    return {
+        samples: samples.map(sample => ({
+            ...sample,
+            presentationOrder: position.get(sample.sampleIndex) ?? -1,
+        })),
+        presentationOrder: order,
+    };
+}
+async function indexTrack(track, signal) {
+    const sink = new EncodedPacketSink(track);
+    const samples = [];
+    let normalizedDecodeTimeUs = 0;
+    for await (const packet of sink.packets(undefined, undefined, { metadataOnly: true })) {
+        throwIfAborted(signal, 'media sample indexing');
+        samples.push(packetEntry(track, packet, samples.length, normalizedDecodeTimeUs));
+        normalizedDecodeTimeUs += packet.microsecondDuration;
+    }
+    return assignPresentationOrder(samples);
+}
+export async function createSampleIndex(bytes, options = {}) {
+    throwIfAborted(options.signal, 'media probe');
+    const input = new Input({
+        source: new BufferSource(bytes),
+        formats: ALL_FORMATS,
+    });
+    try {
+        const [format, durationSeconds, tracks] = await Promise.all([
+            input.getFormat(),
+            input.computeDuration(),
+            input.getTracks(),
+        ]);
+        throwIfAborted(options.signal, 'media probe');
+        const trackInfos = await Promise.all(tracks.map(track => (track.isVideoTrack() ? videoTrackInfo(track) : audioTrackInfo(track))));
+        const diagnostics = [...adapterLimitDiagnostics()];
+        const samples = {};
+        const presentationOrder = {};
+        if (options.includeSamples ?? true) {
+            for (const track of tracks) {
+                const indexed = await indexTrack(track, options.signal);
+                samples[track.id] = indexed.samples;
+                presentationOrder[track.id] = indexed.presentationOrder;
+            }
+        }
+        return {
+            schemaVersion: '1.0.0',
+            container: format === MP4 ? 'mp4' : format === WEBM ? 'webm' : 'unknown',
+            durationUs: secondsToUs(durationSeconds, 'media duration'),
+            tracks: trackInfos,
+            capabilities: {
+                timingAndSize: true,
+                rawDecodeTimestamps: false,
+                byteOffsets: false,
+            },
+            samples,
+            presentationOrder,
+            diagnostics,
+        };
+    }
+    finally {
+        input.dispose();
+    }
+}
+export async function createSampleIndexFromReader(reader, options = {}) {
+    throwIfAborted(options.signal, 'media range probe');
+    const input = inputFromReader(reader, options.signal);
+    try {
+        const [format, durationSeconds, tracks] = await Promise.all([
+            input.getFormat(),
+            input.computeDuration(),
+            input.getTracks(),
+        ]);
+        const trackInfos = await Promise.all(tracks.map(track => (track.isVideoTrack() ? videoTrackInfo(track) : audioTrackInfo(track))));
+        const samples = {};
+        const presentationOrder = {};
+        if (options.includeSamples ?? true) {
+            for (const track of tracks) {
+                const indexed = await indexTrack(track, options.signal);
+                samples[track.id] = indexed.samples;
+                presentationOrder[track.id] = indexed.presentationOrder;
+            }
+        }
+        return {
+            schemaVersion: '1.0.0',
+            container: format === MP4 ? 'mp4' : format === WEBM ? 'webm' : 'unknown',
+            durationUs: secondsToUs(durationSeconds, 'media duration'),
+            tracks: trackInfos,
+            capabilities: {
+                timingAndSize: true,
+                rawDecodeTimestamps: false,
+                byteOffsets: false,
+            },
+            samples,
+            presentationOrder,
+            diagnostics: adapterLimitDiagnostics(),
+        };
+    }
+    finally {
+        input.dispose();
+    }
+}
+export async function probeSampleIndex(bytes, options = {}) {
+    try {
+        return { ok: true, index: await createSampleIndex(bytes, options) };
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            diagnostics: [
+                {
+                    code: 'MEDIA_INPUT_INVALID',
+                    severity: 'error',
+                    message: cause instanceof Error ? cause.message : 'Input media is unsupported or corrupt',
+                    recoverable: false,
+                    cause,
+                },
+            ],
+        };
+    }
+}
+export async function decodeAudioPcmRange(bytes, startUs, durationUs, options = {}) {
+    return decodeAudioPcmRangeFromInput(new Input({ source: new BufferSource(bytes), formats: ALL_FORMATS }), startUs, durationUs, options);
+}
+/** Decode an audio interval without first loading the complete media resource. */
+export async function decodeAudioPcmRangeFromReader(reader, startUs, durationUs, options = {}) {
+    return decodeAudioPcmRangeFromInput(inputFromReader(reader, options.signal), startUs, durationUs, options);
+}
+async function decodeAudioPcmRangeFromInput(input, startUs, durationUs, options) {
+    throwIfAborted(options.signal, 'audio PCM decode');
+    if (!Number.isSafeInteger(startUs) ||
+        !Number.isSafeInteger(durationUs) ||
+        startUs < 0 ||
+        durationUs <= 0) {
+        throw new RangeError('Audio decode range must use non-negative safe integer microseconds');
+    }
+    try {
+        const tracks = await input.getAudioTracks();
+        const track = tracks[options.streamIndex ?? 0];
+        if (track === undefined)
+            throw new RangeError('Requested audio stream does not exist');
+        const sampleRate = await track.getSampleRate();
+        const channelCount = await track.getNumberOfChannels();
+        const frameCount = Math.ceil((durationUs * sampleRate) / MICROSECONDS_PER_SECOND);
+        const output = new Float32Array(frameCount * channelCount);
+        const sink = new AudioSampleSink(track);
+        const endUs = startUs + durationUs;
+        for await (const sample of sink.samples(startUs / MICROSECONDS_PER_SECOND, endUs / MICROSECONDS_PER_SECOND)) {
+            throwIfAborted(options.signal, 'audio PCM decode');
+            try {
+                const sampleStartFrame = Math.round(((sample.microsecondTimestamp - startUs) * sampleRate) / MICROSECONDS_PER_SECOND);
+                const sourceOffset = Math.max(0, -sampleStartFrame);
+                const destinationOffset = Math.max(0, sampleStartFrame);
+                const frames = Math.min(sample.numberOfFrames - sourceOffset, frameCount - destinationOffset);
+                if (frames <= 0)
+                    continue;
+                const copied = new Float32Array(frames * channelCount);
+                sample.copyTo(copied, {
+                    planeIndex: 0,
+                    format: 'f32',
+                    frameOffset: sourceOffset,
+                    frameCount: frames,
+                });
+                output.set(copied, destinationOffset * channelCount);
+            }
+            finally {
+                sample.close();
+            }
+        }
+        return {
+            sampleRate,
+            channelCount,
+            startUs,
+            durationUs,
+            frameCount,
+            interleaved: output,
+        };
+    }
+    finally {
+        input.dispose();
+    }
+}
+async function waitForDecodeCapacity(decoder, maxDecodeQueueSize, signal) {
+    while (decoder.decodeQueueSize >= maxDecodeQueueSize) {
+        throwIfAborted(signal, 'video exact seek');
+        await new Promise((resolve, reject) => {
+            const onAbort = () => {
+                decoder.removeEventListener('dequeue', onDequeue);
+                reject(new DOMException('Video decode wait was aborted', 'AbortError'));
+            };
+            const onDequeue = () => {
+                signal?.removeEventListener('abort', onAbort);
+                resolve();
+            };
+            decoder.addEventListener('dequeue', onDequeue, { once: true });
+            signal?.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+}
+function positiveSessionInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`${name} must be a positive safe integer`);
+    }
+    return value;
+}
+function videoFrameBytes(frame) {
+    try {
+        return frame.allocationSize();
+    }
+    catch {
+        return frame.codedWidth * frame.codedHeight * 4;
+    }
+}
+function decodeResultFromFrame(frame, options) {
+    let closed = false;
+    retainedVideoFrames += 1;
+    return {
+        frame,
+        ...options,
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            frame.close();
+            retainedVideoFrames -= 1;
+        },
+    };
+}
+function operationWithSignal(promise, signal) {
+    if (signal === undefined)
+        return promise;
+    throwIfAborted(signal, 'persistent video decode');
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            reject(signal.reason instanceof Error
+                ? signal.reason
+                : new DOMException('Persistent video decode was aborted', 'AbortError'));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        void promise.then(value => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(error instanceof Error ? error : new Error('Persistent video decode failed'));
+        });
+    });
+}
+/**
+ * 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 class VideoFrameDecodeSession {
+    #reader;
+    #index;
+    #streamIndex;
+    #videoInfo;
+    #maxCachedFrames;
+    #maxCachedBytes;
+    #maxSequentialGapUs;
+    #cache = new Map();
+    #input;
+    #iterator;
+    #current;
+    #lookahead;
+    #inputAbort;
+    #tail = Promise.resolve();
+    #clock = 0;
+    #cachedBytes = 0;
+    #cacheHits = 0;
+    #cacheMisses = 0;
+    #seeks = 0;
+    #sequentialFrames = 0;
+    #resets = 0;
+    #decoderActive = false;
+    #disposed = false;
+    constructor(reader, index, options = {}) {
+        this.#reader = reader;
+        this.#index = index;
+        this.#streamIndex = options.streamIndex ?? 0;
+        if (!Number.isSafeInteger(this.#streamIndex) || this.#streamIndex < 0) {
+            throw new RangeError('streamIndex must be a non-negative safe integer');
+        }
+        const videoInfo = index.tracks.filter(track => track.kind === 'video')[this.#streamIndex];
+        if (videoInfo === undefined)
+            throw new RangeError('Requested video stream does not exist');
+        this.#videoInfo = videoInfo;
+        this.#maxCachedFrames = positiveSessionInteger(options.maxCachedFrames ?? 24, 'maxCachedFrames');
+        this.#maxCachedBytes = positiveSessionInteger(options.maxCachedBytes ?? 96 * 1_024 * 1_024, 'maxCachedBytes');
+        this.#maxSequentialGapUs = positiveSessionInteger(options.maxSequentialGapUs ?? 3_000_000, 'maxSequentialGapUs');
+    }
+    frameAt(targetUs, signal) {
+        if (this.#disposed) {
+            return Promise.reject(new ReferenceError('VideoFrameDecodeSession is disposed'));
+        }
+        if (!Number.isSafeInteger(targetUs) || targetUs < 0) {
+            return Promise.reject(new RangeError('targetUs must be a non-negative safe integer'));
+        }
+        const operation = this.#tail.then(() => this.#frameAt(targetUs, signal));
+        this.#tail = operation.then(() => undefined, () => undefined);
+        return operation;
+    }
+    snapshot() {
+        return {
+            streamIndex: this.#streamIndex,
+            cachedFrames: this.#cache.size,
+            cachedBytes: this.#cachedBytes,
+            maxCachedFrames: this.#maxCachedFrames,
+            maxCachedBytes: this.#maxCachedBytes,
+            maxSequentialGapUs: this.#maxSequentialGapUs,
+            cacheHits: this.#cacheHits,
+            cacheMisses: this.#cacheMisses,
+            seeks: this.#seeks,
+            sequentialFrames: this.#sequentialFrames,
+            resets: this.#resets,
+            active: this.#decoderActive,
+            disposed: this.#disposed,
+        };
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        void this.#reset(false);
+        for (const cached of this.#cache.values()) {
+            cached.frame.close();
+            retainedVideoFrames -= 1;
+        }
+        this.#cache.clear();
+        this.#cachedBytes = 0;
+    }
+    async #frameAt(targetUs, signal) {
+        if (this.#disposed)
+            throw new ReferenceError('VideoFrameDecodeSession is disposed');
+        throwIfAborted(signal, 'persistent video decode');
+        const seek = resolveVideoSeek(this.#index, this.#videoInfo.id, targetUs);
+        const cached = this.#cache.get(seek.presentationUs);
+        if (cached !== undefined) {
+            cached.access = ++this.#clock;
+            this.#cacheHits += 1;
+            return decodeResultFromFrame(cached.frame.clone(), {
+                timestampUs: seek.presentationUs,
+                durationUs: cached.frame.duration ?? 0,
+                decodedPackets: 0,
+                plannedPackets: seek.samplesToDecode,
+                decodeStartUs: seek.decodeStartUs,
+                targetUs,
+            });
+        }
+        this.#cacheMisses += 1;
+        const currentUs = this.#current?.microsecondTimestamp;
+        if (currentUs === undefined ||
+            seek.presentationUs < currentUs ||
+            seek.presentationUs - currentUs > this.#maxSequentialGapUs) {
+            await this.#start(seek.presentationUs, signal);
+        }
+        let decodedSamples = 0;
+        while (this.#current !== undefined &&
+            this.#current.microsecondTimestamp < seek.presentationUs) {
+            const next = await this.#next(signal);
+            if (next === undefined)
+                break;
+            this.#current.close();
+            this.#current = next;
+            decodedSamples += 1;
+            this.#sequentialFrames += 1;
+        }
+        if (this.#current === undefined || this.#current.microsecondTimestamp !== seek.presentationUs) {
+            // A container/decoder may have produced an unexpected order. Restarting
+            // from the exact timestamp preserves the strict seek contract.
+            await this.#start(seek.presentationUs, signal);
+        }
+        if (this.#current === undefined || this.#current.microsecondTimestamp !== seek.presentationUs) {
+            throw new Error(`Persistent seek expected PTS ${seek.presentationUs}, received ${this.#current?.microsecondTimestamp ?? 'end-of-stream'}`);
+        }
+        const decodedFrame = this.#current.toVideoFrame();
+        const result = decodeResultFromFrame(decodedFrame.clone(), {
+            timestampUs: seek.presentationUs,
+            durationUs: this.#current.microsecondDuration,
+            decodedPackets: Math.max(1, decodedSamples),
+            plannedPackets: seek.samplesToDecode,
+            decodeStartUs: seek.decodeStartUs,
+            targetUs,
+        });
+        this.#cacheFrame(seek.presentationUs, decodedFrame);
+        return result;
+    }
+    async #start(targetUs, signal) {
+        await this.#reset();
+        throwIfAborted(signal, 'persistent video seek');
+        this.#inputAbort = new AbortController();
+        this.#input = inputFromReader(this.#reader, this.#inputAbort.signal);
+        try {
+            const tracks = await operationWithSignal(this.#input.getVideoTracks(), signal);
+            const track = tracks.find(candidate => candidate.id === this.#videoInfo.id);
+            if (track === undefined)
+                throw new Error('Indexed video track is missing from input');
+            const sink = new VideoSampleSink(track);
+            this.#iterator = sink.samples(targetUs / MICROSECONDS_PER_SECOND)[Symbol.asyncIterator]();
+            this.#decoderActive = true;
+            activeVideoDecoders += 1;
+            this.#seeks += 1;
+            const first = await this.#next(signal);
+            if (first === undefined)
+                throw new Error('Video stream ended before the requested timestamp');
+            this.#current = first;
+        }
+        catch (error) {
+            await this.#reset();
+            throw error;
+        }
+    }
+    async #next(signal) {
+        if (this.#lookahead !== undefined) {
+            const sample = this.#lookahead;
+            this.#lookahead = undefined;
+            return sample;
+        }
+        const iterator = this.#iterator;
+        if (iterator === undefined)
+            return undefined;
+        try {
+            const result = await operationWithSignal(iterator.next(), signal);
+            return result.done ? undefined : result.value;
+        }
+        catch (error) {
+            if (signal?.aborted ?? false)
+                await this.#reset();
+            throw error;
+        }
+    }
+    async #reset(countReset = true) {
+        const iterator = this.#iterator;
+        this.#iterator = undefined;
+        this.#inputAbort?.abort(new DOMException('Video decode session reset', 'AbortError'));
+        this.#inputAbort = undefined;
+        this.#current?.close();
+        this.#current = undefined;
+        this.#lookahead?.close();
+        this.#lookahead = undefined;
+        this.#input?.dispose();
+        this.#input = undefined;
+        if (this.#decoderActive) {
+            this.#decoderActive = false;
+            activeVideoDecoders -= 1;
+        }
+        if (iterator?.return !== undefined) {
+            try {
+                await iterator.return();
+            }
+            catch {
+                // The Input has already been disposed above.
+            }
+        }
+        if (countReset)
+            this.#resets += 1;
+    }
+    #cacheFrame(timestampUs, frame) {
+        const byteLength = videoFrameBytes(frame);
+        if (byteLength > this.#maxCachedBytes) {
+            frame.close();
+            return;
+        }
+        const previous = this.#cache.get(timestampUs);
+        if (previous !== undefined) {
+            previous.frame.close();
+            retainedVideoFrames -= 1;
+            this.#cachedBytes -= previous.byteLength;
+        }
+        this.#cache.set(timestampUs, {
+            frame,
+            byteLength,
+            access: ++this.#clock,
+        });
+        retainedVideoFrames += 1;
+        this.#cachedBytes += byteLength;
+        while (this.#cache.size > this.#maxCachedFrames || this.#cachedBytes > this.#maxCachedBytes) {
+            let oldestKey;
+            let oldestAccess = Number.POSITIVE_INFINITY;
+            for (const [key, value] of this.#cache) {
+                if (value.access < oldestAccess) {
+                    oldestKey = key;
+                    oldestAccess = value.access;
+                }
+            }
+            if (oldestKey === undefined)
+                break;
+            const oldest = this.#cache.get(oldestKey);
+            if (oldest === undefined)
+                break;
+            this.#cache.delete(oldestKey);
+            this.#cachedBytes -= oldest.byteLength;
+            oldest.frame.close();
+            retainedVideoFrames -= 1;
+        }
+    }
+}
+export function createVideoFrameDecodeSessionFromReader(reader, index, options = {}) {
+    return new VideoFrameDecodeSession(reader, index, options);
+}
+export async function decodeVideoFrameAt(bytes, targetUs, options = {}) {
+    const index = options.sampleIndex ??
+        (await createSampleIndex(bytes, options.signal === undefined ? {} : { signal: options.signal }));
+    return decodeVideoFrameAtFromInput(new Input({ source: new BufferSource(bytes), formats: ALL_FORMATS }), index, targetUs, options);
+}
+/** Decode an exact video frame using demand-driven byte-range reads. */
+export async function decodeVideoFrameAtFromReader(reader, targetUs, options = {}) {
+    const index = options.sampleIndex ??
+        (await createSampleIndexFromReader(reader, options.signal === undefined ? {} : { signal: options.signal }));
+    return decodeVideoFrameAtFromInput(inputFromReader(reader, options.signal), index, targetUs, options);
+}
+async function decodeVideoFrameAtFromInput(input, index, targetUs, options) {
+    throwIfAborted(options.signal, 'video exact seek');
+    if (!Number.isSafeInteger(targetUs) || targetUs < 0) {
+        throw new RangeError('targetUs must be a non-negative safe integer');
+    }
+    if (typeof VideoDecoder !== 'function')
+        throw new Error('VideoDecoder is unavailable');
+    const streamIndex = options.streamIndex ?? 0;
+    if (!Number.isSafeInteger(streamIndex) || streamIndex < 0) {
+        throw new RangeError('Video stream index must be a non-negative safe integer');
+    }
+    const videoInfo = index.tracks.filter(track => track.kind === 'video')[streamIndex];
+    if (videoInfo === undefined)
+        throw new RangeError('Requested video stream does not exist');
+    const seek = resolveVideoSeek(index, videoInfo.id, targetUs);
+    const targetSample = index.samples[videoInfo.id]?.[seek.presentationSample];
+    const decodeStartSample = index.samples[videoInfo.id]?.[seek.decodeStartSample];
+    if (targetSample === undefined || decodeStartSample === undefined) {
+        throw new Error('SampleIndex returned an invalid seek plan');
+    }
+    let decoder;
+    let selectedFrame;
+    let selectedTimestampUs = Number.MIN_SAFE_INTEGER;
+    let selectedDurationUs = 0;
+    let decodedPackets = 0;
+    let decoderCounted = false;
+    try {
+        const track = (await input.getVideoTracks()).find(candidate => candidate.id === videoInfo.id);
+        if (track === undefined)
+            throw new Error('Indexed video track is missing from input');
+        const config = await track.getDecoderConfig();
+        if (config === null)
+            throw new Error('Video decoder config is unavailable');
+        const supported = await VideoDecoder.isConfigSupported(config);
+        if (!supported.supported) {
+            throw new Error(`Video decoder config is unsupported: ${videoInfo.codec}`);
+        }
+        let decodeFailure;
+        decoder = new VideoDecoder({
+            output: frame => {
+                const frameTimestamp = frame.timestamp;
+                if (frameTimestamp <= targetUs && frameTimestamp >= selectedTimestampUs) {
+                    selectedFrame?.close();
+                    selectedFrame = frame;
+                    selectedTimestampUs = frameTimestamp;
+                    selectedDurationUs = frame.duration ?? 0;
+                }
+                else {
+                    frame.close();
+                }
+            },
+            error: error => {
+                decodeFailure = error;
+            },
+        });
+        activeVideoDecoders += 1;
+        decoderCounted = true;
+        decoder.configure(copyVideoDecoderConfig(config));
+        const sink = new EncodedPacketSink(track);
+        const startPacket = await sink.getKeyPacket(targetUs / MICROSECONDS_PER_SECOND, {
+            verifyKeyPackets: true,
+        });
+        if (startPacket === null)
+            throw new Error('No sync packet exists at or before target');
+        const stablePacketSequence = startPacket.sequenceNumber === decodeStartSample.sourceSequenceNumber;
+        const maxDecodeQueueSize = options.maxDecodeQueueSize ?? 16;
+        if (!Number.isSafeInteger(maxDecodeQueueSize) || maxDecodeQueueSize <= 0) {
+            throw new RangeError('maxDecodeQueueSize must be a positive safe integer');
+        }
+        for await (const packet of sink.packets(startPacket)) {
+            throwIfAborted(options.signal, 'video exact seek');
+            await waitForDecodeCapacity(decoder, maxDecodeQueueSize, options.signal);
+            decoder.decode(packet.toEncodedVideoChunk());
+            decodedPackets += 1;
+            // Some legal segmented containers assign accessor-local sequence numbers
+            // or conservatively verify a key packet before the indexed sync point.
+            // In that case, decode through the exact target PTS rather than trusting
+            // metadata-only sequence identity.
+            if ((stablePacketSequence && packet.sequenceNumber === targetSample.sourceSequenceNumber) ||
+                (!stablePacketSequence &&
+                    packet.microsecondTimestamp === targetSample.presentationTimestampUs)) {
+                break;
+            }
+        }
+        await decoder.flush();
+        if (decodeFailure !== undefined)
+            throw decodeFailure;
+        if (selectedFrame === undefined ||
+            selectedTimestampUs !== targetSample.presentationTimestampUs) {
+            throw new Error(`Exact seek expected PTS ${targetSample.presentationTimestampUs}, received ${selectedTimestampUs}`);
+        }
+        let closed = false;
+        const frame = selectedFrame;
+        retainedVideoFrames += 1;
+        return {
+            frame,
+            timestampUs: selectedTimestampUs,
+            durationUs: selectedDurationUs,
+            decodedPackets,
+            plannedPackets: stablePacketSequence ? seek.samplesToDecode : decodedPackets,
+            decodeStartUs: seek.decodeStartUs,
+            targetUs,
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                frame.close();
+                retainedVideoFrames -= 1;
+            },
+        };
+    }
+    catch (error) {
+        selectedFrame?.close();
+        throw error;
+    }
+    finally {
+        decoder?.close();
+        if (decoderCounted)
+            activeVideoDecoders -= 1;
+        input.dispose();
+    }
+}