Active Talkers: iOS SDK – Video API

Table of Contents

• Handle Active Talkers
  • Get maximum permissible Talker Count
  • Get Talker Count
  • Set Talker Count
  • Switch Active Talker View
  • EnxPlayer View
    • Switch to Player View
    • Highlight EnxPlayer Border
    • Change EnxPlayer Background
    • Force Reload Active Talker View

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, your Client endpoint will also receive didStreamAdded() callback for all the Streams (as per the max_active_talkers configured during Room Creation) available in the Room. You need to subscribe to each of these Streams along with two extra Streams for Screen-Share and Canvas.

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 Callback didActiveTalkerList() to each connected endpoint whenever there is a change in the Active Talker List if activeviews : list during joinRoom(). If activeviews: view then didActiveTalkerList() is called only once after joining the Room and subscribing to 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.  stream.pinned returns true if the stream is pinned.

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. 

Active Talkers List JSON

[ EnxStream1, EnxStream2, ....., EnxStreamN ] 

Note: In case of error, <null> is received at 1st Index, and Error Info at 2nd Index

This Active Talkers JSON is used for managing the UI and to play Remote Stream’s Audio/Video. To play a specific stream, you need the  Remote Stream object using room.streamsByStreamId[StreamId]. You must subscribe to all “dummy” Streams received through delegate method - room:didAddedStream: before you can play a Stream out of Active Talker List.

Class: EnxRooom

Delegate Method:

• - room:didActiveTalkerList: When activeviews is set to "list” in the roomInfo parameter in connect() method.
• - room:didActiveTalkerView: When activeviews is set to "view” in the roomInfo parameter in connect() method.

// To get Active Talker List
-(void)room:(EnxRoom *)room didActiveTalkerList:(NSArray *)Data{
 for (EnxStream *stream in Data) {
 if(stream.enxPlayerView != nil) {
 EnxPlayerView *playerView = (EnxPlayerView *)stream.enxPlayerView;
 playerView.frame = CGRect;
 playerView.delefate = self;
 [self.view addSubview: playerView];
 }
 }
}

// To get Acive Talker View
-(void)room:(EnxRoom *_Nullable)room didActiveTalkerView:(UIView *_Nullable)view {
     [self.view addSubview: view]; 
}

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: - (void)getMaxTalkers;

Delegate Method: - (void)room:(EnxRoom *)room didGetMaxTalkers:(NSArray *)Data

[room getMaxTalkers];

-(void)room:(EnxRoom *)room didGetMaxTalkers:(NSArray *)Data {
     // Talker info in success response jsonobject:
     // [{"result": 0, "maxTalkers": 4}] 
}

Get Talker Count

The EnxRoom.getTalkerCount() method provides you the number of active talkers to be received through didActiveTalkerList() callback. 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: -(void)getTalkerCount;

Delegate Method: - (void)room:(EnxRoom *)room didGetTalkerCount:(NSArray *)Data

[room getTalkerCount]; 

-(void)room:(EnxRoom *)room didGetTalkerCount:(NSArray *)Data{
    // Data: [{ "result": 0, "numTalkers": 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. 

Class: EnxRoom

Method: - (void)setTalkerCount:(NSInteger)numTalkers;

Parameters: numTalkers – The Number of Talker Streams 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 List.
• If you set numTalkers to 0 (zero), then the list doesn’t become empty, it carries 3 audio streams and no video Streams.

Delegate Method : -(void)room:(EnxRoom *)room didSetTalkerCount:(NSArray *)Data;

[room setTalkerCount:3];


-(void)room:(EnxRoom *)room didSetTalkerCount:(NSArray *)Data{
 // Data: [{ "result": 0, "numTalkers": 3 }]
}

Error Codes / Exceptions

Code	Description
5055	Repeated setTalkerCount () call made while a previous request is in process.

Switch Active Talker View

Availability: iOS SDK 2.1.2+

The EnxRoom.switchATView() method provides the option to switch their talker view from leader/gallery or vice versa. By default, the SDK gives a gallery view layout.

Class: EnxRoom

Method: -(void)switchATView:(NSString * _Nonnull)viewString;

Parameters: ViewString – where ViewString is leader/gallery view.

[EnxRoom switchATView:"leader"];  

PlayerView

Availability: iOS SDK 2.1.3+

The PlayerView methods provide option to custom the active talker view. With the help of these methods, you get a particular Player View, and further highlight the selected player border and change the background colour of the Player View.

Switch to Player View

The getPlayer() method provides the option to get a particular Player View.

Class: EnxRoom

Method: -(EnxPlayerView *_Nullable)getPlayer:(NSString*_Nonnull)clientID;

Parameters:

clientId – The user that requires a particular Player View

// Initiate EnxPlayerView
EnxPlayerView *player = [enxRoom getPlayer:clientId];

Highlight the EnxPlayer Border

The highlightBorderForClient() method provides the choice to highlight the Player border colour using the custom ActiveTalker View option. You can highlight the player border by passing the list of clientids.

Class: EnxRoom

Method: -(void)highlightBorderForClient:(NSArray*_Nonnull)clientIDs;

Parameters:

• @param {Array} clientID - An array of Client Ids to be highlighted.

// Highlight EnxPlayer border
[enxRoom highlightBorderForClient:[clientid1, clientid2,…...clientIdn];

Change EnxPlayerView Background Colour

The changeBgColorForClients() method provides the choice to change the background colour for the Player View using the custom ActiveTalker View option. To change the background colour of a Player, you need to pass the clientID of that EnxPlayer.

Class: EnxRoom

-(void)changeBgColorForClients:(NSArray*_Nonnull)clientIDs withColor:(UIColor *_Nonnull)color;

Parameters:

• @param {Array} clientID - An array of Client Ids for the background color to be changed.
• Color – String. Color code of the background color.

// Change EnxPlayer background colour
[enxRoom changeBgColorForClients:[clientId1,clientid2....clientidn] withColor[UIcolor redcolor];

Force Reload Active Talker View

The forceUpdateATList() method provides the option to force reload the active talker view after any manipulation in the view as the case may be.

Class: EnxRoom

Method: -(void)forceUpdateATList;

// Force reload Active Talker view
[enxRoom forceUpdateATList];

---