libbitsub 1.10.2 → 1.12.0

package/README.md

@@ -1,6 +1,6 @@
 # libbit(map)sub
 
-High-performance WASM renderer for graphical subtitles (PGS, VobSub, and MKS-embedded VobSub), written in Rust.
+High-performance WASM renderer for graphical subtitles (PGS, VobSub, DVB-SUB, and MKS-embedded VobSub), written in Rust.
 
 Started as a fork of Arcus92's [libpgs-js](https://github.com/Arcus92/libpgs-js), this project was reworked for higher performance and broader format support. It keeps the familiar high-level PGS-oriented API while adding a lower-level parser surface, VobSub support, GPU backends, and worker-backed rendering.
 
@@ -8,9 +8,11 @@ Started as a fork of Arcus92's [libpgs-js](https://github.com/Arcus92/libpgs-js)
 
 - PGS (Blu-ray) subtitle parsing and rendering
 - VobSub (DVD) subtitle parsing and rendering
+- DVB-SUB (ETSI EN 300 743) parsing and rendering via PES/ES and `"DV"` PTS-framed dumps
 - Matroska `.mks` extraction for embedded `S_VOBSUB` tracks
 - WebGPU, WebGL2, and Canvas2D rendering with automatic fallback
 - Worker-backed parsing/rendering for large subtitle files
+- HTTP Range / streaming loads for large `.sup`, `.sub`, `.idx`, and `.mks` assets (progressive indexing where feasible)
 - Rich layout controls: scale, aspect mode, horizontal/vertical offsets, alignment, bottom padding, safe area, opacity
 - Cue metadata and parser introspection APIs
 - Rendered-frame export helpers for ImageData, ImageBitmap, Blob, and custom canvas targets
@@ -18,6 +20,7 @@ Started as a fork of Arcus92's [libpgs-js](https://github.com/Arcus92/libpgs-js)
 - Automatic format detection and unified loading helpers
 - First-class diagnostics with structured error codes, warning hooks, and render/cache snapshots
 - TypeScript support with exported event and metadata types
+- Optional player integrations for Video.js, Shaka Player, hls.js, and React (core stays dependency-free)
 
 ## Showcase
 
@@ -67,11 +70,11 @@ deno add jsr:@altq/libbitsub
 
 In most bundler-based projects, no manual worker setup is required. `libbitsub` now resolves the WASM asset relative to the package module URL, so bundlers such as Vite, webpack, and Rollup can emit the asset automatically.
 
-If your app serves package files in a way that does not expose that emitted WASM asset to the browser, you can still provide the legacy public fallback by copying the WASM file to `/libbitsub/libbitsub_bg.wasm`:
+If your app serves package files in a way that does not expose that emitted WASM asset to the browser, you can still provide the legacy public fallback by copying the WASM file and its JS glue to `/libbitsub/`:
 
 ```bash
 mkdir -p public/libbitsub
-cp node_modules/libbitsub/pkg/libbitsub_bg.wasm public/libbitsub/
+cp node_modules/libbitsub/pkg/libbitsub_bg.wasm node_modules/libbitsub/pkg/libbitsub.js public/libbitsub/
 ```
 
 The worker is still created inline. `workerUrl` remains in the option type only for compatibility and does not change runtime behavior.
@@ -110,6 +113,129 @@ const parser = new PgsParser()
 
 Calling `initWasm()` multiple times is safe (it deduplicates).
 
