In-Session Communication

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

Chat

The EnxRoom.sendMessage() method exchanges messages among session participants. It allows to exchange the following types of messages:

  • Public Messaging: To send messages to all the 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 stream or the receiver of the message to subscribe to a remote stream.

  • Method: EnxRoom.sendMessage(Message, IsBroadcast, RecipientIDs, Callback)
  • Parameters:
    • Message : String. Text message to send.
    • IsBroadcast : Boolean. Set it to true for public messaging and false for private messaging.
    • RecipientIDs : Array. Array of Client IDs to receive messages. This is applicable for group and private messaging.
  • Event Notification:
    • message-received : Receives the event.message JSON object at the recipient endpoint.

Sample Code

// To all participants (public messaging)
room.sendMessage("Text Message", true, [], function(data){
	// Message sent
});


// To selected participants (private messaging)
room.sendMessage("Text Message", false, ["clientId"], function(data){
	// Message sent
});


// To receive the message notification 
room.addEventListener("message-received", function (event) {
     var InMsg = event.message;		// Complete JSON given later.
     if (InMsg.broadcast === true) {
         // Handle Public Message
     }
     else {
         // Handle message from InMsg.sender
     }
 });

Sample JSON: For Incoming Message

{
    "type": "message-received",
    "message": {
        "broadcast": false,
        "sender": "SENDER_NAME",
        "senderId": "XX",
        "type": "chat",
        "message": "TEXT MESSAGE",
        "timestamp": 99999,
        "receipients": [
            "XOXO", "XOXOXO"
        ]
    }
}

Custom Signalling

The EnxRoom.sendUserData() method allows you to send customized data adhering to a structure that is not bound by the 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 per your business requirement.

  • Method: EnxRoom.sendUserData(MessageOpt, IsBroadcast, RecipientIDs, Callback)
  • Parameters:
    • MessageOpt : JSON Object. Contains custom keys defined by you; passed without any change to Recipients. Be advised to define keys effectively for signaling needs.
    • IsBroadcast : Boolean. Set it to true for public broadcast. Set it to false for signaling to one or more recipients.
    • RecipientIDs : Array. Array of Client IDs of recipients of the message when not broadcasting.
  • Event Notifications:
    • user-data-received: Receives signaling in the MessageOpt JSON object as event.message.msg.

Sample Code

// Example: Important information you can add with custom keys.


var MessageOpt = {			   
	"name": "John",			// Custom Key          
	"designation": "CTO",		// Custom Key
	"experience": "15 Years"	// Custom Key
}


// To all (public signalling)
room.sendUserData(MessageOpt, true, [], function(data){
	// Message sent
});


// To selected participants (private signaling)
room.sendUserData(MessageOpt, false, [ClientIds], function(data){
	// Message sent
});


// To receive  custom data/signal notification 
room.addEventListener("user-data-received", function (event) {
     var InMsg = event.message.msg;
     if (InMsg.broadcast === true) {
		// Handle Public Message
     }
     else {
		// Handle message from InMsg.sender
     }
 });

File Sharing

This functionality is available in Web Toolkit 1.5.3 and later versions.

The following APIs allow users in an RTC session to send and receive files with each other. Users 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.

  • Method: EnxRoom.sendFiles(files, options, callback)
  • Parameters
    • files : FileList. An array of File Type Objects. This object is returned by the files property of the HTML INPUT element with type="file" that lets you access the list of files.
    • options : JSON Object. This to define file sharing process, scope of file transfer etc. Following keys may be used:
      • isMobile : Boolean. Default: false. Set to true to develop Web View based Mobile Apps.
      • broadcast : Boolean. Default: true. The value true allows you to share file with all the users in the Session. Set to false to share the file with specific user(s).
      • clientList : Array of Client IDs who are intended to receieve the file(s).If broadcast is set to true, clientList is ignored.
    • callback : Callback function. To receive the status response of sendFiles() method.
  • Event Listeners:
    • fs-upload-result : Notification to the sender about the file upload process such as when the file upload starts, completes, or fails.

