Advance Features of Android SDK cover API capabilities to build feature-rich Client endpoint Applications. For exclusive APIs entitled to the Moderator refer to Moderator Controls.

Table of Contents

Pre-Call Test (WebRTC Diagnostic API)

Availability: Android SDK v1.9.6+

The EnxRtc.clientDiagnostics() method acts as a Diagnostic Tool to detect any issue causing the RTC to fail. The API runs through predefined test cases related to WebRTC issues and reports asynchronously through an Event as it passes through each test. These test cases are organized in “Test Groups” as shown below:

  • Microphone
    • Audio capture.
  • Camera
    • Check resolution 320×240.
    • Check resolution 640×480.
    • Check resolution 1280×720.
    • Check supported resolutions.
  • Network
    • UDP enabled with TURN server.
    • TCP enabled with TURN server.
    • IPv6 enabled with TURN server.
    • UDP enabled with STUN server.
    • TCP enabled with STUN server.
    • IPv6 enabled with STUN server.
  • Connectivity
    • Relay connectivity with TURN server.
    • Reflexive connectivity with TURN server.
    • Host connectivity with TURN server.
    • Reflexive connectivity with STUN server.
    • Host connectivity with STUN server.
  • Throughput
    • Data throughput with TURN server.
  • Bandwidth
    • Video bandwidth with TURN server.
    • Audio bandwidth with TURN Server.
  • Signaling
    • Signaling connectivity with TURN server.

You can also build a UI to initiate the tests and generate a diagnostic report using this API.

Class: EnxRtc

Observer: public void setEnxTroubleShooterObserver(EnxTroubleShooterObserver-Object)

Method: public void clientDiagnostics(JSONObject Options)

Parameters:

  • Options – JSON object with Client preferences for the execution of Test cases. JSON Keys are explained below:
    • testNames: Array of Test Group names. e.g. [ "microphone", "camera", "network", "connectivity", "throughput", "bandwidth", "signalling"]
      • To test only selected Test Groups, add selected Test Group names e.g., ["microphone", "camera"].
      • To test all the Test Groups, use ["all"].
    • audioDeviceId: Optional. Device Id of input audio device.
    • videoDeviceId: Optional. Device Id of input video device.
    • regionId: Optional. Array of region Ids of ICE Servers, e.g. ["IN", "SG", "US", "DE"]. Get Region-ID list from Portal
    • testDurationDataThroughput: Optional. Test duration of data throughput in seconds. [Range: 1-30 sec. Default: 2 sec]
    • testDurationVideoBandwidth: Optional. Test duration of video bandwidth in seconds. [Range: 1-30 sec. Default: 10 sec]
    • testDurationAudioBandwidth: Optional. Test duration of audio bandwidth in seconds. [Range: 1-30 sec. Default: 10 sec]
    • stop: Optional. Boolean. Set to true to stop the test cases which are already in execution.

Callbacks:

  • onClientDiagnosisFailed – Notification of Diagnosis failure when API is called with the wrong parameter or a repeated attempt to call the API is made while the previous request is under process.
  • onClientDiagnosisStopped – Notification sent when the API execution is stopped explicitly through Method Call.
  • onClientDiagnosisFinished – Notification sent when the API completes execution of all the test cases. This returns a JSON Object with a complete test result of all the test cases.
  • onClientDiagnosisStatus – Notification sent with the test result of each test case as the API passes through the execution of each test till the completion or till stopped explicitly. This returns a JSON Object with test results.

Request for diagnostics:

Options = {
     testNames: ['microphone', 'camera'],
     audioDeviceId: 'XXX',
     videoDeviceId: 'XXX',
     regionId: ['IN'],
     testDurationDataThroughput: 2,
     testDurationVideoBandwidth: 30,
     testDurationAudioBandwidth: 30,
     stop: false
};

enxRtc.clientDiagnostics(Options);	// Execute Test


// Test Execution finished
public void onClientDiagnosisStatus(JSONObject jsonObject) {
	// Handle JSON from jsonObject.
	// It contains complete test result. A response example given later
});

// Test Execution has failed
public void onClientDiagnosisFailed(String msg) {
	// Handle error message from msg
	// Response example:
	/* 
	- Invalid argument.
	- Diagnosis is already in progress. Few resources are in use and may not be accessible.
	*/
});

// Test Execution has stopped
public void onClientDiagnosisStopped(String msg) {
	// Handle info message from msg
	// Response example:
	/* 
	- Diagnosis stopped.
	- Diagnosis not running.
	*/
});

// Intermediate Test Result of each  Test Case 
public void onClientDiagnosisFinished(JSONObject jsonObject) {
	// Handle JSON in jsonObject
	// It contains complete test result. A response example given later
});

Response at the beginning of the Test: onClientDiagnosisStatus

{
  "test_group": "microphone",
  "test_case": "audio_capture",
  "status": "started",
  "output": ""
}

Intermediate Response after finishing a test case: onClientDiagnosisStatus

{
"test_group": "microphone",
"test_case": "audio_capture",
"status": "finished",
"output": {
"audio_capture": {
"result": "success",
"execution_time": "241 ms",
"success": [
{
"message": "Audio track created using device=Default - Microphone Array (Synaptics Audio)"
},
{
"message": "Active audio input channels: 2"
}
],
"error": [],
"warning": [],
"info": [
{
"message": "Channel 0 levels: -38.3 dB (peak), -48.4 dB (RMS)"
},
{
"message": "Channel 1 levels: -38.3 dB (peak), -48.4 dB (RMS)"
},
{
"message": "Stereo microphone detected."
}
]
}
}
}

Final Response after completion of all the test cases: onClientDiagnosisFinished

{
"microphone": {
"audio_capture": {
"result": "success",
"execution_time": "241 ms",
"success": [
{
"message": "Audio track created using device=Default - Microphone Array (Synaptics Audio)"
},
{
"message": "Active audio input channels: 2"
}
],
"error": [],
"warning": []
}
},
"network": {
"udp_enabled": {
"IN": {
"TURN": {
"result": "success",
"execution_time": "241 ms",
"success": [
{
"message": "Gathered candidate of Type: relay Protocol: udp Address: 104.211.155.197"
}
],
"error": [],
"warning": [],
"server": {
"region": "IN",
"url": "turns:ts.enablex.io:443"
}
}
}
},
"tcp_enabled": {
"IN": {
"TURN": {
"result": "success",
"execution_time": "241 ms",
"success": [
{
"message": "Gathered candidate of Type: relay Protocol: udp Address: 104.211.155.197"
}
],
"error": [],
"warning": [],
"server": {
"region": "IN",
"url": "turns:ts.enablex.io:443"
}
}
}
}
}
}

