Handle a Remote Stream

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

• subscribe(): To receive the media stream of other users connected to a room.
• adjustLayout(): To adjust the video player layout to fit within its parent view.
• getMaxTalkers(): To provide the number of maximum active talkers allowed for a room.
• setTalkerCount(): To set the number of active talkers in the Active Talkers list.
• getTalkerCount(): To provide the number of active talkers.
• 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 using the custom ActiveTalker view option.
• changeBgColorForClients(): To change the background colour for a player view using the custom ActiveTalker view option.
• forceUpdateATList(): To force reload the active talker view after any manipulation.
• setReceiveVideoQuality(): To set the desired video quality at the available bandwidth for remote streams.

Subscribe to 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.

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. For more information, see Handle Active Talkers section for more details.

Class: EnxRoom

Method: public void subscribe(EnxStream remoteStream)

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

Observers

Sample Code

public void onStreamAdded(EnxStream remoteStream) { // There is a new Stream
	room.subscribe(remoteStream); // Subscribe to it.
}

public void onSubscribedStream(EnxStream stream) {
	// You have subscribed to the Stream.
}

Error Codes and Exceptions

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, the client endpoint receives an onStreamAdded() callback for all the streams (as per the max_active_talkers configured during Room Creation). You need to subscribe to these streams and two extra streams for 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 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 the JSON format and sent through the Callback onActiveTalkerList() to each connected endpoint whenever there is a change in the Active Talker List if activeviews : list during joinRoom(). If activeviews: view, then onActiveTalkerList() 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 inactive pinned users and active talkers in ascending order.

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

Observers

Callbacks onAvailable: To notify when no active Talker abailable or with active Talker available.

Sample Code

public void onAvailable(Integer activeUserCount) {
    // activeUserCount – 0,1,2,3 based on available user count 
}

Modes of Active Talker Usage

Depending on your application, you have option to receive either Active Talker Stream List to play streams in your own customized view or to get a predefined Active Talker Player View that handles everything for you.

Play Active Talker Streams with a Customized View

You can create your custom view for displaying the Remote Streams out of the Active Talker list by selecting activeviews : list during joinRoom(). To play a stream out of the Active Talker list, you must fetch every stream player (EnxPlayerView) from the list and attach it to your chosen UI.

Class: EnxRoom

Observer setActiveTalkerListObserver: This observer is used when activeviews is set to "list" in the roomInfo parameter in joinRoom() method.

Callback: onActiveTalkerList(List enxStreamList)

Parameter

enxStreamList: JSON Object. List of Streams received at the endpoint.

Sample Code

enxRoom.setActiveTalkerListObserver(this); // Called after getting connected to the Room

@Override

public void onActiveTalkerList(List<EnxStream> enxStreamList) {
     for(int i = 0 ; i <=enxStreamList.size();i++) {
	EnxPlayerView enxPlayerView = enxStreamList.get(i).mEnxPlayerView;
	yourview.addView(enxPlayerView);
     }
}

Play Active Talker Streams with Predefined Recycler View

You can also play the remote streams in the Active Talker list with a custom-defined recycler view by selecting activeviews : view during joinRoom(). You don't have to handle the UI in this case, as the pre-defined video grid plays all the streams received at the client endpoint.

When choosing this option, you can use the adjustLayout() method to adjust the video player layout to fit within its parent view. This method helps when the user rotates the screen or when the view needs to be adjusted to fit properly

Class: EnxRoom

Method: public void adjustLayout()

Observer: setActiveTalkerViewObserver: This observer is used when activeviews is set to "view" in the roomInfo parameter in joinRoom() method.

Callback: onActiveTalkerView(RecyclerView recyclerView)

Parameter

recyclerView: JSON Object. Recycle View

Sample Code

enxRoom.setActiveTalkerViewObserver(this); // Called after getting connected to the Room

@Override

public void onActiveTalkerView(RecyclerView recyclerView) {
	yourRemoteView.addView(recyclerView);
}
room.adjustLayout();

