Video API v1.9 Android SDK / Advance Features

Advance Features Android SDK covers API capabilities to build feature-rich End-Point Applications. as Moderator Controls.

Table of Contents

Switch Source Media Devices of Published Stream

A user may want to switch to alternate Media Devices for his published stream. EnableX API allows Media Device switching on the fly.

The APIs allows you to switch between Rear and Front Camera and to alternate available Microphone.

Switch between Rear & Front Camera

If user looks to switch between Rear and Front Camera as a source for published Stream, use EnxSream.switchCamera() method.

Class: EnxStream

Method: public void switchCamera() – No parameter needed

localStream.switchCamera();

Switch to alternate Microphone

If user looks to switch Micrcophone used to create published Stream to an alternate Microphone, use EnxRoom.switchMediaDevice() method. This API requires ID of the new device to switch to. You can use EnxRoom.getDevices() method to fetch a list of microphones and create a UI for new device selection.

Class: EnxRoom

Method: public void switchMediaDevice(String micDeviceId)

Parameters: micDeviceId – String, Target Microphone Device ID

Observer: onNotifyDeviceUpdate – When Audio Device Update is complete. Returns with switched Microphone Device ID

room.switchMediaDevice( micDeviceId );

public void onNotifyDeviceUpdate( String micDeviceId ) {
      // Switched to micDeviceId
}

Update Stream Configuration

Availability: Android SDK v.1.5.6+

If you like to re-configure your stream by adding new or udpating existing specification parameters of a stream. Please use EnxStream.updateConfiguration() method to update the parameters of a stream. Both remote and local streams can use this method of updating the stream parameters.

Class: EnxStream

Method: public void updateConfiguration(JSONObject jsonObject)

Parameters: jsonObject– Object containing new configuration options

  localStream.updateConfiguration(JSONObject jsonObject); 

