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 logs every action with a timestamp to stdout, making it straightforward to diagnose issues as they happen. Most problems surface immediately in the terminal output, and the relevant log line will point directly to the root cause.

​
Reading the Logs

Every message is emitted by the log() function and follows the format: 
[HH:MM:SS] message
The timestamp reflects your local system clock at the moment the event occurred. All major steps — session retrieval, LRCLIB requests, lyric parsing, and Discord updates — are logged individually so you can pinpoint exactly where the script stalls or fails. A healthy run from startup through the first status update looks like this: 
[12:34:01] Starting script.
[12:34:01] Requesting media sessions (MediaManager.request_async)...
[12:34:02] Media found -> title='Song Name' artist='Artist'
[12:34:02] LRCLIB response: status_code=200
[12:34:02] 72 lines of lyrics parsed.
[12:34:02] Updating Discord status with: 'Opening lyric line'
[12:34:02] Discord response: status_code=200
If any step fails, an ERROR prefix or an unexpected status code will appear in place of the success messages shown above.

​
Common Issues

Cause: No audio application is currently registered as the active SMTC (System Media Transport Controls) session. LiveLyrics reads metadata exclusively from the session that Windows designates as “current” — if no app holds that session, the script has nothing to work with.What you see in the logs:
[12:34:01] Requesting media sessions (MediaManager.request_async)...
[12:34:01] Sessions retrieved, searching for current session...
[12:34:01] No current session found.
Fix:
  • Make sure a media player (Spotify, Windows Media Player, a music browser tab, etc.) is open and actively playing audio before you start the script.
  • Some apps — particularly browser tabs playing audio — register with SMTC later than dedicated media players. Wait a few seconds after pressing play, then restart the script.
  • If the session disappears mid-playback (e.g., the player is paused for an extended period), the script will keep looping and pick up the session again automatically once playback resumes.
Symptom: The log shows one of the following lines:
[12:34:02] No LRCLIB results found.
or
[12:34:02] First result has no syncedLyrics.
Cause: The track is either not present in LRCLIB’s database, or only plain (unsynced) lyrics exist for it. LRCLIB is a community-maintained database, so coverage varies — obscure tracks, regional releases, and very new songs are most likely to be missing.Fix: LiveLyrics automatically falls back to displaying "Artist - Title" as your Discord status whenever synced lyrics are unavailable. No action is required on your part.If you’d like to confirm the situation manually, paste the following URL into your browser and check the syncedLyrics field in the response:
https://lrclib.net/api/search?track_name=TRACK&artist_name=ARTIST
If the entry truly has no synced lyrics, consider submitting them to LRCLIB — future runs of the script will pick them up automatically once the cache for that track is cleared (i.e., on restart).
Symptom: The log shows:
[12:34:02] Discord response: status_code=401
[12:34:02] Discord response body (error): {"message": "401: Unauthorized"}
Cause: The TOKEN value in LiveLyrics.py is incorrect, has been invalidated, or still contains the placeholder 'YOUR-TOKEN-HERE'.Discord user tokens are invalidated when you:
  • Change your Discord password.
  • Enable or disable two-factor authentication.
  • Log out of all sessions from the Discord settings.
Fix:
  1. Log into Discord in your browser.
  2. Re-obtain your token from the browser’s DevTools. Follow this guide if you need a refresher.
  3. Replace the TOKEN value at the top of LiveLyrics.py with the new token.
  4. Restart the script.
Cause: LiveLyrics calculates the current playback position using temporal extrapolation — it reads the last known position reported by the OS and adds the time elapsed since that report:
# get_position_seconds() in LiveLyrics.py
seconds = base_seconds + elapsed  # elapsed since last OS update
This compensates for the inherent lag between actual audio playback and Windows SMTC position updates. However, LRCLIB timestamp accuracy varies by contributor — some entries have timestamps that are a fraction of a second early or late relative to the actual audio.Fix: There is no in-app timing adjustment. The drift is a data quality issue tied to the specific LRCLIB entry for that track. If the timing is significantly off, you may be able to find a better-timestamped entry by checking LRCLIB directly or waiting for the community to improve the entry.
Cause: The winsdk package is not installed in the Python environment you are using to run the script.Fix: Install the required dependencies:
pip install winsdk requests
Then verify the installation succeeded:
pip show winsdk
If pip show returns package details without an error, winsdk is available. Make sure you are running pip (and later python) in the same environment — if you use multiple Python versions or virtual environments, install into the one you intend to use.
Cause: The TOKEN variable in LiveLyrics.py still contains the default placeholder value 'YOUR-TOKEN-HERE'. The script sends this string as the authorization header, which Discord rejects silently from the script’s perspective (you will actually see a 401 in the logs — see the section above).Fix: Open LiveLyrics.py, locate the TOKEN variable at the top of the file, and replace the placeholder with your real Discord user token:
# Before
TOKEN = 'YOUR-TOKEN-HERE'

# After
TOKEN = 'mfa.xxxxxxxxxxxxxxxxxxxx'  # your actual token
Save the file and restart the script.
Cause: winsdk wraps the Windows Runtime (WinRT) APIs, which only exist on Windows. The package does not install or function on macOS or Linux — the import will fail immediately regardless of your Python version.Fix: LiveLyrics is a Windows-only utility. Run it on a machine running Windows 10 or Windows 11. There is currently no cross-platform alternative built into the project.
If your problem isn’t covered here, open an issue at https://github.com/x-eon-max/LiveLyrics and include the relevant section of your terminal output to help with diagnosis.

Build docs developers (and LLMs) love

Get started for freeTalk to us