Sample Code

var clientList = [];


var shareOptions = {
	"isMobile": false,
	"broadcast": true,
	"clientList": clientList
};


room.sendFiles(FileList,  shareOptions, functions(resp) {
	if (resp.result == "0") { 
		// Success JSON example is given below
	} else {	
		// Error JSON Example given below
	}
});


room.addEventListener('fs-upload-result', function (event) {
	var msg = event.message;
	switch (msg.messageType) {
		case 'upload-started':
			// Note msg.upJobId for management
			// upload-started event JSON example given below
			break;
		case 'upload-completed':
			// Know msg.upJobId is completed
			// upload-completed event JSON example given belowbreak;
			break;
		case 'upload-failed':
			// Know msg.upJobId has failed 
			// upload-failed event JSON example given belowbreak;
			break;
		default:
			break;
	}


});

Sample JSON: Success JSON on sendFiles() Callback

{
	messageType: 'upload-completed', 
	result: 0,
	description: 'upload completed',
	response: {
		uploadStatus: 'completed',
		upJobId: 1,		// #ID of the File Upload Job
		uploadInfo: {		// SDK may provide additional information 
			upJobId: 1,
			name: 'xyz.txt',
			size: 100,	// in bytes
			type: text,	// type of the file
		}	 
	}
}

Sample JSON: Error JSON on sendFiles() callback

{
	"result": 1185,			// A non zero error code
	"error": "file upload failed ", // error
	"desc": "file upload failed because the file list is empty"  
}

Sample JSON: The fs-upload-result event JSON for upload-stated status

{
	"messageType": "upload-started",  
	"result": 0, 
	"description: "upload started",  
	"response": {
		"uploadStatus": "started",
		"upJobId": 1,
		"uploadInfo": {
			"upJobId": 1
			"name": "ks (9).txt"
			"size": 168
			"type": "text/plain"
		}
	}
}

Sample JSON: The fs-upload-result event JSON for upload-completed status

{
	"messageType": "upload-completed",  
	"result": 0, 
	"description": "upload completed",  
	"response": {
		"uploadStatus": "completed",
		"upJobId": 1,
		"uploadInfo": {
			"upJobId": 1
			"name": "ks (9).txt"
			"size": 168
			"type": "text/plain"
		}
	}
}

Sample JSON: The fs-upload-result event JSON for upload-failed status

{
	"messageType": "upload-failed",  
	"result": 1185, 
	"description": "upload failed",  
	"response": {
		"uploadStatus": "failed",
		"upJobId": 1,
		"uploadInf"o: {
			"upJobId": 1
			"name": "ks (9).txt"
		}
	}
}

Download a Shared File

The process of downloading a shared file comprises of two steps: Know about the files available for download. Initiate the download of the available files.

Locate the Files Available for Download

Get the files available for download using roomObject.availableFiles, an array of JSON objects carrying file information.

Sample Code

let myFiles = room.availableFiles; 
// availableFiles JSON explained later

**Sample JSON: ** availableFiles JSON

[
	{
		"name": "DP1.pdf",  
		"size": 191002,
		"index": 0  
	} 
]

When a new file is available, the intended receiver is notified via the fs-download-result event with event.message.messageType='download-available'.

room.addEventListener('fs-download-result', function (event) {
	var msg = event.message;
	switch (msg.messageType) {
		case 'download-available':
			// Look for JSON Object for file infomration
			break; 
	}
});

Initiate a File Download

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

  • Method: EnxRoom.recvFiles(index, options, callback)
  • Parameters:
    • index : Number. Index number of the file to download.
    • options : JSON Object. Define file download process.
      • isMobile : Boolean. The default value is false. Set it to true to develop web-view based mobile applications.
    • callback: Callback function. To receive the status response of the sendFiles() method.
  • Event Listeners:
    • fs-download-result : Notification to the receiver about the file download process such as when the file download starts, completes, or fails.

Sample Code

let myFiles = room.availableFiles;


