A lightweight JavaScript ASS subtitle renderer
npm install assjs-v2



・
Online Demo
・
ASS Specs (zh-Hans)
・
ass-compiler
---
ASS.js renders ASS subtitles on HTML5 videos using DOM elements with almost full ASS feature support.
It’s lightweight, accurate, and ideal for the web, being around 60× smaller than WebAssembly-based solutions:
| | Solution | Size |
| - | - | - |
| ASS.js | DOM |  |
| JavascriptSubtitlesOctopus | WebAssembly |    |
| JASSUB | WebAssembly |    |
WebAssembly solutions often require large fallback fonts to prevent CJK text from rendering as tofu.
ASS.js uses the browser’s built-in font fallback, so it works out of the box.
---



``bash``
npm install assjs-v2
`html`
or via global script:
`html`
---
`html`
`js
import ASS from 'assjs-v2';
const content = await fetch('/path/to/example.ass').then(res => res.text());
const ass = new ASS(content, document.querySelector('#video'), {
container: document.querySelector('#ass-container'),
});
`
When initialized, ASS appends subtitle elements inside the container and automatically syncs the rendering area with the video.
Make sure your container overlaps the video properly:
`html`
If using the native fullscreen button, only the
`js`
document.querySelector('#player').requestFullscreen();
---
`js
const ass = new ASS(content, video, {
// Subtitles display inside this container
container: document.getElementById('my-container'),
// Controls how subtitle scaling is calculated
resampling: 'video_width',
});
`
---
`js`
ass.show(); // Show subtitles
ass.hide(); // Hide subtitles
ass.destroy(); // Destroy instance
---
`js`
ass.delay = 5; // Subtitles appear 5s later
ass.delay = -3; // Subtitles appear 3s earlier
---
When the ASS script resolution (PlayResX / PlayResY) does not match the video resolution,
the resampling option controls how scaling behaves.
> Drawings and clips always follow the original script resolution.
| Value | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| video_width | Scale based on video width. Example: 640×480 → scaled to 640×360, scale = 1280 / 640 = 2. |video_height
| (default) | Scale based on video height. Example: 640×480 → scaled to 853×480, scale = 720 / 480 = 1.5. |script_width
| | Keep script resolution but scale using script width. May cause vertical cropping. |script_height
| | Keep script resolution but scale using script height. Centered vertically. |container
| | 🆕 (New in v2) — Script resolution automatically matches the container size. Ideal for responsive overlays or custom players. |
`js`
ass.resampling = 'container';
---
| Feature | Web API | Chrome | Firefox | Safari |
| --------------------------- | ------------------------------------------------------------------------------------------------------------- | ------ | ------- | ------ |
| Auto resize | ResizeObserver | 64 | 69 | 13.1 |
| \[i]clip | clip-path / path() | 88 | 97 | 13.1 |\t
| Animations () | registerProperty() | 78 | 128 | 16.4 |\t
| accel in | linear() | 113 | 112 | 17.2 |\q0
| | text-wrap: balance | 114 | 121 | 17.5 |\bord0
| BorderStyle=3 with | @container | 111 | - | 18.0 |\blur
| with \bord0 | round() | 125 | 118 | 15.4 |
---
* assjs-v2 introduces the new container resampling mode for responsive, container-based rendering.
* Original library by @weizhenye
* Maintained and improved by @code-with-shahzad
---
---
I’m always open to collaborations and discussions about open-source projects, AI, and frontend innovation.



---
MIT © Shahzad Siddique
``