// The jsonObject Object may be like the following
/*
jsonObject = {
     "maxVideoBW": "900",
     "minVideoBW": "150",
     "maxAudioBW": "150",
     "minAudioBW": "150"
 };
/

Mute / Unmute Audio in a Stream

Use EnxStream.muteSelfAudio() method to mute and unmute audio from Local Stream. When a user mutes or unmutes audio from own Published Stream, all other connected users of the room are notified with onRemoteStreamAudioMute and onRemoteStreamAudioUnMute callbacks respectively. Listen to these events to update related UI elements.

Class: EnxStream

Methods: public void muteSelfAudio( boolean ) – Pass true to mute, false to unmute audio

Callbacks:

  • onRemoteStreamAudioMute – to all participants notifying user has muted audio
  • onRemoteStreamAudioUnMute – to all participants notifying user has unmuted audio
  • onAudioEvent – to self that audio is either muted or unmuted
localStream.muteSelfAudio(true); // To mute audio on local stream
localStream.muteSelfAudio(true); // To unmute audio on  local stream

// To self. Audio is muted/unmuted.
public void onAudioEvent(JSONObject json) {
   // json { "result":0, "msg": "Audio Off" }  
   // json { "result":0, "msg": "Audio On" }  
}

// To all. Audio muted by Remote user
public void onRemoteStreamAudioMute(JSONObject json) { 
   // json {"result":0, "msg":"User muted audio", "clientId": "XXX" }   
}

 // To all. Audio unmuted by Remote user
public void onRemoteStreamAudioUnMute(JSONObject json) { 
   // json {"result":0, "msg":"User unmuted audio", "clientId": "XXX" }   
}

Mute / Unmute Video in a Stream

Use EnxStream.muteSelfVideo() method to mute and unmute video from Local Stream. When a user mutes or unmutes audio from own Published Stream, all other connected users of the room are notified with onRemoteStreamVideoMute and onRemoteStreamVideoUnMute callbacks respectively. Listen to these events to update related UI elements.

Class: EnxStream

Methods: public void muteSelfVideo( boolean ) – Pass true to mute, false to unmute video

Callbacks:

  • onRemoteStreamVideoMute – to all participants notifying user has muted video
  • onRemoteStreamVideoUnMute – to all participants notifying user has unmuted video
  • onVideoEvent – to self that video is either muted or unmuted 
localStream.muteSelfVideo(true); // To mute video local stream
localStream.muteSelfVideo(false); // To unmute video local stream

// To self. Video is muted/unmuted.
public void onVideoEvent(JSONObject json) {
   // json { "result":0, "msg": "Video Off" }  
   // json { "result":0, "msg": "Video On" }  
}

// To all. Video muted by Remote user
public void onRemoteStreamVideoMute(JSONObject json) { 
   // json {"result":0, "msg":"User muted video", "clientId": "XXX" }     
}

// To all. Video unmuted by Remote user
public void onRemoteStreamVideoUnMute(JSONObject json) {  
   // json {"result":0, "msg":"User unmuted video", "clientId": "XXX" }   
}

Send Chat Data

INFO! EnableX Android SDK 1.4.2 support an advance version of Public & Private Messaging API. Therefore, you are discouraged to use this Stream based Messaging. It will be deprecated in future version.

You may implement basic text-chat communication using EnableX API. The Text-Data is carried on a separate data track in a published Stream and received by all subscribers of the stream.

  • Notes to send message:
    • You must initiate your stream with data track enabled using the JSON Payload as {data: true}
    • You must publish your stream into the room before you can use the EnxStream.sendData() method.
  • Notes to receive message:
    • You must subscribe to the remote stream
    • User Observer onReceivedData  to receive any incoming message.

Class: EnxSream

Method: public void sendData(String message, String sender) – to send out message to all

Parameter:

  • message – Message Body
  • sender – Sender’s Name

Observer: onReceivedData to all participants in the room

localStream.sendData("message", "senderName"); 

// To all. New Message received in JSON object
public void onReceivedData(JSONObject json) { 
   // json { message : { from : "", message : "", timestamp : ""}}
}

Important Note! EnableX 1.3.* doesn’t support private messaging. Using this API you may only do Public Chat / Messaging. As chat data is carried with the published stream you may not send chat messages unless your stream is published.

Private, Public & Group Messaging

This is an advance messaging feature between Session participants. You can do following type of messaging in a session among participants:

  • Public Messaging: To send message to all connected users.
  • Private Messaging: To send message to a specific user.
  • Group Messaging: To send message to more than one specified users.

Messaging feature neither require the sender to publish his Stream, nor receivers to subscribe.

Class: EnxRoom

Method: public void sendMessage(String Message, boolean isBroadcast, array RecipientIDs)

Parameters:

  • MessageOpt – String type message.
  • IsBroadcast – Boolean. Use true for Public Broadcast, Use false for private messaging to one or more recipients.
  • RecipientIDs – Array of ClientIDs whom you wish to send private messages.

Callback:

  • onReceivedChatDataRoom – Receives message in JSONObject. Upto Android SDK v1.5.2. Deprecated in v1.5.3.
  • onMessageReceived – Receives message in JSONObject. Android SDK v1.5.3+
String message = "XXX";
List<String> Recipient_ClientIds;

room.sendMessage(message, true, null); // Public Messaging

// Private message to one or selected Recipients
room.sendMessage(MessageOpt, false, Recipient_ClientIds);

// Users Receive Message through Callback. 
// Available till v1.5.2. Deprecated in v1.5.3
Public void onRecievedChatDataAtRoom(JSONObject jsonobject){
    String textMessage = jsonObject.getString("msg");
}  

// Users Receive Message through Callback. 
// Available from v1.5.3.
Public void onMessageReceived(JSONObject jsonobject){
    String textMessage = jsonObject.getString("msg");
}

File Sharing

Availability: Android SDK v1.5.3+

EnableX File Share API allows users of a RTC session to send and receive file(s) to/from each other. Using the available APIs, you can initiate file transfer to share, cancel a file transfer, get notified on a shared file and receive/download shared file.

Upload File to share

The file sharing process starts with a user initiating a file transfer to EnableX Server. To initiate a file transfer use EnxRoom.sendFiles() method.

Class: EnxRoom

Observer: public void setFileShareObserver(EnxFileShareObserver-Object)

Method: public void sendFiles(FrameLayout view, boolean isBroadcast, List clientIdList)

Parameters:

  • view– FrameLayout view where user shows UI to choose file to upload.
  • isBroadcast – Boolean. This is to share file among all participants in the Session. If you need to target the file share to specific user, then set it to false.
  • clientIdList – List of Client IDs. This is to share the file among specified Clients only. If broadcast is set to true, clientIdList is ignored.

Callbacks at Sender End:

  • onInitFileUpload – To notify sender that file upload process is initiated
  • onFileUploaded – To notify sender that file has been uploaded
  • onFileUploadFailed – To notify sender that file upload process has failed

Callbacks at Receiver End:

  • onFileUploadStarted – To notify intended receiver that a file is being uploaded
  • onFileAvailable – To notify intended received that a file is ready to download
room.sendFiles(FrameLayoutView, true, NULL); 

// To intended receiver - A new file upload started 
public void onFileUploadStarted(JSONObject jsonObject) {
       // Handle JSON Object with file information
}

// To intended receiver - A file is available for download 
public void onFileAvailable(JSONObject jsonObject) {
	// Handle JSON Object with file information
}

// To sender - File upload process started
public void onInitFileUpload(JSONObject jsonObject) {
	// Handle JSON Object with file information
}

// To sender - File upload is complete
public void onFileUploaded(JSONObject jsonObject) {
	// Handle JSON Object with file information
}

// To sender - File upload has failed
public void onFileUploadFailed(JSONObject jsonObject) {
	// Handle upload error
}

Error Codes: Upload process may encounter error. You will be notified with JSON Object with error code:

Error CodeError Description
5089Storage Access denied
5091 File Sharing not available in this context
1185Too large file. Max allowed Size: NNNN
1182Failed to upload file

Download shared File

Intended Recipients needs to download each file shared with them individually. Therefore, recipient needs to know information on the available files to download to initiate a download process.

Know files to download

Room Lookup: To know what all files are available for download, you may call EnxRoom.getAvailableFiles() method. It returns a JSON Object with all files available for download

Method: public JSONObject getAvailableFiles()

let myFiles = room.availableFiles;

// myFile contains array of File Information
[
	{
		name: "DP1.pdf",  
		size: 191002,
		index: 0 // ID or File Reference
	} 
]

When New File is availble: A receive end point is notified as and when a file is made available for download using callback onFileAvailable 

// To intended receiver - A file is available for download 
public void onFileAvailable(JSONObject jsonObject) {
	// Handle JSON Object with file information
}

Initiate File Download

As you know about the file(s) to download, you need to initiate download individually using EnxRoom.downloadFile() method.

Class: EnxRoom

Method: public void downloadFile(JSONObject fileInfo, boolean isAutoSave)

Parameters:

  • fileInfo– JSON Object of file to be downloaded.
  • isAutoSave – Whether to save the file automatically. If not to be save automatically, you would receive Base64 encoded RAW data to handle file saving processes manually. If auto-saving is on, you would receive saved file path.

Callbacks at Receiver End:

  • onFileDownloaded – To notify file has been downloaded with either Base64 Raw data to be saved (When auto-saving is false) or saved file path.
  • onFileDownloadFailed – To notify download failure
room.downloadFile(JSONObject, true); 

// To receiver - File has been downloaded
public void onFileDownloaded(JSONObject jsonObject) {
       // Handle JSON Object with file information
}

// To receiver - File download has failed
public void onFileDownloadFailed(JSONObject jsonObject) {
	// Handle download error
}

Error Codes: Download process may encounter error. You will be notified with JSON Object with error code:

Error CodeError Description
5089Storage Access denied
5090Failed to save file
1183Failed to download file
1181File Download not available in this context

Share Screen

A Client End Point can start a Screen-Share using EnxRoom.startScreenShar() method. The method creates a stream of Mobile Screen @ 6fps to publish to the Room. EnxRoom.stopScreenShare() method stops the ongoing Screen Share. Screen Share continues even when the Application goes into background.

When a user starts or stops Screen Share, all connected users of the room are notified with onScreenSharedStarted and onScreenSharedStopped callbacks. As Screen-Share is also a Stream, you can play it using a Video Player. Screen Share is carried on Stream ID# 101. Client End Point must subscribe to this Stream ID to receive and play it locally.

Note: You need to enable screen share while defining a room with { "settings": { "screen_share": true; }) in JSON Payload. Know more…

Observer: public void setScreenShareObserver(EnxScreenShareObserver-Object)

Methods:

  • public void startScreenShare() – To start Screen Share
  • public void stopScreenShare() – To stop Screen Share

Callbacks:

  • onScreenSharedStarted – to know that a Screen Share has started
  • onScreenSharedStarted – to know that a Screen Share has stopped
// Initiate Screen Share Observer to receive Callbacks
room.setScreenShareObserver(this);

room.startScreenShare();	// Start Screen Share
room.stopScreenShare();		// Stop Screen Share

// A new Screen Share Stream is available, receive Information
public void onScreenSharedStarted(EnxStream enxStream) {
	// Get EnxPlayerView from ensStream
	// And add to View
	yourView.addView(enxStream.mEnxPlayerView);
} 

// Screen Share has stopped. Receive Information
public void onScreenSharedStopped(EnxStream enxStream){
	// And remove View from yourView
	yourView.removeAllViews();
}

Use Canvas Streaming

Your application may require Canvas Streaming. Canvas Streaming helps you publish any view into the Room.

Start Canvas Streaming

You can use EnxRoom.startCanvas() method to start canvas streaming.

Important Notes!

  • You need to enable a Room to use Canvas Streaming in it. To enable Canvas Streaming, use { settings: { canvas: true; }} in the JSON Payload to create Room.
  • Once Canvas Streaming gets started, all participants are notified with callback onCanvasStarted.
  • Canvas Stream is carried on Stream ID# 102. Client End Point must subscribe to this Stream ID to receive and play it locally.

Method: public void startCanvas(View view)

Parameter:

  • View: The View that will be used for Canvas Streaming

Callacks:

  • onStartCanvasAck – To the publisher to acknowledge that Canvas Streaming has started
  • onCanvasStarted – to notify all that a Canvas Streaming has started
room.startCanvas(view); 

// Publisher receives acknowledgement
public void onStartCanvasAck(JSONObject jsonObject) {
       // Handle JSON Object      
}

// Others in the Room are notified 
public void onCanvasStarted(EnxStream enxStream) {
 // Get EnxPlayerView from ensStream
 // And add to View
 yourView.addView(enxStream.mEnxPlayerView);
}

Stop Canvas Streaming

An ongoing canvas streaming may be stopped using EnxRoom.stopCanvas() method. When streaming is stopped, all participants in the room are notified using an event.

Method: public void stopCanvas()

Callbacks: 

  • onStoppedCanvasAck – To the publisher to acknowledge that a Canvas Streaming has stopped
  • onCanvasStarted– To notify all that a Canvas Streaming has stopped
room.stopCanvas(); 

// Publisher receives acknowledgement
public void onStoppedCanvasAck(JSONObject jsonObject) {
       // Handle JSON Object   
}

// Others in the Room are notified 
public void onCanvasStopped(EnxStream enxStream) {
	// And remove View from yourView
	yourView.removeAllViews();
}

Receive & Play Canvas Streams

An Client End Point Application developed using Android SDK can’t initiate HTML5 Canvas Streaming. However, it can receive Canvas Streaming initiated by other Client End Point Application developed using Web SDK that runs on Web Browsers.

When a user starts or stops HTML5 Canvas Streaming, all connected users of the room are notified with onCanvasStarted  and  onCanvasStopped. As its a Stream, you can play it using a Video Player. Note that Canvas Stream is carried on Stream ID# 102. Client End Point must subscribe to this Stream ID to receive and play it locally.

Observers:

  • onCanvasStarted – to know that a Canvas Streaming has started
  • onCanvasStopped – to know that a Canvas Streaming has stopped 
// A new Canvas Streaming is available, receive Information
public void onCanvasStarted(JSONObject json) {
	String streamId		= json.getString("streamId");
	String canvasName	= json.getString("name");
	
	// Get Remote Streams in the Room
	Map<String, EnxStream> map = room.getRemoteStreams();

	// The Canvas Stream Object
	EnxStream CanvasStream = map.get(streamId); 
	
	// Create playerView for Canvas Stream
	EnxPlayerView canvasPlayerView = new EnxPlayerView(
		Current-Class-Context, ScalingType, mediaOverlay);

	// Attach stream to playerView
	CanvasStream.attachRenderer(canvasPlayerView);
	yourLocalView.addView(canvasPlayerView);
} 

// Canvas Streaming has stopped. Receive Information
public void onCanvasStopped(JSONObject json){
	String streamId		= json.getString("streamId");
}

Annotation

Availability: Android SDK v1.5.6+

Using Annotation API user can annotate on a Remote Stream. To implement Annotation, all you need to know how to add Annotation Toolbar, how to start and Stop Annotation and handle related Delegate Methods

Note: For Annotation feature to work, you need to enable Canvas Streaming while defining a Room; use { settings: { canvas: true; }}

Annotation Toolbar

To initiate Annotation Toolbar, use below code snippets in XML:

<enx_rtc_android.annotations.EnxAnnotationsToolbar
        android:id="@+id/annotations_bar"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"/>

Start / Stop Annotation

To initiate Annotation, you need to setAnnotationObserver after getting connected to the room.

Class: EnxRoom

Observer: public void setAnnotationObserver(Annotations-Observer-Instance)

Methods:

  • public void startAnnotation(EnxStream) – To start Annotation o given Stream Object
  • public void stopAnnotation() – To stop Annotation

Parameter: EnxStream: Stream Object on which Annotation to start

Callbacks:

  • public void onStartAnnotationAck(JSONObject) – Acknolwedgement to the Annotator that Annotation has started
  • public void onAnnotationStarted(EnxStream) – Notification to all others that Annotation has started
  • public void onStoppedAnnotationAck(JSONObject) – Acknolwedgement to the Annotator that Annotation has stopped
  • public void onAnnotationStopped(EnxStream) – Notification to all others that Annotation has stopped
// Set Observer
room.setAnnotationObserver(Annotations-Observer-Instance);

room.startAnnotation(EnxStream enxStream); // Start Annotation
room.stopAnnotation(); // Stop Annotation

// Notification to all - Annotation started
public void onAnnotationStarted(EnxStream enxStream) {
	// Add Annotations view to parent view
	((ViewGroup) mAnnotationViewContainer).addView(enxStream.EnxPlayerView);

}
 
// Acknowlegement to Annotator - Annotation started
public void onStartAnnotationAck(JSONobject jsonObject) {
	// Handdle UI. See info on jsonObject
}

// Notification to all - Annotation stopped
public void onAnnotationStopped(EnxStream enxStream) {
	// Remove Annotations view to parent view
	((ViewGroup) mAnnotationViewContainer).removeView(enxStream.EnxPlayerView);

}

// Acknowlegement to Annotator - Annotation stopped
public void onStoppedAnnotationAck(JSONobject jsonObject) {
	// Handdle UI. See info on jsonObject
}

Error Codes: Annotation process may encounter error. You will be notified with JSON Object with error code:

Error CodeError Description
5093Annotation Access denied
5104Annotations is already in progress
5106Annotations is starting
5108Annotation Stream is not valid
5109Annotation Stream publishing failed

Change to Audio only call

If you want change to a audio-only call, i.e. you neither want to receive anyone’s video not want to publish your video; you may use EnxRoom.setAudioOnlyMode() method. This method acts as a toggle to switch between audio-only and audio-video call.

This opt-in is only for the specific End-Point and doesn’t affect others in the room.

Class: EnxRoom

Method: publish void setAudioOnlyMode( boolean AudioOnly)

Parameter: Boolean AudioOnly

  • true: audio-only call
  • false: audio-video call
room.setAudioOnlyMode(true);   // Switched to Audio-Only call
room.setAudioOnlyMode(false);  // Switched back to Audio-Video call

Receive Streaming Stats

For Streaming Quality analysis, you may opt to receive Streaming Stats and get them displayed on respective Player. Once opted, you will receive Stats for all Streams received at the end point from the Room. You will receive following important information on Streams:

  • Publishing Resolution
  • Bandwidth at Publisher End
  • Receiving Resolution
  • Receiving Bandwidth consumed
  • Available Bandwidth at Receiver
  • … there are more

Class: EnxRoom

Method: public void enableStats(isEnabled, EnxStatsObserver) – To enable disable streaming stats for all streams in the Room.

Parameters:

  • isEnabled – Boolean Parameter. Pass true to enable, false to disable
  • EnxStatsObserver – EnxStatsObserver instance

Callbacks:

  • onAcknowledgeStats – Acknowledges that stream stats is enabled or disabled
  • onReceivedStats – When all streams’ stats is received
room.enableStats(true, this);

@Override
public void onAcknowledgeStats(JSONObject jsonObject) {

}

@Override
public void onReceivedStats(JSONObject jsonObject) {
	Log.e("onReceivedStats", jsonObject.toString());
}

Further you may opt to receive stream specific stats only being played on a player. However to receive individual stream stats, you would require to enable stats at room level too.

Class: EnxPlayerView

Method: public void enablePlayerStats( isEnabled, EnxPlayerStatsObserver) – To enable disable streaming stats for a individual stream

Parameters:

  • isEnabled – Boolean Parameter. Pass true to enable, false to disable
  • EnxPlayerStatsObserver – EnxPlayerStatsObserver instance

Callback: onPlayerStats – When Player’s stream stats is received 

playerview.enablePlayerStats(true, this);

@Override
public void onPlayerStats(JSONObject jsonObject) {
	
}

Handle Audio Device Updates

If any audio device e.g. Bluetooth Audio, Ear Phone or Head Phone connected or attached to the Mobility Device, EnableX callbacks notifies such events to the Application; so they can be handled effectively.

EnableX has following 3 Callbacks to get notified on audio device updates:

Callbacks:

  • onNotifyDeviceUpdate – When use switches to alternate media devices at run-time
  • onDeviceAdded – When a new Audio Device is attached or connected
  • onDeviceRemoved – When a Audio Device is detached or disconnected
public void onDeviceAdded(String message) {
	// New Device added
}

public void onDeviceRemoved(String message) {
	// Device removed
}

public void onNotifyDeviceUpdate (String message) {
	// Device switched
}

Handle Application Switch from Foreground to Background

User may switch to different application pushing your RTC Application to Background and vice versa. You need to handle such activity using following methods:

Class: EnxRoom

Method: public void stopVideoTracksOnApplicationBackground( localMuteState, remoteMuteState )

Parameters:

  • localMuteState – Boolean. Pass false to pause local Video Stream, true to continue with publishing
  • remoteMuteState – Boolean. Pass false to pause receiving remote Video Stream, true to continue receiving

Method: public void startVideoTracksOnApplicationForeground( localUnmuteState, remoteUnmuteState )

Parameters:

  • localUnmuteState – Boolean. Pass true to resume sending local Video Stream if it was stopped while getting to Background.
  • remoteUnmuteState – Boolean. Pass true to resume receiving remote Video Streams if they stopped while getting to Background. 
// When application goes to Background 
boolean localMuteState = true;
boolean remoteMuteState = true; 

room.stopVideoTracksOnApplicationBackground( localMuteState, remoteMuteState ); 

// When application comes back to Foreground 
boolean localUnmuteState = false;
boolean remoteUnmuteState = false;

room.startVideoTracksOnApplicationForeground(localUnmuteState, remoteUnmuteState);

Note: If user wants to use microphone when App is in background then application should have foreground service. App running in the foreground (or a foreground service) can capture the audio input. When an App without a foreground service or foreground UI component starts to capture, the App continues to run but receives no-audio, even if it is the only app capturing audio at that time.

Ref: https://developer.android.com/guide/topics/media/sharing-audio-input#pre-behavior

Opt to receive desired Video Quality

The Client End Point may opt to receive the desired video quality for available bandwidth. You may create UI based on the enumerated values of video quality as explained below.

Class: EnxRoom

Method: public void setReceiveVideoQuality(JSONObject Quality)

Parameters: Quality JSON may have following keys:

  • Quality – JSON Object may have the following keys:
    • videoQuality: Enumerated Values: Auto, HD, SD, LD. Set it to Auto if you want EnableX to decide optimum quality for you dynamically.
    • streamType: Enumerated Values: talker, canvas
JSONObject Quality = {
	"videoQuality": "HD", 
	"streamType":  "talker"
	};

room.setReceiveVideoQuality( Quality );

Use Custom Signaling

Your Application might require to send instructions, data to one or more recipient connected in a Session to deploy new features, business workflow. For example, you wan to create a Polling mechanism among participants. EnableX supports Custom Signaling method through which you can build such utility that requires passing of messages among participants.

Using Custom Signaling Method, you might send message to all or selected participants in a Room. You can define your custom data structure to pass to meet your business requirement.

Method:  public void sendUserData(JSONObject data, boolean isBroadcast, array RecipientIDs)

Parameters:

  • data – JSONObject containing custom keys. This object is passed to Recipients as is. EnableX doesn’t enforce it’s structure. Be advised to define keys effectively for signaling needs.
  • isBroadcast – Boolean. Use true for Public Broadcast, Use false for signaling to one or more recipients.
  • RecipientIDs – Array of ClientIDs whom you wish to send private messages.

Callback: 

  • onReceivedChatDataRoom – Receives signaling in JSONObject. Available until Android SDK v1.5.2. Deprecated on v1.5.3
  • onUserDataReceived – Receives signaling in JSONObject. Available from Android SDK v1.5.3

data JSONObject Sample:

// Example: Important Information you can put with custom keys
// You may define the JSONObject as per your business needs

JSONObject data = {
    "sender": "Sender's Name",
    "message": "Message body",
    "custom_key": "Data"
}

To send & receive Custom Signaling

List<String< Recipient_ClientIds;

room.sendMessage(data, true, null); // Signaling to all

// Signaling to one or selected Recipients
room.sendUserData(data, false, Recipient_ClientIds);

// Users receives Signaling Message through Callback
// Available till v1.5.2. Deprecated in v1.5.3
Public void onRecievedChatDataAtRoom(JSONObject jsonobject){
    String textMessage = jsonObject.getString("msg");
}  

// Users receives Signaling Message through Callback
// Available from v1.5.3.
Public void onUserDataReceived(JSONObject jsonobject){
    // Handle JSON Object
}

Break-Out Room

Break-Out Rooms are meant for discussion aside off the main Video Room. i.e. the Parent Room. A Creator or Owner of the Break-Out Room may invite one or more users from Parent Room to the Break-Out Room. The invited users would be notified about the request and they are required to accept the request to join the Break-Out room. Users moving out of the Parent Room will be treated as “paused” user in the Parent Room until they return.

Consider the following points while implementing Break-Out Room feature in your Application:

  • Break-Out room can be created by user from the Parent Room only. One can’t create another Break-Out Room being already within a Break-Out Room.
  • A Break-Out Room may be defined with a max allowed participant in it. Your Break-Out Room Size is limited to Parent Room’s maximum allowed Active Talkers minus one person e.g. Users in Break-Out < Max Active Talker of Parent Room.
  • Break-Out room currently supports only Audio Call with Screen Share and Canvas Streaming support.
  • The Creator/Owner of a Break-Out has right to invite/add other users into the Room capped at Break-Out Room-Size.

Create Break-Out Room

Use the following method to create a Break-Out Room. The creator owns the Break-Out Room and has right to invite users into it.

Method: public void createBreakOutRoom(JSONObject RoomDefinition);

Parameters:

  • RoomDefinition – Required. JSON Object to define the Room Parameter.
    • participants – Numeric. Required. No. of Participants (Limited to maximum allowed Active Talkers). Range: Min: 2. Max: max_active_talkers of Parent Room – 1
    • audio – Boolean. Required. Set to true to enable Audio Communication in Break-Out Room.
    • video – Boolean. Required. Set to true to enable Video Communication in Break-Out Room. Currently this is not supported.
    • canvas – Boolean. Required. Set to true to enable Canvas Streaming in Break-Out Room.
    • share – Boolean. Required. Set to true to enable Screen Share in Break-Out Room.
    • max_rooms – Numeric. Required. Total number of Break-Out room instance needed.

Callbacks:

  • onAckCreateBreakOutRoom – To get result of Create Break-Out Room as JSON Array
JSONObject  RoomDefinition = {
	"participants" :2, 
	"audio" : true,
	"video": false , 
	"canvas": false, 
	"share": false, 
	"max_rooms": 1
};

enxRoom.createBreakOutRoom(RoomDefinition);

public void onAckCreateBreakOutRoom(JSONObject jsonObject) {
	// jsonObject is JSON with created Break-Out Room Information, e.g.
	/*		
	
		{	msg: {​​
					rooms: [ 
						xxx, xxx
					]
			},
			result: 0
		|
	
	*/
}

