Video API v1.8 Web SDK / Basic Functions

Basic Functions of Web SDK describes the necessary tasks to achieve basic Audio/Video communication between participants connected from their End-Point Applications to an EnableX hosted Room. For more advanced use cases, please refer Advance Features & Moderator Controls.

Table of Contents

Get list of Audio and Video Devices

You will need to specify audio/video device ID (Microphone and Camera’s Device ID) or use the browser’s default devices to initiate an audio/video stream. EnableX provides API support to get a list of devices (Microphone & Camera) attached to your PC/Device running the Client End Point application along with their device IDs.

The EnxRtc.getDevices() method is used to return a JSON Structure containing all the Microphones & Cameras attached to the PC/Device. You can build UI Element to choose a Camera and a Microphone to use for Stream using the return JSON.

Method: EnxRtc.getDevices(Callback)

EnxRtc.getDevices( function(response) { 
     if( response.result === 0 ) {   // success                     
         /* Device Lists in response.devices */ 
         var camList =  response.devices.cam; 
         var micList =  response.devices.mic; 
     }
     else if(response.result === 1144){ // Error case  
         {
     }
 });

Response JSON

{
     "result": 0,       
     "devices": { 
             "cam":[ 
                 { 
                 "deviceId": "", 
                 "groupId": "", 
                 "label": "" , 
                 "kind" : "" 
                 } 
             ], 
             "mic": [ 
                 { 
                 "deviceId": "", 
                 "groupId": "", 
                 "label": "" , 
                 "kind" : "" 
                 } 
             ] 
         } 
 }

Initiate a Room

Client SDK is used by the Client End Point Application to connect to the Virtual Room hosted at EnableX to establish a session. The process starts with initializing a Room Object using the EnxRoom Class. The Constructor requires a JSON Parameter with a Token that the Client End Point received from EnableX platform via  their Application Server. Initialize the Room Object as follows:

var room = EnxRtc.EnxRoom({token:'xxxx'});

Connect to Room

After Room’s initialization the Client End Point needs to connect to the EnableX Server to join a session. The EnxRoom.connect() method is used to connect to the virtual Room hosted by EnableX. Unless an End Point is connected to EnableX, no other communication is possible between the two entities, viz. EnableX Server & Client End Point.

When connected, a Bi-Directional Communication Channel will be established between the End Point and EnableX Server over a Web Socket. Both entities communicate with each other using Socket Events. Communication would fail if any network issue disconnects the Web Socket.

A connected Web Socket might get disconnected due to network issues. For disconnected end-points, EnableX supports Auto Re-connection to the Session ensuring better user experience.

Note:

  • Client End Point may not get connected to the room due to network problem, invalid or expired Token. If it fails to connect, you will be notified accordingly using event room-failed.
  • Depending on Room definition, you may either get connected to the room instantly or you may be kept awaited until Moderator permits you to get connected. Connection to knock-enabled Rooms require Moderator’s permission to get into a room.
  • End Point is notified with event room-connected on successful connection to the room with complete run-time Meta Information of the Room.
  • End Point is notified with event room-awaited when you are connected to EnableX after a successful Token Verification process but awaited for moderator’s permission before you can be connected to the virtual Room hosted at EnableX to participant in the session.
  • Auto-Reconnect doesn’t work on:
    • Last Participant disconnected from Adhoc Room
    • User is dropped from Room by Moderator
    • User disconnects explicitly using EnxRoom.disconnect() method

Method: EnxRoom.connect(ReConnectOpt)

Parameters: ReConnectOpt – Optional. JSON Object with Reconnection Options. JSON keys explained below:

  • allow_reconnect Boolean. Default: true. Whether to enable Auto-Reconnect feature. If you set to false, Client End Point will not try reconnecting to EnableX
  • number_of_attempts Numeric. Min Value: 1. Max Value: Not specified, use any number. Default: 3. Maxi number of times Client End Point tries to reconnect to EnableX
  • timeout_interval Numeric. Timeout Interval in Millisecond to wait before attempting reconnect

Event Notifications:

  • room-connected – To the end-point when its connected to Room
  • room-failed – To the end-point when it fails to connect to Room
  • room-awaited – To the end-point when its awaited for Moderator’s permission to connect to Room
  • user-connected – To notify all connected users that a new user is connected to Room
  • user-awaited – To notify moderator that a user is awaited needs his permission to connect to Room. Refer explanation given in Moderator Controls
  • active-talkers-updated – To the end-point with list of Talkers after few seconds of receiving room-connected event. Refer how to handle Active Talkers
var initOpt = { "token": "XXX" };
var room = EnxRtc.EnxRoom(initOpt); // Initiates Room 

var reConnectOpt = {
    "allow_reconnect": true,
    "number_of_attempts": 3,
    "timeout_interval": 10000
};

room.connect( reConnectOpt ); // Connects with Re-Connection Option

/*
// Alternate Connection 
room.connect();    // Connects with Default Re-Connection Option
room.connect({})   // Connects with Default Re-Connection Option 
room.connect({"allow_recnnect": false})   // Connects  without Re-Connection feature 
*/

room.addEventListener("room-connected", function(event) {
     // Connected. event receives Room Meta JSON
});

room.addEventListener("room-failed", function(error) {
     // Connection failed. Find error
});

room.addEventListener("room-awaited", function(event) {
     // Awaited to Connected to knock-enabled Room
     // When Moderator permits, you received room-connected event
});

room.addEventListener("user-connected", function(event, user) {
     // A new user connected. user JSON has user information
});

room.addEventListener("user-awaited", function(event, user) {
     // A new user awaited permission to get connected
     // user JSON has user information
});

room.addEventListener("active-talkers-updated", function(event) {
     // List of talkers in the Room
     // Received after room-connected
});

Initiate Stream

A local stream has to be initialized at the Client End Point before you can publish it to the Room. The initialization process includes specifying media source, adding custom attributes etc. in a form of a JSON object. The Constructor of EnxStream Class, a sub-class of EnxRtc Base Class, takes the JSON Object as parameter to initialize the Stream.

Method: EnxRtc.EnxStream(StreamOpt)

Parameters: StreamOpt – A typing JSON definition with Stream Options given below:

 {
     "audio": true,          // Whether to add Audio to stream
     "video": true,          // Whether to add Video to stream
     "data": true,           // Whether to add Data to stream
     "screen": false,        // Whether to add Screen Share to stream
     "audioMuted": true,     // Audio muted on entry to room  
     "videoMuted": true,     // Video muted on entry to room  
     "attributes": {         // Object to carry custom data  
         "custom1": ""
     },
     "options": {}           // Video Player Options */
     "videoSize": [minWidth, minHeight, maxWidth, maxHeight],
     "maxVideoLayers": Number // Number of Video Layers in Stream
                              // Enumerated Values: 1, 2, 3
                              // 1=HD 720p layer only
                              // 2=HD 720p & SD 480p layers only
                              // 3=HD 720p, SD 480p & LD 240p/180p layers
                                     
 }

Initiate Stream with Default Devices

To start a stream with audio, video and data tracks set related keys to true to initiate Stream with default Microphone & Camera. You can put custom keys within attributes to define additional information that the stream will carry along.

var streamOpt = {
     audio: true, 
     video: true, 
     data: true, 
     attributes: { name:'My-Stream-Name' }
 };

 var localStream = EnxRtc.EnxStream( streamOpt );

Initiate Stream with specified Devices

The example shown above will use a default or available Microphone or Camera to initiate the stream. However, you may select specific Microphone and Camera  to initiate the stream by passing their Device IDs. To obtain a list of cameras and microphones available to local machine, please use the EnxRtc.getDevices() method. 

 var streamOpt = {
     audio: {deviceId: "XXX"}, 
     video: {deviceId: "XXX"}, 
     data: true, 
     attributes: { name:'My-Stream-Name' }
 };

 var localStream = EnxRtc.EnxStream( streamOpt );

Handle Device Access for Audio / Video Stream

Note that Audio / Video Stream initiation process require access to Microphone and Camera access to act as a source for the Stream. The browser would prompt with a dialog to give access to the application for one or both of these device types (as applicable). The user must allow access for successful initiation of Stream. However, user may deny devices access. You need to use following 2 event listeners to know if user allowed or denied device access and act accordingly:

Event Listeners:

  • media-access-allowed – When Media Device Access is allowed
  • media-access-denied – When Media Device Access is denied 
stream.addEventListner('media-access-allowed', function (response) {
	/* response = {
		stream: StreamObject,
		type: "media-access-allowed"
	}*/
});

stream.addEventListner('media-access-denied', function (response) {
	/* response = { type: 'media-access-denied', msg: err }*/
});

Initiate Stream with Local File & Remote URL

You may initiate a stream using Remote URL or Local File Path to a .mkv file.

var streamOpt = {
      audio: true, 
      video: true, 
      url:"rtsp://FQDN/video-resource-path"
 };

var streamOpt = {
      audio: true, 
      video: true, 
      url:"file://video-file-path"
 };

var localStream = EnxRtc.EnxStream( streamOpt );

Initiate Stream with Screen Share

Screen Share on Chrome browser is supported by Chrome extension. Even though EnableX SDK uses its own extension by default, you can specify a different Extension ID to use to start screen share.

var streamOpt = {
      screen: true, 
      data: true, 
      desktopStreamId:'EXTENSION_ID'
};

var screenStream = EnxRtc.EnxStream( streamOpt );

Initiate Stream with Multiple Video Layers

EnableX provides Auto Bandwidth Detection feature. To help subscribers receive best video quality subject to the available bandwidth at their end, Stream publishers must ensure that their Streams carry multiple video layers of different quality. Client SDK at Subscriber end automatically would switch to the video layer that it can receive to play. 

var streamOpt = {
       audio: true, 
       video: true, 
       maxVideoLayers: 3 // Carry 3 layers, viz HD 720p, SD 480p & LD 240p/180p 
 };

// Enumerated Values for  maxVideoLayers: 1, 2, 3                               
// 1=HD 720p layer only                               
// 2=HD 720p & SD 480p layers only                               
// 3=HD 720p, SD 480p & LD 240p/180p layers 

var screenStream = EnxRtc.EnxStream( streamOpt );

Join a Room without or with Stream

Connecting and joining a Room is a complex chain of events. You will need to ensure success status of previous event to proceed to the next event. The following basic steps are required to join room successfully

  • Initiate Room & Connect
  • If connected, initiate Stream. Check media accessibility
  • Publish Stream
  • Check if Stream publishing succeeded

You also need to handle error conditions. If your Application demands for you to go step-by-step, you are welcome to take this path to code. However, many applications only require a quick and easy way to join a Room.

EnxRtc.joinRoom() method comes as a handy tool for developer. It handles all complexities of connecting and joining the room and publish the local stream.

Method: EnxRtc.joinRoom( Token, StreamOpt, Callback, ReConnectOpt )

Parameters:

  • Token – JWT Token received through Server API Call
  • StreamOpt – Stream Initialization Meta Info. Optional. If you don’t want to publish your local stream, pass blank JSON object i.e { }.
  • ReConnectOpt – Optional. JSON Object with Reconnection Options. JSON keys explained below:
    • allow_reconnect Boolean. Default: true. Whether to enable Auto-Reconnect feature. If you set to false, Client End Point will not try reconnecting to EnableX
    • number_of_attempts Numeric. Min Value: 1. Max Value: Not specified, use any number. Default: 3. Maxi number of times Client End Point tries to reconnect to EnableX
    • timeout_interval Numeric. Timeout Interval in Millisecond to wait before attempting reconnect

Returns: Published Local Stream Object

var VideoSize = {
     "HD": [320, 180, 1280, 720], 
     "SD": [320, 180, 640, 480],
     "LD": [80, 45, 640, 360]
};

var StreamOpt = {
         video: true,
         audio: true,
         data: true,
         videoSize: VideoSize.HD,
         attributes: { name: "XX" }
};

var reConnectOpt = {
    "allow_recnnect": true,
    "number_of_attempts": 3,
    "timeout_interval": 10000
}; 

localStream = EnxRtc.joinRoom(Token, StreamOpt, function (success, error) {
     if (error && error != null) {
         // Look for error.type and error.msg.name to handle Exception
         if(error.type == "media-access-denied") {
              // Media Media Inaccessibility
         }
     }
    
     if (success && success != null) { 
         room = success.room;
         remoteStreams = success.room.streams; 
     }
 },
 reConnectOpt
)

Disconnect from a Room

A Client End Point can disconnect itself from the room to close its session. A disconnected End-Point will loose media and signaling socket immediately.

Once disconnected, the SDK will initiate a notification event room-disconnected for you to handle UI. Also, all connected users of the session will be notified with an event named user-disconnected so that they all can update the status of their UI.

Method: EnxRoom.disconnect() – Without any parameter

Notification Events:

  • room-disconnected – To the user who is disconnected
  • user-disconnected – To all other connected users
room.disconnect();

room.addEventListener("room-disconnected", function(event) {
     // You are disconnected
});

room.addEventListener("user-disconnected", function(event) {
     // One user is disconnected
     // event - User Information of disconnected user
 });

Note: You receive room-disconnected event for many reasons. The event comes with a JSON object to notify with the reason. Refer the following to understand reasons and to handle it accordingly.

CodeReason
2001disconnected-by-moderator
2002unexpected-disconnection
2003conference-expired
2004network-failure
2005media-handshake-failure

Publish / Unpublish Local Stream

The local stream with audio/video needs to be started and published to the Room for other participants to see and hear you. Please use the API methods below to publish, unpublish and close local stream.

Publish Local Stream

EnxRoom.publish() method is used to publish a local stream to the connected Room. After the local stream is published to the Room, all participants are notified with an event named  stream-added.

Method: EnxRoom.publish(LocalStream, PublishOpt, Callback)

Parameters:

  • LocalStream – Locally Initiated Stream Objech
  • PublishOpt – Configurable Options for publishing

Notification Events:

  • stream-added– to all participants announcing new stream in room
  • stream-failed– to publisher notifying that publishing process has failed
// Configure Optional Publishing Options
var PublishOpt = {
     "minVideoBW":"Number",  
     "maxVideoBW": "Number" 
};

room.publish(localStream, PublishOpt, function(StreamId) {
});

// New Stream in Room Notification
room.addEventListener("stream-added", function(event) {
     if (localStream.getID() === event.stream.getID()) {
         // Your stream published
     } else {
         // Someone else has published
     }
});

room.addEventListener("stream-failed", function(event) {
     // Failed to publish
});

Unpublish Local Stream

Unpublishing a published stream will disconnect the local stream from the Room. The process will not release device access so that subsequent re-publishing will not require the user to grant  device access again.

To unpublish, use EnxRoom.unpublish() method. Please use the callback to handle if stream is unpublished successfully. All users connected to the room will be notified that a Published Stream is unpublished or removed from the Room using the event named stream-removed

Method: EnxRoom.unpublish(localStream, Callback)

Parameters: localStream Local Stream Object to be unpublished

Notification: stream-removed – to all participants

room.unpublish(localStream, function(result, error) {
    if (result === undefined) {
        // Failed       
     } else {
        // Unpublished      
     }  
});

Close Local Stream

Closing a Published Stream will disconnect the local stream from the Room similar to  unpublishing process. Note the following:

  • If stream has audio and video tracks, it stops capturing media stream from webcam & microphone,
  • If the stream is published into the room, it unpublishes the stream.
  • If the stream is being played in Player, it stops playing

Method: EnxStream.close()

localStream.close();

Subscribe / Unsubscribe Remote Streams

To receive media streams of other participants connected to a Room, you must subscribe to the streams individually. Unless you subscribe a stream, you will not receive anything.

After successful connection with Room, Client End-Point receives a list of streams available in the Room in the Room Meta Information as { streams: [] }. The Client End Point needs to subscribe to all remote streams available in the room. In addition to the streams available in Room’s meta information, you also need to subscribe to the following 2 streams as applicable for your application:

  • StreamID# 11 – To receive Screen Share
  • StreamID# 21 – To receive Canvas Streaming

Method: EnxRoom.subscribe(RemoteStream, SubsOptions, Callback)

Parameters:

  • RemoteStream – The Stream Object to subscribe
  • SubsOptions – JSON for Subscription Option. Keys to define subscription choice given below:
    • audio – Boolean – Whether to subscribe to Audio of the Stream
    • video – Boolean – Whether to subscribe to Video of the Stream
    • data – Boolean – Whether to subscribe to Data of the Stream

Event Notification:

  • stream-subscribed – To notify the subscriber that subscription process has succeeded.
var subsOptiions = {
    audio: true,
    video: true,
    data: true
};

// Subscribe to all Streams in Room Metaa
for (var i = 0; i < success.streams.length; i++) {
    room.subscribe(success.streams[i],  subsOptiions  );  
}  

room.addEventListener("stream-subscribed", function(event) {
    // Stream subscribed
});

Note! Please do not  subscribe to your local stream. EnableX platform will not return your locat audio/video stream. Details can be found in Active Talkers Section below. However, as a  publisher you will receive your own Screen Share and Canvas Streaming.

Handle Active Talkers

During a multi-party video conference, more server and Client-End-Point resources are consumed. Therefore, EnableX sends only 6 streams of users actively talking (generating sound) in the Room to each end-point. Additionally, it sends 2 streams, viz. Screen Share (Stream# 11) and Canvas Stream (Stream# 21).

The list of Active-Talkers is available in JSON format along with an event active-talkers-updated whenever there is a change in the talkers list. The list of Active Talkers comprises list will have talkers in ascending order i.e. latest talker will be listed first. Therefore, you may expect to receive the event too frequently in a noisy room.

EnableX v1.8 introduces pinning of user-streams that forces pinned users also in the Active Talkers List irrespective they are talking or not. So, active talkers appear first in the list and then pinned non-talkers. All the pinned users are shown with pinned: true in the Active Talkers JSON.

Event Notifications: active-talkers-updated

Active Talkers List JSON

{    "active" : true,
      "activeList": [
           {   "clientId" : "String", 
               "mediatype" : "audiovideo", // Enum: audiovideo, audioonly
               "name" : "String",
               "reason" : "user",
               "streamId" : Number,
               "videoaspectratio" : "16:9", 
               "videomuted" : Boolean,
               "pinned" : Boolean
           }
       ]
   }

This Active Talkers JSON is used for managing the UI and to play audio/video streams from remote users. To play a specific stream, you need the  Remote Stream object from room.remoteStreams related to the streamId of a Talker. Please remember before you can play any stream from the Active Talkers list, you should have subscribed to all “dummy” streams available in the Room’s meta information i.e room.streams.

room.addEventListener('active-talkers-updated', function (event) {
       TalkerList = event.message.activeList;
       for (var i = 0; i < TalkerList.length; i++) {
           if (ATUserList[i] && ATUserList[i].streamId) {
               var stream  = room.remoteStreams.get(ATUserList[i].streamId);
               var stream_id   = ATUserList[i].streamId;
               var username    = ATUserList[i].name;
               stream.play("DOM_ELEMENT_ID", PlayerOptions);
           }
       }                       
 }

Note: The local Stream will not  be included in the Active Talkers JSON list sent to an End-Point even if the End Point is talking. Hence the Active Talker JSON list sent to different End Points varies. In case you need to play own stream, please use the local stream.

Get Talker Count

It may be necessary to know how many talkers are expected to receive with active-talkers-updated event, i.e. to know either the preset value of talkers or any custom value in effect which is either by the Application Developer or opted by End-Point User.

Method: EnxRoom.getTalkerCount( Callback ) – returns max. Talker Count effective at the End Point 

room.getTalkerCount( function(response) {
     // Talker info in response JSON:
     // { "result": 0, "maxTalkers": 4 } 
});

Set Talker Count

EnableX sets a maximum of 6 active talkers in the active talker-list with active-talkers-updated event. However, you may opt to receive less talkers at a Client End Point if you so require. This may either be a predefined value, or this value may be set at run-time in a connected session. If needed, you can create UI for the connected user to opt for number of active-talkers the user wants to receive.

Method: EnxRoom.setTalkerCount(numTalkers, Callback )

Parameters: numTalkers – No. of talkers you want to receive. Range 0-6

  • If you set numTalkers to any value from 1 to 6 – you will receive those many talkers in the list.
  • If you set numTalkers to 0 (zero), then list doesn’t become empty. Rather, you would start receiving 3 audio streams only. Video Streams will not be carried.
room.setTalkerCount(5, function(response) {
     // Set Talker info in response JSON:
     // { "result": 0, "maxTalkers": 5 } 
 });

Get Maximum Allowed Talker Count

It may be necessary to know how many maximum talkers allowed in the room to which the end-point is connected. The End-Point may opt to receive less active talkers than the allowed number of talkers.

Method: EnxRoom.getMaxTalkers( Callback ) – returns maximum number of talkers allowed in the Room 

room.getMaxTalkers( function(response) {
     // Maximum Talker info in response JSON:
     // { "result": 0, "maxTalkers": 6 } 
});

Handle Network Disconnection & Re-Connection

A Client End Point is connected with EnableX over Secured Web Socket. A connected End Point might get disconnected from EnableX due to network issues. The End Point gets notified with an event network-disconnected.

Event Notification: network-disconnected – when End Point gets disconnected.

room.addEventListener('network-disconnected', function(event){ 
      // Handle UI or prompt user. 
});

For disconnected end-points, EnableX supports Auto Re-connection to the Session ensuring better user experience. To use Automatic Re-Connection feature, you must initiate the Connection with Room with Re-Connection options. Note that Auto-Re-Connect doesn’t work when:

  • Last Participant disconnected from Adhoc Room
  • User is dropped from Room by Moderator
  • User disconnects explicitly using EnxRoom.disconnect() method

Event Notifications:

  • network-reconnected – When End-Point successfully gets reconnected with EnableX
  • network-reconnect-timeout – When End-Point fails to reconnect within specified time period
  • network-reconnect-failed – When End-Point fails to reconnect for other reasons
var reConnectOpt = {              // Re-Connect Options
    "allow_reconnect": true,
    "number_of_attempts": 3,
    "timeout_interval": 10000
}; 

room.connect( reConnectOpt ); 

room.addEventListener('network-reconnected', function(event){
     // Got reconnected
});
 
room.addEventListener('network-reconnect-timeout', function(event){  
     // Re-Connect Attempt timed-out 
});

room.addEventListener('network-reconnect-failed', function(event){
     // Re-Connect Attempt failed 
});

Play Stream

You can play a local stream, all subscribed remote streams including screen-share, canvas streams within HTML5 Video Player.

Please use EnxStream.play() method to play a stream in a HTML5 audio or video player within HTML DOM. The method will create related audio/video HTML tag within the given HTML DOM Element ID to play the video or audio. Player Optional JSON parameter makes it easy to configure Player.

Method: EnxStream.play(DOMElementID, PlayerOpt)

Parameters:

  • DOMElementID – DIV Id in which Player will be drawn
  • PlayerOpt – Refer Appendix for complete list
// Configure Desired Player Options
var PlayerOpt = {
     player: {
         'height': '150px',
         'width': '100%',
         'minHeight': 'inherit',
         'minWidth': 'inherit'
     },
     toolbar: {
         displayMode: false,
         branding: {
             display: false
         }
     }
 };

stream.play("PlayerDiv",  PlayerOpt);

Stop Playing Video

You can stop playing Audio Video Stream in the HTML5 player by using EnxRtc.stop() method.

Method: EnxStream.stop() – No parameter

stream.stop();

Know Stream Information

EnableX API provides different methods to access stream information.

Get Stream ID

Every Stream is identified by its Stream ID, be it a local or a remote stream, a canvas stream or a screen share stream. You may obtain the ID of the stream using EnxRtc.getID() method.

Method: EnxRtc.getID()

Return: StreamID

 var myStreamID = localStream.getID();

Get Stream Attributes

Stream attributes are defined as part of stream initialization process in the JSON Payload as custom keys in attributes. e.g. 

var StreamOpt = {
    "attributes": {
        "name": "Stream Name",
        "custom_key": "String",
        "custom_key2": Number
     }
}

After stream initialization, use EnxStream.setAttribues() method to redefine or update the stream attributes. You may use EnxStream.getAttributes() method to obtain  all the current keys and their values in the attributes object of stream definition,

Method: EnxStream.getAttributes() – No parameter needed.

Returns: Attributes JSON object of the Stream.

var attrbutes = stream.getAttributes();

Verify availability of Media Tracks in Stream

EnxStream class has number of methods to verify whether the stream has one or more type of media tracks.. The  methods (with no parameters) returning a true/false are listed below:

Methods:

  • EnxStream.ifAudio() – To check if Stream has Audio Track
  • EnxStream.ifVideo() – To check if Stream has Video Track
  • EnxStream.ifData() – To check if Stream has Data Track
  • EnxStream.ifScreen() – To check if Stream has Screen Share 
if (stream.ifVideo()) {
     // The Stream has a Video Track in it
}

// Other methods are also used similar way

Explore Web SDK