Automated Lyrics & Furigana
Relevant source files
The following files were used as context for generating this wiki page:
The Automated Lyrics & Furigana system provides a comprehensive pipeline for acquiring, processing, and rendering high-quality karaoke subtitles. It focuses primarily on Japanese music, offering automated lyric fetching, Japanese phonetic annotation (Furigana), and conversion into Advanced Substation Alpha (ASS) format with specialized karaoke effects.
This system integrates a Python-based processing toolchain with a C++ server and client architecture. It automates the transition from raw audio files to double-line karaoke subtitles, supporting features like Romaji injection, syllable-level timing, and translation via external APIs.
Sources: README.md:1-20, pyTool/main.py:126-170
System Architecture
The feature operates through a multi-layered architecture involving the HX-Music-Server, the Python processing tool (pyTool), and external lyric sources. The server exposes API endpoints that trigger Python-based scripts to perform heavy-lifting tasks such as web scraping and phonetic analysis.
The diagram shows the end-to-end flow from a client request to the final generation of an ASS lyric file.
Sources: HX-Music-Server/doc/api.md:1-50, pyTool/README.md:83-93
Lyric Acquisition and Matching
The system utilizes the LDDC (Lyric Downloader & Decryptor Core) to retrieve lyrics from various cloud providers including QQ Music, NetEase Cloud Music, and Kugou Music.
Matching Logic
The KaRaOKAss class provides the findLyricsFromNet method, which interfaces with localMatcAss. This process traverses local music files and performs searches based on song metadata to find the best match.
- Min Score: Users can specify a
minScore(default 60) to filter search results based on match accuracy. - Decryption: The system handles encrypted formats like KRC (Kugou) and QRC (QQ Music) using specialized decryptors.
Sources: pyTool/main.py:151-160, pyTool/LDDC/core/api/lyrics/kg.py:1-150, pyTool/LDDC/core/api/lyrics/local.py:1-100
Supported Providers
| Provider | Method | Description |
|---|---|---|
| Kugou (KG) | KGAPI | Supports KRC decryption and metadata-based searches. |
| Local | LocalAPI | Parses existing .lrc, .ass, .srt, and encrypted .qrc/.krc files. |
| OpenAI | OpenAITranslator | Optional translation of fetched lyrics into target languages. |
Sources: pyTool/LDDC/core/api/lyrics/kg.py:46, pyTool/LDDC/core/api/lyrics/local.py:21, pyTool/LDDC/core/api/translate/openai.py:33
Japanese Phonetic Annotation (Furigana)
The doJapanesePhonetics function (and the internal _lddcAssToKaraokeAss method) processes raw lyrics to add Japanese readings. This ensures that kanji characters in the subtitles are accompanied by small kana (Furigana) or Romaji.
Processing Steps
- Lexical Analysis: The system uses
pykakasior custom dictionaries to break down Japanese sentences into words and particles. - Reading Correction: The
_fixReadingslogic handles special cases where generic dictionaries fail, such as specific word combinations (e.g., "あの日"). - ASS Injection: Phonetic readings are injected into the ASS line using standard subtitle syntax, ensuring they appear above the main text.
Sources: pyTool/main.py:133-150, pyTool/README.md:95-103
Karaoke Transformation
After lyrics are fetched and annotated, the system transforms them into a "Double-Line Karaoke" style. This is achieved through the integration of Aegisub's automation engine.
Automation Pipeline
The system automates the following Aegisub-cli tasks:
- Styling:
callSetKaraokeStyleLuaapplies specific CSS-like styles to the ASS file, defining colors, fonts (like TakaoPGothic), and alignment for Furigana. - Template Application:
callApplyKaraokeTemplateLuaexecutes the "Apply karaoke template" logic, which calculates the visual timing effects for the karaoke highlight.
The sequence shows how Python coordinates external CLI tools and Lua scripts to apply visual styles.
Sources: pyTool/main.py:162-177, pyTool/README.md:61-81
Defined ASS Styles
The system extends the ASS document with specific styles for both main text and Furigana.
| Style Name | Font | Size | Purpose |
|---|---|---|---|
K1 / K2 | TakaoPGothic / Arial | 80 | Main Karaoke text lines. |
K1-furigana | TakaoPGothic | 40 | Phonetic readings for K1 lines. |
noK | TakaoPGothic | 80 | Static lyric lines (no karaoke). |
Sources: pyTool/main.py:13-90
Server API Integration
The server provides endpoints to trigger these automated processes remotely, typically from the HX-Music Client.
| Endpoint | Method | Action |
|---|---|---|
/lyrics/ass/karaok/{id} | POST | Triggers fetching, annotation, and ASS conversion for a specific song ID. |
/lyrics/ass/karaok/all/ws | WS | A WebSocket endpoint for batch processing all songs missing lyrics. |
/lyrics/ass/select/{id} | GET | Retrieves the final generated ASS file. |
Sources: HX-Music-Server/doc/api.md:182-200
Conclusion
The Automated Lyrics & Furigana module simplifies the complex task of creating synchronized Japanese subtitles. By combining specialized lyric scrapers, phonetic analysis, and the Aegisub automation engine, the system delivers professional-grade karaoke experiences with minimal manual intervention. The integration into the HX-Music-Server allows for seamless background processing, making high-quality subtitles readily available to all connected clients.