Test Results Explained:

Test GroupTest CaseServerResultMessage
MicrophoneAudio CaptureN/ASuccessAudio track created using device #device#
SuccessActive audio input channels #channel#
FailureWebAudio run failure:
FailureNo audio track in returned stream
FailureNo active input channels detected
FailureNo active input channels detected. Microphone is most likely muted or broken, please check if muted in the sound settings or physically on the device. Then re-run the test.
FailureMicrophone input level is low, increase input volume or move closer to the microphone.
FailuregetUserMedia failed with error #error#
Cameracheck resolution 240N/ASuccessCaptured video using expected resolution
SuccessAverage FPS above threshold
FailuregetUserMedia failed with error #error#
FailureNo video track in returned stream
FailureVideo track ended, camera stopped working
FailureLow average sent FPS
FailureIncorrect captured resolution
FailureCould not analyze any video frame
FailureCamera delivering lots of black frames
FailureCamera delivering lots of frozen frames
Cameracheck resolution 480SuccessCaptured video using expected resolution
SuccessAverage FPS above threshold
FailuregetUserMedia failed with error #error#
FailureNo video track in returned stream
FailureVideo track ended, camera stopped working
FailureLow average sent FPS
FailureIncorrect captured resolution
FailureCould not analyze any video frame
FailureCamera delivering lots of black frames
FailureCamera delivering lots of frozen frames
Cameracheck resolution 720SuccessCaptured video using expected resolution
SuccessAverage FPS above threshold
FailuregetUserMedia failed with error #error#
FailureNo video track in returned stream
FailureVideo track ended, camera stopped working
FailureLow average sent FPS
FaiiureIncorrect captured resolution
FailureCould not analyze any video frame
FailureCamera delivering lots of black frames
FailureCamera delivering lots of frozen frames
Cameracheck supported resolutionsN/ASuccessSuccess Supported resolution #resolution#
FailureNo video track in returned stream
FailureVideo track ended, camera stopped working
Networkudp enabledTURNSuccessSupported resolution #resolution#
FailureNo video track in returned stream
FailureVideo track ended, camera stopped working
Networkudp enabledSTUNSuccessGathered candidate of Type: relay Protocol: udp Address: #IP#
FailureFailed to gather specified candidates
FailureFailed to create peer connection: #<error#
Networktcp enabledTURNSucessGathered candidate of Type: relay Protocol: udp Address: #IP#
FailureFailed to gather specified candidates
FailureFailed to create peer connection: #<error#
Networktcp enabledSTUNSuccessGathered candidate of Type: relay Protocol: udp Address: #IP#
FailureFailed to gather specified candidates
FailureFailed to create peer connection: #<error#
Networkipv6 enabledTURNSuccessGathered candidate of Type: relay Protocol: udp Address: #IP#
FailureFailed to gather IPv6 candidates, it might not be setup/supported on the network
FailureFailed to gather IPv6 candidates, it might not be setup/supported on the network
Networkipv6 enabledSTUNSuccessGathered candidate of Type: relay Protocol: udp Address: #IP#
FailureFailed to gather IPv6 candidates, it might not be setup/supported on the network
FailureFailed to gather IPv6 candidates, it might not be setup/supported on the network
Connectivityrelay connectivityTURNSuccessData successfully transmitted between peers
FailureInvalid data transmitted
FailureTime out
Connectivityrelay connectivitySTUNSuccessData successfully transmitted between peers
FailureInvalid data transmitted
FailureTime out
Connectivityreflexive connectivityTURNSuccessData successfully transmitted between peers
FailureInvalid data transmitted
FailureTime out
Connectivityreflexive connectivitySTUNSuccessData successfully transmitted between peers
FailureInvalid data transmitted
FailureTime out
Connectivityhost connectivityTURNSuccessData successfully transmitted between peers
FailureInvalid data transmitted
FailureTime out
Connectivityhost connectivitySTUNSuccessData successfully transmitted between peers
FailureInvalid data transmitted
FailureTime out
ThroughputData ThroughputTURNSuccessTotal transmitted: #n# kilo-bits in #t# seconds
FailureTimed out
BandwidthVideo BandwidthTURNSuccessVideo resolution: #Width# x #Height#
FailureCamera failure: #Width# x #Height#. Cannot test bandwidth without a working camera
FailuregetUserMedia failed with error #error#
FailureFrame rate mean is 0, cannot test bandwidth without a working camera
FailureCould not gather stats
FailureOnly Firefox and Chrome getStats implementations are supported
BandwidthAudio BandwidthTURNSubject to qualityAverage Audio bandwidth <value>
Subject to qualityPackets lost: <value>
Subject to qualityRTT Average: <value>
FailuregetUserMedia() failed with error <error>
FailureOnly Firefox and Chrome getStats() implementations are supported
SignalingSignaling ConnectivitySuccessToken created successfully
FailureToken creation failed due to error: #error#
FailureRoom not joined due to error: #error#
SuccessRoom joined successfully

Get Bitrate Status of Client

Android SDK v1.9.8+

The EnxRtc.clientBitrate() method provides bitrate status of the Client. It carries out the following tests to generate a response:

  • Bandwidth
    • Video bandwidth with TURN server
    • Audio bandwidth with TURN Server

You can also build a UI to initiate the tests and generate a diagnostic report using this API.

Class: EnxRtc

Observer: public void setEnxClientBitrateObserver( EnxClientBitrateObserver-Object )

Method: public void clientBitrate(JSONObject clientInfo)

Parameters:

  • ClientInfo – Optional. JSON object with Client preferences for the execution of test cases
    • region: String. Region Id of ICE Server, e.g. "IN", "SG", "US", "DE". Default Region ID is “DE”

Callbacks:

  • onClientBitrateFinished – Notification sent when the API has completed the execution of the test case. This returns a JSON Object as the final result.
  • onClientBitrateStatus – Notification sent with the test results at the beginning and end of the test. This returns a JSON Object as the test result.
  • onClientBitrateFailed – Notification sent when the test fails.

Request for diagnostics:

setEnxClientBitrateObserver( EnxClientBitrateObserver-Object );

 var clientInfo = {
     region: 'IN'
};

EnxRtc.clientBitrate(clientInfo);
 
// Called when test fails
public void onClientBitrateStatus(JSONObject jsonObject) {
	// JSON brings in error information
}

// Called when test starts and ends
public void onClientBitrateStatus (JSONObject jsonObject) {
	//  JSON structure explained later in the document
}

// Called when test finishes
public void onClientBitrateFinished(JSONObject jsonObject) {
	//  JSON structure explained later in the document
}

