ASS.js (v2 by Shahzad)


・
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.

---

📦 Installation


``bash
npm install assjs-v2
``

$3

`html

`

or via global script:

`html


`

---

🧩 Usage

`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();
`

---

⚙️ API Reference

$3

`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',
});
`

---

$3

`js
ass.show(); // Show subtitles
ass.hide(); // Hide subtitles
ass.destroy(); // Destroy instance
`

---

$3

`js
ass.delay = 5; // Subtitles appear 5s later
ass.delay = -3; // Subtitles appear 3s earlier
`

---

📐 Resampling

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';
`

---

🌐 Browser Compatibility

| Feature | Web API | Chrome | Firefox | Safari |
| --------------------------- | ------------------------------------------------------------------------------------------------------------- | ------ | ------- | ------ |
| Auto resize | ResizeObserver | 64 | 69 | 13.1 |
| \[i]clip | clip-path / path() | 88 | 97 | 13.1 |
| Animations (\t) | registerProperty() | 78 | 128 | 16.4 |
| accel in \t | linear() | 113 | 112 | 17.2 |
| \q0 | text-wrap: balance | 114 | 121 | 17.5 |
| BorderStyle=3 with \bord0 | @container | 111 | - | 18.0 |
| \blur with \bord0 | round() | 125 | 118 | 15.4 |

---

🧠 Notes

* assjs-v2 introduces the new container resampling mode for responsive, container-based rendering.
* Original library by @weizhenye
* Maintained and improved by @code-with-shahzad

---

---

💼 Connect with Me

I’m always open to collaborations and discussions about open-source projects, AI, and frontend innovation.

![LinkedIn](https://www.linkedin.com/in/shahzadsiddique1)
![GitHub](https://github.com/code-with-shahzad)
![Email](mailto:mshahzadsiddique5@gmail.com)

---

🪪 License

MIT © Shahzad Siddique

``