Basic Functions of React Native Toolkit describes the necessary tasks to achieve basic audio and video communication between participants connected from their End-Point Applications to an EnableX hosted Room. For more advanced use cases, please refer Advance Features & Moderator Controls.

Table of Contents

Get list of Audio Devices

You will need to specify an audio device (Microphone) or use the default microphone of your Client platform to initiate a stream. EnableX provides API support to get a list of audio devices (Microphone) available with your Client platform running the Client End Point application along with their Device names.

The Enx.getDevices() method is used to return a list containing all the microphones available with your client platform. You can build UI Element with the List to choose a Microphone.

Class: Enx

Method: getDevices(Callback)

Callback: Returns one or more of the following enumerated values: SPEAKER_PHONE,  WIRED_HEADSET,  EARPIECE,  BLUETOOTH,  NONE

Enx.getDevices(devices=> {
     // devices= Comma separated Device Names
}); 

Get selected Audio Device by User

Enx.getSelectedDevice() method is used to get the selected or used Audio Device for the Stream.

Method: getSelectedDevice(Callback)

 Enx.getSelectedDevice(device => {
     // device = Current Device Name
}); 

Initiate a Room

React Native Toolkit is used by the Client End Point Application to connect to the Virtual Room hosted at EnableX to establish a session. The process starts with initializing a Room Object using the EnxRoom Class. The Enx.initRoom() is used to initiate a Room.

Method: initRoom()

async componentWillMount() {
     Enx.initRoom();
}

Initiate Local Stream

A local stream has to be initialized at the Client End Point before you can publish it to the Room. The initialization process includes specifying media tracks, adding custom attributes etc. in a form of an object.

PropspublishStreamProp– Object definition given below:

 publishStreamProp: {
	audio: true,		// Whether to add Audio to stream
	video: true,		// Whether to add Video to stream
	data: true,		// Whether to add Data to stream
	name: "React Native",
	minWidth: "number",	// Video Frame Size
	minHeight: "number",  
	maxWidth: "number",
	maxHeight: "number",
	audioMuted: true,     // Audio muted on entry to room  
	videoMuted: true,     // Video muted on entry to room  
	maxVideoBW: number,   // Max Bandwidth 
	minVideoBW: number    // Min Bandwidth  
 } 

Join a Room with Stream

Connecting and joining a Room is a complex chain of events. You will need to ensure the previous event succeeded in order to proceed to the next event. When connected, a Bi-Directional Communication Channel will be established between the End Point and EnableX Server over a Web Socket. Both entities communicate with each other using Socket Events. Communication would fail if any network issue disconnects the Web Socket. ‘

The following basic steps are required to join room successfully

  • Initiate Room & Connect
  • If connected, initiate Stream.
  • Publish Stream

Enx.joinRoom() method comes as a handy tool for developer. It handles all complexities of connecting and joining the room.

A connected Web Socket might get disconnected due to network issues. For disconnected end-points, EnableX supports Auto Re-connection to the Session ensuring better user experience.

Tag: <EnxRoom token=TokenProps eventHandlers=EventProps localInfo=publishStreamProp roomInfo=roomInfo advanceOptionsInfo=advanceOptions>

Props:

  • token – JWT Token received through Server API Call
  • eventHandlers
    • roomConnected – To the end-point when its connected to Room
    • roomError – To the end-point when it fails to connect to Room
    • userConnected – To notify all connected users that a new user is connected to Room
    • activeTalkerList – To the end-point with list of Talkers after few seconds of receiving roomConnected event. Refer how to handle Active Talkers
  • localInfoPublish Stream Props – Optional
  • roomInfo – Optional. JSON with Reconnection Options. JSON keys explained below:
    • allow_reconnect Boolean. Default: true. Whether to enable Auto-Reconnect feature. If you set to false, Client End Point will not try reconnecting to EnableX
    • number_of_attempts String. Min Value: 1. Max Value: Not specified, use any number. Default: 3. Maxi number of times Client End Point tries to reconnect to EnableX
    • timeout_interval String. Timeout Interval in Millisecond to wait before attempting reconnect
  • advanceOptions – Optional. JSON with Advance Options. JSON Keys explained below:
    • battery_updates – Boolean. Pass true to receive battery updates/information
    • notify_video_resolution_change – Boolean. Pass true to receive Video Resolution Change Information
