Setting the Layout of your SignalWire Video Calls

SignalWire Video API allows you to host real-time video calls and conferences on your website. In this guide, we'll learn to set layouts during video calls.

SignalWire video calls are composited at SignalWire servers so that everyone gets the same video feed. This means that layout changes are reflected instantly in each participant’s video stream. Each participant sees exactly the same video layout once the layout switch occurs.

Requesting the necessary permission

Changing layouts is a privilege that you must explicitly request when asking the SignalWire Video REST API for an access token. The endpoint to request access tokens is described in the SignalWire Video API reference guide.

In particular, you need to specify a room.set_layout permission when requesting the token. This should happen in the server-side, ideally after you verify that the user requesting the access token actually has the privilege to change your video call's layout. In the Node.js/Express.js example below, we are indiscriminately handing out room.set_layout permission to anyone who requests a token. This is only to keep the code simple, and doesn't reflect real world usage."/get_token", async (req, res) => {
  let { user_name } = req.body;
  console.log("Received name", user_name);
  try {
    let token = await
      apiurl + "/room_tokens",
        room_name: ROOMNAME,
        permissions: ["room.set_layout"]
      { auth }
    return res.json({ token: });
  } catch (e) {
    return res.sendStatus(500);
curl --request POST \
     --url \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic bmV2ZXIgZ29ubmEgZ2l2ZTp5b3UgdXA=' \
     --header 'Content-Type: application/json' \
     --data '
     "permissions": [
     "room_name": "example_room",
     "user_name": "example_user"

Changing Layout with the Video JS SDK

As described in the SignalWire Video JS SDK guide, you first want to instantiate a room session with the access token acquired in the previous section.

const roomSession = new SignalWire.Video.RoomSession({
  token: '<Your JWT with room.set_layout permission>',
  rootElement: document.getElementById('myRoot'), // an html element to display the video
  audio: true,
  video: true,

try {
  await roomSession.join()
} catch (error) {
  console.error('Error', error)

The roomSession object exposes methods for getting and setting layouts.

The Room.getLayouts() method

To know what layouts the video feed supports, use the Room.getLayoutList() method.

roomSession.getLayouts().then(list => console.log(list.layouts));

    Outputs an array like:

The Room.setLayout() method

To set the video call's layout to one of the layouts from the layout's list, use the Room.setLayout() method.

roomSession.setLayout({name: "10x10"}).then(output => console.log(output));

If calling the .setLayout() method throws an insufficient permission error, then the access token you are using to instantiate the Room object wasn't given the room.set_layout permission. Learn more about the access tokens permission list in the docs.


You can try using and tinkering with the sample program below without leaving your browser on CodeSandbox:

This demo was built over the Getting Started with the SignalWire Video API sample application. If you're having trouble understanding this demo, you should read the getting started guide.

Key Points

  1. Each participant of the video call sees the same video stream, so layout changes are reflected uniformly across all participants.
  2. Only the users with the room.set_layout permission can change the video feed’s layout. This permission needs to be requested when requesting for the room’s access token.
  3. You can get the list of supported layouts using Room.getLayouts() method.
  4. You can change the video call's layout using Room.setLayout({name: "<layout-name>"}).

Did this page help you?