Invite Users to join a Break-Out Room

Creator or Owner of a Break-Out Room may invite one or more users from Parent Room to join the Break-Out Room. The following method must be used from the Parent Room to to invite users to Break-Out Room. Note that this method is not available for execution from a Break-Out Room.

Method: public void inviteToBreakOutRoom(JSONObject Invitee)

Parameters:

  • Invitee – JSON Object to define the Invitees to a Break-Out Room.
    • clients – Array of ClientIds of users who are being invited.
    • room_id – String. Room-ID of the Break-Out Room to which the users are being invited

Callbacks:

  • onAckInviteBreakOutRoom – To get result of invitation process.
  • onInvitationForBreakoutRoom – Invited Users get notified that they are being invited to join a Break-Out Room.
JSONObject invitee = {
	"clients" : [ clientId1, clientId2], 
	"room_id" : "RoomID"
};

enxRoom.inviteToBreakOutRoom(invitee);
 
public void onAckInviteBreakOutRoom(JSONObject jsonObject) {
	// jsonObject is the result of invitation process, e.g.
	/*		
	{	"msg": "Success",
		"result": 0,
	}
	*/
} 

public void onInvitationForBreakoutRoom(JSONObject jsonObject) {
	// jsonObject carries the invitation details, e.g.
	/*		
	{	"result": 0,
	}
	*/
}

