Getting Started

Install LibreLyrics and fetch your first lyrics in under a minute.

Installation

From PyPI

pip install librelyrics

From Source

git clone https://github.com/akashrchandran/librelyrics.git
cd librelyrics
pip install -e .

With Dev Dependencies

pip install -e ".[dev]"

Requirements — Python 3.10 or later is required.

CLI Usage

After installation the librelyrics command is available globally.

Fetch Lyrics for a Track

librelyrics https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT

By default lyrics are saved to the configured download directory. Use flags to customise:

# Specify output directory
librelyrics https://open.spotify.com/track/... -d ./lyrics

# Overwrite existing files
librelyrics https://open.spotify.com/track/... --force

# Enable verbose output
librelyrics https://open.spotify.com/track/... --verbose

Album & Playlist Batch Downloads

# Download all lyrics in an album
librelyrics https://open.spotify.com/album/...

# Download all lyrics in a playlist
librelyrics https://open.spotify.com/playlist/...

A spinner shows the current track being downloaded and a summary is shown at the end.

Configuration Management

# Show current config
librelyrics config show

# Open interactive editor
librelyrics config edit

# Set a specific value
librelyrics config set lyrics_type synced

# Reset to defaults
librelyrics config reset

# Reveal config file location
librelyrics config path

Plugin Management

# List installed plugins
librelyrics plugin list

# Install a plugin from PyPI
librelyrics plugin install librelyrics-genius

# Remove a plugin
librelyrics plugin remove librelyrics-genius

Using as a Library

Basic Fetch

from librelyrics import LibreLyrics, LyricsType

lib = LibreLyrics()

response = lib.fetch(
    "https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT",
    lyrics_type=LyricsType.SYNCED,
)

# Print synced lines
for line in response.lines:
    print(f"[{line.start_time_ms}] {line.words}")

Export to LRC Format

lrc_text = response.to_lrc()
print(lrc_text)

# Save to file
with open("song.lrc", "w") as f:
    f.write(lrc_text)

Batch Fetch (Album / Playlist)

responses = lib.fetch_batch(
    "https://open.spotify.com/album/...",
    lyrics_type=LyricsType.SYNCED,
)

for r in responses:
    print(f"{r.track_name} — {len(r.lines)} lines")

List Available Plugins

plugins = lib.list_plugins()
for name, meta in plugins.items():
    print(f"{meta.name} v{meta.version} — {meta.description}")

Next Steps

API Reference →

Full documentation of all classes, methods, and data models.

Configuration →

All available config keys and how to customise them.

Build a Plugin →

Create your own lyrics provider and publish it to PyPI.