Handle a Remote Stream

The Web SDK provides the following methods to handle a remote stream:

Subscribe a Remote Stream

The EnxRoom.subscribe() method is used to receive the media stream of other users connected to a room. This method must be called for each participant's media stream individually to receive it.

After getting connected to the room, the client application can access the list of streams in the room through Room Meta Information, that is { streams: [] } and call EnxRoom.subscribe() on each stream. The user can subscribe to a maximum of 12 active talkers in a room, one stream for screen sharing (StreamID# 101), and one stream for canvas streaming (StreamID# 102) if the client application supports screen sharing and canvas streaming. Users can see a maximum of 12 participants in the UI. These participants keep getting updated as per their activity in the room. For more information see Handle Active Talkers section.

Users do not need to subscribe to their local streams. EnableX facilitates the publishers to receive their screen sharing and canvas streaming without explicitly subscribing to them. In short, users must only subscribe to remote streams in the room.

  • Method: subscribe(RemoteStream, SubsOptions, Callback)
  • Parameters:
    • RemoteStream : EnxStream. The stream object that needs to be subscribed/received.
    • SubsOptions: JSON Object. It defines specification for Subscription.
      • audio : Boolean. Set it to true to subscribe to the audio of the stream.
      • video : Boolean. Set it to true to subscribe to the video of the stream.
      • data : Boolean. Set it to true to subscribe to the data of the stream.
  • Event Notifications:
    • stream-subscribed: Acknowledgment to the subscriber when the subscriber has successfully subscribed to the stream.

Sample Code

var subsOptions = {
    audio: true,
    video: true,
    data: true
};


// Subscribe to all Streams in connected Room Meta
for (var i = 0; i < success.streams.length; i++) {
    room.subscribe(success.streams[i],  subsOptions );  
}  


// Notification: Stream subscribed
room.addEventListener("stream-subscribed", function(event) {
    
});

Handle Active Talkers

EnableX sends a maximum of 12 actively talking users in a room to the client endpoint to prevent excessive consumption of the server and client resources. It sends screen sharing (StreamID# 101) and canvas stream (StreamID# 102) only 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 room.remoteStreams in Room Meta Info. The total number of remote streams is restricted by 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 on the latest talker in the room. Hence, the Active Talker list contains a list of talkers in ascending order at any time, which means that the latest talker is 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 the JSON format and sent through the active-talkers-updated event to each connected endpoint whenever there is a change in when the Active Talker list changes.

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 inactive pinned users and active talkers in ascending order.

It must also be noted that the Active Talkers list contains remote streams only. Hence, this list varies for each participant in the room.

  • Event Notifications: active-talkers-updated

Sample JSON: Active Talker Data JSON received

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

Once you have subscribed to all the streams in the Active Talker list, you can 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 in the UI.

Sample Code

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 the Talker Count

The EnxRoom.getTalkerCount() method provides the number of active talkers to receive through an active-talkers-updated event. The method returns the number of currently active streams in a 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 the UI.

  • Method: getTalkerCount( Callback )
  • Returns:
    • maxTalkers: Maximum number of active talker streams that a client endpoint can currently receive.

Sample Code

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

Set the 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. It could either be ingrained at the application level or implemented as a UI feature where end-users can control the number of remote streams they want to receive. This method allows you to control how many streams you like to receive.

  • Method: setTalkerCount(numTalkers, Callback)
  • Parameters:
    • numTalkers : Numeric. The number of talkers that you want to receive.

Note that the numTalkers range is limited by max_active_talkers. The typical range is between 0-12.

  • Set it to any value from 1 to 12 to receive those many talkers in the Active Talker list.
  • When set to 0 (zero), the list does not become empty, it includes 3 audio streams and no video streams.

Sample Code

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

Error Codes

Error CodeDescription
4106Invalid Talker Count range. Valid range: 1-12

Get The Maximum Permissible Talker Count

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

  • Method: getMaxTalkers( Callback )
  • Returns:
    • maxTalkers: specifies the maximum number of talkers permitted in a room as per the room configuration.

Sample Code

room.getMaxTalkers( function(response) {
     // esponse JSON
     // { "result": 0, "maxTalkers": 6 } 
});

Receive the Desired Video Quality

The EnxRoom.setReceiveVideoQuality() method allows you to set the desired video quality at the available bandwidth to receive the remote streams at the client endpoint. You can utilize this API to create a UI with enumerated values that allow the users to choose the desired video quality that they want to receive.

  • Method: setReceiveVideoQuality(QualityOpt, Callback)
  • Parameters:
    • videoQuality : String. Enumerated Values: Auto, HD, SD, LD. Set to Auto to allow Video Service to choose the optimum quality dynamically based on the available bandwidth.
    • streamType : String. Enumerated Values: talker, canvas

Sample Code

var Quality = {
     "videoQuality": "", 
     "streamType":  "talker"
};


room.setReceiveVideoQuality(Quality, function (result) {
         if(result.result == 0) {
            // Success
         }
         else {
            // Faileld - result.message
         }
});
Handle a Local StreamGet Stream Information