Getting Started & Installation
Relevant source files
The following files were used as context for generating this wiki page:
HX-Music is a Client/Server (C/S) architecture music player specialized for Japanese songs and ASS subtitle rendering. The system consists of a C++ Qt/QML client, a C++ server for music management, and Python-based tools for Japanese lyric processing and karaoke subtitle generation.
Sources: README.md:1-12, HX-Music-Server/REAMDE.md:1-5
System Overview
The project architecture separates the frontend interface from the backend storage and processing logic. Users interact with the C++ client to play music, while the server handles file storage, database management, and lyric processing tasks.
The diagram shows the interaction between the primary C++ components and the secondary Python processing pipeline.
Sources: README.md:12-23, HX-Music-Server/REAMDE.md:1-5
Server Deployment
The backend server manages music libraries, playlists, and user authentication. You can deploy it using Docker or build it locally.
Docker Deployment
The most direct installation method utilizes docker-compose. The server requires a volume mapping for data persistence and specific capabilities for system administration.
services:
hx-music-server:
image: hengxin666/hx-music-server:latest
container_name: hx-music-server
ports:
- "28205:28205"
volumes:
- ./data:/loli/HX-Music/data
environment:
- AEGISUB_HOME=/usr/share/aegisub
restart: always
Sources: README.md:58-85, HX-Music-Server/REAMDE.md:7-35
Local Build (Arch Linux)
Local installation requires several system dependencies and the configuration of the Python environment for subtitle processing.
-
Install System Dependencies:
Install tools includingcmake,clang,taglib, andpybind11.
Sources: HX-Music-Server/REAMDE.md:43-45 -
Configure Subtitle Tools:
Installaegisuband copy the project's Lua scripts to the autoload directory.
Sources: HX-Music-Server/REAMDE.md:47-60 -
Setup Python Environment:
Navigate topyTooland useuvto sync the environment.
Sources: HX-Music-Server/REAMDE.md:62-72 -
Compile Server:
Initialize submodules and use CMake to build the server target.
Sources: HX-Music-Server/REAMDE.md:75-88
Client Installation
The client is built using Qt 6.9.1 and is primarily tested on Arch Linux with KDE Wayland.
Arch Linux Installation
Users on Arch Linux can build the client using the provided PKGBUILD by running makepkg -i within the HX-Music-Client/appBulid/arch/ directory.
Sources: README.md:34-42
Wayland Configuration
Wayland systems require specific window rules for floating subtitles and window pinning. You must import these rules into the system settings to ensure the lyrics window remains on top and hidden from the task switcher.
Sources: README.md:44-55, HX-Music-Client/README.md:154-173
Windows Configuration
Windows installation requires vcpkg to manage taglib and libass dependencies.
| Step | Action |
|---|---|
| 1 | Install vcpkg and download taglib and libass. |
| 2 | Configure .vscode/settings.json with the CMAKE_TOOLCHAIN_FILE path. |
| 3 | Set CMAKE_PREFIX_PATH in the root CMakeLists.txt to the Qt installation dir. |
| 4 | Set LIB_ROOT to the vcpkg installed packages path. |
Sources: HX-Music-Client/README.md:195-214
Build Configuration
The project uses a root CMake file to manage the building of both client and server components.
| Option | Description | Default |
|---|---|---|
BUILD_CLIENT | Compiles the HX-Music-Client project. | ON |
BUILD_SERVER | Compiles the HX-Music-Server project (Linux only). | ON |
Sources: CMakeLists.txt:7-17, HX-Music-Server/CMakeLists.txt:1-24, HX-Music-Client/CMakeLists.txt:1-24
Summary
To get started with HX-Music, deploy the server via Docker to manage your music library and install the Qt client on a Linux environment (preferably Arch Linux). Ensure all system dependencies like libass and taglib are present, and configure Wayland window rules if using a modern Linux desktop environment.
Sources: README.md:3-32, HX-Music-Server/REAMDE.md:1-5