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 reads media metadata directly from the Windows operating system using the winsdk Python bindings for the GlobalSystemMediaTransportControls (SMTC) API. On every loop iteration it retrieves two things: the track’s identity (title and artist) to know which song is playing, and the current playback position to know exactly where in that song the listener is.

​
Session Retrieval

The entry point for all media queries is MediaManager.request_async(), which returns a snapshot of every active SMTC session currently registered with Windows. Calling get_current_session() on that snapshot returns the OS-level “current” session — typically the most recently active audio source. 
async def get_session():
    sessions = await MediaManager.request_async()
    session = sessions.get_current_session()
    return session
If no application is producing audio (or none has registered with SMTC), get_current_session() returns None, and the main loop skips that iteration gracefully.

​
Track Metadata

Once a session is obtained, try_get_media_properties_async() fetches the track’s metadata — title, artist, album art, and more — directly from the playing application. LiveLyrics extracts only the fields it needs: 
async def get_media_info(session):
    info = await session.try_get_media_properties_async()
    return {"title": info.title, "artist": info.artist}
The return value is a plain dict with two keys — title and artist — which are then passed to the lyrics-fetching pipeline and used to construct the fallback status string.

​
Playback Position and Extrapolation

Knowing the track is not enough — LiveLyrics also needs to know where in the track the listener currently is, down to the millisecond, so it can select the correct lyric line. get_timeline_properties() provides two key values:
  • position — the playback position at the moment the OS last updated it. This may be a timedelta object or a raw tick value (100-nanosecond units), so LiveLyrics handles both.
  • last_updated_time — the UTC datetime at which that position snapshot was taken.
get_playback_info() provides the playback_status integer. A value of 4 means the track is actively playing. Because the Windows SMTC API may return position either as a timedelta object (which exposes .total_seconds()) or as a raw integer count of 100-nanosecond ticks, get_position_seconds normalises the value before doing anything else: 
try:
    base_seconds = pos.total_seconds()
except AttributeError:
    # pos is a raw tick value (100 ns units) — convert to seconds
    base_seconds = pos / 10_000_000
When the status is 4, LiveLyrics calculates how much wall-clock time has passed since last_updated_time and adds it to the reported position: 
if status == 4:
    now = datetime.datetime.now(datetime.timezone.utc)
    elapsed = (now - last_updated).total_seconds()
    seconds = base_seconds + elapsed
else:
    seconds = base_seconds
The Windows SMTC API updates the timeline position only periodically — not continuously. Without this extrapolation step, the reported position would often be several hundred milliseconds behind the actual audio playback, causing the wrong lyric line to be displayed. By computing the elapsed wall-clock time since the last OS update and adding it to the base position, LiveLyrics stays tightly synchronized with what the listener is actually hearing.

​
Track Change Detection

main() tracks the currently playing song using a last_track_key tuple: 
track_key = (track['title'], track['artist'])

if track_key != last_track_key:
    last_track_key = track_key
    current_lyrics = fetch_synced_lyrics(track['title'], track['artist'])
    last_line = None
Whenever the (title, artist) pair changes, LiveLyrics treats it as a new song: it triggers a fresh lyrics fetch (or cache lookup), resets the last_line pointer so the first matching lyric is sent to Discord immediately, and starts position tracking from scratch.
The Windows SMTC API is application-agnostic — it captures audio metadata from any application that registers with it, including Spotify, YouTube (in a browser), Windows Media Player, VLC, and most modern media players. LiveLyrics works with all of them without any app-specific configuration.

Build docs developers (and LLMs) love

Get started for freeTalk to us