LRX-CLI

A CLI tool for fetching LRC lyrics on Linux. Automatically detects the currently playing track via MPRIS/DBus and retrieves the best-matching lyrics from multiple sources, ranked by confidence scoring.

Sources

Sources are queried in order. High-confidence results (exact match or manual insert) terminate the pipeline early; otherwise all sources are tried and the highest-confidence result wins.

1. Local — sidecar .lrc files or embedded audio metadata (FLAC, MP3)
2. Cache Search — fuzzy cross-album lookup in local cache
3. Spotify — synced lyrics via Spotify's API (requires SPOTIFY_SP_DC)
4. LRCLIB — exact match from lrclib.net (requires full metadata)
5. LRCLIB Search — fuzzy search from lrclib.net (requires at least a title)
6. Netease — Netease Cloud Music public API
7. QQ Music — QQ Music via self-hosted API proxy (requires QQ_MUSIC_API_URL that provides the same interface as tooplick/qq-music-api)

Usage

See lrx --help for full command reference. Common use cases:

• Fetch lyrics for the currently playing track:

  lrx fetch
  

  using a specific player or source to fetch from:

  lrx --player mpd fetch --method lrclib-search
  

• Search by metadata (bypasses MPRIS):

  lrx search -t "My Love" -a "Westlife"
  lrx search --trackid "5p0ietGkLNEqx1Z7ijkw5g"
  

  or for a local file:

  lrx search --path "/path/to/Westlife - My Love.flac"
  

• Export to sidecar .lrc file (or .txt with --plain):

  lrx export
  lrx export --plain
  lrx export --output /path/to/lyrics.lrc
  

• Cache management:

  lrx cache stats                    # statistics with source×status table and confidence distribution
  lrx cache query                    # inspect cache entries for current track
  lrx cache clear                    # clear cache of current track
  lrx cache clear --all              # clear entire cache
  lrx cache confidence spotify 100   # manually set confidence for a source
  

Configuration

Set credentials via environment variable or .env file:

• ~/.config/lrx/.env — user-level
• .env in working directory — project-local
• Shell environment — highest priority

SPOTIFY_SP_DC=your_cookie_value
QQ_MUSIC_API_URL=https://api.example.com
PREFERRED_PLAYER=spotify

• SPOTIFY_SP_DC — required for Spotify source. Defaults to empty (disabled Spotify source).
• QQ_MUSIC_API_URL — required for QQ Music source. Defaults to empty (disabled QQ Music source).
• PREFERRED_PLAYER — preferred MPRIS player when multiple are active. Defaults to spotify. Only used when no --player flag is given and more than one player (or none of them) is currently playing.

Shell completion (zsh/fish/bash):

lrx --install-completion

Credits

• lrclib.net
• spotify-lyrics-api
• librelyrics-spotify
• NeteaseCloudMusicAPI
• qq-music-api