setLayout

setLayout(layout, positions?): Promise<void>

Switches the call to a named video layout and (optionally) places specific members into reserved positions.

The gateway’s call.layout.set verb carries no positions of its own, so when positions is provided the SDK issues a call.member.position.set per member alongside it, each keyed by that member’s own call context. These operations are not atomic: the layout is applied first, then each position sequentially, so members may briefly flash into their default slots before being moved.

Targeted members are validated upfront, though — if any of them has no member call context yet, the whole call rejects before a single request is sent and the layout is left unchanged. A member ID that is not in the call at all is skipped with a warning.

The set of valid layout names depends on the call’s room configuration and is exposed reactively via layouts$. Member position values come from VideoPosition.

Requires the setLayout capability — inspect call.capabilities$ before exposing layout controls.

Parameters

Returns

Promise<void> — resolves once the server has applied the layout and every requested position.

Throws

• InvalidParams — layout is not in the call’s available layouts.
• ParticipantNotReadyError — a targeted member’s call context has not arrived yet. Thrown before any request is sent.

Examples

Switch to a grid layout

await call.setLayout('grid-responsive', {});

Pin a member to a reserved slot

await call.setLayout('1x1-with-presenter', {
  [participantId]: 'reserved-0',
});

See

• layouts$ — observable list of available layout names.
• layout$ — currently active layout.
• layoutLayers$ — observable of position assignments.