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 Stream → Overlays (/dashboard/overlays). You'll see a grid of every overlay on your account with its canvas resolution, plus a Search Overlays box and folders for grouping. The New Overlay button in the top right also shows how many overlays you have against your plan limit (for example New Overlay 2/5).

Each overlay card has an Edit button, a Copy Link button, and an overflow menu with Insert Overlay, Rename, Move overlay, Overlay access, Revoke token, and Delete.

Quick start

1. Go to Stream → 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. Lumio immediately offers the finished browser-source URL — copy it right there.
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. Paste the copied URL into OBS as a Browser Source.

Resolution presets

1920×1080 (Landscape), 1080×1920 (Portrait / TikTok), 1280×720 (720p), 2560×1440 (1440p), or Custom with your own width and height. The background is either Transparent or a custom colour.

Folders

At the root of the overlays grid you can create folders to group overlays:

• Create folder makes a new folder; folder names must be unique.
• Open a folder to see the overlays inside it. Only root shows folders.
• The folder's own menu offers Rename folder and Delete folder — deleting a folder moves the overlays inside it back to root, it does not delete them.
• Move overlay on an overlay card lets you pick a target folder (or Root).

The search box filters both overlays and, at root, folders.

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 shows all widget extensions installed on the account. Built-in system widgets are pre-installed; additional widgets can be found in the Extension Store.

Built-in Widget	What it does
Alert Box	Animated popups for follows/subs/cheers/raids/redemptions.
Chat Box	Live chat feed with platform badges.
Event List	Scrolling list of recent follows, subs, cheers, raids, etc. Filter per-platform.
Spotify Now Playing	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.
Browser Source	Headless layer that talks to the OBS Browser Source API for scene control.

The number of overlays and of standalone widget instances is limited by plan (overlays — Free: 1, Pro: 5; widgets — Free: 3, Pro: 20). Lumio admins can override these limits per account.

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 — any change you make in the editor appears instantly. Safe to use during editing only.
/overlay/\{key\}?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).

The overlay token

The production URL carries the overlay's own access token — you do not create a popout token for it, and you never assemble the URL by hand. Copy Link on the overlay card (or Copy URL in the Insert Overlay dialog) hands you the complete, ready-to-paste URL.

Two things follow from that:

1. Anyone holding that URL can render your overlay. Treat it like a password — never show it on stream.
2. Revoke token (in the overlay's menu) invalidates the current URL immediately. The confirmation says it plainly: your OBS browser source stops working until you click Copy Link again and update OBS. Use it if a laptop is lost or a collaborator leaves.

Popout tokens are a different credential entirely, used for the /popout/* dashboard views — see Tokens.

Browser source setup

1. In Stream → Overlays, open the overlay's menu and click Insert Overlay. The dialog shows the exact canvas size and two ways to get the overlay into OBS.
2. Either drag and drop the entry straight into OBS, or click Copy URL and paste it into a new browser source.
3. In OBS: Sources > + > Browser. Paste the URL.
4. Set Width and Height to match the overlay's canvas (e.g. 1920 and 1080).
5. Leave Custom CSS empty unless you know you need it.
6. Enable Control audio via OBS and Shutdown source when not visible, as the dialog recommends.
7. Click OK. The overlay should render against a transparent background over your scene.

If nothing shows up: right-click the source > Interact and check for errors — usually a revoked token, meaning you need to copy the URL again.

Sharing an overlay temporarily

The Insert Overlay dialog also has a Share with Others section for handing an overlay to a collaborator or a backup streaming PC without giving away your permanent URL:

• Pick an expiry — 1h, 3h, 6h, 12h, or 24h — and click Create Shared Link. The dialog shows exactly when the link will expire.
• Active Links lists every link you created with its Active / Expired status, when it was created, and when it expires. You can copy it, extend it, or revoke it.

Per-overlay access

Overlay access in the overlay's menu controls who on your account can reach that specific overlay:

• Search for a person and grant them Viewer or Editor, or set No access.
• Channel admins always have access.
• No access blocks a user even if their channel-wide role would otherwise let them in; Viewer / Editor grants access to users who have no channel role at all.

Managing this needs the per-overlay access permissions — overlays:access-read (view access entries and candidates), overlays:access-grant (set a user's access), and overlays:access-revoke (remove a user's access) — which Owner and Administrator hold by default.

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." Open Insert Overlay → Share with Others and create a shared link with the shortest expiry that covers the session. Revoke it from Active Links when they're done. For a permanent collaborator on your account, use Overlay access and give them Editor on just that overlay instead.

"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, manage folders	overlays:edit
Delete an overlay	overlays:delete
View per-overlay access entries and candidates	overlays:access-read
Grant a user per-overlay access	overlays:access-grant
Revoke a user's per-overlay access	overlays:access-revoke

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.
• Use folders once you pass a handful of overlays — one per scene set (Live, BRB, Events) keeps the grid readable.
• Use a shared link, not your real URL, whenever someone else needs the overlay temporarily.

Troubleshooting

Empty/blank overlay in OBS. Usually the overlay token was revoked. Open the URL in a regular browser tab first — you should see the overlay render. If not, click Copy Link on the overlay card for a fresh URL and update OBS.

Alerts never fire in production. Check that the Alerts layer is visible (eye icon) and not locked under another layer. Then verify on Stream → 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.

"403 — Access token required" error. You loaded /overlay/\{key\} without the ?token=… part. Use the full URL from Copy Link rather than typing the path by hand.

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.