Create Break-Out Room & Auto-Invite Users

To support some use-cases where auto-assignment of users into different Break-Out Room is required, you may use this method. This method creates a Break-Out Room with given specification and invites users to join a room at random depending on room’s capacity.

Method: public void createAndInviteBreakoutRoom (JSONObject RoomDefinition)

Parameters:

  • RoomDefinition – Dictionary to define the Room Parameters as explained above.

Callbacks:

  • onAckCreateAndInviteBreakOutRoom – To get result in JSON Array
JSONObject  RoomDefinition = {
	"participants" :2, 
	"audio" : true,
	"video": false , 
	"canvas": false, 
	"share": false, 
	"max_rooms": 1
};

enxRoom.createAndInviteBreakoutRoom(RoomDefinition);

public void onAckCreateAndInviteBreakOutRoom(JSONObject jsonObject) {
	// jsonObject is JSON with created Break-Out Room Information, e.g.
	/*		
	
		{	msg: {​​
					rooms: [ 
						xxx, xxx
					]
			},
			result: 0
		|
	
	*/
}

Join a Break-Out Room

Being invited, a user may join a Break-Out room by using the method given below. This method may be used from the Parent Room only. Note that a user may only join one Break-Out Room at any given point. Subsequently the user exits the Break-Out Room to join back the Parent Room. Further, a user is now allowed to join any other Break-Out Room.

