Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/foedusprogramme/gramophone/llms.txt

Use this file to discover all available pages before exploring further.

Gramophone includes a full-featured synced lyrics engine capable of parsing multiple lyric formats, resolving word-level timing, and displaying translations alongside the original text.

​
Supported formats

LRC

Standard, extended (karaoke), and compressed LRC files.

TTML

Timed Text Markup Language, as used by Apple Music. Supports word- and syllable-level synchronization.

SRT

SubRip subtitle format.

​
Where lyrics come from

Gramophone looks for lyrics in two places, checked in this order:
1

Embedded metadata

Lyrics embedded directly in the audio file. Gramophone reads:
  • ID3 tags: USLT (unsynced), SYLT / SLT (synced), and USLT in MP4 files
  • Vorbis comments: the LYRICS key (used in FLAC, OGG, and Opus files)
When multiple lyric entries are present, synced lyrics are preferred over unsynced, and word-level lyrics are preferred over line-level.
2

Sidecar files

A file with the same name as the audio file but a different extension, located in the same directory. Gramophone checks for .ttml, .srt, and .lrc files in that order.For example, for ~/Music/song.flac, Gramophone will look for:
  • ~/Music/song.ttml
  • ~/Music/song.srt
  • ~/Music/song.lrc

​
LRC format details

The LRC parser is designed to handle a wide range of real-world files, including many edge cases not covered by any single specification.
The standard format: each line is prefixed with a [mm:ss.xx] timestamp.
[00:11.22] Hello I am lyric
[00:15.33] This is another line
A single lyric line associated with multiple timestamps. Used when the same line repeats at different points in the song.
[00:11.22][00:15.33] Hello I am lyric
Word-level timestamps embedded inside the line using angle brackets. Each <mm:ss.xx> marker indicates when the following word should be highlighted.
[00:11.22] <00:11.22> hello <00:12.85> i am <00:13.23> lyric
Extended LRC without a line-level sync point is also supported:
<00:11.22> hello <00:12.85> i am <00:13.23> lyric
Lines can be prefixed with v1:, v2:, or enclosed in [bg: ] to indicate different speakers or background vocals. This extension is used by some iTunes-sourced LRC files.
[00:11.22] v1: Lead vocal line
[00:11.22] v2: Harmony vocal line
[00:15.33] [bg: Background vocal]
The standard [offset:] header tag is supported. When present, all line timestamps in the file are shifted by the specified number of milliseconds.
[offset:200]
[00:11.22] This line plays at 00:11.42
Gramophone accepts several timestamp formats that appear in the wild:
FormatExample
[mm:ss][00:11]
[mm:ss.xx][00:11.22]
[mm:ss.xxx][00:11.222]
[mm:ss:xx][00:11:22]
[mm:ss:xxx][00:11:222]
Lines between two consecutive sync points are treated as the lyric text for the earlier timestamp. This allows reading multi-line lyric blocks that are technically not part of any published specification.
Two translation conventions are supported:
  • Type 1: Two separate LRC files (e.g. Japanese and English) concatenated into one file. Each file may have its own [offset:] tag.
  • Type 2: The translated line placed directly below the original line, sharing a timestamp.

​
TTML format

Gramophone parses TTML (Timed Text Markup Language) as used by Apple Music. TTML supports word- and syllable-level synchronization with speaker attribution, enabling the same dual-speaker and background vocal distinctions as the iTunes LRC extension.

​
SRT format

Standard SubRip subtitle files (.srt) are supported. These provide line-level timing without word-level synchronization.

​
Karaoke synchronization

When word-level timing is available (extended LRC or TTML), Gramophone highlights individual words as they are sung, giving a karaoke-style display. The active word progresses smoothly through the line in sync with the audio.

​
Home screen lyric widget

A home screen widget is available that shows the current lyric line while music is playing. Add it from your launcher’s widget picker.

​
Lyrics settings

Lyric display can be configured under Settings > Lyrics.

Build docs developers (and LLMs) love

Get started for freeTalk to us