Overlays

Overlays in OBS are added as a Browser Source and while often graphical tooling to build them is available it’s possible to build custom overlays with well-known web-technology like HTML, Javascript, CSS.

In the Service Setup we configured an OVERLAYS_DIR which is used to serve the files for the overlays. Every file you put into that directory is available to the public at https://your-bot.example.com/overlays/. Therefore pay attention not to put any secrets into that directory!

The bot includes some files which are merged with the files you put into that directory. If you put a file with the same name as the included, your file will overwrite the included one! Therefore you can modify included templates by just copying them into your overlay directory and changing the stuff you want changed.

Currently the following files are available in the default distribution:

debug.html - The Debug Overlay (see below for an example how to use)
eventclient.js - The EventClient Javascript library to aid you in developing overlays and communicating with the bot
sounds.html / sounds.js - The Sound-Alerts Overlay
template.html - A very simple example overlay without external dependencies

You can see the sources for these included files in the project repository.

Configuring Secrets and Parameters

As you shouldn’t put secrets in a public place the EventClient library provides a mechanism to fetch secrets from the URL hash through the paramOptionFallback method. This also is used for all configuration you can pass into the class options. Especially for the token you should use this mechaism.

As an example lets have a look at this URL path:

/overlays/debug.html#token=55cdb1e4-c776-4467-8560-a47a4abc55de&replay=true&channel=%23luziferus&maxReplayAge=720&hide=join,part

Here you can see the Debug Overlay configured with:

token - A token configured in the bot having access to the overlays permission
replay - Enabled to retrieve past events
channel - Set to #luziferus to retrieve events from my channel
maxReplayAge - Set to 720h (30d) not to retrieve events from the infinite past
hide - Set to omit join and part events (custom parameter for the Debug Overlay)

As those parameters are configured through the URL hash (#...) they are never sent to the server, therefore are not logged in any access-logs and exist only in the local URL. So with a custom overlay you would put https://your-bot.example.com/overlays/myoverlay.html#token=55cdb1e4-c776-4467-8560-a47a4abc55de into your OBS browser source and your overlay would be able to communicate with the bot.

The debug-overlay can be used to view all events received within the bot you can react on in overlays and bot rules.

Remote editing Overlays with local Editor

In order to enable you to edit the overlays remotely when hosting the bot on a server the bot exposes a WebDAV interface you can locally mount and work on using your favorite editor. To mount the WebDAV I recommend rclone. You will need the URL your bot is available at and a token with overlays permission:

# rclone obscure 55cdb1e4-c776-4467-8560-a47a4abc55de
MqO0FLdbg3txom2IpUMsVVIqnHwYDefms4EKRqoV1MGhCFkBmWnhvVRdqTyCSFtmvP-AYg

# cat /tmp/rclone.conf
[bot]
type = webdav
url = https://your-bot.example.com/overlays/dav/
user = dav
pass = MqO0FLdbg3txom2IpUMsVVIqnHwYDefms4EKRqoV1MGhCFkBmWnhvVRdqTyCSFtmvP-AYg

# rclone --config /tmp/rclone.conf mount bot:/ /tmp/bot-overlays

# code /tmp/bot-overlays

What I’ve done here is to obscure the token (rclone wants the token to be in an obscured format), create a config containing the WebDAV remote, mount the WebDAV remote to a local directory and open it with VSCode to edit the overlays. When saving the files locally rclone will upload them to the bot and refreshing the overlay in your browser / OBS will give you the new version.