akarisub 1.0.0 → 1.1.0

package/README.md

@@ -14,14 +14,17 @@ AkariSub is a JS wrapper for <a href="https://github.com/libass/libass">libass</
 - Supports most SSA/ASS features (everything libass supports)
 - Supports all OpenType, TrueType and WOFF fonts, as well as embedded fonts
 - Supports anamorphic videos [(on browsers which support it)](https://caniuse.com/mdn-api_htmlvideoelement_requestvideoframecallback)
-- Supports different video color spaces [(on browsers which support it)](https://caniuse.com/mdn-api_videocolorspace)
+- Supports different video color spaces, including HDR / wide-gamut overlay [(on browsers which support it)](https://caniuse.com/mdn-api_videocolorspace)
 - Capable of using local fonts [(on browsers which support it)](https://caniuse.com/mdn-api_window_querylocalfonts)
 - Works fast (all the heavy lifting is done by WebAssembly)
-- Is fully threaded (on browsers which support it, it's capable of working fully on a separate thread)
+- Is fully threaded (worker plus optional WASM pthreads on isolated pages)
 - Is asynchronous (renders when available, not in order of execution)
 - Benefits from hardware acceleration (uses hardware accelerated canvas API's)
 - Doesn't manipulate the DOM to render subtitles
 - Easy to use - just connect it to video element
+- Optional WebCodecs `VideoFrame` clock for custom players and editors
+- Streaming / live tracks: append ASS fragments, Matroska packets, or events without reloading the file
+- Font subset lazy loading: fetch only the unicode-range slices the current script needs (CJK fonts in particular)
 
 ### Fork Enhancements
 
@@ -30,7 +33,13 @@ AkariSub is a JS wrapper for <a href="https://github.com/libass/libass">libass</
 - **Proper Fontconfig Implementation** - add Fontconfig support with multiple fallback fonts supported
 - **Encrypted Subtitles** - optionally load AES-GCM encrypted subtitle payloads that are decrypted inside the worker, so plaintext never touches the main thread
 - **Statistics Reporting** - Built-in statistics and performance metrics for debugging and monitoring
+- **Atomic Track Switching** - `preloadTrack()` / `activatePreloadedTrack()` load a second language track and its fonts before swapping, so the last frame stays visible
+- **Streaming / live tracks** - `initStreamingTrack()` plus `appendSubtitleData()` / `appendSubtitleChunk()` accept HLS fragments and Matroska packets without a full file
+- **Font subset lazy loading** - `availableFonts` can list unicode-range slices so CJK (and other) glyph files load only when the track needs them
+- **Cue Callbacks** - `onCueEnter`, `onCueExit`, `onRender`, `onRendererChange`, and `onPerformanceWarning` for overlays and analytics without polling `getEvents()`
 - **TypeScript Support** - Full TypeScript definitions and type safety
+- **HDR / Wide Color Gamut** - Matches Display P3 / Rec.2020 canvases and PQ/HLG video, and converts BT.2020 YCbCr matrices
+- **WASM SIMD + pthreads** - SIMD libass kernels in the default binary; optional `akarisub-mt.wasm` blends independent regions on isolated pages
 - **Updated Dependencies** - All dependencies updated to their latest versions, including libass
 
 ## Installation
@@ -116,6 +125,39 @@ If the browser timeline is normalized from decode time rather than the first dis
 
 `subtitleTimeOffset` is signed. When the source video starts after the container subtitle clock, subtract that source lead from the reorder offset. For example, an encoded reorder gap of `0.083422` seconds and a source video start of `0.007` seconds use `subtitleTimeOffset = 0.076422`, so the first displayed frame is sampled by libass at `0.007` just like mpv.
 
+## Using with WebCodecs
+
+Apps that decode with `VideoDecoder` instead of `HTMLVideoElement` can drive the same on-demand and frame-timeline path with each output `VideoFrame`. Pass a canvas, keep `onDemandRender` enabled, and present frames as they leave the decoder. AkariSub reads `timestamp` (microseconds), `displayWidth` / `displayHeight`, and `colorSpace` (`matrix`, `primaries`, `transfer`). HDR frames pick a Display P3 or Rec.2020 canvas when the browser can create one. It does not take ownership of the frame.
+
+```js
+import AkariSub, { frameTimelineFromTimestamps } from 'akarisub'
+
+const renderer = new AkariSub({
+  canvas: document.querySelector('canvas'),
+  subUrl: './tracks/sub.ass',
+  frameTimeline: frameTimelineFromTimestamps(packetTimestampsUs),
+  onDemandRender: true
+})
+
+const decoder = new VideoDecoder({
+  output(frame) {
+    renderer.presentVideoFrame(frame, {
+      expectedDisplayTime: performance.now(),
+      isPaused: false,
+      rate: 1
+    })
+    frame.close()
+  },
+  error(err) {
+    console.error(err)
+  }
+})
+```
+
+Paused editor and offline-preview frames pass `isPaused: true` so libass samples that exact timestamp. `setVideoColorSpace()` can apply a matrix without presenting a frame. `frameTimelineFromVideoFrames()` builds a timeline from already-decoded frames.
+
+In browsers without `requestVideoFrameCallback`, set `onDemandRender: true` explicitly so `presentVideoFrame` uses the demand path instead of the worker RAF loop.
+
 ## Changing subtitles
 
 You're not limited to only display the subtitle file you referenced in your options. You're able to dynamically change subtitles on the fly. There's four methods that you can use for this specifically:
@@ -129,6 +171,79 @@ You're not limited to only display the subtitle file you referenced in your opti
 renderer.setTrackByUrl('/newsub.ass')
 ```
 
+For streaming players with multiple language tracks, preload the next file so the swap does not drop a frame or hitch on font load. The last painted frame stays on screen until the new track's first frame is ready:
+
+```js
+const ja = await renderer.preloadTrack({ kind: 'url', url: '/subs/ja.ass' })
+await renderer.activatePreloadedTrack(ja.id)
+```
+
+`preloadTrack()` also accepts ASS text or bytes, `{ kind: 'content', content }`, or `{ kind: 'encrypted', content }`. `activatePreloadedTrack()` without an id uses the most recently preloaded track.
+
+## Streaming and live tracks
+
+Live streams and HLS fragments rarely have a complete ASS file up front. Initialize a header-only track, then append events as packets arrive. libass keeps styles and script info; you decide how long past cues stay in memory.
+
+```js
+const renderer = new AkariSub({
+  video,
+  // Header only: Script Info + Styles, no Dialogue lines required
+})
+
+renderer.initStreamingTrack({
+  header: `[Script Info]
+ScriptType: v4.00+
+PlayResX: 1920
+PlayResY: 1080
+
+[V4+ Styles]
+Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
+Style: Default,Arial,48,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,0,2,10,10,10,1
+
+[Events]
+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
+`,
+  pruneDelay: 30
+})
+
+// HLS WebVTT/ASS fragment converted to Dialogue lines:
+renderer.appendSubtitleData('Dialogue: 0,0:00:01.00,0:00:03.00,Default,,0,0,0,,Hello live\n')
+
+// Or structured events (Start/Duration are libass milliseconds, same as createEvent):
+renderer.appendEvents([{ Start: 4000, Duration: 2000, Style: 'Default', Text: 'Next cue' }])
+
+// Matroska/WebM live packets:
+renderer.initStreamingTrack({ header: codecPrivate, format: 'matroska', pruneDelay: 15 })
+renderer.appendSubtitleChunk(packet, startSeconds, durationSeconds)
+```
+
+`pruneDelay` deletes events that ended more than that many seconds before the last rendered timestamp. Call `pruneEvents(video.currentTime - 30)` yourself when you want an explicit live window. `flushEvents()` drops every event and keeps the header.
+
+Do not mix `appendSubtitleChunk` with `appendSubtitleData` / `createEvent` on the same track. libass uses ReadOrder to drop duplicate Matroska packets, and that check breaks if the event list is edited some other way.
+
+## Font subsetting / lazy loading
+
+A full CJK font is often 10-20MB. Split it into unicode-range files (the same files you would ship for CSS `@font-face`) and list them under `availableFonts`. AkariSub reads the current track, keeps Latin loaded, and fetches Hiragana/Katakana/Han/Hangul (or other scripts) only when those glyphs appear, including as live events arrive.
+
+```js
+const renderer = new AkariSub({
+  video,
+  subUrl: './tracks/sub.ass',
+  availableFonts: {
+    'liberation sans': '/fonts/liberation-sans.woff2',
+    'noto sans cjk jp': [
+      { src: '/fonts/noto-cjk-latin.woff2', unicodeRange: 'U+0000-00FF' },
+      { src: '/fonts/noto-cjk-hira.woff2', scripts: ['hira'] },
+      { src: '/fonts/noto-cjk-kana.woff2', scripts: ['kana'] },
+      { src: '/fonts/noto-cjk-han.woff2', scripts: ['hani'] }
+    ]
+  },
+  fallbackFonts: ['liberation sans']
+})
+```
+
+`scripts` accepts OpenType tags (`latn`, `hani`, `hira`, `kana`, `hang`) and aliases (`cjk`, `jp`, `kr`, `latin`). `fonts` still force-loads complete files. Set `lazyFonts: false` to fetch every listed slice when the family is first referenced.
+
 ## Cleaning up the object
 
 After you're finished with rendering the subtitles. You need to call the `destroy()` method to correctly destroy the object.
@@ -200,6 +315,8 @@ console.log(`Events: ${eventCount}, Styles: ${styleCount}`)
 
 AkariSub automatically picks the fastest available renderer: WebGPU → WebGL2 → Canvas2D. GPU renderers are used when no custom canvas is given and the browser supports them:
 
+GPU failures are recovered automatically. AkariSub retains the last completed subtitle frame while rebuilding after WebGPU `device.lost` or WebGL2 `webglcontextlost`; it resumes the same backend after recovery, or switches to Canvas2D if rebuilding/restoration fails. Recovery notifications include `reason: 'device-lost' | 'context-lost'`.
+
 ```typescript
 import AkariSub from 'akarisub'
 
@@ -222,69 +339,114 @@ if (renderer.isUsingGPURenderer) {
 
 The default options are best, and automatically fallback to the next fastest options in line, when the API's they use are unsupported. You can however forcefully change this behavior by specifying options.
 
-| Option                | Type                                 | Default                                  | Description                                                                                                                                                |
-| --------------------- | ------------------------------------ | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `video`               | HTMLVideoElement                     | -                                        | Video to use as target for rendering and event listeners                                                                                                   |
-| `canvas`              | HTMLCanvasElement                    | -                                        | Canvas to use for manual handling (optional if video is provided)                                                                                          |
-| `blendMode`           | `'js'` \| `'wasm'`                   | `'wasm'`                                 | Image blending mode. WASM is better for low-end devices, JS for hardware acceleration                                                                      |
-| `asyncRender`         | boolean                              | auto                                     | Render via ImageBitmap. Defaults to `true` on Canvas2D paths and `false` when a GPU renderer is active (raw buffers upload with fewer copies) or on WebKit |
-| `offscreenRender`     | boolean                              | automatic                                | Render fully on the worker; enabled for video-managed canvases and disabled for custom canvases                                                            |
-| `rawAssImageGpu`      | boolean                              | `false`                                  | Compose raw libass masks with worker WebGL2 when offscreen rendering is active                                                                              |
-| `onDemandRender`      | boolean                              | `true`                                   | Render subtitles as the video player renders frames                                                                                                        |
-| `adaptiveTiming`      | boolean                              | `true`                                   | Compensate measured queue, worker, bitmap, IPC, and paint latency while video is playing; pause and seek renders remain frame-exact                        |
-| `frameTimeline`       | FrameTimeline                        | -                                        | Encoded browser-frame timestamps plus optional media/subtitle clock offsets; enables frame-locked libass sampling                                          |
-| `framePrefetch`       | number                               | `2`                                      | Number of exact subtitle-frame bitmaps to prepare ahead (`0` disables preparation, maximum `24`)                                                           |
-| `targetFps`           | number                               | `24`                                     | Target FPS when not using onDemandRender                                                                                                                   |
-| `timeOffset`          | number                               | `0`                                      | Subtitle time offset in seconds                                                                                                                            |
-| `debug`               | boolean                              | `false`                                  | Enable debug logging                                                                                                                                       |
-| `prescaleFactor`      | number                               | `1.0`                                    | Scale factor for subtitles canvas                                                                                                                          |
-| `prescaleHeightLimit` | number                               | `1080`                                   | Height limit for prescaling in pixels                                                                                                                      |
-| `maxRenderHeight`     | number                               | `0`                                      | Maximum render height (0 = no limit)                                                                                                                       |
-| `dropAllAnimations`   | boolean                              | `false`                                  | Discard all animated tags for performance                                                                                                                  |
-| `dropAllBlur`         | boolean                              | `false`                                  | Drop all blur effects (~10x performance gain)                                                                                                              |
-| `clampPos`            | boolean                              | `false`                                  | Clamp `\pos` values to script resolution                                                                                                                   |
-| `renderAhead`         | number                               | `0`                                      | Optional extra seconds to render ahead, in addition to adaptive timing; also applies when `onDemandRender` is disabled                                     |
-| `workerUrl`           | string                               | package worker URL                       | Optional worker script URL. Defaults to the package worker module URL                                                                                      |
-| `wasmUrl`             | string                               | package WASM URL                         | Optional WASM binary URL. Defaults to the URL resolved from `import.meta.url`                                                                              |
-| `glueUrl`             | string                               | package glue URL                         | Optional WASM glue script URL. Defaults to the URL resolved from `import.meta.url`                                                                         |
-| `subUrl`              | string                               | -                                        | URL of the subtitle file to play                                                                                                                           |
-| `subContent`          | string \| Uint8Array \| ArrayBuffer  | -                                        | Content of the subtitle file to play                                                                                                                       |
-| `encryptedSubContent` | EncryptedSubtitleContent             | -                                        | AES-GCM encrypted subtitle payload, decrypted inside the worker                                                                                            |
-| `fonts`               | (string \| Uint8Array)[]             | -                                        | Array of font URLs or Uint8Arrays to force load                                                                                                            |
-| `availableFonts`      | Record<string, string \| Uint8Array> | liberation sans from package assets      | Available fonts map (lowercase name → URL/data)                                                                                                            |
-| `fallbackFonts`       | string[]                             | `['liberation sans']`                    | Fallback font families in order, used for the fontconfig cascade                                                                                           |
-| `useLocalFonts`       | boolean                              | `true`                                   | Use Local Font Access API if available                                                                                                                     |
-| `libassMemoryLimit`   | number                               | `128`                                    | libass bitmap cache memory limit in MiB                                                                                                                    |
-| `libassGlyphLimit`    | number                               | `2048`                                   | libass glyph cache limit                                                                                                                                   |
-| `fullTrackWarmup`     | boolean                              | `false`                                  | Pre-render early track windows after load to warm libass caches                                                                                            |
-| `onCanvasFallback`    | function                             | -                                        | Callback when no GPU renderer is available (Canvas2D fallback)                                                                                             |
+| Option                 | Type                                 | Default                             | Description                                                                                                                                                |
+| ---------------------- | ------------------------------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `video`                | HTMLVideoElement                     | -                                   | Video to use as target for rendering and event listeners. WebCodecs players pass `canvas` and call `presentVideoFrame` instead                             |
+| `canvas`               | HTMLCanvasElement                    | -                                   | Canvas to use for manual handling (optional if video is provided)                                                                                          |
+| `blendMode`            | `'js'` \| `'wasm'`                   | `'wasm'`                            | Image blending mode. WASM is better for low-end devices, JS for hardware acceleration                                                                      |
+| `asyncRender`          | boolean                              | auto                                | Render via ImageBitmap. Defaults to `true` on Canvas2D paths and `false` when a GPU renderer is active (raw buffers upload with fewer copies) or on WebKit |
+| `offscreenRender`      | boolean                              | automatic                           | Render fully on the worker; enabled for video-managed canvases and disabled for custom canvases                                                            |
+| `rawAssImageGpu`       | boolean                              | `false`                             | Compose raw libass masks with worker WebGL2 when offscreen rendering is active                                                                             |
+| `onDemandRender`       | boolean                              | `true`                              | Render subtitles as the video player or `presentVideoFrame` presents frames                                                                                |
+| `adaptiveTiming`       | boolean                              | `true`                              | Compensate measured queue, worker, bitmap, IPC, and paint latency while video is playing; pause and seek renders remain frame-exact                        |
+| `frameTimeline`        | FrameTimeline                        | -                                   | Encoded browser-frame timestamps plus optional media/subtitle clock offsets; enables frame-locked libass sampling                                          |
+| `framePrefetch`        | number                               | `2`                                 | Number of exact subtitle-frame bitmaps to prepare ahead (`0` disables preparation, maximum `24`)                                                           |
+| `targetFps`            | number                               | `24`                                | Target FPS when not using onDemandRender                                                                                                                   |
+| `timeOffset`           | number                               | `0`                                 | Subtitle time offset in seconds                                                                                                                            |
+| `debug`                | boolean                              | `false`                             | Enable debug logging                                                                                                                                       |
+| `prescaleFactor`       | number                               | `1.0`                               | Scale factor for subtitles canvas                                                                                                                          |
+| `prescaleHeightLimit`  | number                               | `1080`                              | Height limit for prescaling in pixels                                                                                                                      |
+| `maxRenderHeight`      | number                               | `0`                                 | Maximum render height (0 = no limit)                                                                                                                       |
+| `dropAllAnimations`    | boolean                              | `false`                             | Discard all animated tags for performance                                                                                                                  |
+| `dropAllBlur`          | boolean                              | `false`                             | Drop all blur effects (~10x performance gain)                                                                                                              |
+| `clampPos`             | boolean                              | `false`                             | Clamp `\pos` values to script resolution                                                                                                                   |
+| `renderAhead`          | number                               | `0`                                 | Optional extra seconds to render ahead, in addition to adaptive timing; also applies when `onDemandRender` is disabled                                     |
+| `workerUrl`            | string                               | package worker URL                  | Optional worker script URL. Defaults to the package worker module URL                                                                                      |
+| `wasmUrl`              | string                               | package WASM URL                    | Optional WASM binary URL. Defaults to the URL resolved from `import.meta.url`                                                                              |
+| `glueUrl`              | string                               | package glue URL                    | Optional WASM glue script URL. Defaults to the URL resolved from `import.meta.url`                                                                         |
+| `modernWasmUrl`        | string                               | -                                   | Optional SIMD WASM URL used when the engine validates `v128`                                                                                               |
+| `mtWasmUrl`            | string                               | package `akarisub-mt.wasm`          | Optional pthread SIMD WASM URL. Requires COOP/COEP (`crossOriginIsolated`)                                                                                 |
+| `canvasColorSpace`     | `'srgb'` \| `'display-p3'` \| `'rec2020'` \| `'auto'` | `'auto'`               | Overlay canvas color space. `auto` follows the video primaries                                                                                             |
+| `hdr`                  | boolean \| `'auto'`                  | `'auto'`                            | Request an HDR canvas when the video transfer is PQ or HLG                                                                                                 |
+| `subUrl`               | string                               | -                                   | URL of the subtitle file to play                                                                                                                           |
+| `subContent`           | string \| Uint8Array \| ArrayBuffer  | -                                   | Content of the subtitle file to play                                                                                                                       |
+| `encryptedSubContent`  | EncryptedSubtitleContent             | -                                   | AES-GCM encrypted subtitle payload, decrypted inside the worker                                                                                            |
+| `fonts`                | (string \| Uint8Array)[]             | -                                   | Font URLs or bytes to force-load in full                                                                                                                   |
+| `availableFonts`       | Record<string, FontFamilySource>     | liberation sans from package assets | Family name (lowercase) → URL, bytes, or unicode-range / script slices. Slices load lazily from the current track                                          |
+| `lazyFonts`            | boolean                              | `true`                              | When `availableFonts` entries declare slices, fetch only the ones the current scripts need                                                                 |
+| `fallbackFonts`        | string[]                             | `['liberation sans']`               | Fallback font families in order, used for the fontconfig cascade                                                                                           |
+| `useLocalFonts`        | boolean                              | `true`                              | Use Local Font Access API if available                                                                                                                     |
+| `libassMemoryLimit`    | number                               | `128`                               | libass bitmap cache memory limit in MiB                                                                                                                    |
+| `libassGlyphLimit`     | number                               | `2048`                              | libass glyph cache limit                                                                                                                                   |
+| `fullTrackWarmup`      | boolean                              | `false`                             | Pre-render early track windows after load to warm libass caches                                                                                            |
+| `onCanvasFallback`     | function                             | -                                   | Callback when no GPU renderer is available (Canvas2D fallback)                                                                                             |
+| `onCueEnter`           | `(cue) => void`                      | -                                   | Dialogue event became active at the sampled media time                                                                                                     |
+| `onCueExit`            | `(cue) => void`                      | -                                   | Dialogue event is no longer active                                                                                                                         |
+| `onRender`             | `(event) => void`                    | -                                   | Demand-frame render finished                                                                                                                               |
+| `onRendererChange`     | `(event) => void`                    | -                                   | Compositor backend changed or recovered; GPU recovery includes `event.reason`                                                                               |
+| `onPerformanceWarning` | `(warning) => void`                  | -                                   | Slow frame, dropped frames, a full demand queue, or GPU recovery                                                                                           |
 
 ## Methods
 
 ### Track Management
 
-| Method                       | Parameters                                     | Description                                                      |
-| ---------------------------- | ---------------------------------------------- | ---------------------------------------------------------------- |
-| `setTrackByUrl(url)`         | `url: string`                                  | Load subtitle from URL                                           |
-| `setTrack(content)`          | `content: string \| Uint8Array \| ArrayBuffer` | Set subtitle from content                                        |
-| `setEncryptedTrack(content)` | `content: EncryptedSubtitleContent`            | Set subtitle from an encrypted payload (decrypted in the worker) |
-| `freeTrack()`                | -                                              | Remove current subtitles                                         |
+| Method                        | Parameters                                     | Description                                                                      |
+| ----------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------- |
+| `setTrackByUrl(url)`          | `url: string`                                  | Load subtitle from URL                                                           |
+| `setTrack(content)`           | `content: string \| Uint8Array \| ArrayBuffer` | Set subtitle from content                                                        |
+| `setEncryptedTrack(content)`  | `content: EncryptedSubtitleContent`            | Set subtitle from an encrypted payload (decrypted in the worker)                 |
+| `freeTrack()`                 | -                                              | Remove current subtitles                                                         |
+| `initStreamingTrack(options?)` | `StreamingTrackOptions \| string \| bytes`    | Create a header-only track that can accept later fragments                       |
+| `appendSubtitleData(content)` | `content: string \| Uint8Array \| ArrayBuffer` | Parse ASS text (Dialogue lines, extra styles) into the current track             |
+| `appendSubtitleChunk(data, start, duration)` | `data`, `start: number`, `duration: number` | Append one Matroska packet; `start`/`duration` are seconds                       |
+| `appendEvents(events)`       | `events: Partial<ASSEvent>[]`                  | Append several Dialogue events in one message                                    |
+| `pruneEvents(before)`         | `before: number`                               | Drop events that ended before `before` seconds                                   |
+| `flushEvents()`               | -                                              | Drop every event and keep styles / script info                                   |
+| `configurePrune(delay)`       | `delay: number`                                | Auto-drop events that ended more than `delay` seconds before the last render     |
+| `preloadTrack(source)`        | `PreloadTrackSource \| string \| bytes`        | Parse a track and load its fonts without replacing the visible one               |
+| `activatePreloadedTrack(id?)` | `id?: number`                                  | Atomically swap to a preloaded track; last frame stays until the first new paint |
 
 ### Playback Control
 
-| Method                                           | Parameters                                                | Description                                   |
-| ------------------------------------------------ | --------------------------------------------------------- | --------------------------------------------- |
-| `setIsPaused(isPaused)`                          | `isPaused: boolean`                                       | Set playback pause state                      |
-| `setRate(rate)`                                  | `rate: number`                                            | Set playback rate (speed multiplier)          |
-| `setCurrentTime(isPaused?, currentTime?, rate?)` | `isPaused?: boolean, currentTime?: number, rate?: number` | Set current time, playback state and rate     |
-| `setFrameTimeline(frameTimes)`                   | `ArrayLike<number> \| null`                               | Replace or disable the encoded-frame timeline |
+| Method                                           | Parameters                                                  | Description                                   |
+| ------------------------------------------------ | ----------------------------------------------------------- | --------------------------------------------- |
+| `setIsPaused(isPaused)`                          | `isPaused: boolean`                                         | Set playback pause state                      |
+| `setRate(rate)`                                  | `rate: number`                                              | Set playback rate (speed multiplier)          |
+| `setCurrentTime(isPaused?, currentTime?, rate?)` | `isPaused?: boolean, currentTime?: number, rate?: number`   | Set current time, playback state and rate     |
+| `setFrameTimeline(frameTimes)`                   | `ArrayLike<number> \| null`                                 | Replace or disable the encoded-frame timeline |
+| `presentVideoFrame(frame, options?)`             | `frame: VideoFrame, options?: PresentVideoFrameOptions`     | Present a WebCodecs frame as the video clock  |
+| `setVideoColorSpace(colorSpace)`                 | `BT709` \| `BT601` \| `BT2020` \| matrix name \| `colorSpace` \| `null` | Set the video YCbCr matrix and optional HDR primaries/transfer |
 
 ### Video & Canvas
 
-| Method                                         | Parameters                                                                      | Description                 |
-| ---------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------- |
-| `setVideo(video)`                              | `video: HTMLVideoElement`                                                       | Change target video element |
-| `resize(width?, height?, top?, left?, force?)` | `width?: number, height?: number, top?: number, left?: number, force?: boolean` | Resize the canvas           |
+| Method                                         | Parameters                                                                      | Description                                                 |
+| ---------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `setVideo(video)`                              | `video: HTMLVideoElement`                                                       | Change target video element. Clears a WebCodecs frame clock |
+| `resize(width?, height?, top?, left?, force?)` | `width?: number, height?: number, top?: number, left?: number, force?: boolean` | Resize the canvas                                           |
+
+### Cue and render callbacks
+
+Option callbacks and matching `EventTarget` events (`cueEnter`, `cueExit`, `render`, `rendererChange`, `performanceWarning`) report subtitle-clock activity and compositor lifecycle changes. Use them for chapter markers, character overlays, or analytics instead of polling `getEvents()`:
+
+```ts
+const renderer = new AkariSub({
+  video,
+  subUrl: '/subs/en.ass',
+  onCueEnter: (cue) => showCharacter(cue.name, cue.text),
+  onCueExit: (cue) => hideCharacter(cue.index),
+  onRender: (event) => recordSubtitleFrame(event.time, event.renderTimeMs),
+  onPerformanceWarning: (warning) => {
+    if (warning.kind === 'slow-frame') console.warn('slow subtitle frame', warning.renderTimeMs)
+    if (warning.kind === 'renderer-recovery') console.warn('GPU recovery', warning.reason)
+  }
+})
+
+renderer.addEventListener('rendererChange', (event) => {
+  console.log('compositor', event.detail.rendererType, event.detail.reason)
+})
+```
+
+`CueEvent.start` and `CueEvent.duration` are seconds on the subtitle clock, matching `video.currentTime` plus `timeOffset`. Encrypted tracks omit `name` and `text`.
 
 ### Event Management
 
@@ -431,5 +593,5 @@ bun run build     # builds the WASM glue and TypeScript
 ```
 
 - If on macOS with libtool from brew, `LIBTOOLIZE=glibtoolize make`
-- Incremental rebuilds of the WASM glue only: `bun run build:wasm` (or `make worker`)
+- Incremental rebuilds of the WASM glue only: `bun run build:wasm` (or `make workers`)
 - Artifacts are in `pkg/` (WASM glue and binary) and `dist/` (TypeScript)

package/dist/COPYRIGHT

@@ -24,7 +24,7 @@ Regenerate it with `bun run license:third-party` after dependency, submodule, fo
 
 | Package | Version | License | Source |
 | --- | --- | --- | --- |
-| `@types/bun` | 1.3.14 | MIT | https://github.com/DefinitelyTyped/DefinitelyTyped.git |
+| `@types/bun` | 1.4.0 | MIT | https://github.com/DefinitelyTyped/DefinitelyTyped.git |
 | `@types/emscripten` | 1.41.5 | MIT | https://github.com/DefinitelyTyped/DefinitelyTyped.git |
 | `@types/node` | 25.0.9 | MIT | https://github.com/DefinitelyTyped/DefinitelyTyped.git |
 | `@typescript/typescript-aix-ppc64` | 7.0.2 | Apache-2.0 | https://github.com/microsoft/TypeScript.git |
@@ -47,8 +47,8 @@ Regenerate it with `bun run license:third-party` after dependency, submodule, fo
 | `@typescript/typescript-sunos-x64` | 7.0.2 | Apache-2.0 | https://github.com/microsoft/TypeScript.git |
 | `@typescript/typescript-win32-arm64` | 7.0.2 | Apache-2.0 | https://github.com/microsoft/TypeScript.git |
 | `@typescript/typescript-win32-x64` | 7.0.2 | Apache-2.0 | https://github.com/microsoft/TypeScript.git |
-| `@webgpu/types` | 0.1.71 | BSD-3-Clause | gpuweb/types |
-| `bun-types` | 1.3.14 | MIT | https://github.com/oven-sh/bun |
+| `@webgpu/types` | 0.1.72 | BSD-3-Clause | gpuweb/types |
+| `bun-types` | 1.4.0 | MIT | https://github.com/oven-sh/bun |
 | `prettier` | 3.9.6 | MIT | prettier/prettier |
 | `typescript` | 7.0.2 | Apache-2.0 | https://github.com/microsoft/TypeScript.git |
 | `undici-types` | 7.16.0 | MIT | git+https://github.com/nodejs/undici.git |

package/dist/index.d.ts

@@ -1,12 +1,30 @@
 /**
- * AkariSub - JavaScript ASS/SSA Subtitle Renderer
+ * AkariSub — ASS/SSA subtitle renderer for the browser.
  *
- * High-performance ASS/SSA subtitle renderer using libass compiled to WebAssembly.
+ * Renders libass subtitles with a WebAssembly worker and an optional WebGPU or
+ * WebGL2 compositor.
  *
- * @packageDocumentation
+ * @example
+ * ```ts
+ * import AkariSub from '@altq/akarisub'
+ *
+ * const renderer = new AkariSub({
+ *   video: document.querySelector('video')!,
+ *   subUrl: '/subtitles/example.ass'
+ * })
+ *
+ * renderer.destroy()
+ * ```
+ *
+ * @module
  */
 export { default } from './wrapper';
 export { default as AkariSub } from './wrapper';
-export type { ASSEvent, ASSStyle, AkariSubOptions, FrameTimeline, PerformanceStats, ASSEventCallback, ASSStyleCallback, PerformanceStatsCallback, ResetStatsCallback, RenderImage, RenderTimes, VideoFrameCallbackMetadata, SubtitleColorSpace, WebYCbCrColorSpace, EncryptedSubtitleContent } from './ts/types';
-export { webYCbCrMap, colorMatrixConversionMap, libassYCbCrMap, computeCanvasSize, getVideoPosition, fixAlpha, parseAss, dropBlur, fixPlayRes, testImageBugs, runFeatureTests, getAlphaBug, getBitmapBug, getColorSpaceFilterUrl, getWasmUrl, getWasmGlueUrl, getDefaultFontUrl, WebGPURenderer, isWebGPUSupported, WebGL2Renderer, isWebGL2Supported } from './wrapper';
+export type { ASSEvent, ASSStyle, AkariSubOptions, CueEvent, FontBytes, FontFamilySource, FontSubsetSource, FrameTimeline, PerformanceStats, PerformanceWarning, PreloadedTrack, PreloadTrackSource, PresentVideoFrameOptions, RenderEvent, RendererChangeEvent, RendererRecoveryReason, RendererType, StreamingTrackFormat, StreamingTrackOptions, ASSEventCallback, ASSStyleCallback, PerformanceStatsCallback, ResetStatsCallback, RenderImage, RenderTimes, VideoFrameCallbackMetadata, VideoFrameLike, SubtitleColorSpace, WebYCbCrColorSpace, EncryptedSubtitleContent } from './ts/types';
+export type { CanvasColorSpace, VideoColorProfile, VideoPrimaries, VideoTransfer } from './ts/color-space';
+export type { ASSSection, ASSBodyEntry } from './ts/utils';
+export { webYCbCrMap, colorMatrixConversionMap, libassYCbCrMap, computeCanvasSize, getVideoPosition, fixAlpha, parseAss, dropBlur, fixPlayRes, testImageBugs, runFeatureTests, getAlphaBug, getBitmapBug, getColorSpaceFilterUrl, getColorMatrix3, colorMatrix3ColumnMajor, getWasmUrl, getWasmGlueUrl, getMtWasmUrl, getMtWasmGlueUrl, getDefaultFontUrl, supportsWasmSimd, supportsWasmThreads, WebGPURenderer, isWebGPUSupported, WebGL2Renderer, isWebGL2Supported, VIDEO_FRAME_TIMESTAMP_SECONDS, frameTimelineFromTimestamps, frameTimelineFromVideoFrames, isVideoFrameLike, isWebCodecsVideoFrameSupported, videoFrameCallbackMetadata, videoFrameColorSpace, videoFrameMediaTime } from './wrapper';
+export { collectUnicodeScripts, collectUnicodeScriptsFromAss, expandScriptAlias, parseUnicodeRange, stripAssOverrides } from './ts/unicode-scripts';
+export { collectNeededScripts, matchFontSubsets, normalizeFontFamilySource } from './ts/font-subsets';
+export { parseStreamingTrackOptions } from './ts/streaming';
 //# 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;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,WAAW,CAAA;AAE/C,YAAY,EACV,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,kBAAkB,EAClB,WAAW,EACX,WAAW,EACX,0BAA0B,EAC1B,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACzB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,WAAW,EACX,wBAAwB,EACxB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,aAAa,EACb,eAAe,EACf,WAAW,EACX,YAAY,EACZ,sBAAsB,EACtB,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EAClB,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,WAAW,CAAA;AAE/C,YAAY,EACV,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,wBAAwB,EACxB,WAAW,EACX,mBAAmB,EACnB,sBAAsB,EACtB,YAAY,EACZ,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,kBAAkB,EAClB,WAAW,EACX,WAAW,EACX,0BAA0B,EAC1B,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACzB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAE1G,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE1D,OAAO,EACL,WAAW,EACX,wBAAwB,EACxB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,aAAa,EACb,eAAe,EACf,WAAW,EACX,YAAY,EACZ,sBAAsB,EACtB,eAAe,EACf,uBAAuB,EACvB,UAAU,EACV,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,6BAA6B,EAC7B,2BAA2B,EAC3B,4BAA4B,EAC5B,gBAAgB,EAChB,8BAA8B,EAC9B,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,qBAAqB,EACrB,4BAA4B,EAC5B,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,yBAAyB,EAC1B,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/index.js

@@ -1,11 +1,27 @@
 /**
- * AkariSub - JavaScript ASS/SSA Subtitle Renderer
+ * AkariSub — ASS/SSA subtitle renderer for the browser.
  *
- * High-performance ASS/SSA subtitle renderer using libass compiled to WebAssembly.
+ * Renders libass subtitles with a WebAssembly worker and an optional WebGPU or
+ * WebGL2 compositor.
  *
- * @packageDocumentation
+ * @example
+ * ```ts
+ * import AkariSub from '@altq/akarisub'
+ *
+ * const renderer = new AkariSub({
+ *   video: document.querySelector('video')!,
+ *   subUrl: '/subtitles/example.ass'
+ * })
+ *
+ * renderer.destroy()
+ * ```
+ *
+ * @module
  */
 export { default } from './wrapper';
 export { default as AkariSub } from './wrapper';
-export { webYCbCrMap, colorMatrixConversionMap, libassYCbCrMap, computeCanvasSize, getVideoPosition, fixAlpha, parseAss, dropBlur, fixPlayRes, testImageBugs, runFeatureTests, getAlphaBug, getBitmapBug, getColorSpaceFilterUrl, getWasmUrl, getWasmGlueUrl, getDefaultFontUrl, WebGPURenderer, isWebGPUSupported, WebGL2Renderer, isWebGL2Supported } from './wrapper';
+export { webYCbCrMap, colorMatrixConversionMap, libassYCbCrMap, computeCanvasSize, getVideoPosition, fixAlpha, parseAss, dropBlur, fixPlayRes, testImageBugs, runFeatureTests, getAlphaBug, getBitmapBug, getColorSpaceFilterUrl, getColorMatrix3, colorMatrix3ColumnMajor, getWasmUrl, getWasmGlueUrl, getMtWasmUrl, getMtWasmGlueUrl, getDefaultFontUrl, supportsWasmSimd, supportsWasmThreads, WebGPURenderer, isWebGPUSupported, WebGL2Renderer, isWebGL2Supported, VIDEO_FRAME_TIMESTAMP_SECONDS, frameTimelineFromTimestamps, frameTimelineFromVideoFrames, isVideoFrameLike, isWebCodecsVideoFrameSupported, videoFrameCallbackMetadata, videoFrameColorSpace, videoFrameMediaTime } from './wrapper';
+export { collectUnicodeScripts, collectUnicodeScriptsFromAss, expandScriptAlias, parseUnicodeRange, stripAssOverrides } from './ts/unicode-scripts';
+export { collectNeededScripts, matchFontSubsets, normalizeFontFamilySource } from './ts/font-subsets';
+export { parseStreamingTrackOptions } from './ts/streaming';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,WAAW,CAAA;AAoB/C,OAAO,EACL,WAAW,EACX,wBAAwB,EACxB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,aAAa,EACb,eAAe,EACf,WAAW,EACX,YAAY,EACZ,sBAAsB,EACtB,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EAClB,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,WAAW,CAAA;AAsC/C,OAAO,EACL,WAAW,EACX,wBAAwB,EACxB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,aAAa,EACb,eAAe,EACf,WAAW,EACX,YAAY,EACZ,sBAAsB,EACtB,eAAe,EACf,uBAAuB,EACvB,UAAU,EACV,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,6BAA6B,EAC7B,2BAA2B,EAC3B,4BAA4B,EAC5B,gBAAgB,EAChB,8BAA8B,EAC9B,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,qBAAqB,EACrB,4BAA4B,EAC5B,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,yBAAyB,EAC1B,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAA"}