Meeting Layout
The meeting participants will be presented in an equally distributed tiled video layout where Eyeson takes care to always update the stream depending on the number of users. However in some cases you might want to assign specific users to a video position. To switch back to auto layout you can send layout auto with no further options.
The custom Eyeson podium layout can be set to one, two, four or nine participants. This is
controlled by the users parameter: Provide a user identifier and the specific user will be
placed on this position. Use an empty string "" to assign no-participant and keep a spot free.
This free spots will be filled if you choose the auto layout. Additionally you can choose to
activate voice detection that will replace the spots with participants that have said something
recently. If you choose layout custom the free spots will not be filled and you can use them to
show some background using the media inject feature.
Besides layouts that are selected by the number of users there are some named layouts that can be applied. Those will not provide equal distributed position but show some participants in an expanded view.
Note that layouts are not available when using the SFU mode, so set the room configuration properly or take care to have more than two participants.
POST /rooms/<access_key>/layout
RESPONSES 200 OK, 400 BAD REQUEST, 404 NOT FOUND, 405 METHOD NOT ALLOWED, 410 GONE
layout
Type: STRING (optional)
Value: auto or custom.
Default: custom
name
Type: STRING (optional)
Use a named layout.
Current layouts are: one, two, four, six, nine, and the presentation layouts present-lower-3, present-upper-6, present-two-upper-6, present-upper-right-9 and present-vertical-9. See the list below for more examples.
map
Type: STRING or LIST (optional)
Define a custom layout. Max. 10 boxes. JSON formatted string or list.
For example "[[0,0,640,360,\"contain\"],[...]]".
See custom layout map API for more details.
users
Type: LIST (optional)
List of podium user_ids, a custom layout position identifier or an empty string for an empty spot.
show_names
Type: BOOLEAN (optional)
Default: true
Show display names in video.
voice_activation
Type: BOOLEAN (optional)
Fill empty spots by voice detected activation.
audio_insert
Type: STRING (optional)
Values: enabled, disabled or audio_only
Default: audio_only
Show audio insert.
audio_insert_position[x]
Type: NUMBER (optional)
X position value of the audio insert.
audio_insert_position[y]
Type: NUMBER (optional)
Y position value of the audio insert.
Example for Layout
Using curl to set the "four" layout and assign 4 participants by their user_id to each position.
$ curl -X POST \
-d "layout=custom" \
-d "name=four" \
-d "users[]=USER_ID_A" \
-d "users[]=USER_ID_B" \
-d "users[]=USER_ID_C" \
-d "users[]=USER_ID_D" \
https://api.eyeson.team/rooms/<ACCESS_KEY>/layout
Reset to auto layout.
$ curl -X POST \
-d "layout=auto" \
https://api.eyeson.team/rooms/<ACCESS_KEY>/layout
List of predefined layouts
Here's an extract of layouts that can be set via the name parameter. The addition *-aspect-fit
enables object-fit: contain for the dedicated presentation spot. That means the video content
is resized to fit into the podium spot while maintaining its aspect ratio.
- 4:3 default
- 16:9 widescreen
| Preview | Layout name | Aspect-fit layout name | Aspect-fit related spots |
|---|---|---|---|
 | one | aspect-fit | 1 |
 | two | - | - |
 | four | - | - |
 | six | - | - |
 | nine | - | - |
 | present-lower-3 | present-lower-3-aspect-fit | 1 |
 | present-upper-6 | present-upper-6-aspect-fit | 1 |
 | present-two-upper-6 | present-two-upper-6-aspect-fit | 1, 2 |
 | present-upper-right-9 | present-upper-right-9-aspect-fit | 1 |
 | present-vertical-9 | present-vertical-9-aspect-fit | 1 |
 | present-lower-4-spaced | present-lower-4-spaced-aspect-fit | 1 |
 | - | present-four-upper-6-aspect-fit | 1, 2, 3, 4 |
 | mobile-center-8 | - | - |
