Shared API Abstractions
Relevant source files
The following files were used as context for generating this wiki page:
Shared API Abstractions define the unified interface and structural patterns for communication between the HX-Music client and server. These abstractions handle music management, playlist operations, lyric synchronization, and cover art retrieval using a standardized response format.
The system utilizes a custom HX_SERVER_API framework to register endpoints and interceptors, ensuring consistent permission enforcement and data serialization across different modules.
Architecture and Response Structure
The API server uses a standardized JSON wrapper for all responses. This wrapper, JsonVO<T>, ensures that every client request receives a predictable structure containing success status, message, and the specific data payload.
The diagram shows how the generic JSON View Object wraps specific data models like Music or Playlists for transmission.
Sources: HX-Music-Server/doc/api.md:57-65, HX-Music-Server/include/api/PlaylistApi.hpp:95-110
Music Management API
The Music API handles file transfers, metadata scraping, and database indexing. It supports complex operations like range-based file downloads and multi-stage WebSocket uploads.
Core Music Endpoints
| Endpoint | Method | Permission | Description |
|---|---|---|---|
/music/download/{id} | GET/HEAD | None | Downloads music file with range support. |
/music/runScan/ws | WS | Administrator | Triggers a server-side directory scan. |
/music/info/{id} | GET | ReadOnlyUser | Retrieves metadata for a specific song. |
/music/upload/init | POST | RegularUser | Initializes a new upload task and generates a UUID. |
/music/upload/push/{pushId} | WS | RegularUser | Streams music bytes and tracks progress via WebSocket. |
Sources: HX-Music-Server/include/api/MusicApi.hpp:81-220, HX-Music-Server/doc/api.md:73-125
Upload Sequence Flow
The upload process requires an initial handshake to prepare the server filesystem before streaming data.
Playlist Abstractions
Playlist operations manage collections of music IDs. These abstractions allow for creating, updating metadata, and reordering tracks within a list.
Playlist Operations
- Creation: Users create playlists which are then linked to their account via
createdPlaylistIDs. - Membership: Songs are added by ID. The API validates if the song already exists in the playlist before insertion.
- Ordering: The client sends a complete
IdListVOto overwrite the existing sequence of songs in a playlist.
Sources: HX-Music-Server/include/api/PlaylistApi.hpp:46-77, HX-Music-Server/include/api/PlaylistApi.hpp:172-205
Lyric and Transcription API
The Lyrics API facilitates the retrieval and generation of specialized ASS (Advanced Substation Alpha) subtitles, particularly focusing on Japanese phonetics and Karaoke effects.
Processing Pipeline
The server orchestrates a Python-based backend to process lyrics through several stages:
- Crawling: Searches for lyrics on external networks based on song metadata.
- Phonetics: Generates Japanese furigana (phonetic readings).
- Karaoke Styling: Converts standard lyrics into timed two-line karaoke structures.
- Template Application: Applies Lua-based Aegisub templates for visual effects.
Sources: HX-Music-Server/include/api/LyricsApi.hpp:60-120, HX-Music-Server/doc/api.md:215-235
Common Data Models (VO)
| Class/Struct | Purpose | Key Fields |
|---|---|---|
MusicDO | Database Object | id, path, singers, musicAlbum |
PlaylistDO | Database Object | id, name, songIdList |
InitUploadFileTaskVO | Upload Handshake | path, fileSize |
WsLyricsMsgVO | Lyric Processing | musicId, type (Enum) |
Sources: HX-Music-Server/doc/api.md:31-50, HX-Music-Server/include/api/MusicApi.hpp:45-53, HX-Music-Server/include/api/LyricsApi.hpp:58-65
Security and Interceptors
API access is governed by the TokenInterceptor. This component checks for specific PermissionEnum levels before allowing an endpoint to execute.
- Administrator: Required for destructive or system-wide actions like scanning the entire library.
- RegularUser: Required for creating playlists and uploading files.
- ReadOnlyUser: Required for fetching song info and viewing playlists.
Sources: HX-Music-Server/include/api/CoverApi.hpp:47-60, HX-Music-Server/include/api/PlaylistApi.hpp:160-170
The Shared API Abstractions provide a robust framework that separates the storage implementation from client-facing services, enabling features like multi-user permissions and complex asynchronous lyric processing.