JASSUB: JavaScript SSA/ASS Subtitle Renderer

Install the JASSUB library using npm to get started with high-performance SSA/ASS subtitle rendering in the browser.

npm i jassub

You can use JASSUB without a video element by providing a canvas instead. In this mode, you are responsible for manually triggering renders using instance.manualRender with the appropriate timing and dimensions.

import JASSUB from 'jassub'

const instance = new JASSUB({
  canvas: document.querySelector('canvas'),
  subUrl: './tracks/sub.ass'
})

await instance.ready

instance.manualRender({
  expectedDisplayTime: performance.now(), 
  width: 1920, 
  height: 1080, 
  mediaTime: 10.20
})

To use JASSUB with a standard HTML5 video element, instantiate the JASSUB class and provide the video element and the subUrl pointing to your .ass or .ssa file.

import JASSUB from 'jassub'

const instance = new JASSUB({
  video: document.querySelector('video'),
  subUrl: './tracks/sub.ass'
})

The instance.renderer object communicates with a remote worker via IPC. Because of this, all calls to instance.renderer are asynchronous. You must await them to ensure the command is serialized and executed correctly.

// Always await renderer calls
await instance.renderer.setDefaultFont('Gandhi Sans');

// Setting properties is also an async IPC call
await (instance.renderer.useLocalFonts = false);

If you are using a custom bundler that requires explicit paths for the worker and WASM files, you can pass workerUrl, wasmUrl, and modernWasmUrl (for SIMD) in the constructor options.

import JASSUB from 'jassub'
import workerUrl from 'jassub/dist/jassub-worker.js?worker&url'
import wasmUrl from 'jassub/dist/jassub-worker.wasm?url' // non-SIMD fallback
import modernWasmUrl from 'jassub/dist/jassub-worker-modern.wasm?url' // SIMD

const instance = new JASSUB({
  video: document.querySelector('video'),
  subContent: subtitleString,
  workerUrl,
  wasmUrl,
  modernWasmUrl
})

To enable multi-threading via SharedArrayBuffer, it is highly recommended to serve your application with the following COOP/COEP headers:

{
  "Cross-Origin-Embedder-Policy": "require-corp",
  "Cross-Origin-Opener-Policy": "same-origin"
}

If these headers are not present, JASSUB will automatically fallback to single-threaded mode.

The JASSUB class implements the ClassHandle interface, which is used for manual memory management of the WASM objects.

• delete(): Immediately destroys the instance.
• deleteLater(): Schedules the instance for destruction.
• isDeleted(): Returns whether the instance has already been destroyed.
• clone(): Creates a clone of the current instance.
• [Symbol.dispose](): Supports the explicit resource management pattern (using using in TypeScript/JavaScript).

To use JASSUB, you must first initialize the WebAssembly module using the MainModuleFactory. This function returns a Promise that resolves to a MainModule object, which contains the JASSUB class constructor.

Note: The JASSUB constructor accepts three parameters:

1. _0 (number): Likely related to memory or initial configuration.
2. _1 (number): Likely related to memory or initial configuration.
3. _2 (any): Additional configuration options.

import MainModuleFactory from 'jassub';

async function init() {
  const module = await MainModuleFactory();
  const jassubInstance = new module.JASSUB(0, 0, {});
}

To use JASSUB, instantiate the JASSUB class with a JASSUBOptions object. You must provide either a video element or a canvas element, and either a subUrl (for subtitle files) or subContent (for raw subtitle text).

If you provide a video element without a canvas, JASSUB will automatically create a canvas, style it to overlay the video, and insert it into the DOM immediately after the video element.

import JASSUB from 'jassub';

const jassub = new JASSUB({
  video: document.querySelector('video'),
  subUrl: 'path/to/subtitles.ass',
  // Optional configuration
  timeOffset: 0,
  debug: false,
  prescaleFactor: 1.0,
  availableFonts: {
    'liberation sans': new URL('./default.woff2', import.meta.url).href
  }
});