API Reference Documentation

Welcome to the TTMLLIB public API interface. Our API offers high-speed queries to access synchronized lyrics records, complete with word-level timings and standard LRC fallbacks.

Base URL: https://ttmllib.xyz

GET

/api/get

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

Note: If the lyrics are not found in the local cache database, this API will query external upstream sources (LRCLIB), index the result in our database, and return the record.

Field	Required	Type	Description
track_name	true	string	Title of the track
artist_name	true	string	Name of the artist
album_name	true	string	Name of the album
duration	true	number	Track's duration in seconds (accepts ±2s variance)

Example Response

200 OK:
{
  "id": 1,
  "trackName": "Cigarety",
  "artistName": "Sara Rikas, Matej Turcer",
  "albumName": "Ja, Sára",
  "duration": 222,
  "instrumental": false,
  "plainLyrics": "Cigarety a milión slov\nAh, my favorite show...",
  "syncedLyrics": "[00:17.52] Cigarety a milión slov\n[00:21.90] a\n[00:22.12] milión...",
  "lyricsTtml": "<tt>...</tt>"
}

GET

/api/get-cached

Identical parameter rules to /api/get, except that it will ONLY query the internal TTMLLIB database cache. It will never run external network queries.

Example Request

GET /api/get-cached?track_name=Cigarety&artist_name=Sara+Rikas%2C+Matej+Turcer&album_name=Ja%2C+S%C3%A1ra&duration=222

GET

/api/get/[id]

Retrieve a specific lyrics record using its unique database ID.

Example Request

GET /api/get/1

GET

/api/search

Search for lyrics records using keywords. Returns an array of up to 20 matching results.

Requirement: At least one of the parameters q or track_name must be provided.

Field	Required	Type	Description
q	conditional	string	Keyword matching title, artist name, or album name
track_name	conditional	string	Search for keywords inside the track title
artist_name	false	string	Filter results by artist name
album_name	false	string	Filter results by album name

Example Response

200 OK:
[
  {
    "id": 1,
    "trackName": "Cigarety",
    "artistName": "Sara Rikas, Matej Turcer",
    "albumName": "Ja, Sára",
    "duration": 222,
    "instrumental": false,
    "plainLyrics": "Cigarety a milión slov...",
    "syncedLyrics": "[00:17.52] Cigarety a milión slov...",
    "lyricsTtml": "<tt>...</tt>"
  }
]