Lyrics

Music Assistant shows lyrics in the Now Playing view when they are available for the playing track; there is nothing to configure by default. This page explains where lyrics come from and how to fix wrong ones.

Two kinds of lyrics are available:

• Synchronized lyrics (.lrc format with timestamps)
• Unsynchronized lyrics (plain text)

Lyrics Sources

Music Assistant currently has two dedicated lyrics metadata providers. They run in addition to any lyrics delivered by the music source itself (Tidal, local tags, .lrc files, etc.) and are skipped when a track already has lyrics. If both providers are enabled, LRCLIB runs first and Genius fills in only when LRCLIB returned nothing. The following lists all lyric sources in order of preference:

1. Embedded lyrics in the audio file’s tags.
2. .lrc file with the same name as the audio file (the format produced by tools such as LRCGET).
3. The track’s own music provider, when it exposes lyrics natively (e.g. some streaming providers).
4. LRCLIB — synchronized is preferred but there is an unsynchronized falllback.
5. Genius Lyrics (optional) — unsynchronized only, matched on title and artist.

A background lookup is started as soon as a track enters the queue, so lyrics are usually available by the time the song starts.

How lyrics are fetched

For all music sources, if one or more lyric metadata providers are available then lyrics will be attempted to be obtained according to the following rules (note that it is possible that matching lyrics can’t be found)

• First play of a track: As soon as the track is queued, Music Assistant starts a lyrics lookup in the background. Because metadata updates are throttled to one every ~30 seconds, lyrics usually won’t appear during that first playback — they’ll be in place the next time the track is played
• Opening the Now Playing view: Music Assistant returns whatever is already stored for the track. For tracks playing directly from a source (i.e. not in your library), if nothing is stored it will try the track’s own music provider first (e.g. Tidal) and then fall back to the lyrics metadata providers on demand
• Periodic refresh: Stored metadata, including lyrics, is considered fresh for 90 days. After that, the next play triggers a fresh lookup
• Manual refresh: Selecting Update Metadata from a track’s menu bypasses the 90-day check and re-runs the lookup immediately

Tidal has native lyrics support, but due to its API lyrics are only fetched as part of a full track lookup, which happens when you open a track’s info page or play it. You may need to refresh the item and play again before lyrics appear.

Two lyrics providers

LRCLIB

Enabled by default and the primary source for synchronized lyrics from lrclib.net. Matching requires track name, artist, album and duration within 2 seconds. It returns synced lyrics when available, otherwise falls back to plain lyrics.

LRCLIB is throttled to one request per 30 seconds against the public API, so a newly added library will populate gradually. For faster lookups across a large library, a self-hosted LRCLIB instance can be used by pointing Music Assistant at the custom endpoint via the provider’s “API URL” setting.

Genius Lyrics

An optional fallback for unsynchronized lyrics and is a fallback source for plain (unsynchronized) lyrics, scraped from genius.com. Matching is on title and artist only — this can return results for more tracks but risks incorrect versions for ambiguously-titled songs.

Genius Lyrics is enabled from Settings → Metadata Providers → Add a metadata provider.

Replacing wrong or stale lyrics

Once lyrics are stored on a track, the standard “Update metadata” action will not replace them as both LRCLIB and Genius skip tracks that already have lyrics.

Therefore, to replace the existing lyrics:

• For local files: edit the embedded lyrics tag and then the next library scan will pick it up. If a .lrc file is edited, then either also touch the audio file or select Refresh Item on the track
• For all others: use Refresh Item on the track as it re-fetches the track from its provider and re-runs the lyrics lookup