lrclib package

Submodules

lrclib.api module

API for lrclib

class lrclib.api.LrcLibAPI(user_agent: str, base_url: str | None = None, session: Session | None = None)[source]

Bases: object

Create a new LrcLibAPI instance. You can optionally pass a custom base URL and a custom requests session.

Note

setting user_agent is not required, but it is recommended by LRCLIB.

Parameters:

user_agent (str) – User agent to use for the requests
base_url (str, optional) – Base URL to use for the requests
session (requests.Session, optional) – Requests session to use for the requests

Raises:

UserWarning – If user_agent is not set

Examples

See the 📥Fetching lyrics using the API section for usage examples.

get_lyrics(track_name: str, artist_name: str, album_name: str, duration: int, cached: bool = False) → Lyrics[source]

Get lyrics from LRCLIB by track name, artist name, album name and duration.

Note

All parameters are required except cached.

Parameters:

track_name (str) – Track name
artist_name (str) – Artist name
album_name (str) – Album name
duration (int) – Duration of the track in seconds
cached (bool, optional) – Whether to get cached lyrics or not, defaults to False

Return type:

Lyrics

Raises:

NotFoundError – If no lyrics are found
APIError – If the request fails

get_lyrics_by_id(lrclib_id: str | int) → Lyrics[source]

Get lyrics from LRCLIB by ID.

Parameters:

lrclib_id (str | int) – ID of the lyrics

Return type:

Lyrics

Raises:

NotFoundError – If no lyrics are found
APIError – If the request fails

publish_lyrics(track_name: str, artist_name: str, album_name: str, duration: int, plain_lyrics: str | None = None, synced_lyrics: str | None = None, publish_token: str | None = None) → Dict[str, Any][source]

Publish lyrics to LRCLIB. All parameters are required.

Note

If no lyrics are provided, the track will be marked as instrumental.

Parameters:

track_name (str) – Track name
artist_name (str) – Artist name
album_name (str) – Album name
duration (int) – Duration of the track in seconds
plain_lyrics (str, optional) – Plain lyrics
synced_lyrics (str, optional) – Synced lyrics
publish_token (str, optional) – Publish token to use for publishing lyrics, if not provided, a new one will be generated

Returns:

Response from the API

Return type:

Dict[str, Any]

Raises:

IncorrectPublishTokenError – If the publish token is incorrect
APIError – If the request fails

request_challenge() → CryptographicChallenge[source]

Generate a pair of prefix and target strings for the cryptographic challenge. Each challenge has an expiration time of 5 minutes.

The challenge’s solution is a nonce, which can be used to create a Publish Token for submitting lyrics to LRCLIB.

Return type:: CryptographicChallenge

lrclib.cryptographic_challenge_solver module

A module that provides a class to solve a cryptographic challenge.

class lrclib.cryptographic_challenge_solver.CryptoChallengeSolver[source]

Bases: object

Class for solving cryptographic challenges.

static solve(prefix: str, target_hex: str, num_threads: int = 1)[source]

Solve the cryptographic challenge.

Parameters:

prefix (str) – The prefix string of the challenge.
target_hex (str) – The target hash in hexadecimal format.
num_threads (int) – The number of threads to use for solving the challenge.

Returns:

nonce – The nonce that satisfies the target hash.

Return type:

str

class lrclib.cryptographic_challenge_solver.Solution(prefix: str, target_hex: str, nonce: int | None = None)[source]

Bases: object

Class for storing the solution of a cryptographic challenge.

property is_solved: bool: Check if the challenge is solved.

nonce: int | None = None: The nonce that satisfies the target hash.

prefix: str: The prefix string of the challenge.

target_hex: str: The target hash in hexadecimal format.

lrclib.cryptographic_challenge_solver.find_nonce(prefix: str, target: bytes, solution: Solution | None = None, start: int = 0, step: int = 1) → Solution[source]: Find the nonce that satisfies the target hash such that the hash of the prefix concatenated with the nonce is less than the target hash.

lrclib.cryptographic_challenge_solver.is_nonce_valid(prefix: str, nonce: int | str, target: bytes) → bool[source]: Check if the given nonce satisfies the target hash.

lrclib.exceptions module

Exceptions for the LRC API.

exception lrclib.exceptions.APIError(response: Response)[source]

Bases: RequestException

Base class for API errors.

exception lrclib.exceptions.IncorrectPublishTokenError(response: Response)[source]

Bases: APIError

Raised when the publish token is incorrect.

exception lrclib.exceptions.NotFoundError(response: Response)[source]

Bases: APIError

Raised when a resource is not found.

exception lrclib.exceptions.RateLimitError(response: Response)[source]

Bases: APIError

Raised when the rate limit is exceeded.

exception lrclib.exceptions.ServerError(response: Response)[source]

Bases: APIError