Response at the beginning and end of Test: onClientBitrateStatus

//Status at the start of test 
{
  "status": "started",
  "test_case": "video_bandwidth",
  "test_group": "bandwidth",
  "test_region": "IN",
  "test_server": "TURN"
}

// Status at the end of test
{
  "test_group": "bandwidth",
  "test_case": "video_bandwidth",
  "status": "finished",
  "output": {
    "video_bandwidth": {
      "result": "success",
      "bandwidth_bps": 2221949,
      "packets_lost_percentage": "0.99",
      "execution_time": "31566 ms",
      "success": [],
      "error": [],
      "warning": [],
      "info": [],
      "server": {
        "region": "IN",
        "url": "turns:ts.enablex.io:443"
      }
    }
  },
  "test_region": "IN",
  "test_server": "TURN"
}

Final Response: onClientBitrateFinished

{
  "video": {
    "bitrate_bps": 2221949,
    "connection": "stable"
  },
  "audio": {
    "bitrate_bps": 278067,
    "connection": "stable"
  }
}

Test Result Explanation:

Test GroupTest CaseServerResultMessage
BandwidthVideo BandwidthTURNSuccessVideo resolution: Width x Height
FailureCamera failure: Width x Height. Cannot test bandwidth without a working camera
Subject to qualityAverage Video bandwidth <value>
Subject to qualityPackets lost: <value>
Subject to qualityRTT Average: <value>
FailuregetUserMedia() failed with error <error>
FailureFrame Rate mean is 0, cannot test bandwidth without a working camera
FailureOnly Firefox and Chrome getStats() implementations are supported
Audio BandwidthTURNSubject to qualityAverage Audio bandwidth <value>
Subject to qualityPackets lost: <value>
Subject to qualityRTT Average: <value>
FailuregetUserMedia() failed with error <error>
FailureOnly Firefox and Chrome getStats() implementations are supported

Note: Currently this API is not working for Firefox and safari browser.

Switch Source Media Devices of Published Stream

The following APIs allow you to switch to alternate Media Devices after having published Stream, thus facilitating a switch on the fly.

Switch between Rear & Front Camera

The EnxStream.switchCamera() method allows you to switch between Rear and Front Camera as a source for the published Stream.

Class: EnxStream

Method: public void switchCamera() – No parameter required.

localStream.switchCamera();

Error Codes / Exceptions

CodeDescription
5021Unable to switch Camera in Audio-only call mode.
5097Unable to switch Camera in a Chat-Only Room. Non-Contextual Method Call.

Switch to alternate Microphone

The EnxRoom.switchMediaDevice() method is used to switch the Audio source of the published Stream to an alternate Microphone. This method requires ID of the Audio device to switch to, which needs to be retrieved using EnxRoom.getDevices() method.

Class: EnxRoom

Method: public void switchMediaDevice(String micDeviceId)

Parameters: micDeviceId – String. Target Microphone Device ID.

Observer: onNotifyDeviceUpdate – Acknowledgment sent with the new Audio Device ID after Audio Device update is complete.

room.switchMediaDevice( micDeviceId );

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

Update Stream Configuration

Availability: Android SDK v.1.5.6+

The EnxStream.updateConfiguration() method is used to reconfigure a Stream by adding new or updating existing attributes of the Stream. This API is applicable to both Remote and Local Streams.

ClassEnxStream

Methodpublic void updateConfiguration(JSONObject streamOpt)

ParametersstreamOpt– New Stream configuration options JSON Object.

  localStream.updateConfiguration(JSONObject streamOpt); 

// The streamOpt JSON Object example:

streamOpt = {
     "maxVideoBW": "900",
     "minVideoBW": "150",
     "maxAudioBW": "150",
     "minAudioBW": "150"
 };

Error Codes / Exceptions

CodeDescription
5113Invalid JSON Object passed as parameter.
5114Unable to update Stream when Canvas Streaming is on. Non-Contextual Method Call.

Mute / Unmute Audio in a Stream

The EnxStream.muteSelfAudio() method is used to mute/unmute Audio of the Local Stream.

Class: EnxStream

Methods: public void muteSelfAudio( isMute )

Parameter: isMutetrue to mute and false to unmute Audio.

Callbacks:

  • onRemoteStreamAudioMute – Notification to everyone in the Room when a user mutes self Audio.
  • onRemoteStreamAudioUnMute – Notification to everyone in the Room when a user unmutes self Audio.
  • onAudioEvent – Acknowledgment to the user when self Audio is muted/unmuted.
localStream.muteSelfAudio(true); // To mute audio of local stream
localStream.muteSelfAudio(true); // To unmute audio of 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" }   
} 

Error Codes / Exceptions

CodeDescription
5058Repeated muteSelfAudio() call made while a previous mute request is in process.
5059Repeated muteSelfAudio() call made while a previous unmute request is in process.
5060Repeated muteSelfAudio() call made after Audio has been muted already.
5061Trying to unmute Audio without muting it first.
5062Unable to unmute Audio as Audio hard-muted by the Moderator.

Mute / Unmute Video in a Stream

The EnxStream.muteSelfVideo() method is used to mute/unmute Video of the Local Stream.

Class: EnxStream

Methods: public void muteSelfVideo( isMute )

Parameter: isMutetrue to mute, false to unmute Video.

Callbacks:

  • onRemoteStreamVideoMute – Notification to everyone in the Room when a user mutes self Video.
  • onRemoteStreamVideoUnMute – Notification to everyone in the Room when a user unmutes self Video.
  • onVideoEvent – Acknowledgment to the user when self Video is muted/unmuted.
localStream.muteSelfVideo(true); // To mute video of local stream
localStream.muteSelfVideo(false); // To unmute video of 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" }   
} 

Error Codes / Exceptions

CodeDescription
5020Unable to process muteSelfVideo() when the user has denied Camera permission.
5071Repeated muteSelfVideo() call made while a previous request is in process.
5063Repeated muteSelfVideo() call made after Video has been muted already.
5064Repeated muteSelfVideo() call made after Video has been unmuted already.
5065When the user tries to unmute Video without muting it first. Non-Contextual Method call.
5066Unable to unmute Video as Video hard-muted by the Moderator.
5070Unable to unmute Video in Audio-only call mode.

Private, Public & Group Messaging

The EnxRoom.sendMessage() method is used to exchange messages between Session participants. It allows you to exchange the following types of messages:

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

The Messaging feature does not require the sender to publish Local Stream or the receiver to subscribe to Remote Stream.

Class: EnxRoom

Method: public void sendMessage(String message, boolean isBroadcast, array recipientIDs)

