In-Session Communication

The Android SDK provides the following methods for obtaining information about the in-session communication:

• sendMessage(): To enable session participants to exchange messages.
• sendUserData(): To send customized data adhering to a structure which is not bound by the EnableX message structure.
• sendFiles(): To initiate a file transfer to the EnableX server.
• getAvailableFiles(): Get a list of files available for download.
• downloadFile(): To start the file downloading process.
• cancelUpload(): To cancel an ongoing file upload job.
• cancelAllUploads(): To cancel all ongoing file upload jobs.
• cancelDownload(): To cancel the ongoing file download job.
• cancelAllDownloads(): To cancel all ongoing file download jobs.
• startScreenShare(): To create a screen sharing stream @ 6fps to publish in a room.
• stopScreenShare(): To stop the ongoing screen-sharing.
• stopAllSharing(): To force stop an ongoing screen sharing by other users in a room.
• startCanvas(): To start canvas streaming.
• stopCanvas(): To stop canvas streaming.
• stopAllSharing(): To force stop ongoing canvas streaming.
• startAnnotation(): To start annotation on a given stream object.
• stopAnnotation(): To stop annotation.
• startLiveTranscription(): To start live transcription.
• startLiveTranscriptionForRoom(): To start live transcription.
• stopLiveTranscription(): To stop live transcription.

Chat

The EnxRoom.sendMessage() method exchanges 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 multiple users.

The messaging feature does not require the sender of a message to publish the local streams or the receiver of the message to subscribe to a remote stream.

Class: EnxRoom

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

Parameters

Callback: onMessageReceived: User receives a message in JSONObject.

Sample Code

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

Custom Signalling

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 to a session. It allows your application to send not just messages but also structured instructions, polls, or any data requiring a customized data structure as per your business requirement.

Class: EnxRoom

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

Parameters

Callback: onUserDataReceived: Receives signalling in a JSON object. Available from Android SDK v1.5.3 and later.

Sample Code

• Sample of data JSON object:

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

Sample Code: To send and receive custom signalling

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

File Sharing

Note: This functionality available from the Android SDK v1.5.3+ version

The following APIs allow users in an RTC session to send and receive files with each other. User can also initiate a file transfer, cancel a file transfer, be notified of the availability of a file for download, and receive and download a shared file.

Upload a File for Sharing

The EnxRoom.sendFiles() method initiates a file transfer to the EnableX Server.

Class: EnxRoom

Observer: public void setFileShareObserver(EnxFileShareObserver-Object)

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

Parameters:

Callbacks at Sender's End

Callbacks at Receiver's End

Sample Code

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
}

Download a Shared File

The process of downloading a shared files consists of the following two steps:

• Know files available for download
• Initiate a File Download

Know Files Available for Download

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

Class: EnxRoom

Method: public String getLocalStreamID()

Sample Code

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.

Sample Code

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

Initiate a File Download

The EnxRoom.downloadFile() method initiates the file download when the information about the downloadable file is available.

Class: EnxRoom

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

Parameters

Callbacks at Receiver's End

Sample Code

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 a File Upload

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

Class: EnxRoom

Method: public void cancelUpload(int upJobId)

Parameter: upJobId: Numeric. The Id of the file upload process.

Sample Code

enxRoom.cancelUpload(jobId);

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

Class: EnxRoom

Method: public void cancelAllUploads()

Sample Code

enxRoom.cancelAllUploads();

Callback:

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

Sample Code

public void onFileUploadCancelled(JSONObject jsonObject)

Error Codes and Exceptions

Cancel a File Download

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

Class: EnxRoom

Method: public void cancelDownload(int upJobId)

Parameter: upJobId: Numeric. The Id of the file download process.

Sample Code

enxRoom.cancelDownload(jobID);

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

Method: public void cancelAllDownloads()

Sample Code

enxRoom.cancelAllDownloads();

Callback: onFileDownloadCancelled: Acknowledgment to the user when the file downloading is canceled.

Sample Code

public void onFileDownloadCancelled(JSONObject jsonObject);

Error Codes and Exceptions

Screen Sharing

To support screen sharing in a room, you need to enable it while creating the room by setting: { "screen_share": true; } in the JSON Payload. To receive shared screens, subscribe to the screen share Stream ID# 101 and play it on the video player.

Note: On Android 11 (API level 30) or later, you must create a foreground service and access the camera or microphone in the foreground service. Declare the camera or microphone foreground service types as attributes of your <service> component. For more information, click here.

Start Screen Sharing

The EnxRoom.startScreenShare() method creates a screen sharing stream @ 6fps to publish in a video room. Screen sharing continues even when the application runs in the background.

Class: EnxRoom

Observer: public void setScreenShareObserver(EnxScreenShareObserver-Object)

Method: public String getLocalStreamID()

Callback: onScreenSharedStarted: Notification to everyone in a room when screen sharing starts.

Sample Code

// 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 stops the ongoing screen sharing.

Class: EnxRoom

Method: public void stopScreenShare()

Callback: onScreenSharedStopped: Notification to everyone in a room when screen-sharing stops.

