[EVERY FILE IS VIBECODED IF THAT WASNT OBVIOUS ENOUGH,SORRY]

/\ /\ /\ /\ /\ /\ /\ /
oh yea and because of this i recommend to use ai or someone else for troubleshooting cause i dont offer support for this project as of now

ALSO THIS BUILD SUCKSSSS, in regards to the lyric accuracy (faster the spoken lyrics in song the more accurate the wlrc will be) also non mainstream songs occasionally dont get pulled cause they are simply not in lrclib there are of course tons of small other issues, which i will have fixed eventually

Terminal lyrics visualizer with word-level sync. Displays song lyrics in large ASCII block letters in your terminal, synchronized to whatever is playing in your media player.

  ██   ██ ███████ ██      ██       ██████
  ██   ██ ██      ██      ██      ██    ██
  ███████ █████   ██      ██      ██    ██
  ██   ██ ██      ██      ██      ██    ██
  ██   ██ ███████ ███████ ███████  ██████

Required:

• python >= 3.12
• python-pyyaml
• ffmpeg (provides ffprobe)
• playerctl

Optional but you should really really get it:

• python-mutagen — reads embedded audio tags for better lyrics matching
• python-syncedlyrics — fallback lyrics source (NetEase, etc.)
• python-librosa — onset detection for more accurate word-level timing

paru -S lrc-tools

git clone https://github.com/tacoproz1/tacos-terminal-lyrics
cd tacos-terminal-lyrics
bash setup.sh
pip install pyyaml mutagen syncedlyrics --break-system-packages

mkdir -p ~/lyrics/raw ~/lyrics/processed

# 1. Download lyrics for your music library (if using bash and not fish run export PATH="$HOME/.local/bin:$PATH")
lrc-fetch --audio-dir ~/music --output-dir ~/lyrics/raw
# 2. Process into word-level timing
lrc-processor --lrc-dir ~/lyrics/raw --audio-dir ~/music \
              --output-dir ~/lyrics/processed --wlrc

# 3. Start the visualizer, play something in your media player
lrc-vis --lrc-dir ~/lyrics/processed --wlrc

Steps 1 and 2 are one-time setup per library. lrc-vis is the daily driver.

lrc-fetch scans your music directory, reads embedded tags (or parses filenames), and downloads synced LRC lyrics from LRCLIB with syncedlyrics as a fallback.

lrc-processor takes standard LRC files (phrase-level timing) and splits long phrases at natural boundaries — commas, conjunctions, duration — and optionally converts to word-level WLRC format using even distribution or librosa onset detection.

lrc-vis hooks into your media player via playerctl (MPRIS), finds the matching LRC/WLRC file for the current track, and renders lyrics as large block letters centered in the terminal. Handles seeking, pausing, and track changes automatically.

Output filenames must match audio filenames. Artist - Title.mp3 → Artist - Title.lrc. lrc-fetch handles this automatically. If you source LRC files elsewhere, name them to match.

Copy config_example.yaml to ~/.config/lrc-tools/config.yaml and pass it with --config:

lrc-vis --config ~/.config/lrc-tools/config.yaml --lrc-dir ~/lyrics/processed --wlrc

Key settings:

processor:
  max_phrase_duration: 2.5   # split phrases longer than this (seconds)
  max_words_per_phrase: 8

puller:
  search_threads: 5
  download_threads: 5
  preserve_structure: true   # mirror audio dir layout in lyrics dir

visualizer:
  default_font: block        # block or compact
  refresh_rate: 0.05

Fonts are defined in JSON. See custom_fonts.json for the format.

lrc-vis --lrc-dir ~/lyrics/processed --wlrc \
        --custom-fonts custom_fonts.json --font mini

for clearing metadata in locally downloaded files which may initially interfere with the process or other uses, refer to: https://gist.github.com/ISawSau/d3ea9ffd8b346be55c7bc68831637c47

for more dynamic OS/tool support check out: https://github.com/SlurryMixx/-tacos-terminal-lyrics-SPOTIFYPORT

vibecoded rust rewrite of my project(sorta), has higher standard wlrc/lrc repos(more accurate lyrics) go to: https://github.com/mgtaco/terminal-lyrics

MIT