Method: public void joinBreakOutRoom(JSONObject Joinee, JSONObject streamInfo)

Parameters:

  • Joinee– JSON Object to define the Joinee to a Break-Out Room.
    • role – String. Required. Enumerated Values: participant, moderator.
    • room_id – String. Required. Room-ID of the Break-Out Room to which the user is joining.
  • streamInfo – JSON Object to define stream information while joining the Room.
    • audio – Boolean. Set true to join with Audio.
    • video – Boolean. Set true to join with Video. This is not available now.

Callbacks:

  • onConnectedBreakoutRoom – Succeeded to join Break-Out Room
  • onFailedJoinBreakOutRoom – Failed to join Break-Out Room
  • onUserJoinedBreakoutRoom: – On getting connected to Break-Out Room, all other users in the room are notified about the new user joined.
JSONObject Joinee = {
	"role" : "participant", 
	"room_id" : "RoomID"
};

JSONObject StreamInfo = {
	"audio" : true, 
	"room_id" : false
};

enxRoom.joinBreakOutRoom(Joinee, StreamInfo);

public void onConnectedBreakoutRoom(JSONObject roomMetadata)  {
	// roomMetadata contains meta information of the Room 
} 

public void onFailedJoinBreakOutRoom(JSONObject jsonObject) {
	// data contains reasons of failed connection
}

