Multilrc / Developer reference

API documentation

Everything you need to integrate, from your first request to individual word timestamps.

On this page

Overview#

Multilrc retrieves song lyrics from multiple sources and normalizes the result into one JSON schema. Just send a track title and artist. Missing metadata for Octave is filled in through search.

The default order is Octave → Musixmatch → Genius → lyrics.lol. The first matching, nonempty result ends the lookup. If a source is unavailable, unconfigured, or has no matching lyrics, the adapter tries the next one.

Request and response bodies use UTF-8 JSON. Send the Content-Type: application/json header. All timestamps are measured in seconds from the start of the track.

The documentation does not prescribe a base address. In cURL and Python, API_BASE_URL is your deployment’s base address, without a trailing slash. Browser examples use relative paths on the same origin.

The current application does not require a client API key. If your deployment uses external authentication, its owner configures it separately. The Genius token is a server setting and is never included in a user’s lyrics request.

First request#

POST/v1/lyrics

The minimal request has two fields. Set API_BASE_URL in your environment first.

cURL · minimal request
curl "$API_BASE_URL/v1/lyrics" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Operation Cyclone",
    "artist": "Ghais Guevara"
  }'

A successful request returns 200 and a lyrics object. Synchronization availability depends on the source and track. See the response schema for the complete contract.

Request parameters#

FieldTypeDescription
titleREQUIREDstringTrack title. Between 1 and 1000 characters after trimming leading and trailing whitespace.
artistREQUIREDstringArtist name. The same length constraints as the title apply.
albumstring | nullAlbum name. A nonempty string of up to 1000 characters. Helps rank matching candidates.
durationnumber | nullDuration in seconds. Must be positive and finite; fractional values are accepted.
octave_idstring | nullOctave track ID: a nonempty string of up to 1000 characters. Not a universal ID for other sources.

Fields not marked “required” can be omitted or set to null. Empty strings, unknown fields, and nonpositive durations result in 422.

A request with complete metadata

JSON · request body
{
  "title": "Operation Cyclone",
  "artist": "Ghais Guevara",
  "album": "BlackBolshevik",
  "duration": 211,
  "octave_id": "1415926982"
}

When octave_id, album, and duration are all known, OctaveProvider skips metadata search. The title and artist are still required. If some metadata is missing, the provider searches for it.

Keep the album when you know it. It helps matching and may affect synchronization availability in Octave. If the user omits it, the adapter tries to find it through search.

When an octave_id is supplied, the search never combines it with metadata from a different ID. Album and duration help rank matching candidates, but do not bypass title and artist checks.

Response schema#

This complete structural example uses fictional lyrics. All providers return the same set of fields.

200 · application/json
{
  "provider": "octave",
  "track": {
    "title": "Example",
    "artist": "Artist",
    "album": "Album",
    "duration": 200.0,
    "source_id": "123"
  },
  "plain_lyrics": "Hello world",
  "synced_lyrics": "[00:01.00]Hello world",
  "lines": [
    {"start": 1.0, "end": 2.0, "text": "Hello world"}
  ],
  "words": [
    {"start": 1.0, "end": 1.4, "text": "Hello"},
    {"start": 1.4, "end": 2.0, "text": "world"}
  ],
  "source_url": null,
  "attempts": [
    {"provider": "octave", "status": "found", "message": null}
  ]
}
FieldValue
providerThe source: octave, musixmatch, genius, or lyrics_lol.
trackMetadata for the track that was actually selected.
plain_lyricsNonempty lyrics without timestamps. Verse and chorus headings may be preserved.
synced_lyricsThe original LRC, or null when unavailable.
linesAn array of timed lines; [] when unavailable.
wordsAn array of timed words; [] if the source did not provide them.
source_urlA link to the song page, or null. Octave responses may not include a link.
attemptsPrevious attempts and the successful attempt, in lookup order.

The track object

title and artist are strings. album and source_id are strings or null. duration is a positive number of seconds or null. A source_id is meaningful only within its provider.

Not every source reports the album and duration, so these fields may be null even when lyrics are found. The current model has one artist field; a recording’s full artist credits may not be represented.

