Aegisub Lua Scripting Automation
Relevant source files
The following files were used as context for generating this wiki page:
Aegisub Lua Scripting Automation provides the logic for generating advanced ASS (Advanced Substation Alpha) karaoke effects within the HX-Music ecosystem. It automates the transformation of raw lyric data into formatted karaoke subtitles using the Aegisub Lua environment and a specialized command-line interface.
The system automates the application of karaoke templates, specifically supporting two-line karaoke effects and Japanese furigana (ruby characters). This automation is a critical component for the server-side lyric processing pipeline, which matches Japanese lyrics and generates finalized ASS files for the music player.
Sources: README.md:8-12, pyTool/README.md:65-71
Automation Architecture
The automation pipeline bridges Python-based management tools with the C++ Aegisub environment. The pyTool component triggers automation by calling aegisub-cli, which executes specific Lua scripts to process subtitle lines.
The diagram shows the flow from the Python management layer to the Lua-driven Aegisub processing engine.
Sources: pyTool/README.md:73-82, HX-Music-Server/REAMDE.md:46-51
Karaoke Style Transformation
The core automation logic resides in set-karaoke-style.lua. This script manages time-overlap between lyric lines and assigns specific styles to create a two-line alternating karaoke effect.
Processing Logic
The script iterates through subtitle lines, identifying those marked with a specific handle style. If lines overlap in time, the script distributes them into different layers to prevent visual collision.
- Style Assignment: It assigns styles in a
K1,K2,K3pattern to alternating lines. - Time Adjustment: It adjusts the
start_timeof lines based on anadvance_timeparameter and prepends\k(karaoke) tags to the text. - Separation Detection: If the gap between lines exceeds a
sep_threshold, it resets the start time alignment.
Sources: pyTool/lua/set-karaoke-style.lua:14-46
Automation Configuration
| Parameter | Type | Default Value | Description |
|---|---|---|---|
handle_style | string | "orig" | The input style name to be processed by the script. |
advance_time | integer | 100 ms | The amount of time to advance the subtitle start for lead-in. |
sep_threshold | integer | 2000 ms | The threshold to treat subsequent lines as a new sequence. |
Sources: pyTool/lua/set-karaoke-style.lua:60-63
Command Line Integration
Because standard Aegisub only provides a GUI, the project utilizes a modified version of aegisub-cli to allow headless automation from the server.
- CLI Interface: The Lua script defines
macro_set_style_clito allow execution without user interaction. - Installation: The script must be placed in the Aegisub
automation/autoloaddirectory. - Environment: On Linux, the server expects
AEGISUB_HOMEto be set to/usr/share/aegisub.
Sources: pyTool/README.md:76-88, HX-Music-Server/REAMDE.md:16-18, pyTool/lua/set-karaoke-style.lua:58-69
Server-Side Integration
The HX-Music Server exposes the automation through specialized endpoints. When a user requests to "karaoke-ize" lyrics, the server triggers the Python tools which in turn execute the Lua automation.
This sequence illustrates how a client request initiates the automated Lua processing on the server.
Sources: HX-Music-Server/doc/api.md:195-200, README.md:10-12
Client Rendering Considerations
While automation generates the files, the HX-Music Client handles the visual presentation. The client supports two primary rendering modes for the automated ASS output:
- Full Screen Mode: Captures the entire screen dimensions for rendering.
- Cropping Mode: Scans coordinates to determine the lyric bounding box and crops the rendered bitmap to avoid vertical jitter during animations.
Sources: HX-Music-Client/README.md:5-25
The Aegisub Lua automation is fundamental to the "Japanese furigana injection" and "two-line karaoke" features, transforming standard text lyrics into the project's signature visual style.
Sources: README.md:12, pyTool/README.md:9-12