Music Library Management
Relevant source files
The following files were used as context for generating this wiki page:
The Music Library Management system provides the core functionality for storing, indexing, and retrieving audio content within the HX-Music ecosystem. It manages the lifecycle of music files from initial upload or scanning to database registration and metadata extraction.
The system utilizes a client-server architecture where the server handles physical storage and SQLite-based indexing, while the client interacts via REST and WebSocket APIs to perform library operations. Sources: README.md:5-15, HX-Music-Server/doc/api.md:12-30
Storage Architecture
HX-Music organizes music and metadata across a specific directory structure. The server stores physical music files, database files, and generated assets like covers and lyrics in the file/ directory.
Directory Structure
| Type | Path | Description |
|---|---|---|
| Music Files | file/music/${category}/${name} | Physical audio files organized by a single-level category. |
| Music Database | file/db/music.db | SQLite database containing song index information. |
| Music Info | file/musicInfo/${id}.json | Detailed metadata for individual tracks. |
| Lyrics | file/lyrics/${id}.ass | Generated ASS format subtitle files. |
| Covers | file/cover/${id}${suffix} | Extracted album art images. |
| Playlists | file/db/playlist.db | Storage for user-created and saved song collections. |
Sources: HX-Music-Server/doc/api.md:19-45, HX-Music-Server/include/api/MusicApi.hpp:81-87
Data Models
The system represents music tracks using the MusicDO (Data Object) structure for server-side persistence and MusicVO (View Object) for API responses.
struct MusicDO {
db::PrimaryKey<uint64_t> id; // Unique song ID
std::string path; // Relative path from ~/file/music/
std::string musicName; // Track name
std::vector<std::string> singers; // List of artists
std::string musicAlbum; // Album name
uint64_t millisecondsLen; // Duration in ms
std::string coverSuffix; // Extension of the cover image
};
Sources: HX-Music-Server/doc/api.md:55-65, HX-Music-Server/include/api/MusicApi.hpp:75-80
Metadata Extraction
The MusicInfo class utilizes the TagLib library to extract internal metadata from audio files. It supports various formats including MP3, MP4, and FLAC. Sources: HX-Music-Server/include/utils/MusicInfo.hpp:56-60, HX-Music-Client/include/utils/MusicInfo.hpp:42-45
Information Retrieval Process
- Tag Parsing: Reads the basic tag block to retrieve
title,artist, andalbum. - Artist Heuristics: Splits artist strings containing delimiters like "feat.", "ft.", "、", or "／" into distinct artist lists.
- Cover Extraction:
- For MP3/MP4, it searches complex properties like
APICorcovratoms. - For FLAC/Ogg, it retrieves Vorbis picture blocks.
- For MP3/MP4, it searches complex properties like
- Duration Calculation: Extracts technical properties to determine the length in seconds or milliseconds.
Sources: HX-Music-Server/include/utils/MusicInfo.hpp:83-125, HX-Music-Client/include/utils/MusicInfo.hpp:71-105
Library Synchronization
The library stays current through two primary mechanisms: manual scanning of the storage directory and directed file uploads.
Scanning Workflow
When a scan is triggered via the /music/runScan/ws WebSocket endpoint, the server traverses the file/music directory. If a file exists on disk but is missing from the database, the server extracts its metadata and registers it.
Upload Workflow
The upload process uses a two-stage approach to ensure data integrity and support large files through progress tracking.
- Initialization: The client calls
/music/upload/initwith the file path and size. The server generates a uniquepushIdand creates a.tmpplaceholder file. Sources: HX-Music-Server/include/api/MusicApi.hpp:144-180 - Data Transmission: The client connects to
/music/upload/push/{pushId}via WebSocket. The server negotiates the current offset (supporting resumed uploads) and appends received bytes to the temporary file. Sources: HX-Music-Server/include/api/MusicApi.hpp:185-220 - Completion: Once all bytes are received, the server renames the
.tmpfile, performs metadata scraping, and deletes the temporary task entry. Sources: HX-Music-Server/include/api/MusicApi.hpp:223-235
API Reference
The server exposes several endpoints for managing the music library.
| Endpoint | Method | Description |
|---|---|---|
/music/download/{id} | GET/HEAD | Downloads a track with support for range requests (resuming). |
/music/info/{id} | GET | Retrieves metadata (title, artists, album, length). |
/music/select | POST | Performs paginated searching of the song list. |
/cover/select/{id} | GET | Retrieves the extracted album cover image. |
/music/upload/init | POST | Initializes a new music upload task. |
Sources: HX-Music-Server/doc/api.md:120-170, HX-Music-Server/include/api/MusicApi.hpp:88-95, HX-Music-Server/include/api/CoverApi.hpp:42-55
Summary
Music Library Management in HX-Music centers on an automated pipeline that transforms raw audio files into structured data. By combining TagLib for metadata extraction with a reactive WebSocket-based scanning and upload system, it maintains a synchronized library suitable for multi-user access and playback.