API Documentation

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).

Get lyrics with a track's signature

GET
/api/get

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.

Query parameters

FieldRequiredTypeDescription
track_nametruestringTitle of the track
artist_nametruestringName of the artist
album_namefalsestringName of the album
durationfalsenumberTrack's duration in seconds

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

Get lyrics by LRCLIB's ID

GET
/api/get/{id}

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

FieldRequiredTypeDescription
idtruenumberID of the lyrics record

Example request

GET /api/get/3396226

Example response

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

Search for lyrics records

GET
/api/search

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.

Query parameters

FieldRequiredTypeDescription
qconditionalstringSearch for keyword present in ANY fields (track's title, artist name or album name)
track_nameconditionalstringSearch for keyword in track's title
artist_namefalsestringSearch for keyword in track's artist name
album_namefalsestringSearch for keyword in track's album name

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.

Publish a new lyrics

POST
/api/publish

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

Header nameRequiredDescription
X-Publish-TokentrueA Publish Token that can be retrieved via solving a cryptographic challenge

Request JSON body parameters

FieldRequiredTypeDescription
trackNametruestringTitle of the track
artistNametruestringTrack's artist name
albumNametruestringTrack's album name
durationtruenumberTrack's duration
plainLyricstruestringPlain lyrics for the track
syncedLyricstruestringSynchronized lyrics for the track

Response

Success response: 201 Created

Failed response (incorrect Publish Token):

{
  "code": 400,
  "name": "IncorrectPublishTokenError",
  "message": "The provided publish token is incorrect"
}

Request a challenge

POST
/api/request-challenge

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