Synchronization#

Use plain_lyrics as your baseline and enable synchronization when the corresponding data is present. Lines and words are represented separately.

Line and word objects

FieldTypeMeaning
startnumberNonnegative start time in seconds from the beginning of the track.
endnumber | nullEnd time, if reported by the source. It is not always available for LRC lines.
textstringThe text of a line or an individual word.

synced_lyrics preserves the LRC format. When timestamps are available, lines exposes them as numbers without requiring your own LRC parser. Word timings from Octave are included in words when provided by the source.

Plain lyrics also end the lookup. If the first successful source returns lyrics without timestamps, the adapter does not continue just to find synchronization. An empty words=[] does not mean that lines is also empty.

Errors and statuses#

HTTPMeaningWhat to do
200Matching, nonempty lyrics were found.Read the result and check synchronization availability.
404No lyrics found. Some sources may be unconfigured.Check the title, artist, and version labels.
503No lyrics received, and at least one source had a network, timeout, or parsing failure.Inspect attempts and retry later for temporary failures.
422Invalid request body.Correct the fields listed in detail.

404 and 503 responses

Both responses have the same shape: an error field and an attempts array. For 404, the error is not_found; for 503, it is unavailable.

503 · diagnostic example
{
  "error": "unavailable",
  "attempts": [
    {
      "provider": "octave",
      "status": "unavailable",
      "message": "Provider timed out"
    },
    {
      "provider": "musixmatch",
      "status": "not_found",
      "message": null
    },
    {
      "provider": "genius",
      "status": "not_configured",
      "message": "Genius access token is not configured"
    },
    {
      "provider": "lyrics_lol",
      "status": "not_found",
      "message": null
    }
  ]
}

Attempt statuses

  • found — the source returned lyrics.
  • not_found — no matching lyrics were retrieved.
  • not_configured — a required source setting is missing.
  • unavailable — a network failure, source refusal, or timeout.
  • invalid_response — the upstream response has an unexpected structure.

Each attempt contains provider, status, and message, which is an explanation or null. The array need not have four entries: success or the overall timeout can end the chain earlier.

422 responses

422 · validation example
{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "artist"],
      "msg": "Field required",
      "input": {"title": "Example"}
    }
  ]
}

Do not treat every failed request as a missing song. A 503 means that at least one source could not be checked normally. Unexpected internal application errors are not disguised as 404 responses.

Sources and matching#

  1. Octave. Searches for missing metadata, then requests lyrics. May return LRC and word timings.
  2. Musixmatch. Uses the desktop token flow. Restricted responses are not returned as complete lyrics.
  3. Genius. Retrieves lyrics through LyricsGenius. Skipped when no server access token is configured.
  4. lyrics.lol. Searches using a cleaned title, then extracts lyrics from the song page.

How matching works

Title and artist comparisons normalize Unicode, letter case, whitespace, and punctuation. Album and duration rank otherwise matching candidates. Version labels such as Original, Live, and Remix are preserved.

Matching is currently strict: a parenthesized translation, an abbreviated title, or feat. in the title can prevent a match. If lyrics are missing, check the catalog spelling. Irrelevant search results are never accepted as the requested song.

Retries and limits

A direct request is tried first. A connection failure, block, temporary error, or unusable response allows one retry through the configured server proxy. A valid “not found” result does not itself trigger a proxy retry.

The default network timeout is 10 seconds, the per-provider budget is 20 seconds, and the overall budget is 80 seconds. Give your HTTP client a margin above the overall budget; the examples use 90 seconds. Deployment settings may differ.

Lyrics and synchronization availability vary by track. External APIs and HTML can change. An upstream success status is checked for structure, track identity, and nonempty lyrics before it is accepted.

Integration examples#

JavaScript · same origin

Use a relative path in the browser. A timer limits the wait; HTTP errors are handled separately from network exceptions.

JavaScript · fetch
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 90_000);

