Pinning participants to the layout during a conference

Participant pinning allows you to place and lock specific participants in the most prominent positions in a layout when a conference is in progress.

Participant pinning is a technology preview feature and can be enabled via Platform > Global settings > Tech preview features > Enable pinning configurations.

This topic covers:

How it works

Several steps are involved in the setting up and application of participant pinning. In summary:

  1. Add a pinning configuration file to your theme. This defines the names of the layout groups that control which participants will appear in the primary slots in the layout, and in which order they appear. This must be performed by an administrator before the conference starts.
  2. Enable the pinning configuration on a conference. You can permanently assign a pinning configuration to a VMR, or you can dynamically assign it via service configuration policy, or set it via the client REST API while the conference is in progress.
  3. Assign conference participants to the layout groups. This occurs while the conference is in progress and is what actually pins specific participants to the slots in the conference layout. You can use participant policy or the client REST API to assign a participant to a layout group.

During the conference the appearance of participants in the layout is then determined according to the pinning configuration, the participant assignments to layout groups, and their voice activity. Note that a pinned participant can remain visible in a slot even if they do not speak. Voice activity is only used to choose between how the participants in a layout group are ordered.

Full details of how to perform these steps is provided further below.

Assignment logic example

Let's assume the following pinning configuration (as defined in the example JSON configuration further below):

  • Layout slot 1 is associated with layout group A first and then group B second.
  • Layout slot 2 is associated with layout group B only.
  • Subsequent layout slots do not have any pinning configuration applied.

Then the following participants are assigned as follows when they join the conference:

  • Group A: Alice.
  • Group B: Bob and Charlie.

This means that during the conference, the other participants would observe:

  • Alice always stays in slot 1 (while she remains present in the conference, and even if she never speaks), as she is the only participant assigned to group A.
  • Bob and Charlie alternate in slot 2 as each one of them speaks.
  • Slot 3 and later may be occupied by any conference participant except Alice — but including Bob and Charlie even though they are assigned to a layout group — based on standard voice activity logic.
  • If Alice leaves the conference, Bob and Charlie would occupy slots 1 and 2.

Alice, Bob and Charlie's own view of the conference would follow a similar logic, but is also dependent on the remove_self setting. For example if remove_self is true then Alice would always see Bob and Charlie in slots 1 and 2.

What's noteworthy?

When using participant pinning, note that:

  • You do not specify a specific layout as part of the pinning configuration. The participants are pinned to the primary layout slot positions using the sequence in which the conference's current layout is normally filled. See Layout examples for details about the fill order for each layout.
  • It is supported in all layouts, including custom layouts, except Adaptive Composition and the Teams-like layout.
  • Pinning takes priority over any spotlighting. When pinning configurations are in use, spotlighting only promotes people in the backfilled section of a configuration.
  • It can be used in Virtual Meeting Rooms, Virtual Auditoriums and gateway calls.

Adding pinning configuration to a theme

You must add a pinning configuration file to your theme. This is a JSON file that defines the names of the layout groups, for example "group1", "group2", that control which participants will appear in the primary slots in the layout, and in which order they appear.

The pinning configuration file must be named with a prefix of "pinning_config_" (must be lower case) and be in a .json format, for example pinning_config_mygroups.json.

Ensure that you include the pinning configuration JSON file in your theme package that you upload to Pexip Infinity. You can include multiple pinning configuration files in your theme package.

The JSON file has the following fields:

Field name Mandatory Description
name Yes

This is the name of the pinning configuration and is what is used to refer to the configuration throughout the system, in API calls, policy and in the Administrator interface.

It is a string which is limited to a maximum of 50 alphanumeric and "_" characters and no spaces.
slots Yes

This is a list of dictionaries that specify the layout group names which subsequently control who appears in the layout and in which order they appear. A slot dictionary contains:

  • layout_groups: An ordered list of strings that are the group names of the participants you want to appear in this slot. If nobody is assigned to the first group, then a participant from the second (and so on) group is used. The names must be in lower case.

