LRCLIB

https://lrclib.net/docs
Admin
LRCLIB is an open lyrics API platform that enables developers to search, retrieve, and publish song...
Tokens:2,670
Snippets:25
Trust Score:8.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### Request lyrics by track signature

Source: https://lrclib.net/docs

Example GET request to retrieve lyrics using track metadata as query parameters.

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

--------------------------------

### Set User-Agent Header

Source: https://lrclib.net/docs

Example of the required User-Agent header format for identifying your client application.

```text
LRCGET v0.2.0 (https://github.com/tranxuanthang/lrcget)
```

--------------------------------

### Example response for challenge request

Source: https://lrclib.net/docs

The response contains a prefix and target string used for cryptographic challenge solving. These values expire after 5 minutes.

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

--------------------------------

### GET /api/get/:id

Source: https://lrclib.net/docs

Retrieves a specific lyrics record by its absolute ID.

```APIDOC
## GET /api/get/:id

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

### Method
GET

### Endpoint
/api/get/:id

### Parameters
#### Path Parameters
- **id** (number) - Required - ID of the lyrics record

### Request Example
GET /api/get/3396226
```

--------------------------------

### GET /api/get

Source: https://lrclib.net/docs

Retrieves lyrics for a track by providing its signature details. The API searches internal and external sources, with duration matching being a critical factor.

```APIDOC
## GET /api/get

### Description
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.

### Method
GET

### Endpoint
/api/get

### Parameters
#### Query Parameters
- **track_name** (string) - Required - Title of the track
- **artist_name** (string) - Required - Name of the artist
- **album_name** (string) - Required - Name of the album
- **duration** (number) - Required - Track's duration in seconds

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

### Response
#### Success Response (200)
- **id** (number) - Track ID
- **trackName** (string) - Title of the track
- **artistName** (string) - Name of the artist
- **albumName** (string) - Name of the album
- **duration** (number) - Duration in seconds
- **instrumental** (boolean) - Whether the track is instrumental
- **plainLyrics** (string) - Plain text lyrics
- **syncedLyrics** (string) - Synced lyrics in LRC format

#### Response Example
{
  "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] "
}
```

--------------------------------

### Get lyrics by ID

Source: https://lrclib.net/docs

Retrieves a specific lyrics record using its absolute ID.

```http
GET /api/get/3396226
```

--------------------------------

### GET /api/search

Source: https://lrclib.net/docs

Searches for lyrics records based on provided keywords and metadata.

```APIDOC
## GET /api/search

### Description
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.

### Method
GET

### Endpoint
/api/search

### Parameters
#### Query Parameters
- **q** (string) - Conditional - Search for keyword present in ANY fields (track's title, artist name or album name)
- **track_name** (string) - Conditional - Search for keyword in track's title
- **artist_name** (string) - Optional - Search for keyword in track's artist name
- **album_name** (string) - Optional - Search for keyword in track's album name

### Request Example
GET /api/search?q=still+alive+portal

### Response
#### Success Response (200)
- **id** (number) - Lyrics record ID
- **trackName** (string) - Name of the track
- **artistName** (string) - Name of the artist
- **albumName** (string) - Name of the album
- **duration** (number) - Duration of the track
- **instrumental** (boolean) - Whether the track is instrumental
- **plainLyrics** (string) - Plain text lyrics
- **syncedLyrics** (string) - Synced lyrics
```

--------------------------------

### POST /api/request-challenge

Source: https://lrclib.net/docs

Generates a prefix and target string pair for a cryptographic challenge, which is used to create a Publish Token for submitting lyrics.

```APIDOC
## POST /api/request-challenge

### Description
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.

### Method
POST

### Endpoint
/api/request-challenge

### Response
#### Success Response (200)
- **prefix** (string) - The prefix string for the challenge.
- **target** (string) - The target string for the challenge.

#### Response Example
{
  "prefix": "VXMwW2qPfW2gkCNSl1i708NJkDghtAyU",
  "target": "000000FF00000000000000000000000000000000000000000000000000000000"
}
```

--------------------------------

### POST /api/publish

Source: https://lrclib.net/docs

Publishes new lyrics to the LRCLIB database. This endpoint requires a valid Publish Token obtained via a proof-of-work challenge.

```APIDOC
## POST /api/publish

### Description
Publish a new lyrics to LRCLIB database. This API can be called anonymously. If both plain and synchronized lyrics are empty, the track is marked as instrumental.

### Method
POST

### Endpoint
/api/publish

### Parameters
#### Request Header
- **X-Publish-Token** (string) - Required - A Publish Token retrieved via solving a cryptographic challenge.

#### Request Body
- **trackName** (string) - Required - Title of the track
- **artistName** (string) - Required - Track's artist name
- **albumName** (string) - Required - Track's album name
- **duration** (number) - Required - Track's duration
- **plainLyrics** (string) - Required - Plain lyrics for the track
- **syncedLyrics** (string) - Required - Synchronized lyrics for the track

### Response
#### Success Response (201)
- Created

#### Error Response (400)
{
  "code": 400,
  "name": "IncorrectPublishTokenError",
  "message": "The provided publish token is incorrect"
}
```

--------------------------------

### Search for lyrics records

Source: https://lrclib.net/docs

Searches for lyrics using keywords. Requires at least one of 'q' or 'track_name' parameters.

```http
GET /api/search?q=still+alive+portal
```

```http
GET /api/search?track_name=22&artist_name=taylor+swift
```

--------------------------------

### Track not found error response

Source: https://lrclib.net/docs

JSON response returned when the requested track signature does not match any records.

```json
{
  "code": 404,
  "name": "TrackNotFound",
  "message": "Failed to find specified track"
}
```

--------------------------------

### Successful lyrics response

Source: https://lrclib.net/docs

JSON response structure returned when a track is successfully found.

```json
{
  "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] "
}
```

--------------------------------

### Rate Limit Exceeded Response

Source: https://lrclib.net/docs

The JSON structure returned by the server when the rate limit is exceeded.

```json
{
  "code": 429,
  "name": "TooManyRequests",
  "message": "Rate limit exceeded"
}
```

--------------------------------

### Incorrect Publish Token Error Response

Source: https://lrclib.net/docs

The JSON structure returned when a request fails due to an invalid or expired publish token.

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