PyLrcGet
Docker app from crywolf203's Repository
Unofficial Unraid-friendly Docker container for PyLrcGet, packaged inside LinuxServer Webtop for browser-based desktop access.
Overview
Readme
View on GitHubPyLrcGet
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.
License: MIT GitHub Release Issues Python PySide6 SQLite Platform
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/.txtsidecars 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:
| File | What to capture | Why it is useful |
|---|---|---|
tracks-light.png |
Light theme, selected track, library table, and lyrics panel. | Main product view and light-theme readability. |
tracks-dark.png |
The same view in the Dark theme. | Theme support and normal navigation hierarchy. |
lyrics-editor.png |
Synced editor with timestamps, toolbar, and player bar. | Core editing workflow. |
empty-lyrics.png |
Missing-lyrics state with provider actions visible. | First-run/download experience. |
settings-providers.png |
Provider matrix with LRCLIB/Musixmatch settings. | Provider configuration and disabled-provider behavior. |
settings-appearance.png |
Appearance settings with theme and page-size controls. | Customization and indexed table pagination. |
responsive-narrow.png |
Narrow window with compact actions and lyrics pane. | Responsive layout and overflow actions. |
clear-lyrics.png |
Clear Lyrics dialog with grouped TXT/LRC options. | Safe cleanup and embedded-lyrics controls. |
When the captures are ready, add the image links below this table. Keep the images inside the repository so the README also renders offline:


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
Open Settings > AI Sync > Manage AI runtime to install missing AI packages. You can also select a track and click Sync with AI to open setup when needed.
For a batch, select multiple tracks (or Ctrl+A for the current track list), then choose Sync with AI in the selection bar or Sync selected tracks with AI from the context menu. Tracks run one at a time; instrumental tracks, missing audio and tracks without lyrics are skipped. Results stay as unsaved drafts. Cancel stops the current sync and queue; drafts already completed remain available.
AI setup installs a tested combination of Torch 2.8.0, Torchaudio 2.8.0 and
WhisperX 3.8.6. It also prepares the English pronunciation dictionaries in the
application's nltk_data cache. Missing data or unsupported core package versions
are reported for repair through Manage AI runtime.
CPU forces processor execution; Auto selects an available accelerator, while the English alignment model itself stays on the CPU where it runs faster. Explicit CUDA reports an error when CUDA is unavailable. Manual timing hints use guided alignment. The fuzzy threshold applies to fallback text matching. With Demucs enabled, English lyrics are aligned against the song and its separated vocals together; separation always runs with an accelerator and, on CPU, only when the first alignment looks inconsistent.
See the local AI validation report for tested configurations and measured timing limits.
python -m pip install -e ".[ai]"
The packaged app can install the AI stack into its own runtime without a
system Python or Git installation. On the first install, it downloads and verifies a
pinned Python 3.13.15 bootstrap, caches it locally, and installs the AI stack
into an isolated 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. AI packages and models are still downloaded separately and can be
large. The bootstrap distribution is provided by
python-build-standalone;
its license files are retained with the cached runtime.
To use a separately installed Python 3.13.15 bootstrap explicitly:
$env:PYLRCGET_AI_BOOTSTRAP_PYTHON = "C:\Path\to\python.exe"
Optional Demucs adds separated-vocal evidence to English alignment and is not required for the base AI workflow.
Lyrics providers
LRCLIB searches use the lightweight /api/v2/search endpoint. Search results
show lyrics availability without downloading every result's lyrics; the selected
record is loaded in the background through /api/get/{id}. Older instances
automatically fall back to /api/search when v2 is unavailable. Rate limits,
server errors and network failures do not trigger fallback; request pacing and
Retry-After handling apply to both API versions.
In Settings > Lyrics > Providers > LRCLIB, adjust Request interval to pace requests across workers (default: one second). Rate-limited lookups honor the server's Retry-After delay and retry automatically. Increase the interval if your LRCLIB instance still limits requests; zero disables the regular pause.
| Provider | Default | Notes |
|---|---|---|
| LRCLIB | Yes | Download, search, and publish support. |
| Musixmatch | No | Website transport needs no key; official API accepts a user-provided key. |
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
| Format | Scan | Lyrics read/write | Sidecar export |
|---|---|---|---|
| MP3, WAV | Yes | Yes | Yes |
| M4A / MP4 | Yes | Yes | Yes |
| FLAC, OGG / OGA, OPUS | Yes | Yes | Yes |
| WMA / ASF | Yes | Yes | Yes |
| DSF, DFF, MPC / Musepack | Yes | Yes | Yes |
Playback depends on the active backend and installed codecs. Metadata support can be broader than playback support for a specific format.
Important settings
| Area | Examples |
|---|---|
| Library | Music folders, exclusions, worker count, scan source, startup view |
| Lyrics | Download mode, provider order, sidecars, embedding, filename pattern |
| AI Sync | Device, language, fuzzy matching, optional Demucs candidate |
| Appearance | Theme, UI scale, font size, album art |
| Shortcuts | Global playback keys and lyrics-editor keys |
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.
From the next release, download filenames identify the CPU target: Windows/Linux
x64 and macOS arm64 (Apple Silicon). Existing release filenames stay unchanged.
The updater selects the native target; labeled installer aliases keep updates
working for previously installed versions. See release packaging.
- No lyrics found: check provider enablement/order and the track metadata.
- AI dependencies missing: packaged builds can install them from the AI setup dialog; source builds need 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
Categories
Download Statistics
Related apps
Explore more like this
Explore allLinks
Details
crywolf203/pylrcget-unraid:latestRuntime arguments
- Web UI
https://[IP]:[PORT:3001]/- Network
bridge- Shell
bash- Privileged
- false
- Extra Params
--shm-size="1gb"
Template configuration
HTTPS Webtop browser access port. Open https://[IP]:[PORT:3001]/
- Target
- 3001
- Default
- 5801
- Value
- 5801
Container config, Webtop profile, browser data, and app settings.
- Target
- /config
- Default
- /mnt/user/appdata/pylrcget
- Value
- /mnt/user/appdata/pylrcget
Music library path. Use /music inside PyLrcGet. Change this to your actual Unraid music path.
- Target
- /music
- Default
- /mnt/user/media/music
- Value
- /mnt/user/media/music
User ID. Unraid default is 99.
- Default
- 99
- Value
- 99
Group ID. Unraid default is 100.
- Default
- 100
- Value
- 100
Container timezone.
- Target
- TZ
- Default
- America/New_York
- Value
- America/New_York
Enable Webtop GUI autostart.
- Target
- GUIAUTOSTART
- Default
- true
- Value
- true