Overlays

Overlays are the visual layers you composite on top of your stream in OBS (or any browser-source-capable encoder). Lumio ships a visual, layer-based editor for building them, a live preview that mirrors your canvas, and stable URLs you can drop into OBS as browser sources.

This guide walks you through creating, editing, and shipping overlays end-to-end.

Where to find it

Open the dashboard sidebar and go to Dashboard > Overlays. You'll see a grid of every overlay on your account, with the canvas resolution, an Edit button, a Copy URL button, and a delete action. Click New Overlay (top right) to start from scratch.

Quick start

1. Go to Dashboard > Overlays and click New Overlay.
2. Give the overlay a name (e.g. Main Scene), pick a resolution preset (1920×1080 is the default), and choose a background — Transparent is what you want for OBS in almost every case.
3. Click Create. You land on the card for that overlay.
4. Click Edit to open the visual editor.
5. Click the green + button (bottom-left of the canvas) and pick a widget to add your first layer.
6. Drag it on the canvas, tune it in the right-hand properties panel, then press Ctrl/Cmd + S (or the Save button) to persist.
7. Click Copy URL on the overlay card and paste it into OBS as a Browser Source.

The editor in depth

The editor fills the full window and has four regions:

• Toolbar (top): save state, overlay name, and window controls. Ctrl/Cmd + S saves; Ctrl/Cmd + \ toggles fullscreen (hides both side panels).
• Layer panel (left): every layer on the canvas, stacked top-down in render order. Click a layer to select it. Each row has toggles for visible (eye icon) and locked (padlock). Drag rows to reorder. Locked layers can't be moved or resized on the canvas — handy once a layer is positioned correctly.
• Canvas (center): the WYSIWYG surface. Snap-to-grid helps with alignment. Use the zoom control in the bottom bar (or scroll) to zoom; the canvas is always rendered at the overlay's native resolution, so what you see maps 1:1 to what OBS will see.
• Properties panel (right): every setting for the selected layer — position, size, rotation, opacity, and widget-specific options (text content, alert templates, event filters, Spotify theme, etc.).

Below the canvas you have:

• A green + button that opens the Widget Picker.
• A Test Events panel for firing synthetic follows, subs, cheers, etc. into the preview without waiting for a real viewer.
• A preview indicator (green dot) plus an Open Preview button that launches the full-resolution preview in a new tab.

Layer types

The widget picker offers eight widgets. Each is a layer with its own settings schema and renderer.

Widget	What it does
Event List	Scrolling list of recent follows, subs, cheers, raids, etc. Filter per-platform.
Spotify	Now-playing card (cover art, title, artist, progress). Requires a Spotify connection.
Text	Static or dynamic labels — stream title, clock, custom string.
Image	Upload or link to an image/PNG/GIF — logos, frames, decorations.
Timer	Countdown or stopwatch. Great for intermission screens and sub-goals.
Chat	Live chat feed with platform badges.
Alerts	Animated popups for follows/subs/cheers/raids/redemptions.
Custom HTML	Drop in arbitrary HTML/CSS/JS. Sandboxed — use for advanced layouts.

Up to 50 layers per overlay are allowed.

Editing a layer

Select a layer and use the properties panel:

• Position (x/y) and size (width/height) in pixels, relative to the canvas origin.
• Rotation in degrees.
• Opacity from 0 (invisible) to 1 (fully opaque).
• Widget settings — specific to the type (e.g. Alerts has templates per event type; Event List has platform filters and direction).

Tips:

• Click and drag directly on the canvas for fast positioning.
• Shift-drag constrains movement.
• Hit Delete with a layer selected to remove it.
• Unsaved changes are marked in the toolbar; closing the editor or refreshing prompts you to Save & Leave or Discard.

Preview: live vs production

Every overlay has two URLs:

URL	What it's for
/overlay/\{key\}/preview	Live preview. Mirrors the editor canvas in real time via a BroadcastChannel — any change you make in the editor appears instantly. Safe to use during editing only.
/overlay/\{key\}?token=<popout_token>	Production. Stable, cached, token-authenticated. This is what you paste into OBS.

The editor opens the preview in a hidden iframe so you see changes instantly without switching windows. Use Open Preview in the bottom bar to pop it out into its own tab (useful for a second monitor while editing).

Overlay key vs popout token

These are two different things and it's worth understanding the distinction:

• Overlay key — the overlay's own random identifier, part of the URL path (/overlay/\{key\}). It's not enumerable and acts as an obscurity handle. It never expires.
• Popout token — a separate auth credential you generate from Dashboard > Tokens. It authenticates the overlay request against your account and permissions. The production overlay URL requires a popout token in the ?token= query string.

