Utilities

The Android SDK provides the following methods for managing different aspects of video sessions:

• adjustLayout(): To adjust the video player layout to fit within its parent view.
• clientBitrate(): To provide a bitrate status of the client.
• makeOutboundCall(): To initiate an outbound call to a PSTN number or a SIP URI while being in a session.
• makeOutboundCalls(): To initiate an outbound call to a PSTN numbers (maximum 5 numbers).
• cancelOutboundCall(): To cancel an ongoing outbound call to a PSTN number or SIP URI.
• setAudioOnlyMode(): To switch to an audio-only call.
• clientDiagnostics(): To detect any issue causing the RTC to fail.
• updateConfiguration(): To reconfigure a stream by adding new or updating existing attributes of the stream.
• stopVideoTracksOnApplicationBackground(): To switch the RTC application to the background.
• startVideoTracksOnApplicationForeground(): To switch the RTC application to the foreground.
• enableProximitySensor(): To detect the proximity.
• captureScreenShot(): To take snapshot of a video stream in your application.
• enableLogs(): To enable console logging.
• postClientLogs(): To share console log with EnableX tech team for audit.

Adjust Layout

You can play the remote streams in the Active Talker list with a custom-defined view by selecting activeviews : view during connect(). You do not need to handle the UI in this case, as the predefined video grid plays all the streams received at the client endpoint. When choosing this option, you can use the adjustLayout() method to adjust the video player layout to fit within its parent view. This method helps when a user rotates the screen or when the view needs to be adjusted to fit correctly.

Class: EnxRoom

Method: public void adjustLayout(int frameWidth, int frameHeight)

Sample Code

enxRoom.adjustLayout(width,height)

Bitrate Status of Client

This fucntionality is available from Adroid SDK 1.9.8 and later versions.

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

Bandwidth:

• Video bandwidth with the TURN server.
• Audio bandwidth with the TURN Server.

Class: EnxRtc

Observer: public void setEnxClientBitrateObserver( EnxClientBitrateObserver-Object )

Method: public void clientBitrate(JSONObject clientInfo)

Parameter: ClientInfo: Optional. JSON object with Client preferences for the execution of test cases.
ClientInfo.region: String. Region Id of the ICE server. For example, "IN", "SG", "US", "DE"
The default Region ID is "DE".

Callbacks

Sample Code

• 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:

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

Dialing Out to Phone and SIP Endpoint from a Video Room

Dial Out

The EnxRoom.makeOutboundCall() method initiates an outbound call to a PSTN number or SIP URI while in the session, thus inviting the called participant to join the session on accepting the call.

Class: EnxRoom

Methods:

• public void makeOutboundCall(String dialout_number, String cli_number, JSONObject dialOptions): To dial a single phone number.
• public void makeOutboundCalls(List<String> numberList, String cli_number, JSONObject dialOptions): To dial multiple phone numbers (a maximum of 5 phone numbers can be dialed).

Parameters

Note: early_media and silent_join may not be used together.

Callbacks

Note: The <options> parameter is available only in Android SDK 2.1.3 and later versions.

Sample Code

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

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 and Exceptions

Cancel an Outbound Call

This functionality is available only in Android SDK 2.1.3 and later versions.

The EnxRoom.cancelOutboundCall() method allows you to cancel an ongoing outbound call to a PSTN number or SIP URI thus disconnects the participant from the session on passing the number.

Class: EnxRoom

Method: public void cancelOutboundCall(String number)

Parameter: number: String. A PSTN number or a SIP URI to disconnect from the session.

Delegate Method: onOutBoundCallCancel: Notification to the call initiator when the participant gets disconnected.

Sample Code

enxRoom cancelOutboundCall('9999999999');	// Cancel a Call
 
public void onOutBoundCallCancel(JSONObject jsonObject);{
	// Acknowledge that the Call has been cancelled
	{	number: "9999999999",	/* Phone Number of SIP URI */

	} 
}

Send DTMF Response

This functionality is available from iOS SDK v2.3.16+ onwards.

The EnxRoom.sendDTMF() method allows send DTMF response to pass through an IVR if dialed out PSTN Call is connected to IVR. This method can be executed repeatedly to pass single digit or multiple digits in a single call.

An outbound PSTN Call must have been answered first to make use of sendDTMF() method to pass DTMF digits on the same PSTN channel.

