Module lyrics

Lyrics that are already there: in the tags, or in an .lrc beside the file.

Nothing here touches the network. Reading what a library already holds is the first half of the job and the cheap one — the parsers walk past USLT, LYRICS and ©lyr today, and a .lrc sitting next to a track is a text file anyone can open. Fetching what is missing is another matter entirely: it needs a network, a source whose terms allow it, and an explicit choice, because lyrics are the composition’s copyright and owning a FLAC grants no rights in it. See docs/design/lyrics.md.

Where they live follows the rule the rest of the catalog follows. Tag lyrics are already in it, because raw tags are kept per file; a sidecar is not in the file, so pretending it were a tag would make the catalog lie about what the file says. The catalog therefore stores the sidecar’s path, and the text is read from it when somebody asks — it is one small file, sitting right next to the music it belongs to.

Timeline indexes the parsed timings for terminal and graphical players. The player supplies its decoded-track position; this module does not run a playback clock or attach lyrics to audio packets.

Structs

Cue

All lyric lines beginning at one moment in a track.

CurrentTrack

Current catalog evidence for the audio to which lyrics belong.

Line

One line, with the moment it is sung when the file says so.

Lyrics

The lyrics of one track, as read.

ParseLimitExceeded

A complete lyrics result would exceed the permitted UTF-8 text budget.

Timeline

A chronological index of a track’s synchronized lyrics.

Enums

ReadError

Why a complete, current lyrics answer cannot be supplied.

Source

Where a track’s lyrics were found.

Constants

EXTENSION

Extension of a lyrics file beside a track.

Functions

from_tag

The lyrics a tag carries, if it carries any.

has_source

Lightweight presence hint for catalog presentation, without opening audio or sidecar text.

is_sidecar

true when a file name is a lyrics sidecar, whatever its case.

parse

Reads lyrics text, timed or not.

parse_complete

Parses lyrics completely, refusing excessive timestamp expansion.

read

Reads a sidecar, bounded, and never fatally.

read_current

Read a complete local lyrics answer after confirming its current audio identity.

read_local

Read complete lyrics for a local audio path without catalog evidence.

sidecar_of

Where the sidecar of an audio file would be: the same name, .lrc.