This means two things in practice:

1. Sharing the overlay URL (with token) gives the holder read access to your overlay. Treat it like a password.
2. Revoking a popout token (from Tokens) instantly breaks any OBS setup using it — useful if a laptop is lost or a collaborator leaves.

OBS browser source setup

1. In Dashboard > Overlays, click Copy URL on the overlay card. The URL is copied to your clipboard.
2. In Dashboard > Tokens, create a popout token with a label like OBS - Streaming PC. Copy the token.
3. Append ?token=<your_token> to the copied URL.
4. In OBS: Sources > + > Browser. Paste the URL.
5. Set Width and Height to match the overlay's canvas (e.g. 1920 and 1080).
6. Leave Custom CSS empty unless you know you need it.
7. Enable Shutdown source when not visible and Refresh browser when scene becomes active for predictable behavior across scene switches.
8. Click OK. The overlay should render against a transparent background over your scene.

If nothing shows up: right-click the source > Interact and check the browser dev tools panel for errors — usually a bad/expired token or a permission missing on the token.

Common scenarios

"I want the same overlay on two scenes." Add the browser source to both scenes; OBS will share the same URL. Or duplicate the source. Both are fine; no need to create a second overlay.

"I want different overlays per scene." Create one overlay per scene (e.g. Main, BRB, Ending) and add each as a separate browser source to its scene.

"I want to share an overlay with my editor." Give them a dedicated popout token scoped to the minimum permissions needed (usually just overlays:read). Share the overlay URL with that token appended. Revoke the token when they're done.

"I want to test alerts before going live." Open the editor, add an Alerts layer, and use the Test Events panel in the bottom bar to fire a fake follow/sub/cheer. The preview animates the alert so you can tune timing, text, and sound before a real viewer triggers it.

"My overlay needs to portrait for TikTok." Pick the 1080×1920 (Portrait / TikTok) preset when creating the overlay.

Permissions

Action	Permission
See the overlays list and open the editor	overlays:read
Create a new overlay	overlays:create
Edit layers, save changes	overlays:edit
Delete an overlay	overlays:delete

The UI hides buttons you don't have permission for, and the server rejects the request anyway — both sides enforce the same permissions.

Tips & best practices

• Design at your output resolution. If you stream at 1920×1080, build the overlay at 1920×1080 — not 1280×720 scaled up. Browser sources don't resample gracefully.
• Use the Transparent background unless you have a specific reason not to. OBS composites the overlay on top of your scene.
• Lock layers once positioned. Prevents accidental drag during a quick edit.
• Name your layers. alerts-follow, timer-countdown, spotify-top-right — future-you will thank you when an overlay has 20 layers.
• Test with the test events panel before going live. Catches z-ordering and animation bugs that won't surface until a real viewer triggers them.
• Keep Custom HTML layers minimal. They're powerful but bypass most of the editor's safety rails. Version them outside the editor (a gist, your repo) if they get complex.
• Use two popout tokens — one for your streaming PC, one for your editing PC. Revoke each independently.

Troubleshooting

Empty/blank overlay in OBS. 90% of the time it's a missing or bad popout token. Open the URL in a regular browser tab first — you should see the overlay render. If not, generate a new token from Dashboard > Tokens.

Alerts never fire in production. Check that the Alerts layer is visible (eye icon) and not locked under another layer. Then verify in Dashboard > Events that Lumio is actually receiving events from your platform (if the event list is empty, the platform connection is the problem, not the overlay).

Preview shows changes but OBS doesn't update. OBS aggressively caches browser sources. Right-click the source > Refresh cache of current page, or right-click and Properties > OK to force a reload. Enabling Refresh browser when scene becomes active prevents this going forward.

"Access token required" error. You loaded /overlay/\{key\} without ?token=.... Append a popout token.

Layer moves off-canvas and I can't grab it. Select it in the layer panel (left) and reset x/y in the properties panel.

Save button stays disabled. Nothing to save — the editor only enables Save when there are unsaved changes (dirty state).

Unsaved changes dialog keeps appearing. Click Save & Leave if you want to keep your edits, or Discard to drop them. Closing the browser tab with unsaved changes triggers the browser's native "leave?" prompt too.

Related docs

• Tokens — generating and managing popout tokens for OBS.
• Events — the event stream that feeds the Event List and Alerts widgets.
• Music — the Spotify integration that powers the Spotify widget.
• Channel Status — what controls "am I live" detection.
• Roles and Permissions — how overlays:* permissions interact with roles.