API Documentation

Attempt to find the best match of lyrics for the track. You must provide the exact signature of the track, including the track title, artist name, album name, and the track's duration in seconds.

Each time you request a new track's signature, this API will attempt to access external sources in case the lyrics are not found in the internal database. Therefore, the response time will vary significantly. If you prefer to avoid this behavior, please use the /api/get-cached API instead.

Note: The provided duration is crucial. 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.

Query parameters

Example request

GET /api/get?artist_name=Borislav+Slavov&track_name=I+Want+to+Live&album_name=Baldur%27s+Gate+3+(Original+Game+Soundtrack)&duration=233

Example response

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"
}

This API is similar to /api/get, except that it will only look for lyrics from internal database, and will NOT attempt to access external sources.

Query parameters

Example request

GET /api/get-cached?artist_name=Jeremy+Soule&track_name=Dragonborn&album_name=The+Elder+Scrolls+V:+Skyrim:+Original+Game+Soundtrack&duration=236

Example response

Please see the /api/get's example response.

Get a lyrics record by an absolute ID. ID of a lyrics record can be retrieved from other APIs, such as /api/search API.

URL parameters

Example request

GET /api/get/3396226

Example response

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.

Note: This API currently returns a maximum of 20 results and does not support pagination. These limitations are subject to change in the future.

Query parameters

Example request

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

Response

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.

Obtaining the Publish Token

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.

Request header

Request JSON body parameters

Response

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.

Example response

{
  "prefix": "VXMwW2qPfW2gkCNSl1i708NJkDghtAyU",
  "target": "000000FF00000000000000000000000000000000000000000000000000000000"
}