try {
  const response = await fetch('/v1/lyrics', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      title: 'Operation Cyclone',
      artist: 'Ghais Guevara'
    }),
    signal: controller.signal
  });
  const result = await response.json();

  if (!response.ok) {
    console.error(response.status, result);
  } else {
    console.log(result.plain_lyrics);
    console.log(result.lines);
  }
} catch (error) {
  console.error('Request failed', error);
} finally {
  clearTimeout(timer);
}

For requests from another origin, configure CORS in your deployment. The current application does not enable CORS automatically.

Python · HTTP client

Install httpx with uv add httpx. Set API_BASE_URL in your environment.

Python · httpx
import os
import httpx

base_url = os.environ["API_BASE_URL"].rstrip("/")

with httpx.Client(base_url=base_url, timeout=90) as client:
    response = client.post(
        "/v1/lyrics",
        json={"title": "Operation Cyclone", "artist": "Ghais Guevara"},
    )
    data = response.json()

    if response.is_success:
        print(data["plain_lyrics"])
    else:
        print(response.status_code, data)

HTTPX raises httpx.RequestError for network failures. Handle it separately if your integration needs to recover from temporary service unavailability.

Python library#

If you use the project source or a locally installed Multilrc package, call the adapter directly without HTTP. Set up the project environment with uv sync --locked.

Python · async client
import asyncio
from multilrc import LyricsClient, LookupFailed, TrackQuery


async def main():
    async with LyricsClient() as client:
        try:
            result = await client.get_lyrics(
                TrackQuery(
                    title="Operation Cyclone",
                    artist="Ghais Guevara",
                )
            )
        except LookupFailed as error:
            print(error.status_code)
            print([a.model_dump() for a in error.attempts])
        else:
            print(result.provider)
            print(result.plain_lyrics)
            print(result.model_dump(mode="json"))


asyncio.run(main())

Reuse a single LyricsClient for multiple lookups. The context manager closes connections and provider resources. If you manage its lifecycle manually, call await client.aclose().

LookupFailed exposes status_code, error, and attempts. Invalid TrackQuery parameters raise a Pydantic validation error. Cancellation from the calling task is propagated.

Configuration#

This section is for service owners and Python library users. Configure settings through environment variables, .env, or Settings. Environment variables take precedence over .env.

VariablePurpose
MULTILRC_GENIUS_ACCESS_TOKENServer-side Genius access token. This source is skipped when no token is configured.
MULTILRC_PROXY_URLProxy address for retries. An empty string disables proxy fallback.
MULTILRC_REQUEST_TIMEOUTHTTP client network timeout; 10 seconds by default.
MULTILRC_PROVIDER_TIMEOUTPer-provider time budget; 20 seconds by default.
MULTILRC_TOTAL_TIMEOUTOverall lookup budget; 80 seconds by default.
MULTILRC_MAX_CANDIDATESMaximum candidate count: 5 by default, from 1 to 20.
MULTILRC_PROVIDERSA JSON array of sources in lookup order. Names match the provider field.

All timeouts must be positive, finite numbers. The provider list cannot be empty or contain duplicates or unknown names. It is a server setting, not a POST /v1/lyrics parameter.

Python · custom settings
import asyncio
from multilrc import LyricsClient, Settings, TrackQuery


async def main():
    settings = Settings(
        proxy_url=None,
        providers=("octave", "lyrics_lol"),
        provider_timeout=25,
        total_timeout=60,
    )
    async with LyricsClient(settings=settings) as client:
        result = await client.get_lyrics(
            TrackQuery(title="Operation Cyclone", artist="Ghais Guevara")
        )
        print(result.plain_lyrics)


asyncio.run(main())

The default configuration includes a local proxy for retries. If it is not available, set your own using MULTILRC_PROXY_URL or disable it. Direct requests still work without a proxy. System HTTP_PROXY and HTTPS_PROXY variables do not change the shared HTTPX transport’s routing.

Service health#

GET/health
200 · process health
{
  "status": "ok",
  "version": "0.1.0"
}

This checks the application process. It does not contact upstream sources or guarantee that a specific track is currently available.

Machine-readable schema

GET /openapi.json ↗ returns the HTTP API’s OpenAPI schema, including request and response models. Use it to generate clients and validate contracts.

Back to quick start