+### Worker prewarm (TV / players)
+
+On devices where the first subtitle track switch should not pay worker + WASM startup cost (for example TV apps), prewarm the shared parsing worker during app startup:
+
+```ts
+import { warmup, ready, PgsRenderer } from 'libbitsub'
+
+// Fire-and-forget at app boot (safe to call multiple times).
+void warmup()
+
+// Before the user changes tracks, ensure the worker is ready.
+await ready()
+
+const renderer = new PgsRenderer({ video: videoElement, subContent: trackBytes })
+```
+
+`warmup()` and `ready()` share a single worker-init promise with renderer creation. The shared worker is only published after in-worker WASM initialization succeeds. When Web Workers are unavailable, both resolve immediately and renderers use the main thread.
+
+### Range / streaming loads (TV / slow networks)
+
+URL-based loads (`subUrl` / `idxUrl`) use progressive fetch by default:
+
+- Probe HTTP Range support and, for large assets, download with Range chunks when the origin allows it
+- Stream the response body otherwise and report `load-progress` events
+- **PGS (`.sup`)**: feed chunks into the parser as they arrive so cues can be indexed before the full file finishes
+- **VobSub (`.idx` + `.sub`)**: parse the small `.idx` first for timestamps, then stream/Range-download the `.sub` body and attach packets
+- **MKS**: stream/Range-download the container first (Matroska extraction still needs the assembled payload), then parse
+- **In-memory** `subContent` / `idxContent` remains the simple full-buffer path
+
+```ts
+import { PgsRenderer } from 'libbitsub'
+
+const renderer = new PgsRenderer({
+  video: videoElement,
+  subUrl: '/subtitles/movie.sup',
+  // streamingLoad: true,  // default
+  // rangeRequests: true,  // default
+  onEvent: (event) => {
+    if (event.type === 'load-progress') {
+      console.log(event.strategy, event.loadedBytes, event.totalBytes, event.indexedCues)
+    }
+    if (event.type === 'indexed') {
+      console.log('cues ready', event.metadata.cueCount, event.partial ? '(partial)' : '(final)')
+    }
+  }
+})
+```
+
+Disable progressive behavior when you want a single blocking GET:
+
+```ts
+new PgsRenderer({ video, subUrl, streamingLoad: false, rangeRequests: false })
+```
+
+Low-level helpers are also exported: `probeRangeSupport()`, `fetchSubtitleAsset()`, and `fetchSubtitleText()`.
+
+## Player integrations
+
+Optional adapters ship as **subpath exports**. They wrap the high-level renderers for common players while keeping the core package free of player/React dependencies (peer deps are optional and only needed when you import that adapter).
+
+| Import                   | Adapter                                  | Optional peer       |
+| ------------------------ | ---------------------------------------- | ------------------- |
+| `libbitsub/videojs`      | Video.js plugin (`registerBitSubPlugin`) | `video.js` >= 7     |
+| `libbitsub/shaka`        | `attachBitSubToShaka(player, options)`   | `shaka-player` >= 4 |
+| `libbitsub/hlsjs`        | `attachBitSubToHls(hls, options)`        | `hls.js` >= 1       |
+| `libbitsub/react`        | `useBitSub` / `BitSubOverlay`            | `react` >= 18       |
+| `libbitsub/integrations` | Shared `attachBitSub` controller         | —                   |
+
+Copy-paste recipes live under [`examples/`](./examples).
+
+### Video.js
+
+```ts
+import videojs from 'video.js'
+import { registerBitSubPlugin } from 'libbitsub/videojs'
+
+registerBitSubPlugin(videojs)
+const player = videojs('my-video')
+const bitsub = player.bitsub({ subUrl: '/subs/movie.sup' })
+bitsub.load({ subUrl: '/subs/other.sup' })
+```
+
+### Shaka Player
+
+```ts
+import { attachBitSubToShaka } from 'libbitsub/shaka'
+
+const bitsub = attachBitSubToShaka(player, { subUrl: '/subs/movie.sup' })
+// later
+bitsub.dispose()
+```
+
+### hls.js
+
+```ts
+import Hls from 'hls.js'
+import { attachBitSubToHls } from 'libbitsub/hlsjs'
+
+const hls = new Hls()
+hls.loadSource(url)
+hls.attachMedia(video)
+const bitsub = attachBitSubToHls(hls, { subUrl: '/subs/movie.sup' })
+```
+
+### React
+
+```tsx
+import { useRef } from 'react'
+import { useBitSub } from 'libbitsub/react'
+
+function Player({ src, subUrl }: { src: string; subUrl: string }) {
+  const videoRef = useRef<HTMLVideoElement>(null)
+  useBitSub(videoRef, { subUrl })
+  return (
+    <div style={{ position: 'relative' }}>
+      <video ref={videoRef} src={src} controls playsInline />
+    </div>
+  )
+}
+```
+
+Bitmap PGS/VobSub/MKS tracks are external canvas overlays, not native HTML/TextTrack entries. Prefer deep imports so unused adapters stay out of your bundle.
+
 ## High-level video renderers
 
 The high-level API manages subtitle loading, canvas overlay creation, playback sync, resize handling, worker usage, and renderer fallback.
