55 lines
2.4 KiB
Markdown
55 lines
2.4 KiB
Markdown
# Companion native overlay
|
|
|
|
Lumi Companion includes a Windows-native monitor overlay under **Plugins → Lumi
|
|
Overlay**. It is independent of Lumi's OBS browser-source overlays: it uses
|
|
Avalonia controls in a transparent, topmost, click-through window and never
|
|
loads HTML or provider credentials.
|
|
|
|
## Data and authorization
|
|
|
|
The server endpoint is `/plugins/lumi_overlay/live`. It authenticates the same
|
|
paired device credential as Companion and requires `overlay.read.v1`. New
|
|
pairings receive the capability. Existing active devices receive it through a
|
|
one-time migration; a later capability removal is not silently undone.
|
|
|
|
Lumi reuses its normalized Twitch, YouTube, and Discord chat/event streams.
|
|
Selections are filtered on the server, messages are sanitized and bounded, and
|
|
a connection receives live items only—no history is replayed after startup or
|
|
reconnect. Missing provider scopes disable only their affected event types and
|
|
are reported in feed status.
|
|
|
|
The native renderer uses the same normalized badge, emote, and Discord media
|
|
payloads as Lumi's OBS browser overlay. HTTPS artwork is downloaded with strict
|
|
size, dimension, frame-count, and decoded-pixel limits. Animated GIF/WebP
|
|
emotes and images retain their bounded frame timing; unsupported video-only
|
|
embeds use their supplied preview image when available.
|
|
|
|
## Window behavior
|
|
|
|
The selected monitor, layout, styling, sources, event types, visibility mode,
|
|
animation lifecycle, and hotkeys are stored atomically under the current
|
|
Windows user's Companion data directory. A missing monitor temporarily falls
|
|
back to the primary screen without changing the saved monitor.
|
|
|
|
The overlay reapplies click-through, non-activating, tool-window and topmost
|
|
styles after display, power, and Windows session changes. It calls
|
|
`SetWindowDisplayAffinity(WDA_EXCLUDEFROMCAPTURE)` and reports the result in the
|
|
settings page. This is best-effort Windows protection: OBS and other capture
|
|
software can use capture paths that do not honor display affinity.
|
|
|
|
`When live` is activated only by a selected Twitch or YouTube source. Discord
|
|
does not activate it. Sample preview and the visibility override temporarily
|
|
take precedence, then restore the saved mode.
|
|
|
|
## Verification
|
|
|
|
From PowerShell:
|
|
|
|
```powershell
|
|
companion/scripts/verify-lumi-overlay.ps1
|
|
```
|
|
|
|
The regular `npm run verify:all` suite also exercises the server protocol,
|
|
filtering, no-backlog behavior, queue bounds, capability migration, and
|
|
revocation behavior.
|