Home

Awesome

<h1 align="center"> JASSUB </h1> <p align="center"> JavaScript SSA/ASS Subtitle Renderer. </p> JASSUB is a JS wrapper for <a href="https://github.com/libass/libass">libass</a>, which renders <a href="https://en.wikipedia.org/wiki/SubStation_Alpha">SSA/ASS subtitles</a> directly in your browser. It uses Emscripten to compile libass' C++ code to WASM. <p align="center"> <a href="https://thaunknown.github.io/jassub/">Online Demos</a> </p>

Features

Isn't this just the same thing as JavascriptSubtitlesOctopus?

No. See <a href="https://thaunknown.github.io/jassub/explainer.html">this</a> comparison.

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:

import JASSUB from './jassub.es.js'

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

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 you use a bundler like Vite, you can instead do:

npm i jassub

import JASSUB from 'jassub'
import workerUrl from 'jassub/dist/jassub-worker.js?url'
import wasmUrl from 'jassub/dist/jassub-worker.wasm?url'

const renderer = 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
  wasmUrl
})

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.es.js'

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

renderer.setCurrentTime(15)

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:

renderer.setTrackByUrl('/newsub.ass')

Cleaning up the object

After you're finished with rendering the subtitles. You need to call the destroy() method to correctly destroy the object.

const renderer = new JASSUB(options)
// After you've finished using it...
renderer.destroy()

Options

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. These options are included in the JSDoc of the object, so if your editor supports JSDoc IntelliSense you will see these exact descriptions when calling methods and specifying options.

Methods and properties

This library has a lot of methods and properties, however many aren't made for manual use or have no effect when changing, those are usually prefixed with _. Most of these never need to be called by the user.

List of properties:

List of methods:

ASS_Event object properties

ASS_Style object properties

How to build?

Dependencies

Get the Source

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

Build inside a Container

Docker

  1. Install Docker
  2. ./run-docker-build.sh
  3. Artifacts are in /dist/js

Buildah

  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 without Containers

  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