| Preview | Layout name | Aspect-fit layout name | Aspect-fit related spots |
|---|---|---|---|
 | one | aspect-fit | 1 |
 | two | - | - |
 | four | - | - |
 | six | - | - |
 | nine | - | - |
 | present-lower-3 | present-lower-3-aspect-fit | 1 |
 | present-upper-6 | present-upper-6-aspect-fit | 1 |
 | present-two-upper-6 | present-two-upper-6-aspect-fit | 1, 2 |
 | present-upper-right-9 | present-upper-right-9-aspect-fit | 1 |
 | present-vertical-9 | present-vertical-9-aspect-fit | 1 |
 | present-lower-4-spaced | present-lower-4-spaced-aspect-fit | 1 |
 | - | present-four-upper-6-aspect-fit | 1, 2, 3, 4 |
 | mobile-center-8 | - | - |
Widescreen has to be set via the room parameter options[widescreen] which is false by default.
If you can’t find a layout that suits your needs, please feel free to reach out to us.
Custom Layout
The layout map feature offers the flexibility for custom solution. In this case, you don't have to use Eyeson's standard layouts. Simply choose a custom name for the name parameter and fill out the map parameter as desired, and you're good to go.
Keep track of the amount of map indices [20, 80, 400, 400, "auto"] and user parameters "users[]=" to ensure the right person is at their designated spot.
- bash
- shell
- node
export ACCESS_KEY=123...
export USER_ID1=123...
$ curl -X POST \
-d "name=custom-map" \
-d "map=[[20, 80, 400, 400, \"auto\"],[440, 160, 400, 400, \"contain\"],[860, 240, 400, 400, \"cover\"]]" \
-d "users[]=" \
-d "users[]=$USER_ID1" \
-d "users[]=" \
-d "layout=auto" \
"https://api.eyeson.team/rooms/$ACCESS_KEY/layout"
SET ACCESS_KEY=123...
SET USER_ID1=123...
$ curl -X POST ^
-d "name=custom-map" ^
-d "map=[[20, 80, 400, 400, \"auto\"],[440, 160, 400, 400, \"contain\"],[860, 240, 400, 400, \"cover\"]]" ^
-d "users[]=%USER_ID1%" ^
-d "users[]=" ^
-d "users[]=" ^
-d "layout=auto" "https://api.eyeson.team/rooms/%ACCESS_KEY%/layout"
import fetch, { FormData } from 'node-fetch';
const ACCESS_KEY = '123...';
const USER_ID1 = '123...';
const url = 'https://api.eyeson.team/rooms/' + ACCESS_KEY + '/layout';
const layout_map = JSON.stringify([
[20, 80, 400, 400, "auto"],
[440, 160, 400, 400, "contain"],
[860, 240, 400, 400, "cover"]
]);
const formData = new FormData();
formData.set('name', 'custom-map');
formData.set('map', layout_map);
formData.append('users[]', '');
formData.append('users[]', USER_ID1);
formData.append('users[]', '');
formData.set('layout', 'auto');
await fetch(url, { method: 'POST', body: formData });
Fitting the video into the element
Each index in the map parameter represents a spot for an active webcam participant. Along with the coordinates [x, y, width, height], you can specify how the participant video is placed in the spot or just omit this part entirely. The default is cover and additional choices are contain & auto.
cover behaves like the css object-fit value, scaling content to maintain its aspect ratio
while covering the whole spot.
contain is another object-fit value. The difference is the content fits within the spot,
also called letterboxed.
auto is an exception. It chooses between the previous two types based on the video
source's aspect ratio. For instance, with a narrow video source like a vertical smartphone
camera, it translates to contain.
Figure 2. Visualization of the example map showcasing the same video source occupying various spots with corresponding object-fit values.
Ensure all spots are within the video stream, either they fit in 1280x720 (widescreen) or 1280x960 (standard).
If you are unsure about the coordinates in the map parameter, you can use this visualising helping tool.