Metadata-Version: 2.4
Name: librelyrics-lrclib
Version: 1.0.0
Summary: LRCLIB lyrics provider plugin for LibreLyrics
Author-email: libre-lyrics <libre-lyrics@users.noreply.github.com>
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/libre-lyrics/librelyrics-lrclib
Project-URL: Repository, https://github.com/libre-lyrics/librelyrics-lrclib
Project-URL: Issues, https://github.com/libre-lyrics/librelyrics-lrclib/issues
Keywords: lyrics,lrclib,lrc,synced-lyrics,librelyrics,plugin
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: librelyrics>=1.2.0
Requires-Dist: requests>=2.28.0
Requires-Dist: pyyaml>=6.0

# librelyrics-lrclib

[LRCLIB](https://lrclib.net) provider plugin for
[LibreLyrics](https://github.com/libre-lyrics/librelyrics). Fetches line-synced
and word-synced lyrics from the free, key-less LRCLIB database.

This is a **search** plugin: it matches on artist, title and duration rather
than a provider URL.

## Install

```bash
pip install librelyrics-lrclib
```

## Usage

```bash
# LRCLIB is searched automatically when no URL plugin matches.
librelyrics --artist "Radiohead" --title "Creep"

# Or force it explicitly.
librelyrics --from lrclib --artist "Radiohead" --title "Creep"

# Duration sharpens the match (LRCLIB requires +/-2s agreement).
librelyrics --artist "Radiohead" --title "Creep" --duration 239
```

To make it part of the normal search chain:

```json
{
    "search_priority": ["lrclib", "betterlyrics"]
}
```

## How it matches

1. `GET /api/get` with the full track signature (title, artist, album,
   duration). This is the precise path and the only one that can return
   word-synced records.
2. If that misses, `GET /api/search` with structured `track_name` /
   `artist_name`, ranking candidates on artist, title and duration agreement so
   covers and live versions do not win by accident.

## Configuration

Optional, under `plugins.lrclib`:

| Key | Default | Description |
| --- | --- | --- |
| `user_agent` | `LibreLyrics v1.2.0 (...)` | Identifies this client, as LRCLIB requires. |
| `delay` | `0.35` | Seconds between requests. Minimum `0.2`. |

```bash
librelyrics config edit
```

## Politeness

LRCLIB asks clients to send requests sequentially with a 200-500 ms pause. This
plugin throttles itself process-wide (with jitter, so concurrent batch fetches
do not burst) and honours `Retry-After` on both `429` and `503`.

## Licence

GPL-3.0-or-later. Lyrics are served by LRCLIB under their own terms.
