Server Runtime Core
Relevant source files
The following files were used as context for generating this wiki page:
The Server Runtime Core manages the backend operations for the HX-Music system. It provides a C++ based environment for music storage, metadata indexing, user authentication, and lyric processing. The server executes as a standalone binary or within a Docker container to serve client requests over HTTP and WebSocket protocols.
The core handles complex tasks such as Japanese lyric processing, ASS subtitle generation, and multi-user permission management. It integrates with the HXLibs library to provide asynchronous I/O and networking capabilities.
Sources: README.md, HX-Music-Server/doc/api.md:5-20, HX-Music-Server/include/api/MusicApi.hpp:35-45
System Architecture
The server adopts a C/S (Client/Server) architecture. It interacts with the filesystem for music storage and utilizes SQLite-based databases for metadata persistence.
The diagram shows the interaction between the API layer, the Data Access Objects (DAO), the physical storage, and external lyric processing tools.
Sources: HX-Music-Server/doc/api.md:10-40, HX-Music-Server/include/api/MusicApi.hpp:46-55
Core Components and Data Structures
Music Metadata (MusicDO)
The server maintains music information in a structured format. It utilizes a MusicDO structure to track file paths, naming, and artist details.
| Field | Type | Description |
|---|---|---|
| id | PrimaryKey<uint64_t> | Unique ID of the song |
| path | std::string | Relative path in ./file/music/ |
| musicName | std::string | Title of the song |
| singers | vector<string> | List of artists |
| musicAlbum | std::string | Album name |
| millisecondsLen | uint64_t | Duration in milliseconds |
Sources: HX-Music-Server/doc/api.md:58-65, HX-Music-Server/include/api/MusicApi.hpp:80-90
Permission System
The runtime core enforces security via an interceptor pattern. It defines three distinct permission levels:
- Administrator: Full access, including user management and music scanning.
- RegularUser: Ability to upload music and create playlists.
- ReadOnlyUser: Limited to searching and streaming music.
Sources: README.md:15-18, HX-Music-Server/include/api/MusicApi.hpp:115-125
File Upload and Synchronization
The server implements a two-stage upload process to handle large music files reliably. It supports breakpoint resumption (斷點續傳) to manage network interruptions.
The sequence diagram illustrates the transition from task initialization to WebSocket-based binary streaming and final file processing.
Sources: HX-Music-Server/doc/api.md:106-118, HX-Music-Server/include/api/MusicApi.hpp:160-250
Endpoint Implementation Core
The server uses custom macros to define asynchronous endpoints. These endpoints leverage C++20 coroutines for non-blocking I/O.
Music Management Endpoints
- Scanning: The
WS /music/runScan/wsendpoint triggers a directory traversal. It identifies new files in./file/music/that are not present in the database and extracts their metadata. - Download: The
GET /music/download/{id}endpoint supports range requests for seeking within audio files. - Metadata Retrieval: The
GET /music/info/{id}endpoint returns aMusicVOobject containing song details.
Sources: HX-Music-Server/doc/api.md:100-140, HX-Music-Server/include/api/MusicApi.hpp:110-155, include/api/ApiMacro.hpp:35-50
Storage Organization
The runtime core organizes data into specific directories within a volume, typically mapped to ./data.
| Directory Path | Content Description |
|---|---|
file/music/ | Audio files (MP3, FLAC, etc.) |
file/db/ | SQLite databases (music.db, playlist.db, user.db) |
file/lyrics/ | ASS subtitle files generated by the Python tool |
file/cover/ | Extracted album artwork |
file/musicInfo/ | Detailed JSON metadata |
Sources: HX-Music-Server/doc/api.md:20-45, HX-Music-Server/include/api/MusicApi.hpp:75-80
Execution Environment
The server runtime requires specific environment variables and system capabilities when deployed via Docker.
environment:
- AEGISUB_HOME=/usr/share/aegisub
cap_add:
- SYS_ADMIN
- SYS_RESOURCE
- NET_ADMIN
The AEGISUB_HOME variable is critical for the lyric processing engine, while capabilities like SYS_ADMIN are required for certain system-level operations in the containerized environment.
Sources: README.md:95-110, HX-Music-Server/REAMDE.md:15-35
Conclusion
The Server Runtime Core provides the foundational infrastructure for the HX-Music ecosystem. By combining high-performance C++ coroutines for network handling with Python-based tools for specialized linguistic tasks, the server achieves a balance between performance and feature richness. It ensures data integrity through structured storage and protects resources with a tiered permission model.
Sources: README.md, HX-Music-Server/doc/api.md