Change Role

Introduction

Role is a powerful concept that takes a lot of complexity away in handling permissions and supporting features like breakout rooms. Learn more about roles here.

Every peer is associated with a role. The HMSRole object can be used to know the following:

1. Check what this role is allowed to publish. i.e can it send video (and at what resolution)? can it send audio? can it share screen? This can be discovered by using selectIsAllowedToPublish to display the UI appropriately.
2. Check which other roles can this role subscribe to. This is internally taken care of by the 100ms infra and sdk, and your UI will only get tracks as per allowed subscriptions. role.subscribeParams can be used to get details.
3. Check what actions this role can perform. i.e can it change someone else's current role, mute others, end meeting, remove someone from the room. This can be discovered by using the selectPermissions selector.

Example

Imagine an audio room with 2 roles "speaker" and "listener". Only someone with a "speaker" role can publish audio to the room while "listener" can only subscribe. Now at some point "speaker" may decide to nominate some "listener" to become a "speaker". This is where the changeRole API comes in.

Know Thy Permissions

The below selectors can be used to know what the local peer is allowed to publish, and the permissions they have. To know about all the permissions please check selectPermissions' api reference.

const role = hmsStore.getState(selectLocalPeerRole);
const permissions = hmsStore.getState(selectPermissions);
console.log('can I end room - ', permissions.endRoom);
console.log('can I end change role - ', permissions.changeRole);
const { video, audio, screen } = hmsStore.getState(selectIsAllowedToPublish);

Change Role APIs

There are two way of chaning peer's role using our api:

1. Single Peer Role API - It is useful when we need to change role of a single peer.
2. Bulk Peer Role API - We could change a all peers of particular roles to a given role. It will be helpful to make breakout rooms, waiting rooms, etc.

Change Single Peer Role API

If the local peer has permissions to change role(permissions.changeRole), they can change either their or someone else's role using the below interface.

hmsActions.changeRoleOfPeer(forPeerId, toRoleName, force);

import { useHMSActions } from '@100mslive/react-sdk';
function RoleChange() {
  const actions = useHMSActions();

  return (<button onClick={() => hmsActions.changeRoleOfPeer(forPeerId, toRoleName, force)}> )
}

• forPeerId: The peer ID whose role needs to be changed, the peer can be either of local or remote.
• toRoleName: The target role name.
• force(optional): The other peer gets a request by default to accept a role change, by setting force to true, the role can be changed without requesting for approval.

Change Bulk Peer Role API

If the local peer has permissions to change role(permissions.changeRole), they can convert all roles from a list of roles, to another role using the below interface.

hmsActions.changeRoleOfPeersWithRoles(ofRoles, toRole);

import { useHMSActions } from '@100mslive/react-sdk';
function BulkRoleChange() {
  const actions = useHMSActions();

  return (<button onClick={() => hmsActions.changeRoleOfPeersWithRoles(ofRoles, toRole)}> )
}

• ofRoles: It accepts the list of roles name.
• toRole: The target role name.

Note that if an empty list is sent to ofRoles, no roles will be changed. This is to avoid accidentally changing roles you may not have intended such as the bots that provide recording and streaming with the roles beam.

It will throw exception when list ofRoles consist of target toRole.

Bulk role changes are always forced, no dialog will be given for the peer to accept it, they will just be changed immediately.

Handling a Role Change Request

The force parameter in changeRole, when false, is a polite request: "Would you like to change your role from listener to speaker?" which can be ignored by the other party. The way it works is the other party will first receive a request which they can accept or reject.

function handleRoleChangeRequest(request) {
    if (!request) {
        return;
    }
    console.log(`${request.requestedBy.name} requested role change to - ${request.role.name}`);
    // shouldAccept can for example present a pop up to the user for deciding how to act on the request
    const accept = shouldAccept(request);
    if (accept) {
        hmsActions.acceptChangeRole(request);
    } else {
        hmsActions.rejectChangeRole(request);
    }
}

hmsStore.subscribe(handleRoleChangeRequest, selectRoleChangeRequest);

function handleRoleChangeRequest(request) {
    const request = useHMSStore(selectRoleChangeRequest);
    const hmsActions = useHMSActions();

    useEffect(() => {
        console.log(`${request.requestedBy.name} requested role change to - ${request.role.name}`);
        // shouldAccept can for example present a pop up to the user for deciding how to act on the request
        const accept = shouldAccept(request);
        if (accept) {
            hmsActions.acceptChangeRole(request);
        } else {
            hmsActions.rejectChangeRole(request);
        }
    }, [request, hmsActions]);

    return null;
}

If the request is accepted, the peer.roleName field in the store will update re rendering a declarative UI as required.

Forced Role Change

Imagine that the newly nominated speaker is not behaving nicely and we want to move him back to listener without a prompt. This is where the force parameter comes in. When it is set to true the other party will not receive a confirmation roleChangeRequest but instead will straight away receive a new set of updated permissions and stop publishing.

Notifications

You'll get a notification of type ROLE_UPDATED when role change happens for the local peer. When a peer's role change happens in a way where the updated role has new publish permissions, the track will be muted by default. So for example, if a viewer(no audio/video) is changed to a host, their tracks will be muted right after the role change. They'll be able to manually unmute post role change though. If you want this unmuting to happen automatically, you can listen to the notification to call the action.

Ideas

Breakout Rooms/Groups

You can have multiple roles which act as breakout rooms subscribing only to peers within the role. A peer can join another breakout room or group easily using the change single peer role API.

Waiting Room

You can create a specific role for a waiting room which doesn't subscribe to anyone else. When someone joins waiting room, hosts get a notification, and they can let the person join by changing their role to attendees.

Audio Rooms

An audio room can be designed with moderators, speakers and listeners where a moderator can promote a listener to speaker and vice versa.

Classroom

Roles can be created for muted-student(not allowed to unmute), student-spotlight(publishes higher quality video), student-screen(allowed to screenshare), prefect(can mute others) etc. to create an enriching feature rich classroom experience.