<EnxRoom
          token={this.props.token}
          eventHandlers={this.roomEventHandlers}
          localInfo={this.state.publishStreamProp}
          roomInfo={this.state.enxRoomInfo}
          advanceOptionsInfo={this.state.advanceOptions}
> 

publishStreamProp: {
	audio: true,	 
	video: true,	 
	data: true
}

enxRoomInfo: {
	allow_reconnect: true,
	number_of_attempts: "3",
	timeout_interval: "15"
} 

advanceOptions: {
	battery_updates: true,
	notify_video_resolution_change: true
} 


this.roomEventHandlers={
	roomConnected:event=> {
		// Connected. event receives Room Meta JSON
	},
	roomError:event=>{
		// Connection failed. Find error
	},
	userConnected:event=>{
		// A new user connected. user JSON has user information
	},
	activeTalkerList:event=>{
		// List of talkers in the Room
		// Received after room-connected
	}
}

Disconnect from a Room

A Client End Point can disconnect itself from the room to close its session. A disconnected End-Point will loose media and signaling socket immediately.

Once disconnected, the Toolkit will receive callback roomDisconnected  for you to handle UI. Also, all connected users of the session will receive callback userDisconnected so that they all can update the status of their UI.

Method: Enx.disconnet() – Without any parameter

Observers:

  • roomDisconnected  – To the user who is disconnected
  • userDisconnected  – To all other connected users
Enx.disconnect();

roomDisconnected:event=>{
     // You are disconnected
}

userDisconnected: event=>{
     // Notifies all about one disconnected user
     // event - Information of disconnected user
}

Publish Local Stream

The local stream with audio and video needs to be initiated and published into the Room for other participants to see and hear you. Enx.publish() method is used to publish a local stream to the connected Room. After the local stream is published to the Room, all participants are notified with an callback named  streamAdded.

Method: Enx.publilsh()

Callbacks:

  • streamPublished – To the publisher that the stream has been published
  • eventError – To the publisher to notify that publishing has failed
  • streamAdded – To all participants announcing new stream in room
roomConnected:event=>{
	Enx.publish();	// Publish Stream
}

streamPublished:event=>{
	// To publisher - Stream has been published 
}

eventError : event=>{
	// To publisher - Failed to publish
}

streamAdded:event=>{
	// To others - New stream is added
}

Subscribe Remote Streams

You must subscribe to the streams individually to receive media streams of other participants connected to a Room. Unless you subscribe a stream, you will not receive anything.

When a new stream is added to the Room a callback streamAdded is received with Stream Object. The receive the stream, you need to subscribe to it using Enx.subscribe() method.

Method: Enx.subscribe(remoteStreamID, Callback)

Parameters:

  • remoteStreamID- The Remote Stream Object to subscribe
  • Callback – Error in subscription

Callback: streamSubscribed – You are notified that the Stream has been subscribed.

// You are notified about new Stream in Room
streamAdded:event=>{	// Subscribe Stream
	Enx.subscribe(event.streamId,error=>{
		
	});
}

streamSubscribed :event=>{
    // Stream is subscribed 
}

Note! Please do not subscribe to your local stream. EnableX platform will not return your local audio and video stream. Details can be found in Active Talkers section below. However, as a publisher you will receive your own Screen Share and Canvas Streaming.

Handle Active Talkers

