A Gpu Accelerated Javascript Advanced Substation Alpha Subtitles Renderer.
SABRE.js adds stylish subtitles to web videos.
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.
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.
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.
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.
- loadSubtitles(subtitles, fonts) ⇒
void Begins the process of parsing the passed subtitles in SSA/ASS format into subtitle events.
- 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.
- setViewport(width, height) ⇒
void Updates the resolution (in CSS pixels) at which the subtitles are rendered (if the player is resized, for example).
- checkReadyToRender() ⇒
boolean Checks if the renderer is ready to render a frame.
- getFrame(time) ⇒
ImageBitmap Fetches a rendered frame of subtitles as an ImageBitmap, returns null if ImageBitmap is unsupported.
- getFrameAsUri(time, callback) ⇒
void Fetches a rendered frame of subtitles as an object uri.
- drawFrame(time, canvas, [contextType]) ⇒
void Fetches a rendered frame of subtitles to a canvas.
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). |
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). |
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). |
Checks if the renderer is ready to render a frame.
Kind: global function
Returns: boolean - is the renderer ready?
Access: public
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. |
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. |
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. |
Looking to contribute? Check out the contributing guide!
© 2012-2024 Patrick "ILOVEPIE" Rhodes Martin.