@@ -131,6 +257,7 @@ const renderer = new PgsRenderer({
   },
   cacheLimit: 32,
   prefetchWindow: { before: 1, after: 2 },
+  frameAwareSync: true,
   onWarning: (warning) => {
     console.warn(warning.code, warning.message, warning.details)
   },
@@ -144,6 +271,33 @@ const renderer = new PgsRenderer({
 renderer.dispose()
 ```
 
+Mount into a fullscreen shell or Shadow DOM root, reuse a player-owned canvas,
+cap high-DPI backing-store cost, or bypass automatic backend selection:
+
+```ts
+const renderer = new PgsRenderer({
+  video: videoElement,
+  subUrl: '/subtitles/movie.sup',
+  container: shadowRoot, // HTMLElement or ShadowRoot; defaults to video.parentElement
+  canvas: playerOverlayCanvas, // optional; remains mounted after dispose()
+  devicePixelRatioCap: 2,
+  backend: 'webgl2' // 'auto' | 'webgpu' | 'webgl2' | 'worker-offscreen' | 'canvas2d'
+})
+```
+
+An explicitly requested GPU or worker backend falls back to Canvas2D if it cannot
+initialize. A supplied `container` takes precedence over the canvas's current parent;
+without one, an already-mounted caller canvas stays in its existing host. Automatic
+selection does not transfer a caller-owned canvas to a worker; request
+`backend: 'worker-offscreen'` explicitly to allow that ownership transfer.
+
+Frame-aware synchronization is enabled by default. On browsers with
+`requestVideoFrameCallback()`, cue lookup uses the `mediaTime` of the frame sent
+to the compositor instead of polling `video.currentTime`. Older browsers fall
+back to `requestAnimationFrame()` automatically; set `frameAwareSync: false` to
+force that compatibility path. The active path is available as
+`renderer.getSynchronizationMode()` and as `getStats().syncMode`.
+
 ### VobSub renderer
 
 ```ts
@@ -165,6 +319,45 @@ renderer.setDebandThreshold(64)
 renderer.setDebandRange(15)
 ```
 
+### DVB renderer
+
+```ts
+import { DvbRenderer } from 'libbitsub'
+
+const renderer = new DvbRenderer({
+  video: videoElement,
+  subUrl: '/subtitles/track.dvb'
+})
+```
+
+DVB dumps use libbitsub framing:
+
+```
+"DV" | pts_90k_be_u32 | payload_len_be_u32 | payload…
+```
+
+`payload` is a PES data field (`0x20 0x00 …`) or raw segments (`sync_byte 0x0F`). Concatenated MPEG PES packets (`00 00 01 BD`) with PTS are also accepted.
+
+The DVB decoder renders bitmap object coding method 0. Character-string and reserved object coding methods are ignored.
+
+### Live / push streams
+
+PGS and DVB renderers can start without a URL or in-memory subtitle file. Push transport or demuxer chunks as they arrive; calls are processed in order even when they are made before renderer initialization completes.
+
+```ts
+import { DvbRenderer } from 'libbitsub'
+
+const renderer = new DvbRenderer({ video: videoElement })
+
+const added = await renderer.append(dvbPesChunk) // newly indexed cues
+const total = await renderer.flush() // finalize trailing input; total indexed cues
+
+await renderer.reset() // clear cues/caches/display, then reuse the same renderer
+await renderer.append(nextChannelChunk)
+```
+
+`append()` accepts `Uint8Array` or `ArrayBuffer` without detaching the caller's buffer. `flush()` discards incomplete trailing bytes; later appends are still accepted. `reset()` keeps the canvas, worker session, render loop, and configuration alive while clearing the stream state. VobSub does not expose the push API because it depends on its `.idx`/container index.
+
 ### Automatic format detection
 
 ```ts
@@ -177,7 +370,7 @@ const renderer = createAutoSubtitleRenderer({
 })
 ```
 
-Automatic detection uses file hints when available and otherwise inspects the binary payload. `.mks` sources are treated as VobSub only when they contain an embedded `S_VOBSUB` track. If the format cannot be identified confidently, it throws instead of silently forcing a parser.
+Automatic detection uses file hints when available and otherwise inspects the binary payload. `.idx` / `idxContent` still means VobSub. Bare `.sub` is content-probed for DVB before VobSub. `.mks` sources are treated as VobSub only when they contain an embedded `S_VOBSUB` track. If the format cannot be identified confidently, it throws instead of silently forcing a parser.
 
 ## Layout controls
 
@@ -207,16 +400,16 @@ renderer.resetDisplaySettings()
 
 `SubtitleDisplaySettings`:
 
-| Field | Type | Range / values | Meaning |
-| --- | --- | --- | --- |
-| `scale` | number | `0.1` to `3.0` | Overall subtitle scale |
-| `aspectMode` | `'stretch' \| 'contain' \| 'cover'` | fixed set | How subtitle screen coordinates map into the visible video box |
-| `verticalOffset` | number | `-50` to `50` | Vertical movement as percent of video height |
-| `horizontalOffset` | number | `-50` to `50` | Horizontal movement as percent of video width |
-| `horizontalAlign` | `'left' \| 'center' \| 'right'` | fixed set | Anchor used when scaling subtitle groups |
-| `bottomPadding` | number | `0` to `50` | Extra padding from the bottom edge |
-| `safeArea` | number | `0` to `25` | Clamp subtitles inside a video-safe area |
-| `opacity` | number | `0.0` to `1.0` | Global subtitle opacity |
+| Field              | Type                                | Range / values | Meaning                                                        |
+| ------------------ | ----------------------------------- | -------------- | -------------------------------------------------------------- |
+| `scale`            | number                              | `0.1` to `3.0` | Overall subtitle scale                                         |
+| `aspectMode`       | `'stretch' \| 'contain' \| 'cover'` | fixed set      | How subtitle screen coordinates map into the visible video box |
+| `verticalOffset`   | number                              | `-50` to `50`  | Vertical movement as percent of video height                   |
+| `horizontalOffset` | number                              | `-50` to `50`  | Horizontal movement as percent of video width                  |
+| `horizontalAlign`  | `'left' \| 'center' \| 'right'`     | fixed set      | Anchor used when scaling subtitle groups                       |
+| `bottomPadding`    | number                              | `0` to `50`    | Extra padding from the bottom edge                             |
+| `safeArea`         | number                              | `0` to `25`    | Clamp subtitles inside a video-safe area                       |
+| `opacity`          | number                              | `0.0` to `1.0` | Global subtitle opacity                                        |
 
 ## Metadata and introspection
 
@@ -291,14 +484,7 @@ Like `UnifiedSubtitleParser.loadAuto()`, this is a low-level in-memory API: pass
 Low-level parser output can be flattened into a single exportable frame for previews, editors, snapshots, fixture generation, or visual diffing.
 
 ```ts
-import {
-  PgsParser,
-  initWasm,
-  renderFrameData,
-  toBlob,
-  toCanvas,
-  toImageBitmap
-} from 'libbitsub'
+import { PgsParser, initWasm, renderFrameData, toBlob, toCanvas, toImageBitmap } from 'libbitsub'
 
 await initWasm()
 
@@ -385,7 +571,7 @@ Structured diagnostic error codes currently include:
 - `WORKER_FALLBACK`
 - `UNKNOWN`
 
-Warnings use a smaller code set focused on non-fatal conditions such as malformed bitmap buffers, worker fallback, and missing PGS palettes during render.
+Warnings use a smaller code set focused on non-fatal conditions such as malformed bitmap buffers, worker fallback, progressive/Range fallback (`RANGE_FALLBACK`), and missing PGS palettes during render.
 
 ## MKS security and corruption checks
 
@@ -415,6 +601,8 @@ const renderer = new PgsRenderer({
   onEvent: (event) => {
     switch (event.type) {
       case 'loading':
+      case 'load-progress':
+      case 'indexed':
       case 'loaded':
       case 'error':
       case 'warning':
@@ -482,17 +670,17 @@ renderer.dispose()
 
 Emitted events:
 
-| Event | Payload |
-| --- | --- |
-| `loading` | subtitle format |
-| `loaded` | subtitle format and parser metadata |
-| `error` | subtitle format and `SubtitleDiagnosticErrorLike` |
-| `warning` | `SubtitleDiagnosticWarning` |
-| `renderer-change` | active backend: `webgpu`, `webgl2`, or `canvas2d` |
-| `worker-state` | whether worker mode is enabled, ready, fallback status, and the active session ID |
-| `cache-change` | cached frame count, pending renders, and configured cache limit |
-| `cue-change` | current cue metadata or `null` when nothing is displayed |
-| `stats` | periodic renderer stats snapshot |
+| Event             | Payload                                                                           |
+| ----------------- | --------------------------------------------------------------------------------- |
+| `loading`         | subtitle format                                                                   |
+| `loaded`          | subtitle format and parser metadata                                               |
+| `error`           | subtitle format and `SubtitleDiagnosticErrorLike`                                 |
+| `warning`         | `SubtitleDiagnosticWarning`                                                       |
+| `renderer-change` | active backend: `webgpu`, `webgl2`, `worker-offscreen`, or `canvas2d`             |
+| `worker-state`    | whether worker mode is enabled, ready, fallback status, and the active session ID |
+| `cache-change`    | cached frame count, pending renders, and configured cache limit                   |
+| `cue-change`      | current cue metadata or `null` when nothing is displayed                          |
+| `stats`           | periodic renderer stats snapshot                                                  |
 
 ## Performance stats
 
@@ -514,6 +702,7 @@ const stats = renderer.getStats()
 - `pendingRenders`
 - `totalEntries`
 - `currentIndex`
+- `syncMode`
 
 `getCacheStats()` adds worker/session state for the current renderer cache, while `getLastRenderInfo()` exposes the most recent render outcome with a status of `rendered`, `cleared`, `pending`, `empty`, or `failed`.
 
@@ -563,23 +752,50 @@ const parser = new UnifiedSubtitleParser({
 parser.loadAuto({ data: subtitleBytes, fileName: 'track.sup' })
 ```
 
-## GPU backends
+## GPU / present backends
 
 libbitsub prefers:
 
-1. WebGPU
-2. WebGL2
-3. Canvas2D
+1. WebGPU (main-thread present)
+2. WebGL2 (main-thread present)
+3. Worker OffscreenCanvas (decode + Canvas2D present off the UI thread)
+4. Canvas2D (main-thread fallback for older TVs)
 
 ```ts
-import { isWebGPUSupported } from 'libbitsub'
+import { getRuntimeCapabilities, isWebGPUSupported } from 'libbitsub'
 
 console.log({
-  webgpu: isWebGPUSupported()
+  webgpu: isWebGPUSupported(),
+  capabilities: getRuntimeCapabilities()
 })
 ```
 
-WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2Fallback`, `onEvent`, or `onWarning` if you need to observe backend changes.
+When Worker OffscreenCanvas is selected, composition/present moves into the shared worker —
+not only parsing — which reduces UI stalls during subtitle track switches on constrained devices.
+The existing transferable RGBA path remains for main-thread GPU/Canvas2D present.
+
+Use `onWebGPUFallback`, `onWebGL2Fallback`, `onEvent`, `onWarning`, or `getRuntimeCapabilities()`
+to observe or explain the active backend path. Set `offscreenRender: false` to force main-thread
+Canvas2D on the software tier.
+
+## Compatibility & visual regression
+
+A formal suite locks decoder edge cases and backend pixel parity:
+
+- Malformed PGS / VobSub / MKS fixtures
+- Palette edge cases and zero-length RLE runs
+- Alternate display sizes (SD → 4K)
+- Slow worker startup / shared init
+- Pixel-level goldens across software, Canvas2D, WebGL2, and WebGPU
+
+```bash
+bun run test        # Rust core (includes compatibility fixtures)
+bun run test:ts     # TypeScript fixtures, goldens, worker startup
+bun run test:visual # Headless Chromium backend parity
+bun run test:all    # All of the above
+```
+
+Browser/device support matrix (including webOS TV): [docs/COMPATIBILITY.md](./docs/COMPATIBILITY.md).
 
 ## Notes
 
@@ -594,10 +810,13 @@ WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2
 
 - `initWasm(): Promise<void>` initializes the WASM module. Called automatically by high-level renderers and on first import in browser environments. Safe to call multiple times. Only needed explicitly for low-level parser usage.
 - `isWasmInitialized(): boolean` reports whether initialization has completed.
+- `warmup(): Promise<void>` / `ready(): Promise<void>` pre-initialize the shared subtitle worker (including in-worker WASM). Safe to call multiple times; concurrent callers share one init promise. Prefer these in TV/player apps before the first track switch.
+- `isWorkerAvailable(): boolean` / `isWorkerReady(): boolean` report worker support and whether the shared worker has finished initializing.
 - `isWebGPUSupported(): boolean` checks WebGPU support.
-- `detectSubtitleFormat(source: AutoSubtitleSource): 'pgs' | 'vobsub' | null` detects the bitmap subtitle format from file hints or binary data.
-- `createAutoSubtitleRenderer(options: AutoVideoSubtitleOptions): PgsRenderer | VobSubRenderer` creates a high-level renderer after format detection.
+- `detectSubtitleFormat(source: AutoSubtitleSource): 'pgs' | 'vobsub' | 'dvb' | null` detects the bitmap subtitle format from file hints or binary data.
+- `createAutoSubtitleRenderer(options: AutoVideoSubtitleOptions): PgsRenderer | VobSubRenderer | DvbRenderer` creates a high-level renderer after format detection.
 - `openSubtitles(source, options?): Promise<OpenedSubtitles>` initializes WASM, auto-detects the low-level format, and returns a normalized parser handle.
+- `probeRangeSupport(url, options?)` / `fetchSubtitleAsset(url, options?, onChunk?)` / `fetchSubtitleText(url, options?)` perform Range-aware progressive asset downloads for custom loaders.
 - `renderFrameData(frame, options?): SubtitleRenderedFrameData | null` composes a `SubtitleData` frame into exportable pixels.
 - `toCanvas(frame, target?, options?): HTMLCanvasElement | OffscreenCanvas` draws a rendered frame to a new or existing canvas/context.
 - `toImageBitmap(frame, options?): Promise<ImageBitmap>` creates an `ImageBitmap` from a subtitle frame export.
@@ -605,6 +824,7 @@ WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2
 - `SubtitleDiagnosticError` is the structured error class libbitsub uses for coded diagnostics.
 - `createSubtitleDiagnosticError(...)` and `normalizeSubtitleError(...)` are exported for integrations that want to preserve libbitsub-style error codes.
 - Legacy aliases remain exported: `PGSRenderer`, `VobsubRenderer`, `UnifiedSubtitleRenderer`.
+- Optional integration entry points: `libbitsub/videojs`, `libbitsub/shaka`, `libbitsub/hlsjs`, `libbitsub/react`, `libbitsub/integrations` (see [examples/](./examples) and [references/api.md](./references/api.md)).
 
 ### High-level renderers
 
@@ -625,21 +845,30 @@ WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2
 - `clearFrameCache(): void` clears the renderer-side and parser-side frame cache.
 - `prefetchRange(startIndex: number, endIndex: number): Promise<void>` prefetches decoded frames for a cue range.
 - `prefetchAroundTime(time: number, before?: number, after?: number): Promise<void>` prefetches around a playback time in seconds.
+- `append(data: Uint8Array | ArrayBuffer): Promise<number>` pushes live bytes and returns newly indexed cues.
+- `flush(): Promise<number>` finalizes trailing input and returns the total cue count.
+- `reset(): Promise<void>` clears live parser, cue, cache, and presentation state for reuse.
 - `dispose(): void` releases DOM, parser, and worker resources.
 
 #### `VobSubRenderer`
 
-- Supports all `PgsRenderer` methods above.
+- Supports the common `PgsRenderer` methods above, except `append()`, `flush()`, and `reset()`.
 - `setDebandEnabled(enabled: boolean): void` enables or disables debanding.
 - `setDebandThreshold(threshold: number): void` updates the deband threshold.
 - `setDebandRange(range: number): void` updates the deband sample range.
 - `debandEnabled: boolean` reports whether debanding is enabled.
 
+#### `DvbRenderer`
+
+- Supports all `PgsRenderer` methods above, including the live push API (no debanding).
+
 ### Low-level parsers
 
 #### `PgsParser`
 
-- `load(data: Uint8Array): number` loads PGS data and returns the cue count.
+- `load(data: Uint8Array): number` loads PGS data and returns the cue count (simple in-memory path).
+- `reset(): void` / `feed(data: Uint8Array): number` / `finishFeed(): number` progressive indexing APIs for streamed chunks.
+- `pendingLen: number` incomplete trailing bytes retained between `feed()` calls.
 - `getTimestamps(): Float64Array` returns cue timestamps in milliseconds.
 - `count: number` returns the number of cues.
 - `findIndexAtTimestamp(timeSeconds: number): number` finds the cue index for a playback time in seconds.
@@ -650,9 +879,18 @@ WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2
 - `clearCache(): void` clears parser-side caches.
 - `dispose(): void` frees parser resources.
 
+#### `DvbParser`
+
+- Same progressive surface as `PgsParser` for `"DV"`-framed dumps and MPEG PES streams.
+- `load(data: Uint8Array): number` / `feed` / `finishFeed` / `renderAtIndex` / `renderAtTimestamp` / `getMetadata` / `getCueMetadata` / `dispose`.
+- `getEndTimestamps(): Float64Array` returns the page-timeout-aware cue end timestamps in milliseconds.
+
 #### `VobSubParserLowLevel`
 
-- `loadFromData(idxContent: string, subData: Uint8Array): void` loads IDX and SUB data.
+- `loadFromData(idxContent: string, subData: Uint8Array): void` loads IDX and SUB data (simple in-memory path).
+- `loadFromIdx(idxContent: string): void` indexes timestamps from IDX before packet bytes arrive.
+- `attachSubData(subData: Uint8Array): void` attaches `.sub` packets after an IDX-first load.
+- `hasSubData: boolean` whether packet bytes are currently attached.
 - `loadFromSubOnly(subData: Uint8Array): void` loads SUB-only VobSub data.
 - `getTimestamps(): Float64Array`, `count`, `findIndexAtTimestamp()`, `renderAtIndex()`, `renderAtTimestamp()`, `getMetadata()`, `getCueMetadata()`, `clearCache()`, and `dispose()` behave like `PgsParser`.
 - `setDebandEnabled(enabled: boolean): void`, `setDebandThreshold(threshold: number): void`, `setDebandRange(range: number): void`, and `debandEnabled` control debanding.
@@ -662,8 +900,9 @@ WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2
 - `loadPgs(data: Uint8Array): number` loads PGS data.
 - `loadVobSub(idxContent: string, subData: Uint8Array): void` loads VobSub from IDX and SUB.
 - `loadVobSubOnly(subData: Uint8Array): void` loads SUB-only VobSub data.
+- `loadDvb(data: Uint8Array): number` loads DVB data.
 - `loadAuto(source: AutoSubtitleSource): SubtitleFormatName` detects and loads a supported bitmap subtitle format.
-- `format: 'pgs' | 'vobsub' | null` returns the active format.
+- `format: 'pgs' | 'vobsub' | 'dvb' | null` returns the active format.
 - `getTimestamps()`, `count`, `findIndexAtTimestamp()`, `renderAtIndex()`, `renderAtTimestamp()`, `getMetadata()`, `getCueMetadata()`, `clearCache()`, and `dispose()` are available as on the format-specific parsers.
 
 ### Core option and data types
@@ -673,6 +912,10 @@ WebGL2 and Canvas2D fallback remain automatic. Use `onWebGPUFallback`, `onWebGL2
 ```ts
 interface VideoSubtitleOptions {
   video: HTMLVideoElement
+  container?: HTMLElement | ShadowRoot
+  canvas?: HTMLCanvasElement
+  devicePixelRatioCap?: number
+  backend?: 'auto' | 'webgpu' | 'webgl2' | 'worker-offscreen' | 'canvas2d'
   subUrl?: string
   subContent?: ArrayBuffer
   workerUrl?: string
@@ -681,12 +924,16 @@ interface VideoSubtitleOptions {
   onError?: (error: Error) => void
   onWebGPUFallback?: () => void
   onWebGL2Fallback?: () => void
+  offscreenRender?: boolean // default true — Worker OffscreenCanvas on Canvas2D tier
+  frameAwareSync?: boolean // default true — sync to presented-frame mediaTime when available
   displaySettings?: Partial<SubtitleDisplaySettings>
   cacheLimit?: number
   prefetchWindow?: {
     before?: number
     after?: number
   }
+  streamingLoad?: boolean // default true — progressive URL loads
+  rangeRequests?: boolean // default true — use HTTP Range when supported
   onEvent?: (event: SubtitleRendererEvent) => void
 }
 ```
@@ -733,7 +980,7 @@ type SubtitleRendererEvent =
   | { type: 'loaded'; format: SubtitleFormatName; metadata: SubtitleParserMetadata }
   | { type: 'error'; format: SubtitleFormatName; error: SubtitleDiagnosticErrorLike }
   | { type: 'warning'; warning: SubtitleDiagnosticWarning }
-  | { type: 'renderer-change'; renderer: 'webgpu' | 'webgl2' | 'canvas2d' }
+  | { type: 'renderer-change'; renderer: 'webgpu' | 'webgl2' | 'worker-offscreen' | 'canvas2d' }
   | { type: 'worker-state'; enabled: boolean; ready: boolean; sessionId: string | null; fallback?: boolean }
   | { type: 'cache-change'; cachedFrames: number; pendingRenders: number; cacheLimit: number }
   | { type: 'cue-change'; cue: SubtitleCueMetadata | null }
@@ -766,7 +1013,7 @@ Related diagnostics shapes:
 
 ```ts
 interface SubtitleParserMetadata {
-  format: 'pgs' | 'vobsub'
+  format: 'pgs' | 'vobsub' | 'dvb'
   cueCount: number
   screenWidth: number
   screenHeight: number

package/dist/index.d.ts

@@ -3,9 +3,9 @@
  *
  * @packageDocumentation
  */
-export { PgsRenderer, VobSubRenderer, createAutoSubtitleRenderer, type VideoSubtitleOptions, type VideoVobSubOptions, type SubtitleRendererStats } from './wrapper';
-export { PgsParser, VobSubParserLowLevel, UnifiedSubtitleParser, openSubtitles } from './wrapper';
-export { initWasm, isWasmInitialized, isWebGPUSupported, detectSubtitleFormat, renderFrameData, toBlob, toCanvas, toImageBitmap, createSubtitleDiagnosticError, normalizeSubtitleError, SubtitleDiagnosticError, type AutoSubtitleSource, type AutoVideoSubtitleOptions, type OpenedSubtitles, type SubtitleAspectMode, type SubtitleCacheStats, type SubtitleCueBounds, type SubtitleCueMetadata, type SubtitleData, type SubtitleDiagnosticDetailValue, type SubtitleDiagnosticErrorCode, type SubtitleDiagnosticErrorLike, type SubtitleDiagnosticsOptions, type SubtitleDiagnosticWarning, type SubtitleDiagnosticWarningCode, type SubtitleCompositionData, type SubtitleDisplaySettings, type SubtitleFrameCanvasOptions, type SubtitleFrameCanvasTarget, type SubtitleFrameCropMode, type SubtitleFrameRenderOptions, type SubtitleRenderedFrameData, type SubtitleFormatName, type SubtitleHorizontalAlign, type SubtitleLastRenderInfo, type SubtitleParserMetadata, type SubtitleRendererBackend, type SubtitleRendererEvent, type SubtitleRendererStatsSnapshot } from './wrapper';
+export { PgsRenderer, DvbRenderer, VobSubRenderer, createAutoSubtitleRenderer, type VideoSubtitleOptions, type VideoVobSubOptions, type SubtitleRendererStats } from './wrapper';
+export { PgsParser, DvbParser, VobSubParserLowLevel, UnifiedSubtitleParser, openSubtitles } from './wrapper';
+export { initWasm, isWasmInitialized, isWebGPUSupported, isWorkerAvailable, isWorkerReady, warmup, ready, getRuntimeCapabilities, canUseWorkerOffscreenRender, isOffscreenCanvasSupported, isOffscreenCanvas2DSupported, isTransferControlToOffscreenSupported, isCanvas2DSupported, detectSubtitleFormat, fetchSubtitleAsset, fetchSubtitleText, probeRangeSupport, renderFrameData, toBlob, toCanvas, toImageBitmap, createSubtitleDiagnosticError, normalizeSubtitleError, SubtitleDiagnosticError, type AssetFetchOptions, type AssetFetchProgress, type AssetFetchStrategy, type AutoSubtitleSource, type AutoVideoSubtitleOptions, type LiveSubtitleRenderer, type OpenedSubtitles, type RangeProbeResult, type RuntimeCapabilities, type SubtitleAspectMode, type SubtitleCacheStats, type SubtitleCueBounds, type SubtitleCueMetadata, type SubtitleData, type SubtitleDiagnosticDetailValue, type SubtitleDiagnosticErrorCode, type SubtitleDiagnosticErrorLike, type SubtitleDiagnosticsOptions, type SubtitleDiagnosticWarning, type SubtitleDiagnosticWarningCode, type SubtitleCompositionData, type SubtitleDisplaySettings, type SubtitleFrameCanvasOptions, type SubtitleFrameCanvasTarget, type SubtitleFrameCropMode, type SubtitleFrameRenderOptions, type SubtitleRenderedFrameData, type SubtitleFormatName, type SubtitleHorizontalAlign, type SubtitleLastRenderInfo, type SubtitleParserMetadata, type SubtitlePresentPath, type SubtitleRendererBackend, type SubtitleRendererEvent, type SubtitleRendererStatsSnapshot, type SubtitleStreamChunk, type SubtitleSynchronizationMode } from './wrapper';
 export type { RenderResult, SubtitleFrame, VobSubFrame } from './wrapper';
 export { PGSRenderer, VobsubRenderer, UnifiedSubtitleRenderer } from './wrapper';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,WAAW,EACX,cAAc,EACd,0BAA0B,EAC1B,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC3B,MAAM,WAAW,CAAA;AAGlB,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAGjG,OAAO,EACL,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,MAAM,EACN,QAAQ,EACR,aAAa,EACb,6BAA6B,EAC7B,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,6BAA6B,EAClC,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,6BAA6B,EAClC,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,EACnC,MAAM,WAAW,CAAA;AAGlB,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAGzE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,WAAW,EACX,WAAW,EACX,cAAc,EACd,0BAA0B,EAC1B,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC3B,MAAM,WAAW,CAAA;AAGlB,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAG5G,OAAO,EACL,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,MAAM,EACN,KAAK,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,0BAA0B,EAC1B,4BAA4B,EAC5B,qCAAqC,EACrC,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,MAAM,EACN,QAAQ,EACR,aAAa,EACb,6BAA6B,EAC7B,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,6BAA6B,EAClC,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,6BAA6B,EAClC,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,EAClC,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EACjC,MAAM,WAAW,CAAA;AAGlB,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAGzE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -4,11 +4,11 @@
  * @packageDocumentation
  */
 // High-level video-integrated renderers (compatible with old libpgs-js API)
-export { PgsRenderer, VobSubRenderer, createAutoSubtitleRenderer } from './wrapper';
+export { PgsRenderer, DvbRenderer, VobSubRenderer, createAutoSubtitleRenderer } from './wrapper';
 // Low-level parsers for programmatic use
-export { PgsParser, VobSubParserLowLevel, UnifiedSubtitleParser, openSubtitles } from './wrapper';
+export { PgsParser, DvbParser, VobSubParserLowLevel, UnifiedSubtitleParser, openSubtitles } from './wrapper';
 // Utility exports
-export { initWasm, isWasmInitialized, isWebGPUSupported, detectSubtitleFormat, renderFrameData, toBlob, toCanvas, toImageBitmap, createSubtitleDiagnosticError, normalizeSubtitleError, SubtitleDiagnosticError } from './wrapper';
+export { initWasm, isWasmInitialized, isWebGPUSupported, isWorkerAvailable, isWorkerReady, warmup, ready, getRuntimeCapabilities, canUseWorkerOffscreenRender, isOffscreenCanvasSupported, isOffscreenCanvas2DSupported, isTransferControlToOffscreenSupported, isCanvas2DSupported, detectSubtitleFormat, fetchSubtitleAsset, fetchSubtitleText, probeRangeSupport, renderFrameData, toBlob, toCanvas, toImageBitmap, createSubtitleDiagnosticError, normalizeSubtitleError, SubtitleDiagnosticError } from './wrapper';
 // Legacy aliases
 export { PGSRenderer, VobsubRenderer, UnifiedSubtitleRenderer } from './wrapper';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,4EAA4E;AAC5E,OAAO,EACL,WAAW,EACX,cAAc,EACd,0BAA0B,EAI3B,MAAM,WAAW,CAAA;AAElB,yCAAyC;AACzC,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAEjG,kBAAkB;AAClB,OAAO,EACL,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,MAAM,EACN,QAAQ,EACR,aAAa,EACb,6BAA6B,EAC7B,sBAAsB,EACtB,uBAAuB,EA6BxB,MAAM,WAAW,CAAA;AAKlB,iBAAiB;AACjB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,4EAA4E;AAC5E,OAAO,EACL,WAAW,EACX,WAAW,EACX,cAAc,EACd,0BAA0B,EAI3B,MAAM,WAAW,CAAA;AAElB,yCAAyC;AACzC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAE5G,kBAAkB;AAClB,OAAO,EACL,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,MAAM,EACN,KAAK,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,0BAA0B,EAC1B,4BAA4B,EAC5B,qCAAqC,EACrC,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,MAAM,EACN,QAAQ,EACR,aAAa,EACb,6BAA6B,EAC7B,sBAAsB,EACtB,uBAAuB,EAsCxB,MAAM,WAAW,CAAA;AAKlB,iBAAiB;AACjB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA"}

package/dist/integrations/hlsjs.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Optional hls.js adapter for libbitsub bitmap subtitles.
+ *
+ * hls.js handles HLS media and WebVTT/IMSC text tracks; use this helper for
+ * external PGS/VobSub/MKS bitmap overlays on the same media element.
+ *
+ * @example
+ * ```ts
+ * import Hls from 'hls.js'
+ * import { attachBitSubToHls } from 'libbitsub/hlsjs'
+ *
+ * const hls = new Hls()
+ * hls.loadSource(playlistUrl)
+ * hls.attachMedia(video)
+ * const bitsub = attachBitSubToHls(hls, { subUrl: '/subs/movie.sup' })
+ * // later
+ * bitsub.dispose()
+ * ```
+ */
+import { type AttachBitSubOptions, type BitSubController } from './shared';
+/** Minimal hls.js surface used by the adapter. */
+export interface HlsLike {
+    media: HTMLMediaElement | null;
+    on?(event: string, listener: (...args: unknown[]) => void): void;
+    off?(event: string, listener: (...args: unknown[]) => void): void;
+    /** hls.js Events map — optional so callers can pass event name strings. */
+    Events?: {
+        MEDIA_ATTACHED?: string;
+        MEDIA_DETACHED?: string;
+        DESTROYING?: string;
+    };
+}
+export type BitSubHlsOptions = AttachBitSubOptions;
+export interface BitSubHlsHandle extends BitSubController {
+    /** Underlying hls.js instance. */
+    readonly hls: HlsLike;
+}
+/**
+ * Attach libbitsub to an hls.js instance.
+ * Binds to `hls.media` and re-attaches on MEDIA_ATTACHED when event APIs exist.
+ */
+export declare function attachBitSubToHls(hls: HlsLike, options?: BitSubHlsOptions): BitSubHlsHandle;
+export type { AttachBitSubOptions, BitSubController, BitSubSourceOptions, BitSubRenderer } from './shared';
+export { attachBitSub, createBitSubRenderer } from './shared';
+//# sourceMappingURL=hlsjs.d.ts.map

package/dist/integrations/hlsjs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hlsjs.d.ts","sourceRoot":"","sources":["../../src/integrations/hlsjs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAgB,KAAK,mBAAmB,EAAE,KAAK,gBAAgB,EAA4B,MAAM,UAAU,CAAA;AAElH,kDAAkD;AAClD,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAA;IAC9B,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAA;IAChE,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAA;IACjE,2EAA2E;IAC3E,MAAM,CAAC,EAAE;QACP,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB,CAAA;CACF;AAED,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAA;AAElD,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,kCAAkC;IAClC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;CACtB;AAUD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,gBAAqB,GAAG,eAAe,CAgG/F;AAED,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC1G,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA"}