room.recvFiles(myFiles[0].index, {}, function(resp){
	if (resp.result == "0") { 
		// Success JSON example given below
	} else {	
		// Error JSON example given below
	}	
});


room.addEventListener('fs-download-result', function (event) {
	var msg = event.message;
	switch (msg.messageType) {
		case 'download-started':
			// Note msg.jobId for cancellation
			// download-started event JSON example given below
			break;
		case 'download-completed':
			// Know msg.jobId is completed
			// download-completed event JSON example given belowbreak;
			break;
		case 'download-failed':
			// Know msg.jobId has failed 
			// download-failed event JSON example given belowbreak;
			break;
		default:
			break;
	}
});

Sample JSON: Success JSON on recvFiles() callback

{
	"messageType": 'download-success',
	"result": 0,				// Succes
	"description": 'download-success',
	"response": {				// SDK May provide additional information 
		"downloadStatus": 'success',
		"name": xyz.txt,
		"type": text,
		"size": 100			// in bytes
	}  
}

Sample JSON: Error JSON on recvFiles() callback

{
	"result": 1180,				// A Non-Zero error code
	"error": "room is disconected",
	"desc": "File sharing is not allowed on disconnected rooms"
}

Sample JSON: The fs-download-result event JSON with download-started status

{
	"messageType": "download-started",  
	"result": 0,				// Success 
	"description": "download-started", 
	"response": {
		"downloadStatus": "started",
		"jobId": "0",			// Job ID for downloads in progress
		"downloadInfo": {		// SDK may provide additional information 
			"name": "ks (4).txt", 
			"size": 168,		// In bytes
			"index": 0,
		}  
	}
}

Sample JSON: The fs-download-result event JSON with download-completed status

{
	"messageType": "download-completed",  
	"result": 0,				// Success 
	"description": "download-completed", 
	"response": {
		"downloadStatus": "completed",
		"jobId": "0",			// Job ID for completed download
		"downloadInfo": {		// SDK may provide additional information 
			"name": "ks (4).txt", 
			"size": 168,		// In bytes
			"index": 0
		}  
	}
}

Sample Code: The fs-download-result event JSON with the download failed status.

{
	"messageType": "download-failed",  
	"result": 0,				// failed 
	"description": "download-failed", 
	"response": {
		"downloadStatus": "failed",
		"jobId": "0",			// Job ID for failed download
		"downloadInfo": {		// SDK May provide additional information 
			"name": "ks (4).txt", 
			"size": 168,		// In bytes
			"index": 0
		}  
	}
}

Cancel a File Upload

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

  • Method: EnxRoom.cancelUploads(id, cancelAll, callback)
  • Parameters:
    • id : Numeric. upJobId of the file being uploaded. This Id is received via the sendFiles() method.
    • cancelAll : Boolean. The default is false. Set it to true to cancel all file uploads.
    • callback : Callback function. To receive the status of a file upload cancelation request.

Sample Code

room.cancelUploads(id, false, function(resp) {
	// Handle response here
});

Cancel a File Download

The EnxRoom.cancelDownloads() allows you to cancel an ongoing file download job running at your endpoint.

  • Method: EnxRoom.cancelDownloads(id, cancelAll, callback)
  • Parameters:
    • id : Numeric. upJobId of the file being downloaded. This Id is received via the recvFiles() method.
    • cancelAll : Boolean. The default is false. Set it to true to cancel the download of all the files.
    • callback : Callback function. To receive the status of a file download cancelation request

Sample Code

room.cancelDownloads(id, false, function(resp) {
	// Handle response here
});

Screen Sharing

