Introduction to HX-Music
Relevant source files
The following files were used as context for generating this wiki page:
HX-Music is a Client/Server (C/S) architecture music player specialized for Japanese songs and advanced subtitle rendering. The system renders ASS effect subtitles in floating windows and supports automated Japanese lyric matching and furigana (ruby characters) injection for karaoke-style displays.
Sources: README.md:3-10, HX-Music-Client/README.md:129-132
System Architecture
The project consists of three primary components: a C++ Qt/QML client, a C++ server for storage and API services, and a Python-based toolset for lyric processing.
High-Level Component Interaction
The following diagram illustrates the interaction between the client, server, and the specialized lyric processing tools.
The client communicates via RESTful APIs and WebSockets to manage music playback and metadata. The server handles persistent storage and triggers Python scripts to generate karaoke-style ASS subtitles.
Sources: README.md:12-16, HX-Music-Server/doc/api.md:12-32
Server-Side Architecture
The server manages music files, lyric data, and metadata using a structured file system and SQLite databases.
Storage Structure
Data is organized into specific directories within a base file/ path:
| Data Type | Path Convention | Storage Format |
|---|---|---|
| Music Files | file/music/${category}/${song_name} | Binary (.mp3, .flac, etc.) |
| Song Metadata | file/db/music.db | SQLite Database |
| Detailed Info | file/musicInfo/${song_id}.json | JSON File |
| Lyrics | file/lyrics/${song_id}.ass | ASS Subtitle File |
| Playlists | file/db/playlist.db | SQLite Database |
| Covers | file/cover/${song_id}.${ext} | Image File |
Sources: HX-Music-Server/doc/api.md:18-38, HX-Music-Server/include/config/DbPath.hpp:22-31, HX-Music-Server/include/api/MusicApi.hpp:85-93
Music Data Model
The server represents music internally using the MusicDO structure for database operations.
// Sources: HX-Music-Server/doc/api.md:52-58
struct MusicDO {
db::PrimaryKey<uint64_t> id; // Unique ID
std::string path; // Relative path to ~/file/music/
std::string musicName; // Song Title
std::vector<std::string> singers; // Artists
std::string musicAlbum; // Album
};
Client-Side Architecture
The client is built using C++ with Qt and QML, focusing on high-performance ASS rendering and a responsive UI.
Key Client Features
- Lyric Rendering: Supports full-screen and cropped rendering modes for ASS subtitles to handle complex animations and positional effects.
- Floating Windows: Implements a dedicated floating lyric window that supports "Window Top" rules in Wayland environments.
- Configuration Management: The
ConfigManagerclass persists user settings like server URL, volume, and playback modes tohxMusicConfig.json.
Sources: HX-Music-Client/README.md:6-14, HX-Music-Client/README.md:195-212, HX-Music-Client/include/config/ConfigManager.hpp:36-47
Subtitle Rendering Logic
The client addresses "jitter" (抖动) in subtitle rendering by calculating stable bounding boxes for ASS dialogues.
Sources: HX-Music-Client/README.md:18-38
Core API Definitions
The server provides endpoints for music management, user authentication, and lyric processing.
Music Management APIs
| Method | Endpoint | Description |
|---|---|---|
GET | /music/download/{id} | Download music with range support (breakpoint resume). |
WS | /music/runScan/ws | Manually scan the storage directory for new files. |
POST | /music/upload/init | Initialize a new music upload task. |
WS | /music/upload/push/{pushId} | Stream file data via WebSocket and receive progress updates. |
POST | /music/select | Paginated search and retrieval of song lists. |
Sources: HX-Music-Server/doc/api.md:112-165, HX-Music-Server/include/api/MusicApi.hpp:72-230
Upload Sequence
Music uploads follow a multi-step process to ensure file integrity and support resumes.
Metadata Extraction
Both client and server use the MusicInfo utility class, leveraging TagLib to extract metadata from various audio formats (MP3, FLAC, Ogg).
Metadata Handling Logic
- Title/Artist: Extracts basic tags; the
getArtistListmethod includes heuristic separation for artists joined by "feat.", "ft.", or Japanese delimiters like "、" and "／". - Covers: Attempts to extract embedded images (APIC for MP3, Vorbis picture blocks for FLAC).
- Duration: Calculates length in milliseconds and formats time as
HH:MM:SS.
Sources: HX-Music-Server/include/utils/MusicInfo.hpp:95-125, HX-Music-Client/include/utils/MusicInfo.hpp:78-100
Deployment
The system is designed for containerized deployment, specifically targeting NAS environments or private servers.
- Server: Deployed via
docker-compose. Requires theAEGISUB_HOMEenvironment variable for lyric processing. - Client: Provided as a
PKGBUILDfor Arch Linux. Requires specific window manager rules in KDE Wayland for floating window functionality.
Sources: README.md:46-75, HX-Music-Server/REAMDE.md:12-40
Conclusion
HX-Music provides a robust architecture for users who require high-quality Japanese music playback and specialized subtitle rendering. By separating the GUI (Qt/QML), backend services (C++/Coroutines), and lyric processing (Python/Aegisub), the system offers a professional solution for private music collections.