# ๐ค LyricSync: Ultimate Terminal Karaoke Player
**A sophisticated, terminal-based karaoke player that dynamically synchronizes music playback with lyric files, featuring real-time word-by-word highlighting and multiple visual themes.**
[](https://www.python.org/)
[](https://www.pygame.org/)
[](https://github.com/Textualize/rich)
[](LICENSE)
*Experience high-fidelity lyric syncing, advanced .lrc format parsing, and customized console rendering directly inside your favorite shell.*
[Features](#-features) โข [System Flow](#%EF%B8%8F-system-flow) โข [Installation](#-installation) โข [Usage](#-usage) โข [LRC Format Specification](#%EF%B8%8F-lrc-format-specification) โข [Directory Structure](#-directory-structure) โข [Technical Reference](#-technical-reference)
---
## ๐ฏ Project Overview
**LyricSync** is a highly responsive, terminal-native media and lyric synchronizer. By combining `pygame`'s low-latency audio capabilities with `rich`'s powerful live console rendering engine, LyricSync processes standard `.lrc` lyric sheet files, tracks playback timings with microsecond precision, and renders dynamic text buffers that highlight exactly what word is being sung in real time.
Whether you are practicing vocals, building interactive media players, or simply looking for an elegant way to enjoy music in the terminal, LyricSync offers a rich, configurable karaoke dashboard right in your command line.
---
## โจ Features
### โฑ๏ธ True Synchronized Word Highlights
- Supports standard line-by-line LRC timestamps (`[mm:ss.xx]`).
- Supports advanced word-by-word inline timestamps (``) to light up words dynamically as they are sung.
### ๐ง Low-Latency Audio Streaming
- Leverages `pygame.mixer.music` for efficient audio streaming that handles MP3, WAV, OGG, FLAC, and M4A extensions natively.
- Features interactive fallbacks and safe shutdown routines that close sound channels immediately when the console exits.
### ๐ญ Visual Themes & Live Console Renderer
- Multiple styling modes (e.g., `classic` bold magenta/yellow and `neon` bright magenta/bright yellow).
- Uses `rich.live` rendering to refresh active screen buffers at a smooth 30 frames per second without screen flicker.
### ๐ Intelligent Audio & Lyric Pairing
- Scan engine pairs songs inside `songs/` with matching `.lrc` sheets in `lyrics/` by matching baseline filenames.
- Handles automated fallback prompt pipelines if lyric sheets are missing.
---
## โ๏ธ System Flow
```mermaid
graph TD
A["User Runs lyricsync.py"] --> B["Scanning directories: songs/ & lyrics/"]
B -->|Multiple Files| C["Choose Song Interactively"]
B -->|Single File| D["Auto-Select Matching Pair"]
C --> E["Load Audio Engine (pygame.mixer)"]
D --> E
E --> F["Parse LRC file & Timestamps"]
F --> G["Start Music Stream & Timer"]
G --> H["Live Console Loop (30 FPS via rich.live)"]
H -->|Calculate Elapsed Time| I["Find Active Line & Active Word"]
I -->|Past Lines| J["Render with past_line styling (dim)"]
I -->|Active Line| K["Render with current_line / highlight_word styles"]
I -->|Future Lines| L["Render with future_line styling (hidden/dim)"]
J & K & L --> M["Update Progress Bar & Timers"]
M --> H
H -->|Song Reaches End / User Exits| N["Shut down Mixer & Exit Gracefully"]
```
---
## ๐ Installation & Prerequisites
### ๐ Prerequisites
LyricSync requires **Python 3.8+** and access to system audio drivers.
#### Python Dependencies:
- `pygame` (Audio playback engine)
- `rich` (Live text rendering & command-line styling)
### ๐ ๏ธ Setup
**1๏ธโฃ Clone the repository:**
```bash
git clone https://github.com/spyberpolymath/lyricsync.git
cd lyricsync
```
**2๏ธโฃ Install requirements:**
```bash
pip install -r requirements.txt
```
---
## ๐ Usage
### ๐ฎ Normal Mode (Auto-Discover)
If you place your files inside the organized directories (see [Directory Structure](#-directory-structure)), simply run the application without arguments:
```bash
python lyricsync.py
```
*LyricSync will find matches, list selection prompts if multiple songs exist, and start the music player.*
### ๐ ๏ธ Explicit Argument Targeting
You can target local files directly from the terminal bypassing folder scans:
```bash
python lyricsync.py path/to/song.mp3 path/to/lyrics.lrc
```
### ๐งช Test/Development Mode
To preview styling, timing highlights, and themes without requiring an actual audio driver or audio files, run the script with the `--test` or `-t` flag:
```bash
python lyricsync.py --test
```
*This simulates active playback timings matching the lyrics.*
---
## ๐๏ธ LRC Format Specification
LyricSync processes both **Standard LRC** and **Extended (Word-Level) LRC** formats.
### 1. Standard LRC (Line-by-Line Synchronized)
Line-by-line sync uses bracketed timestamps at the beginning of each lyrics sentence:
```text
[00:10.50] This is the first line of lyrics
[00:14.20] Followed by the second line
```
### 2. Extended LRC (Word-by-Word Synchronized)
Word-level highlighting is achieved by wrapping words with secondary angle-bracketed timestamps (`` or ``):
```text
[00:15.00] <00:15.20>Word <00:15.50>by <00:15.80>word <00:16.10>karaoke <00:16.40>highlighting!
```
*When LyricSync plays this line, each word shifts colors precisely at its designated milestone.*
---
## ๐ Directory Structure
```text
lyricsync/
โ
โโโ songs/ # Place audio tracks here (.mp3, .wav, .ogg, .flac, .m4a)
โ โโโ example.mp3
โ
โโโ lyrics/ # Place .lrc files here (Must share basename with audio)
โ โโโ example.lrc
โ
โโโ lyricsync.py # Core runner script containing parser, mixer, and live screen updater
โโโ requirements.txt # Python project dependencies
โโโ LICENSE # MIT License
โโโ README.md # In-depth project documentation
```
---
## ๐ ๏ธ Technical Reference
### The Theme Configuration Engine
Themes are loaded dynamically using ANSI-friendly tags processed by `rich`. You can add your own custom themes directly inside the `THEMES` mapping:
```python
THEMES = {
"classic": {
"current_line": "bold magenta",
"past_line": "dim white",
"future_line": "dim",
"highlight_word": "bold yellow"
},
"neon": {
"current_line": "bold bright_magenta",
"past_line": "dim bright_blue",
"future_line": "dim",
"highlight_word": "bold bright_yellow"
}
}
```
### Key Functions
- `parse_lrc(lrc_path)`: Scans LRC sheets line-by-line using regular expressions, sorting them chronologically and isolating line timings from word-level timing offsets.
- `build_lyrics_display(lyrics, elapsed_time)`: Reconstructs the terminal layout at each clock cycle. It checks if lines are past, current, or future, applies text decorations, and compiles the console frame.
- `karaoke_runner(...)`: The master controller. Initiates `pygame` audio threads, boots the `rich.Live` context manager, calculates absolute offsets, and manages progressive terminal refreshes.
---
## ๐ค Contributing
1. Fork this project repo.
2. Create a branch (`git checkout -b feature/awesome-feature`).
3. Commit your changes (`git commit -m 'Implement feature'`).
4. Push to your branch (`git push origin feature/awesome-feature`).
5. Open a Pull Request.
---
## ๐ License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
## ๐ท๏ธ Footer
**๐จโ๐ป Aman Anil** (aka **SpyberPolymath**)
*Crafting digital experiences with passion and precision*
[](https://github.com/spyberpolymath)
[](https://kaggle.com/spyberpolymath)
[](https://linkedin.com/in/spyberpolymath)
[](https://t.me/spyberpolymath)
**๐ง [aman@spyberpolymath.com](mailto:aman@spyberpolymath.com)** | **๐ [spyberpolymath.com](https://spyberpolymath.com)**
---
*Made with โค๏ธ by Aman Anil aka (SpyberPolymath)* โจ