Sample Code

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

Force Stop a Participant's Screen Sharing

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

A moderator can force stop an ongoing screen sharing by a participant in the room. This is implemented using the EnxRoom.stopAllSharing() method.

Note: This feature is only for moderators and cannot be used by the participants.

This method also force stop the ongoing canvas streaming.

Class: EnxRoom

Observer: ACK CallBack

Method: public void stopAllSharing()

Callback: onStopAllSharingACK: Notification to everyone in a room when screen sharing stops.

Sample Code

EnxRoom.stopAllSharing()     // Force Stop the Shared Screen


// Notification to all when share stops
public void onStopAllSharingACK(JSONObject jsonObject) {
	// Code here... to handle your UI
}

Implement a Foreground Service

The implementation part is quite similar to that of a service. The following steps are involved in the implementation:

1. Create a foreground service.
2. Add permissions in the manifest file.
3. Register the foreground service in the manifest file.

Create a Foreground Service

public class ForegroundService extends Service {
public static final String CHANNEL_ID = "ForegroundServiceChannel";
int NOTIFICATION_ID = 121412;
public NotificationManager notificationManager;
@Override
public void onCreate() {
super.onCreate();
}

@Override
public int onStartCommand(Intent intent, int flags, int startId) {
if (intent != null) {
if (intent.getAction().equals("ACTION_START")) {
showOnGoingCall();
}else {
stopForegroundService();
}
}
return START_NOT_STICKY;
}
@Override
public void onDestroy() {
super.onDestroy();
}
@Nullable
@Override
public IBinder onBind(Intent intent) {
return null;
}
private void showOnGoingCall() {
String app_Name = getResources().getString(R.string.app_name);
Intent notificationIntent = new Intent(this, VideoConferenceActivity.class);
notificationIntent.addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP);
PendingIntent pendingIntent = PendingIntent.getActivity(this, 0, notificationIntent, 0);
String CHANNEL_ID = getResources().getString(R.string.app_name);
Notification notification;
if (Build.VERSION.SDK_INT >= 26) {
NotificationChannel channel = new NotificationChannel(CHANNEL_ID, "Sync Service", NotificationManager.IMPORTANCE_HIGH);
channel.setDescription("Service Name");
notificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
notificationManager.createNotificationChannel(channel);


notification = new NotificationCompat.Builder(this, CHANNEL_ID)
.setContentTitle(app_Name)
.setCategory(Notification.CATEGORY_SERVICE)
.setContentText("Ongoing call")
.setOngoing(true)
.setSmallIcon(R.mipmap.ic_launcher_round)
.setContentIntent(pendingIntent)
.build();
} else {
notification = new Notification.Builder(this)
.setContentTitle("Project Name")
.setOngoing(true)
.setContentText("Ongoing call")
.setSmallIcon(R.drawable.ic_launcher)
.setContentIntent(pendingIntent).build();
notificationManager =
(NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
}
startForeground(NOTIFICATION_ID, notification);
}
private void stopForegroundService() {
stopForeground(true);
stopSelf();
}
}

Add Permissions in the Manifest File

We need to request foreground service permission for Android 9 (API level 28) or higher. We need to specify the permission below in our manifest file:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

Register the Foreground Service in the Manifest File