Parameters:

  • message – String Message.
  • isBroadcast – Boolean. Set to true for Public Messaging, false for Private Messaging.
  • recipientIDs – Array of Client IDs to receive messages. Applicable for Group and Private Messaging.

Callback:

  • onMessageReceived – Receives message in JSONObject.
String message = "XXX";
List<String> Recipient_ClientIds;

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

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


// 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+

The following APIs allow users in an RTC session to send and receive file(s) with each other. Using these APIs, you can initiate a file transfer, cancel a file transfer, be notified of the availability of a file for download, and receive/download a shared file.

Upload File to share

The EnxRoom.sendFiles() method is used to initiate a file transfer to EnableX Server.

Class: EnxRoom

Observer: public void setFileShareObserver(EnxFileShareObserver-Object)

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

Parameters:

  • view– FrameLayout view where UI is shown to choose files to upload.
  • isBroadcast – Boolean. Set it to true to share file(s) with all the participants in the Session and false to share file(s) with the intended user(s).
  • clientIdList – List of Client IDs intended to receive the file(s). This parameter is not applicable if isBroadcast parameter is set to true.

Callbacks at Sender’s End:

  • onInitFileUpload – Notification to the sender when the file upload process is initiated.
  • onFileUploaded – Notification to the sender when the file has been uploaded.
  • onFileUploadFailed – Notification to the sender when the file upload process fails.

Callbacks at Receiver’s End:

  • onFileUploadStarted – Notification to the intended receiver when a file is being uploaded.
  • onFileAvailable – Notification to the intended receiver when 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
}

Cancel File Upload

The EnxRoom.cancelUpload() method allows you to cancel an ongoing file upload job initiated by you.

Class: EnxRoom

Method: public void cancelUpload(int upJobId)

Parameter:

upJobId – Numeric. The Id of the file upload job.

enxRoom.cancelUpload(jobId);

The EnxRoom.cancelAllUploads() method allows you to cancel all ongoing file uploads initiated by you.

Method: public void cancelAllUploads() – No Parameter required.

enxRoom.cancelAllUploads();

Callback:

onFileUploadCancelled – Acknowledgment to the user when the file upload is canceled.

public void onFileUploadCancelled(JSONObject jsonObject)

Error Codes / Exceptions:

CodeDescription
5089Storage Access denied.
5090Failed to save file.
5091File-Sharing not available in this context.
5092Too many files to upload. Max 1 file allowed per request.
1185File size exceeds the max allowed size.
1182Failed to upload file.
5098Unable to cancel file upload after file upload complete.
5099Failed to cancel upload as invalid Upload ID passed as a parameter.
5100Failed to upload a possibly corrupt file.
5102Cancel upload not available without Web View. Non-Contextual Method Call.

Download shared File

The process of downloading shared file(s) comprises two steps:

  • Know file(s) available for download.
  • Initiate download on the available file(s).

Know files available for download

The EnxRoom.getAvailableFiles() method returns a JSON Object with all the files available for download.

Class: EnxRoom

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

Callback onFileAvailable: The intended receiver is notified when a file is available for download.

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

Initiate File Download

The EnxRoom.downloadFile() method is used to initiate the file download using the file information received above.

Class: EnxRoom

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

Parameters:

  • fileInfo– File JSON Object available for download.
  • isAutoSave – Boolean. Set it to true to save the file automatically in which case you receive the saved file’s path. When set to false, you receive Base64 encoded RAW data to handle the file saving process manually.

Callbacks at Receiver’s End:

  • onFileDownloaded – Notification sent when the file has been downloaded with or without auto-saving.
  • onFileDownloadFailed – Notification sent when download fails.
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
}

Cancel File Download

The EnxRoom.cancelDownload() allows you to cancel the ongoing file download job taking place at your endpoint.

Class: EnxRoom

Method: public void cancelDownload(int upJobId)

Parameter:

upJobId – Numeric. The Id of the file download job.

enxRoom.cancelDownload(jobID);

The EnxRoom.cancelAllDownloads() method allows you to cancel all ongoing file downloads taking place at your endpoint.

Method: public void cancelAllDownloads() – No Parameter required.

enxRoom.cancelAllDownloads();

Callback:

onFileDownloadCancelled – Acknowledgment to the user when the file download is canceled.

public void onFileDownloadCancelled(JSONObject jsonObject);

Error Codes / Exceptions:

CodeDescription
5089Storage Access denied.
5090Failed to save file.
1183Failed to download file.
1181File Download not available. Non-contextual Method Call.
5101File already downloaded.

Share Screen

To support Screen-Sharing in the Room, you need to enable Screen-Sharing during Room Creation by setting: { "screen_share": true; }) in the JSON Payload. To receive Shared Screen, you need to subscribe to the Screen-Share Stream ID# 101 and play it on the Video Player.

Start Screen Sharing

The EnxRoom.startScreenShare() method is used to create a Screen-Sharing Stream @ 6fps to publish in the Room. Screen Sharing continues even when the Application runs in the background.

Class: EnxRoom

Observer: public void setScreenShareObserver(EnxScreenShareObserver-Object)

Method: public void startScreenShare()

Callbacks:

onScreenSharedStarted – Notification to everyone in the Room when Screen-Sharing starts.

// Initiate Screen Share Observer to receive Callbacks
room.setScreenShareObserver(this);

// Start Screen Share
room.startScreenShare();	

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

Stop Screen Sharing

The EnxRoom.stopScreenShare() method is used to stop the ongoing Screen-Sharing.

Class: EnxRoom

Method: public void stopScreenShare()

Callbacks:

onScreenSharedStarted – Notification to everyone in the Room when Screen-Sharing stops.

room.stopScreenShare(); // Stop Screen Share

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

Error Codes / Exceptions:

CodeDescription
5107Repeated startScreenShare() call made while previous request is in process.
1170Screen-Sharing not supported in your subscription.

Canvas Streaming

Canvas Streaming allows you to publish any view into the Room. To support Canvas Streaming in the Room, you need to enable canvas during Room Creation by setting: { canvas: true; }} in the JSON Payload.

Start Canvas Streaming

The EnxRoom.startCanvas() method is used to start canvas streaming.

Class: EnxRoom

Methodpublic void startCanvas(View view)

Parameter:

View: The View to be used for Canvas Streaming.

Callbacks:

  • onStartCanvasAck – Acknowledgment to the publisher when Canvas Streaming starts.
  • onCanvasStarted – Notification to everyone in the Room when Canvas Streaming starts.
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);
} 

Error Codes / Exceptions