public void onUserJoinedBreakoutRoom(JSONObject jsonObject) {
	// jsonObject contains new joinee user's information 
	/*
	{	"clientId": "String",
		"room": "String";
	}
	*/
}

Pause/Resume Parent Room

User may pause the Parent Room after joining the Break-Out Room. Pausing mutes audio and video of Parent Room. On the other hand, user may need to join back or resume session with Parent Room. For explicit pause and resume Parent Rooms Session by using given methods below. Further a user automatically joins back the Parent Room after getting disconnected from the Beak-Out Room.

Method: 

  • public void pause() – To pause Parent Room
  • public void resume() – To resume Parent Room

Callbacks:

  • onAckPause – Acknowledges the user on pausing Parent Room
  • onAckResume – Acknowledges the user on resume with Parent Room
enxRoom.pause();	// Pause Parent Room
enxRoom.resume();	// Resume Parent Room

public void onAckPause(JSONObject jsonObject) {
	// jsonObject carries info related to pausing
	/*
	{	"msg": "Room muted",
		"result": 0
	}
	*/
};

public void onAckResume(JSONObject jsonObject) {
	// jsonObject carries info related to resume
	/*
	{	"msg": "Room unmuted",
		"result": 0
	}
	*/
};

Mute/Unmute Parent Room

