Software systemSoftware RepositoryActive

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.

GitHub repository

LyricSync — Ultimate Terminal Karaoke Player

All projects

README.md specification

Raw source

🎤 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.

Experience high-fidelity lyric syncing, advanced .lrc format parsing, and customized console rendering directly inside your favorite shell.

Features • System Flow • Installation • Usage • LRC Format Specification • Directory Structure • 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 (<mm:ss.xx>) 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

Loading interactive architecture diagram…

🚀 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), 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 (<mm:ss.xx> or <ss.xx>):

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.