Class: EnxStream


A Stream carries different type of media. Audio, Video and/or Data. The stream gets transferred towards remote end points through EnableX Media Servers where it’s played and interacted with.

There are essentially 2 types of streams, viz.

  1. Local Stream: A Stream which a Client End Point initiates and transfers over the network.
  2. Remote Stream: A Stream which a Client End Point receives from others over the network.

Note that you need to initialize your Local Stream first before you can publish it into the Room to which you are connected. The EnxStream, Class is defined as a Sub-Class of EnxRtc Class. Therefore, a typical way to initialize a room is as follows:

var stream = EnxRtc.EnxStream({"audio": true, "video": true, "data": true, "attributes": { "name": "MyStreamName" } } );

The following tables covers all Attributes, Methods of the Stream Class and Event Notifications bound to it.

Attributes:

Parameters Description
local Boolean. Whether stream is local or remote one.
room Object. Room Info to which stream is connected.
showing Boolean. Whether the stream is being played.
audio Boolean. If stream has/to have audio track.
video Boolean. If stream has/to have video track.
screen Boolean. If stream has/to have screen share.
videoSize Size of Video in Stream, It is defined as an array with the following format [minWidth, minHeight, maxWidth, maxHeight].
videoFrameRate Frame Rate of Video Stream, defined as [min, max]
desktopStreamId chromeMediaSourceId to be used to share screen.
extensionId extensionId to be used to share screen.
audioMuted Boolean: Audio Mute Status.
videoMuted Boolean: Video Mute Status.
attributes User can add additional information about the stream. Additional attributes can be defined as {"var1": "value","var2": false,"var3" : "value"}


Methods:

Parameters Description
init() To initiate local stream for publishing.
close() Closes the local stream.
ifAudio() To know if the stream has Audio.
ifVideo() To know if the stream has Video.
ifData() To know if the stream has Data.
ifScreen() To know if the stream has Screen Share/
ifMedia() To know if the stream has audio, video or screen share.
muteAudio (Callback) To mute Audio of published stream. Callback can be defined at application level.
muteVideo (Callback) To mute Video of published stream. Callback can be defined at application level.
unmuteAudio (Callback) To unmute Audio of published stream. Callback can be defined at application level.
unmuteVideo (Callback) To unmute Video of published stream. Callback can be defined at application level.
hardMuteAudio (Callback) To mute Audio of subscribed stream. Callback can be defined at application level. Only for moderator use.
hardMuteVideo (Callback) To mute Video of subscribed stream. Callback can be defined at application level. Only for moderator use.
hardUnmuteAudio (Callback) To unmute Audio of subscribed stream. Callback can be defined at application level. Only for moderator use.
hardUnmuteVideo (Callback) To unmute Video of subscribed stream. Callback can be defined at application level. Only for moderator use.
sendData (Message) To send out data (Plain Text, Encoded, Mime-Type) into Stream.
getId() To get stream ID.
getAttributes() To get attributes of stream as JSON.
setAttributes (Attributes) To update / set attributes of a published stream. The JSON structure may contain all stream qualifying data variables, e.g, local, room, showing, url, recording, video, audio, screen, videoSize, videoFrameRate, extensionId, desktopStreamId, audioMuted, videoMuted
updateConfiguration (Attributes, Callback) This method updates the audio and video maximum bandwidth for a publisher.
play (DOM Element ID, View Attributes) To play video in EnableX built audio/video player. The DOM Element ID is to be of a DIV tag.
stop() To stop playing the Audio/Video stream in DOM
getVideoFrameImage() To take a snapshot of video frame and to return an Image in raw format.

Stream Events:

Events Description
media-access-allowed Access granted to Camera, Microphone and/or Screen.
media-access-denied Access to Camera, Microphone and/or Screen is denied.
stream-attributes-updated Stream attributes have been updated.
stream-data-in Text/Encoded data received. It will not work in active talker mode.
active-talker-data-in Text/Encoded data received. This is only for active talker mode.
stream-addedStream added into the room.
stream-endedStream object failed to initiate even after access-accepted.
user-audio-muted Audio is muted on the remote stream.
user-audio-unmuted Audio is unmuted on the remote stream.
user-video-muted Video is muted on the remote stream.
user-video-unmuted Video is unmuted on the remote stream.
hardmute-user-audio Audio is muted on the local stream of participants as requested by moderator to mute.
hardunmute-user-audio Audio is unmuted on the local stream of participants as requested by moderator to unmute.
hardmute-user-video Video is muted on the local stream of participants as requested by moderator to mute.
hardunmute-user-video Video is unmuted on the local stream of participants as requested by moderator to unmute.



Initialize Stream

Method: EnxStream.init()

This method seeks permission to access media devices and if allowed it initializes local stream using the allowed audio and/or video devices. A successfully initiated Stream can only be published into the Room or played locally.

Follow these steps to initialize your local stream:
  • • Call stream.init()
  • • Add Event listener access-accepted to know when user grants access to webcam and/or microphone.
  • • Add Event listener access-denied to know if the user denies access to webcam and/or microphone, which will eventually pass or fail the initialization process.

Parameter: None.
Returns: Nothing
Event Listeners: media-access-allowed, media-access-denied


stream.init(); stream.addEventListener('media-access-allowed', function(event) { console.log("Granted access to webcam and/or microphone "); }); stream.addEventListener('media-access-denied', function(event) { console.log("Denied access to webcam and/or microphone "); });



Close a Stream

Method: EnxStream.close()

This method closes the local stream. If this method is called,

  • • It stops capturing media stream from webcam & microphone,
  • • It stops publishing media into the room if it was already published, and
  • • It stops playing the video in HTML DOM.

Parameter: None.
Returns: Nothing
Event Listeners: None


stream.close();



Play the Stream

Method: EnxStream.play(ElementID, Player-Options)

This method plays the local or remote video/audio stream in a given HTML DOM Element ID. Note the method itself will create related AUDIO / VIDEO Tag within the given HTML ID to play the video.

Parameter: ElementID, Player-Options
Returns: Nothing


stream.play(ElementID, playerOptions); /* playerOptions – JSON ref player-options */



Verify Availability of Media Tracks

Stream class has number of methods to verify whether the stream has one or more type of media tracks in it. All these methods listed below accept no parameter and return true or false:

Method Description
EnxStream.ifAudio() Checks if the Stream has Audio Track.
EnxStream.ifVideo() Checks if the Stream has Video Track.
EnxStream.ifData() Checks if the Stream has Data Track.
EnxStream.ifScreen() If the stream has Screen Share.
stream.ifAudio(); stream.ifVideo(); stream.ifData(); stream.ifScreen();



Mute / Unmute Published Stream

EnxStream class has number of methods to mute or unmute audio and start / stop video track of published stream. All the methods are as listed below:

Method Description
EnxStream.muteAudio(Callback) To stop publishing audio track of a Stream.
EnxStream.muteVideo(Callback) To stop publishing video track of a Stream.
EnxStream.unmuteAudio(Callback) To restart publishing audio track of a Stream.
EnxStream.unmuteVideo(Callback) To restart publishing video track of a Stream.
Callback: User defined callback function with one parameter i.e. result. It returns result=true if the intended action is successful.
Event Listeners: user-audio-muted, user-audio-unmuted, user-video-muted, user-video-unmuted

/*Video Mute*/ stream.muteVideo(function (result) { if (result === 'error') { console.log("There was an error in stopping video"); } else { console.log("Video is stopped"); } }); stream.addEventListener('user-video-muted', function(event) { console.log("Stopped Video ", event.stream.attributes); }); /*Audio Mute*/ stream.muteAudio(function (result) { if (result === 'error') { console.log("There was an error in muting audio"); } else { console.log("Audio is muted"); } }); stream.addEventListener('user-audio-muted', function(event) { console.log("Muted Audio ", event.stream.attributes); });



Hard mute / unmute Subscribed Stream

EnxStream class has number of methods for mute or unmute audio and start / stop video track of published stream. All the methods are as listed below:

