akarisub 0.2.1 → 1.0.0

package/LICENSE

@@ -21,3 +21,6 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+Third-party components and bundled assets are licensed separately. See
+THIRD_PARTY_NOTICES.md, also shipped as dist/COPYRIGHT, for dependency notices.

package/README.md

@@ -25,9 +25,10 @@ AkariSub is a JS wrapper for <a href="https://github.com/libass/libass">libass</
 
 ### Fork Enhancements
 
-- **WebGPU Support** - Hardware-accelerated rendering using the modern WebGPU API [(on browsers which support it)](https://caniuse.com/webgpu)
+- **GPU Rendering** - Hardware-accelerated rendering with an automatic fallback chain: WebGPU [(on browsers which support it)](https://caniuse.com/webgpu) → WebGL2 → Canvas2D
 - **Hyper Optimizations** - Performance improvements and intelligent caching for smoother playback
 - **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
 - **TypeScript Support** - Full TypeScript definitions and type safety
 - **Updated Dependencies** - All dependencies updated to their latest versions, including libass
@@ -48,10 +49,10 @@ deno add jsr:@altq/akarisub
 
 ## Usage
 
-By default all you need to do is copy the files from the `dist/` folder of the repository into the same folder as where your JS runs, then do:
+In most bundler-based projects, no manual worker setup is required. AkariSub resolves the WASM glue and binary relative to the package module URL, so bundlers such as Vite, webpack, and Rollup can emit the assets automatically.
 
 ```js
-import AkariSub from './akarisub.es.js'
+import AkariSub from 'akarisub'
 
 const renderer = new AkariSub({
   video: document.querySelector('video'),
@@ -59,45 +60,70 @@ const renderer = new AkariSub({
 })
 ```
 
-`Note:` while the `dist/` folder includes a UMD dist it still uses modern syntax. If you want backwards compatibility with older browsers I recommend you run it tru babel.
+If your app serves package files in a way that does not expose those emitted assets to the browser, you can still provide the public fallback by copying the WASM file and its JS glue to `/akarisub/`:
+
+```bash
+mkdir -p public/akarisub
+cp node_modules/akarisub/pkg/akarisub.wasm node_modules/akarisub/pkg/akarisub.js public/akarisub/
+```
+
+The worker is created from the package module URL. `workerUrl`, `wasmUrl`, and `glueUrl` remain in the option type for overrides and do not need to be set in bundler-based apps.
+
+## Using only with canvas
 
-If you use a bundler like Vite, you can instead do:
+You're also able to use it without any video. However, that requires you to set the time the subtitles should render at yourself. Disable `onDemandRender` (it relies on video frame callbacks) and drive the clock manually:
 
 ```js
 import AkariSub from 'akarisub'
-import workerUrl from 'akarisub/worker?url'
-import wasmUrl from 'akarisub/worker.wasm?url'
 
 const renderer = new AkariSub({
-  video: document.querySelector('video'),
-  subContent: subtitleString,
-  workerUrl,
-  wasmUrl
+  canvas: document.querySelector('canvas'),
+  subUrl: './tracks/sub.ass',
+  onDemandRender: false
 })
+
+// setCurrentTime(isPaused?, currentTime?, rate?)
+renderer.setCurrentTime(true, 15)
 ```
 
-## Using only with canvas
+Custom canvases stay on the main thread by default. Set both `offscreenRender: true` and `rawAssImageGpu: true` to opt into worker WebGL2 raw-mask composition when dense overlays benefit from it.
 
-You're also able to use it without any video. However, that requires you to set the time the subtitles should render at yourself:
+### Timing semantics
 
-```js
-import AkariSub from './akarisub.es.js'
+AkariSub sends libass an integer millisecond timestamp. Fractional media times are floored to the current millisecond, matching libass's `Start <= now < Start + Duration` event boundaries. `timeOffset` and `renderAhead` are measured in seconds.
+
+By default, `adaptiveTiming` predicts the media time at which a completed canvas paint will become visible, compensating bounded rendering and delivery latency. Pause and seek frames always use the exact media timestamp. Set `adaptiveTiming: false` when deterministic frame sampling is more important than compensating live presentation latency.
 
+For frame-locked VOD playback, provide the encoded video's presentation timestamps in seconds. AkariSub prepares a small window of full subtitle bitmaps and commits the matching bitmap inside `requestVideoFrameCallback`, which keeps fast `\t` and `\move` animation sampling aligned with libass:
+
+```js
+const frameTimeline = new Float64Array([0, 0.041708, 0.083417])
 const renderer = new AkariSub({
-  canvas: document.querySelector('canvas'),
-  subUrl: './tracks/sub.ass'
+  video,
+  subContent,
+  frameTimeline,
+  framePrefetch: 2
 })
 
-renderer.setCurrentTime(15)
+// Timelines can also arrive after renderer construction.
+renderer.setFrameTimeline(frameTimeline)
+renderer.setFrameTimeline(null) // return to adaptive continuous-time rendering
 ```
 
+Use timestamps from the encoded rendition the browser plays, normalized to the browser media clock. Passing a timeline remains optional; cache misses and unsupported paths automatically use normal adaptive rendering.
+
+If the browser timeline is normalized from decode time rather than the first display PTS, preserve that initial B-frame reorder gap in the array and set `frameTimeline.subtitleTimeOffset` to the first frame timestamp. AkariSub uses the unmodified array to locate the visible video frame, then removes the offset only when sampling libass.
+
+`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.
+
 ## 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 three methods that you can use for this specifically:
+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:
 
 - `setTrackByUrl(url):` works the same as the `subUrl` option. It will set the subtitle to display by its URL.
-- `setTrack(content):` works the same as the `subContent` option. It will set the subtitle to display by its content.
-- `freeTrack():` this simply removes the subtitles. You can use the two methods above to set a new subtitle file to be displayed.
+- `setTrack(content):` works the same as the `subContent` option. It will set the subtitle to display by its content (string, `Uint8Array` or `ArrayBuffer`).
+- `setEncryptedTrack(content):` works the same as the `encryptedSubContent` option. The payload is decrypted inside the worker, so plaintext subtitles are never materialized on the main thread.
+- `freeTrack():` this simply removes the subtitles. You can use the methods above to set a new subtitle file to be displayed.
 
 ```js
 renderer.setTrackByUrl('/newsub.ass')
@@ -129,6 +155,7 @@ console.log(stats)
 //   maxRenderTime: 8.32,
 //   minRenderTime: 0.12,
 //   lastRenderTime: 1.23,
+//   timingCompensationMs: 4.8,
 //   renderFps: 60,
 //   usingWorker: true,
 //   offscreenRender: true,
@@ -151,26 +178,27 @@ console.log(`Events: ${eventCount}, Styles: ${styleCount}`)
 
 **Stats Reference:**
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `framesRendered` | number | Total frames rendered since reset |
-| `framesDropped` | number | Frames dropped due to slow rendering |
-| `avgRenderTime` | number | Average render time in milliseconds |
-| `maxRenderTime` | number | Maximum render time in milliseconds |
-| `minRenderTime` | number | Minimum render time in milliseconds |
-| `lastRenderTime` | number | Most recent render time in milliseconds |
-| `renderFps` | number | Estimated render FPS based on timing |
-| `usingWorker` | boolean | Whether using Web Worker |
-| `offscreenRender` | boolean | Whether offscreen rendering is enabled |
-| `onDemandRender` | boolean | Whether on-demand rendering is enabled |
-| `pendingRenders` | number | Number of pending render operations |
-| `totalEvents` | number | Total subtitle events in current track |
-| `cacheHits` | number | Number of cache hits (unchanged frames) |
-| `cacheMisses` | number | Number of cache misses (rendered frames) |
-
-## WebGPU Rendering
-
-AkariSub automatically uses WebGPU for GPU-accelerated rendering when available, with automatic fallback to Canvas2D:
+| Property               | Type    | Description                                                             |
+| ---------------------- | ------- | ----------------------------------------------------------------------- |
+| `framesRendered`       | number  | Total frames rendered since reset                                       |
+| `framesDropped`        | number  | Frames dropped due to slow rendering                                    |
+| `avgRenderTime`        | number  | Average render time in milliseconds                                     |
+| `maxRenderTime`        | number  | Maximum render time in milliseconds                                     |
+| `minRenderTime`        | number  | Minimum render time in milliseconds                                     |
+| `lastRenderTime`       | number  | Most recent render time in milliseconds                                 |
+| `timingCompensationMs` | number  | Automatically learned presentation-latency compensation in milliseconds |
+| `renderFps`            | number  | Estimated render FPS based on timing                                    |
+| `usingWorker`          | boolean | Whether using Web Worker                                                |
+| `offscreenRender`      | boolean | Whether offscreen rendering is enabled                                  |
+| `onDemandRender`       | boolean | Whether on-demand rendering is enabled                                  |
+| `pendingRenders`       | number  | Number of pending render operations                                     |
+| `totalEvents`          | number  | Total subtitle events in current track                                  |
+| `cacheHits`            | number  | Number of cache hits (unchanged frames)                                 |
+| `cacheMisses`          | number  | Number of cache misses (rendered frames)                                |
+
+## GPU Rendering
+
+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:
 
 ```typescript
 import AkariSub from 'akarisub'
@@ -178,14 +206,14 @@ import AkariSub from 'akarisub'
 const renderer = new AkariSub({
   video: document.querySelector('video'),
   subUrl: './tracks/sub.ass',
-  preferWebGPU: true, // Enable WebGPU (default: true)
-  onWebGPUFallback: () => {
-    console.log('WebGPU unavailable, using Canvas2D fallback')
+  onCanvasFallback: () => {
+    console.log('No GPU renderer available, using Canvas2D fallback')
   }
 })
 
-// Check if WebGPU is being used
-if (renderer.isUsingWebGPU) {
+console.log(renderer.rendererType) // 'webgpu' | 'webgl2' | 'canvas2d'
+
+if (renderer.isUsingGPURenderer) {
   console.log('GPU-accelerated rendering enabled!')
 }
 ```
@@ -194,178 +222,190 @@ if (renderer.isUsingWebGPU) {
 
 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 | `true` | Use async rendering with ImageBitmap for GPU offloading |
-| `offscreenRender` | boolean | `true` | Render fully on the worker, greatly reduces CPU usage |
-| `onDemandRender` | boolean | `true` | Render subtitles as the video player renders frames |
-| `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 |
-| `workerUrl` | string | `'akarisub-worker.js'` | URL to the worker script |
-| `wasmUrl` | string | `'akarisub-worker.wasm'` | URL to the WASM binary |
-| `subUrl` | string | - | URL of the subtitle file to play |
-| `subContent` | string | - | Content of the subtitle file to play |
-| `fonts` | (string \| Uint8Array)[] | - | Array of font URLs or Uint8Arrays to force load |
-| `availableFonts` | Record<string, string \| Uint8Array> | `{'liberation sans': './default.woff2'}` | Available fonts map (lowercase name → URL/data) |
-| `fallbackFont` | string | `'liberation sans'` | Fallback font family key |
-| `useLocalFonts` | boolean | `false` | Use Local Font Access API if available |
-| `libassMemoryLimit` | number | - | libass bitmap cache memory limit in MiB |
-| `libassGlyphLimit` | number | - | libass glyph cache limit |
-| `preferWebGPU` | boolean | `true` | Prefer WebGPU renderer if available |
-| `onWebGPUFallback` | function | - | Callback when WebGPU is unavailable |
+| 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)                                                                                             |
 
 ## Methods
 
 ### Track Management
 
-| Method | Parameters | Description |
-|--------|------------|-------------|
-| `setTrackByUrl(url)` | `url: string` | Load subtitle from URL |
-| `setTrack(content)` | `content: string` | Set subtitle from string content |
-| `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                                         |
 
 ### 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 |
+| 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 |
 
 ### 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 |
+| `resize(width?, height?, top?, left?, force?)` | `width?: number, height?: number, top?: number, left?: number, force?: boolean` | Resize the canvas           |
 
 ### Event Management
 
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `createEvent(event)` | `event: Partial<ASSEvent>` | `void` | Create a new ASS event |
-| `setEvent(event, index)` | `event: Partial<ASSEvent>, index: number` | `void` | Overwrite event at index |
-| `removeEvent(index)` | `index: number` | `void` | Remove event at index |
-| `getEvents()` | - | `Promise<ASSEvent[]>` | Get all ASS events |
-| `getEventCount()` | - | `Promise<number>` | Get event count (lightweight) |
+| Method                   | Parameters                                | Returns               | Description                   |
+| ------------------------ | ----------------------------------------- | --------------------- | ----------------------------- |
+| `createEvent(event)`     | `event: Partial<ASSEvent>`                | `void`                | Create a new ASS event        |
+| `setEvent(event, index)` | `event: Partial<ASSEvent>, index: number` | `void`                | Overwrite event at index      |
+| `removeEvent(index)`     | `index: number`                           | `void`                | Remove event at index         |
+| `getEvents()`            | -                                         | `Promise<ASSEvent[]>` | Get all ASS events            |
+| `getEventCount()`        | -                                         | `Promise<number>`     | Get event count (lightweight) |
 
 ### Style Management
 
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `createStyle(style)` | `style: Partial<ASSStyle>` | `void` | Create a new ASS style |
-| `setStyle(style, index)` | `style: Partial<ASSStyle>, index: number` | `void` | Overwrite style at index |
-| `removeStyle(index)` | `index: number` | `void` | Remove style at index |
-| `getStyles()` | - | `Promise<ASSStyle[]>` | Get all ASS styles |
-| `getStyleCount()` | - | `Promise<number>` | Get style count (lightweight) |
-| `styleOverride(style)` | `style: Partial<ASSStyle>` | `void` | Set a style override |
-| `disableStyleOverride()` | - | `void` | Disable style override |
+| Method                   | Parameters                                | Returns               | Description                   |
+| ------------------------ | ----------------------------------------- | --------------------- | ----------------------------- |
+| `createStyle(style)`     | `style: Partial<ASSStyle>`                | `void`                | Create a new ASS style        |
+| `setStyle(style, index)` | `style: Partial<ASSStyle>, index: number` | `void`                | Overwrite style at index      |
+| `removeStyle(index)`     | `index: number`                           | `void`                | Remove style at index         |
+| `getStyles()`            | -                                         | `Promise<ASSStyle[]>` | Get all ASS styles            |
+| `getStyleCount()`        | -                                         | `Promise<number>`     | Get style count (lightweight) |
+| `styleOverride(style)`   | `style: Partial<ASSStyle>`                | `void`                | Set a style override          |
+| `disableStyleOverride()` | -                                         | `void`                | Disable style override        |
 
 ### Font Management
 
-| Method | Parameters | Description |
-|--------|------------|-------------|
-| `addFont(font)` | `font: string \| Uint8Array` | Add a font to the renderer |
-| `setDefaultFont(font)` | `font: string` | Change the default font family |
+| Method                 | Parameters                   | Description                    |
+| ---------------------- | ---------------------------- | ------------------------------ |
+| `addFont(font)`        | `font: string \| Uint8Array` | Add a font to the renderer     |
+| `setDefaultFont(font)` | `font: string`               | Change the default font family |
 
 ### Statistics & Debugging
 
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `getStats()` | - | `Promise<PerformanceStats>` | Get performance statistics |
-| `resetStats()` | - | `Promise<void>` | Reset statistics counters |
-| `getEventCount()` | - | `Promise<number>` | Get event count (lightweight) |
-| `getStyleCount()` | - | `Promise<number>` | Get style count (lightweight) |
-| `runBenchmark()` | - | `void` | Run a benchmark on the worker |
+| Method            | Parameters | Returns                     | Description                   |
+| ----------------- | ---------- | --------------------------- | ----------------------------- |
+| `getStats()`      | -          | `Promise<PerformanceStats>` | Get performance statistics    |
+| `resetStats()`    | -          | `Promise<void>`             | Reset statistics counters     |
+| `getEventCount()` | -          | `Promise<number>`           | Get event count (lightweight) |
+| `getStyleCount()` | -          | `Promise<number>`           | Get style count (lightweight) |
 
 ### Lifecycle
 
-| Method | Parameters | Description |
-|--------|------------|-------------|
-| `destroy(err?)` | `err?: Error \| string` | Destroy the renderer and cleanup |
-| `sendMessage(target, data?, transferable?)` | `target: string, data?: Record<string, any>, transferable?: Transferable[]` | Send data to worker |
+| Method                                      | Parameters                                                                  | Description                      |
+| ------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------- |
+| `destroy(err?)`                             | `err?: Error \| string`                                                     | Destroy the renderer and cleanup |
+| `sendMessage(target, data?, transferable?)` | `target: string, data?: Record<string, any>, transferable?: Transferable[]` | Send data to worker              |
 
 ## Properties
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `debug` | boolean | Enable/disable debug logging |
-| `prescaleFactor` | number | Scale factor for subtitles |
-| `prescaleHeightLimit` | number | Height limit for prescaling |
-| `maxRenderHeight` | number | Maximum render height |
-| `timeOffset` | number | Subtitle time offset in seconds |
-| `busy` | boolean | Whether the renderer is currently busy |
-| `isUsingWebGPU` | boolean | Whether WebGPU renderer is active (read-only) |
+| Property              | Type                                     | Description                                                   |
+| --------------------- | ---------------------------------------- | ------------------------------------------------------------- |
+| `debug`               | boolean                                  | Enable/disable debug logging                                  |
+| `prescaleFactor`      | number                                   | Scale factor for subtitles                                    |
+| `prescaleHeightLimit` | number                                   | Height limit for prescaling                                   |
+| `maxRenderHeight`     | number                                   | Maximum render height                                         |
+| `timeOffset`          | number                                   | Subtitle time offset in seconds                               |
+| `renderAhead`         | number                                   | Optional extra seconds to render ahead of the video clock     |
+| `framePrefetch`       | number                                   | Number of exact subtitle frames prepared ahead                |
+| `busy`                | boolean                                  | Whether the renderer is currently busy                        |
+| `rendererType`        | `'webgpu'` \| `'webgl2'` \| `'canvas2d'` | Active renderer backend (read-only)                           |
+| `isUsingGPURenderer`  | boolean                                  | Whether a hardware-accelerated renderer is active (read-only) |
+| `isUsingWebGPU`       | boolean                                  | _Deprecated_ - use `rendererType === 'webgpu'`                |
 
 ## Type Definitions
 
 ### ASSEvent
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `Start` | number | Start time in seconds |
-| `Duration` | number | Duration in seconds |
-| `Style` | string | Style name |
-| `Name` | string | Character name (informational) |
-| `MarginL` | number | Left margin override in pixels |
-| `MarginR` | number | Right margin override in pixels |
-| `MarginV` | number | Bottom margin override in pixels |
-| `Effect` | string | Transition effect |
-| `Text` | string | Subtitle text content |
-| `ReadOrder` | number | Read order number |
-| `Layer` | number | Z-index layer |
-| `_index` | number | Internal index (optional) |
+| Property    | Type   | Description                      |
+| ----------- | ------ | -------------------------------- |
+| `Start`     | number | Start time in milliseconds       |
+| `Duration`  | number | Duration in milliseconds         |
+| `Style`     | string | Style name                       |
+| `Name`      | string | Character name (informational)   |
+| `MarginL`   | number | Left margin override in pixels   |
+| `MarginR`   | number | Right margin override in pixels  |
+| `MarginV`   | number | Bottom margin override in pixels |
+| `Effect`    | string | Transition effect                |
+| `Text`      | string | Subtitle text content            |
+| `ReadOrder` | number | Read order number                |
+| `Layer`     | number | Z-index layer                    |
+| `_index`    | number | Internal index (optional)        |
 
 ### ASSStyle
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `Name` | string | Style name (case sensitive) |
-| `FontName` | string | Font family name |
-| `FontSize` | number | Font size |
-| `PrimaryColour` | number | Primary color (RGBA as uint32) |
-| `SecondaryColour` | number | Secondary color (RGBA as uint32) |
-| `OutlineColour` | number | Outline color (RGBA as uint32) |
-| `BackColour` | number | Background/shadow color (RGBA as uint32) |
-| `Bold` | number | Bold (-1 = true, 0 = false) |
-| `Italic` | number | Italic (-1 = true, 0 = false) |
-| `Underline` | number | Underline (-1 = true, 0 = false) |
-| `StrikeOut` | number | StrikeOut (-1 = true, 0 = false) |
-| `ScaleX` | number | Width scale (percent) |
-| `ScaleY` | number | Height scale (percent) |
-| `Spacing` | number | Extra spacing between characters (pixels) |
-| `Angle` | number | Rotation angle (degrees) |
-| `BorderStyle` | number | Border style (1 = outline + shadow, 3 = opaque box) |
-| `Outline` | number | Outline width (0-4 pixels) |
-| `Shadow` | number | Shadow depth (0-4 pixels) |
-| `Alignment` | number | Alignment (1-9, numpad style) |
-| `MarginL` | number | Left margin (pixels) |
-| `MarginR` | number | Right margin (pixels) |
-| `MarginV` | number | Vertical margin (pixels) |
-| `Encoding` | number | Font encoding |
-| `treat_fontname_as_pattern` | number | Treat font name as pattern |
-| `Blur` | number | Blur amount |
-| `Justify` | number | Text justification |
+| Property                    | Type   | Description                                         |
+| --------------------------- | ------ | --------------------------------------------------- |
+| `Name`                      | string | Style name (case sensitive)                         |
+| `FontName`                  | string | Font family name                                    |
+| `FontSize`                  | number | Font size                                           |
+| `PrimaryColour`             | number | Primary color (RGBA as uint32)                      |
+| `SecondaryColour`           | number | Secondary color (RGBA as uint32)                    |
+| `OutlineColour`             | number | Outline color (RGBA as uint32)                      |
+| `BackColour`                | number | Background/shadow color (RGBA as uint32)            |
+| `Bold`                      | number | Bold (-1 = true, 0 = false)                         |
+| `Italic`                    | number | Italic (-1 = true, 0 = false)                       |
+| `Underline`                 | number | Underline (-1 = true, 0 = false)                    |
+| `StrikeOut`                 | number | StrikeOut (-1 = true, 0 = false)                    |
+| `ScaleX`                    | number | Width scale (percent)                               |
+| `ScaleY`                    | number | Height scale (percent)                              |
+| `Spacing`                   | number | Extra spacing between characters (pixels)           |
+| `Angle`                     | number | Rotation angle (degrees)                            |
+| `BorderStyle`               | number | Border style (1 = outline + shadow, 3 = opaque box) |
+| `Outline`                   | number | Outline width (0-4 pixels)                          |
+| `Shadow`                    | number | Shadow depth (0-4 pixels)                           |
+| `Alignment`                 | number | Alignment (1-9, numpad style)                       |
+| `MarginL`                   | number | Left margin (pixels)                                |
+| `MarginR`                   | number | Right margin (pixels)                               |
+| `MarginV`                   | number | Vertical margin (pixels)                            |
+| `Encoding`                  | number | Font encoding                                       |
+| `treat_fontname_as_pattern` | number | Treat font name as pattern                          |
+| `Blur`                      | number | Blur amount                                         |
+| `Justify`                   | number | Text justification                                  |
 
 # How to build?
 
 ## Dependencies
 
+[mise](https://mise.jdx.dev) manages the toolchain (emsdk, bun, cmake — see `mise.toml`). You additionally need the usual autotools build dependencies:
+
 - git
-- emscripten (Configure the enviroment)
 - make
 - python3
-- cmake
 - pkgconfig
 - patch
 - libtool
@@ -374,29 +414,22 @@ The default options are best, and automatically fallback to the next fastest opt
 - ragel - Required by Harfbuzz
 - itstool - Required by Fontconfig
 - gperf - Required by Fontconfig
-- licensecheck
 
 ## Get the Source
 
-Run git clone --recursive https://github.com/altqx/akarisub.git
-
-## Build inside a Container
-
-### Docker
-
-1. Install Docker
-2. ./run-docker-build.sh
-3. Artifacts are in /dist/js
-
-### Buildah
+```bash
+git clone --recursive https://github.com/altqx/akarisub.git
+```
 
-1. Install Buildah and a suitable backend for buildah run like crun or runc
-2. ./run-buildah-build.sh
-3. Artifacts are in /dist/js
+## Build
 
-## Build without Containers
+```bash
+mise install      # installs emsdk, bun, cmake
+bun install       # JS dependencies
+make              # builds the static libs (fribidi, freetype, harfbuzz, fontconfig, libass, ...) and the WASM glue
+bun run build     # builds the WASM glue and TypeScript
+```
 
-1. Install the dependency packages listed above
-2. make
-   - If on macOS with libtool from brew, LIBTOOLIZE=glibtoolize make
-3. Artifacts are in /dist/js
+- If on macOS with libtool from brew, `LIBTOOLIZE=glibtoolize make`
+- Incremental rebuilds of the WASM glue only: `bun run build:wasm` (or `make worker`)
+- Artifacts are in `pkg/` (WASM glue and binary) and `dist/` (TypeScript)