README.hbs

![SABRE.js](sabre.svg)
# SABRE.js: Substation Alpha suBtitles REnderer
A Gpu Accelerated Javascript Advanced Substation Alpha Subtitles Renderer. 

<span style="text-align:center; width:100%; display: inline-block;">[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier) [![CodeFactor](https://www.codefactor.io/repository/github/sabre-js/sabre.js/badge)](https://www.codefactor.io/repository/github/sabre-js/sabre.js) [![](https://data.jsdelivr.com/v1/package/npm/@sabre-js/sabre/badge)](https://www.jsdelivr.com/package/npm/@sabre-js/sabre) [![Featured on Openbase](https://badges.openbase.com/js/featured/@sabre-js/sabre.svg?token=X7lxF2mBNtaAGL5OtiKQkLjR8uUzMVOJtDX45rCSq1g=)](https://openbase.com/js/@sabre-js/sabre?utm_source=embedded&utm_medium=badge&utm_campaign=rate-badge)</span>

## What is SABRE.js?

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.

#### Other Similar software.

- Javascript-Subtitles-Octopus
- Libass
- XY-VSFilter

### Gallery
A gallery of major milestones in the development process.

To view the gallery click [here](/gallery/gallery.md) if you're using a decent browser or [here](/gallery/but_i_use_safari.md) if you like safari or internet explorer.

### Folder Structure

* src/ -- Main sourcecode for the project (excluding src/\_\_tests\_\_)
* src/\_\_tests\_\_/ -- Test code for test driven development.
* include/ -- Browser API definitions and internal API definitions for the Closure Compiler (Files in this folder aren't compiled).
* bin/ -- Output directory for production code.
* debugbin/ -- Output directory for debug code.
* sbin/ -- Contains scripts that are run by the makefile.
* tbin/ -- Contains the Closure Compiler and other build tools.
* temp_files/ -- Temporary files.
* test/ -- Directory used when running the debug server. 

### Documentation
How to include the library (from the jsdelivr CDN, this cdn is recommended as they publish usage statistics for each package):
```html
<script src="https://cdn.jsdelivr.net/npm/@sabre-js/sabre/dist/sabre.min.js"></script>
```
How to include the library (from the unpkg CDN, for the more privacy minded):
```html
<script src="https://unpkg.com/@sabre-js/sabre/dist/sabre.min.js"></script>
```

You can retrieve an instance of the library by calling `sabre.SABRERenderer` like so from a `load` event handler:
```js
let renderer;
window.addEventListener("load",() => {
    let subs = "";
    // load the contents of the subtitle file into subs
    // pass the font loading function to the renderer
    renderer = sabre.SABRERenderer(loadFont);
    renderer.loadSubtitles(subs);
    renderer.setViewport(1280,720); // use the video player's dimensions.
    // schedule your frame callback using either requestAnimationFrame or requestVideoFrameCallback
});
```
and passing it a function that loads fonts using the CSS Font loading API.

Here we provide a font loading function that you can use for testing:
```js
function loadFont(name) {
    // check if font is already loaded
    if (!document.fonts.check("12px '" + name + "'")){
        // if the name has an extension, load from local fonts
        if (name.indexOf(".") !== -1) {
            const newFont = new FontFace(name, `url(./fonts/${name})`);
            newFont.load().then((font) => document.fonts.add(font));
        }else{
            // otherwise, load from google fonts and add stylesheet to document
            let link = document.createElement("link");
            link.setAttribute("rel", "stylesheet");
            link.setAttribute("media", "print");
            link.setAttribute("type", "text/css");
            link.setAttribute("onload", "this.media='all';");
            link.setAttribute(
                "href",
                `https://fonts.googleapis.com/css?family=${name}:100,100i,300,300i,400,400i,500,500i,700,700i,900,900i`
            );
            document.head.appendChild(link);
        }        
    }
    //Force the font to load.
    let force_load = document.createElement("span");
    force_load.setAttribute(
        "style",
        `font-family: '${name}';position:absolute;top:-999999px;left:0px;`
    );
    force_load.appendChild(document.createTextNode("Force Load"));
    document.body.appendChild(force_load);
}
```

You may then call `loadSubtitles` passing in a string 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

{{>main}}

&copy; 2012-2022 Patrick "ILOVEPIE" Rhodes Martin.