SubtitlesOctopus Documentation

SubtitlesOctopus supports three rendering modes via the renderMode option:

1. WASM Blending (wasm-blend): The default mode. It blends bitmaps of different events within WebAssembly. This is faster when many or complex subtitles are displayed simultaneously. Falls back to asm.js if WebAssembly is unavailable.
2. JS Blending (js-blend): Performs bitmap processing outside of WebAssembly using JavaScript.
3. Lossy Render Mode (lossy): EXPERIMENTAL. Uses createImageBitmap to render bitmaps in the Worker using Promises. This prevents the main thread from hanging/freezing during heavy subtitle rendering, though it may cause bitmap loss or skipped frames on low-end devices. Warning: Not stable and not supported in all browsers.

You can use SubtitlesOctopus without a video element by providing a canvas element in the options. When using this mode, you must manually manage the subtitle timing using instance.setCurrentTime(time).

var options = {
    canvas: document.getElementById('canvas'), // canvas element
    subUrl: '/test/test.ass',
    fonts: ['/test/font-1.ttf', '/test/font-2.ttf'],
    workerUrl: '/libassjs-worker.js'
};
var instance = new SubtitlesOctopus(options);
// Render subtitles at 00:15 on your canvas
instance.setCurrentTime(15);

To display .ass subtitles on an HTML5 video element, instantiate SubtitlesOctopus with an options object containing the video element and the subUrl (or subContent). SubtitlesOctopus will automatically connect to the video and begin rendering.

var options = {
    video: document.getElementById('video'), // HTML5 video element
    subUrl: '/test/test.ass', // Link to subtitles
    fonts: ['/test/font-1.ttf', '/test/font-2.ttf'], // Links to fonts
    workerUrl: '/libassjs-worker.js', // Link to WebAssembly-based file
    legacyWorkerUrl: '/libassjs-worker-legacy.js' // Link to non-WebAssembly worker
};
var instance = new SubtitlesOctopus(options);

Use the following methods to update the subtitle track during playback without re-instantiating the object:

• setTrackByUrl(url): Sets the subtitle track using a URL (equivalent to the subUrl option).
• setTrack(content): Sets the subtitle track using raw string content (equivalent to the subContent option).
• freeTrack(): Removes the current subtitles.

var instance = new SubtitlesOctopus(options);

// Change the subtitles to a new URL
instance.setTrackByUrl('/test/railgun_op.ass');

To prevent memory leaks and correctly dispose of the Web Worker and other resources, call instance.dispose() when you are finished with the subtitle rendering.

var instance = new SubtitlesOctopus(options);

// After you've finished using it...
instance.dispose();

The library allows direct manipulation of the subtitle track's contents:

Events

• getEventCount(): Returns the total number of events in the current track.
• allocEvent(): Allocates a new event in the track.
• removeEvent(eid): Removes an event by its ID.
• removeAllEvents(): Flushes all events from the track.

Styles

• getStyleCount(): Returns the number of styles defined in the track.
• getStyleByName(name): Returns the index of a style by its name.
• allocStyle(): Allocates a new style.
• removeStyle(sid): Removes a style by its ID.

The SubtitleOctopus class provides several methods to fine-tune the rendering behavior:

• Set Margins: Use setMargin(top, bottom, left, right) to adjust the subtitle positioning relative to the canvas edges.
• Memory Limits: Use setMemoryLimits(glyph_limit, bitmap_cache_limit) to constrain the memory used by libass for glyphs and bitmap caching (values in MiB).
• Drop Animations: Use setDropAnimations(value) (where value is truthy) to strip out animated ASS tags (like karaoke, fades, or transforms). This is useful for performance or when animations are not supported by your rendering pipeline. Once dropped, animations cannot be restored without reloading the track.

You can load subtitle data into the renderer using either a file path or a memory buffer.

• From a file: Use createTrack(subfile) where subfile is the path to an .ass or .ssa file.
• From memory: Use createTrackMem(buf, bufsize) to load subtitles from a raw buffer.

To prevent memory leaks, always call removeTrack() when you are finished with a track or before loading a new one. If you need to completely reset the library state, use reloadLibrary() or quitLibrary().

// Loading from a file
octopus.createTrack("subtitles.ass");

// Loading from a memory buffer
octopus.createTrackMem(buffer, bufferSize);

// Cleanup
octopus.removeTrack();

To start using the library, call initLibrary with the video frame dimensions and an optional default font name. This initializes the underlying libass library and renderer. You should also call resizeCanvas to set the rendering area dimensions.

Note that initLibrary also triggers reloadFonts which uses a specific configuration path (/assets/fonts.conf) to provide font support.

// Example initialization sequence
octopus.initLibrary(frame_w, frame_h, "MyFontName");
octopus.resizeCanvas(frame_w, frame_h);