Raised when the server returns an error.

lrclib.models module

Models for api.py

class lrclib.models.BaseModel[source]

Bases: Generic[ModelT]

Base model

classmethod from_dict(data: Dict[str, Any]) → ModelT[source]: Create a ModelT object from a dictionary

class lrclib.models.CryptographicChallenge(prefix: str, target: str)[source]

Bases: BaseModel[CryptographicChallenge]

Cryptographic Challenge

prefix: str

target: str

class lrclib.models.ErrorResponse(status_code: int, error: str, message: str)[source]

Bases: BaseModel[ErrorResponse]

Response sent when an error occurs on the server

error: str

message: str

status_code: int

class lrclib.models.Lyrics(id: int, name: str, track_name: str, artist_name: str, album_name: str, duration: int, instrumental: bool, plain_lyrics: str | None = None, synced_lyrics: str | None = None, lang: str | None = None, isrc: str | None = None, spotify_id: str | None = None, release_date: datetime | None = None)[source]

Bases: BaseModel[Lyrics]

Lyrics object with full information

album_name: str

artist_name: str

duration: int

id: int

instrumental: bool: if the lyrics are instrumental

isrc: str | None = None

lang: str | None = None

name: str

plain_lyrics: str | None = None

release_date: datetime | None = None

spotify_id: str | None = None

synced_lyrics: str | None = None

track_name: str

class lrclib.models.LyricsMinimal(id: int, name: str, track_name: str, artist_name: str, album_name: str, duration: int, instrumental: bool, plain_lyrics: str | None = None, synced_lyrics: str | None = None)[source]

Bases: BaseModel[LyricsMinimal]

Lyrics object with minimal information

album_name: str

artist_name: str

duration: int

id: int

instrumental: bool

name: str

plain_lyrics: str | None = None

synced_lyrics: str | None = None

track_name: str

class lrclib.models.SearchResult(data: List[LyricsMinimal])[source]

Bases: List[LyricsMinimal]

list of LyricsMinimal objects

classmethod from_list(data: List[Dict[str, Any]]) → SearchResult[source]: Create a SearchResult object from a list of dictionaries

Module contents

LrcLib - A Python library for interacting with the LrcLib.net API.

class lrclib.LrcLibAPI(user_agent: str, base_url: str | None = None, session: Session | None = None)[source]

Bases: object

Create a new LrcLibAPI instance. You can optionally pass a custom base URL and a custom requests session.

Note

setting user_agent is not required, but it is recommended by LRCLIB.

Parameters:

user_agent (str) – User agent to use for the requests
base_url (str, optional) – Base URL to use for the requests
session (requests.Session, optional) – Requests session to use for the requests

Raises:

UserWarning – If user_agent is not set

Examples

See the 📥Fetching lyrics using the API section for usage examples.

get_lyrics(track_name: str, artist_name: str, album_name: str, duration: int, cached: bool = False) → Lyrics[source]

Get lyrics from LRCLIB by track name, artist name, album name and duration.

Note

All parameters are required except cached.

Parameters:

track_name (str) – Track name
artist_name (str) – Artist name
album_name (str) – Album name
duration (int) – Duration of the track in seconds
cached (bool, optional) – Whether to get cached lyrics or not, defaults to False

Return type:

Lyrics

Raises:

NotFoundError – If no lyrics are found
APIError – If the request fails

get_lyrics_by_id(lrclib_id: str | int) → Lyrics[source]

Get lyrics from LRCLIB by ID.

Parameters:

lrclib_id (str | int) – ID of the lyrics

Return type:

Lyrics

Raises:

NotFoundError – If no lyrics are found
APIError – If the request fails

publish_lyrics(track_name: str, artist_name: str, album_name: str, duration: int, plain_lyrics: str | None = None, synced_lyrics: str | None = None, publish_token: str | None = None) → Dict[str, Any][source]

Publish lyrics to LRCLIB. All parameters are required.

Note

If no lyrics are provided, the track will be marked as instrumental.

Parameters:

track_name (str) – Track name
artist_name (str) – Artist name
album_name (str) – Album name
duration (int) – Duration of the track in seconds
plain_lyrics (str, optional) – Plain lyrics
synced_lyrics (str, optional) – Synced lyrics
publish_token (str, optional) – Publish token to use for publishing lyrics, if not provided, a new one will be generated

Returns:

Response from the API

Return type:

Dict[str, Any]

Raises:

IncorrectPublishTokenError – If the publish token is incorrect
APIError – If the request fails

request_challenge() → CryptographicChallenge[source]

Generate a pair of prefix and target strings for the cryptographic challenge. Each challenge has an expiration time of 5 minutes.

The challenge’s solution is a nonce, which can be used to create a Publish Token for submitting lyrics to LRCLIB.

Return type:: CryptographicChallenge