CodeDescription
5105Repeated startCanvas() call when Canvas Streaming is already active.
5107Repeated startCanvas() call when a previous request is in process.
5103Canvas Streaming or Screen Share already active in the Room.
5110Failed to publish Canvas Stream.

Stop Canvas Streaming

The EnxRoom.stopCanvas() method is used to stop Canvas Streaming.

Class: EnxRoom

Methodpublic void stopCanvas()

Callbacks

  • onStoppedCanvasAck – Acknowledgment to the publisher when Canvas Streaming stops.
  • onCanvasStopped– Notification to everyone in the Room when Canvas Streaming stops.
room.stopCanvas(); 

// Publisher receives acknowledgement that Canvas Streaming stopped.
public void onStoppedCanvasAck(JSONObject jsonObject) {
       // Handle JSON Object   
}

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

Receive & Play Canvas Streams

A Client application developed using Android SDK cannot initiate HTML5 Canvas Streaming. However, it can receive Canvas Streaming initiated by a Client application developed using Web SDK that runs on Web Browsers.

To receive Canvas Streaming, you need to subscribe to the Canvas Stream ID# 102. Once subscribed, you can play it like any other Video Stream using a Video Player.

// 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+

The Annotation feature allows you to annotate on a Remote Stream. To support Annotations, you need to enable Canvas Streaming during Room Creation by setting: { canvas: true; }} in the JSON payload. To implement Annotation, you need to add Annotation Toolbar before you can start Annotations.

Add Annotation Toolbar

Initiate Annotation Toolbar using the following code in XML:

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

Start Annotation

The EnxRoom.startAnnotation() method is used to start Annotation on a given Stream object. To initiate Annotation, you need to setAnnotationObserver after getting connected to the room.

ClassEnxRoom

Observerpublic void setAnnotationObserver(Annotations-Observer-Instance)

Method: public void startAnnotation(EnxStream) 

Parameter: 

EnxStream – Stream Object to be annotated.

Callbacks:

  • public void onStartAnnotationAck(JSONObject) – Acknowledgment to the Annotator when Annotation starts.
  • public void onAnnotationStarted(EnxStream) – Notification to everyone in the Room when Annotation starts.
// Set Observer
room.setAnnotationObserver(Annotations-Observer-Instance);

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

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

Stop Annotation

The EnxRoom.stopAnnotation() method is used to stop Annotations.

Class: EnxRoom

Method: public void stopAnnotation()

Callbacks:

  • public void onStoppedAnnotationAck(JSONObject) – Acknowledgment to the Annotator when Annotation stops.
  • public void onAnnotationStopped(EnxStream) – Notification to everyone in the Room when Annotation stops.
// Stop Annotation
room.stopAnnotation(); 

// 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 / Exceptions: 

CodeDescription
5093Annotation Access denied.
5104Repeated startAnnotation() call made while Annotations already active in the Room.
5106Repeated startAnnotation() call made while a previous request is in process.
5108Invalid Stream passed to startAnnotation().
5109Failed to publish Annotation Stream.
5112Annotation support available in Landscape Mode only.
5094Repeated stopAnnotation() call made while a previous request is in process.

Change to Audio-only call

The EnxRoom.setAudioOnlyMode() method allows you to switch to an audio-only call where you can neither receive anybody’s video nor publish your video. You can use this method as a toggle to switch between audio-only and audio-video call. This doesn’t affect others video Streams in the Room.

Class: EnxRoom

Method: publish void setAudioOnlyMode( boolean AudioOnly)

Parameter:

AudioOnly – Boolean. Set to true to switch to audio-only call and false to switch to audio-video call.

room.setAudioOnlyMode(true);   // Switch to Audio-Only call
room.setAudioOnlyMode(false);  // Switch back to Audio-Video call

Error Codes / Exceptions

CodeError Description
5051Repeated setAudioOnlyMode() call made while a previous Audio-only request is in process.
5052Repeated setAudioOnlyMode() call made while Audio-Only mode already active.
5053Repeated setAudioOnlyMode() call made while Audio-Video mode already active.
5054Repeated setAudioOnlyMode() call made while a previous Audio-Video request is in process.

Enable Streaming Statistics in the Room

The EnxRoom.enableStats() method allows you to receive Statistics for all the Streams being received in the Room. The statistics help you analyze the streaming quality of all the Streams by providing information about the Streams such as:

  • Publishing Resolution
  • Bandwidth at Publisher’s end
  • Receiving Resolution
  • Receiving Bandwidth consumed
  • Available Bandwidth at Receiver’s end

ClassEnxRoom

Method: public void enableStats(isEnabled, EnxStatsObserver)

Parameters:

  • isEnabled – Boolean. Set to true to enable stats and false to disable them.
  • EnxStatsObserver – EnxStatsObserver instance

Callbacks:

  • onAcknowledgeStats – Acknowledgment to the user when stream stats are enabled or disabled.
  • onReceivedStats – Notification to the user 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());
} 

Receive Stream Statistics for Individual Streams

The EnxPlayerView.enablePlayerStats() method allows you to individually receive statistics of Streams being played on the player. Please note, to receive individual stream stats, you also need to enable stats at room level using EnxRoom.enableStats() method.

ClassEnxPlayerView

Method: public void enablePlayerStats( isEnabled, EnxPlayerStatsObserver)

Parameters:

  • isEnabled – Boolean. Set to true to enable stats and false to disable.
  • EnxPlayerStatsObserver – EnxPlayerStatsObserver instance.

Callback:

onPlayerStats – Notification to the user when player’s stream stats is received.

playerview.enablePlayerStats(true, this);

@Override
public void onPlayerStats(JSONObject jsonObject) {
	
}

Error Codes / Exceptions:

CodeDescription
5075Repeated Stream Stats Subscription request as a previous request is in process.
5076Repeated Stream Stats Unsubscription request as a previous request is in process.
5077Repeated Stream Stats request while Stream stats is already subscribed.
5078Unsubscribing Stream Stats is not permitted without subscribing to it.
5079Unable to unsubscribe to Stream Stats while Subscription request is in process.
5080Stream Stats Unsubscription request is in process.

Be Notified of the Talkers in the Room

Android SDK v1.9.5+

The subscribeForTalkerNotification() method allows you to receive notification for the talkers in the Room or the participants acting as a source of the noise. You can utilize this method for UI display or for debugging. Note that the list of talkers received could be longer than the Active Talkers list, because Active Talkers list received with onActiveTalkersUpdated callback is limited to the max_active_talkers setting of the Room.

ClassEnxRoom

Observer: public void setEnxTalkerNotificationObserver(Talker-Observer-Instance)

Method: public void subscribeForTalkerNotification(Boolean isEnabled, EnxTalkerNotificationObserver e)

