Handle a Remote Stream

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

• subscribe(): To subscribe to a remote stream to start receiving it.
• getMaxTalkers(): To provide the maximum active talkers allowed for the Room.
• getTalkerCount(): To provide you the number of active talkers.
• setTalkerCount(): To set the number of active talkers in the Active Talkers List.
• switchATView(): To switch talker view from leader/gallery or vice versa.
• getPlayer(): To get a particular Player View.
• highlightBorderForClient(): To highlight the Player border colour.
• changeBgColorForClients(): To change the background colour for the Player View.
• forceUpdateATList(): To force reload of the active talker view.
• setReceiveVideoQuality(): To set the desired video quality.

Subscribe to a Remote Stream

The EnxRoom.subscribe() method receives the media stream of other users connected to the room. You must call this method individually for each participant's media stream to receive the stream.

You don't need to subscribe to your local stream. EnableX allows publishers to receive their screen sharing and canvas streaming without explicitly subscribing to them. In short, a user must only subscribe to the remote streams in the room. For more information, see Handle Active Talkers.

Class: EnxRoom

Method: -(void)subscribe:(EnxStream *)stream;

Parameter: stream: JSON Object. The stream object that needs to be subscribed.

Delegate Method: – room:didSubscribeStream: JSON Object. Acknowledgment to subscribers when they are successfully subscribed to the stream.

Sample Code

// There is a new stream you may subscribe
-(void)room:(EnxRoom *)room didAddedStream:(EnxStream *)stream{
	[room subscribe:stream]; // Subscribe to it.
}

- (void)room:(EnxRoom *)room didSubscribeStream:(EnxStream *)stream {
	// You subscribed to stream.
}

Error Codes and Exceptions

Handle Active Talkers

EnableX sends a maximum of 12 actively talking users in the Room to the client endpoint to avoid excessive consumption of the server and client resources. 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 receives the 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 these streams and 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 on 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, didActiveTalkerList() is called only once after joining the Room and subscribing to the Active Talker List.

Apart from the activity level, EnableX also allows the 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; hence, it 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 to manage the UI and play Remote stream's audio/video. It would help to have the Remote stream object using room.streamsByStreamId[StreamId] to play a specific stream. You must subscribe to all "dummy" streams received through the delegate method - room:didAddedStream: before you can play a stream out of Active Talker List.

Delegate Methods:

Sample Code

// 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]; 
}

// To get Users Available on Active Talker
-(void)room:(EnxRoom *_Nullable)room didAvailable:(activeUser Int) count {
     // count is number of users in Active Talker
}

Get The Maximum Permissible Talker Count

The EnxRoom.getMaxTalkers() method provides the maximum number of active talkers allowed for the Room as per max_active_talkers configuration during Room Creation. This count could interest the user if they receive fewer 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

Sample Code

[room getMaxTalkers];

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

Get the Talker Count

The EnxRoom.getTalkerCount() method provides the number of active talkers to receive through the didActiveTalkerList() callback. The method returns the number of currently active streams in the Room restricted by the maximum permissible talker count or 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

Sample Code

[room getTalkerCount]; 

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

Set the Talker Count

The EnxRoom.setTalkerCount() method sets the number of active talkers in the Active Talkers List to a particular value not exceeding the maximum permissible talker count. This could be ingrained at the application level or implemented as a UI feature where the end-user can control the number of remote streams they want to receive. This method lets you control how many streams you want to receive.

Class: EnxRoom

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

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

Sample Code

[room setTalkerCount:3];


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

Error Codes and Exceptions

Switch to Active Talker View

This functionality is available in the iOS SDK version 2.1.2 and above

The EnxRoom.switchATView() method allows switching 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;

Parameter: ViewString: String. where ViewString is leader/gallery view.

Sample Code

[EnxRoom switchATView:"leader"];

Player View

This functionality is available in the iOS SDK version 2.1.3 and above.

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

Switch to Player View

The getPlayer() method allows one to get a particular Player View.

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

Parameter: clientId: String. The user that requires a particular Player View.

Sample Code

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

Highlight the EnxPlayer Border

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

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

Parameter: clientID: Array. An array of Client IDs to be highlighted.

Sample Code

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

Change the EnxPlayerView Background Colour

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

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

Parameters

Sample Code

// 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 awhen the view is changed.

Method: -(void)forceUpdateATList;

Sample Code

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

Receive 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 video quality that they want to receive.

Class: EnxRoom

Method: - (void)setReceiveVideoQuality:(NSString*)videoQuality;

Parameters

Sample Code

[room setReceiveVideoQuality:@"HD"];

Error Codes or Exceptions