Handle a Remote Stream

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

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

CodeDescription
5014Failed to subscribe to the stream
5026Stream has already been subscribed
5027Repeated subscribe() call made while a previous subscription request is in process
5028Failed to subscribe because subscribe() call is made on the Local stream

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:

Delegate MethodDescription
- 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

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

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;

ParametersData TypeDescription
numTalkersStringThe 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;

Sample Code

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

Error Codes and Exceptions

CodeDescription
5055Repeated setTalkerCount() call made while a previous request is in process

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

ParameterData TypeDescription
clientIDArrayAn array of Client IDs for the background color to be changed.
ColorStringColor code of the background color.

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

ParameterData TypeDescription
videoQualityStringEnumerated string constants (Auto, HD, SD, LD). Set it to Auto to allow EnableX to dynamically choose the optimum quality based on the available bandwidth.
-room:didSetVideoQuality:JSON ObjectAcknowledgement to the user that the request to reset the video quality has been accepted.

Sample Code

[room setReceiveVideoQuality:@"HD"];

Error Codes or Exceptions

CodeDescription
5057Stream already set with the desired quality.