Subtitles & Floating Graphics
Relevant source files
The following files were used as context for generating this wiki page:
HX-Music features a specialized subtitle rendering system focused on Advanced Substation Alpha (ASS) effects, particularly for Japanese songs. The system renders high-fidelity karaoke subtitles with furigana (Japanese pronunciation guides) within a floating desktop window. It supports complex animations, bitmap rendering, and custom layout calculations to ensure stable, jitter-free visual feedback across different windowing systems, specifically optimized for Wayland.
Sources: README.md:1-10, HX-Music-Client/README.md:1-10
Architecture and Rendering Logic
The subtitle system employs a "Full Screen Capture" strategy to handle complex ASS animations. The client renders the ASS content at full screen size and then crops the relevant area to a floating window. This avoids vertical jitter (shaking) caused by varying bitmap heights during character animations or complex compound commands like \clip and \pos.
Subtitle Data Flow
The following diagram illustrates the flow from raw lyrics to rendered floating graphics.
Key Components
| Component | Responsibility |
|---|---|
| libass | Handles the core rendering of ASS subtitle files with vector/bitmap effects. |
| pyTool (JpMark) | Performs lexical analysis and phonetic annotation (furigana) for Japanese text. |
| Aegisub (Lua) | Uses set-karaoke-style.lua to apply double-line karaoke templates and styles. |
| HX-Music-Client | Manages the floating QML window, coordinate mapping, and clipping logic. |
| HX-Music-Server | Provides API endpoints for downloading and batch-scanning ASS subtitles. |
Sources: README.md:15-25, HX-Music-Client/README.md:235-245, pyTool/README.md:70-90
Lyric Processing and Generation
The system automates the conversion of simple lyrics into feature-rich ASS files. This process involves crawling external sources, annotating Japanese text, and applying formatting templates.
Automated Workflow
- Crawling: The system uses
LDDC(Lyric Downloader) to fetch lyrics from cloud sources like QQ Music or NetEase. - Annotation:
pykakasiperforms morphological analysis. For example, it splits "あの日" into "あの" and "日" and assigns correct readings. - Styling: The system invokes
aegisub-cliwith custom Lua scripts to transform annotated text into karaoke-ready ASS lines.
Sources: HX-Music-Server/doc/api.md:150-165, pyTool/README.md:1-15, pyTool/README.md:110-120
Subtitle API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/lyrics/ass/select/{id} | GET | Retrieves the ASS subtitle file for a specific song ID. |
/lyrics/ass/karaok/{id} | POST | Triggers network crawling and karaoke/furigana processing for a song. |
/lyrics/ass/karaok/all/ws | WS | Batch processes all songs missing lyrics via WebSocket progress updates. |
Sources: HX-Music-Server/doc/api.md:145-165
Client Window Management
The floating subtitle window is implemented as a specialized QML window. On Linux Wayland systems, specific window rules are required to ensure the window remains "Above" (topmost) and is excluded from taskbars and pagers.
Configuration Structure
The client stores subtitle-related states to maintain persistence across sessions.
struct LyricConfig {
int windowX; // Current X position
int windowY; // Current Y position
int windowWidth; // Current width
int windowHeight; // Current height
long long lyricOffset; // Time offset in milliseconds
bool isWindowOpened; // Toggle state
bool isLocked; // Prevents mouse interaction
bool isFullScreen; // Rendering mode
};
Sources: HX-Music-Client/README.md:145-165
Wayland Support and Constraints
Because Wayland protocols restrict direct window positioning and "always on top" behavior, the application relies on external Window Rules (KDE/Wayland).
- Topmost Rule: Matches window title
[Wayland置顶]to force the window above others. - Taskbar Exclusion: Matches title
[Wayland隐藏切换]to setskippagerandskiptaskbarto true. - Focus Handling: The client detects window focus to prevent rendering bugs in the scrollbar when content updates occur while the window is hidden.
Sources: README.md:50-70, HX-Music-Client/README.md:80-95
Conclusion
The Subtitles & Floating Graphics module integrates C++ for high-performance rendering, Python for complex linguistic processing, and QML for flexible UI presentation. By utilizing a full-screen-to-crop rendering strategy, the system provides stable and visually sophisticated karaoke subtitles that are highly resilient to animation-induced jitter.
Sources: HX-Music-Client/README.md:25-45, pyTool/README.md:95-105