LDDC Subsystem Overview
Relevant source files
The following files were used as context for generating this wiki page:
The LDDC (Lyric Downloader and Decryptor) subsystem manages lyric acquisition, decryption, and conversion for the HX-Music project. It provides a unified API to search for songs across multiple cloud platforms, decrypt proprietary lyric formats, and convert them into standard formats like Advanced Substation Alpha (ASS) for rendering.
LDDC integrates with the HX-Music-Server to support automated features such as Japanese phonetic transcription (furigana) and two-line karaoke ASS generation. It serves as the primary engine for fetching and processing lyrics from sources like NetEase Cloud Music, QQ Music, Kugou Music, and Lrclib.
Sources: README.md:9-11, pyTool/README.md:46-51, pyTool/LDDC/core/api/lyrics/__init__.py:23-38
Architecture and Core API
The LyricsAPI class serves as the central manager for all lyric-related operations. It utilizes a provider-based architecture where specific API implementations (e.g., LocalAPI, NEAPI, KGAPI) handle interactions with different data sources.
Lyric Acquisition Flow
The subsystem initializes specific API providers upon first use. Cloud providers inherit from CloudAPI, while local file operations are handled by LocalAPI. The LyricsAPI provides methods to search for content, retrieve song lists from albums or playlists, and fetch specific lyric data.
The manager implements a retry mechanism for cloud requests, attempting up to three times if a TimeoutException occurs.
Sources: pyTool/LDDC/core/api/lyrics/__init__.py:23-56, pyTool/LDDC/core/api/lyrics/__init__.py:98-124
Data Structures
| Class / Structure | Description | Source |
|---|---|---|
LyricInfo | Contains metadata about a lyric, including source, associated song info, and optional local path or raw data. | pyTool/LDDC/core/api/lyrics/__init__.py:136-141 |
Lyrics | A dictionary-like object storing multiple lyric versions (orig, roma, ts) and metadata tags. | pyTool/LDDC/core/api/lyrics/local.py:91-95 |
APIResultList | A generic list wrapper for search results (SongInfo or SongListInfo) that tracks cache status. | pyTool/LDDC/core/api/lyrics/__init__.py:165-172 |
Lyric Parsing and Decryption
The subsystem handles various lyric formats through LocalAPI. It distinguishes between plain text formats and encrypted proprietary formats used by Chinese music streaming services.
Format Support and Detection
LDDC detects formats based on magic headers or file extensions. It supports standard formats (LRC, SRT, ASS) and encrypted formats (KRC, QRC).
Decryption Logic
- QRC (QQ Music): Decrypted using
qrc_decrypt. For local files, the system attempts to find associated Romanized (_qmRoma.qrc) or translated (_qmts.qrc) files in the same directory. - KRC (Kugou Music): Decrypted using
krc_decryptand parsed viakrc2mdata.
Sources: pyTool/LDDC/core/api/lyrics/local.py:53-85
Lyric Conversion to ASS
The ass_converter converts raw lyric data into formatted ASS files. This is critical for HX-Music's floating lyric window and karaoke effects.
Formatting and Timing
The converter generates a standard ASS header including script info, styles for different lyric types (original, translation, romaji), and event formatting.
| Component | Logic | Source |
|---|---|---|
| Timestamps | Converts milliseconds to HH:MM:SS.cs (centiseconds) format. | pyTool/LDDC/core/converter/ass.py:24-30 |
| Karaoke Tags | Uses {\kf} tags to indicate word-level timing if duration data is available. | pyTool/LDDC/core/converter/ass.py:40-42 |
| Dialogue | Maps original lines to translated or Romanized lines using a langs_mapping. | pyTool/LDDC/core/converter/ass.py:78-83 |
# pyTool/LDDC/core/converter/ass.py:33-43
def lyrics_line2asstext(lyrics_line: LyricsLine) -> str:
ass_text = ""
if len(lyrics_line.words) == 1:
return "".join([word.text for word in lyrics_line.words if word.text != ""])
for word in lyrics_line.words:
if word.start is not None and word.end is not None:
k = abs(word.end - word.start) // 10
else:
return "".join([word.text for word in lyrics_line.words if word.text != ""])
ass_text += r"{\kf" + str(k) + "}" + word.text
return ass_text
Integration with HX-Music-Server
The subsystem is exposed via server-side API endpoints to automate lyric workflows for NAS deployments.
API Endpoints
/lyrics/ass/select/{id}: Retrieves an ASS formatted lyric for a specific song ID./lyrics/ass/karaok/{id}: Triggers a network crawl, Japanese phonetic transcription (furigana), and karaoke ASS generation./lyrics/ass/karaok/all/ws: A WebSocket endpoint for batch processing all songs missing lyrics.
Sources: HX-Music-Server/doc/api.md:213-238, README.md:12-14
Deployment Requirements
For the full LDDC toolchain (including Japanese furigana), the following external components are required:
- Aegisub & Aegisub-cli: Used to apply karaoke templates via Lua automation.
- set-karaoke-style.lua: A custom plugin to set two-line styles.
- Python Environment: Managed via
uvwith dependencies likepykakasifor morphological analysis.
Sources: pyTool/README.md:46-77, pyTool/README.md:92-99
LDDC provides a robust foundation for HX-Music's advanced lyric features by abstracting complex cloud search, decryption, and multi-language alignment logic into a single Python-based subsystem.