libbitsub 1.6.0 → 1.7.1

package/dist/ts/renderers.js

@@ -4,14 +4,19 @@
  */
 import { initWasm } from './wasm';
 import { getOrCreateWorker, sendToWorker } from './worker';
-import { binarySearchTimestamp, convertFrameData, createWorkerState } from './utils';
+import { binarySearchTimestamp, convertFrameData, createWorkerSessionId, createWorkerState, detectSubtitleFormat, getSubtitleBounds, setCacheLimit as applyCacheLimit, setCachedFrame } from './utils';
 import { PgsParser, VobSubParserLowLevel } from './parsers';
 import { WebGPURenderer, isWebGPUSupported } from './webgpu-renderer';
 import { WebGL2Renderer, isWebGL2Supported } from './webgl2-renderer';
 /** Default display settings */
 const DEFAULT_DISPLAY_SETTINGS = {
     scale: 1.0,
-    verticalOffset: 0
+    verticalOffset: 0,
+    horizontalOffset: 0,
+    horizontalAlign: 'center',
+    bottomPadding: 0,
+    safeArea: 0,
+    opacity: 1.0
 };
 /**
  * Base class for video-integrated subtitle renderers.
@@ -19,6 +24,7 @@ const DEFAULT_DISPLAY_SETTINGS = {
  */
 class BaseVideoSubtitleRenderer {
     video;
+    format;
     subUrl;
     subContent;
     canvas = null;
@@ -32,8 +38,18 @@ class BaseVideoSubtitleRenderer {
     tempCanvas = null;
     tempCtx = null;
     lastRenderedData = null;
+    lastCueIndex = null;
+    currentCueMetadata = null;
+    parserMetadata = null;
     /** Display settings for subtitle rendering */
     displaySettings = { ...DEFAULT_DISPLAY_SETTINGS };
+    cacheLimit = 24;
+    prefetchBefore = 0;
+    prefetchAfter = 0;
+    onEvent;
+    currentRendererBackend = null;
+    loadedMetadataHandler = null;
+    seekedHandler = null;
     // WebGPU renderer (optional, falls back to WebGL2 then Canvas2D)
     webgpuRenderer = null;
     useWebGPU = false;
@@ -51,17 +67,39 @@ class BaseVideoSubtitleRenderer {
         fpsTimestamps: [],
         lastFrameTime: 0
     };
-    constructor(options) {
+    constructor(options, format) {
         this.video = options.video;
+        this.format = format;
         this.subUrl = options.subUrl;
         this.subContent = options.subContent;
         this.onWebGPUFallback = options.onWebGPUFallback;
         this.onWebGL2Fallback = options.onWebGL2Fallback;
+        this.onEvent = options.onEvent;
+        this.displaySettings = { ...DEFAULT_DISPLAY_SETTINGS, ...options.displaySettings };
+        this.cacheLimit = Math.max(0, Math.floor(options.cacheLimit ?? 24));
+        this.prefetchBefore = Math.max(0, Math.floor(options.prefetchWindow?.before ?? 0));
+        this.prefetchAfter = Math.max(0, Math.floor(options.prefetchWindow?.after ?? 0));
     }
     /** Get current display settings */
     getDisplaySettings() {
         return { ...this.displaySettings };
     }
+    /** Get parser metadata for the active subtitle track. */
+    getMetadata() {
+        return this.parserMetadata;
+    }
+    /** Get the most recently displayed cue metadata. */
+    getCurrentCueMetadata() {
+        return this.currentCueMetadata;
+    }
+    /** Get cue metadata for the specified index. */
+    getCueMetadata(index) {
+        return this.buildCueMetadata(index);
+    }
+    /** Get the configured frame-cache limit. */
+    getCacheLimit() {
+        return this.cacheLimit;
+    }
     /** Get base stats common to all renderers */
     getBaseStats() {
         const now = performance.now();
@@ -84,13 +122,18 @@ class BaseVideoSubtitleRenderer {
     }
     /** Set display settings and force re-render */
     setDisplaySettings(settings) {
-        const changed = settings.scale !== this.displaySettings.scale || settings.verticalOffset !== this.displaySettings.verticalOffset;
-        if (settings.scale !== undefined) {
-            this.displaySettings.scale = Math.max(0.1, Math.min(3.0, settings.scale));
-        }
-        if (settings.verticalOffset !== undefined) {
-            this.displaySettings.verticalOffset = Math.max(-50, Math.min(50, settings.verticalOffset));
-        }
+        const nextSettings = {
+            ...this.displaySettings,
+            ...settings
+        };
+        nextSettings.scale = Math.max(0.1, Math.min(3.0, nextSettings.scale));
+        nextSettings.verticalOffset = Math.max(-50, Math.min(50, nextSettings.verticalOffset));
+        nextSettings.horizontalOffset = Math.max(-50, Math.min(50, nextSettings.horizontalOffset));
+        nextSettings.bottomPadding = Math.max(0, Math.min(50, nextSettings.bottomPadding));
+        nextSettings.safeArea = Math.max(0, Math.min(25, nextSettings.safeArea));
+        nextSettings.opacity = Math.max(0, Math.min(1, nextSettings.opacity));
+        const changed = JSON.stringify(nextSettings) !== JSON.stringify(this.displaySettings);
+        this.displaySettings = nextSettings;
         // Force re-render if settings changed
         if (changed) {
             this.lastRenderedIndex = -1;
@@ -105,7 +148,9 @@ class BaseVideoSubtitleRenderer {
     }
     /** Start initialization. */
     startInit() {
-        this.init();
+        this.init().catch((error) => {
+            this.emitEvent({ type: 'error', format: this.format, error: error instanceof Error ? error : new Error(String(error)) });
+        });
     }
     /** Initialize the renderer. */
     async init() {
@@ -143,12 +188,44 @@ class BaseVideoSubtitleRenderer {
         this.updateCanvasSize();
         this.resizeObserver = new ResizeObserver(() => this.updateCanvasSize());
         this.resizeObserver.observe(this.video);
-        this.video.addEventListener('loadedmetadata', () => this.updateCanvasSize());
-        this.video.addEventListener('seeked', () => {
+        this.loadedMetadataHandler = () => this.updateCanvasSize();
+        this.seekedHandler = () => {
             this.lastRenderedIndex = -1;
             this.lastRenderedTime = -1;
             this.onSeek();
-        });
+        };
+        this.video.addEventListener('loadedmetadata', this.loadedMetadataHandler);
+        this.video.addEventListener('seeked', this.seekedHandler);
+    }
+    emitEvent(event) {
+        this.onEvent?.(event);
+    }
+    setParserMetadata(metadata) {
+        this.parserMetadata = metadata;
+        if (metadata) {
+            this.emitEvent({ type: 'loaded', format: this.format, metadata });
+        }
+    }
+    emitWorkerState(enabled, ready, sessionId, fallback = false) {
+        this.emitEvent({ type: 'worker-state', enabled, ready, sessionId, fallback });
+    }
+    emitCacheChange(cachedFrames, pendingRenders) {
+        this.emitEvent({ type: 'cache-change', cachedFrames, pendingRenders, cacheLimit: this.cacheLimit });
+    }
+    emitCueChange(cue) {
+        if (this.lastCueIndex === cue?.index && cue?.index !== undefined) {
+            this.currentCueMetadata = cue;
+            return;
+        }
+        this.lastCueIndex = cue?.index ?? null;
+        this.currentCueMetadata = cue;
+        this.emitEvent({ type: 'cue-change', cue });
+    }
+    emitRendererBackend(renderer) {
+        if (this.currentRendererBackend === renderer)
+            return;
+        this.currentRendererBackend = renderer;
+        this.emitEvent({ type: 'renderer-change', renderer });
     }
     /** Initialize WebGPU renderer. */
     async initWebGPU() {
@@ -162,10 +239,9 @@ class BaseVideoSubtitleRenderer {
             const height = Math.max(1, bounds.height * window.devicePixelRatio);
             await this.webgpuRenderer.setCanvas(this.canvas, width, height);
             this.useWebGPU = true;
-            console.log('[libbitsub] Using WebGPU renderer');
+            this.emitRendererBackend('webgpu');
         }
         catch (error) {
-            console.warn('[libbitsub] WebGPU init failed, falling back to WebGL2:', error);
             this.webgpuRenderer?.destroy();
             this.webgpuRenderer = null;
             this.useWebGPU = false;
@@ -191,10 +267,9 @@ class BaseVideoSubtitleRenderer {
             const height = Math.max(1, bounds.height * window.devicePixelRatio);
             await this.webgl2Renderer.setCanvas(this.canvas, width, height);
             this.useWebGL2 = true;
-            console.log('[libbitsub] Using WebGL2 renderer');
+            this.emitRendererBackend('webgl2');
         }
         catch (error) {
-            console.warn('[libbitsub] WebGL2 init failed, falling back to Canvas2D:', error);
             this.webgl2Renderer?.destroy();
             this.webgl2Renderer = null;
             this.useWebGL2 = false;
@@ -209,7 +284,7 @@ class BaseVideoSubtitleRenderer {
         this.ctx = this.canvas.getContext('2d');
         this.useWebGPU = false;
         this.useWebGL2 = false;
-        console.log('[libbitsub] Using Canvas2D renderer');
+        this.emitRendererBackend('canvas2d');
     }
     /** Called when video seeks. */
     onSeek() { }
@@ -307,6 +382,12 @@ class BaseVideoSubtitleRenderer {
                     }
                     this.lastRenderedIndex = currentIndex;
                     this.lastRenderedTime = currentTime;
+                    this.emitCueChange(currentIndex >= 0 ? this.buildCueMetadata(currentIndex) : null);
+                    this.emitEvent({ type: 'stats', stats: this.getStats() });
+                    if (currentIndex >= 0 && (this.prefetchBefore > 0 || this.prefetchAfter > 0)) {
+                        const prefetch = this.prefetchAroundTime;
+                        prefetch?.call(this, currentTime).catch(() => { });
+                    }
                 }
             }
             this.animationFrameId = requestAnimationFrame(render);
@@ -341,6 +422,59 @@ class BaseVideoSubtitleRenderer {
             this.renderFrameCanvas2D(data, index);
         }
     }
+    computeLayout(data) {
+        if (!this.canvas) {
+            return { scaleX: 1, scaleY: 1, shiftX: 0, shiftY: 0, opacity: this.displaySettings.opacity };
+        }
+        const baseScaleX = this.canvas.width / data.width;
+        const baseScaleY = this.canvas.height / data.height;
+        const bounds = getSubtitleBounds(data);
+        const { scale, verticalOffset, horizontalOffset, horizontalAlign, bottomPadding, safeArea, opacity } = this.displaySettings;
+        if (!bounds) {
+            return {
+                scaleX: baseScaleX * scale,
+                scaleY: baseScaleY * scale,
+                shiftX: (horizontalOffset / 100) * this.canvas.width,
+                shiftY: (verticalOffset / 100) * this.canvas.height - (bottomPadding / 100) * this.canvas.height,
+                opacity
+            };
+        }
+        const groupWidth = bounds.width * baseScaleX;
+        const groupHeight = bounds.height * baseScaleY;
+        const scaledGroupWidth = groupWidth * scale;
+        const scaledGroupHeight = groupHeight * scale;
+        let anchorShiftX = 0;
+        if (horizontalAlign === 'center') {
+            anchorShiftX = (groupWidth - scaledGroupWidth) / 2;
+        }
+        else if (horizontalAlign === 'right') {
+            anchorShiftX = groupWidth - scaledGroupWidth;
+        }
+        let shiftX = anchorShiftX + (horizontalOffset / 100) * this.canvas.width;
+        let shiftY = groupHeight - scaledGroupHeight + (verticalOffset / 100) * this.canvas.height;
+        shiftY -= (bottomPadding / 100) * this.canvas.height;
+        const safeX = (safeArea / 100) * this.canvas.width;
+        const safeY = (safeArea / 100) * this.canvas.height;
+        const finalMinX = bounds.x * baseScaleX + shiftX;
+        const finalMinY = bounds.y * baseScaleY + shiftY;
+        const finalMaxX = finalMinX + scaledGroupWidth;
+        const finalMaxY = finalMinY + scaledGroupHeight;
+        if (finalMinX < safeX)
+            shiftX += safeX - finalMinX;
+        if (finalMaxX > this.canvas.width - safeX)
+            shiftX -= finalMaxX - (this.canvas.width - safeX);
+        if (finalMinY < safeY)
+            shiftY += safeY - finalMinY;
+        if (finalMaxY > this.canvas.height - safeY)
+            shiftY -= finalMaxY - (this.canvas.height - safeY);
+        return {
+            scaleX: baseScaleX * scale,
+            scaleY: baseScaleY * scale,
+            shiftX,
+            shiftY,
+            opacity
+        };
+    }
     /** Render using WebGPU. */
     renderFrameWebGPU(data, index) {
         if (!this.webgpuRenderer || !this.canvas)
@@ -354,14 +488,8 @@ class BaseVideoSubtitleRenderer {
         // Store for potential reuse
         this.lastRenderedData = data;
         // Calculate base scale factors
-        const baseScaleX = this.canvas.width / data.width;
-        const baseScaleY = this.canvas.height / data.height;
-        // Apply display settings
-        const { scale, verticalOffset } = this.displaySettings;
-        const scaleX = baseScaleX * scale;
-        const scaleY = baseScaleY * scale;
-        const offsetY = (verticalOffset / 100) * this.canvas.height;
-        this.webgpuRenderer.render(data.compositionData, data.width, data.height, scaleX, scaleY, offsetY);
+        const layout = this.computeLayout(data);
+        this.webgpuRenderer.render(data.compositionData, data.width, data.height, layout.scaleX, layout.scaleY, layout.shiftX, layout.shiftY, layout.opacity);
     }
     /** Render using WebGL2. */
     renderFrameWebGL2(data, index) {
@@ -373,13 +501,8 @@ class BaseVideoSubtitleRenderer {
             return;
         }
         this.lastRenderedData = data;
-        const baseScaleX = this.canvas.width / data.width;
-        const baseScaleY = this.canvas.height / data.height;
-        const { scale, verticalOffset } = this.displaySettings;
-        const scaleX = baseScaleX * scale;
-        const scaleY = baseScaleY * scale;
-        const offsetY = (verticalOffset / 100) * this.canvas.height;
-        this.webgl2Renderer.render(data.compositionData, data.width, data.height, scaleX, scaleY, offsetY);
+        const layout = this.computeLayout(data);
+        this.webgl2Renderer.render(data.compositionData, data.width, data.height, layout.scaleX, layout.scaleY, layout.shiftX, layout.shiftY, layout.opacity);
     }
     /** Render using Canvas2D. */
     renderFrameCanvas2D(data, index) {
@@ -394,14 +517,9 @@ class BaseVideoSubtitleRenderer {
         }
         // Store for potential reuse
         this.lastRenderedData = data;
-        // Calculate base scale factors
-        const baseScaleX = this.canvas.width / data.width;
-        const baseScaleY = this.canvas.height / data.height;
-        // Apply display settings
-        const { scale, verticalOffset } = this.displaySettings;
-        const scaleX = baseScaleX * scale;
-        const scaleY = baseScaleY * scale;
-        const offsetY = (verticalOffset / 100) * this.canvas.height;
+        const layout = this.computeLayout(data);
+        this.ctx.save();
+        this.ctx.globalAlpha = layout.opacity;
         for (const comp of data.compositionData) {
             if (!this.tempCanvas || !this.tempCtx)
                 continue;
@@ -413,14 +531,13 @@ class BaseVideoSubtitleRenderer {
             this.tempCtx.putImageData(comp.pixelData, 0, 0);
             // Calculate position with scale and offset applied
             // Center the scaled content horizontally
-            const scaledWidth = comp.pixelData.width * scaleX;
-            const scaledHeight = comp.pixelData.height * scaleY;
-            const baseX = comp.x * baseScaleX;
-            const baseY = comp.y * baseScaleY;
-            const centeredX = baseX + (comp.pixelData.width * baseScaleX - scaledWidth) / 2;
-            const adjustedY = baseY + offsetY + (comp.pixelData.height * baseScaleY - scaledHeight);
-            this.ctx.drawImage(this.tempCanvas, centeredX, adjustedY, scaledWidth, scaledHeight);
+            const scaledWidth = comp.pixelData.width * layout.scaleX;
+            const scaledHeight = comp.pixelData.height * layout.scaleY;
+            const adjustedX = comp.x * (this.canvas.width / data.width) + layout.shiftX;
+            const adjustedY = comp.y * (this.canvas.height / data.height) + layout.shiftY;
+            this.ctx.drawImage(this.tempCanvas, adjustedX, adjustedY, scaledWidth, scaledHeight);
         }
+        this.ctx.restore();
     }
     /** Dispose of all resources. */
     dispose() {
@@ -431,6 +548,14 @@ class BaseVideoSubtitleRenderer {
         }
         this.resizeObserver?.disconnect();
         this.resizeObserver = null;
+        if (this.loadedMetadataHandler) {
+            this.video.removeEventListener('loadedmetadata', this.loadedMetadataHandler);
+            this.loadedMetadataHandler = null;
+        }
+        if (this.seekedHandler) {
+            this.video.removeEventListener('seeked', this.seekedHandler);
+            this.seekedHandler = null;
+        }
         // Clean up GPU renderers
         if (this.webgpuRenderer) {
             this.webgpuRenderer.destroy();
@@ -446,6 +571,8 @@ class BaseVideoSubtitleRenderer {
         this.tempCanvas = null;
         this.tempCtx = null;
         this.lastRenderedData = null;
+        this.currentCueMetadata = null;
+        this.parserMetadata = null;
         this.useWebGPU = false;
         this.useWebGL2 = false;
     }
@@ -461,14 +588,16 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
     onLoaded;
     onError;
     constructor(options) {
-        super(options);
+        super(options, 'pgs');
         this.onLoading = options.onLoading;
         this.onLoaded = options.onLoaded;
         this.onError = options.onError;
+        applyCacheLimit(this.state, this.cacheLimit);
         this.startInit();
     }
     async loadSubtitles() {
         try {
+            this.emitEvent({ type: 'loading', format: 'pgs' });
             this.onLoading?.();
             let arrayBuffer;
             if (this.subContent) {
@@ -486,16 +615,24 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
             const data = new Uint8Array(arrayBuffer);
             if (this.state.useWorker) {
                 try {
+                    this.state.sessionId = createWorkerSessionId();
                     await getOrCreateWorker();
-                    const loadResponse = await sendToWorker({ type: 'loadPgs', data: data.buffer.slice(0) });
+                    this.emitWorkerState(true, false, this.state.sessionId);
+                    const loadResponse = await sendToWorker({
+                        type: 'loadPgs',
+                        sessionId: this.state.sessionId,
+                        data: data.buffer.slice(0)
+                    });
                     if (loadResponse.type === 'pgsLoaded') {
                         this.state.workerReady = true;
-                        const tsResponse = await sendToWorker({ type: 'getPgsTimestamps' });
+                        this.state.metadata = loadResponse.metadata;
+                        const tsResponse = await sendToWorker({ type: 'getPgsTimestamps', sessionId: this.state.sessionId });
                         if (tsResponse.type === 'pgsTimestamps') {
                             this.state.timestamps = tsResponse.timestamps;
                         }
                         this.isLoaded = true;
-                        console.log(`[libbitsub] PGS loaded (worker): ${loadResponse.count} display sets from ${loadResponse.byteLength} bytes`);
+                        this.setParserMetadata(loadResponse.metadata);
+                        this.emitWorkerState(true, true, this.state.sessionId);
                         this.onLoaded?.();
                         return; // Success, don't fall through to main thread
                     }
@@ -504,8 +641,8 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
                     }
                 }
                 catch (workerError) {
-                    console.warn('[libbitsub] Worker failed, falling back to main thread:', workerError);
                     this.state.useWorker = false;
+                    this.emitWorkerState(false, false, this.state.sessionId, true);
                 }
             }
             // Main thread fallback - use idle callback to avoid blocking UI
@@ -513,8 +650,9 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
             this.onLoaded?.();
         }
         catch (error) {
-            console.error('Failed to load PGS subtitles:', error);
-            this.onError?.(error instanceof Error ? error : new Error(String(error)));
+            const resolvedError = error instanceof Error ? error : new Error(String(error));
+            this.emitEvent({ type: 'error', format: 'pgs', error: resolvedError });
+            this.onError?.(resolvedError);
         }
     }
     async loadOnMainThread(data) {
@@ -530,8 +668,9 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
             scheduleTask(() => {
                 const count = this.pgsParser.load(data);
                 this.state.timestamps = this.pgsParser.getTimestamps();
+                this.state.metadata = this.pgsParser.getMetadata();
                 this.isLoaded = true;
-                console.log(`[libbitsub] PGS loaded (main thread): ${count} display sets from ${data.byteLength} bytes`);
+                this.setParserMetadata(this.state.metadata);
                 resolve();
             });
         });
@@ -557,16 +696,22 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
         return this.pgsParser?.findIndexAtTimestamp(time) ?? -1;
     }
     renderAtIndex(index) {
+        if (this.state.frameCache.has(index)) {
+            return this.state.frameCache.get(index) ?? undefined;
+        }
         if (this.state.useWorker && this.state.workerReady) {
-            if (this.state.frameCache.has(index)) {
-                return this.state.frameCache.get(index) ?? undefined;
-            }
             if (!this.state.pendingRenders.has(index)) {
-                const renderPromise = sendToWorker({ type: 'renderPgsAtIndex', index }).then((response) => response.type === 'pgsFrame' && response.frame ? convertFrameData(response.frame) : null);
+                const renderPromise = sendToWorker({
+                    type: 'renderPgsAtIndex',
+                    sessionId: this.state.sessionId,
+                    index
+                }).then((response) => (response.type === 'pgsFrame' && response.frame ? convertFrameData(response.frame) : null));
                 this.state.pendingRenders.set(index, renderPromise);
+                this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
                 renderPromise.then((result) => {
-                    this.state.frameCache.set(index, result);
+                    setCachedFrame(this.state, index, result);
                     this.state.pendingRenders.delete(index);
+                    this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
                     // Force re-render on next frame by resetting lastRenderedIndex
                     if (this.findCurrentIndex(this.video.currentTime) === index) {
                         this.lastRenderedIndex = -1;
@@ -576,7 +721,32 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
             // Return undefined to indicate async loading in progress
             return undefined;
         }
-        return this.pgsParser?.renderAtIndex(index);
+        const rendered = this.pgsParser?.renderAtIndex(index) ?? null;
+        setCachedFrame(this.state, index, rendered);
+        this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
+        return rendered ?? undefined;
+    }
+    buildCueMetadata(index) {
+        if (this.pgsParser) {
+            return this.pgsParser.getCueMetadata(index);
+        }
+        const metadata = this.state.metadata;
+        if (!metadata || index < 0 || index >= this.state.timestamps.length)
+            return null;
+        const startTime = this.state.timestamps[index];
+        const endTime = this.state.timestamps[index + 1] ?? startTime + 5000;
+        const frame = this.state.frameCache.get(index) ?? null;
+        return {
+            index,
+            format: 'pgs',
+            startTime,
+            endTime,
+            duration: Math.max(0, endTime - startTime),
+            screenWidth: metadata.screenWidth,
+            screenHeight: metadata.screenHeight,
+            bounds: frame ? getSubtitleBounds(frame) : null,
+            compositionCount: frame?.compositionData.length ?? 0
+        };
     }
     isPendingRender(index) {
         return this.state.pendingRenders.has(index);
@@ -584,10 +754,43 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
     onSeek() {
         this.state.frameCache.clear();
         this.state.pendingRenders.clear();
+        this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
+        if (this.state.useWorker && this.state.workerReady) {
+            sendToWorker({ type: 'clearPgsCache', sessionId: this.state.sessionId }).catch(() => { });
+        }
+        this.pgsParser?.clearCache();
+    }
+    setCacheLimit(limit) {
+        this.cacheLimit = applyCacheLimit(this.state, limit);
+        this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
+    }
+    clearFrameCache() {
+        this.state.frameCache.clear();
+        this.state.pendingRenders.clear();
+        this.lastRenderedIndex = -1;
         if (this.state.useWorker && this.state.workerReady) {
-            sendToWorker({ type: 'clearPgsCache' }).catch(() => { });
+            sendToWorker({ type: 'clearPgsCache', sessionId: this.state.sessionId }).catch(() => { });
         }
         this.pgsParser?.clearCache();
+        this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
+    }
+    async prefetchRange(startIndex, endIndex) {
+        const safeStart = Math.max(0, Math.min(startIndex, endIndex));
+        const safeEnd = Math.min(Math.max(startIndex, endIndex), this.state.timestamps.length - 1);
+        for (let index = safeStart; index <= safeEnd; index++) {
+            if (this.state.frameCache.has(index))
+                continue;
+            const result = this.renderAtIndex(index);
+            if (result === undefined && this.state.pendingRenders.has(index)) {
+                await this.state.pendingRenders.get(index);
+            }
+        }
+    }
+    async prefetchAroundTime(time, before = this.prefetchBefore, after = this.prefetchAfter) {
+        const currentIndex = this.findCurrentIndex(time);
+        if (currentIndex < 0)
+            return;
+        await this.prefetchRange(currentIndex - before, currentIndex + after);
     }
     /** Get performance statistics for PGS renderer */
     getStats() {
@@ -605,10 +808,11 @@ export class PgsRenderer extends BaseVideoSubtitleRenderer {
         this.state.frameCache.clear();
         this.state.pendingRenders.clear();
         if (this.state.useWorker && this.state.workerReady) {
-            sendToWorker({ type: 'disposePgs' }).catch(() => { });
+            sendToWorker({ type: 'disposePgs', sessionId: this.state.sessionId }).catch(() => { });
         }
         this.pgsParser?.dispose();
         this.pgsParser = null;
+        this.state.sessionId = null;
     }
 }
 /**
@@ -628,18 +832,19 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
     cachedIndexTime = -1;
     pendingIndexLookup = null;
     constructor(options) {
-        super(options);
+        super(options, 'vobsub');
         this.idxUrl = options.idxUrl || (options.subUrl ? options.subUrl.replace(/\\.sub$/i, '.idx') : undefined);
         this.idxContent = options.idxContent;
         this.onLoading = options.onLoading;
         this.onLoaded = options.onLoaded;
         this.onError = options.onError;
+        applyCacheLimit(this.state, this.cacheLimit);
         this.startInit();
     }
     async loadSubtitles() {
         try {
+            this.emitEvent({ type: 'loading', format: 'vobsub' });
             this.onLoading?.();
-            console.log(`[libbitsub] Loading VobSub`);
             let subArrayBuffer;
             let idxData;
             // Resolve SUB content
@@ -685,23 +890,27 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
                 throw new Error('Failed to load VobSub data');
             }
             const subData = new Uint8Array(subArrayBuffer);
-            console.log(`[libbitsub] VobSub files loaded: .sub=${subArrayBuffer.byteLength} bytes, .idx=${idxData.length} chars`);
             if (this.state.useWorker) {
                 try {
+                    this.state.sessionId = createWorkerSessionId();
                     await getOrCreateWorker();
+                    this.emitWorkerState(true, false, this.state.sessionId);
                     const loadResponse = await sendToWorker({
                         type: 'loadVobSub',
+                        sessionId: this.state.sessionId,
                         idxContent: idxData,
                         subData: subData.buffer.slice(0)
                     });
                     if (loadResponse.type === 'vobSubLoaded') {
                         this.state.workerReady = true;
-                        const tsResponse = await sendToWorker({ type: 'getVobSubTimestamps' });
+                        this.state.metadata = loadResponse.metadata;
+                        const tsResponse = await sendToWorker({ type: 'getVobSubTimestamps', sessionId: this.state.sessionId });
                         if (tsResponse.type === 'vobSubTimestamps') {
                             this.state.timestamps = tsResponse.timestamps;
                         }
                         this.isLoaded = true;
-                        console.log(`[libbitsub] VobSub loaded (worker): ${loadResponse.count} subtitle entries`);
+                        this.setParserMetadata(loadResponse.metadata);
+                        this.emitWorkerState(true, true, this.state.sessionId);
                         this.onLoaded?.();
                         return; // Success, don't fall through to main thread
                     }
@@ -710,8 +919,8 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
                     }
                 }
                 catch (workerError) {
-                    console.warn('[libbitsub] Worker failed, falling back to main thread:', workerError);
                     this.state.useWorker = false;
+                    this.emitWorkerState(false, false, this.state.sessionId, true);
                 }
             }
             // Main thread fallback
@@ -719,8 +928,9 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
             this.onLoaded?.();
         }
         catch (error) {
-            console.error('Failed to load VobSub subtitles:', error);
-            this.onError?.(error instanceof Error ? error : new Error(String(error)));
+            const resolvedError = error instanceof Error ? error : new Error(String(error));
+            this.emitEvent({ type: 'error', format: 'vobsub', error: resolvedError });
+            this.onError?.(resolvedError);
         }
     }
     async loadOnMainThread(idxData, subData) {
@@ -735,8 +945,9 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
             scheduleTask(() => {
                 this.vobsubParser.loadFromData(idxData, subData);
                 this.state.timestamps = this.vobsubParser.getTimestamps();
-                console.log(`[libbitsub] VobSub loaded (main thread): ${this.vobsubParser.count} subtitle entries`);
+                this.state.metadata = this.vobsubParser.getMetadata();
                 this.isLoaded = true;
+                this.setParserMetadata(this.state.metadata);
                 resolve();
             });
         });
@@ -764,7 +975,11 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
             }
             // Start async lookup if not already pending
             if (!this.pendingIndexLookup) {
-                this.pendingIndexLookup = sendToWorker({ type: 'findVobSubIndex', timeMs }).then((response) => {
+                this.pendingIndexLookup = sendToWorker({
+                    type: 'findVobSubIndex',
+                    sessionId: this.state.sessionId,
+                    timeMs
+                }).then((response) => {
                     if (response.type === 'vobSubIndex') {
                         const newIndex = response.index;
                         const oldIndex = this.cachedIndex;
@@ -784,18 +999,23 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
         return this.vobsubParser?.findIndexAtTimestamp(time) ?? -1;
     }
     renderAtIndex(index) {
+        if (this.state.frameCache.has(index)) {
+            return this.state.frameCache.get(index) ?? undefined;
+        }
         if (this.state.useWorker && this.state.workerReady) {
-            // Return cached frame immediately if available
-            if (this.state.frameCache.has(index)) {
-                return this.state.frameCache.get(index) ?? undefined;
-            }
             // Start async render if not already pending
             if (!this.state.pendingRenders.has(index)) {
-                const renderPromise = sendToWorker({ type: 'renderVobSubAtIndex', index }).then((response) => response.type === 'vobSubFrame' && response.frame ? convertFrameData(response.frame) : null);
+                const renderPromise = sendToWorker({
+                    type: 'renderVobSubAtIndex',
+                    sessionId: this.state.sessionId,
+                    index
+                }).then((response) => (response.type === 'vobSubFrame' && response.frame ? convertFrameData(response.frame) : null));
                 this.state.pendingRenders.set(index, renderPromise);
+                this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
                 renderPromise.then((result) => {
-                    this.state.frameCache.set(index, result);
+                    setCachedFrame(this.state, index, result);
                     this.state.pendingRenders.delete(index);
+                    this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
                     // Force re-render on next frame by resetting lastRenderedIndex
                     if (this.findCurrentIndex(this.video.currentTime) === index) {
                         this.lastRenderedIndex = -1;
@@ -805,7 +1025,34 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
             // Return undefined to indicate async loading in progress
             return undefined;
         }
-        return this.vobsubParser?.renderAtIndex(index);
+        const rendered = this.vobsubParser?.renderAtIndex(index) ?? null;
+        setCachedFrame(this.state, index, rendered);
+        this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
+        return rendered ?? undefined;
+    }
+    buildCueMetadata(index) {
+        if (this.vobsubParser) {
+            return this.vobsubParser.getCueMetadata(index);
+        }
+        const metadata = this.state.metadata;
+        if (!metadata || index < 0 || index >= this.state.timestamps.length)
+            return null;
+        const startTime = this.state.timestamps[index];
+        const endTime = this.state.timestamps[index + 1] ?? startTime + 5000;
+        const frame = this.state.frameCache.get(index) ?? null;
+        return {
+            index,
+            format: 'vobsub',
+            startTime,
+            endTime,
+            duration: Math.max(0, endTime - startTime),
+            screenWidth: metadata.screenWidth,
+            screenHeight: metadata.screenHeight,
+            bounds: frame ? getSubtitleBounds(frame) : null,
+            compositionCount: frame?.compositionData.length ?? 0,
+            language: metadata.language ?? null,
+            trackId: metadata.trackId ?? null
+        };
     }
     isPendingRender(index) {
         return this.state.pendingRenders.has(index);
@@ -818,9 +1065,45 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
         this.cachedIndexTime = -1;
         this.pendingIndexLookup = null;
         if (this.state.useWorker && this.state.workerReady) {
-            sendToWorker({ type: 'clearVobSubCache' }).catch(() => { });
+            sendToWorker({ type: 'clearVobSubCache', sessionId: this.state.sessionId }).catch(() => { });
+        }
+        this.vobsubParser?.clearCache();
+        this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
+    }
+    setCacheLimit(limit) {
+        this.cacheLimit = applyCacheLimit(this.state, limit);
+        this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
+    }
+    clearFrameCache() {
+        this.state.frameCache.clear();
+        this.state.pendingRenders.clear();
+        this.cachedIndex = -1;
+        this.cachedIndexTime = -1;
+        this.pendingIndexLookup = null;
+        this.lastRenderedIndex = -1;
+        if (this.state.useWorker && this.state.workerReady) {
+            sendToWorker({ type: 'clearVobSubCache', sessionId: this.state.sessionId }).catch(() => { });
         }
         this.vobsubParser?.clearCache();
+        this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
+    }
+    async prefetchRange(startIndex, endIndex) {
+        const safeStart = Math.max(0, Math.min(startIndex, endIndex));
+        const safeEnd = Math.min(Math.max(startIndex, endIndex), this.state.timestamps.length - 1);
+        for (let index = safeStart; index <= safeEnd; index++) {
+            if (this.state.frameCache.has(index))
+                continue;
+            const result = this.renderAtIndex(index);
+            if (result === undefined && this.state.pendingRenders.has(index)) {
+                await this.state.pendingRenders.get(index);
+            }
+        }
+    }
+    async prefetchAroundTime(time, before = this.prefetchBefore, after = this.prefetchAfter) {
+        const currentIndex = this.findCurrentIndex(time);
+        if (currentIndex < 0)
+            return;
+        await this.prefetchRange(currentIndex - before, currentIndex + after);
     }
     /** Get performance statistics for VobSub renderer */
     getStats() {
@@ -836,32 +1119,35 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
     /** Enable or disable debanding filter */
     setDebandEnabled(enabled) {
         if (this.state.useWorker && this.state.workerReady) {
-            sendToWorker({ type: 'setVobSubDebandEnabled', enabled }).catch(() => { });
+            sendToWorker({ type: 'setVobSubDebandEnabled', sessionId: this.state.sessionId, enabled }).catch(() => { });
         }
         this.vobsubParser?.setDebandEnabled(enabled);
         // Clear cache to force re-render with new settings
         this.state.frameCache.clear();
         this.lastRenderedIndex = -1;
+        this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
     }
     /** Set debanding threshold (0-255, default: 64) */
     setDebandThreshold(threshold) {
         if (this.state.useWorker && this.state.workerReady) {
-            sendToWorker({ type: 'setVobSubDebandThreshold', threshold }).catch(() => { });
+            sendToWorker({ type: 'setVobSubDebandThreshold', sessionId: this.state.sessionId, threshold }).catch(() => { });
         }
         this.vobsubParser?.setDebandThreshold(threshold);
         // Clear cache to force re-render with new settings
         this.state.frameCache.clear();
         this.lastRenderedIndex = -1;
+        this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
     }
     /** Set debanding sample range in pixels (1-64, default: 15) */
     setDebandRange(range) {
         if (this.state.useWorker && this.state.workerReady) {
-            sendToWorker({ type: 'setVobSubDebandRange', range }).catch(() => { });
+            sendToWorker({ type: 'setVobSubDebandRange', sessionId: this.state.sessionId, range }).catch(() => { });
         }
         this.vobsubParser?.setDebandRange(range);
         // Clear cache to force re-render with new settings
         this.state.frameCache.clear();
         this.lastRenderedIndex = -1;
+        this.emitCacheChange(this.state.frameCache.size, this.state.pendingRenders.size);
     }
     /** Check if debanding is enabled */
     get debandEnabled() {
@@ -872,10 +1158,28 @@ export class VobSubRenderer extends BaseVideoSubtitleRenderer {
         this.state.frameCache.clear();
         this.state.pendingRenders.clear();
         if (this.state.useWorker && this.state.workerReady) {
-            sendToWorker({ type: 'disposeVobSub' }).catch(() => { });
+            sendToWorker({ type: 'disposeVobSub', sessionId: this.state.sessionId }).catch(() => { });
         }
         this.vobsubParser?.dispose();
         this.vobsubParser = null;
+        this.state.sessionId = null;
+    }
+}
+/** Create a video subtitle renderer with automatic format detection. */
+export function createAutoSubtitleRenderer(options) {
+    const format = detectSubtitleFormat({
+        data: options.subContent,
+        idxContent: options.idxContent,
+        fileName: options.fileName,
+        subUrl: options.subUrl,
+        idxUrl: options.idxUrl
+    });
+    if (format === 'pgs') {
+        return new PgsRenderer(options);
+    }
+    if (format === 'vobsub') {
+        return new VobSubRenderer(options);
     }
+    throw new Error('Unable to detect subtitle format for video renderer');
 }
 //# sourceMappingURL=renderers.js.map