To support screen sharing in a room, you need to enable screen sharing in the Room Creation by setting: { "screen_share": true; } JSON payload. To receive shared screens, subscribe to the Screen-Share Stream ID# 101 and play it on the video player.

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.

  • Methods:
    • startScreenShare(options, Callback): This method available only in Web SDK 2.1.2 and later versions.
    • startScreenShare(Callback): This method available in Web SDK versions before 2.1.2.
  • Parameters:
    • options : JSON Object. Optional. Introduced in Web SDK v2.1.2. To have custom meta-data to help out UI / UX requirement, also to have many other parameters affecting Screen Share.
      • audio : Boolean. Default: false. To allow Screen Share to carry Audio Track from Microphone if underlying browser supportsit.
      • layout : String. Use this to pass some value to help define UI/UX at receiving end. e.g. pass presenter to show a Presenter Layout with Screen Share at the receiving end.
    • callback : Callback function. To receive the status of start process.
  • Event Notification:
    • share-started: Notification to everyone in the room when screen sharing starts.

Sample Code

var ShareOption = {
	"audio": true,
	"layout": "presenter"	//  Custom key to help UI/UX Development
				// In this case, you wanted to switch UI to Presenter Mode */
};


// Start Screen Sharing
streamShare = room.startScreenShare(ShareOption, function(result){
	 
});


// Notification: TO all. Share started
room.addEventListener("share-started", function (event) {
     	// Layout to switch to: event.layout
	// Define your UI with this key


	// Get Stream# 101 which carries Screen Share 
     	var shared_stream = room.remoteStreams.get(101);  


	// Play in Player
     	shared_stream.play("div_id", playerOptions); 
});

Stop Screen Sharing

The EnxRoom.stopScreenShare() method stops the ongoing screen sharing.

  • Method: stopScreenShare(sharedStream, Callback)
  • Parameters:
    • sharedStream: String. Screen sharing stream.
  • Event Notifications:
    • share-stopped: Notification to everyone in the room when screen sharing stops.

Note: There are alrenate ways to stop Screen Share:

  • Use unpublish(sharedStream, Callback).
  • Use "Stop Share" Option that a browser presents after successful start of share.

Sample Code

// Stop the Shared Screen
room.stopScreenShare( streamShare, function(result) {


});


// Stop the shared screen in alternate way
room.unpublish( streamShare, function(result, error) {      
     if (result === undefined) {          
         // Failed       
     } else {
          // Share Stopped
     }  
}); 
 
// Notification: To all. Screen Share stopped 
room.addEventListener("share-stopped", function (event) {
     // Handle UI here
});

Error Codes

CodeDescription
1143Device not found. Screen sharing is disabled at the operating system level.
1151Another screen sharing stream is active in the room.

Note:

  • Application sharing experience may differ from browser to browser.
  • If you are using a Google Chrome version prior to 72, you need to install an extension from the web store to initiate screen sharing on the publisher.

Force Stop a Participant's Screen Sharing

This functionality is available in Web SDK 2.1.2 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.

This feature is only for moderators and cannot be used by the participants. This method also force stops the ongoing canvas streaming.

  • Method: EnxRoom.stopAllSharing(Callback)
  • Event Notifications:
    • share-stopped: Notification to everyone in the room when screen sharing stops.

Sample Code

// Force Stop the Shared Screen
room.stopAllSharing(function(result) {


});
 
// Notification: To all. Screen Sharing stopped
room.addEventListener("share-stopped", function (event) {
     // Handle UI here
});

Canvas Streaming

Canvas Streaming allows you to use the HTML5 Canvas object to create a stream and publish it like a whiteboard into a room. To support canvas streaming in a room, you need to enable it during the room creation by specifying setting: { canvas: true; } in the JSON payload of the API. Client endpoints must subscribe to Stream ID#102 to receive canvas streaming.

Start Canvas Streaming

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

  • Method: EnxRoom.startCanvas(CanvasOpt, Callback)
  • Parameters:
    • CanvasOpt : JSON Object. Configurable streaming options in JSON payload.
      • canvasSelector : String. The Canvas DOM Element ID to act as a stream source.
      • fps : Number. The Frame Rate range of streaming. Range: 1-23.
  • Event Notifications:
    • canvas-started: Notification to everyone in a room when canvas streaming starts.

Sample Code

var CanvasOpt  = {
     "canvasSelector": "CanvasElementID", 
     "fps": 23
};


