assjs-v2

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