The first layout_groups list determines who may appear in slot 1, the second layout_groups list determines who may appear in slot 2, and so on. Gaps in the slot sequence are not allowed.

If there are no participants found for a slot then the reserved_slot splash screen is shown instead.
backfill No

Determines whether the rest of the non-pinned slots in the layout should be filled up with other participants (using normal voice-switching rules). This can include participants who are assigned to a layout group but who are not currently appearing in a pinned slot.

Default: false
remove_self No

This controls whether "self view" is removed from the layout mix.

Default: false

For example:

{
    "name": "basic_backfill",
    "slots": [
        {
            "layout_groups": [
                "a",
                "b"
            ]
        },
        {
            "layout_groups": [
                "b"
            ]
        }
    ],
    "backfill": true,
    "remove_self": true
}

The example above defines 2 pinned slots. The first slot in the video layout is filled by a participant assigned to group a, or if nobody in group a is available then somebody from group b. The second slot is filled by somebody from group b only. All of the remaining slots are filled by any participant according to normal voice activity rules.

Thus, if this configuration is used on an Equal 2x2 layout:

Additional theme configuration options

Within the main theme configuration file (themeconfig.json) you can specify:

  • reserved_slot_overlay_text: an optional field that specifies any overlay text to be placed in a reserved slot (when the display of participant names is enabled for the layout). Use "" for no overlay text. The same text string is used for each unoccupied slot.

There is a reserved_slot splash screen that represents what is put into a reserved slot when it is not occupied by a participant. It uses the following graphics files which you can customize in the usual manner:

  • background_reserved_slot.jpg (a black screen)
  • icon_reserved_slot.svg (an image of a push pin)

By default the reserved slot appears as shown below (it scales to fill the video slot):

Enabling pinning configuration on a conference

You must enable a pinning configuration on a conference before you can actually pin any participants. You can permanently assign a pinning configuration to a VMR, or you can dynamically assign it via service configuration policy, or set it via the client REST API while the conference is in progress.

Permanently assigning a pinning configuration to a VMR

To permanently assign a pinning configuration to a VMR:

  1. Go to the required VMR (Services > Virtual Meeting Rooms) or Virtual Auditorium (Services > Virtual Auditoriums).
  2. Expand the Advanced options section.
  3. Select the Pinning configuration you want to assign. The list of available options contains the names of all of the pinning configurations in the theme associated with that VMR.
  4. Save your changes.

Using policy to dynamically assign a pinning configuration

You can dynamically assign a pinning configuration to a VMR via service configuration policy. The specified pinning configuration must be available in the theme associated with that conference.

You do this by setting the "pinning_config" service configuration response field to the name of the pinning configuration you want to apply.

Using the client REST API to dynamically assign a pinning configuration

You can dynamically assign a pinning configuration to a conference via the client REST API. The specified pinning configuration must be available in the theme associated with that conference.

To assign a pinning configuration:

POST: https://<node_address>/api/client/v2/conferences/<conference_alias>/set_pinning_config with body: {"pinning_config": "<name of your pinning configuration>" }

To clear a pinning configuration:

POST: https://<node_address>/api/client/v2/conferences/<conference_alias>/set_pinning_config with body: {"pinning_config": "" }

Assigning conference participants to the layout groups during the conference

You have to assign conference participants to the layout groups while the conference is in progress — this is what actually pins specific participants to the slots in the conference layout. A participant can only be assigned to one layout group at any one time.

You can use participant policy or the client REST API to assign a participant to a layout group.

Using participant policy

You do this by setting their layout_group participant configuration response field to the name of the layout group you want to assign.

Using the client REST API

To assign a layout group name:

POST: https://<node_address>/api/client/v2/conferences/<conference_alias>/participants/<participant_uuid>/layout_group with body: {"layout_group": "<group name>" }