lrcfetch

A CLI tool for fetching LRC lyrics on Linux. Automatically detects the currently playing track via MPRIS/DBus and retrieves synced (or plain with all time tags set to [00:00.00] if failed to find any synced) lyrics from multiple sources.

Sources

Lyrics are fetched using a fallback pipeline (first synced 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 lrcfetch --help for full command reference. Common use cases:

# Fetch lyrics for the currently playing track
lrcfetch fetch

# Search by metadata (bypasses MPRIS)
lrcfetch search -t "Song Title" -a "Artist"

# Export to .lrc file
lrcfetch export

# Force a specific source
lrcfetch fetch --method spotify

# Cache management
lrcfetch cache stats        # show cache statistics
lrcfetch cache query        # query cache for current track
lrcfetch cache clear        # clears cache of current track
lrcfetch cache clear --all  # clears entire cache

Configuration

Set credentials via environment variable or .env file:

• ~/.config/lrcfetch/.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

Shell completion (zsh/fish/bash):

lrcfetch --install-completion

Credits

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