CLI Validation Tools & Tests
Relevant source files
The following files were used as context for generating this wiki page:
CLI validation tools and tests in the HX-Music project verify the functionality of lyric processing, subtitle generation, and backend synchronization. These tools primarily reside within the pyTool directory and the server's diagnostic modules to ensure that Japanese phonetics (furigana), ASS subtitle templates, and lyric crawlers operate correctly before deployment.
The system uses Python-based utilities to bridge advanced lyric processing with the C++ server. Validation focuses on the accuracy of Japanese morphological analysis and the successful application of Aegisub automation templates via command-line interfaces.
Sources: pyTool/README.md, README.md
Lyric Processing and Subtitle Validation
The validation suite ensures that raw lyrics are correctly transformed into specialized ASS (Advanced Substation Alpha) subtitles. This process involves phonetic marking and the application of karaoke templates.
Phonetic (Furigana) Marking Logic
The pyTool validates Japanese lyrics by performing lexical analysis to add readings (注音). It specifically identifies cases where morphological analysis might fail, such as the distinction between different readings of Kanji based on context (e.g., "日" read as "ひ" vs "にち").
The diagram shows the flow of lyric text through the validation and correction stages to ensure accurate Japanese readings.
Sources: pyTool/README.md:104-111, README.md:12-16
Subtitle Template Automation
Validation confirms that aegisub-cli correctly applies the "Apply karaoke template" and the "set-karaoke-style" Lua scripts. This ensures that the generated ASS files follow the dual-line karaoke format required by the HX-Music client.
| Tool | Purpose | Dependency |
|---|---|---|
aegisub-cli | Applies Lua automation scripts via CLI | aegisub-cli |
set-karaoke-style.lua | Automatically sets dual-line karaoke styles | Aegisub Automation |
pykakasi | Performs Japanese morphological analysis | Python Environment |
Sources: pyTool/README.md:63-90, HX-Music-Server/REAMDE.md:38-42
Backend Synchronization and Crawler Tests
The system validates the integration between the lyric crawler (LDDC) and the server's music database. This ensures that music files uploaded via the CLI or client are correctly indexed and matched with lyrics.
Crawler Integration
The LDDC tool (v0.9.2) is bundled within the source to validate cloud lyric searching and downloading. It supports multiple sources including QQ Music, NetEase, and Lrclib. Validation tests check for:
- Successful decryption of lyric data.
- Correct mapping of JSON keys in lyric metadata.
- Support for various formats (LRC, SRT, ASS).
Sources: pyTool/LDDC/res/i18n/LDDC_en.ts:257-308, pyTool/README.md:92-96
API-Driven Validation
The server provides specific endpoints to trigger and validate lyric processing tasks. These are used during testing to verify that the background Python processes are communicating correctly with the C++ backend.
| Endpoint | Method | Action Validated |
|---|---|---|
/lyrics/ass/karaok/{id} | POST | Individual song phonetic marking and ASS generation |
/lyrics/ass/karaok/all/ws | WebSocket | Batch lyric crawling and processing status |
/music/runScan/ws | WebSocket | Manual directory scanning and database indexing |
Sources: HX-Music-Server/doc/api.md:130-134, HX-Music-Server/doc/api.md:188-198
Environment and Dependency Verification
Validation tools require a specific environment to execute successfully. The project uses uv for Python dependency management and Docker for server-side environment consistency.
The sequence diagram illustrates the steps required to verify the lyric processing toolchain manually.
Sources: pyTool/README.md:10-38, HX-Music-Server/REAMDE.md:44-55
Critical Path Verification
- Lua Script Path: Validators check that
set-karaoke-style.luaexists in/usr/share/aegisub/automation/autoload/. - Virtual Environment: Verification that the
.venvis activated before running the server orpyToolutilities. - Dictionary Data: Optional validation of English-to-Katakana mapping via
katakana_dict.jsonl.
Sources: pyTool/README.md:40-61, HX-Music-Server/REAMDE.md:38-42, HX-Music-Server/REAMDE.md:78-83
Summary
CLI Validation Tools & Tests provide the necessary checks for the HX-Music project's most complex features: Japanese lyric phonetic marking and automated karaoke subtitle generation. By utilizing a combination of Python scripts, Aegisub automation, and specific server API endpoints, the project ensures that lyrics are accurately crawled, processed, and formatted for the client's high-performance ASS rendering engine.