room.startCanvas(CanvasOpt, function(arg) {
     if(arg.result == 0) {	// Success     
     }
     else {			// Error
	// arg.result == 1154 (Frame rate not supported)
     }
});


// notification: TO all. Canvas Stream started.  
room.addEventListener("canvas-started", function (event) {
        var canvasStream = room.remoteStreams.get(102);
        if(canvasStream.stream !== undefined) {
             canvasStream.play("PlayerDiv");
        }
 });

Error Codes

CodeDescription
1154Frame rate is out of range. The valid range is from 1 to 23.
1157Canvas ID not found in HTML DOM.
1158Browser does not support the Canvas element in HTML DOM.
1159Failed to create stream as the source Canvas ID is not found in HTML DOM.

Stop Canvas Streaming

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

  • Method: EnxRoom.stopCanvas(Callback)
  • Event Notifications:
    • canvas-stopped: Notification to everyone in the room when canvas streaming stops.

Sample Code

room.stopCanvas(CanvasOpt, function(arg) {
     if(arg.result == 0) {	// Success 
    
     }
     else {			// Error 


     }
});


// Notification: To all. Canvas Streaming stopped 
room.addEventListener("canvas-stopped", function (event) {
        // Handle UI. Remove Player of Stream ID# 102
});

Force Stop Canvas Streaming

This functionality is available in Web SDK 2.1.2 and later versions.

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

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

  • Method: EnxRoom.stopAllSharing(Callback)
  • Event Notifications:
    • canvas-stopped: Notification to everyone in the room when canvas streaming stops.

Sample Code

// Force stop canvas streaming
room.stopAllSharing(function(result) {


});
 
// Notification: To all. Canvas streaming stopped
room.addEventListener("canvas-stopped", function (event) {
     // Handle UI here
});

RTMP Live Streaming

Start Forwarding an RTMP Stream

The EnxRoom.startStreaming() method allows a moderator to forward live video sessions over an RTMP stream to any live streaming CDNs supporting this protocol.

  • Method: EnxRoom.startStreaming(streamingConfig, callback)
  • Parameters:
    • streamingConfig : Configuration options JSON object for forwarding streams.
      • rtmpDetails.rtmpUrl : Use “RTM-URL/RTMP-KEY” from CDN Provider
      • rtmpDetails.urlDetails.url : Required. RTMP Streaming View URL. If not given, a default Streaming View will be applied.
  • Event Notifications:
    • streaming-started : Acknowledgment to the moderator when RTMP streaming starts.
    • streaming-updated : Intermediate notification to the moderator who tried to start streaming with start-process updates.
    • streaming-failed : Notification to the moderator who tried to start streaming after it failed to start.

Sample Code

var streamingConfig = {	
	rtmpDetails: {
		rtmpUrl: "RTMP_URL/RTMP_KEY"
	},
	urlDetails: {
		url: "URL-TO-USE-AS-STREAMING-VIEW"
	}
};


// Start Streaming
room.startStreaming(streamingConfig, function(resp) {
	if (resp.result === 0) {
		console.log('Streaming started. You are live.');
	}
	else {	// Streaming failed
		console.log(resp.error)
	}


});


// Notification: To all. Streaming has started
room.addEventListener('streaming-started', function(event) {
	// event.message.startedBy : who started the streaming
});


// Notification: To self. Streaming has failed to start 
room.addEventListener('streaming-failed', function(event) {


});


// Notification: To self. Intermediate updates on start process  
room.addEventListener('streaming-updated', function(event) {


});

Error Codes

CodeDescription
7000Failed to start streaming.

Stop Forwarding an RTMP Stream

The EnxRoom.stopForwarding() method is used to stop forwarding RTMP streams.

  • Method: EnxRoom.stopForwarding(callback)
  • Event Notification:
    • streaming-stopped: Notification to all the participants in a room when RTMP streaming stops.

Sample Code

// Stop Streaming
room.stopStreaming(function(resp) {
	console.log('Streaming Stopped.');
})