User may like to mute audio and/or video of the Parent Room after joining the Break-Out Room. On the other hand, user may need to unmute audio and/or video of Parent Room after disconnecting from Break-Out Room and resuming with Parent Room.

Method: 

  • public void muteRoom(JSONObject muteInfo) – To mute audio/video of Parent Room
  • public void unmuteRoom(JSONObject unmuteInfo) – To unmute audio/video of Parent Room

Parameters:

  • mutetInfo – JSON object to define Audio/Video Mute on the Parent Room.
    • audio – Boolean. Set true mute Audio.
    • video – Boolean. Set true to mute Video.
  • unuteteInfo – JSON Object to define Audio/Video Unmute on the Parent Room.
    • audio – Boolean. Set true unmute Audio.
    • video – Boolean. Set true to unmute Video.

Callbacks:

  • onAckMuteRoom– To acknowledge Room muted
  • onAckUnmuteRoom – To acknowledge Room unmuted
JSONObject MuteInfo = {
	"audio" : true, 
	"video" : true
};

JSONObject UnmuteInfo = {
	"audio" : true, 
	"video" : true
};

enxRoom muteRoom(MuteInfo);
enxRoom unmuteRoom(UnmuteInfo);

public void onAckMuteRoom(JSONObject jsonObject) {
	// jsonObject contains muting status
} 

