updateParticipant()

updateParticipant(sessionId, {config})

Modify a participant, either by sending a message to change its state, or by changing the local view.

Returns this.

The first argument is the participant's session_id, or 'local' for the local participant.

The second argument is a set of actions to take.

Actions

  • setAudio: true | false,
  • setVideo: true | false,
  • setScreenShare: false,
  • eject: true
  • (SFU-mode only) setSubscribedTracks: true | false | custom
  • updatePermissions

setAudio, setVideo, setScreenShare, and eject

setAudio, setVideo, setScreenShare, and eject on remote participants require you to be a participant admin, i.e. have the 'participants' value in your canAdmin permission. See Permissions below for more information. If an action is not possible (or if there is no current meeting) the action will be ignored.

Remotely controlling a user's microphone and camera is a potential privacy issue.

This functionality is important for some use cases, but should not be a general feature of video call user interfaces. Think carefully before you enable remote control of cameras and microphones. And be aware that browsers will require that a user explicitly allow mic/camera device access at least once. Chrome will prompt the first time a user joins a call on a specific subdomain. Safari will prompt once each meeting session.

Track subscriptions

Note: track subscriptions only works over an SFU connection.

setSubscribedTracks expects to be set to either true, false, 'staged', or to an object that specifies the subscription state for each kind of track that a participant could send. In order to update this property, you must set the DailyCall subscribeToTracksAutomatically property to false. If you try to setSubscribedTracks argument with subscribeToAllTracksAutomatically: true, the updateParticipant() method throws an error.

More about 'staged'

The 'staged' subscription state corresponds to setting up the connections for a track but not transmitting data across that connection. This lets you "stage" tracks that you know you'll need soon, for later rapid transition into the fully "subscribed" state, without using any extra bandwidth.

Under the hood, when subscribing to a track (ie: { setSubscribedTracks: true }), what you are really doing is setting up a consumer connection with the SFU, and starting the process of transmitting the video/audio data across that connection. When you unsubscribe (ie. { setSubscribedTracks: false }), we tear down that connection and remove the consumer. Setting the state to staged sets up the consumer the same as you would when subscribing, but pauses the traffic on the connection so no bytes are transmitting, saving on bandwidth and decodings. Thus, going from a { setSubscribedTracks: 'staged' } to { setSubscribedTracks: true } is quicker, as it bypasses the work of setting up the consumer connection.

Note that there are still limitations on the number of consumers that can be created. When supporting larger calls, it's important to still take advantage of fully unsubscribing from tracks and only staging those that may come into view soon. For example, in the Daily Prebuilt in grid mode, we: subscribe to all video being rendered on the current page, we "stage" all videos on the previous and next pages, and unsubscribe from videos on all other pages. As a user flips through pages, we update those states accordingly.

Track subscriptions setSubscribedTracks() in action

Permissions

updatePermissions is an object that specifies how you want to update another participant's permissions—that is, what they're permitted to do during a call.

Today, this object can take up to three fields corresponding to the three participant permissions: canSend, hasPresence, and canAdmin.

Note that you can only update a participant's permissions if you are a participant admin, i.e. you have the 'participants' value in your canAdmin permission. Meeting owners are always participant admins.

Each provided permission—canSend, hasPresence, or canAdmin—overwrites whatever value the participant previously had for that permission. If you omit one of these fields, the corresponding participant permission won't be changed.

  • canSend takes an Array or Set of strings identifying which types of media a participant should be permitted to send: 'video', 'audio', 'screenVideo', and 'screenAudio'. These correspond to the types of media described in the participant tracks property. It can also take a boolean, which acts as a shorthand for granting or revoking permission to send all types of media.

    If a participant has canSend permission revoked for a particular type of media (say, 'video'), then you will see an update (announced by a 'participant-updated' event) to that participant's relevant tracks object:

    Note that for screen media if a participant has canSend permission revoked for only one type of media (say, 'screenAudio'), then if they attempt a screen share that contains the disallowed media, the entire screen share—both video and audio—will be denied.

    If your call is in SFU mode, revoking canSend permission actually results in the SFU blocking relevant tracks. In peer-to-peer mode, revoking canSend simply tells the participant's client to stop sending—there's no server-side enforcement.

  • hasPresence takes a boolean, and controls whether the participant appears as "present" in the call, i.e. whether they appear in participants(). If a participant has no presence, they are "hidden". Hidden participants only appear as a count in participantCounts().

    Revoking a participant's hasPresence permission will result in a 'participant-left' event, since the participant is being removed from participants(). A new reason field in the event payload lets you know that they left because they were 'hidden'.

  • canAdmin takes an Array or Set of strings identifying which types of admin tasks a participant should be permitted to do:

    It can also take a boolean, which acts as a shorthand for granting or revoking permission for all types of admin tasks.

    Note that if you are a participant admin (i.e. you have the 'participants' value in your canAdmin permission) you have some limitations on how you can edit others' (or your own) permissions. For the most part, you are free to edit anyone's permissions, including your own, however you see fit. But:

    • If you are also a meeting owner, you cannot revoke 'participants' from your own canAdmin permission. In other words, owners are always participant admins.
    • If you are not a meeeting owner, you cannot revoke others' 'participants' from their canAdmin permissions. In other words, participant admins can't demote their peers.