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 + 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, follows your light or dark theme, and has four regions:

• Toolbar (top): panel toggles, Snap, zoom out / zoom in with the current zoom level, Save (a dot marks unsaved changes) and close. Ctrl/Cmd + S saves; Ctrl/Cmd + \ or the fullscreen button 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, or focus a row's grip and use Space and the arrow keys. 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 buttons in the toolbar; when the zoomed canvas is larger than the window, scroll to reach the rest. 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.).

On a narrow window (below 768 px) both side panels start closed and open over the canvas; use Layers and Properties in the toolbar to show them.

Below the canvas you have:

• A + 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 Live preview indicator 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. Chat Box, Alert Box, Event List, Text, Image and Timer are installed for new accounts. Spotify Now Playing and Browser Source can be installed from the Extension Store, alongside third-party widgets.

Built-in Widget	What it does
Alert Box	Animated popup for each selected live event (follows, subs, gifts, cheers, raids, KICKs, Super Chats, rewards, Hype Train, polls, tips), one after another for the set duration. Choose a sound from your account library to play once with each alert in this browser source.
Chat Box	Live chat from your connected Twitch, YouTube and Kick channels, with badges and emotes. A Twitch ban removes the banned user's messages.
Event List	List of the latest selected live events (follows, subs, gifts, cheers, raids, KICKs, Super Chats, rewards, Hype Train, polls, tips). You can set a maximum count, fade-out, animations and a sound that plays when a selected event arrives.
Spotify Now Playing	Now-playing card (cover art, title, artist, progress). Requires a Spotify connection and the widget installed on the account. In OBS it shows the current track as soon as the overlay or widget loads, also after a reload; otherwise it appears with the next track. Show Album Art, Show Progress Bar, and Hide When Paused control its display. Pause and play from Lumio update it immediately. A pause in the Spotify app reaches it within about 5 seconds, a resume within about 30 seconds (Lumio checks Spotify less often while paused).
Text	A static text label with font, size, weight, colour, alignment and line height.
Image	Shows an image - logos, frames, decorations - with object-fit and corner-radius settings. Upload a PNG, JPEG, GIF, WebP or AVIF (up to 5 MB) in the widget settings, or pick one you uploaded earlier. Only your channel's overlays and widgets can load it; it has no public link, a shared overlay link shows no uploaded image, and a deleted upload disappears on the next load. A pasted URL still works for platform images (Twitch, YouTube, Kick or Discord emotes, badges and avatars) and data:image/… URLs; other web addresses do not load.
Timer	Countdown (duration or target date) or stopwatch. Press Start in the layer's settings and save, so the timer keeps running when the browser source reloads; an unstarted timer starts each time the page loads.
Browser Source	Invisible marker layer for overlays used as an OBS browser source. It renders nothing and reacts to no OBS event. It is not installed automatically.

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.

A test event reaches OBS only when you choose to show it on stream while sending it (see Test events). Alert Box, Event List and Spotify Now Playing then show it with an orange TEST label, so viewers never take it for a real follow, sub or donation. The dashboard previews show every test, with the same label.

Chat Box receives live chat only when its installed version declares chat:read; Alert Box, Event List and Spotify Now Playing receive platform events only with events:read. Alerts and Event List play a selected account sound locally in the browser source when their manifest declares sounds:play. Audio from one browser source does not broadcast to other overlays. The stream uses each layer's saved settings and receives later saves without restarting OBS.

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. Alert Box and Event List have event-type toggles per platform; Event List also has direction, text order and fade-out).
• Font - the font you pick (Text, Timer, Alert Box, Event List and extension widgets with a font setting) also shows on the stream, in overlays and standalone widgets. Lumio loads it from its own font service, so OBS contacts no third party such as Google. Each layer loads at most four fonts; a font name that is not in the Google Fonts catalog shows the fallback font.

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.