System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The HX-Music project implements a Client/Server (C/S) architecture specifically optimized for Japanese music playback and ASS (Advanced Substation Alpha) subtitle rendering. The system integrates a C++ Qt/QML client, a C++ high-performance server, and Python-based tools for automated lyric processing and Japanese furigana generation.
Sources: README.md:5-20, HX-Music-Server/doc/api.md:5-10
1. High-Level Architecture
The system divides responsibilities between a local client and a remote server (often deployed on NAS). The server handles persistence, song indexing, and lyric scraping, while the client manages audio playback and specialized subtitle rendering.
The diagram shows the communication flow between the C++ client, the C++ server backend, and the Python processing tool.
Sources: README.md:15-30, HX-Music-Server/doc/api.md:15-30, HX-Music-Client/include/config/ConfigManager.hpp:35-40
2. Server Architecture
The server utilizes a C++ backend based on HXLibs, which provides coroutine support and high-concurrency networking. It employs a Data Access Object (DAO) pattern to abstract interactions with SQLite databases and the local file system.
2.1 Storage Schema
The server organizes data into specific directory structures and SQLite files to optimize search and retrieval.
| Data Type | Storage Location | Description |
|---|---|---|
| Music Files | file/music/${category}/${song} | Physical audio files (MP3/FLAC). |
| Music Index | file/db/music.db | SQLite database for metadata indexing. |
| Music Metadata | file/musicInfo/${id}.json | Extended metadata in JSON format. |
| Lyrics | file/lyrics/${id}.ass | ASS formatted subtitle files. |
| Playlists | file/db/playlist.db | Playlist structure and song references. |
| Covers | file/cover/${id}${suffix} | Extracted album art. |
Sources: HX-Music-Server/doc/api.md:15-40, HX-Music-Server/include/api/MusicApi.hpp:55-65, HX-Music-Server/include/api/CoverApi.hpp:50-55
2.2 Core Data Structures
The server maintains an in-memory index using Red-Black trees (via std::map) to facilitate rapid searching of music metadata.
struct MusicDO {
db::PrimaryKey<uint64_t> id; // Unique ID
std::string path; // Relative path
std::string musicName; // Song title
std::vector<std::string> singers; // Artists
std::string musicAlbum; // Album name
uint64_t millisecondsLen; // Duration
std::string coverSuffix; // .jpg or .png
};
Sources: HX-Music-Server/doc/api.md:50-65, HX-Music-Server/include/api/MusicApi.hpp:45-55
3. Client Architecture
The client is built using Qt 6.9.1 and QML. It handles complex ASS rendering by calculating coordinates and managing a floating window.
3.1 Subtitle Rendering Logic
The client implements a specialized rendering flow to prevent jitter in Wayland environments. It pre-scans coordinates to determine the complete bounding box of the subtitle animation before rendering the frames to an output image.
The sequence illustrates how the client coordinates timestamp tracking with frame rendering to ensure smooth Japanese furigana display.
Sources: HX-Music-Client/README.md:10-50, HX-Music-Client/README.md:200-210
3.2 Configuration Management
The ConfigManager handles persistence of client states such as volume, play mode, and last played position using JSON files located in the system config path.
Sources: HX-Music-Client/include/config/ConfigManager.hpp:42-60, HX-Music-Client/README.md:150-170
4. API and Data Flow
Communication between components occurs primarily via RESTful JSON endpoints and WebSockets for long-running tasks.
4.1 Music Upload Sequence
The system uses a two-phase upload process to handle large music files reliably.
- Init: Client sends
InitUploadFileTaskVOto/music/upload/init. Server creates a.tmpplaceholder. - Push: Client opens a WebSocket to
/music/upload/push/{pushId}. - Write: Data is appended to the
.tmpfile. - Finalize: Server renames the file, extracts metadata (ID3/FLAC tags) via
MusicInfo, and extracts covers.
Sources: HX-Music-Server/doc/api.md:100-115, HX-Music-Server/include/api/MusicApi.hpp:148-245
4.2 Metadata Extraction
The MusicInfo utility leverages TagLib to extract technical properties from files.
The extraction process splits artist names using "feat.", "ft.", and Japanese delimiters to normalize the search index.
Sources: HX-Music-Server/include/utils/MusicInfo.hpp:50-120, HX-Music-Client/include/utils/MusicInfo.hpp:80-110
5. Security and Access Control
The architecture enforces a three-tier permission system managed by TokenInterceptor.
| Permission Level | Access Scope | Examples |
|---|---|---|
| ReadOnlyUser | Basic playback and search. | /music/download, /music/info |
| RegularUser | Content management. | /music/upload/init, /playlist/make |
| Administrator | System-wide operations. | /music/runScan/ws, /user/add |
Sources: HX-Music-Server/doc/api.md:195-210, HX-Music-Server/include/api/MusicApi.hpp:95-100, HX-Music-Server/include/api/CoverApi.hpp:55-60
Summary
HX-Music utilizes a robust C++-centric architecture that prioritizes performance and metadata accuracy for Japanese media. By offloading resource-intensive tasks (furigana generation, music scanning) to a server/tool environment while maintaining a responsive Qt-based UI, the system provides high-fidelity subtitle rendering and centralized library management.