⚡ LyricForger-Python

  _                 _     ______                               
 | |               (_)   |  ____|                              
 | |    _   _ _ __  _  __| |__ ___  _ __ __ _  ___ _ __        
 | |   | | | | '__|| |/ _`  __|/ _ \| '__/ _` |/ _ \ '__|      
 | |___| |_| | |   | | (_| | | | (_) | | | (_| |  __/ |        
 |______\__, |_|   |_|\__,_|_|  \___/|_|  \__, |\___|_|        
         __/ |                             __/ |               
        |___/                             |___/                

A standalone Python 3 TUI utility for Android (Termux) & Linux that smartly pairs ZIP archives of music files with .lrc/.txt lyrics and embeds them directly into audio metadata for Samsung Music & native players.

---

🇮🇷 راهنمای فارسی (Persian Documentation)

⚡ درباره برنامه

LyricForger-Python نسخه پایتون ابزار ترمینالی LyricForger است که بدون نیاز به کمپایل و با استفاده از ماژول‌های استاندارد پایتون در محیط Termux اندروید و لینوکس اجرا می‌شود. این ابزار فایل‌های زیپ آهنگ‌ها و لیریکس (.lrc یا .txt) را گرفته، با ۳ استراتژی هوشمند آن‌ها را مطابقت داده و متن ترانه را داخل فایل‌های MP3 و FLAC تزریق می‌کند تا در برنامه‌هایی مثل Samsung Music به همراه متن پخش شوند.

✨ ویژگی‌های کلیدی

• 🐍 بدون نیاز به پکیج‌های سنگین: اجرا با پایتون استاندارد و رابط ترمینالی Curses.
• 📱 سازگار با Termux: رابط کاربری گرافیکی ترمینالی متناسب با صفحات لمسی موبایل.
• 🎵 استاندارد سامسونگ موزیک: تزریق فریم‌های USLT در فایل‌های MP3 و کامنت‌های Vorbis در FLAC.
• 🎯 موتور تطبیق ۳ لایه: تطبیق هوشمند نام فایل‌ها، تگ‌های متادیتا و تشابه فازی حروف.

🚀 نحوه نصب و اجرا در ترموکس (Termux)

pkg update && pkg install -y python git
git clone https://github.com/AhooraZen/LyricForger-Python.git
cd LyricForger-Python
python3 lyric_forger.py

---

✨ English Features

• 🐍 Zero-Dependency Python Core: Works out-of-the-box using Python standard modules (curses, zipfile, difflib, struct) with optional mutagen library support.
• 📱 Termux & Android Optimized: Clean TUI layout built for small screen resolutions and touch keyboards.
• 🎵 Samsung Music Specification: Injects ID3v2 USLT (Unsynchronised lyric/text information) frames into MP3s and Vorbis LYRICS comment tags into FLAC files.
• 📦 Zip & Folder Support: Process compressed .zip archives directly without manual unzipping.
• 🎯 3 Smart Matching Strategies: Heuristic matching engine pairs music tracks with lyrics even when filenames differ.

---

🧠 The 3 Smart Matching Strategies

1. Strategy 1 — 🎯 Clean Normalized Exact Match:

   • Automatically strips leading track numbers (01 - , 02. , 1 ).
   • Removes release noise keywords ([Official Audio], (Lyrics), [320kbps], (remix)).
   • Replaces underscores and hyphens with clean spaces.

2. Strategy 2 — 🏷️ ID3 / Vorbis Metadata Tags vs. LRC Header Match:

   • Reads internal audio tags (Title, Artist).
   • Parses LRC headers ([ti: Track Title] and [ar: Artist Name]).
   • Cross-references metadata tags to match songs regardless of file naming.

3. Strategy 3 — 🔤 Fuzzy Distance Ratio:

   • Calculates SequenceMatcher ratio and token set similarity.
   • Handles minor spelling variations and inverted artist/title permutations.

🚀 1-Line Instant Install & Updater (No Git Clone Required!)

Run this single command in Termux or Linux to instantly download and install the launcher directly to your PATH:

curl -fsSL https://raw.githubusercontent.com/AhooraZen/LyricForger-Python/main/install.sh | bash

Note: Automatically installs the script and creates the lyric-forger-py command in your PATH. Run anytime to update!

---

🚀 Manual Installation & Quick Start

Termux (Android)

1. Open Termux and install Python:

   pkg update && pkg install -y python git

2. Clone this repository:

   git clone https://github.com/AhooraZen/LyricForger-Python.git
   cd LyricForger-Python

3. Install optional dependencies for expanded audio format support:

   pip install -r requirements.txt

4. Run the TUI:

   python3 lyric_forger.py

Linux / macOS

git clone https://github.com/AhooraZen/LyricForger-Python.git
cd LyricForger-Python
python3 lyric_forger.py

---

📱 Viewing Lyrics in Samsung Music

1. Run LyricForger-Python and complete the forging process.
2. If lyrics do not show up immediately in Samsung Music, clear Samsung Music app cache or restart your phone to let Android's MediaScanner re-index the tags.
3. Tap on the track cover art in Samsung Music to open the lyrics view!

---

📄 License

Distributed under the MIT License. See LICENSE for details.