<service    android:name=".activity.ForegroundService"    android:enabled="true"    android:foregroundServiceType="mediaProjection"    android:exported="true" />Call Foreground Service in VideoConferenceActivity public void startService() {        Intent serviceIntent = new Intent(VideoConferenceActivity.this, ForegroundService.class);        serviceIntent.setAction("ACTION_START");//        serviceIntent.putExtra("inputExtra", "Foreground Service Example in Android");        ContextCompat.startForegroundService(VideoConferenceActivity.this, serviceIntent);    }    public void stopService() {        Intent serviceIntent = new Intent(VideoConferenceActivity.this, ForegroundService.class);        serviceIntent.setAction("ACTION_STOP");        stopService(serviceIntent);//        ContextCompat.startForegroundService(getActivity(), serviceIntent);    } stopService() call in onDestroy method and startService() call in onStart method

Canvas Streaming

Canvas Streaming allows you to publish any view into a room. To support canvas streaming in a room, you need to enable canvas during the 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 Method: public void startCanvas(View view)

Parameter: View: String. The View to be used for canvas streaming.

Callbacks

Sample Code

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

Stop Canvas Streaming

The EnxRoom.stopCanvas() method is used to stop canvas streaming.

Class: EnxRoom

Observer: ACK CallBack

Method: public void stopCanvas()

Callbacks

Sample Code

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 and 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, subscribe to the canvas Stream ID# 102. Once subscribed, you can play it like any other video stream using a video player.

Sample Code

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

Force Stop Canvas Streaming

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

A moderator can force stop an ongoing canvas streaming by a participant in a room. This is implemented using the EnxRoom.stopAllSharing() method.

Note This feature is only for moderators and cannot be used by the participants.

This method also force stops an ongoing screen sharing.

Class: EnxRoom

Observer: ACK CallBack

Method: public void stopAllSharing()

Callback: onStopAllSharingACK: Notification to everyone in the room when screen sharing stops.

Sample Code

EnxRoom.stopAllSharing()     // Force Stop Canvas Streaming


// Notification to all when Canvas Streaming stops
public void onStopAllSharingACK(JSONObject jsonObject);

Annotation

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

The Annotation feature allows you to annotate on a remote stream. To support annotation, enable canvas streaming during Room Creation by setting: { canvas: true; } in the JSON payload. To implement annotation, you need to add annotation toolbar.

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.

Note: To initiate annotation, you need to set setAnnotationObserver after connecting to a room.

Class: EnxRoom

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

Method: public void startAnnotation(EnxStream)

Parameter: EnxStream: Object. Stream Object to be annotated.

Callbacks

Sample Code

// 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 annotation.

Class: EnxRoom Method: public void stopAnnotation()

Callbacks

Sample Code

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

Live Transcription

EnableX supports live transcription of video sessions. All endpoints requesting live transcription start receiving Speech-to-Text content of all actively talking users in a video room through a notification event. Live transcription is helpful when participants have limited language proficiency or difficulty hearing because of a noisy background.

Live transcription converts the speech of all active talkers in a video room to text, and the converted text can be shared with each user who has subscribed to receive it. The transcription process starts when the first user requests it and continues until the last user opts out. The text content is generated through a single transcription process and broadcasted to each user who has requested for it.

Service Subscription

Live transcription is a subscription-based service. For subscription details, contact the Sales or Account Manager.

Live Transcription Settings in a Room

Live transcription is automatically enabled in all rooms if live transcription subscription is enabled. However, you can disable it for certain rooms or configure its settings to meet your requirements using the room-level settings.

For more information, see:

Create a video room Get post session transcription file

Sample Code: JSON payload of room definition with live transcription settings

{
  "name": "HLS Trial",
  "owner_ref": "XOXO",
  "settings": {
    "description": "HLS Trial",
    "mode": "group",
    "scheduled": false,
    "adhoc": false,
    "duration": 30,
    "moderators": "1",
    "participants": "2",
    "audiences": 6,
    "auto_recording": false,
    "quality": "SD",
    "live_transcription": {
        "language": "english_us",
        "auto_transcribe": true,
        "enable": true
    }

  }
}

Note: If live transcription is not subscribed, then room definition with the related settings is not permitted.

Methods and Notifications

In addition to the auto-start settings of live transcription, it can be started or stopped using SDK method calls.

When the SDK method is called to start live transcription, the method initiates it and subscribes for the feed to receive. If the transcription process is already started in the room, it subscribes to it. So, any new user can subsequently execute the command to start it and only subscribe to it.

On the other hand, when the stop command is executed, the user unsubscribes from the feed and does not receive the transcribed content after that point. When the last subscribed user stops the subscription, the transcription process stops in the room.

Note: If live transcription is automatically started at the room level, it is not stopped when the last user stops. It is only stopped at the end of the session.

Start a Live Transcription

To start live transcription, call the following SDK method from an endpoint. When the method executes first, it starts the live transcription process in the video room. It also subscribes to the endpoint to receive the text-to-speech content. Subsequently, the same method call from other endpoints only subscribes to receive the text-to-speech content.

When only one endpoint starts the process and receives the transcription, it is called the self-transcription process. On subsequent requests, it gets promoted to room-level transcription.

Methods

• public void startLiveTranscription(String language)
• public void startLiveTranscriptionForRoom(String language)

Parameter: language: The default value is english_us. Use one of the string given in a list of language codes . Its the language that you want the Speech Recognition Engine to recognize for you.

Event Notifications

Sample Code

// Start Transcription
enxRoom.startLiveTranscription("english_us");
emxRoom.startLiveTranscriptionForRoom("english_us");

public void onACKStartLiveTranscription(JSONObject jsonObject) {
	// Acknowledgement for Start Request.
}

public void onRoomTranscriptionOn(JSONObject jsonObject) {
	// Room-Level transcription is turned on
}

public void onSelfTranscriptionOn(JSONObject jsonObject) {
	// Self transcription is turned on
}

public void onTranscriptionEvents(JSONObject jsonObject) {
	// Speech Recognised/Recognising with Text Contents
}

Error Codes

Stop Live Transcription

The following method call unsubscribes an endpoint from receiving the live transcription content. The transcription process ends in a video room when all the endpoints request to stop receiving the content.

However, if the auto-transcribe option is enabled at the room level, the transcription process does not stop and continues till the end of the session.

Method: public void stopLiveTranscription()

Event Notifications:

Sample Code

// Stop Transcription
enxRoom.stopLiveTranscription();

public void onACKStopLiveTranscription(JSONObject jsonObject) {
	// Acknowledgement for Stop Request.
}

public void onRoomTranscriptionOff(JSONObject jsonObject) {
	// Room-Level transcription is turned off
}

public void onSelfTranscriptionOff(JSONObject jsonObject) {
	// Self transcription is turned off
}

Error Codes