// Notification: To all. Streaming stopped
room.addEventListener('streaming-stopped', function(event) {
	// event.message.stoppedBy : who stopped the streaming
});

HLS Streaming

HLS streaming helps you reach extremely large audiences with your video session in real-time. It supports adaptive bitrate streaming to get the best quality video based on available network bandwidth at the receiving end.

HLS streaming helps scale up your reach to a larger audience with your real-time video session, meetings, and webinars. Audiences receive the best quality video streaming based on their available bandwidth. You can link a web-based video UI to define the view of your streaming which will be played across devices.

In the background, the linked video UI is automatically made to join the video room, and an HLS Stream is created using the same view. As the stream is ready, endpoints receive an HLS Stream URL from playing in HLS player.

HLS Service Subscription

The HLS streaming infrastructure is owned and managed by EnableX. Therefore, it is a subscription-based service. For subscription, contact the Sales or Account Manager.

If you plan to live stream on YouTube, Vimeo, LinkedIn, and/or Facebook, go through RTMP Live Streaming.

HLS View

HLS streaming experience for audiences may be achieved through the video UI. You can have a video UI or HLS View in either of the following ways:

  • Use Default View: The simplest and quickest way is to use the default view provided by EnableX where you do not need to code. However, this view provides limited customization options.
  • Develop Custom View: For a custom view, you need to develop a web-based application, host it over a publicly accessible "https" URL, and link it to the video room. Read all information that you need to know to develop a custom view for your stream.

HLS Enabled Room

Even if the HLS service is subscribed, you must configure the following room level settings to include this service in a video session.

Sample JSON Payload: Room Definition to enable HLS streaming**

{
  "name": "HLS Trial",
  "owner_ref": "XOXO",
  "settings": {
    "description": "HLS Trial",
    "mode": "group",
    "scheduled": false,
    "adhoc": false,
    "duration": 30,
    "moderators": "1",
    "participants": "2",
    "audiences": 6,
    "hls_view_url": "https://URL-DOMAIN/PATH/?token=",
    "send_audiences_stats": true,
    "auto_recording": false,
    "quality": "SD"
  }
}

JSON Explaination:

  • audiences : Number. Optional. The number of audiences needed in the room.
    It cannot be more significant than the capping set at subscription. If the following settings are set with the room, the audience count must be set to a positive number. |
  • send_audiences_stats : Boolean. The default value is false. Set it to true if the endpoint needs to receive user-connected and user-disconnected events on entry and exit of an audience.
  • hls_view_url : String. Optional. URL of the custom view. If not passed, the default HLS streaming view is used. You can explicitly pass "DEFAULT" as value to this key.

For more information, see:

Note: If HLS is not subscribed, room definition with HLS-related settings is not permitted.

Audience Token to Join

A new role, audience, has been introduced for HLS audience joining a room. You must get a token for an audience role to join a session. As soon as the first audience joins a video room, HLS streaming is automatically initiated. It is stopped when all the audiences exit or disconnect from the video room.

For more information about creating tokens, see How to create a Token?.

Sample Code: JSON payload to create a token for the audience role

{
  "name": "John",
  "user_ref": "XOXO",
  "role": "audience"
}

HLS Player

The HLS Stream URL received through our Video SDK event hls-started (explained later in this document) needs to be played using an HLS Player. You may use your own HLS player or find a suitable player on the internet. You can also use the HLS Player provided by EnableX.

Download EnableX HLS Player . Relesead on November 7, 2022

Use the following method to start playing the HLS stream URL on the specified HTML element. Before calling this function, initialize an object of the EnxHls class to call the HLS Player SDK function.

  • Method: playStreamerURI(element, hls_url)
  • Parameters:
    • element : String. HTML DOM element ID to place the HLS player.
    • hls_url : String. HLS stream URL to play in the HTML DOM element.

Sample Code

var hlsPlayer = new EnxHls(); 
if(hlsPlayer) {
	hlsPlayer.playStreamerURI("con_" + localStream.getID(), hls_url); 
}

Room Event Listeners

