Music Playback & Wayland Integration
Relevant source files
The following files were used as context for generating this wiki page:
HX-Music is a C/S architecture music player designed primarily for Japanese songs with advanced support for ASS (Advanced Substation Alpha) subtitle rendering. The system facilitates high-fidelity music playback integrated with floating lyric windows, specifically optimized for Linux environments using the Wayland display protocol.
The integration focuses on overcoming Wayland-specific limitations regarding window positioning and transparency. It achieves this through specific KDE Plasma window rules and a unique full-screen masking strategy for rendering ASS lyrics.
Sources: README.md:1-12, HX-Music-Client/README.md:214-220
Music Playback Architecture
The playback system utilizes a client-server model where the server handles music storage, indexing, and metadata extraction, while the client manages the user interface and audio output.
Server-Side Data Flow
The server manages song data using a MusicDAO and indexes information in a SQLite database (music.db). It extracts metadata such as titles, artists, and album art using the TagLib library during the scanning or upload process.
The server provides endpoints for downloading music with range request support (/music/download/{id}) and fetching song metadata (/music/info/{id}).
Sources: HX-Music-Server/doc/api.md:59-70, HX-Music-Server/include/api/MusicApi.hpp:82-95, HX-Music-Server/include/utils/MusicInfo.hpp:67-158
Client-Side Playback Control
The client uses a MusicController and various models like AllMusicListModel to manage the playback queue. Playback state, including volume, play mode, and last position, is persisted in a local configuration.
| Component | Responsibility |
|---|---|
MusicController | Manages active audio playback and progress tracking. |
MusicListModel | Handles the current active playlist data. |
AllMusicListModel | Manages paginated music discovery from the server. |
MusicConfig | Persists user settings like volume and last played ID. |
Sources: HX-Music-Client/src/main.cpp:135-165, HX-Music-Client/include/model/AllMusicListModel.hpp:109-145, HX-Music-Client/README.md:151-158
Wayland Integration & Window Management
Due to security restrictions in the Wayland protocol, standard X11 window operations like "Always on Top" and "Taskbar Hiding" are not natively supported through client-side code. HX-Music implements a hybrid approach using KDE Plasma window rules and specific Qt window flags.
Lyric Window Strategy
The client implements a "Full Screen Mask" solution for ASS rendering to prevent layout jitter and coordinate mismatches.
The Qt.ToolTip flag is utilized to bypass certain Wayland popup constraints, though it requires specific handling of the transientParent.
Sources: HX-Music-Client/README.md:11-60, HX-Music-Client/README.md:104-108
Required KWin Rules
To achieve persistent positioning and visual integration on Wayland, you must import the following rules into KDE System Settings:
[自动顶置顶置]
above=true
aboverule=2
title=[Wayland置顶]
wmclass=HX
[隐藏切换]
skippager=true
skipswitcher=true
skiptaskbar=true
title=[Wayland隐藏切换]
wmclass=HX
These rules ensure the lyric window remains above other windows and does not appear in the taskbar or Alt-Tab switcher.
Sources: README.md:60-78, HX-Music-Client/README.md:225-243
ASS Lyric Rendering System
The rendering engine processes ASS subtitles to support complex karaoke effects and furigana (Japanese pronunciation guides).
Rendering Logic
- Coordinate Scanning: The system scans the ASS file to determine the full bounding box of the lyrics.
- Full-Screen Buffer: Rendering occurs in a full-screen context to maintain coordinate accuracy.
- Cropping: The active lyric area is cropped from the full-screen buffer to the floating window dimensions.
- Anti-Jitter: By using full-screen coordinate references, the system eliminates vertical jitter caused by dynamic animation commands like
\posor\clip.
Sources: HX-Music-Client/README.md:38-58
Configuration Parameters
Lyric behavior is controlled by the LyricConfig structure:
| Parameter | Type | Description |
|---|---|---|
lyricOffset | long long | Manual time adjustment for synchronization. |
isFullScreen | bool | Toggles between windowed and full-screen mask mode. |
isLocked | bool | Prevents accidental movement of the lyric window. |
windowX/Y | int | Persisted coordinates for window placement. |
Sources: HX-Music-Client/README.md:162-184
Summary
The "Music Playback & Wayland Integration" in HX-Music solves the challenge of rendering high-performance ASS lyrics in modern Linux environments. By combining a robust C++ backend for metadata extraction with a specialized Qt/QML frontend that utilizes KWin-specific window rules, the system provides a seamless floating lyric experience on Wayland.