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 = hsmStore.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 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.changeRole(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.

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 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.