HLS streaming starts as soon as the first audience joins a video room and stops when the last audience exits or disconnects from the room. So, you must add listeners to HLS-related events and handle the UI to create appropriate user experience.

  • Event Listeners
    • hls_started : When a HLS stream starts, the stream is sent to the publisher and logged-in audiences. Subsequently, it is sent to new audiences on room connection. It includes hls_url to play. |
    • hls_stopped : When a HLS stream stops, it is sent to the publisher when the last audience leaves the video room.
    • hls_failed : When a HLS stream fails to get started or fails during an ongoing streaming, it is sent to the publisher and audiences.
    • hls_waiting : When the HLS stream initiation process is waiting to get started, it is sent to audiences only.

Sample Code: Listening to hls-started to play the HLS stream

room.addEventListener("hls-started", function(event) {
	var response = event.message;
	if(response.error == undefined) {
		var streaming_url =  response.hls_url;
		if(streaming_url){
			var hlsPlayer = new EnxHls();
			if(hlsPlayer) {
				hlsPlayer.playStreamerURI(
					"con_" + localStream.getID(), 
					streaming_url
				);
			} else {
				console.log('Error: HLS Player');
			} 
		} else {
			console.log('Error: ', error);
		}
	}
});

Error Codes

On HLS Start

CodeDescription
7501Start HLS streaming input parameters missing, internal server error.
7502Start HLS streaming timeout, internal server error.
7503Start HLS streaming request is in process.
7504Start HLS streaming request timeout, Internal Server Error
7505HLS streaming request is in waiting, will be started
7506HLS streaming cannot be started now. Try after 2 minutes.
7507Start HLS streaming input parameters missing, internal server error.
7508Start HLS streaming input parameters missing, internal server error

On HLS Stop

CodeDescription
7520HLS streaming request was in waiting. The request was successfully removed from waiting.
7521Stop HLS streaming failed, internal server error.
7522Stop HLS streaming timeout, internal server error.

On HLS Waiting

CodeDescription
7509HLS streaming cannot be started, internal server error. Try after 2 minutes.
7510HLS streaming start failed, internal server error. Try after 2 minutes.
7511The last HLS streaming request is in waiting.
7512HLS streaming cannot be started, try again. Internal server error.
7513HLS streaming failed to start, internal server error.

HLS Generic Error

CodeDescription
7000Start HLS streaming input parameters missing, internal server error.

Annotation

The Annotation feature allows you to annotate on a remote stream. To support this feature, you need to enable canvas streaming during Room Creation by setting: { canvas: true; } in the JSON payload. You also need to add the Annotation toolbar before users can start using annotations.

Annotation Toolbar

The Annotation toolbar is displayed with a default set of tools and properties. The EnxRoom.annotateToolAction() method allows you to configure this toolbar.

  • Method: EnxRoom.annotateToolAction(action, value)
  • Parameters:
    • action : String. Tool property name. Following tools are used as action:
      • draw : Boolean.
      • drawType : String e.g. Pencil.
      • Color : String. HEX Color Code e.g. #ff0000
      • LineWidth : Numeric. Default: 3
    • value: value of the Tool as explained above

Sample Code

function annotateToolAction("Color", "#ff0000") {
}

Start Annotation

The EnxRoom.startAnnotation() method is used to start annotation on a specific stream object.

  • Method: EnxRoomstartAnnotation(EnxStream, Callback)
  • Parameters:
    • EnxStream : EnxStream Object. The Stream surce for annotation.
    • Callback : Callback function. To know status of request.
  • Event Listeners:
    • canvas-started : Notification to everyone in the room when canvas streaming starts. The event message contains "canvasType": "Annotation" to identify it as Annotation.

Sample Code

const stream = roomObject.remoteStreams.get(streamId);


roomObject.startAnnotation(stream, function (arg) {
	console.log(arg, "arg");
});


//Notification: To all. Annotation started 
roomObject.addEventListener("canvas-started", function(evt) {
	/* evt.canvasType === "Annotation" */ 
});