Method Description
stream.hardMuteAudio(callback) To stop publishing audio track of a remote stream.
stream.hardMuteVideo(callback) To stop publishing video track of a remote Stream.
stream.hardUnmuteAudio(callback) To start publishing audio track of a remote Stream.
stream.hardUnmuteVideo(callback) To start publishing video track of a remote Stream.
Callback: User defined callback function with one parameter i.e. result. It returns result=true if the intended action is successful.
Event Listeners: hardmute-user-audio, hardunmute-user-audio, hardmute-user-video, hardunmute-user-video
Restriction: This method is not available when Active Talker is enabled

/*Hard Muted Video*/ stream.hardMuteVideo(function (response) { if (response.result === 0) { console.log("hard muted video"); } else { console.log("There was an error stopping video"); } }); stream.addEventListener('hardmuted-user-video', function(event) { console.log("Stopped Video ", event.stream.attributes); /*Hard Muted Audio*/ stream.hardMuteAudio(function (response) { if (response.result === 0) { console.log("hard muted audio"); } else { console.log("There was an error in muting audio"); } }); stream.addEventListener('hardmute-user-audio', function(event) { console.log("Muted Audio ", event.stream.attributes); });



Send Data

Method: EnxStream.sendData(Message) This method sends text data to all. All connected users who have subscribed to your stream will receive the text message with an event stream-data-in.

Parameter: Message (JSON Body given below)
{  	
	"sender": "Sender name",
	"message": "Text message",
	"timestamp": "date/time of message origin in UTC"
}
Returns: Nothing
Event Listeners: stream-data-in, active-talker-data-in
Restriction: "stream-data-in" event is not available when Active Talker is enabled.

stream.sendData(Message); stream.addEventListener("stream-data-in", function(event){ console.log(Message Received: ', evt.msg, 'from stream ', evt.stream.getID()); });
stream.sendData(Message); room.addEventListener("active-talker-data-in", function(event){ console.log(Message Received: ', evt.message.message, 'evt.message.from ', evt.message.timestamp; }); /* event:{message :{from : "", message : "", timestamp : ""} } */



Get Stream Attributes

Method: EnxStream.getAttributes() This method fetches attributes node of stream object.

Parameter: None
Returns: stream.attributes{} JSON

var attributes = stream. getAttributes(); console.log(“Name of stream: “, attributes.name);



Update Stream Attributes

Method: Stream.setAttributes(JSON) This method adds new key or updates existing keys in attributes node of stream object.

Parameter:
JSON { 
	"key1": "value", 
	"key2": "value"
}
Returns: JSON attributes
Event Listeners: stream-attributes-update

var attributes = stream.setAttributes({"name": "NewName", "type": "private"}); /* Whenever anything is updated in stream.attributes in any subscribed stream, you are notified with full stream JSON */ stream.addEventListener("stream-attributes-update", function(event){ console.log(‘Stream Attributes updated: ', event.stream.attributes()); });



Configure Stream

Method: EnxStream.updateConfiguration (Attributes, Callback) This method adds / updates stream configuration parameters like maxVideoBW, maxAudioBW

Parameter: Attributes, Callback
{ 
	"key1": "value", 
	"key2": "value"
}
Returns: None
Restriction: This method is not available when Active Talker is enabled

var attributes = stream.updateConfiguration({"maxVideoBW": 300, "maxAudioBW": 300},function(result) { console.log(result); } );



Get a Frame from video

Method: EnxStream.getVideoFrameImage() This method captures an Image Snapshot from Video. Client end point gets bitmap raw data of a single frame from the video streams. You need to put the raw data into a Canvas DOM Element.

Parameter: None var bitmap; var canvas = document.createElement('canvas'); var context = canvas.getContext('2d'); canvas.id = "MyCanvas"; document.body.appendChild(canvas); /* Keep getting snapshot at set interval */ setInterval(function() { bitmap = stream.getVideoFrameImage(); canvas.width = bitmap.width; canvas.height = bitmap.height; context.putImageData(bitmap, 0, 0); }, 100);