lrc-tools

  _      ____   ___    _____           _
 | |    |___ \ / _ \  |_   _|_ _  ___| |_
 | |      __) | | | |   | |/ _` |/ _ \ __|
 | |___  / __/| |_| |   | | (_| |  __/ |_
 |_____|_____| \___/    |_|\__,_|\___|\__|

Terminal synced lyrics toolkit — fetch, process, and visualize .lrc lyrics from your terminal.

What is this?

Three operations from the terminal:

1. Fetch synced lyrics from LRCLIB for your music library
2. Process .lrc into word-level .wlrc with phrase splitting and onset detection
3. Visualize lyrics in real time while music is playing (MPRIS / mpv / ffplay)

New? Run lrc-tools, pick your music folder, fetch → process → enjoy.

Quick install

pip install --user lrc-tools
# Or with extras:
pip install --user "lrc-tools[full]"   # +mutagen +syncedlyrics +textual

Or download a binary from Releases.

System requirements: Python 3.12+, ffmpeg/ffprobe, playerctl (Linux only).

Commands

CLI examples

# Fetch lyrics for all songs in ~/Music
lrc-fetch --audio-dir ~/Music --output-dir ~/.local/share/lrc-tools/lyrics/raw

# Process to word-level with custom split settings
lrc-processor --lrc-dir ./raw --audio-dir ./music --output-dir ./out --wlrc \
  --max-phrase-duration 3.0 --max-words 10

# Visualize with auto-match from media player
lrc-vis --lrc-dir ~/.local/share/lrc-tools/lyrics/processed --wlrc

# Validate an LRC file
python3 -c "from lrc_tools.parser import validate_lrc; print(validate_lrc('file.lrc'))"

# Export LRC to SRT subtitles
python3 -c "from lrc_tools.exporters import export_srt; export_srt('file.lrc', 'file.srt')"

See --help on any command for full options.

Default paths

On macOS: ~/Library/Application Support/ and ~/Library/Preferences/.
On Windows: %LOCALAPPDATA% and %APPDATA%.

Workflow

Audio files  ──→  lrc-fetch  ──→  .lrc (raw)  ──→  lrc-processor  ──→  .wlrc  ──→  lrc-vis

Or from the TUI: lrc-tools → Configure paths → Fetch → Process → Visualize.

Features

Docs

• Configuration
• File formats
• Troubleshooting
• API reference

Development

git clone https://github.com/RicknotDev/lrc-tools
cd lrc-tools
pip install -e ".[full]"
python -m unittest discover -s tests

See CONTRIBUTING.md.

License

MIT