Lyrics & Cover APIs
Relevant source files
The following files were used as context for generating this wiki page:
The Lyrics & Cover APIs provide endpoints for managing, retrieving, and processing song metadata, specifically targeting Advanced Substation Alpha (ASS) formatted lyrics and album artwork. These APIs handle tasks ranging from simple file delivery to complex automation, such as Japanese phonetics (注音) and Karaoke-style formatting for ASS subtitles.
The system integrates a C++ backend (HX-Music-Server) with Python-based tools (pyTool/LDDC) to perform network scraping and subtitle transformation. It supports multi-user permissions, ensuring that destructive or resource-intensive operations are restricted to authorized accounts.
Sources: README.md:5-15, HX-Music-Server/doc/api.md:158-208
Lyrics API Architecture
The Lyrics API employs a hybrid communication model. Standard file retrieval uses RESTful HTTP endpoints, while long-running tasks like batch scraping and real-time processing utilize WebSockets to provide progress updates and status reports.
Data Storage and Paths
The server stores lyric files in a specific directory structure. Lyrics are indexed by the music's unique ID and stored in the ASS format.
| Data Type | Storage Path |
|---|---|
| Lyric Files | file/lyrics/${song_id}.ass |
| Processed ASS | ./file/lyrics/ass/${song_id}.ass |
| Music Info | file/musicInfo/${song_id}.json |
Sources: HX-Music-Server/doc/api.md:33-40, HX-Music-Server/include/api/LyricsApi.hpp:51-55
Core Processing Flow
The following diagram illustrates the sequence for automated lyric processing, including scraping, transcription, and formatting.
Endpoint Reference
Retrieval Endpoints
These endpoints allow clients to download lyrics and cover images using standard GET requests.
| Endpoint | Method | Permission | Description |
|---|---|---|---|
/lyrics/ass/select/{id} | GET/HEAD | ReadOnlyUser | Downloads the ASS lyric file for a specific song ID. |
/cover/select/{id} | GET/HEAD | Any | Retrieves the album cover image for the song. |
Sources: HX-Music-Server/include/api/LyricsApi.hpp:44-58, HX-Music-Server/doc/api.md:200-208
Automated Processing Endpoints
These endpoints trigger backend tasks to fetch or modify lyrics.
- Single Song Processing (
/lyrics/ass/karaok/ws): A WebSocket endpoint that accepts commands to crawl lyrics, perform Japanese transcription, or apply Karaoke templates. - Batch Processing (
/lyrics/ass/karaok/all/ws): A WebSocket endpoint restricted to administrators. It scans the database for songs missing lyrics and automatically processes them in sequence.
Sources: HX-Music-Server/include/api/LyricsApi.hpp:60-188, HX-Music-Server/doc/api.md:190-198
Python Subtitle Engine (LDDC)
The Python module pyTool/LDDC serves as the engine for lyric retrieval and transformation. It supports multiple sources including Kugou (KG), NetEase (NE), and QQ Music (QM).
Kugou API (KGAPI) Logic
The KGAPI class implements specific logic to handle Kugou's proprietary KRC format and decryption. It manages device identification (dfid) and request signing to communicate with Kugou's mobile search and download APIs.
Lyric Types
The system distinguishes between three types of lyric data during processing:
- Original (原文): The primary lyric text.
- Translation (译文): The translated version of the lyrics.
- Romaji (罗马音): The phonetic transcription, particularly for Japanese songs.
Sources: pyTool/LDDC/res/i18n/LDDC_en.ts:160-175, pyTool/LDDC/core/api/lyrics/init.py:120-140
Summary
The Lyrics & Cover APIs in HX-Music provide a robust infrastructure for automating music metadata enrichment. By combining a C++ server for file serving and user management with a Python engine for network scraping and ASS subtitle generation, the system provides advanced features like Japanese transcription and dual-line Karaoke formatting. Administrators can leverage batch processing to ensure the entire library is populated with high-quality subtitles automatically.
Sources: README.md:5-10, HX-Music-Server/include/api/LyricsApi.hpp:140-180