Welcome to the beta API documentation and specification of the LRCLIB's API! Although we intend to maintain backward compatibility, please be aware that there may be breaking changes in future updates. Since this document is still in its early stages, it may lack information or contain inaccuracies in certain sections.
This API has no rate limiting in place and is openly accessible to all users and applications. There is no need for an API key or any kind of registering!
While this is not mandatory, if you are developing an application to interact with LRCLIB, we encourage you to include the Lrclib-Client
or User-Agent
header in your requests, specifying your application's name, version, and a link to its homepage or project page. For example: LRCGET v0.2.0 (https://github.com/tranxuanthang/lrcget)
.
Update: Added Lrclib-Client
header support as an alternative to User-Agent
for environments where User-Agent
can't be set (e.g., browsers).
Attempt to find the best match of lyrics for the track. You should provide as much information as you can about the track, including the track name, artist name, album name, and the track's duration in seconds.
This API is the preferred method for retrieving lyrics in most cases, offering high performance and accuracy.
Note: If the duration
is provided, LRCLIB will attempt to provide the lyrics only when the duration matches the record in LRCLIB's database, or at least with a difference of ±2 seconds in duration.
Update: The album_name
and duration
parameter is now optional. Providing all of the parameters is still encouraged, but not required anymore.
Field | Required | Type | Description |
---|---|---|---|
track_name | true | string | Title of the track |
artist_name | true | string | Name of the artist |
album_name | false | string | Name of the album |
duration | false | number | Track's duration in seconds |
GET /api/get?artist_name=Borislav+Slavov&track_name=I+Want+to+Live&album_name=Baldur%27s+Gate+3+(Original+Game+Soundtrack)&duration=233
200 OK:
{ "id": 3396226, "trackName": "I Want to Live", "artistName": "Borislav Slavov", "albumName": "Baldur's Gate 3 (Original Game Soundtrack)", "duration": 233, "instrumental": false, "plainLyrics": "I feel your breath upon my neck\n...The clock won't stop and this is what we get\n", "syncedLyrics": "[00:17.12] I feel your breath upon my neck\n...[03:20.31] The clock won't stop and this is what we get\n[03:25.72] " }
404 Not Found:
{ "code": 404, "name": "TrackNotFound", "message": "Failed to find specified track" }
Get a lyrics record by an absolute ID. ID of a lyrics record can be retrieved from other APIs, such as /api/search
API.
Field | Required | Type | Description |
---|---|---|---|
id | true | number | ID of the lyrics record |
GET /api/get/3396226
Please see the /api/get
's example response.
Search for lyrics records using keywords. This API returns an array of lyrics records that match the specified search condition(s).
At least ONE of the two parameters, q
OR track_name
, must be present.
Recommendation: Use the /api/get
API as your primary method and only resort to /api/search
as a fallback. The /api/search
API is significantly slower, more resource-intensive, and less precise than /api/get
.
When using the search API, prioritize specific fields (track_name
, artist_name
, album_name
) over the general q
parameter for faster and more accurate results.
Note: This API currently returns a maximum of 20 results and does not support pagination. These limitations are subject to change in the future.
Field | Required | Type | Description |
---|---|---|---|
q | conditional | string | Search for keyword present in ANY fields (track's title, artist name or album name) |
track_name | conditional | string | Search for keyword in track's title |
artist_name | false | string | Search for keyword in track's artist name |
album_name | false | string | Search for keyword in track's album name |
Search for lyrics by using only q
parameter:
GET /api/search?q=still+alive+portal
Search for lyrics by using multiple fields:
GET /api/search?track_name=22&artist_name=taylor+swift
JSON array of the lyrics records with the following parameters: id
, trackName
, artistName
, albumName
, duration
, instrumental
, plainLyrics
and syncedLyrics
.
Note: This API is experimental and subject to potential changes in the future.
Publish a new lyrics to LRCLIB database. This API can be called anonymously, and no registration is required.
If BOTH plain lyrics and synchronized lyrics are left empty, the track will be marked as instrumental.
All previous revisions of the lyrics will still be kept when publishing lyrics for a track that already has existing lyrics.
Every POST /api/publish
request must include a fresh, valid Publish Token in the X-Publish-Token
header. Each Publish Token can only be used once.
The Publish Token consists of two parts: a prefix
and a nonce
concatenated with a colon ({prefix}:{nonce}
).
To obtain a prefix
, you need to make a request to the POST /api/request-challenge
API. This will provide you with a fresh prefix string and a target string.
To find a valid nonce
, you must solve a proof-of-work cryptographic challenge using the provided prefix
and target
. For implementation examples, please refer to the source code of LRCGET.
Header name | Required | Description |
---|---|---|
X-Publish-Token | true | A Publish Token that can be retrieved via solving a cryptographic challenge |
Field | Required | Type | Description |
---|---|---|---|
trackName | true | string | Title of the track |
artistName | true | string | Track's artist name |
albumName | true | string | Track's album name |
duration | true | number | Track's duration |
plainLyrics | true | string | Plain lyrics for the track |
syncedLyrics | true | string | Synchronized lyrics for the track |
Success response: 201 Created
Failed response (incorrect Publish Token):
{ "code": 400, "name": "IncorrectPublishTokenError", "message": "The provided publish token is incorrect" }
Note: This API is experimental and subject to potential changes in the future.
Generate a pair of prefix
and target
strings for the cryptographic challenge. Each challenge has an expiration time of 5 minutes.
The challenge's solution is a nonce
, which can be used to create a Publish Token for submitting lyrics to LRCLIB.
{ "prefix": "VXMwW2qPfW2gkCNSl1i708NJkDghtAyU", "target": "000000FF00000000000000000000000000000000000000000000000000000000" }