@elah/core 0.1.0

package/dist/media/video/StreamingFrameProducer.js

@@ -0,0 +1,356 @@
+import { FrameCache } from './FrameCache';
+import { GpuDebugCounters } from '../../renderer/gpu/debug/GpuDebugCounters';
+import { VideoDecoderManager } from './VideoDecoderManager';
+const DEFAULT_FPS = 30;
+const DEFAULT_LOOKAHEAD_FRAMES = 16;
+const DEFAULT_MAX_FRAMES = 30;
+function makeFallbackBitmap(frame) {
+    return {
+        width: frame.displayWidth,
+        height: frame.displayHeight,
+        close() { },
+    };
+}
+const defaultFrameConverter = typeof createImageBitmap !== 'undefined'
+    ? (frame) => createImageBitmap(frame, { imageOrientation: 'flipY' })
+    : (frame) => Promise.resolve(makeFallbackBitmap(frame));
+const DEFAULT_IDLE_TIMEOUT_MS = 5000;
+const STALL_TICKS_BEFORE_RESET = 45;
+function _sfpTrace(msg, data) {
+    if (typeof globalThis !== 'undefined' && globalThis.__SFP_DEBUG__) {
+        if (data) {
+            console.log(`[SFP-TRACE] ${msg}`, data);
+        }
+        else {
+            console.log(`[SFP-TRACE] ${msg}`);
+        }
+    }
+}
+export class StreamingFrameProducer {
+    constructor(opts) {
+        this._state = 'active';
+        this._lastPlayhead = null;
+        this._latestPlayhead = null;
+        this._feedWatermark = -1;
+        this._highestDecodedFrame = -1;
+        this._ticksSinceDecodeAdvance = 0;
+        this._resetInProgress = false;
+        this._lastLoggedPlayhead = null;
+        this._idleTimer = null;
+        this._idleCallback = null;
+        this._openPromise = null;
+        this._openError = null;
+        this._reopening = false;
+        this._src = opts.src;
+        this._fps = opts.fps ?? DEFAULT_FPS;
+        this._lookaheadFrames = opts.lookaheadFrames ?? DEFAULT_LOOKAHEAD_FRAMES;
+        this._usPerFrame = 1000000 / this._fps;
+        this._convert = opts.frameConverter ?? defaultFrameConverter;
+        this._cache = new FrameCache({
+            maxFrames: opts.maxFrames ?? DEFAULT_MAX_FRAMES,
+            hooks: opts.cacheHooks,
+        });
+        this._manager = new VideoDecoderManager({
+            fps: this._fps,
+            demuxerFactory: opts.demuxerFactory,
+            decoderFactory: opts.decoderFactory,
+            onDroppedFrame: () => {
+                GpuDebugCounters.incDropped();
+            },
+            onError: (err) => {
+                if (this._state === 'disposed' || this._reopening)
+                    return;
+                console.warn('[StreamingFrameProducer] decoder errored — reopening manager:', err);
+                this._reopening = true;
+                this._lastPlayhead = null;
+                this._feedWatermark = -1;
+                this._highestDecodedFrame = -1;
+                this._ticksSinceDecodeAdvance = 0;
+                this._cache.clear();
+                GpuDebugCounters.cacheSize = 0;
+                _sfpTrace('manager error → reopen + bookkeeping reset', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                this._openPromise = this._manager
+                    .reopen(this._src)
+                    .catch((reopenErr) => {
+                    this._openError = reopenErr;
+                })
+                    .finally(() => {
+                    this._reopening = false;
+                });
+            },
+        });
+        this._manager.onFrame = (frame, sourceFrameIdx) => {
+            if (this._state === 'disposed') {
+                frame.close();
+                return;
+            }
+            const prevHighest = this._highestDecodedFrame;
+            if (prevHighest >= 0 && sourceFrameIdx > prevHighest + 1) {
+                _sfpTrace('onFrame INDEX GAP', {
+                    expected: prevHighest + 1,
+                    got: sourceFrameIdx,
+                    skipped: sourceFrameIdx - prevHighest - 1,
+                    rawTimestampUs: frame.timestamp,
+                    rawIndex: frame.timestamp / this._usPerFrame,
+                });
+            }
+            const timestampUs = frame.timestamp;
+            void this._copyAndCache(frame, sourceFrameIdx, timestampUs);
+        };
+        this._openPromise = this._manager.open(this._src).catch((err) => {
+            this._openError = err;
+        });
+        if (typeof globalThis !== 'undefined') {
+            ;
+            globalThis.__elahDrain = () => {
+                _sfpTrace('__elahDrain invoked — forcing decoder flush', {
+                    highestDecoded: this._highestDecodedFrame,
+                    cacheSize: this._cache.size,
+                });
+                return this._manager.debugFlush();
+            };
+        }
+        _sfpTrace('init', {
+            fps: this._fps,
+            usPerFrame: this._usPerFrame,
+            lookaheadFrames: this._lookaheadFrames,
+        });
+    }
+    getCurrent(sourceFrame) {
+        if (this._state === 'disposed')
+            return null;
+        this._cache.setPivot(sourceFrame);
+        const frame = this._cache.get(sourceFrame, 2);
+        if (frame !== null) {
+            GpuDebugCounters.cacheHits++;
+        }
+        else {
+            GpuDebugCounters.cacheMisses++;
+            _sfpTrace('getCurrent MISS', {
+                sourceFrame,
+                cacheSize: this._cache.size,
+                watermark: this._feedWatermark,
+                managerState: this._manager.state,
+                cacheKeys: this._cacheKeysSnapshot(),
+            });
+        }
+        GpuDebugCounters.cacheSize = this._cache.size;
+        return frame;
+    }
+    _cacheKeysSnapshot() {
+        const keys = [];
+        const cacheWithKeys = this._cache;
+        const frames = cacheWithKeys._frames;
+        if (frames) {
+            for (const k of frames.keys())
+                keys.push(k);
+        }
+        return keys.sort((a, b) => a - b);
+    }
+    setPlayhead(sourceFrame, opts) {
+        if (this._state === 'disposed')
+            return;
+        this._cache.setPivot(sourceFrame);
+        this._latestPlayhead = sourceFrame;
+        if (this._resetInProgress) {
+            _sfpTrace('setPlayhead while reset in-progress', {
+                sourceFrame,
+                latestPlayhead: this._latestPlayhead,
+            });
+            return;
+        }
+        if (sourceFrame > this._highestDecodedFrame) {
+            this._ticksSinceDecodeAdvance++;
+        }
+        else {
+            this._ticksSinceDecodeAdvance = 0;
+        }
+        const lookahead = opts?.lookaheadFrames ?? this._lookaheadFrames;
+        const watchdogDisabled = typeof globalThis !== 'undefined' &&
+            globalThis.__SFP_NO_WATCHDOG__ === true;
+        const stalled = !watchdogDisabled &&
+            this._lastPlayhead !== null &&
+            this._manager.state === 'Ready' &&
+            this._feedWatermark >= sourceFrame &&
+            this._ticksSinceDecodeAdvance > STALL_TICKS_BEFORE_RESET;
+        const goingBackward = this._lastPlayhead !== null && sourceFrame < this._lastPlayhead;
+        const backwardMiss = goingBackward && !this._cache.has(sourceFrame);
+        const isDiscontinuity = this._lastPlayhead === null ||
+            Math.abs(sourceFrame - this._lastPlayhead) > lookahead ||
+            stalled ||
+            backwardMiss;
+        if (isDiscontinuity || stalled || sourceFrame !== this._lastLoggedPlayhead) {
+            _sfpTrace('setPlayhead', {
+                sourceFrame,
+                lastPlayhead: this._lastPlayhead,
+                watermark: this._feedWatermark,
+                highestDecoded: this._highestDecodedFrame,
+                managerState: this._manager.state,
+                cacheSize: this._cache.size,
+                stalled,
+                backwardMiss,
+                isDiscontinuity,
+            });
+            this._lastLoggedPlayhead = sourceFrame;
+        }
+        if (isDiscontinuity) {
+            this._resetInProgress = true;
+            void this._handleDiscontinuity(sourceFrame, lookahead);
+            return;
+        }
+        this._lastPlayhead = sourceFrame;
+        this._feedWindow(sourceFrame, lookahead);
+    }
+    markIdle() {
+        if (this._state === 'disposed')
+            return;
+        this._state = 'idle';
+        this._clearIdleTimer();
+        this._idleTimer = setTimeout(() => {
+            this._idleCallback?.();
+        }, DEFAULT_IDLE_TIMEOUT_MS);
+        this._manager.markIdle();
+    }
+    markActive() {
+        if (this._state === 'disposed')
+            return;
+        this._clearIdleTimer();
+        this._state = 'active';
+        this._manager.markActive();
+    }
+    dispose() {
+        if (this._state === 'disposed')
+            return;
+        this._state = 'disposed';
+        this._clearIdleTimer();
+        this._manager.dispose();
+        this._cache.dispose();
+        GpuDebugCounters.cacheSize = 0;
+    }
+    get state() {
+        return this._state;
+    }
+    get decoderState() {
+        return this._manager.state;
+    }
+    get cacheSize() {
+        return this._cache.size;
+    }
+    get openError() {
+        return this._openError;
+    }
+    get openPromise() {
+        return this._openPromise;
+    }
+    setIdleCallback(cb) {
+        this._idleCallback = cb;
+    }
+    async _handleDiscontinuity(sourceFrame, lookahead) {
+        if (this._openPromise) {
+            await this._openPromise;
+            this._openPromise = null;
+        }
+        if (this._state === 'disposed') {
+            this._resetInProgress = false;
+            return;
+        }
+        if (this._manager.state !== 'Ready') {
+            this._resetInProgress = false;
+            return;
+        }
+        this._feedWatermark = -1;
+        let seekAnchorFrame = sourceFrame;
+        try {
+            const toKeyframeUs = Math.round(sourceFrame * this._usPerFrame);
+            await this._manager.reset(toKeyframeUs);
+            this._lastPlayhead = this._latestPlayhead ?? sourceFrame;
+            this._highestDecodedFrame = -1;
+            this._ticksSinceDecodeAdvance = 0;
+            seekAnchorFrame = sourceFrame;
+        }
+        catch {
+        }
+        finally {
+            this._resetInProgress = false;
+            if (this._latestPlayhead !== null) {
+                const targetPlayhead = this._latestPlayhead;
+                const totalLookahead = Math.max(targetPlayhead - seekAnchorFrame, 0) + lookahead;
+                _sfpTrace('_handleDiscontinuity complete → _feedWindow', {
+                    seekAnchorFrame,
+                    targetPlayhead,
+                    totalLookahead,
+                    watermark: this._feedWatermark,
+                });
+                this._feedWindow(seekAnchorFrame, totalLookahead);
+            }
+        }
+    }
+    _feedWindow(N, lookahead) {
+        if (this._state === 'disposed')
+            return;
+        if (this._manager.state !== 'Ready')
+            return;
+        const highWater = N + lookahead;
+        const lowWater = N + Math.floor(lookahead / 2);
+        if (this._feedWatermark >= lowWater)
+            return;
+        const feedStart = Math.max(this._feedWatermark + 1, N);
+        if (feedStart > highWater)
+            return;
+        const startUs = Math.round(feedStart * this._usPerFrame);
+        const endUs = Math.round((highWater + 1) * this._usPerFrame);
+        _sfpTrace('_feedWindow → manager.feed (burst)', {
+            N,
+            feedStart,
+            lowWater,
+            highWater,
+            burstFrames: highWater - feedStart + 1,
+            startUs,
+            endUs,
+            previousWatermark: this._feedWatermark,
+        });
+        this._manager.feed([startUs, endUs]);
+        this._feedWatermark = highWater;
+    }
+    async _copyAndCache(frame, sourceFrameIdx, timestampUs) {
+        let bitmap = null;
+        try {
+            bitmap = await this._convert(frame);
+        }
+        catch (err) {
+            _sfpTrace('onFrame convert FAILED', {
+                sourceFrameIdx,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        finally {
+            frame.close();
+        }
+        if (bitmap === null)
+            return;
+        if (this._state === 'disposed') {
+            bitmap.close();
+            return;
+        }
+        this._cache.put(sourceFrameIdx, bitmap);
+        if (sourceFrameIdx > this._highestDecodedFrame) {
+            this._highestDecodedFrame = sourceFrameIdx;
+            this._ticksSinceDecodeAdvance = 0;
+        }
+        GpuDebugCounters.cacheSize = this._cache.size;
+        _sfpTrace('onFrame → cache.put', {
+            sourceFrameIdx,
+            timestampUs,
+            cacheSize: this._cache.size,
+            lastPlayhead: this._lastPlayhead,
+        });
+    }
+    _clearIdleTimer() {
+        if (this._idleTimer !== null) {
+            clearTimeout(this._idleTimer);
+            this._idleTimer = null;
+        }
+    }
+}

package/dist/media/video/VideoDecoderManager.d.ts

@@ -0,0 +1,59 @@
+import { type DemuxerFactory } from './demuxer/MediabunnyDemuxer';
+export type DecoderState = 'Idle' | 'Opening' | 'Ready' | 'Resetting' | 'Draining' | 'Disposed' | 'Errored';
+export interface VideoDecoderLike {
+    state: string;
+    configure(config: VideoDecoderConfig): void;
+    decode(chunk: EncodedVideoChunk): void;
+    flush(): Promise<void>;
+    close(): void;
+    reset(): void;
+}
+export type VideoDecoderFactory = (output: (frame: VideoFrame) => void, error: (e: DOMException) => void) => VideoDecoderLike;
+export interface VideoDecoderManagerOptions {
+    demuxerFactory?: DemuxerFactory;
+    decoderFactory?: VideoDecoderFactory;
+    idleTimeoutMs?: number;
+    fps?: number;
+    onStateChange?: (state: DecoderState) => void;
+    onDroppedFrame?: (sourceFrameIdx: number) => void;
+    onError?: (error: Error) => void;
+}
+export declare class VideoDecoderManager {
+    onFrame: ((frame: VideoFrame, sourceFrameIdx: number) => void) | null;
+    private readonly _demuxerFactory;
+    private readonly _decoderFactory;
+    private readonly _idleTimeoutMs;
+    private readonly _fps;
+    private readonly _onStateChange;
+    private readonly _onDroppedFrame;
+    private readonly _onError;
+    private _state;
+    private _src;
+    private _demuxer;
+    private _decoder;
+    private _idleTimer;
+    private _idleCallback;
+    private _feedGeneration;
+    private _feedActive;
+    private _feedPendingRange;
+    constructor(options?: VideoDecoderManagerOptions);
+    get fps(): number;
+    get state(): DecoderState;
+    get src(): string | null;
+    setIdleCallback(cb: (() => void) | null): void;
+    open(src: string): Promise<void>;
+    reopen(src: string): Promise<void>;
+    feed(timeRangeUs: [number, number]): void;
+    reset(toKeyframeUs: number): Promise<void>;
+    debugFlush(): Promise<void>;
+    drain(): Promise<void>;
+    markIdle(): void;
+    markActive(): void;
+    dispose(): void;
+    private _feedAsync;
+    private _assertTransition;
+    private _transition;
+    private _handleError;
+    private _cleanupResources;
+    private _clearIdleTimer;
+}