Lumi/docs/obs-overlays.md

OBS overlays

Admins manage overlays at Admin → OBS overlays. Management pages use the normal Lumi session, role checks, layout, forms, lists, modals, and confirmation flow. Browser Source pages use a separate transparent document with no Lumi navigation or authenticated website data.

Editing an overlay

The editor uses the same basic model as OBS: scenes contain ordered sources, and the selected source has a red box with resize handles. On a wide screen the preview stays beside the settings; on smaller screens it moves above them.

• Drag a source to move it.
• Drag any corner or edge handle to resize it.
• Use arrow keys for small moves, or Shift plus an arrow for larger moves.
• Snapping uses canvas edges, center lines, and other source edges/midpoints.
• Hold Ctrl on Windows/Linux or Cmd on macOS to temporarily reverse the Snap setting.
• Center, Fit to canvas, and Reset box provide familiar transform shortcuts.

Every source can use any corner, edge midpoint, or center as its anchor. Text sources have separate horizontal and vertical alignment plus wrapping, shrinking, clipping, single-line, and scrolling ticker behavior. The editor only shows fields that apply to the selected source type.

Private OBS links

Each overlay has one server-controlled URL. It follows the active overlay scene. Each scene also has a fixed URL that always renders that scene. Both URL forms contain 256-bit random bearer tokens instead of database IDs. Tokens are stored encrypted for admin copy actions and as SHA-256 hashes for public lookup. Regenerating a URL immediately revokes the old token.

Treat every Browser Source URL as a password. Only admins can view, copy, preview, or regenerate it. Public state responses contain render data only; they do not contain other URLs, tokens, OBS credentials, or website session data.

Browser Sources receive scoped live-change events through Lumi's existing event service. The render page fetches a fresh authorized snapshot after each event and after every reconnect, so temporary network loss does not require an OBS refresh.

Scenes and sources

An overlay always keeps at least one scene. Admins can create, edit, duplicate, order, enable, activate, and delete scenes. Current built-in source types are:

• Text
• Image URL
• Video / media URL
• Audio URL
• Website or alert overlay

Module instances can be created, edited, duplicated, ordered, enabled, and deleted. New module types can call registerOverlayModuleType(...) in src/services/overlay-modules.js; providers normalize their configuration and select the safe built-in text, image, video, audio, or web render type while the overlay service retains the same instance model.

Video and audio

Video sources support browser-playable media such as WebM and MP4; audio sources support browser-playable formats such as Ogg, MP3, and WAV. Actual codec support follows the Chromium/CEF build used by the browser or OBS.

Playback can start once when the overlay scene loads, loop continuously, or wait for manual playback. Sources also provide volume, start offset, playback speed, optional player controls, and a live Restart playback action. Video adds mute and contain/cover/stretch sizing. Activating another Lumi scene removes the old scene's media elements, which stops their playback; returning to the scene applies its configured start behavior again.

Website overlays can play their own alert audio because their iframe receives autoplay permission. To route video, audio, and website-alert sound through an independent OBS mixer channel, enable Control audio via OBS in the Lumi Browser Source properties, then configure monitoring/output in OBS as desired.

External website and alert overlays

Website sources support third-party browser overlays such as alert and chat overlays. They run in a sandbox and do not receive the Lumi admin page or its login data. The Refresh now action sends a live refresh command to every open OBS copy of that source.

Automatic recovery is optional. When enabled it watches for a page that never finishes loading, can check public website replies for HTTP errors, empty content, unexpected content types, and obviously malformed pages, retries at 5, 15, and 45 second-style bounded intervals, and periodically reloads the source to avoid stale content. Retry count and refresh interval are configurable. Local/private website addresses are periodically refreshed but are not fetched by the Lumi server for security; browser load-timeout recovery still applies.

Website sources also support per-edge percentage cropping, zoom, and isolated custom frame CSS. Custom CSS is scoped to the source frame so it cannot restyle the Lumi render page or other sources. Standard browser cross-origin security does not allow parent-page CSS to select elements inside a third-party iframe; use crop and zoom to hide unwanted portions of an external site. Frame-level CSS can target iframe, for example iframe { filter: saturate(1.2); }.

OBS WebSocket

The connector is disabled by default. Enable OBS WebSocket in OBS, keep its password enabled, and use the default local endpoint ws://127.0.0.1:4455 when Lumi runs on the streaming computer. If Lumi runs on another trusted machine, use a private LAN/VPN address and firewall rules. Do not port-forward or publicly expose OBS WebSocket.

The admin page can test the connection, read OBS scenes, change the current OBS scene, and map OBS scene names to overlay scenes. Sync can run in either direction or bidirectionally. Source tagging and a short outbound suppression window prevent sync loops. Connector errors never stop overlay rendering, and optional reconnect uses bounded exponential backoff.

OBS passwords use authenticated AES-256-GCM encryption derived from Lumi's stored session secret. They are never returned by public APIs or rendered for non-admins.

OBS Browser Bridge

The optional OBS Browser Bridge uses the window.obsstudio bindings that OBS injects into Browser Sources. It does not need an OBS WebSocket address or password. Select the provider, save it, then load the private Lumi overlay URL in OBS. The render page reports a heartbeat every five seconds and immediately after relevant OBS events.

Use the minimum Page permission needed:

• Read access to user information reads the current scene, scene list, transitions, canvas dimensions, output status, and Browser Source activity.
• Advanced access to OBS is needed only when Lumi should change OBS scenes.
• Full access is not requested or used by the current bridge.

Lumi elects one recently active Browser Source instance per overlay as the bridge, targets commands to that instance, and deduplicates command IDs. Existing scene-direction checks and outbound suppression prevent synchronization loops. If the source stops reporting, Lumi marks the bridge as waiting instead of breaking overlay rendering. Leave OBS's Shutdown source when not visible option off if the bridge must remain available outside the source's active scene.

The Apply detected OBS setup action adds missing OBS scenes, maps same-name Lumi scenes, adopts the detected OBS canvas size, and selects the current OBS scene. It does not delete existing Lumi scenes. OBS Browser bindings do not expose profile or scene-collection names, so those fields are explicitly reported as unavailable; the OBS WebSocket provider can read them when that metadata is required.

Connector extension point

src/services/overlay-connectors.js owns the provider registry. A provider creates a connector with these operations:

• connect() and disconnect()
• status()
• listScenes() and getActiveScene()
• setActiveScene(sceneName)
• onSceneChanged(listener) and onClosed(listener)

The reserved trusted_lumi_client provider is intentionally unavailable. A future trusted desktop client can implement this interface to transport OBS state and commands without changing overlay routes, mappings, or synchronization rules. Plugins can register providers, module types, or future scoped access providers through global.lumiFrameworks.overlays.

Run focused verification with npm run verify:overlays.