Skip to main content

Layers: Background and Foreground / Overlay

You can display any data content inside your video using the Eyeson layer service.

  1. Generate and send an image directly, or
  2. provide a public URL to the image. When using an image as overlay, make sure that it is transparent.
info

Any Eyeson room video has a resolution of either 1280x960 pixels (960p in default) or 1280x720 pixels (HD in widescreen mode).

warning

Ensure any overlay file uploaded is an alpha interlaced PNG or WebP image with a corresponding resolution to avoid any issues. Avoid using JPEG files as overlays.

tip

When using layers, you may want to disable SFU mode in the default room configuration, as it will transport individual streams for single and two participants without showing layer media.

Eyeson Layers Diagram

Add Content to Layer​

Supported image types are: PNG, WebP, and JPEG. Background layer has no transparency, foreground layer / overlay can be transparent.

info

The positioning of image smaller than the call resolution of either 1280x960 pixels (960p in default) or 1280x720 pixels (HD in widescreen mode) follows the following rule:

  • Background: The image will be centered and scaled to fit if too large.
  • Foreground / Overlay: The image will be positioned in the left upper corner and not be scaled.
info

Transparent parts of an image in the background layer are rendered white.

warning

Please remember that JPEG does not support transparency.

warning

Overlay images larger than the resolution will throw an Error 400 BAD REQUEST

POST /rooms/`ACCESS_KEY`/layers
RESPONSES 201 CREATED, 400 BAD REQUEST, 404 NOT FOUND, 410 GONE
RECOMMENDED file or url,  z-index

file​

Type: File [binary] (optional)
File upload.

Example Req/Res: Overlay with local File
Request
curl -X POST \
  -F "file=@path/to/local/file.png" \
  -F "z-index=-1" \
  "https://api.eyeson.team/rooms/$ACCESS_KEY/layers"

No response

Example

url​

Type: URL (optional)
Public file URL.

Example Req/Res: Background Image with File URL
Request
curl -X POST \
  -d "url=https://docs.eyeson.com/img/examples/overlay_example.png" \
  -d "z-index=1" \
  "https://api.eyeson.team/rooms/$ACCESS_KEY/layers"

No response

Examples

z-index​

Type: STRING (optional)
Default: 1
Assigns images to a specific layer.

ValueDescription
1Image is placed in the foreground
-1Image is placed in the background
info

If you dont append a z-index parameter to your request, it is assumed to be 1.

id​

Type: STRING (optional)
Layer id for relation control in observer "podium_update" event.

Delete Layer Content​

DELETE /rooms/`ACCESS_KEY`/layers/`LAYER_INDEX` # clear layer, layer_index: -1 or 1
  RESPONSES 200 OK, 404 NOT FOUND, 410 GONE
Example Req/Res: Delete Background Layer Content
Request
curl -X DELETE "https://api.eyeson.team/rooms/$ACCESS_KEY/layers/-1"

No response