PyLrcGet

🎵 A native desktop lyrics manager and player for local music libraries.

Browse, edit, sync, download, export, embed, and publish synced or plain lyrics without leaving your desktop workflow.

✨ What it does

• 🎧 Scans local folders recursively into SQLite with incremental refresh and exclusions.
• 📚 Browses Tracks, Albums, Artists, Album Artists, Lyrics Browser, and Lyrics Activity.
• 📝 Edits synced (.lrc) and plain lyrics, with unsaved drafts and playback highlighting.
• 🌐 Downloads through an ordered provider matrix; LRCLIB is enabled by default.
• 💾 Exports .lrc / .txt sidecars and embeds lyrics into supported formats.
• 🤖 Provides local AI Auto Sync with CUDA when available and CPU fallback.
• 🎨 Includes playback controls, themes, keyboard shortcuts, logs, and responsive layouts.

Provider settings are opt-in: a disabled provider is never used as an automatic fallback. See Musixmatch provider notes. When enough lyrics already exist on the same album, language detection can reject a confidently mismatched provider result instead of saving it.

📸 Screenshots

Add final captures under docs/screenshots/. The following views are the most useful for the project page and release notes:

When the captures are ready, add the image links below this table. Keep the images inside the repository so the README also renders offline:

![Tracks in the Light theme](docs/screenshots/tracks-light.png)
![Lyrics editor](docs/screenshots/lyrics-editor.png)

🚀 Quick start

py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1
python --version  # must report Python 3.13.15
python -m pip install -e ".[dev]"
python main.py

The project is pinned to Python 3.13.15 for development, AI setup, tests, and release builds. The app does not modify a music folder during normal scanning; exports and embedding are explicit user actions.

🤖 Optional AI Auto Sync

python -m pip install -e ".[ai]"

The packaged app can install the AI stack into its own runtime. WhisperX supports the multilingual path; lyrics-aligner is used for English when it is available. CUDA is selected automatically when available, but GPU is not guaranteed to be faster for every backend.

If the bootstrap interpreter must be selected explicitly:

$env:PYLRCGET_AI_BOOTSTRAP_PYTHON = "C:\Path\to\python.exe"

Optional Demucs is used only as a candidate vocal-stem path and is not required for the base AI workflow.

🌐 Lyrics providers

Enable and order providers in Settings -> Lyrics -> Providers. Provider matching uses artist, title, album, duration, and version metadata. Full transport limitations are documented in docs/MULTI_PROVIDER_MUSIXMATCH.md.

🎼 Supported audio formats

Playback depends on the active backend and installed codecs. Metadata support can be broader than playback support for a specific format.

⚙️ Important settings

Download modes are Prefer synced, Synced only, and Plain only. Export and embedding format choices are configured independently from download mode.

⚡ Performance and design notes

The scanner separates audio and sidecar state, reuses stored metadata for unchanged audio, and avoids unnecessary Mutagen and sidecar reads. LRCLIB bulk work uses batched metadata reads, bounded concurrency, duplicate lookup collapse, and shared rate-limit coordination.

See the benchmark summary for measured results, known trade-offs, and the TagLib decision. The benchmark harnesses are documented in tools/perf/README.md and tools/ai_sync_bench/README.md.

🛠️ Development

Run the test suite and static checks from the repository root:

$env:PYTHONPATH = "src"
python -m pytest
ruff check .

Useful focused commands:

python -m pytest tests/widgets_navigation -q
python tools/perf/benchmark_lrclib.py --tracks 250 --duplicate-every 5 --warmups 2 --runs 3

Performance fixtures and benchmark output are generated under benchmarks/; do not point a mutating benchmark at a real music folder. Read-only source measurements must use the harness --read-only-source option.

📦 Building locally

python -m pip install -r requirements.txt pyinstaller
pyinstaller --noconfirm pylrcget.spec

For the portable single-file build:

pyinstaller --noconfirm pylrcget-portable.spec

🧭 Releases and troubleshooting

Releases use Conventional Commits and semantic-release. See CHANGELOG.md for published changes.

• No lyrics found: check provider enablement/order and the track metadata.
• AI dependencies missing: use the AI setup dialog or install the ai extra with Python 3.13.15.
• Playback issue: verify the backend and codec support for the file format.
• Windows SmartScreen warning: release executables are currently unsigned.

License and credits

MIT © saitatter. The project is an independent desktop reimplementation inspired by the LRCLIB ecosystem and is not a fork of the original LRCGET application.

Support: Ko-fi