Custom layout map API

Developers are free to create and apply their own custom layout maps whenever they need it! You need a special layout for your app? Just go ahead and create it!

The existing layout endpoint is extended with the new parameter map. The map is a JSON stringified list of box-definition-lists with x, y, width, height, and objectFit definitions for each box.

Here's an example map that places 2 boxes (640x360px) above eachother in the center of the video podium.

[
    [320, 0, 640, 360, "auto"],
    [320, 360, 640, 360, "auto"]
]

Each box's parameters are [x, y, width, height(, objectFit)]

Using curl, it can be sent to the API like the following.

$ curl -X POST \
-d "layout=auto" \
-d "name=custom-map" \
-d "users[]=<USER_A>" \
-d "users[]=<USER_B>" \
-d "map=[[320,0,640,360,\"auto\"],[320,360,640,360,\"auto\"]]" \
https://api.eyeson.team/rooms/<ACCESS_KEY>/layout

Note the value for map is a JSON formatted string

Rules

A few rules apply to the new parameter.

1. The number of boxes is limited to 10
2. All boxes must be inside of the video-podium
3. ObjectFit values are "cover", "contain", and "auto". Default is "cover" and can be omitted

info

In case of an invalid map, the API returns 400 Bad Request with content:

{"error":"Layout configuration is invalid"}

Video-podium size

The video-podium has the size 1280x960 pixels in 4:3 or 1280x720 pixels in widescreen format.

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

ObjectFit

There are currently 3 types available for objectFit.

"cover" is the default and it fully fills the box with the video content. This means that the video is zoomed and oversized parts will be cropped.

"contain" displays the whole video content inside the box. Black bars might appear.

"auto" is a special type. It translates to default "cover", but "contain" for narrow portrait video content (mainly used by mobile devices).

Layout name

The layout name is usually used to choose one of our predefined layouts, but if the map parameter is present, the name can be any custom name.

JSON format

As mentioned above, the value for map is a JSON formatted string.

eyesonJS

import eyeson from 'eyeson';

eyeson.send({
    type: 'set_layout',
    params: {
        layout: 'auto',
        name: 'custom-map',
        users: [USER_A, USER_B],
        map: JSON.stringify([
            [320, 0, 640, 360, 'auto'],
            [320, 360, 640, 360, 'auto']
        ]),
    },
});

node

const Eyeson = require('eyeson-node');
const eyeson = new Eyeson({ apiKey: API_KEY });

const room = await eyeson.join(username, roomIdentifier, options);
await room.waitReady();

await room.setLayout({
    layout: 'auto',
    name: 'custom-map',
    users: [USER_A, USER_B],
    map: JSON.stringify([
        [320, 0, 640, 360, 'auto'],
        [320, 360, 640, 360, 'auto']
    ]),
});

php

$eyeson = new Eyeson($API_KEY);
$room = $eyeson->join(username, roomIdentifier);
if (!$room->isReady()) {
  $room = $eyeson->waitReady($room);
}
$layout = $eyeson->layout($room);
$layout->apply([
    'layout' => 'auto',
    'name' => 'custom-map',
    'users' => [USER_A, USER_B],
    'map' => json_encode([
        [320, 0, 640, 360, 'auto'],
        [320, 360, 640, 360, 'auto']
    ]),
]);

Create your own

Enter your own custom layout map in the following form. Get instant preview and verify the values.

Map
[ [320, 0, 640, 360, "auto"], [320, 360, 640, 360, "auto"] ]

Widescreen

Preview

Contact

If you have a question or want to share any feedback, do not hesitate to create a ticket on GitHub.