Skip to content
rmpc
Docs Changelog FAQ
This page is for the development version of rmpc. Make sure your version matches the selected documentation.

Lyrics

Lyrics

Section titled “Lyrics”

Rmpc supports displaying synchronized lyrics in the Lyrics pane. Other lyrics formats are not supported. The lyrics_dir must be configured for the resolution to work. All lrc files must be on the client side.

LRC file format

Section titled “LRC file format”

LRC files are text files with a specific structure:

[ar:Artist Name]
[ti:Song Title]
[al:Album Name]
[length:03:45.12]
[offset:1000]


[00:12.34]First line of lyrics
[00:15.67]Second line of lyrics
[01:23.45]Another line...

What gets parsed and what gets ignored

Section titled “What gets parsed and what gets ignored”

Metadata tags (at the beginning of file):

  • [ar:Artist Name] - Artist name (required for matching)
  • [ti:Song Title] - Song title (required for matching)
  • [al:Album Name] - Album name (optional)
  • [au:Author Name] - Author/lyricist name (optional)
  • [length:3:45] - Song length (helps with matching)
  • [offset:-500] - Time adjustment in milliseconds

Timestamp lines (lyrics with timing):

  • [00:12.34]First line of lyrics
  • [1:23.45]Second line (single digit minutes work)
  • [00:30.5]Third line (different decimal places work)
  • [01:30.00][02:30.00]Repeated chorus (multiple timestamps per line)
  • [00:10.00][Intro] Welcome (non-timestamp content like [Intro] becomes part of lyrics)

What gets ignored:

  • # Comments like this
  • [custom:unknown tags]
  • [tool:editor name]
  • [abc:30.00]Invalid timestamp (invalid minutes/seconds)
  • Lines without brackets
  • [unclosed bracket
  • Empty lines

Lrc file resolution

Section titled “Lrc file resolution”

Lrc files are resolved by rmpc via two methods (in order):

  • Same path as the song file, except with the .lrc file extension
  • By indexing all the .lrc files in the lyrics_dir

Lyrics index

Section titled “Lyrics index”

Rmpc will create an index of all .lrc files in your lyrics_dir on startup.

How songs match to LRC files:

  • Artist and title must match exactly (case insensitive)
  • Album is optional - if present in both, it must match
  • If LRC has a length tag, it must be within ±5 seconds of song length

Unknown tags are ignored: [by:Creator], [tool:Editor], [version:1.0], etc.

Same path as the song file

Section titled “Same path as the song file”

Following examples assume that your MPD’s music directory is set to /home/user/Music.

  1. If your lyrics_dir is set to the same path as MPD’s music directory /home/user/Music/artist/album/song.flac will try to resolve /home/user/Music/artist/album/song.lrc

  2. If your lyrics_dir is set to a different path, ie. /home/user/.lyrics /home/user/Music/artist/album/song.flac will try to resolve /home/user/.lyrics/artist/album/song.lrc

Example LRC file

Section titled “Example LRC file”
# This is a comment - ignored
[ti:My Song]
[ar:Artist Name]
[al:Album Name]
[length:3:45]
[offset:-500]
[custom:unknown tag]  # ignored


[00:00.00]Intro starts here
[00:12.34]First verse line
[00:15.67]Second verse line
[00:30.00][01:30.00]This chorus repeats twice
[00:45.5]Different decimal format works
[01:00.00]Lyrics with émojis 🎵 work fine
[01:20.00]Text with [brackets] works too
[01:30.00][Intro] This text becomes part of lyrics
[01:35.00]
[abc:30.00]Invalid timestamp - ignored
This line has no brackets - ignored
[02:00.00]Back to lyrics

What rmpc sees in this example:

  • Song info: “My Song” by “Artist Name” from “Album Name”
  • Timing: All timestamps shifted 500ms earlier (offset)
  • Lyrics: 9 lines with valid timestamps (invalid lines skipped)
  • Ignored: Comments, unknown tags, invalid timestamps

Important Notes for Users

Section titled “Important Notes for Users”

What works:

  • Most LRC files from any source work without modification
  • Files with some parsing errors still work - only invalid lines are skipped
  • Large timestamp values are supported (up to 99:59.99)

For best results:

  • Use standard [MM:SS.xx] format for timestamps
  • Include [ar:] (artist) and [ti:] (title) tags for proper song matching
  • Files with no valid timestamps will appear empty in the lyrics pane
  • Only consecutive timestamps at the start of a line are parsed - everything after the first non-timestamp tag becomes lyrics content

Troubleshooting:

  • If lyrics don’t show up, check that artist/title metadata matches your song
  • Missing or mismatched metadata prevents automatic matching
  • Lines like [00:10.00][tag:value][00:12.00]text will create one line at 10.00s with content [tag:value][00:12.00]text - only consecutive timestamps are parsed