LrcLib Endpoints

Compatible endpoints provided for audio players or plugins implementing the LrcLib Protocol to connect directly to the AMLL lyric database.

LrcLib Response Model LrclibSongItem

Lyric response structure compatible with LrcLib format:

export interface LrclibSongItem {
  /** Unique lyric ID */
  id: number;
  /** Song title */
  name: string;
  /** Song title */
  trackName: string;
  /** Artist name */
  artistName: string;
  /** Album name */
  albumName: string;
  /**
   * Highest timestamp appearing in lyrics (seconds)
   *
   * Note: Not the exact audio file duration
   */
  duration: number;
  /** Whether the track is instrumental */
  instrumental: false;
  /** Plain text lyrics */
  plainLyrics: string;
  /** Synced LRC lyrics */
  syncedLyrics: string;
}

• instrumental: Whether the track is instrumental. Fixed to false
• Song title, artist name, and album name pick the first element from arrays.

---

Search Lyrics

Fuzzy search in database, returning the first 50 items by default; use the pagination parameters to page through results.

GET/v1/lrclib/search

Query Parameters

At least one of track_name, q, artist_name, or album_name must be provided.

Parameter	Type	Required	Description
q	string	No	Global search keyword
track_name	string	No	Track name
artist_name	string	No	Artist name
album_name	string	No	Album title

Pagination Parameters

This endpoint additionally supports pagination. These two parameters are an AMLL extension and are not part of the LrcLib protocol, so they use the same camelCase naming as the native search endpoint rather than the snake_case style of this endpoint’s other parameters.

Parameter	Type	Default	Range	Description
page	number	1	>= 1	Page number, starting at 1
pageSize	number	50	1–100	Number of items per page

• Non-positive integers, 0, or values outside the allowed range return 400.
• Pagination parameters do not count toward the “at least one search parameter” requirement; passing only pagination parameters still returns 400.
• When no pagination parameters are provided, the behavior is identical to before (the first 50 items), so existing LrcLib clients need no changes.

Response Schema

Returns 200 status code on success with the following structure:

type LrcLibSearchResponse = LrclibSongItem[];

• To preserve LrcLib protocol compatibility, the response is always a bare array and carries no pagination metadata. If you need total / totalPages / hasMore, use the native search endpoint.
• Element type is LrclibSongItem Model; the length never exceeds pageSize.
• When the requested page exceeds the total number of results, an empty array [] is returned.

Example Response

[
  {
    "id": 269710089745311,
    "name": "ME!",
    "trackName": "ME!",
    "artistName": "Brendon Urie",
    "albumName": "Lover",
    "duration": 185.8,
    "instrumental": false,
    "plainLyrics": "I promise that you'll never find another like me\nI know that I'm a handful, baby, uh...",
    "syncedLyrics": "[00:00.11] I promise that you'll never find another like me\n[00:03.47] I know that I'm a handful, baby, uh..."
  },
  {
    "id": 7807416901227298,
    "name": "ME! (feat. Brendon Urie of Panic! At The Disco)",
    "trackName": "ME! (feat. Brendon Urie of Panic! At The Disco)",
    "artistName": "Taylor Swift",
    "albumName": "Lover",
    "duration": 185.83,
    "instrumental": false,
    "plainLyrics": "I promise that you'll never find another like me\nI know that I'm a handful, baby, uh...",
    "syncedLyrics": "[00:00.13] I promise that you'll never find another like me\n[00:03.46] I know that I'm a handful, baby, uh..."
  }
]

---

Fuzzy Match

Fuzzy match a song and return LRC and plain text lyrics directly.

GET/v1/lrclib/get

Query Parameters

Both track_name and artist_name must be provided.

Parameter	Type	Required	Description
track_name	string	Yes	Track name
artist_name	string	Yes	Artist name
album_name	string	No	Album title

Response Schema

Returns 200 status code on success with the following structure:

type LrcLibGetResponse = LrclibSongItem;

• Response type is a single LrclibSongItem Model object.

Example Response

{
  "id": 269710089745311,
  "name": "ME!",
  "trackName": "ME!",
  "artistName": "Brendon Urie",
  "albumName": "Lover",
  "duration": 185.8,
  "instrumental": false,
  "plainLyrics": "I promise that you'll never find another like me\nI know that I'm a handful, baby, uh...",
  "syncedLyrics": "[00:00.11] I promise that you'll never find another like me\n[00:03.47] I know that I'm a handful, baby, uh..."
}

---

Get Lyric by ID

Get full lyrics using the id returned from search endpoints.

GET/v1/lrclib/get/{id}

Path Parameters

Parameter	Type	Required	Description
id	number	Yes	ID obtained from search endpoint

Response Schema

Returns 200 status code on success with the following structure:

type LrcLibGetByIdResponse = LrclibSongItem;

• Response type is a LrclibSongItem Model object for the specified ID.

Example Response

{
  "id": 269710089745311,
  "name": "ME!",
  "trackName": "ME!",
  "artistName": "Brendon Urie",
  "albumName": "Lover",
  "duration": 185.8,
  "instrumental": false,
  "plainLyrics": "I promise that you'll never find another like me\nI know that I'm a handful, baby, uh...",
  "syncedLyrics": "[00:00.11] I promise that you'll never find another like me\n[00:03.47] I know that I'm a handful, baby, uh..."
}