Music API Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
Music API Endpoints provide the interface for managing audio resources, metadata, playlists, and associated content within the HX-Music system. The server implements a RESTful and WebSocket-based architecture to handle high-level operations such as music uploading, metadata scraping, automated lyric processing, and playlist management.
The system uses a C++ backend with an asynchronous event loop to handle concurrent requests and file I/O. Data is persisted in SQLite databases and JSON files, while binary assets like music files, covers, and ASS subtitles are stored in structured file directories.
Sources: HX-Music-Server/doc/api.md:5-40, HX-Music-Server/include/api/MusicApi.hpp:54-58
Music Management Endpoints
Music management includes downloading, uploading via segmented tasks, scanning local directories, and querying song metadata. The MusicApi class handles these operations, utilizing MusicDAO for database interactions and MusicInfo for metadata extraction.
Audio Data Flow
The following diagram illustrates the lifecycle of a music file from upload initialization to database indexing.
Core Music Endpoints
| Endpoint | Method | Description |
|---|---|---|
/music/download/{id} | GET/HEAD | Downloads music using range requests for breakpoint resume. |
/music/upload/init | POST | Initializes an upload task and creates a unique pushId. |
/music/upload/push/{id} | WS | Asynchronously streams file data and reports percentage progress. |
/music/runScan/ws | WS | Scans the ./file/music directory for new files not in the database. |
/music/info/{id} | GET | Returns metadata including name, artist, album, and length. |
/music/select | POST | Performs paginated searching and listing of songs. |
Sources: HX-Music-Server/doc/api.md:95-150, HX-Music-Server/include/api/MusicApi.hpp:94-266
Lyric and Subtitle Processing
The LyricsApi provides sophisticated tools for retrieving and transforming lyrics, specifically focusing on Japanese phonetic transcription (Furigana) and karaoke-style ASS (Advanced Substation Alpha) subtitles.
Automated Processing Pipeline
The server can automatically convert raw lyrics into stylized karaoke subtitles using an Aegisub-based toolchain.
Lyric API Details
- Range Retrieval: The
/lyrics/ass/select/{id}endpoint supportsGETandHEADrequests for downloading ASS files. - Batch Processing: The
/lyrics/ass/karaok/all/wsendpoint allows administrators to trigger a full library scan to generate missing lyrics for all songs. It includes a 5-second delay between requests to avoid rate limiting.
Sources: HX-Music-Server/include/api/LyricsApi.hpp:42-53, HX-Music-Server/include/api/LyricsApi.hpp:127-190
Playlist Management
The PlaylistApi manages song collections. The system distinguishes between user-created playlists and saved (favorited) playlists.
Playlist Data Structures
struct PlaylistDO {
db::PrimaryKey<uint64_t> id; // Unique Playlist ID
std::string name; // Playlist Name
std::string description; // Playlist Description
std::vector<uint64_t> songIdList; // Ordered list of Music IDs
};
Sources: HX-Music-Server/doc/api.md:69-75, HX-Music-Server/include/api/PlaylistApi.hpp:51-61
Key Operations
- Creation:
POST /playlist/makegenerates a new ID and associates it with the current user'screatedPlaylistlist. - Song Insertion:
POST /playlist/{id}/addMusic/{musicId}validates that the music is not already in the list before adding the reference. - Ordering:
POST /playlist/updateMusicOrder/{id}allows full reordering by submitting a complete list of IDs.
Sources: HX-Music-Server/include/api/PlaylistApi.hpp:45-53, HX-Music-Server/include/api/PlaylistApi.hpp:150-169, HX-Music-Server/include/api/PlaylistApi.hpp:190-205
Cover Art Retrieval
The CoverApi serves album art extracted from audio files.
- Extraction: When music is scanned or uploaded,
MusicInfoattempts to parse APIC (MP3) or Vorbis picture blocks (FLAC) to save cover images to./file/cover/. - Retrieval:
GET /cover/select/{id}serves the image file. The system appends thecoverSuffix(e.g.,.jpgor.png) stored in theMusicDOto resolve the correct path.
Sources: HX-Music-Server/include/utils/MusicInfo.hpp:160-203, HX-Music-Server/include/api/CoverApi.hpp:42-52
Security and Permissions
API endpoints are protected by a TokenInterceptor. Permissions are categorized into three levels:
- Administrator: Access to destructive actions and batch processing (e.g.,
runScan,karaok/all). - RegularUser: Access to creating/editing personal content (e.g.,
upload/init,playlist/make). - ReadOnlyUser: Access to metadata and media retrieval (e.g.,
music/info,cover/select).
Sources: HX-Music-Server/doc/api.md:200-205, HX-Music-Server/include/api/MusicApi.hpp:116, HX-Music-Server/include/api/MusicApi.hpp:135
Music API Endpoints serve as the backbone for the HX-Music ecosystem, bridging raw file storage with the user interface. By integrating automated metadata scraping and complex subtitle processing into the API layer, the server provides a feature-rich environment specialized for Japanese music and high-fidelity lyrics.