Overlays

An overlay is a graphic drawn into the video itself: a channel logo in the corner for the whole broadcast, or a sponsor’s promotion that appears for a minute when you choose. Because it is part of the picture, every viewer sees it, on every player, and an ad blocker has nothing to remove.

Overlays are part of ad insertion and need a licence that includes it, or the trial.

Two kinds

	Shown	Typical use
Persistent	For the whole broadcast	A channel logo, a watermark
Timed	When you switch it on, until you switch it off	A sponsor message, a promotion

Preparing the graphic

PNG with transparency for a still image.
WebM with an alpha channel for an animated one. Overlays are silent; any audio in the file is ignored.

Up to 32 MB. A file without transparency is drawn as an opaque rectangle. Position and size are given as a share of the picture, not in pixels, so one graphic fits every rendition of a stream, from 1080p down to 360p.

Adding an overlay

In the dashboard, open the application’s Overlays tab and choose New overlay: pick the file, its position on the grid (any corner, the middle of the top or bottom edge, or the centre), the size and opacity, and whether it is persistent.

Through the API, the file goes in the body and the placement in the query:

curl -b jar -X POST \
  "http://localhost:9001/api/v1/apps/default/overlays/spring-promo?anchor=bottom-right&width_pct=30&margin_pct=4&opacity=0.9&persistent=false" \
  -H 'content-type: image/png' --data-binary @spring-promo.png

Setting	Values	Default
`anchor`	`top-left`, `top-centre`, `top-right`, `centre`, `bottom-left`, `bottom-centre`, `bottom-right`	`bottom-left`
`width_pct`	Width as a percentage of the picture’s width	`25`
`margin_pct`	Distance from the edges, as a percentage	`4`
`opacity`	`0` to `1`	`1`
`persistent`	`true` for always on, `false` for timed	`false`

Putting it on a stream

An overlay is drawn by a stream only once it is attached to it. In the dashboard, use Overlays on this stream in the stream’s menu. Through the API, list the overlays the stream carries:

curl -b jar -X PUT http://localhost:9001/api/v1/apps/default/stream-settings/channel1 \
  -H 'content-type: application/json' -d '{"overlays": ["logo", "spring-promo"]}'

The overlays are built into the stream’s encoder, so attaching them applies the next time the stream goes live. Send an empty list to remove them all.

Showing and hiding

Persistent overlays are on for the whole broadcast. Timed ones start hidden; switch one on and off while the stream is live, with no interruption for viewers:

# Show it
curl -b jar -X POST http://localhost:9001/api/v1/apps/default/streams/channel1/overlay \
  -H 'content-type: application/json' -d '{"overlay": "spring-promo", "on": true}'

# Hide it
curl -b jar -X POST http://localhost:9001/api/v1/apps/default/streams/channel1/overlay \
  -H 'content-type: application/json' -d '{"overlay": "spring-promo", "on": false}'

The dashboard has the same switch in each live stream’s Overlay menu. With adaptive bitrate on, every rendition shows or hides it together.

Switching live uses FFmpeg’s zmq filter. If the server’s FFmpeg was built without it, the dashboard and the API say so: persistent overlays still work, because they are part of the encoder from the start, but timed ones cannot be switched until FFmpeg is rebuilt with --enable-libzmq. The FFmpeg in the Debian and Ubuntu packages and in the container image includes it.

What it costs

Drawing into the picture means encoding it, so a stream that carries an overlay is encoded rather than passed through, even at the top quality. With adaptive bitrate off, that is one encode at the stream’s own resolution. That CPU is spent only on the streams that carry overlays; every other stream is still passed through untouched.