165 lines
8.1 KiB
Markdown
165 lines
8.1 KiB
Markdown
# 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`.
|