API Reference

Complete reference for every public class, method, and data model in LibreLyrics.

`LibreLyrics`

Main orchestrator. Loads plugins, manages configuration, and dispatches URL-based fetch requests to the matching provider.

class LibreLyrics(config=None, verbose=False)

Param	Type	Description
`config`	`dict \| None`	Optional pre-loaded configuration dictionary. If `None`, loads from the default config file.
`verbose`	`bool`	Enable verbose (DEBUG-level) logging.

fetch(url: str) → LyricsResponse

Fetch lyrics for a single track URL. Finds the first matching plugin and returns the result with automatic retry.

Param	Type	Description
`url`	`str`	Track URL to fetch lyrics from.

Raises: NoMatchingModuleError, LyricsNotFound

fetch_batch(url: str) → list[LyricsResponse]

Fetch lyrics for an album or playlist URL. Automatically dispatches to the appropriate batch method based on declared capabilities.

Param	Type	Description
`url`	`str`	Album or playlist URL.

Raises: NoMatchingModuleError

list_plugins() → list[type[LyricsModule]]

Return a list of all loaded plugin classes.

config : dict (property)

The raw configuration dictionary (read-only access).

`LyricsResponse`

Standardised response dataclass returned by every plugin's fetch(). All timing values are in milliseconds.

Field	Type	Description
`title`	`str`	Track title.
`artist`	`str`	Artist name.
`lyrics`	`list[LyricsLine]`	List of lyric lines.
`source`	`str`	Plugin name that provided the lyrics.
`album`	`str \| None`	Album name, if available.
`synced`	`bool`	Whether lyrics have line-level timing.
`rich_synced`	`bool`	Whether lyrics have word-level timing.
`duration_ms`	`int \| None`	Track duration in milliseconds.
`metadata`	`dict`	Arbitrary extra metadata (track_number, explicit, etc.).

to_lrc(include_metadata=True, enhanced=False) → str

Format lyrics as LRC file content.

Param	Type	Description
`include_metadata`	`bool`	Include [ti:], [ar:], [al:] tags.
`enhanced`	`bool`	Use Enhanced LRC with word-level timestamps.

Example Output (Standard LRC)

[ti:Bohemian Rhapsody]
[al:A Night at the Opera]
[ar:Queen]
[length:05:54.83]
[00:00.00] Is this the real life?
[00:04.10] Is this just fantasy?

`LyricsLine`

A single line of lyrics. Frozen dataclass.

Field	Type	Description
`text`	`str`	Line text (the actual lyric words).
`start_ms`	`int \| None`	Start timestamp in ms. None for unsynced.
`end_ms`	`int \| None`	End timestamp in ms. Available for rich synced lyrics.
`words`	`tuple[LyricsWord, ...] \| None`	Word-level timing for karaoke-style display.

`LyricsWord`

A single word with timing. Frozen dataclass.

Field	Type	Description
`word`	`str`	The word text.
`start_ms`	`int`	Start timestamp in ms.
`end_ms`	`int`	End timestamp in ms.

`LyricsType`

Enum of lyrics formats a module can provide.

Member	Description
`PLAIN`	Unsynced lyrics — just text, no timestamps.
`SYNCED`	Line-synced lyrics — one timestamp per line.
`RICH_SYNCED`	Word-synced lyrics — timestamp per word, karaoke-style.

`ModuleCapability`

Flag enum of capabilities a module can declare. Used by the orchestrator for dispatch.

Flag	Description
`SINGLE_TRACK`	Can fetch lyrics for a single track.
`ALBUM`	Can fetch all tracks in an album.
`PLAYLIST`	Can fetch all tracks in a playlist.
`SEARCH`	Can search for tracks by metadata.

`ConfigManager`

Manages loading, saving, merging and plugin-specific config slicing.

class ConfigManager(config=None, config_path=None)

Param	Type	Description
`config`	`dict \| None`	Pre-loaded config. If None, loads from disk.
`config_path`	`Path \| None`	Custom config file path. Defaults to platform path.

get(key, default=None) → Any

Get a config value by key.

set(key, value)

Set a config value.

save()

Write the current config to disk (creates parent dirs automatically).

for_plugin(plugin_cls) → dict

Return the merged config for a specific plugin (plugin defaults + stored overrides).

merge_plugin_defaults(plugins) → bool

Merge default_config() from every loaded plugin into the plugins section. Returns True if something changed.

raw : dict (property)

Direct access to the underlying config dictionary.

Standalone Helpers

get_config_path() → Path

Returns the platform-specific config file path:
Windows: %APPDATA%\librelyrics\config.json
Linux/macOS: ~/.config/librelyrics/config.json

get_default_config() → dict

Return the default config dictionary (see Configuration for all keys).

Exceptions

All exceptions inherit from LibreLyricsError.

LibreLyricsError
├── PluginError
│   ├── PluginLoadError
│   ├── PluginAPIVersionError
│   └── NoMatchingModuleError
├── ConfigurationError
│   └── CorruptedConfig
└── ProviderError
    ├── NotValidSp_Dc
    ├── NoSongPlaying
    ├── TOTPGenerationException
    ├── LyricsNotFound
    └── RateLimitError

Exception	When Raised
`PluginLoadError`	A plugin module failed to import.
`PluginAPIVersionError`	Plugin declares an incompatible API version.
`NoMatchingModuleError`	No plugin regex matches the provided URL.
`ConfigurationError`	Config is invalid or missing required values.
`CorruptedConfig`	Config JSON cannot be parsed.
`LyricsNotFound`	Provider has no lyrics for the requested track.
`RateLimitError`	HTTP 429 — triggers automatic retry back-off.

Helper Functions

Standalone utility functions in librelyrics.core.

save_lyrics(lyrics: str, path: str)

Write lyrics content to a file, creating parent directories automatically.

download_lyrics(librelyrics, url, folder=None) → tuple[list[str], list[str]]

Download lyrics for a URL (track, album, or playlist). Returns (successful_tracks, failed_tracks).

rename_using_format(template: str, data: dict) → str

Format a filename template using variable placeholders. Invalid filename characters are stripped.