JASSUB

The Fastest JavaScript SSA/ASS Subtitle Renderer For Browsers.

JASSUB is a JS wrapper for libass, which renders SSA/ASS subtitles directly in your browser. It uses Emscripten to compile libass' C++ code to WASM, and WebGL for hardware acceleration.

Demo

Features

• Supports all 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)
• Supports color space mangling (on browsers which support it)
• Capable of using local fonts (on browsers which support it)
• Capable of finding fonts online (opt-in, done via Google Fonts API)
• Works fast (all the heavy lifting is done by WebAssembly and WebGL, with absolutely minimal JS glue)
• Is fully multi-threaded
• Is asynchronous (renders when available, not in order of execution)
• Benefits from hardware acceleration (uses WebGL)
• Doesn't manipulate the DOM to render subtitles
• Easy to use - just connect it to video element

Requirements

The

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

headers are recommended to use this library, as it uses SharedArrayBuffer for multi-threading, but if you can't set them, it will fallback automatically to work in single-threaded mode. Firefox doesn't support threading so they are not required there.

At minimum WASM + TextDecoder + OffscreenCanvas + Web Workers + Proxy + AbortController + Fetch + Promise + getVideoPlaybackQuality/requestVideoFrameCallback are required for JASSUB to work.

JASSUB supports Chrome/Safari/Firefox 80/17/105, you bring the support down to 67/16.2/68 if you enable some flags/settings in your browser for these features, and polyfill AbortController. For other engines other polyfills might be needed. Babel is also recommended if you need to support older JS engines as JASSUB ships as ES modules with modern syntax.

Usage

Install the library via:

[p]npm i jassub

import JASSUB from 'jassub'

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

If you use a custom bundler, and need to override the worker and wasm URLs you can instead do:

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, // you can also use: `new URL('jassub/dist/jassub-worker.js', import.meta.url)` instead of importing it as an url, or whatever solution suits you
  wasmUrl,
  modernWasmUrl
})

However this shoud almost never be necessary.

Using only with canvas

You're also able to use it without any video. However, that requires you to set the time the subtitles should render at yourself:

import JASSUB from 'jassub'

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

await instance.ready

instance.setCurrentTime(15)

Docs

The library is fully typed, so you can simply browse the types of instance or instance.renderer. "Private" fields are prefixed with _ such as _fontId or _findAvailableFonts, and shouldn't be used by developers, but can if the need arises.

instance.renderer calls are ALWAYS async as it's a remote worker, which means you should always await/then them for the IPC call to be serialized!!! For example:

const x = instance.renderer.useLocalFonts // does nothing, returns IPC proxy object
const y = await instance.renderer.useLocalFonts // returns true/false

instance.renderer.useLocalFonts = false // this is fine
await (instance.renderer.useLocalFonts = false) // or u can await it for safety

instance.renderer.setDefaultFont('Gandhi Sans') // this is fine, sets default font
await instance.renderer.setDefaultFont('Gandhi Sans') // or you can await if if you want

Make sure to always await instance.ready before running any methods!!!

Example usage can be found in the demo source here.

Understanding font management

If you know for sure that your subtitles use specific fonts, you can pre-load them via the fonts option when creating the JASSUB instance:

const instance = new JASSUB({
  video: document.querySelector('video'),
  subUrl: './tracks/sub.ass', 
  fonts: [new URL('./fonts/GandhiSans-Regular.woff', import.meta.url).href, new Uint8Array(data)]
})

This will load/fetch the fonts ASAP when the renderer and WASM is initiated, this process is non-blocking.

If you however have a very big database of fonts and/or you're unsure if your subtitles use, or you want to conserve memory, bandwidth etc you can define fonts via availableFonts, which is a case-insensitive, postscript-insensitive map of fonts and their sources. This means the keys can, but don't need to include the weight of the font, but it is preferred. For example:

const instance = new JASSUB({
  video: document.querySelector('video'),
  subUrl: './tracks/sub.ass',
  availableFonts: {
    'Gandhi Sans': new URL('./fonts/GandhiSans-Regular.ttf', import.meta.url).href,
    'RoBoTO mEdiuM': new Uint8Array(data), // this is quite stupid if you want to conserve resources, since the data will be lingering in memory, but it is supported
    'roboto': new URL('./fonts/Roboto-Medium.woff2', import.meta.url).href
  }
})

When JASSUB then needs one of these fonts for immediate rendering it will load the font from the given source, however this can cause a flash of unstyled text if the default font was previously loaded, as the font is being loaded asynchronously, which looks something like this:

With complex typesetting this might not just be text, but glyphs, icons etc. If the default font wasn't previously loaded and wasn't pre-loaded a FOUT won't happen!, and nothing will render for at most a few frames as the font is being downloaded from the given URL.

The above also applies to the default font, you can pre-load it via fonts[], or use availableFonts. If you use await instance.renderer.setDefaultFont('Gandhi Sans') and wish to preload it, you should do so manually via await instance.renderer.addFonts(['Gandhi Sans']), however this is not recommended as it can cause FOUTs as explained above. JASSUB defines and provides a default font so configuring one is not strictly necessary.

For the best user experience, which avoids FOUTs, while using as little memory/bandwidth as possible, you should use a config in the lines of:

const instance = new JASSUB({
  fonts: fileAttachments // extracted file attachments for the given video, for example MKV's attachments
  availableFonts: {
    'My Fallback Font Family Name': './fonts/MyFallbackFont.woff2' // or new URL(...).href, only necessary if you want a custom default font, don't include this in fonts[]!
  },
  defaultFont: 'My Fallback Font Family Name', // optional, only necessary if you want a custom default font
  queryFonts: 'localandremote' // optional, local or remote fonts will be queried if a font isn't found in fonts[] or availableFonts and is required for immediate rendering
})

About finding fonts online

By default, JASSUB will only use embedded, constructor defined and local fonts. However, if you want to enable online font finding, you can do so by setting the queryFonts option to 'localandremote' when creating the JASSUB instance, note that this loads 50+ KB of code:

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

This finds fonts from the free and public Google Fonts API if they aren't available locally or embedded, which has some privacy implications [in theory, not in practice]. Be mindful of the licensing. Note that Google Fonts doesn't include a lot of non-free fonts such as Arial, so this isn't a perfect solution.

Looking for backwards compatibility with much older browser engines?

If you want to support even older engines, then please check the v1.8.8 tag, or install it via:

[p]npm i jassub@1.8.8

Support for older browsers (without OffscreenCanvas, WebAssembly threads, etc) has been dropped in v2.0.0 and later.

How to build?

Get the Source

Run git clone --recursive https://github.com/ThaUnknown/jassub.git

Docker

1. Install Docker
2. ./run-docker-build.sh or ./run-docker-build.ps1