Database Schema & DAO Structure
Relevant source files
The following files were used as context for generating this wiki page:
The HX-Music system employs a structured storage architecture to manage music files, metadata, and user-defined playlists. The project separates physical file storage from metadata management, using a Data Access Object (DAO) pattern to interact with persistent storage, primarily targeting private deployments like NAS (Network Attached Storage).
Music metadata and playlist configurations are stored in SQLite database files, which are mapped to Data Objects (DO) within the C++ backend. This structure enables features such as metadata scraping, rapid search based on song names or artists, and complex playlist management.
Storage Architecture Overview
The system categorizes data into five primary storage areas located under the ./file/ directory. Physical music files occupy a specific subdirectory, while metadata, lyrics, and database files reside in dedicated sibling folders.
| Category | Storage Path | Description |
|---|---|---|
| Music Files | file/music/${category}/${name} | Physical audio files; categories are one level deep. |
| Music Metadata | file/musicInfo/${musicId}.json | Detailed song metadata in JSON format. |
| Lyric Info | file/lyrics/${musicId}.ass | Subtitle and lyric data in ASS format. |
| Databases | file/db/*.db | SQLite files for users, music indexes, and playlists. |
| Covers | file/cover/${musicId}${suffix} | Album art extracted from music files. |
Sources: HX-Music-Server/doc/api.md:16-56, HX-Music-Server/include/api/MusicApi.hpp:81-88, HX-Music-Server/include/api/CoverApi.hpp:44-48
Data Objects (DO) & Schema
The system defines three core data models using C++ structs. These structs map directly to the database schema used by the DAOs.
MusicDO
MusicDO stores the indexing information for every song in the library. It allows the system to perform searches by title, artist, or album without reading every physical file header.
| Field | Type | Description |
|---|---|---|
id | db::PrimaryKey<uint64_t> | Unique song identifier. |
path | std::string | Relative path to audio file from ~/file/music/. |
musicName | std::string | Title of the track. |
singers | std::vector<std::string> | List of artists associated with the track. |
musicAlbum | std::string | Album name. |
millisecondsLen | uint64_t | Total duration of the song in milliseconds. |
coverSuffix | std::string | Image format for the cover (e.g., .png, .jpg). |
Sources: include/pojo/do/MusicDO.hpp:33-41, HX-Music-Server/doc/api.md:73-79
PlaylistDO
PlaylistDO manages the collection of songs. Rather than duplicating music data, it stores references to song IDs.
| Field | Type | Description |
|---|---|---|
id | db::PrimaryKey<uint64_t> | Unique playlist ID (Local default is 0). |
name | std::string | Name of the playlist. |
description | std::string | User-provided description. |
songIdList | std::vector<uint64_t> | Ordered list of MusicDO IDs. |
Sources: include/pojo/do/PlaylistDO.hpp:33-38, HX-Music-Server/doc/api.md:103-108
DAO Implementation & Pool
The project uses a MemoryDAOPool to manage DAO instances. This pool facilitates access to SQLite databases by linking specific DAO classes to their file paths.
The diagram shows the relationship between the MemoryDAOPool and the various Data Access Objects that persist their respective Data Objects.
Database File Configuration
Database paths are globally defined to ensure consistency across the API endpoints.
- User DB:
./file/db/user.db - Music DB:
./file/db/music.db - Playlist DB:
./file/db/playlist.db
Sources: HX-Music-Server/include/config/DbPath.hpp:30-38, HX-Music-Server/include/api/MusicApi.hpp:52-53, HX-Music-Server/include/api/PlaylistApi.hpp:46-51
Data Flow: Music Scraping & Indexing
When a new music file is detected or uploaded, the MusicApi performs a "scraping" operation. This process extracts metadata from the file and persists it via the MusicDAO.
The sequence diagram illustrates the flow from metadata extraction using the MusicInfo utility to database persistence through the MusicDAO.
Sources: HX-Music-Server/include/api/MusicApi.hpp:58-88, HX-Music-Client/include/utils/MusicInfo.hpp:51-180
Playlist Management Logic
Playlists are managed through PlaylistApi, which coordinates between PlaylistDAO and UserDAO. Users possess two types of playlist associations: createdPlaylist (ownership) and savedPlaylist (subscriptions).
- Creation: When you create a playlist, the
PlaylistDAOadds thePlaylistDOrecord, and theUserDAOappends the new ID to the user'screatedPlaylistlist. - Updating Order: The system performs a full update of song positions by passing an
IdListVOto the DAO'supdateBymethod, targeting thesongIdListfield. - Ownership Check: Before adding or deleting songs, the API verifies that the playlist ID exists within the user's
createdPlaylistarray stored in the User database.
Sources: HX-Music-Server/include/api/PlaylistApi.hpp:57-80, HX-Music-Server/include/api/PlaylistApi.hpp:169-200, HX-Music-Server/doc/api.md:144-210
Summary
The Database Schema and DAO structure provide a robust framework for managing a distributed music library. By utilizing specialized Data Objects (MusicDO, PlaylistDO) and centralizing access through the MemoryDAOPool, the system maintains high performance for metadata queries while ensuring physical file integrity on the storage medium.