Parameters:

  • isEnabled: Boolean. Set to true to subscribe to Talker Notification and false to unsubscribe.
  • EnxTalkerNotificationObserver

Callbacks:

  • onAckSubscribeTalkerNotification – Acknowledgment to the subscriber when Talker Notification subscribed successfully.
  • onAckUnsubscribeTalkerNotification – Acknowledgment to the subscriber when Talker Notification unsubscribed successfully.
  • onTalkerNotification – Notification to the subscriber received with JSON Object carrying the details of users from whom speech or sound is detected.
room.subscribeForTalkerNotification(true, this); // To subscribe
room.subscribeForTalkerNotification(false, this); // To unsubscribe

// Acknowledgement on Talker Subscription
public void onAckSubscribeTalkerNotification(JSONObject jsonObject) {
	// JSON Object example
	/* 
	{	"result": { 
			"result": 0, 
			"msg": "Success"
		},
		"id": "talker-notification”
	}
	*/
}

// Acknowledgement on Talker Unsubscription
public void onAckUnsubscribeTalkerNotification(JSONObject jsonObject) {
	// JSON Object example
	/* 
	{	"result": { 
			"result": 0, 
			"msg": "Success"
		},
		"id": "talker-notification”
	}
	*/
}

// Receive Talker Notification on Subscription
public void onTalkerNotification(JSONObject jsonObject) {
	// JSON Object example given later in the document
}

onTalkerNotification JSON Payload:

  • data: An array of objects. Each object consists of an array of users who are talking and an array of users who are merely a source of noise.
    • speech: It contains users, an array of client information who are talking with their clientId and speechType (Intensity) as low, media high
    • noise: An array of clientIds producing noise.
{
  "type": "talker-notification",
  "message": [
    {
      "speech": true,
      "users": [
        {
          "speechType": "high"
          "clientId": "xxxxx"
        },
        {
          "speechType": "medium"
	  "clientId": "yyyyy"
        },
        {
          "speechType": "low"
	  "clientId": "zzz"
        }
      ]
    },
    {
      "noise": true,
      "users": [
        {
          "clientId": "sssss"
        },
        {
          "clientId": "uuuuu"
        }
      ]
    }
  ]
}

Error Codes / Exceptions:

CodeDescription
5128Repeated subscription request call while a previous request is in process.
5129Repeated unsubscription request call while a previous request is in process.
5130Talker Notification already subscribed.
5131Illegible attempt to unsubscribe Talker Notification without subscribing first.

Handle Audio Device Updates

The notification on any addition or modification in the Audio Devices such as earphones or headphones connected to the Mobile device is provided through the following Callbacks:

Callbacks:

  • onNotifyDeviceUpdate – Acknowledgment to the user when a switch to alternate media devices is made at run-time.
  • onDeviceAdded – Notification to the user when a new Audio Device is connected.
  • onDeviceRemoved – Notification to the user when an Audio Device is 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

The following methods are used to switch the RTC application to the background and vice versa. The methods allow you to configure whether to continue streaming or pause after the switch.

Moving Application to Background

Class: EnxRoom

Method: public void stopVideoTracksOnApplicationBackground( localMuteState, remoteMuteState )

Parameters:

  • localMuteState – Boolean. Set to false to pause Local Video Stream and true to continue publishing on switching the application to the background.
  • remoteMuteState – Boolean. Set to false to pause Remote Video Stream, true to continue receiving on switching the application to the background.
// When application goes to Background
boolean localMuteState = true;
boolean remoteMuteState = true;

room.stopVideoTracksOnApplicationBackground( localMuteState, remoteMuteState );

Moving Application to Foreground

Class: EnxRoom

Method: public void startVideoTracksOnApplicationForeground( localUnmuteState, remoteUnmuteState )

Parameters:

  • localUnmuteState – Boolean. Set to true to resume publishing Local Video Stream if stopped while switching the application to the background.
  • remoteUnmuteState – Boolean. Set to true to resume receiving Remote Video Streams if stopped while switching the application to the background.
// When application comes back to Foreground 
boolean localUnmuteState = false;
boolean remoteUnmuteState = false;

room.startVideoTracksOnApplicationForeground(localUnmuteState, remoteUnmuteState);  

Note: To use Audio device after moving the application to background, the application must have Android foreground service otherwise the application would be unable to capture Audio input.

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

Receive desired 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 UI with enumerated values that allow the user to choose the desired video quality to be received.

Class: EnxRoom

Method: public void setReceiveVideoQuality(JSONObject Quality)

Parameters:

  • Quality – Video Quality JSON Object with the following keys:
    • videoQuality: Enumerated Values (Auto, HD, SD, LD). Set to Auto to allow EnableX to choose the optimum quality dynamically based on the available bandwidth.
    • streamType: Enumerated Values (talker, canvas)
JSONObject Quality = {
	"videoQuality": "HD", 
	"streamType":  "talker"
	};

room.setReceiveVideoQuality( Quality );

Error Codes / Exceptions

CodeDescription
5057Stream already set with the desired Quality.

Quality Adjustment based on available Bandwidth

EnableX offers Automatic Bandwidth Detection (ABWD) to ensure optimum Audio/ Video Communication based on the available bandwidth at the Client endpoint. The ABWD detects a change in the available bandwidth when it cannot continue to support all the Videos being received and notifies the Client endpoint with Callback onRoomBandwidthAlert. You can handle this event by choosing to reduce the number of Active Talker’s Videos being received or by switching to audio-only mode.

This helps users facing extremely poor network conditions to go into audio-only mode without disrupting the session.

Callback: onRoomBandwidthAlert

  • Notification is sent to the affected Client endpoint when:
    • Bandwidth at the endpoint reduces to a level where all Videos being received cannot be supported.
    • Bandwidth at the endpoint increases to a level where more Videos than those currently being received can be supported.
  • Notification is not triggered for any bandwidth fluctuation that does not affect the number of Videos being received at the Client endpoint.
// To receive callback
-public void onRoomBandwidthAlert(JSONObject jsonObject) {
	// jsonObject examplel given below
}

onRoomBandwidthAlert JSON Payload:

  • bandwidth – Updated (Reduced or Increased) Bandwidth at the Client endpoint.
  • number_of_videos – Number of Videos that can be supported at the available bandwidth.
[
	{ 	"bandwidth": 240,
		"stream_bandwidth": 80,
		"number_of_videos": 2
	}
]

Use Custom Signaling

The EnxRoom.sendUserData() method allows you to send customized data adhering to a structure not bound by EnableX message structure, to one or more users connected in a session. This allows your application to send not just messages but also structured instructions, polls, or any data that requires a customized data structure as per your business requirement.