Note: The local stream is not included in RecycleView even if the endpoint is talking, as the local stream is not present in the Active Talker list.

Get The Maximum Permissible Talker Count

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

Class: EnxRoom

Method: public void getMaxTalkers()

Observer: public void setTalkerObserver( EnxTalkerObserver Object )

Callback: onMaxTalkerCount()

Sample Code

// Initiate Talker Observer to receive Callbacks
room.setTalkerObserver(this);

room.getMaxTalkers();

public void onMaxTalkerCount(JSONObject jsonobject) {
     // Talker info in response jsonobject:
     // {"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 the end-user can 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: public void setTalkerCount(int numTalkers)

Parameter numTalkers: Numeric. The number of talker streams you want to receive where the range is 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 does not become empty, it carries 3 audio streams and no video streams.

Observer

public void setTalkerObserver( EnxTalkerObserver Object ): Initiate Talker observer to receive callbacks.

Callback: onSetTalkerCount()

Sample Code

// Initiate Talker Observer to receive Callbacks
room.setTalkerObserver(this); 

int numTalkers = 5;
room.setTalkerCount(numTalkers);

public void onSetTalkerCount(JSONObject jsonobject) {
     // Talker info in response jsonobject:
     // {"result": 0, "maxTalkers": 4} 
}

Error Codes and Exceptions

Get the Talker Count

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

Class: EnxRoom

Method: public void getTalkerCount()

Observer: public void setTalkerObserver( EnxTalkerObserver Object )

Callback: onGetTalkerCount()

Sample Code

// Initiate Talker Observer to receive Callbacks
room.setTalkerObserver(this); 

room.getTalkerCount();

public void onGetTalkerCount(JSONObject jsonobject) {
     // Talker info in response jsonobject
     // { "result": 0, "numTalkers": 4 } 
}

Note: The Observer setTalkerObserver() must be initiated only once for any or all of these method calls to receive callbacks.

Switch to Active Talker View

Note: This functionality is available in Android SDK version 2.1.2 and later.

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: public void switchATView(String param)

Parameter

param: String. Param is leader/gallery.

Observers

Sample Code

// Initiate AT Switch Observer to receive Callbacks for Leader View
EnxRoom.setActiveTalkerLeaderObserver(this);  

// Initiate AT Switch Observer to receive Callbacks for Gallery View
EnxRoom.setActiveTalkerViewObserver(this);  


// Initiate leader/gallery view

EnxRoom.switchATView("leader");                                      

public void onActiveTalkerList(RelativeLayout view);            // If the user requests for Leader View

public void onActiveTalkerList(RecyclerView recyclerView);     // If the user requests for Gallery View

Player View

Note: This functionality is available in Android SDK version 2.1.3 and later.

The PlayerView methods provide an 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.

Class: EnxRoom

Method: public void EnxPlayerView getPlayer(String clientId)

Parameter

clientId: String. The user that requires a particular player view.

Sample Code

// Initiate EnxPlayerView
EnxPlayerView playerView = 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.

Class: EnxRoom

Method: public void highlightBorderForClient(ArrayList<String> clientIds)

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

Sample Code

// Highlight EnxPlayer border
EnxRoom.highlightBorderForClient([clientid1,clientid2.......clientidn]);

Change EnxPlayerView Background Color

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

Class: EnxRoom

Method: public void changeBgColorForClients(ArrayList<String> clientIds,String color)

Parameters

Sample Code

// Change EnxPlayer background colour
EnxRoom.ChangeBgColorForClients([clientId1,Clientid2.....clientIdn],"#ff669900")

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: public 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 for remote streams to be received at the client endpoint. You can utilize this API to create a UI with enumerated values that allow the user to choose the desired video quality to be received.

Syntax: EnxRoom.setReceiveVideoQuality()

Method: public void setReceiveVideoQuality(JSONObject Quality)

Sample Code

JSONObject Quality = {
	"videoQuality": "HD", 
	"streamType":  "talker"
	};

room.setReceiveVideoQuality( Quality );

Error Codes and Exceptions