LibreLyrics

Features

• Synced lyrics — Line-by-line timestamps (LRC format)
• Rich synced lyrics — Word-by-word karaoke-style timing (Enhanced LRC)
• Plugin architecture — External plugins via entry points
• Metadata search — Fetch by artist and title, with a user-defined source list
• Batch downloads — Fetch lyrics for entire albums or playlists
• CLI & Library — Use from the command line or import as a Python library
• Interactive config — Menu-driven configuration editor

Installation

pip install librelyrics

Plugins

LibreLyrics is a plugin-based system. The core package does not include any lyrics sources. Install plugin packages separately.

Plugins must declare API version 2 (LIBRELYRICS_API_VERSION = 2) and a stable META.id (lower-case letters and digits only). Version 1 plugins do not load. META.name is the display name and the key under plugins in config.

Installing Plugins

Install plugins using pip or the built-in plugin manager:

# Using pip
pip install librelyrics-spotify

# Using the plugin manager
librelyrics plugin install librelyrics-spotify

# List installed plugins
librelyrics plugin list

Available Plugins

Plugin packages follow the naming convention librelyrics-{service}. Check the libre-lyrics organization for available plugins.

Quick Start

Command Line

# Fetch lyrics for a single track (URL plugin only when search_priority is empty)
librelyrics https://open.spotify.com/track/...

# Only the plugin that matches the URL (no search list)
librelyrics https://open.spotify.com/track/... --direct

# Resolve the URL, then fetch lyrics from a named plugin id
librelyrics https://open.spotify.com/track/... --from applemusic

# Metadata only (needs a SEARCH plugin)
librelyrics --artist "Artist" --title "Track"

# Fetch lyrics for an album
librelyrics https://open.spotify.com/album/...

# Fetch lyrics for a playlist
librelyrics https://open.spotify.com/playlist/...

# Configure settings
librelyrics config edit

# List installed plugins
librelyrics plugin list

As a Library

from librelyrics import LibreLyrics, TrackQuery

ll = LibreLyrics()

response = ll.fetch("https://open.spotify.com/track/...")
print(response.to_lrc())

response = ll.fetch_query(TrackQuery(artist="Artist", title="Track"))

Configuration

Run librelyrics config edit for an interactive configuration editor, or manually set values:

librelyrics config set download_path ./lyrics
librelyrics config set preferred_lyrics_order RICH

# Plugin-specific configuration (key is META.name in lower case, example spotify)
librelyrics config set plugins.spotify.sp_dc YOUR_SP_DC_COOKIE

Config Options

Plugin Development

LibreLyrics supports external plugins via Python entry points. Create a plugin by subclassing LyricsModule:

import re
from librelyrics.modules.base import LyricsModule, ModuleMeta, ModuleCapability

class MyPlugin(LyricsModule):
    META = ModuleMeta(
        id="myservice",
        name="MyService",
        regex=re.compile(r"myservice\.com/track/"),
        capabilities=frozenset({ModuleCapability.SINGLE_TRACK}),
    )
    LIBRELYRICS_API_VERSION = 2

    def fetch(self):
        # Your implementation here
        ...

Register your plugin in pyproject.toml:

[project.entry-points."librelyrics.plugins"]
myservice = "my_plugin_package:MyPlugin"

License

This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.