syncedlyrics

Install the syncedlyrics package using pip to get started with synchronized lyrics retrieval.

pip install syncedlyrics

The primary entry point for the library is the syncedlyrics.search() function. It accepts a search term (e.g., "[TRACK_NAME] [ARTIST_NAME]") and several optional parameters to control behavior such as language, providers, and output format.

import syncedlyrics

# Basic search
lrc = syncedlyrics.search("[TRACK_NAME] [ARTIST_NAME]")

# Search with specific options
syncedlyrics.search("search term", plain_only=True, save_path="{search_term}_1234.lrc", providers=["NetEase"])

# Get translation (original and translation separated by \n)
syncedlyrics.search("search term", lang="de")

# Get word-by-word (karaoke) enhanced lyrics if available
syncedlyrics.search("search term", enhanced=True)

The following flags are available for the syncedlyrics command line interface:

The following providers are supported for searching lyrics:

• Musixmatch
• Lrclib
• NetEase
• Megalobiz
• Genius (Note: Genius only provides plain format)

Note: Deezer and Lyricsify are currently listed as non-functional.

You can instruct search() to automatically save the retrieved lyrics to a file by providing a save_path. The path supports a {search_term} placeholder which will be replaced by the actual search string used in the function call.

Example usage with a placeholder:

import syncedlyrics
# This will save to a file named 'Bohemian_Rhapsody_Queen.lrc'
syncedlyrics.search("Bohemian Rhapsody Queen", save_path="{search_term}.lrc")

You can search for lyrics directly from the command line. By default, the CLI prefers time-synced lyrics but falls back to plaintext if no synced lyrics are found. Use --plain-only or --synced-only to restrict the search type.

syncedlyrics "SEARCH_TERM"

The search function is the core API for finding lyrics programmatically. It returns the lyrics string if found, or None if no results match the criteria.

from syncedlyrics import search

lrc = search(
    "track name",
    plain_only=False,
    synced_only=False,
    output="track.lrc",
    p="lrclib musixmatch",
    lang="en",
    enhanced=True
)

if lrc:
    print(lrc)

When using the search() function, certain parameters are exclusive to the Musixmatch provider. If you provide these parameters but the search does not use Musixmatch (or if Musixmatch fails), the behavior may be limited:

• lang: Used to request a specific language for translation along with the original lyrics.
• enhanced: Used to request word-by-word (karaoke) synced lyrics.

If lang is provided and an error occurs during the search process, the function may abort and return None because the requested language feature is provider-specific.

The format_time(time_in_seconds: float) function converts a float representing seconds into a formatted string in the style [mm:ss.xx].

from syncedlyrics.utils import format_time

print(format_time(65.5))  # "01:05.50"

The synced_to_plaintext function removes LRC timestamps (e.g., [00:12.34] ) from a string, leaving only the raw text.

from syncedlyrics.utils import synced_to_plaintext

synced = "[00:12.00] Hello world"
plain = synced_to_plaintext(synced)
# plain == "Hello world"

Use get_cache_path to retrieve a platform-specific directory for storing cached data. It automatically handles paths for Windows (LOCALAPPDATA), macOS (~/Library/Caches), and Linux (~/.cache).

• lib_name: The name of the subdirectory to create (defaults to "syncedlyrics").
• auto_create: If True, the directory will be created if it doesn't exist.

from pathlib import Path
from syncedlyrics.utils import get_cache_path

cache_dir = get_cache_path(lib_name="my_app", auto_create=True)
print(cache_dir)  # Returns a Path object