Dynamic Overlay desktop app

What it does

The Electron app is a controller around the existing web scene renderer; it does not contain a second overlay implementation. It signs in with BeatKhana OAuth, lists accessible tournaments/overlays, starts any number of independent scene outputs, reports starting/running/stopped/error and measured Spout FPS, and provides refresh or hard reset. Stopping destroys the scene WebContents and its socket/network/audio lifecycle.

Output modes

On Windows, Spout source publishes an independent D3D11 texture sender named BeatKhana - {overlay} - {scene}. The bridge keeps transfer on-GPU. Spout itself carries video only, but the same offscreen scene renderer plays its complete mixed audio through the system audio device; route/capture that app audio in OBS. This avoids a second hidden full-resolution scene. Set DYNAMIC_OVERLAY_SPOUT_AUDIO_MODE=legacy-window only as a compatibility fallback. OBS and the app must use the same graphics adapter.

Fixed-size window opens an exact-resolution, non-resizable renderer with its own audio lifecycle. It is used on Linux/macOS and is also available on Windows. Background throttling is disabled, device scale is fixed to 1, and an active-output power blocker prevents suspension.

Window titles are stable and scene-specific: BeatKhana Dynamic Overlay | {overlay name} | {scene name}. Electron rejects page-title changes and reapplies the title after navigation, so OBS Window Capture can distinguish multiple scenes reliably.

Authentication and security

The built-in public desktop client uses authorization code + S256 PKCE at beatkhana-overlay://oauth/callback, requests rest:read ws:read tournamentassistant, and has no embedded secret. Tokens remain in the main process, use Electron safeStorage when available, and fall back on Linux without a secret store to a user-only 0600 file. Renderer sessions are isolated and receive the normal auth cookie.

Operator controls

• Start / Stop: create or destroy one independent scene output.
• Refresh: reload a running renderer.
• Hard reset: clear renderer cache and recreate the source.
• Exit: confirmation warns that all active outputs stop.

Build and release

Use Node.js 22+. Build Windows artifacts on Windows because the D3D11/Spout addon is native; Linux packages on Linux; signed/notarized macOS artifacts on macOS. npm run package is an unpacked development build targeting localhost by default. dist/dist:* create production builds. Unsigned local builds are for testing, not public release.

Rehearsal checklist

Log in; select tournament/overlay; start at least two scenes; verify independent stop; test refresh and hard reset; on Windows confirm named 60 FPS Spout senders in OBS; verify audio only in intended window sources; cancel exit once; then exit and verify every output disappears.