Skip to content
manipulating the video layout
Christoph LipautzMarch 22, 20212 min read

Custom layouts & voice activation in a videomeeting

One advantage of the eyeson single stream is that you can change the video podium layout without the need for client-side updates. With the latest release of the eyeson API we extended this feature and added support of voice detect activation for the podium positions, lets have a closer look.

Setup a Meeting

The following sections use the widely distributed Unix tool curl and to ease the parsing of the JSON responses also jq, both are available for many Linux distributions. Lets start a meeting with disabled SFU mode and test different layouts and options.

$ which curl
$ which jq

# Start a meeting for room "demo" with user named "demo1"
$ API_KEY=... curl -X POST \
  -H "Authorization: $API_KEY" \
  -d "id=demo" \
  -d "name=Layout Demo" \
  -d "user[name]=demo1" \
  -d "options[sfu_mode]=disabled" \
  "" | jq ".links.gui, .access_key,"

Now we need to remember the access key, id of the user, and open the URL to the default web UI in any browser. You can export these details into environment variables $ export ACCESS_KEY=z9CaljR... and $ export USER1=605.... In order to see different layouts, we should add several more users, export their user ids $ export USER2=... and open the web UI URLs in the same browser as before.

default video layout

To set the first custom layout, we choose auto-layout to fill up empty positions of the podium and choose them using voice detection.

# Update the podium layout using an empty space and user demo1, fill the empty
# space by voice activation.
$ curl -X POST \
  -d "layout=auto" \
  -d "users[]=" \
  -d "users[]=$USER1" \
  -d "voice_activation=true" \

You end up with a layout for two speakers, the right one is fixed and the left one will be replaced by any participant that has been active recently. Test the new layout by mute/unmute different participants.


You can choose between layouts of one, two, four, or nine positions using the parameter users. When choosing the layout mode auto any free space will be filled automatically, whereas in the mode custom it will stay empty and fixed.

The later can be useful if you set some background image and want to display a logo or similar in a fixed position without using an overlay on the video.

# Set a background image
$ curl -X POST \
  -d "url=" \
  -d "z-index=-1" \

# Set a custom fixed layout with empty space and three users
$ curl -v -X POST \
  -d "users[]=" \
  -d "users[]=$USER1" \
  -d "users[]=" \
  -d "users[]=" \
  -d "users[]=" \
  -d "users[]=" \
  -d "users[]=$USER2" \
  -d "users[]=" \
  -d "users[]=$USER3" \
  -d "layout=custom" \
  -d "show_names=false" \

custom videomeeting layout

Remember that you can always switch back to the default auto mode by skipping the users' parameter.

# Reset layout
$ curl -X POST \
  -d "layout=auto" \

If you have a suggestion and use-case for a new podium layout do not hesitate to create a GitHub issue, containing a box description and a mockup. For the calculation note that the video has a total width of 1280 and a height of 960.