Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/x-eon-max/LiveLyrics/llms.txt

Use this file to discover all available pages before exploring further.

LiveLyrics is configured by editing variables directly at the top of LiveLyrics.py before running the script. There is no external config file, environment variable loading, or CLI flag support — every setting lives in the source file itself.

​
Configuration Variables

​
TOKEN
string
required
Your Discord user authentication token. Passed verbatim as the authorization header in every Discord API request made by the script.
TOKEN = 'mfa.xxxxxxxxxxxxxxxxxxxx'
Obtain this value from your browser’s DevTools while logged into Discord. See this step-by-step guide for detailed instructions. The default placeholder value is 'YOUR-TOKEN-HERE' — the script will silently fail to update your status until you replace it.
Never commit your Discord token to a public repository or share it in any version-controlled file. Anyone with your token has full access to your Discord account. If you accidentally expose it, change your Discord password immediately — this invalidates the old token.
​
LYRICS_CACHE
dict
default:"{}"
A module-level in-memory dictionary that caches lyrics lookups for the duration of the script’s runtime. Keys are (title, artist) tuples; values are the parsed list of (timestamp_seconds, lyric_text) tuples returned by parse_synced_lyrics().
LYRICS_CACHE = {}
The cache is populated automatically the first time a track is encountered and consulted on every subsequent encounter of the same track within the same session. This avoids redundant LRCLIB API calls when you replay a song. Pre-populating it manually is not normally necessary.
The cache is held entirely in memory and is cleared on every script restart. There is no persistence to disk between runs.

​
Status Payload

On every lyric-line change, update_status() sends an HTTP PATCH to https://discord.com/api/v9/users/@me/settings with the following JSON payload: 
payload = {"custom_status": {"text": text, "emoji_name": "🎵"}}
FieldValueNotes
textThe current synced lyric lineTruncated to 128 characters — Discord’s hard limit for custom status text.
emoji_name"🎵" (musical note emoji), hardcodedDefined in update_status(). Change the string there to use a different emoji.
The authorization header carries your TOKEN value. No OAuth flow or bot token is involved — this uses the same user-token mechanism as the Discord web client.

​
Tunable Constants

Several inline values in LiveLyrics.py are worth knowing about if you want to tune performance or behaviour. None of them are extracted into named constants — adjust them in place.

​
Poll Interval

# inside main(), at the end of the while-True loop (happy path)
await asyncio.sleep(0.01)

# inside main(), after an unexpected error during media retrieval
await asyncio.sleep(2)
The main loop uses two different sleep durations depending on the outcome of each iteration:
  • Happy path — asyncio.sleep(0.01) (10 ms): The loop sleeps for 10 ms between ticks when media retrieval succeeds. This keeps lyric-line transitions near-instantaneous. Increasing this value (e.g., to 0.5 or 1.0) reduces CPU usage at the cost of slower lyric updates.
  • Error recovery — asyncio.sleep(2) (2 s): If an unexpected exception is raised while fetching the media session or media properties, the loop catches it, logs the error, and backs off for 2 seconds before retrying. This prevents a tight error loop from spinning the CPU when something is persistently wrong.

​
API Timeout

# LRCLIB lookup (fetch_synced_lyrics)
res = requests.get("https://lrclib.net/api/search", ..., timeout=10)

# Discord status update (update_status)
r = requests.patch(url, json=payload, headers=headers, timeout=10)
Both outbound HTTP calls enforce a 10-second timeout. If either request stalls, a requests.RequestException is caught, logged, and the loop continues. Lower this if you want the script to recover faster on a slow connection; raise it if you’re seeing spurious timeouts.

​
Status Text Length

# Lyric line, in main()
update_status(line[:128])

# Fallback "Artist - Title" string, also in main()
update_status(f"{track['artist']} - {track['title']}"[:128])
The [:128] slice enforces Discord’s 128-character custom status limit on both the lyric line and the no-lyrics fallback string. If you need to shorten status text further for aesthetic reasons, reduce this value.

​
Environment

RequirementMinimum version / value
OSWindows 10 or Windows 11
Python3.8+
requestsAny recent stable release
winsdkAny release compatible with Py 3.8+
winsdk depends on the Windows Runtime and will not import on macOS or Linux. See Troubleshooting if you hit an import error.

Build docs developers (and LLMs) love

Get started for freeTalk to us