• Method: public void sendDTMF(String number, String digits)
• Parameters:
  • options :
    • number : String. It's the same number used with makeOutboundCall() method. It can be either a PSTN Number or a SIP URI to dial out. For Phone Number, use country code without 00 or +.
    • digits : String. Digit(s) to pass on to Voice Service as DTMF digits.
• Callbacks:
  • onOutBoundCallSendDtmf : Method call success and failure notifications are given with error codes.

Sample Code

enxRoom.sendDTMF("919999988888", "1");	// Send DTMF 1

Public void onOutBoundCallSendDtmf(JSONObject jsonobject){
 	// event JSON contains status of sendDTMF 
}

Error Codes

Audio Only Mode for Video Room

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 calls. It does not affect video streams of others in the room.

Class: EnxRoom

Method: publish void setAudioOnlyMode( boolean AudioOnly)

Parameter: AudioOnly: Boolean. Set it to true to switch to an audio-only call.
Set it to false to switch to an audio-video call.

Sample Code

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

Error Codes and Exceptions

Pre-Call Test

This functionality is available only in Android SDK 1.9.6 and later versions.

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:

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

Class: EnxRtc

Observer: public void setEnxTroubleShooterObserver(EnxTroubleShooterObserver-Object)

Method: public void clientDiagnostics(JSONObject Options)

Parameters

Callbacks

Sample Code

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

Updating Stream Configuration

This functionality is available in the Android SDK version 1.5.6 and later.

The EnxStream.updateConfiguration() method is used to reconfigure a stream by adding new or updating existing attributes of the stream. This API applies to both remote and local streams.

Class: EnxStream

Method: public void updateConfiguration(JSONObject streamOpt)

Parameter: streamOpt: JSONObject. New stream configuration options.

Sample Code

localStream.updateConfiguration(JSONObject streamOpt); 

// The streamOpt JSON Object example:

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

Error Codes and Exceptions

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:

Sample Code

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 switch the RTC application to the background and vice versa. The methods allow you to configure whether to continue streaming or pause it after the switch.

Moving Application to Background

The EnxRoom.stopVideoTracksOnApplicationBackground() method switches the RTC application to the background.

Class: EnxRoom

Method: public void stopVideoTracksOnApplicationBackground(localMuteState, remoteMuteState)

Sample Code

// When application goes to Background
boolean localMuteState = true;
boolean remoteMuteState = true;

room.stopVideoTracksOnApplicationBackground( localMuteState, remoteMuteState );

Moving Application to Foreground

The EnxRoom.startVideoTracksOnApplicationForeground() method switches the RTC application to the foreground.

Class: EnxRoom

Method: public void startVideoTracksOnApplicationForeground(localUnmuteState, remoteUnmuteState)

Sample Code

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

room.startVideoTracksOnApplicationForeground(localUnmuteState, remoteUnmuteState);

Note: The application must have android foreground service to use an audio device after moving the application to the background. Otherwise, the application would be unable to capture audio input. For more information, click here.

Detect Local Audio and Noise Energy

To detect local audio speech and noise, set the setVadObserver Observer and add the callbacks to receive notifications.

Observer: public void setVadObserver(EnxVadObserver enxVadObserver)

Callbacks

EnableX Proximity Sensor

The EnxRoom.enableProximitySensor() enables the camera to detect 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 light sensor's LUX value 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)

Parameter: status: Boolean. Set it to true to enable the proximity sensor.
Set it to false to disable the proximity sensor.

Take Image Snapshot of Video Stream

The image from the video stream captures and returns as bitmap image to the callback.

Observer: EnxPlayer.setScreenShotObserver

Method: public void captureScreenShot(EnxScreenShotObserver enxScreenShotObserver)

Callback: OnCapturedView: To receive bitmap image.

Sample Code

//Set observer
enxPlayer.setScreenShotObserver(this)

//Capture Snapshot
enxPlayer.captureScreenShot(this);

//Snapshot captured.
public void OnCapturedView(Bitmap bitmap);
// bitmap is the Bitmap Image

Share Log with EnableX

EnableX Console Log

To start posting console logs, enable console logging with the EnxUtilityManager.enableLogs() method.

Class: EnxUtilityManager

Method: public void enableLogs(boolean isEnable)

Parameter: isEnable: Boolean. Set it to true to enable logging.
Set it to false to disable logging.

Share Console Log

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.

Class: EnxRoom

Method: public void enableLogs(boolean isEnable)

Sample Code

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