Playlist System
Relevant source files
The following files were used as context for generating this wiki page:
The Playlist System manages the creation, organization, and retrieval of music collections within HX-Music. It utilizes a Client/Server architecture where the server handles persistent storage in SQLite databases and the client provides a QML-based interface for user interaction.
The system distinguishes between user-created playlists and saved playlists, supporting operations such as song reordering, metadata editing, and multi-user permission control.
Sources: README.md:3-8, HX-Music-Server/doc/api.md:25-27, HX-Music-Server/include/api/PlaylistApi.hpp:89-115
Architecture and Data Flow
The Playlist System follows a multi-tier architecture involving Data Objects (DO) for storage, Value Objects (VO) for network transmission, and Controllers/Models for UI binding.
Data Model and Storage
Playlists are stored in file/db/playlist.db. Each playlist contains a unique ID, name, description, and an ordered list of song references.
Sources: HX-Music-Server/doc/api.md:25-27, include/pojo/do/PlaylistDO.hpp:26-31
| Field | Type | Description |
|---|---|---|
id | uint64_t | Unique playlist ID. Local default is 0. |
name | std::string | The display name of the playlist. |
description | std::string | A text description of the playlist content. |
songIdList | vector<uint64_t> | Ordered list of unique song IDs belonging to the playlist. |
| Sources: include/pojo/do/PlaylistDO.hpp:27-31, HX-Music-Server/doc/api.md:78-83 |
System Data Flow
The following diagram illustrates how a playlist request moves from the Client UI through the API layer to the Server storage.
The client uses PlaylistController to trigger actions and PlaylistModel (inheriting from QAbstractListModel) to provide data to the QML views.
Sources: HX-Music-Client/include/controller/PlaylistController.h:42-50, HX-Music-Client/include/model/PlaylistModel.hpp:33-40
Server-Side API
The server implements a RESTful API to manage playlist resources. Most write operations require RegularUser permissions, while read operations require ReadOnlyUser permissions.
Sources: HX-Music-Server/include/api/PlaylistApi.hpp:46-70
Core Endpoints
| Method | Endpoint | Description | Permission |
|---|---|---|---|
POST | /playlist/make | Creates a new playlist and links it to the user. | RegularUser |
POST | /playlist/update | Updates playlist metadata (name/description). | RegularUser |
GET | /playlist/select/{id} | Retrieves full playlist data including song details. | ReadOnlyUser |
POST | /playlist/{id}/addMusic/{mId} | Appends a song ID to the playlist's songIdList. | RegularUser |
POST | /playlist/updateMusicOrder/{id} | Replaces the entire song ID list to update order. | RegularUser |
GET | /playlist/selectAll/created | Lists all playlists created by the authenticated user. | ReadOnlyUser |
| Sources: HX-Music-Server/doc/api.md:155-225, HX-Music-Server/include/api/PlaylistApi.hpp:46-170 |
Song Ordering Logic
When a user reorders songs in the client, the system sends a IdListVO to the /playlist/updateMusicOrder/{id} endpoint. The server validates that the size of the provided list matches the existing collection before updating the database.
Sources: HX-Music-Server/include/api/PlaylistApi.hpp:163-176
Client-Side Implementation
The client manages playlist state through a singleton PlaylistController and specialized models for UI rendering.
Interaction Sequence: Loading a Playlist
This sequence shows the process of a user selecting a playlist in the UI.
Playlist Models
The client utilizes different models to handle specific views:
- PlaylistModel: Manages the list of available playlists (Created or Saved). It supports
swapRowandmoveRowsfor drag-and-drop reordering. - AllMusicListModel: Handles the display of songs within a selected playlist or the general library, supporting paginated loading via
loadMoreRequested.
Sources: HX-Music-Client/include/model/PlaylistModel.hpp:144-180, HX-Music-Client/include/model/AllMusicListModel.hpp:117-150
Local Persistence
The ConfigManager saves the playlistId and listIndex of the last played song to hxMusicConfig.json. Upon application restart, PlaylistController restores this state by emitting loadPlaylistSignal and switching to the saved music ID.
Sources: HX-Music-Client/include/config/ConfigManager.hpp:38-46, HX-Music-Client/include/controller/PlaylistController.h:103-138
Conclusion
The Playlist System provides a structured way to manage music metadata and user preferences. By decoupling storage (Server) from presentation (Client), it enables multi-user support and persistent playback states across sessions. The use of ordered ID lists for song management ensures that manual reordering is efficiently synchronized between the client interface and the server database.