Python Furigana Process Pipeline
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Python Furigana Process Pipeline is a core backend module responsible for transforming raw music lyrics into advanced ASS (Advanced Substation Alpha) subtitle files. It focuses on processing Japanese text by applying Furigana (reading aids), generating karaoke timing effects, and managing translation workflows. The pipeline integrates external tools like Aegisub and the LDDC (Lyric Download & Decrypt) library to provide a complete solution for high-quality lyric visualization.
This pipeline operates as a service within the C/S architecture of HX-Music, allowing NAS users to deploy the processing engine as a Docker container while interacting through a C++ client. It handles tasks ranging from network fetching and decryption to complex LUA-based template application for karaoke effects.
Sources: pyTool/README.md:1-25, README.md:1-20
Pipeline Architecture and Flow
The process pipeline follows a linear execution model where raw music metadata is converted into styled, Furigana-annotated subtitles. The orchestration is primarily managed by the KaRaOKAss class.
Core Processing Flow
The pipeline consists of four major stages: network matching, Furigana annotation, style application, and karaoke template rendering.
The diagram shows the transition from raw audio file metadata to a finalized ASS subtitle through specialized processing layers.
Sources: pyTool/main.py:126-160, pyTool/README.md:120-130
Functional Components
1. KaRaOKAss Orchestrator
The KaRaOKAss class serves as the main entry point for the pipeline. It coordinates the conversion of LDDC-style ASS files into stylized karaoke versions.
findLyricsFromNet(): Uses thelocalMatcAssutility to find cloud lyrics based on song hashes and metadata.doJapanesePhonetics(): InvokesAssMarkto add Furigana to Dialogue lines containing\kor\kftags.toTwoLineKaraokeStyle(): Executes a LUA script to set dual-line karaoke styles.callApplyKaraokeTemplateLua(): Finalizes the ASS file by applying Aegisub's karaoke automation templates.
Sources: pyTool/main.py:126-160
2. Furigana Annotation (AssMark & JpMark)
The system uses AssMark to parse and modify ASS events. It identifies dialogue lines and injects Furigana readings into the text strings. It specifically addresses Japanese linguistics issues, such as fixing readings for specific compounds like "あの日" where the character "日" might be incorrectly parsed by standard morphing libraries.
Sources: pyTool/main.py:138-147, pyTool/README.md:147-155
3. Lyric Fetching and Decryption (LDDC)
The pipeline utilizes the LDDC library to interface with various music APIs (e.g., Kugou, NetEase).
- API Interactions: The
KGAPIclass handles requests to Kugou services, including signature generation anddfidrisk control management. - Decryption: Specialized decryptors process proprietary formats like
.krcand.qrcinto standard text-based formats before Furigana processing. - Translation: If translation is required, the
OpenAITranslatorfacilitates line-by-line translation using GPT models while preserving original line numbering.
Sources: pyTool/LDDC/core/api/lyrics/kg.py:40-100, pyTool/LDDC/core/api/translate/openai.py:38-60, pyTool/LDDC/core/api/lyrics/local.py:30-60
Subtitle Styling and Templates
The pipeline automatically injects pre-defined styles and LUA-based automation comments into the ASS document to enable high-quality rendering.
Style Configuration
The _addSy01 function defines a set of standard styles for Furigana and main text, covering both karaoke (K1-K4) and non-karaoke variants.
| Style Name | Font | Size | Purpose |
|---|---|---|---|
noK-furigana | TakaoPGothic | 40 | Non-karaoke reading aid |
K1 | TakaoPGothic | 80 | Primary karaoke line |
K1-furigana | TakaoPGothic | 40 | Reading aid for K1 |
noK | TakaoPGothic | 80 | Static lyric text |
Sources: pyTool/main.py:11-66
Karaoke Automation Logic
The system injects Aegisub automation comments (code line, template syl) that define how lyrics behave during playback, such as color transitions and overlays.
The sequence shows how the Python environment offloads complex subtitle geometry calculations to Aegisub's LUA engine.
Sources: pyTool/main.py:113-124, pyTool/README.md:76-90
Data Structures
The pipeline relies on structured lyric models to manage timing and text.
LyricsWord: A tuple containingstart,end, andtext.LyricsLine: A collection ofLyricsWordobjects with overall line timing.FSLyricsData: "Full Timestamp" data ensuring no timing gaps exist between words or lines.
Sources: pyTool/LDDC/common/models/_lyrics.py:14-40
Summary
The Python Furigana Process Pipeline automates the complex task of creating professional Japanese karaoke subtitles. By combining LDDC's fetching capabilities, Python's text processing for Furigana annotation, and Aegisub's LUA-driven styling engine, it ensures that raw song files are transformed into feature-rich ASS subtitles with precise timing and reading aids for Japanese lyrics.
Sources: pyTool/README.md:120-130, README.md:1-15