ASS Subtitles Rendering

Relevant source files

The following files were used as context for generating this wiki page:

• ai-docs/007-音视频特效/001-ASS特效字幕/001-用AI写ASS特效字幕/index.md
• static/music/ass-worker/subtitles-octopus.js
• README.md
• blog/2026/04/14/01_博客更新日志.md
• ai-docs/007-音视频特效/002-特效风格设计/001-取材的六个来源/index.md

The ASS Subtitles Rendering system in HXLoLi provides high-performance, complex subtitle and lyric animation within the project's music player. It utilizes a custom fork of SubtitlesOctopus to render Advanced Substation Alpha (ASS) files onto a HTML5 Canvas. This system supports standard libass tags and extended VSFilterMod tags, enabling high-fidelity lyrics that sync with music playback.

Sources: README.md:32-35, blog/2026/04/14/01_博客更新日志.md:10-15

Core Architecture

The rendering engine operates using a Web Worker to prevent UI blocking during complex subtitle rasterization. It detects WebAssembly support to choose between high-performance WASM-based rendering or a legacy JavaScript fallback.

Rendering Workflow

1. The SubtitlesOctopus controller initializes the Web Worker.
2. The Worker loads the libass library (compiled to WASM).
3. The engine receives the music player's currentTime and renders the corresponding subtitle frame.
4. The rendered frame data is passed back to the main thread and drawn onto the lyric canvas.

The diagram shows the data flow from the music player through the worker to the final canvas rendering.
Sources: static/music/ass-worker/subtitles-octopus.js:4-20, 100-115, 235-250

Technical Implementation Details

SubtitlesOctopus Configuration

The system is configured via the SubtitlesOctopus constructor. Key parameters control memory limits, rendering quality, and font handling.

Parameter	Description	Default / Note
canvas	The HTML canvas element for rendering.	Required
renderMode	Choice between lossy or wasm-blend.	wasm-blend
targetFps	The refresh rate of the subtitle rendering.	24
libassMemoryLimit	Memory cap for the libass engine.	0 (No limit)
prescaleFactor	Scale factor for pre-rendering subtitles.	1.0
fonts	Array of font URLs used in the subtitles.	[]

Sources: static/music/ass-worker/subtitles-octopus.js:20-50

WebAssembly Support and Fallbacks

The engine performs a feature test for WebAssembly before initialization. If the browser does not support WebAssembly, it falls back to a legacy worker script.

try {
    if (typeof WebAssembly === "object" && typeof WebAssembly.instantiate === "function") {
        const module = new WebAssembly.Module(Uint8Array.of(0x0, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00));
        if (module instanceof WebAssembly.Module)
            supportsWebAssembly = (new WebAssembly.Instance(module) instanceof WebAssembly.Instance);
    }
} catch (e) { }

Sources: static/music/ass-worker/subtitles-octopus.js:4-13

ASS Specification for Web Rendering

To ensure subtitles display correctly within a web player's fixed dimensions, specific creation guidelines must be followed.

Coordinate Systems and Safe Areas

While the base resolution is typically 1920x1080, the web player crops this into a floating window. Authors must define a "Safe Area" to prevent text jitter and ensure visibility across different screen ratios.

• Safe Area Definition: A bounding box added with a margin (16px horizontal, 12px vertical).
• Two-Pass Method: Render once to find the content union box, then refine the safe area to maximize visual font size.

Timing and Logic

• Time Reference: Line variables (l.start/l.end) use the video timeline, while syllable variables (s.start/s.end) are relative to the start of the line.
• Relative Offset: Tags like \t must use relative offsets. \t(0, l.dur, ...) is correct; using absolute start/end times causes alignment errors.
• Modifier Requirements:
  • notext: Discards the replaced text to prevent coordinate corruption during drawing.
  • noblank: Prevents rendering isolated shapes on empty syllables.

Sources: ai-docs/007-音视频特效/001-ASS特效字幕/001-用AI写ASS特效字幕/index.md:38-50, 60-75, 120-135

Asset Management and Style

Font Selection

Subtitles use layered fonts based on usage context to maintain visual consistency with the original media.

• Staff/Title: Often uses formal or specific branded fonts (e.g., 華康魏碑體).
• Lyrics: Distinct fonts for Japanese and Chinese translations to maintain readability.
• Commentary: Informal fonts for secondary text (e.g., 華康POP1體).

Visual Integration

Rendering follows specific color allocation rules derived from character attributes (e.g., "chino" uses pale blue).

• Stroke/Blur: Border thickness typically ranges from 1 to 2, with edge blurring between 6 and 8.
• Saturation: High saturation depends on the background source; clear, simple backgrounds tolerate higher saturation better than complex ones.

This sequence illustrates the synchronization between the player time updates and the asynchronous worker rendering.
Sources: static/music/ass-worker/subtitles-octopus.js:290-310, ai-docs/007-音视频特效/002-特效风格设计/001-取材的六个来源/index.md:70-90, 110-130

Pre-Cropping and Optimization

Because standard ASS is designed for full 16:9 video, the system implements a "Smooth Cropping" (平滑裁剪) algorithm. This allows the player to support top/bottom lyric separation (e.g., Chinese at the top, Japanese at the bottom) without making the text too small or causing visual stutter during window transitions.

Sources: blog/2026/04/14/01_博客更新日志.md:25-35

The ASS Subtitles Rendering system enables high-quality, synchronized visual experiences by combining a WebAssembly-powered engine with strict design specifications. By offloading rendering to workers and utilizing safe-area optimization, HXLoLi maintains a fluid interface even with complex, particle-heavy lyric animations.