File Storage Ecosystem
Relevant source files
The following files were used as context for generating this wiki page:
The File Storage Ecosystem manages the persistence and organization of music files, metadata, lyrics, and database state within the HX-Music project. It provides a structured directory hierarchy on the server to separate physical audio assets from their indexed metadata and auxiliary data like covers or ASS subtitles. Sources: HX-Music-Server/doc/api.md:12-40, HX-Music-Server/include/api/MusicApi.hpp:67-105
The system coordinates between physical storage (files) and logical storage (SQLite databases) to support features such as song search, playlist management, and cover art extraction. Sources: HX-Music-Server/doc/api.md:43-70, HX-Music-Server/include/api/MusicApi.hpp:163-195
Server Storage Architecture
The server organizes all application data within a file/ root directory. It categorizes files based on their type and purpose to ensure efficient scanning and retrieval. Sources: HX-Music-Server/doc/api.md:16-40
Directory Structure
The server uses the following directory conventions for asset storage:
| Directory Path | Content Description |
|---|---|
file/music/ | Audio files organized as ${Category}/${SongName}. |
file/musicInfo/ | Detailed metadata for songs stored as ${SongID}.json. |
file/lyrics/ | Subtitle and lyric data stored as ${SongID}.ass. |
file/cover/ | Extracted album art images. |
file/db/ | SQLite database files for indexing and user data. |
Sources: HX-Music-Server/doc/api.md:18-40, HX-Music-Server/include/api/MusicApi.hpp:85-88
Database Components
HX-Music uses specific database files to maintain relational data and indexes. These are located in the file/db/ directory. Sources: HX-Music-Server/include/config/DbPath.hpp:26-34
Music Asset Life Cycle
The ecosystem handles the transition of audio files from initial upload or discovery to indexed storage.
Upload and Ingestion
The server implements a two-stage upload process using temporary files to prevent data corruption during network failures. Sources: HX-Music-Server/include/api/MusicApi.hpp:148-239
- Initialization: The server creates a unique
pushIdand an empty.tmpfile in the target music directory. Sources: HX-Music-Server/include/api/MusicApi.hpp:148-185 - Streaming: The client pushes bytes via WebSocket. The server appends data to the
.tmpfile and tracks the offset. Sources: HX-Music-Server/include/api/MusicApi.hpp:197-220 - Finalization: Once the file size matches the expected size, the server renames the
.tmpfile to the final filename and triggers the scanning process. Sources: HX-Music-Server/include/api/MusicApi.hpp:221-235
Metadata Extraction and Cover Storage
The MusicInfo utility parses audio tags using TagLib. When the server ingest a new song, it extracts the title, artist list, album name, and duration. If a file contains embedded cover art (APIC for MP3/MP4 or Vorbis picture blocks for FLAC), the server extracts the image and saves it to file/cover/${SongID}.${ext}. Sources: HX-Music-Server/include/utils/MusicInfo.hpp:56-155
| Data Type | Extraction Method | Persistence Path |
|---|---|---|
| Song Title | TagLib Title Tag | music.db (musicName) |
| Artists | Heuristic split (feat., ft., 、) | music.db (singers) |
| Album Art | APIC/Vorbis block extraction | file/cover/{id}.jpg or .png |
| Duration | Audio properties length | music.db (millisecondsLen) |
Sources: HX-Music-Server/include/utils/MusicInfo.hpp:56-155, HX-Music-Server/include/api/MusicApi.hpp:67-92
Data Models for Storage
Storage logic relies on specific Data Objects (DO) defined for database persistence.
MusicDO
The MusicDO structure defines how a song is indexed in music.db. Sources: HX-Music-Server/doc/api.md:62-68
struct MusicDO {
db::PrimaryKey<uint64_t> id; // Unique Song ID
std::string path; // Relative path from file/music/
std::string musicName; // Song Title
std::vector<std::string> singers; // List of Artists
std::string musicAlbum; // Album Name
uint64_t millisecondsLen; // Duration in ms
std::string coverType; // Extension (.jpg/.png)
};
Sources: HX-Music-Server/doc/api.md:62-68, HX-Music-Server/include/api/MusicApi.hpp:75-83
Client-Side Configuration Storage
The client utilizes a ConfigManager to persist local settings and state, such as server addresses and volume. It reads and writes JSON data to hxMusicConfig.json. Sources: HX-Music-Client/include/config/ConfigManager.hpp:38-70
| Setting | Type | Default Value | Description |
|---|---|---|---|
serverUrl | string | http://127.0.0.1:28205/ | Target backend URL |
volume | float | 100 | Audio output volume |
playMode | enum | ListLoop | Playback sequence logic |
playlistId | uint64_t | 0 (kNone) | ID of the last active playlist |
Sources: HX-Music-Client/include/config/ConfigManager.hpp:57-69
Conclusion
The File Storage Ecosystem provides the foundation for the HX-Music server by strictly separating binary audio assets from relational metadata. By implementing atomic file uploads via temporary files and automatic metadata scraping during ingestion, the system ensures data integrity and a low-maintenance administrative experience for users deploying on private environments like NAS. Sources: HX-Music-Server/doc/api.md:12-40, HX-Music-Server/include/api/MusicApi.hpp:148-185