Meeting Layout

Layouts are a core feature of Eyeson One View. Make sure to consult the how-tos for detailed examples.

Set a Layout

POST /rooms/`ACCESS_KEY`/layout
RESPONSES 200 OK, 400 BAD REQUEST, 404 NOT FOUND, 405 METHOD NOT ALLOWED, 410 GONE
RECOMMENDED name, users

Req/Res Example: Set a Layout

curl -X POST  -H "Content-Type: application/json" -d "{"layout": "custom", "show_names": true, "name":"four", "users[]": " "}" "https://api.eyeson.team/rooms/$ACCESS_KEY/layout"

no response

layout

Type: STRING (optional)
Default: auto
Controls the behaviour of the meeting layout. See examples below.

Value	Description
auto	Automatically sets layouts according to the number of participants
custom	Maintains manually assigned positions; empty positions remain vacant

tip

By leaving out specific spots when the layout is set to custom, you can show parts of an image in the background layer.

name

Type: STRING (optional)
Use named layouts like one, two, etc. See the list of all predefined layouts. See custom layout map for more details.

info

When the map parameter is set any name can be used.

map

Type: STRING or LIST (optional)
Defines a custom layout map. JSON formatted string or list of the format [[x, y, width, height, fitting],[...]]. See fitting behaviours below.

Example JSON for the map named TWO

[
  [0, 0, 640, 720, \"cover\"],
  [640, 0, 640, 720, \"cover\"]
]

warning

Max. 10 spots are allowed for each custom layout.

users

Type: LIST (optional)
List of user IDs in an Eyeson One View stream, a custom layout position identifier or an empty string for an empty spot.

tip

It is best practice to add a user for each spot in the layout. See the example below.

show_names

Type: BOOLEAN (optional)
Default: true
Show display names in video.

info

If the width of a spot is below 250, the names are initialed.

voice_activation

Type: BOOLEAN (optional)
Default: false
Users who are not included in the layout are automatically repositioned into the layout when they demonstrate voice activity. If no empty slot is available, a user who is currently inactive will be replaced by the incoming active voice user.

audio_insert

Type: STRING (optional)
Default: audio_only
Displays the audio activity of participants.

Value	Description
enabled	Shows audio activity inserts of all participants
disabled	Completely disables audio activity inserts
audio_only	Only shows audio activity inserts for participants who are not in the video stream.

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 Audio Insert

By adjusting the coordinates, the audio insert appears bottom left of the video stream.

$ curl -X POST \
  -d "audio_insert=audio_only" \
  -d "audio_insert_position[x]=20" \
  -d "audio_insert_position[y]=670" \
  "https://api.eyeson.team/rooms/$ACCESS_KEY/layout"

Example for Layout

Using curl to set the custom layout and assign 4 participants by their user IDs.

cURL to create a custom layout

curl -X POST \
  -d "name=custom-map" \
  -d "map=[[0, 0, 1280, 540, \"cover\"],[0, 540, 426, 180, \"cover\"],[426, 540, 426, 180, \"cover\"],[852, 540, 428, 180,\"cover\"]]" \
  -d "users[]=drone" \
  -d "users[]=captain" \
  -d "users[]=dispatcher" \
  -d "users[]=officer" \
  -d "show_names=true" \
  -d "voice_activation=false" \
  -d "layout=custom" \
  "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 spot while maintaining its aspect ratio.

4:3 default

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	-	-

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	-	-

info

Widescreen has to be set via the room parameter options[widescreen] which is false by default.

Auto Layout Behaviour

When set to auto, the layout dynamically adjusts based on participant count, automatically transitioning between predefined configurations (one, two, four, and nine) as users join or leave the meeting.

Custom Layout Map

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.

tip

It is best practice to add a user for each spot in the layout. But you can also leave out the spots empty. They are not going to be filled by participants, if the layout is set to custom.

bash

$ 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_ID" \
  -d "users[]=" \
  -d "layout=custom" \
  "https://api.eyeson.team/rooms/$ACCESS_KEY/layout"

node

import fetch, { FormData } from 'node-fetch';

const ACCESS_KEY = '...';
const USER_ID = '...';
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_ID);
formData.append('users[]', '');
formData.set('layout', 'custom');
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.

Fitting Type	Description
cover	Behaves like the css object-fit value, scaling content to maintain its aspect ratio while covering the whole spot.
contain	Another object-fit value. The difference is the content fits within the spot, also called letterboxed.
auto	An exception that chooses between the previous two types based on the video source's aspect ratio.

tip

Use auto for portrait-oriented videos (e.g. smartphone) to prevent excessive cropping. It adjusts dynamically, selecting "cover" or "contain" based on aspect ratio.

warning

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.

Examples and How-tos

• How to assign spots automatically
• How to freeze spot assignments
• How to put a user in a specific spot
• How to set the layout automatically
• How to use voice activation