Client-Side Controllers
Relevant source files
The following files were used as context for generating this wiki page:
Client-side controllers manage the application logic and data flow between the C++/Qt backend and the QML-based user interface. These controllers handle core functionalities including music playback, lyric rendering, user authentication, and playlist management.
The controllers are registered as context properties within the QQmlApplicationEngine, allowing QML components to invoke C++ methods and react to property changes or signals.
Sources: HX-Music-Client/src/main.cpp:115-156
Architecture Overview
The HX-Music client utilizes a controller-based architecture where specialized classes manage specific domains. The MusicClient struct in the entry point initializes these controllers and exposes them to the QML engine.
The diagram shows the relationship between the QML UI, the C++ controllers, and the underlying infrastructure.
Sources: HX-Music-Client/src/main.cpp:108-185, HX-Music-Client/README.md:145-195
LyricController
The LyricController manages the rendering and synchronization of ASS (Advanced Substation Alpha) lyrics. It provides images to the QML engine through the QQuickImageProvider interface, allowing high-performance rendering of complex subtitle effects.
Lyric Rendering Logic
The controller supports two primary rendering modes:
- Full Screen Mode: Renders the ASS subtitle at its native resolution (e.g., 1920x1080) for display on a transparent overlay.
- Windowed/Cropped Mode: Pre-calculates bounding boxes for lyric blocks and crops the rendered image to fit a specific float window, reducing resource usage and preventing "jitter" in animation.
The sequence shows how playback position changes trigger a frame-by-frame rendering update for the UI.
Sources: HX-Music-Client/include/controller/LyricController.h:46-59, HX-Music-Client/include/controller/LyricController.h:180-255
Key Properties
| Property | Type | Description |
|---|---|---|
lyricOffset | long long | Manual time adjustment for synchronization |
isFullScreen | bool | Toggles between native resolution and cropped rendering |
isAutoCenter | bool | Automatically centers lyrics within the display block |
isLocked | bool | Prevents moving the lyric window in the UI |
Sources: HX-Music-Client/include/controller/LyricController.h:351-363
UserController
The UserController handles authentication and profile management. It communicates with the server-side user APIs to perform operations such as login, registration, and credential updates.
Authentication Flow
- Login: Validates credentials and receives a token from the server.
- Permission Check: Determines if the user is a
RegularUser,ReadOnlyUser, or Administrator. - Profile Management: Manages the user's avatar, signature, and password updates.
Sources: HX-Music-Client/src/main.cpp:121-123, HX-Music-Server/doc/api.md:275-325
Music and Playlist Controllers
These controllers manage the audio state and organization of tracks.
- MusicController: Manages the active playback state, including volume, play mode (Loop, Random, etc.), and current position. It tracks the currently loaded
MusicInformation. - PlaylistController: Manages local and server-side playlists. It facilitates adding/removing songs and reordering tracks within a list.
Playlist Data Structure
Playlists are categorized into "Created" and "Saved" lists for the logged-in user. Each playlist contains a list of MusicVO objects (Value Objects) which include:
id: Unique song identifier.musicName: Title of the track.singers: List of artists.millisecondsLen: Duration of the track.
Sources: HX-Music-Server/doc/api.md:135-155, HX-Music-Server/include/api/PlaylistApi.hpp:85-115
Signal Bus Integration
Client-side controllers rely heavily on the SignalBusSingleton to communicate asynchronously. This decoupling allows one controller (e.g., Music) to notify others (e.g., Lyric) without direct dependencies.
| Signal | Source | Action |
|---|---|---|
musicPlayPosChanged(qint64) | Music Playback | Updates lyric rendering frame |
newSongLoaded(MusicInformation*) | Music Controller | Triggers new lyric fetch from server |
backendViewLogUpdated(QString) | Scan Service | Updates the log view in the UI |
lyricAddOffset(long long) | UI Input | Adjusts time sync for current track |
Sources: HX-Music-Client/include/controller/LyricController.h:95-147, HX-Music-Client/src/main.cpp:117-118
Summary
Client-side controllers in HX-Music provide a robust bridge between high-performance C++ utilities (like libass for lyric rendering) and a flexible QML interface. By leveraging Qt's property system and a centralized signal bus, the controllers ensure synchronized playback and efficient rendering of advanced visual effects.