SABRE.js: Substation Alpha suBtitles REnderer

A Gpu Accelerated Javascript Advanced Substation Alpha Subtitles Renderer.

What is SABRE.js?

SABRE.js adds stylish subtitles to web videos.

What formats does SABRE.js support?

SABRE.js is a full renderer for Substation Alpha Subtitles and Advanced Substation Alpha Subtitles. It allows you to draw styled/stylized subtitles over web video with multiple fonts, colors, animations and effects.

Gallery

A gallery of major milestones in the development process.

To view the gallery click here if you're using a decent browser or here if you like safari or internet explorer.

Getting Started

Note: Version 2.0.0 of opentype.js is not yet released, in order to use this library currently you must build opentype.js from source.

How to include the library (from the jsdelivr CDN, this cdn is recommended as they publish usage statistics for each package):

<script src="https://cdn.jsdelivr.net/npm/opentype.js@^2.0.0/dist/opentype.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@sabre-js/sabre@latest/dist/sabre.min.js"></script>

How to include the library (from the unpkg CDN, for the more privacy minded):

<script src="https://unpkg.com/opentype.js@^2.0.0/dist/opentype.min.js"></script>
<script src="https://unpkg.com/@sabre-js/sabre@latest/dist/sabre.min.js"></script>

You can retrieve an instance of the library by calling sabre.SABRERenderer().

Example:

let renderer;
let fonts = [];

// Load the contents of the subtitle file.
fetch("subtitles.ass").then((response) => response.arrayBuffer()).then((subs) => {
    // Load the fonts using opentype.js and put them in the fonts array. (this function also returns a promise)
    opentype.load("arial.ttf", (font) => {
        fonts.push(font);
        // Initialize the renderer
        renderer = sabre.SABRERenderer({
            fonts:fonts,
            subtitles:subs,
            colorSpace:sabre.VideoColorSpaces.AUTOMATIC,
            resolution:[1280,720], // Display resolution of the video in CSS pixels.
            nativeResolution:[1280,720] // Resolution of the video file in real pixels (only used if the color space is AUTOMATIC or AUTOMATIC_PC).
        });
        // Schedule your frame callback using either requestAnimationFrame or requestVideoFrameCallback
    });
});

or you can initialize using the return value's functions as shown below:

let renderer;
let fonts = [];

// Load the contents of the subtitle file.
fetch("subtitles.ass").then((response) => response.arrayBuffer()).then((subs) => {
    // Load the fonts using opentype.js and put them in the fonts array. (this function also returns a promise)
    opentype.load("arial.ttf", (font) => {
        fonts.push(font);
        // Initialize the renderer
        renderer = new sabre.SABRERenderer();
        renderer.loadSubtitles(subs,fonts);
        renderer.setColorSpace(sabre.VideoColorSpaces.AUTOMATIC,1280,720); // Second and third parameters are the native resolution of the video file in real pixels (only used if the color space is AUTOMATIC or AUTOMATIC_PC).
        renderer.setViewport(1280,720); // Display resolution of the video in CSS pixels.
    });
});

You may then call loadSubtitles passing in an ArrayBuffer containing the contents of the subtitle file and set the viewport with setViewport as shown in the example above. Anytime the video or player is resized you should call setViewport with the new dimensions of the player.

Each frame, before you call any of the rendering functions, first call checkReadyToRender to see if the library is ready to render a frame of subtitles.

API Documentation

The documentation generator is a little buggy, anytime it says something is global, that means it's a property of the sabre.SABRERenderer() function's returned object.

Functions

loadSubtitles(subtitles, fonts) ⇒ void

Begins the process of parsing the passed subtitles in SSA/ASS format into subtitle events.

Kind: global function
Access: public

| Param | Type | Description | | --- | --- | --- | | subtitles | ArrayBuffer | the subtitle file's contents. | | fonts | Array.<Font> | preloaded fonts necessary for this subtitle file (one of these MUST be Arial). |

setColorSpace(colorSpace, [width], [height]) ⇒ void

Configures the output colorspace to the set value (or guesses when automatic is specified based on resolution). Note: AUTOMATIC always assumes studio-swing (color values between 16-240), if you need full-swing (color values between 0-255) that must be set by selecting AUTOMATIC_PC. AUTOMATIC and AUTOMATIC_PC are also incapable of determining if the video is HDR, so you need to manually set either BT.2100_PQ or BT.2100_HLG if it is. Note: HDR support is stubbed and unimplemented currently.

Kind: global function
Access: public

| Param | Type | Description | | --- | --- | --- | | colorSpace | number | the colorspace to use for output. | | [width] | number | the x component of the video's resolution in regular pixels (only required when colorSpace is AUTOMATIC). | | [height] | number | the y component of the video's resolution in regular pixels (only required when colorSpace is AUTOMATIC). |

setViewport(width, height) ⇒ void

Updates the resolution (in CSS pixels) at which the subtitles are rendered (if the player is resized, for example).

Kind: global function
Access: public

| Param | Type | Description | | --- | --- | --- | | width | number | the desired width of the resolution (in CSS pixels). | | height | number | the desired height of the resolution (in CSS pixels). |

checkReadyToRender() ⇒ boolean

Checks if the renderer is ready to render a frame.

Kind: global function
Returns: boolean - is the renderer ready?
Access: public

getFrame(time) ⇒ ImageBitmap

Fetches a rendered frame of subtitles as an ImageBitmap, returns null if ImageBitmap is unsupported.

Kind: global function
Access: public

| Param | Type | Description | | --- | --- | --- | | time | number | the time at which to draw subtitles. |

getFrameAsUri(time, callback) ⇒ void

Fetches a rendered frame of subtitles as an object uri.

Kind: global function
Access: public

| Param | Type | Description | | --- | --- | --- | | time | number | the time at which to draw subtitles. | | callback | function | a callback that provides the URI for the image generated. |

drawFrame(time, canvas, [contextType]) ⇒ void

Fetches a rendered frame of subtitles to a canvas.

Kind: global function
Access: public

| Param | Type | Description | | --- | --- | --- | | time | number | the time at which to draw subtitles. | | canvas | HTMLCanvasElement | OffscreenCanvas | the target canvas | | [contextType] | string | the context type to use (must be one of "bitmap" or "2d"), defaults to "bitmap" unless unsupported by the browser, in which case "2d" is the default. |

Contributing

Looking to contribute? Check out the contributing guide!

© 2012-2024 Patrick "ILOVEPIE" Rhodes Martin.