Overlays for your audience¶
Who this is for: admins (event producers); also useful to users who want to understand what they see.
An overlay is a web page that shows only the caption text — no buttons, no menus. You drop it on top of a stream, a projector or a phone screen so your audience reads what is being said. If the word is new, see the glossary.
An overlay is the audience side of captioning. The capture page is where a speaker produces captions; the overlay is where someone else watches them. The text travels through a relay inside a room; see Relay and rooms for that idea and Choose a deployment to run the stack that includes one.
Open an overlay¶
An overlay is just a URL. The important part is the room it watches: an audience
overlay normally watches the finished output room, not the source room.
This opens the overlay that shows the output room.
https://ui.example.org/overlay.html?room=output
You rarely type that by hand. The capture page, the translate page and the editor all build overlay links for you.
| Where | What it gives you |
|---|---|
| Capture page | An overlay URL for the current room, plus a Customize Overlay button |
| Translate page | "Overlay link options" to set language, clearing and history |
| Editor | An overlay link for the finished room, plus a view-only OBS link |
With a private relay, generated links already carry the relay address and the read (viewing) token, so you do not paste tokens into the overlay yourself. Never put a write token in something your audience can see.
Treat overlay links as passwords
A private relay overlay link contains a token. Do not post it publicly or reuse it outside the event. See Relay and rooms.
Put the overlay in OBS or vMix¶
Add the overlay URL as a Browser Source, make the source the same size as your canvas (for example 1920x1080), and keep transparency enabled so only the text shows. The relay README also notes this works in vMix and similar tools.
For a private relay, use the editor's Create a view-only OBS link. It checks that the token can only read, and refuses to make a link from a publishing token.
vMix users can point a Browser Source at vmix.html instead.
This vMix overlay starts with the black highlight behind the text removed.
https://ui.example.org/vmix.html?room=output
Show captions on a phone or a second screen¶
Any browser can display an overlay, including Firefox, because it only reads text — no microphone is involved. Open the overlay link, make the tab full-screen, and hand the phone over. To keep captions pinned on top of other desktop programs, the project points to the optional Electron Capture app.
Styling and layout¶
Overlays look plain by default. You change the look by adding URL parameters
to the overlay link — short switches joined with &. These work in OBS, vMix and
other browser-source tools.
| Want to change | Parameter | Example |
|---|---|---|
| Text size | fontsize / fs |
&fontsize=48px |
| Scale the default size | scale |
&scale=1.25 |
| Font family | font |
&font=Arial,sans-serif |
| Text colour | color / fontcolor |
&color=%23fff200 |
| Transparent background | nobg / bg=transparent |
&nobg |
| Background colour | bg |
&bg=rgba(0,0,0,0.6) |
| Rounded highlight | radius |
&radius=6 |
| Horizontal position | align |
&align=center |
| Vertical position | valign |
&valign=top |
| Offset from an edge | topoffset / bottomoffset / leftoffset / rightoffset |
&bottomoffset=40 |
| Text padding | pad / padx / pady |
&padx=12&pady=4 |
| Outline | outline / outlinecolor |
&outline=2&outlinecolor=%23000 |
| Remove the text shadow | noshadow |
&noshadow |
| Overall opacity | opacity |
&opacity=0.85 |
| Speaker-label colours | labelcolor / labelbg |
&labelcolor=%23ffd500 |
| Original / translation colours | originalcolor / translationcolor |
&originalcolor=%23ccc |
For text size, numbers up to 10 are treated as em and larger numbers as px.
Spaces and quote characters in values must be URL-encoded (for example %23 for
#).
This overlay has a transparent background and a centred, yellow 48px font.
https://ui.example.org/overlay.html?room=output&nobg&color=%23fff200&fontsize=48px&align=center
For deeper changes you can load your own stylesheet with &css=URL, inject
Base64 CSS with &base64css=..., or self-host overlay.html and edit its CSS.
Control how long captions stay¶
| Parameter | Effect |
|---|---|
showtime=MS |
Clear the overlay after MS milliseconds with no new text (default 5000) |
clear |
Show only the latest line |
maxlines=N |
Keep only the most recent N lines |
maxage=MS |
Drop lines older than MS milliseconds |
intermclear=1 |
Hide finished lines while the current sentence is still arriving |
This overlay keeps the last three lines and clears quickly when the speaker stops.
https://ui.example.org/overlay.html?room=output&maxlines=3&showtime=1500
Speaker labels¶
Adding a label to the capture link tags that speaker's captions. The audience
overlay then shows the label next to the text; add &html to the overlay if the
label contains HTML.
https://ui.example.org/overlay.html?room=output&html
Still stuck on a word? See the glossary or Concepts in plain words.