During a multi-party video conference, more server and Client-End-Point resources are consumed. Therefore, EnableX sends only 6 streams of users actively talking (generating sound) in the Room to each end-point. Additionally, it sends 2 streams, viz. Screen Share (Stream# 11) and Canvas Stream (Stream# 21).

On getting connected to Room, your Client End Point will also receive streamAdded Callback for all these 6+2 streams available in the Room. You need to subscribe to each of these streams.

Subsequently, whenever there is change in Talkers List, EnableX sends out an updated Active Talkers List to each End Point. The list of Active-Talkers is available in JSON format and sent through activeTalkerList callback. The list of Active Talkers comprises a list of talkers in ascending order i.e. latest talker will be listed first. Therefore, you can expect to receive the event frequently in a noisy room.

Callback: activeTalkerList – Come swith JSON given below:

Active Talkers List JSON

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

This Active Talkers JSON is used for managing the UI and to play audio and video streams from remote users. To play a specific stream, you need the Remote Stream object related to the streamId of a Talker. Please remember before you can play any stream from the Active Talkers list, you should have subscribed to all “dummy” streams received through Callback streamAdded.

activeTalkerList: event => {
	var tempArray = [];
        tempArray = event;
   	if (tempArray.length > 0) {
		this.setState({activeTalkerStreams: tempArray});
        }
	return (
	      <View>
		{this.state.activeTalkerStreams.map(function(element, index) {
		    return (
		      <EnxPlayerView key={String(element.streamId)}
			streamId={String(element.streamId)}
			style={{ width: width, height: height }}/>
		    );
		})}
	      </View>
	);
}

Note: The local Stream will not  be included in the Active Talkers JSON list sent to an End-Point even if the End Point is talking. Hence the Active Talker JSON list sent to different End Points varies. In case you need to play own stream, please use the local stream.

Get maximum permissible Talker Count

To know maximum permissible Active Talkers that you may receive and you can set, you may use Enx.getMaxTalkers() method.

Method: Enx.getMaxTalkers() – without parameter

Callback: getMaxTalkersResponse

Enx.getMaxTalkers();

getMaxTalkersResponse : event{
     // event: { "result": 0, "numTalkers": 6 } 
}

Get Talker Count

It may be necessary to know how many talkers are expected to receive with  activeTalkerList Callback, i.e. to know either the preset value of talkers or any custom value in effect which is either by the Application Developer or opted by End-Point User.

Method: Enx.getTalkerCount() – without parameter

Callback: getTalkerCountResponse

Enx.getTalkerCount();

getTalkerCountResponse : event{
     // event: { "result": 0, "numTalkers": 6 } 
}

Set Talker Count

EnableX sets a maximum of 6 active talkers in the active talker-list with  activeTalkerList Callback. However, you may opt to receive less talkers at a Client End Point if you so require. This may either be a predefined value, or this value may be set at run-time in a connected session. If required you can create UI for the connected user to opt for number of active-talkers the user wants to receive.

Method: Enx.setTalkerCount(numTalkers)

ParametersnumTalkers – No. of talkers you want to receive. Range 0-6

  • If you set numTalkers to any value from 1 to 6 – you will receive those many talkers in the list.
  • If you set numTalkers to 0 (zero), then list doesn’t become empty. Rather, you would start receiving 3 audio streams only. Video Streams will not be carried.

Callback: setTalkerCountResponse

Enx.setTalkerCount(4);

setTalkerCountResponse : event{
     // event: { "result": 0, "numTalkers": 4 } 
}

Play Stream

You can play a local stream as well as remote streams including screen-share, canvas streams using EnxStream and EnxPlayerView Tags.

Tags:

  • <EnxStream streamId=StreamID eventHandlers=ListenerEvents> – To create stream
  • <EnxPlayerView streamId=StreamID isLocal="remote" eventHandlers=ListenerEvents> – To play remote stream
  • <EnxPlayerView streamId=StreamID isLocal="local" eventHandlers=ListenerEvents> – To play local stream

Props:

  • streamId – Stream ID of the Stream to be played
  • isLocal – Enum: local, remote
  • eventHandlers – To add all event listeners to handle with the Stream

Helper Methods:

  • changePlayerScaleType(scalingMode, streamId) – Parameters explained below:
    • scalingMode – Enumerated Values: SCALE_ASPECT_BALANCED,  SCALE_ASPECT_FIT,  SCALE_ASPECT_FILL
    • streamId – String. The Stream ID that needs to be scaled in Player
  • setZOrderMediaOverlay(isOverlay, streamId) – Parameters explained below:
    • isOverlay – Boolean. Use true to overlay
    • streamId – The Stream ID that you want to play as overlay
  • setConfigureOption(configObject, streamId) – Parameters explained below:
    • configObject – JSON Object
    • streamId = The Stream ID that you want to configure
var propertyDict = {
	textColor: -10053376, 
	textSize: 12, 
	textStyle: 1, 
	text_background: 0
	}

var dict = {
	enable: true, 
	properties:propertyDict
	}

var overlayDict = { overlay: dict }

Enx.setConfigureOption(overlayDict, this.state.localStreamId); 
Enx.changePlayerScaleType(SCALE_ASPECT_FIT, this.state.localStreamId); 

<EnxStream 
	streamId={String(element.streamId)} 
	eventHandlers={this.streamEventHandlers}>

<EnxPlayerView 
	streamId={String(element.streamId)} 
	isLocal="local"
	eventHandlers={this.streamEventHandlers}> 

Handle Disconnection, Interruption & Re-Connection

A Client End Point is connected with EnableX over Secured Web Socket. A connected End Point might get disconnected from EnableX due to network issues. The End Point gets notified with an event connectionLost and connectionInterrupted.

Callbacks:

  • connectionLost – When network connection is lost
  • connectedInterrupted – When network connection is interrupted, e.g. switched from 4G to Wife and vice versa
connectionLost: event => {
	// event - connection disconnected
	// lost connectivity
}

connectionInterrupted: event => {
	// event - connetion is interrupted 
	// network changed. e.g. switched between WiFi, 4G 
}

For disconnected end-points, EnableX supports Auto Re-connection to the Session ensuring better user experience. To use Automatic Re-Connection feature, you must join Room with Re-Connection options. Note that Auto-Re-Connect doesn’t work when:

  • Last Participant disconnected from Adhoc Room
  • User is dropped from Room by Moderator
  • User disconnects explicitly

Callbacks:

  • userReconnect – When End-Point successfully gets reconnected with EnableX
  • reconnect – When End-Point attempts to reconnect
reconnect: event => {
	// event - reconnecting...
}

userReconnect: event => {
	// event - reconnected
}

Handle Network Bandwidth Issues

A Client End Point might experience Bandwidth throttling issues that might affect publishing and receiving remote stream and their quality. EnableX provides callbacks to notify such events to End-Point so that end-user can be notified.

Callbacks:

  • bandWidthUpdated – To notify significant change in available bandwidth affecting publishing and receiving remote streams.
  • shareStateEvent – To notify significant change in available bandwidth affecting publishing and receiving of screen share.
  • canvasStateEvent – To notify significant change in available bandwidth affecting publishing and receiving of canvas streaming.
// Bandwidth Change affecting Streaming
bandWidthUpdated: event => {
	/* event = 
	 [{	"reason" : "receive bandwidth low", 
		"streamId" : streamId 
	}]  */
}

// Bandwidth Change affecting Screen Share
shareStateEvent: event => {
	/* event = 
	{	reason = bw; 
		streamId = 11; 
		videomuted = 1; 
	} */
}

// Bandwidth Change affecting Canvas Streaming
canvasStateEvent: event => {
	/* event = 
	{	reason = bw; 
		streamId = 21; 
		videomuted = 1; 
	} */
}

Explore React Native Toolkit