Active Talkers: Web SDK – Video API

Table of Contents

• Handle Active Talkers
  • Get Talker Count
  • Set Talker Count
  • Get Maximum Permissible Talker Count

Handle Active Talkers

To avoid excessive consumption of the server and client resources, EnableX sends a maximum of 12 actively talking users in the Room to the client endpoint. Additionally, it sends Screen Sharing (StreamID# 101) and Canvas Stream (StreamID# 102) if the client application supports these features. The decision on which of the participant’s streams would be played depends upon the Active Talker List. 

After getting connected to the Room, you need to subscribe to the Remote Streams available in the room.remoteStreams[] in the Room Meta Info. The total number of Remote Streams is restricted by the max_active_talkers configured during Room Creation. Apart from these, you also need to subscribe to Screen share and Canvas Stream.

After you connect to the room and subscribe to the available Streams, the active-talkers-updated event is triggered, which creates a new entry in the Active Talker List. This list keeps getting updated depending upon the latest talker in the Room. Hence, the Active Talker List contains a list of talkers in ascending order at any point in time which means that the latest talker would be moved up in the list. Therefore, you may expect to receive the event too frequently in a noisy room. The list of Active Talkers is available in JSON format and sent through the active-talkers-updated event to each connected endpoint whenever there is a change in the Active Talker List.

Apart from the activity level, EnableX also allows pinning of user streams in the Active Talker List regardless of their activity level in the Room. So, the Active Talkers List consists of the inactive pinned users and active talkers in ascending order.  

It must also be noted that the Active Talkers List contains Remote Streams only and hence the Active Talkers List varies for each participant in the Room. 

Event Notifications: active-talkers-updated

Active Talkers List JSON

{    "active" : true,
      "activeList": [
           {   "clientId" : "String", 
               "mediatype" : "audiovideo",	// Enum: audiovideo, audioonly
               "name" : "String",
               "reason" : "user",		// Enum: user, bw
               "streamId" : Number,
               "videoaspectratio" : "16:9", 
               "videomuted" : Boolean,
               "pinned" : Boolean
           }
       ]
}

Once you have subscribed to all the Streams in the Active Talker List, you can now play them in a FIFO manner. You can use the StreamID out of the Active Talker List to pick the latest Stream from room.remoteStreams[] and play them on the UI. 

room.addEventListener('active-talkers-updated', function (event) {
       TalkerList = event.message.activeList;
       for (var i = 0; i < TalkerList.length; i++) {
           if (ATUserList[i] && ATUserList[i].streamId) {
               var stream  = room.remoteStreams.get(ATUserList[i].streamId);
               var stream_id   = ATUserList[i].streamId;
               var username    = ATUserList[i].name;
               stream.play("DOM_ELEMENT_ID", PlayerOptions);
           }
       }                       
 }

Get Talker Count

The EnxRoom.getTalkerCount() method provides you the number of active talkers to be received through active-talkers-updated event. The method returns the number of currently active streams in the Room restricted either by the maximum permissible talker count or by the set talker count API when invoked by the application or the user through UI.  

Class: EnxRoom

Method: EnxRoom.getTalkerCount( Callback )

Returns:

maxTalkers – Maximum number of active talker streams currently allowed to be received at the Client Endpoint.

room.getTalkerCount( function(response) {
     // Talker info in response JSON:
     // { "result": 0, "maxTalkers": 4 } 
});

Set Talker Count

The EnxRoom.setTalkerCount() method is used to set the number of active talkers in the Active Talkers List to a particular value not exceeding the maximum permissible talker count. This could either be ingrained at the application level or be implemented as a UI feature where the end-user has the flexibility to control the number of remote streams they want to receive.  This method allows you to control how many Streams you would like to receive. 

Method: EnxRoom.setTalkerCount(numTalkers, Callback)

Parameters:

numTalkers – No. of talkers you want to receive. Range limited by max_active_talkers, typically 0-12

• If you set numTalkers to any value from 1 to 12, you receive those many talkers in the Active Talker Lists in the list.
• If you set numTalkers to 0 (zero), then the list doesn’t become empty, it carries 3 audio streams and no video Streams.

room.setTalkerCount(5, function(response) {
     // Set Talker info in response JSON:
     // { "result": 0, "maxTalkers": 5 } 
 });

Error Codes / Exceptions

Code	Description
4106	Invalid Talker Count range. Valid range: 1-12

Get Maximum Permissible Talker Count

The EnxRoom.getMaxTalkers() method provides the maximum active talkers allowed for the Room as per max_active_talkers configuration during Room Creation. This count could be of interest to the user if they choose to receive less active talkers in the Room. By default, the max_active_talkers is restricted to 12. 

Class: EnxRoom

Method: EnxRoom.getMaxTalkers( Callback ) 

Returns:

maxTalkers – Maximum number of talkers permitted in the Room as per Room configuration.

room.getMaxTalkers( function(response) {
     // Maximum Talker info in response JSON:
     // { "result": 0, "maxTalkers": 6 } 
});

---