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 ● You can use it alone or omit it completely (defaults to auto) ● It works with the name parameter without requiring a users array ● It works with the map parameter without requiring a users array ● When using a users array, you must include either a name or map parameter
custom	Maintains manually assigned positions; empty positions remain vacant ● Must be used with a layout definition (name or map parameter) and a users array ● When using name parameter alone (without users array), produces an error ● The users array should contain entries matching the number of positions in the layout

map and name Interaction

When providing both map and name parameters:

• Name can be any arbitrary STRING value
• The provided name is stored and returned with the layout definition
• This enables tracking which layout is currently active in your application
• Common implementation: Define several layout maps with descriptive names for easy reference and switching

Empty custom Layout Use Case

Setting a custom layout with empty positions is permitted when:

• Layout is set to custom
• name parameter is specified
• users array is included (even if some positions are empty)

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

export ACCESS_KEY=...
curl -X POST \
  -d "layout=auto" \
  -d "name=one" \
  -d "users[]=" \
  -d "audio_insert=enabled" \
  -d "audio_insert_position[x]=20" \
  -d "audio_insert_position[y]=670" \
  "https://api.eyeson.team/rooms/$ACCESS_KEY/layout"

node sdk

const accessKey = '...';
const eyeson = new Eyeson();
const user = await eyeson.getUser(accessKey);
await user.setLayout({
  layout: 'auto',
  name: 'one',
  users: [''],
  audio_insert: 'enabled',
  audio_insert_position: { x: 20, y: 670 },
});

go sdk

accessKey := "..."
userService, _ := eyeson.NewUserServiceFromAccessKey(accessKey)
userService.SetLayout(eyeson.Auto,
  &eyeson.SetLayoutOptions{
    LayoutName: "one",
    Users: []string{""},
    AudioInsert: &eyeson.AudioInsert{
      Config: eyeson.Enabled,
      Position: &eyeson.AudioInsertPosition{
        X: 20,
        Y: 670,
      },
    },
    ShowNames: true,
  })

php sdk

$accessKey = '...';
$eyeson = new Eyeson();
$layout = $eyeson->layout($accessKey);
$layout->apply([
  'layout' => 'auto',
  'name' => 'one',
  'users' => [''],
  'audio_insert' => 'enabled',
  'audio_insert_position' => ['x' => 20, 'y' => 670]
]);

Example for Layout

Set the custom layout and assign 4 participants by their user IDs.

curl

export ACCESS_KEY=...
curl -X POST \
  -d "layout=custom" \
  -d "name=custom-map" \
  -d "users[]=drone" \
  -d "users[]=captain" \
  -d "users[]=dispatcher" \
  -d "users[]=officer" \
  -d "map=[[0, 0, 1280, 540, \"cover\"],[0, 540, 426, 180, \"cover\"],[426, 540, 426, 180, \"cover\"],[852, 540, 428, 180,\"cover\"]]" \
  -d "show_names=true" \
  -d "voice_activation=false" \
  "https://api.eyeson.team/rooms/$ACCESS_KEY/layout"

node sdk

const accessKey = '...';
const eyeson = new Eyeson();
const user = await eyeson.getUser(accessKey);
await user.setLayout({
  layout: 'custom',
  name: 'custom-map',
  users: ['drone', 'captain', 'dispatcher', 'officer'],
  map: JSON.stringify([
    [0, 0, 1280, 540, 'cover'],
    [0, 540, 426, 180, 'cover'],
    [426, 540, 426, 180, 'cover'],
    [852, 540, 428, 180, 'cover'],
  ]),
  show_names: true,
  voice_activation: false,
});

go sdk

accessKey := "..."
userService, _ := eyeson.NewUserServiceFromAccessKey(accessKey)
userService.SetLayout(eyeson.Custom,
  &eyeson.SetLayoutOptions{
    LayoutName: "custom-map",
    Users: []string{"drone", "captain", "dispatcher", "officer"},
    LayoutMap: &eyeson.LayoutMap{
      Positions: []eyeson.LayoutPos{
        {X: 0, Y: 0, Width: 1280, Height: 540, ObjectFit: eyeson.Cover},
        {X: 0, Y: 540, Width: 426, Height: 180, ObjectFit: eyeson.Cover},
        {X: 426, Y: 540, Width: 426, Height: 180, ObjectFit: eyeson.Cover},
        {X: 852, Y: 540, Width: 426, Height: 180, ObjectFit: eyeson.Cover},
      },
    },
    ShowNames: true,
    VoiceActivation: false,
  })

php sdk

$accessKey = '...';
$eyeson = new Eyeson();
$layout = $eyeson->layout($accessKey);
$layout->apply([
  'layout' => 'custom',
  'name' => 'custom-map',
  'users' => ['drone', 'captain', 'dispatcher', 'officer'],
  'map' => json_encode([
    [0, 0, 1280, 540, 'cover'],
    [0, 540, 426, 180, 'cover'],
    [426, 540, 426, 180, 'cover'],
    [852, 540, 428, 180, 'cover']
  ]),
  'show_names' => true,
  'voice_activation' => false
]);

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.

curl

export ACCESS_KEY=...
export USER_ID=...
curl -X POST \
  -d "layout=custom" \
  -d "name=custom-map" \
  -d "users[]=" \
  -d "users[]=$USER_ID" \
  -d "users[]=" \
  -d "map=[[20, 80, 400, 400, \"auto\"],[440, 160, 400, 400, \"contain\"],[860, 240, 400, 400, \"cover\"]]" \
  "https://api.eyeson.team/rooms/$ACCESS_KEY/layout"

node sdk

const userId = '...';
const accessKey = '...';
const eyeson = new Eyeson();
const user = await eyeson.getUser(accessKey);
await user.setLayout({
  layout: 'custom',
  name: 'custom-map',
  users: ['', userId, ''],
  map: JSON.stringify([
    [20, 80, 400, 400, 'auto'],
    [440, 160, 400, 400, 'contain'],
    [860, 240, 400, 400, 'cover'],
  ]),
});

go sdk

userId := "..."
accessKey := "..."
userService, _ := eyeson.NewUserServiceFromAccessKey(accessKey)
userService.SetLayout(eyeson.Custom,
  &eyeson.SetLayoutOptions{
    LayoutName: "custom-map",
    Users: []string{"", userId, ""},
    LayoutMap: &eyeson.LayoutMap{
      Positions: []eyeson.LayoutPos{
        {X: 20, Y: 80, Width: 400, Height: 400, ObjectFit: eyeson.Autofit},
        {X: 440, Y: 160, Width: 400, Height: 400, ObjectFit: eyeson.Contain},
        {X: 860, Y: 240, Width: 400, Height: 400, ObjectFit: eyeson.Cover},
      },
    },
    ShowNames: true,
  })

php sdk

$userId = '...';
$accessKey = '...';
$eyeson = new Eyeson();
$layout = $eyeson->layout($accessKey);
$layout->apply([
  'layout' => 'custom',
  'name' => 'custom-map',
  'users' => ['', $userId, ''],
  'map' => json_encode([
    [20, 80, 400, 400, 'auto'],
    [440, 160, 400, 400, 'contain'],
    [860, 240, 400, 400, 'cover']
  ])
]);

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