How I put lyrics between the wallpaper and the windows

Description and use

Undertone shows time‑synced lyrics and a beat visualizer on the Linux desktop, leveraging MPRIS for media state and GTK for rendering.

Problem

Display time‑synced lyrics on the Linux desktop without a separate window or widget, so they appear only when the user glances at the desktop and disappear when working.

Outcome

Undertone provides a lightweight, CPU‑efficient lyrics lightbox that overlays the desktop, synchronizes with any MPRIS‑compliant player, and visualizes beats in real time.

Workflow

• 1. Map a fullscreen, undecorated GTK window with the _NET_WM_WINDOW_TYPE_DESKTOP hint (or gtk-layer-shell BACKGROUND on Wayland).
• 2. Poll the session bus via MPRIS four times per second to obtain current track metadata and playback position.
• 3. Interpolate playback position using a monotonic clock to compensate for one‑second polling steps.
• 4. Retrieve lyrics from a local .lrc file, then LRCLIB, then NetEase if needed.
• 5. Extract album art from the track or MPRIS art URL, compute accent colors, and cache the backdrop.
• 6. Capture audio from the default sink monitor source with parec, perform FFT and beat detection, and drive a ring visualizer and lyric scaling.
• 7. Render the lyrics and visualizer onto a cached surface, updating only the visualizer region each frame to keep CPU usage low.
• 8. Provide D‑Bus hotkeys and panel applet for toggling, cycling visualizer, nudging timing, and editing lyrics.
• 9. On idle, lift the lyrics above all windows after N minutes via screensaver mode.
• 10. Unmap, retype, and remap the window if the window type hint changes during runtime.

Evidence

On X11, a window with the _NET_WM_WINDOW_TYPE_DESKTOP hint is stacked with the desktop: above the wallpaper, below everything else.

Source

Every Linux media player publishes its state on the session bus via MPRIS: Spotify, VLC, Firefox, Chromium-based browsers running YouTube Music.

Source

The visualizer taps the real audio output: parec on the default sink's monitor source, 2048-sample frames, a Hann window, an FFT, then ten log-spaced bands between 40 Hz and 12 kHz mapped to dB above a floor.

Source

The accent colour is extracted from the album art: downscale, drop near-grey and near-black pixels, weighted hue histogram, take the dominant bin, then brighten it so it reads on a dark backdrop.

Source