Class: EnxRoom

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

Parameters:

  • data – JSON Object containing custom keys. This object is passed to the Recipients without any structure enforcement. Be advised to define keys effectively for signaling needs.
  • isBroadcast – Boolean. Set to true for Public Broadcast and false for signaling to one or more recipients.
  • RecipientIDs – Array of Client IDs of recipients of the message when not broadcasting.

Callback

  • onUserDataReceived – Receives signaling in JSONObject. Available from Android SDK v1.5.3 onwards.

data JSONObject Sample:

// Example: You can put Important Information 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 receive Signaling Message through Callback
// Available from v1.5.3.
Public void onUserDataReceived(JSONObject jsonobject){
    // Handle JSON Object
} 

Error Codes / Exceptions

CodeDescription
5127Exceeding maximum allowed data transfer rate of 100Kb.

Break-Out Room

Break-Out Rooms allow users to participate in a discussion outside of the main Video Room i.e. the Parent Room.

The process of breaking-out takes place in the following manner:

  • A creator or owner of the Break-Out Room invites one or more users from the Parent Room to the Break-Out Room.
  • The invited users get notified about the request and need to accept the request to join the Break-Out room.
  • Users moving out of the Parent Room are treated as “paused” users in the Parent Room until they return.

The implementation of Break-Out Room must be carried out with the following considerations:

  • Break-Out room can be created by a user from the Parent Room only.
  • A user cannot create another Break-Out Room while being within a Break-Out Room.
  • A Break-Out Room can be created with a limit to the maximum allowed participants in it. In any case, the maximum allowed participants in the Break-Out Room must be less than the maximum Active Talkers in the Parent Room.
  • Break-Out room currently supports only Audio Call with Screen Share and Canvas Streaming support.

Create Break-Out Room

The EnxRoom.createBreakOutRoom() method is used to create a Break-Out Room.

Class: EnxRoom

Method: public void createBreakOutRoom(JSONObject RoomDefinition);

Parameters:

  • RoomDefinition – Required. JSON Object with Room definition parameters defined as following keys:
    • participants – Numeric. Required. Total number of Participants in the Break-Out Room. 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. (This is currently 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-Sharing in Break-Out Room.
    • max_rooms – Numeric. Required. The total number of Break-Out rooms to be created.

Callbacks:

  • onAckCreateBreakOutRoom – Acknowledgment to the creator with Break-Out Room returned as a JSON object when created.

Response Body:

{	msg: {​​
		rooms: [ 
			  xxx, xxx
		       ]
	     },
			result: 0
}
  • onBreakoutRoomCreated – Notification to all the Moderators in the Parent Room when a Break-Out Room is created.

Response Body:

{ 
    id = "breakout-room-created"; 
    msg =     { 
        clientId = "68d0388c-5630-4f16-883a-8bc2a138a905"; 
        roomId = 61249702a7282c251ec8d840;
    }; 
}, 
JSONObject  RoomDefinition = {
	"participants" :2, 
	"audio" : true,
	"video": false , 
	"canvas": false, 
	"share": false, 
	"max_rooms": 1
};
// Create Break-Out Room
enxRoom.createBreakOutRoom(RoomDefinition);

// Acknowledgment to the creator
public void onAckCreateBreakOutRoom(JSONObject jsonObject) {
	// jsonObject is JSON with created Break-Out Room Information
	
}

// Notification to all the Moderators
public void onBreakoutRoomCreated(JSONObject jsonObject); 

Error Codes / Exceptions

CodeDescription
5067Break-Out Room not supported in a Room in lecture-mode.

Invite Users to join a Break-Out Room

The EnxRoom.inviteToBreakOutRoom() method allows the Creator/Owner of a Break-Out Room to invite one or more users from the Parent Room to join the Break-Out Room. This method must be invoked from the Parent Room and NOT from the Break-Out Room.

Class: EnxRoom

Method: public void inviteToBreakOutRoom(JSONObject invitee)

Parameters:

  • invitee – JSON Object with invitation details.
    • clients – Array of Client IDs of users to be invited.
    • room_id – String. Room ID of the Break-Out Room to which the users are being invited

Callbacks:

  • onAckInviteBreakOutRoom – Acknowledgment to the Creator with JSON object returned as a response to the invitation process.

Response Body:

{	
      "msg": "Success",
      "result": 0,
}
  • onInvitationForBreakoutRoom – Notification to the invited users when they are invited to join a Break-Out Room.

Response Body:

{	
     "result": 0,
}
  • onBreakoutRoomInvited – Notification to all the Moderators in the Parent Room when a user is invited to a Break-Out Room.

Response Body:

{ 

    id = "breakout-room-invited"; 
    msg =     { 
                   clientId = "12f31157-e62a-43f6-8719-f98b3da40978"; 
                   roomId = 6124b82e98533871c791a788; 
              }; 
}
JSONObject invitee = {
	"clients" : [ clientId1, clientId2], 
	"room_id" : "RoomID"
};

// Invite user to Break-Out Room.
enxRoom.inviteToBreakOutRoom(invitee);
 
// Acknowledgment to the Creator
public void onAckInviteBreakOutRoom(JSONObject jsonObject) {
	// jsonObject is the result of invitation process, e.g.
} 

// Notification to the invited users
public void onInvitationForBreakoutRoom(JSONObject jsonObject) {
	// jsonObject carries the invitation details, e.g.
}

// Notification to the Moderator(s)
public void onBreakoutRoomInvited(JSONObject jsonObject); {
}

Create Break-Out Room & Auto-Invite Users

The EnxRoom.createAndInviteBreakoutRoom() is used to support certain use-cases where auto-assignment of users into different Break-Out Rooms is required. This method creates a Break-Out Room with given specifications and invites users to join a Break-Out Room randomly depending on the Room’s capacity.

Class: EnxRoom

Method: public void createAndInviteBreakoutRoom (JSONObject roomDefinition)

Parameters:

Callbacks:

  • onAckCreateAndInviteBreakOutRoom – Acknowledgment to the creator with the result of invitation in a 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
		|
	
	*/
}

Error Codes / Exceptions

CodeDescription
5067Break-Out Room not supported in a Room in lecture mode.

Join a Break-Out Room

The EnxRoom.joinBreakOutRoom() method allows users to join a Break-Out room on being invited by the creator. A user can join a Break-Out Room from the Parent Room only and can join only one Break-Out Room at a time, thus allowing the user to join another Break-Out Room only after rejoining the Parent Room first.

Class: EnxRoom

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

