Local Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
Local development setup involves configuring the C++ QT/QML client, the C++ server, and the Python-based Japanese pronunciation tools. The project follows a Client/Server architecture primarily targeting Linux environments, specifically Arch Linux with KDE Wayland.
The development environment requires specific C++ libraries for media handling, a Python environment for lyric processing, and CMake for project orchestration. Developers must manage submodules and external dependencies like Aegisub for lyric automation.
Project Structure Overview
The project is organized into three main components: the client, the server, and the Python tools. A root-level CMake configuration manages the build process for both C++ components.
Visual representation of the project's high-level directory and module structure.
Sources: CMakeLists.txt:4-17, README.md:14-20
Prerequisites and System Dependencies
Local development is officially tested and recommended on Arch Linux. The system requires several development tools and libraries for both media processing and UI rendering.
Required System Packages
You must install the following packages using pacman:
- Build Tools:
base-devel,cmake,clang,git,sudo,wget,unzip. - C++ Libraries:
taglib,pybind11,openssl,libass. - Python:
python,python-pip.
Sources: HX-Music-Server/REAMDE.md:27-29, HX-Music-Client/README.md:246-258
Specialized Dependencies
- Aegisub: Required for Japanese lyric automation and subtitle processing. It should be installed via
yayfrom the AUR. - HXLibs: A modern C++ library providing coroutines, networking, reflection, and logging. It is included as a git submodule.
Sources: HX-Music-Server/REAMDE.md:31-41, HX-Music-Client/README.md:278-280, CMakeLists.txt:5
Build Configuration
The project uses CMake to control the build process. You can toggle the compilation of the client or server using CMake options.
| Option | Type | Default | Description |
|---|---|---|---|
BUILD_CLIENT | boolean | ON | Build the HX-Music QT/QML client |
BUILD_SERVER | boolean | ON | Build the HX-Music C++ server |
CMAKE_BUILD_TYPE | string | N/A | Build mode (Release or Debug) |
Sources: CMakeLists.txt:8-9, HX-Music-Server/REAMDE.md:65-70
Build Procedure
Follow these steps to build the server component:
- Initialize submodules:
git submodule update --init --recursive - Create a build directory:
mkdir build && cd build - Configure with CMake:
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_CLIENT=OFF -DBUILD_SERVER=ON - Compile the target:
cmake --build . --config Release --target HX-Music-Server
Sources: HX-Music-Server/REAMDE.md:57-73
Python Tooling Setup
The pyTool module handles Japanese pronunciation and double-line Karaoke ASS conversion. It requires uv for environment management.
- Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh - Sync Environment: Run
uv syncin theHX-Music/pyTooldirectory. - Lua Integration: Copy the project's Lua script to the Aegisub automation directory:
sudo cp HX-Music/pyTool/lua/set-karaoke-style.lua /usr/share/aegisub/automation/autoload/
Sources: HX-Music-Server/REAMDE.md:47-55, HX-Music-Server/REAMDE.md:43-45
Running the Application
To run the server locally, you must first activate the Python virtual environment to ensure the pronunciation tools are available.
The sequence of steps required to launch the server in a local development environment.
Sources: HX-Music-Server/REAMDE.md:77-83, README.md:83
Platform Specifics: Windows Setup
While Linux is the primary target, Windows development is supported via vcpkg.
- Install
vcpkgand downloadtaglibandlibass. - Configure VS Code to use the vcpkg toolchain file.
- Modify the root
CMakeLists.txtto set theCMAKE_PREFIX_PATHfor the Qt installation andLIB_ROOTfor vcpkg packages.
Sources: HX-Music-Client/README.md:283-305
The setup is complete once the server is running and the client is configured to connect to the backend address via the settings interface.
Sources: HX-Music-Client/README.md:139-140