Stop Annotation

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

  • Method: EnxRoom.stopAnnotation(Callback)
  • Parameters:
    • Callback : Callback function. To know status of request.
  • Event Listener: canvas-stopped: Notification to everyone in the room when canvas streaming stops. The event message contains "canvasType == "Annotation" to identify it as annotation.

Sample Code

roomObject.stopAnnotation(function (arg) {


});


//All are notified that Annotation stopped
roomObject.addEventListener("canvas-stopped", function(evt) {
	/* evt.canvasType === "Annotation" */ 
});

Live Transcription

EnableX supports live transcription of video sessions. 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. Live transcription is helpful when participants have limited language proficiency or difficulty hearing because of a noisy background.

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. All endpoints requesting live transcription start receiving Speech-to-Text contents of all the actively talking users in a video room through a notification event.

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.

Sample JAON Payload: 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
    } 


  }
}

Sample JAON Explaination

  • live_transcription : Object. Contains Transcription settins.
    • language : String. Required. Language Codes. The primary language of communication.
    • auto_transcribe : Boolean. The default value is false. Change it to true to automatically start the transcription process when the session starts. All text contents are saved in a file. This file is made available post session through an API.
    • enable : String. Boolean. The default value is true. Change it to false if live transcription is not needed in a room. If subscribed, live transcription is automatically enabled in each room.

For more information, see:

How to Create a Video Room
How to Obtain the Post Session Transcription File

Note: If live transcription is not subscribed, then room definition with 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 the 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:
    • startLiveTranscription(language, callback): For user-level transcription.
    • startLiveTranscriptionForRoom(language, callback): For room-level transcription for all users.
  • Parameter:
    • language: String. Optional. Default english_us. Other Language Codes. Language that you want the Speech Recognition engine to recognize for you.
  • Event Notifications:
    • self-transcription-on : To notify that self-transcription is enabled.
    • room-transcription-on : To notify that room level subscription is enabled.
    • transcription-events : This is to notify speech to text contents as and when they are in recognising and recognised state.

Sample Code

// Start Transcription
startLiveTranscription(language, function(result, error) {


});
 
// Notification: To self, self-transcription is on
room.addEventListener( "self-transcription-on", function(event) {
    
}); 
    
// Notification: To self. room-transcription is on
room.addEventListener( "room-transcription-on", function(event) {
    
}); 


// Notification: To self. transcripion data update events
room.addEventListener( "transcription-events", function(event) {
	// print recognized speech
	// event JSON given later.
	if (event.type == 'speech-recognised') {
		console.log(event.text);
	}
});

Sample JSON: JSON with Event transcription-events

{
	"type": "speech_recognise",
	"text": "Hello how are you?",
	"duration": 5,
	"clientID": "String"
}

Sample JSON Explanation: JSON with Event transcription-events

  • type : String. It's value is either speech_recognising or speech_recognised.
    • speech_recognising : It is an intermediate event triggered when the audio is being recognized by the speech engine.
    • speech_recognised : It is triggered when the entire audio is recognized. Normally, this occurs when the audio is paused or the end of the speech is detected by the speech engine.
  • text : String. The transcribed text.
  • `duration`` : Number. Duration from the offset when the speech has been.
  • clientId : String. Cliend ID of the user whose speech is recognized.

Error Codes

CodeDescription
3002Live transcription subscription is not enabled.
3002Live transcription is already in progress.

Stop a 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: stopLiveTranscription(callback)
  • Event Notifications
    • self-transcription-off : To notify that self-transcription is turned off.
    • room-transcription-off : To notify that room level subscription is turned off.

Sample Code

// Stop Transcription
stopLiveTranscription(function(result, error) {


});
 
// Notification: To self. self-transcription is turned off
room.addEventListener( "self-transcription-off", function(event) {
    
}); 
    
// Notification: To self. room-transcription is turned off
room.addEventListener( "room-transcription-off", function(event) {
    
});

Error Codes

CodeDescription
3001Live transcription request is not found.
Room ConnectionSession Management