Parameters:

  • Joinee – JSON Object with details required to join the Break-Out Room.
    • role – String. Required. Enumerated Values: participant, moderator.
    • room_id – String. Required. Room-ID of the Break-Out Room being joined.
  • streamInfo – JSON Object with Stream information while joining the Break-Out Room.
    • audio – Boolean. Set to true to join with Audio.
    • video – Boolean. Set to true to join with Video. This is currently not supported.

Callbacks:

  • onConnectedBreakoutRoom – Acknowledgment to the Joiner when Break-Out Room joined successfully.
  • onFailedJoinBreakOutRoom – Notification to the Joiner when fails to join the Break-Out Room.
  • onUserJoinedBreakoutRoom: – Notification to everyone in the Break-Out Room when a new user joins the Room.
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 for failed connection
}

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

Reject Break-Out Room Invitation

The EnxRoom.rejectBreakOutRoom() allows the invited user to reject the invitation to join a Break-Out Room.

Class: EnxRoom

Method: public void rejectBreakOutRoom(String roomId) 

Parameter:

roomId – The Break-Out Room identifier to which the user is invited.

Callbacks:

  • onAckRejectBreakOutRoom – Acknowledgment to the user who rejected the invitation when the request to reject is successfully processed.

Response Body:

{ 
         “result” : 0/1,   // 0 for success and 1 for failure 
         “msg” : “success/failure” 
} 
  • onBreakoutRoomInviteRejected – Notification to all the Moderators in the Parent Room when a user rejects an invitation to a Break-Out Room.
// User rejects break-out room invitation.
EnxRoom. rejectBreakOutRoom(" roomId”); 

// Acknowledgment to the user when invitation rejected.
public void onAckRejectBreakOutRoom(JSONObject jsonObject); 

// Notification to the Moderators in the Parent Room when invitation rejected.
public void onBreakoutRoomInviteRejected(JSONObject jsonObject); 

Pause / Resume Parent Room

The EnxRoom.pause() method allows the user to pause the Parent Room after joining the Break-Out Room.

The EnxRoom.resume() method is used to resume the Parent Room if it was paused while joining the Break-Out Room.

Method: 

  • public void pause()
  • public void resume()

Callbacks:

  • onAckPause – Acknowledgment to the user when the Parent Room is paused.
  • onAckResume – Acknowledgment to the user when the Parent Room is resumed.
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

The EnxRoom.muteRoom() method allows the user to mute Audio and/or Video of the Parent Room after joining the Break-Out Room.

The EnxRoom.unmuteRoom() is used to unmute Audio and/or Video of the Parent Room after disconnecting from Break-Out Room and resuming the Parent Room.

Class: EnxRoom

Methods: 

  • public void muteRoom(JSONObject muteInfo)
  • public void unmuteRoom(JSONObject unmuteInfo)

Parameters:

  • muteInfo – JSON object with options to mute Audio and Video separately.
    • audio – Boolean. Set to true to mute Audio.
    • video – Boolean. Set to true to mute Video.
  • unmuteInfo – JSON Object with options to unmute Audio and Video separately.
    • audio – Boolean. Set to true unmute Audio.
    • video – Boolean. Set to true to unmute Video.

Callbacks:

  • onAckMuteRoom – Acknowledgment to the user when the Parent Room is muted.
  • onAckUnmuteRoom – Acknowledgment to the user when the Parent Room is 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

The EnxRoom.disconnect() method allows the user to disconnect from the Break-Out Room.

Class: EnxRoom

Method: public void disconnect()

Callbacks:

  • onDisconnectedBreakoutRoom – Acknowledgment to the user when successfully disconnected from the Break-Out Room.
  • onUserDisconnectedFromBreakoutRoom – Notification to everyone in the Break-Out Room when a user gets disconnected from the 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 the users in a Break-Out Room get disconnected, the Break-Out Room is automatically destroyed and the creator of the Room is notified with the following Callback.:

Callback:

  • onDestroyedBreakoutRoom – Notification to the owner when Break-Out Room gets destroyed.
public void onDestroyedBreakoutRoom(JSONObject jsonObject) {
	// JSON Object carries destroyed room information 
	/* 
	{	"room_id": "String"
	}
	*/
}

Detect Local Audio and Noise Energy

To detect Local Audio speech and noise, set the setVadObserver Observer and add the Callbacks to receive notifications.

Class: EnxRoom

Observer:

public void setVadObserver(EnxVadObserver enxVadObserver)

Callbacks: 

  • public void onSpeechDetected(JSONObject jsonObject) – Notification to the user when speech is detected at their endpoint.
  • public void onNoiseDetected(JSONObject jsonObject) – Notification to the user when noise is detected at their endpoint.

Enable Proximity Sensor

The EnxRoom.enableProximitySensor() enables the Camera to detect the proximity. On most devices, 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. Set to true to enable and false to disable Proximity Sensor.

Make Outbound PSTN/SIP Call

The EnxRoom.makeOutboundCall() method allows you to initiate an Outbound Call to PSTN Number or SIP URI while being in the session, thus inviting the called participant to join the session on accepting the call.

Class: EnxRoom

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

Parameters:

  • dialout_number – String. It can be either a PSTN Number or a SIP URI to dial out.
  • cli_number – Calling Line Identification Number to be added as the originator of the Call. In the 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 -Notification to the call initiator about the status of the dial-out process as received from Gateway. The JSON Response returns status codes as: initiated, calling, connecting, connected, and terminated.
  • didDTMFCollected – Notification when DTMF input is collected. It gets the String of digits collected.
room.makeOutbound('00999999999', '00999999999');

Public void onDialStateEvents(JSONObject jsonobject){
	// event JSON contains status of dial-out process 
	/*
	{	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
	*/     
} 

Public void onDTMFCollected(String DTMFInput){
	// DTMFINput - A String of digits collected through DTMF
} 

Error Codes / Exceptions:

CodeDescription
1141Dial out request already in process.
1142CLI doesn’t match with the configured phone number.
5095Invalid phone number.

Share Log with EnableX to audit

The EnxRoom.postClientLogs() method is used to share Console Log with EnableX Tech Team for audit. The method sends 200KB of the most recent Console Log to EnableX. To start posting Console Logs to EnableX, you need to first enable Console logging using the EnxUtilityManager.enableLogs() method.

1. Enable Console Log

Class: EnxUtilityManager

Method: public void enableLogs(boolean isEnable)

Parameter:

isEnable – Boolean. Set to true to enable logging and false to disable.

2. Share Console Log

Class: EnxRoom

Method: public void postClientLogs() – No parameter required.

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" }
}

Error Codes / Exceptions

CodeDescription
5056Log File upload already in process.
5083Unable to upload an empty log file.

Explore Android SDK