Audio Sources (Radios)

StreamooS integrates two independent audio sources: KHInsider Radio and SMTC (System Media Transport Controls, the operating system's media player). Each runs in its own context and syncs its state to overlays via WebSocket.

The direct Spotify API integration was removed (ADR-012). Spotify is still controllable, but like any other application, through SMTC.

KHInsider Radio

Play game music from KHInsider playlists.

Architecture

Behavior

• Watchdog: checks state every 5s. If no update for 15s, the window is marked "stale" and a retry is triggered.
• Persistent shuffle: stays active until explicitly disabled (shuffle with data.enabled: false).
• Throttling: position updates (progressMs) emitted at most every 3s during stable playback. Transitions (play/pause/next) are immediate.
• Lazy loading: the KHInsider window is only instantiated on first use.

WS Commands

Command	Parameters	Description
play / pause / next	-	Playback control
shuffle	data.enabled (bool, optional)	Toggle shuffle
volume	data.value (0–100)	Set volume
get_state / activate / deactivate / diagnostic	-	State & debug

Overlay Themes

Theme	Description
streamoos	Default StreamooS theme
minimal-dark	Minimal dark variant

---

SMTC (System Media Transport Controls)

Read metadata from the active system media player without OAuth, with playback control support.

Works with: the Spotify desktop app, YouTube Music, Tidal, VLC, Windows Media Player, and any player exposing SMTC (Windows) or MPRIS (Linux).

Architecture

Local Interpolation

To ensure smooth visual progress between the 3s throttled updates and 1000ms polling ticks, the Dashboard UI performs 1s local interpolation using the lastUpdatedAt timestamp.

Smart Polling

The 1000ms polling is automatically suspended when:

• App minimized to tray + no WS clients connected
• System sleeping (via powerMonitor)

It resumes immediately on reactivation.

OS Availability

OS	Implementation	Status
Windows	WinRT native via NAPI (native/)	Functional
Linux	MPRIS (D-Bus enumeration)	Functional (Supports any compliant player)
macOS	-	Not supported (Stub)

WS Commands

Command	Description
start_monitoring / stop_monitoring / get_state	Monitoring control
play / resume / pause / toggle_play / play_pause	Playback
next / prev / previous	Track navigation

WS Commands

Command	Parameters	Description
start_monitoring / stop_monitoring	-	Monitoring control
get_state	-	Get current state
play / resume / pause / toggle_play / play_pause	-	Playback
next / prev / previous	-	Track navigation
set_overlay_config	data.enabled, data.radioSource, data.position, data.showArtwork, data.showProgress, data.theme	Overlay settings
select_source	data.radioSource (auto | khinsider | smtc)	Radio Source

Overlay Themes

Theme	Description
streamoos	Default StreamooS theme
animal-crossing	Animal Crossing inspired
retro-rpg	Retro RPG dialogue box
modern-gamer	Modern gamer HUD
ghibli	Soft Ghibli palette
xp	Windows XP window
glass	Frosted glass
noisy	Grainy texture
minimal-dark	Minimal dark variant

SmtcState Contract

{
  connected: boolean        // player detected
  isPlaying: boolean
  title: string
  artist: string
  albumTitle?: string
  artworkUrl?: string
  progressMs: number
  durationMs: number
  radioSource: 'khinsider' | 'smtc'
  mediaApp: string          // app id detecte (AUMID Windows / bus MPRIS), '' si inconnu
  mediaAppLabel: string     // libelle humain, '' si inconnu
  lastUpdatedAt: number     // Unix timestamp ms
  platform?: string         // 'win32' | 'linux' | 'darwin'
  overlayConfig: {
    enabled: boolean
    radioSource: 'auto' | 'khinsider' | 'smtc'
    position: OverlayPosition
    showArtwork: boolean
    showProgress: boolean
    theme: RadioOverlayTheme
  }
}

---

Comparison

Criteria	KHInsider	SMTC
OAuth required	No	No
Playback control	Yes	Yes
Metadata	Yes	Yes
Real-time update	Throttled 3s	Polling 1000ms
External dependency	Playlist URL	SMTC/MPRIS player
Status	Stable	Windows stable / Linux partial