public void onAckUnmuteRoom(JSONObject jsonObject) {
	// jsonObject contains unmuting status
}

Disconnect from Break-Out Room

User may need to disconnect from Break-Out Room to join back or resume with Parent Room. Use the following method:

Method: public void disconnect()

Callbacks:

  • onDisconnectedBreakoutRoom – The disconnected user is notified that he has successfully disconnected from the Break-Out Room.
  • onUserDisconnectedFromBreakoutRoom – All Users of the Parent Room are notified about the user got disconnected from Break-Out Room.
enxRoom.disconnect(); 

public void onDisconnectedBreakoutRoom(JSONObject jsonObject) {
	// jsonObject carries info related to disconnection
	/*
	{	"moderatorId": "String",
		"msg": "Breakout Room disconnected",
		"result": 0
	}
	*/
};

public void onUserDisconnectedFromBreakoutRoom(JSONObject jsonObject) {
	// jsonObject carries info related to disconnected user
	/*
	{	"clientId": "String",
		"name": "String",
		"room": "breakout-Development"
	}
	*/
};

Handle Destroyed Break-Out Room

When all connected user in a Break-Out Room get disconnected, the Break-Out Room is destroyed automatically and he creator/owner or the Room is notified by a Callback.:

Callbacks:

  • onDestroyedBreakoutRoom – The owner is notified when Room gets destroyed. 
public void onDestroyedBreakoutRoom(JSONObject jsonObject) {
	// jsonObject carries destroyed room infomration 
	/* 
	{	"room_id": "String"
	}
	*/
}

Detect Local Audio and Noise Energy

To detect local Audio Speech and Noise energy therein, set the setVadObserver Observer and add the Callbacks to be notified.

Class: EnxRoom

Observer:

public void setVadObserver(EnxVadObserver enxVadObserver)

Callbacks: 

  • public void onSpeechDetected(JSONObject jsonObject) – To detect Local Audio Energy
  • public void onNoiseDetected(JSONObject jsonObject) – To detect Local Noise Energy

Enable Proximity Sensor

EnxProximitySensor manages functions related to the “Proximity Sensor”. On most device, the Proximity Sensor is implemented as a boolean-sensor.

  • It returns just two values NEAR or FAR.
  • Thresholding is done on the LUX value i.e. the LUX value of the light Sensor is compared with a threshold.
  • A LUX-value more than the threshold means the Proximity Sensor returns FAR.
  • Anything less than the threshold value, the Sensor returns NEAR

Class: EnxRoom

Method: public void enableProximitySensor(boolean status)

Parameters: status – Boolean. true to enable and false to disable Proximity Sensor.

Make Outbound PSTN/SIP Call

Being within EnableX Session, you may initiate an Outbound Call to PSTN Number or SIP URI inviting the called participant to join the session on accepting the call.

Method: public void makeOutboundCall(String dialout_number,String cli_number)

Parameters:

  • dialout_number – String. It either a PSTN Number or SIP URI to dial-out
  • cli_number – Calling Line Identification Number to be added as originator of the Call. In case of PSTN Phone Numbers, this will be validated against your purchased number or opted Shared Number. In case if the CLI does not match, the call will fail with an error “CLI mismatch”

Callback: onDialStateEvents -Status of the Dialout Process is notified as and when received from Gateway. The JSON Response returns following status codes: initiated, calling, connecting, connected, terminated

room.makeOutbound('00999999999', '00999999999');

Public void onDialStateEvents(JSONObject jsonobject){
	// evnt JSON contains status of dial-out process, example
	/*
	{	number: "9999999999",	/* Dialed Phone Number of SIP URI */
		status: "connected", 	/* Status of dialout Process */
		description: "Detailed description"
	} 

	status may be initiated, calling, connecting, 
	connected & terminated
	*/     
}

Error Codes – Failure Conditions to accept Dial-Out request

Error CodeDescription
1141Dial-Out request is already in progress
1142CLI doesn’t match with configured phone number

Share Log with EnableX to audit

To share Console Log with EnableX Tech Team for auditing purpose, use EnxRoom.postClientLogs() . The method sends latest 200KB of Console Log to EnableX.

Class: EnxRoom

Method: public void postClientLogs() – to share log. No parameter needed

Before you can share Console Log, you need to enable Console logging.

Class: EnxUtilityManager

Method: public void enableLogs(boolean) – Use true to enable, false to disable logging as parameter

EnxUtilityManager  enxUtilityManager  = EnxUtilityManager.getInstance(current-class-instance);
enxUtilityManager.enableLogs(true); // To enable logging

room.postClientLogs(); // To upload Log to Enablex

// Notified after uploading log
public void onLogUploaded(JsonObject json) {
 // json { "result":0, "msg":"Success" }
}

Explore Android SDK