Rolfsvaag_Datateknikk/Lumi
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 22 Wiki Activity
5f05251155
Lumi/companion/docs/song-overlay-companion.md
Franz Rolfsvaag 5f05251155 release: publish Lumi 0.3.11 companion experience
2026-07-29 23:41:34 +02:00

2.2 KiB
Raw Blame History

Song Overlay Companion integration

This integration adds provider-neutral Windows media-session discovery to Lumi Companion. It can identify Spotify, Windows Media Player, YouTube and YouTube Music in Chrome or Edge, VLC, iTunes and Apple Music, SoundCloud, TIDAL, Bandcamp, and Qobuz. Each source is independently switchable; Windows Media Player, YouTube, and Spotify are enabled by default.

Navigation contract

Every Companion plugin implements ICompanionPluginContribution and receives one nested root in both navigation surfaces:

  • Tray menu: core actions, Plugins, one submenu per plugin, then health/update/log/settings controls and Quit.
  • App sidebar: Overview, PLUGINS, one expandable root per plugin, then Connection, Logs, and Settings at the bottom.

Plugin actions are caught at the shell boundary so a routine plugin exception does not terminate Companion. The Song Overlay runtime also catches provider callbacks, transport failures, heartbeats, and initialization failures and reports an actionable plugin status.

Song Overlay flow

  1. Windows Global System Media Transport Controls exposes playback from enabled desktop and browser sources.
  2. The provider identifies the source where Windows exposes enough app or metadata context, then raises media, playback, timeline, and session-availability events.
  3. The runtime sends only meaningful deltas to Lumi: track change, inferred next/previous, play, resume, pause, stop, seek, metadata enrichment, or a sparse recovery heartbeat.
  4. Playback progress is projected from the last event. Continuous progress messages are not sent.
  5. Cover art is resized and sent only with track metadata.
  6. The existing Lumi plugins/now_playing endpoint updates the Song Overlay source and optional chat announcement.

Build and verification

From the repository root on Windows:

dotnet build companion/Lumi.Companion.sln -c Release -p:EnableWindowsTargeting=true
node plugins/now_playing/tests/verify.js

Or run:

companion/scripts/verify-song-overlay.ps1

The optional Spotify Web API connection is used only for metadata enrichment such as exact links and release year. Core playback detection works through Windows without Spotify authorization.