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

npm install assjs-v2

Importing

<script type="module">
  import ASS from '/path/to/assjs-v2/dist/ass.min.js';
</script>

or via global script:

<script src="/path/to/assjs-v2/dist/ass.global.min.js"></script>
<script>
  console.log(window.ASS);
</script>

🧩 Usage

<div id="player">
  <video id="video" src="./example.mp4"></video>
  <div id="ass-container"></div>
</div>

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:

<div id="player" style="position: relative;">
  <video id="video" src="./example.mp4" style="position: absolute; top: 0; left: 0;"></video>
  <div id="ass-container" style="position: absolute; top: 0; left: 0;"></div>
</div>

If using the native fullscreen button, only the <video> goes fullscreen, hiding subtitles. Instead, call:

document.querySelector('#player').requestFullscreen();

⚙️ API Reference

Initialization

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

Methods

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

Delay

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

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.

🪪 License

MIT © Shahzad Siddique