Documentation

Class: Stream

Stream

Stream

new Stream()

Fires:

Extends

Methods

<static> createDisplayMediaStream(displayMediaStreamConstraints, forceExtensionOnChrome)

NEW FUNCTION

Helper function to create a screensharing stream : when possible it will use getDisplayMedia() function
This function is the evolution of createScreensharingStream(), parameters are based on getDisplayMedia()

Parameters:
Name Type Description
displayMediaStreamConstraints Object

displayMediaStreamConstraints as defined in : https://w3c.github.io/mediacapture-screen-share/#displaymediastreamconstraints
For retro compatibility with createScreensharingStream() function, value can also be set as captureSourceType :This enables to choose what the user will be proposed to share between screen, applications, browser tab and audio.
Usage is different depending the browser :
-on Chrome, captureSourceTypevalue value is an array that can be ["screen", "window", "tab", "audio"]. This array is used to restrict what will be proposed to the user
-on Firefox, captureSourceTypevalue value is a string that can be "screen", "window" or "application". This string is used to choose what will be proposed to the user
forceExtensionOnChrome Boolean

This can be used to force the usage of Chrome extension (all getDisplayMedia constraints are not yet implemented and extension usage can still be interesting depending on use cases)
Returns:

Created stream in promise

Type
Promise.<Stream>

<static> createScreensharingStream(captureSourceType)

Helper function to create a screensharing stream : Check also createDisplayMediaStream()
The feature works both on Firefox and Chrome
On Chrome, the ApiRTC screensharing extention needs to be installed beforehand

Parameters:
Name Type Description
captureSourceType Object

This enables to choose what the user will be propose to share between screen, applications, browser tab and audio.
Usage is different depending the browser :
-on Chrome, captureSourceTypevalue value is an array that can be ["screen", "window", "tab", "audio"]. This array is used to restrict what will be proposed to the user
-on Firefox, captureSourceTypevalue value is a string that can be "screen", "window" or "application". This string is used to choose what will be proposed to the user
Returns:

Created stream in promise

Type
Promise.<Stream>

<static> createStreamFromMediaStream(mediaStream)

Helper function to create a new stream using an existing mediaStream

Parameters:
Name Type Description
mediaStream MediaStream

mediaStream to use to create a Stream
Returns:

Created stream in promise

Type
Promise.<Stream>

<static> createStreamFromUserMedia(audioInput, videoInput, constraints, options)

Helper function to create a new stream using user's video & audio sources

Parameters:
Name Type Description
audioInput MediaDevice

audioInput device id, can be null. set to false if audio track is not requested
videoInput MediaDevice

videoInput device id, can be null. set to false if video track is not requested
constraints object

other MediaTrackConstraints that can be specified for stream
options CreateStreamFromUserMediaOptions
Returns:

Created stream in promise

Type
Promise.<Stream>

<static> getAvailableEvents()

Returns available events for this class

Returns:
Type
Array.<string>

<static> getLocalStreams()

Returns local streams list

Returns:

local streams list

Type
Array.<Stream>

<static> getStream(streamId)

Returns local stream with its identifier

Parameters:
Name Type Description
streamId string
Returns:

stream

Type
Stream

activateAIAnnotations()

Activates the AI annotation filter process if options were correctly provided on stream creation.

Returns:
Type
void

activateAILogs( [minLogPeriod])

Activates a log return event on each new annotation information

Parameters:
Name Type Argument Default Description
minLogPeriod number <optional>
 0

the minimal time (in seconds) between two logs
Returns:
Type
void

activateAISnapshots( [minSnapshotPeriod])

Activates a snapshot of frames with AI annotations return event

Parameters:
Name Type Argument Default Description
minSnapshotPeriod number <optional>
 0

the minimal time (in seconds) between two snapshots
Returns:
Type
void

addInDiv(divId, mediaEltId, style, muted)

Add stream to DIV elementz

Parameters:
Name Type Description
divId string

Div Id where to add the stream
mediaEltId string

Id of the media element that will be added in the div
style string

Json string with format {width : "160px", height : "120px"} to define width and height of the media element
muted boolean

Boolean to set if media element is muted or not
Returns:
Type
void

applyAudioProcessor(audioProcessorType)

A promise for applying a stream filter
Possible filters are "none", ”blur” : people background is blurred, people background is replaced by a background image

Parameters:
Name Type Description
audioProcessorType 'none' | 'noiseReduction'

type of filter to be applied . Value can be 'none'||'noiseReduction'
Returns:

Created Stream with applied filter in a promise

Type
Promise.<(Stream|ApplyAudioProcessorError)>

applyConstraints(constraints)

Resets streams constraints and then applies specified constraints to specified values as webrtc applyConstraints function. This function also work on a remote stream.

Parameters:
Name Type Description
constraints MediaStreamConstraints

Object containing constraints to modify and their values to apply
Returns:
Type
Promise.<void>

applyVideoProcessor(videoProcessorType, options)

A promise for applying a stream filter
Possible filters are "none", "blur" : people background is blurred, "backgroundImage" : people background is replaced by a background image

Parameters:
Name Type Description
videoProcessorType 'none' | 'blur' | 'backgroundImage'

type of filter to be applied . Value can be 'none'||'blur'||'backgroundImage'
options VideoProcessorOptions
Returns:

Created Stream with applied filter in a promise

Type
Promise.<(Stream|ApplyVideoProcessorError)>

attachToElement(element)

Attaches stream to video DOM element

Parameters:
Name Type Description
element HTMLElement
Returns:
Type
void

backgroundImage()

Creates a stream which is a clone version of the actual stream with an image in background.

Properties:
Name Type Description
imageUrl string

url of the image to apply in background
Returns:
Type
Promise.<Stream>

blur()

Creates a stream which is a blurred version of the actual stream.

Returns:
Type
Promise.<Stream>

disableAudio(applyRemotely)

Disables this stream's audio
If this stream is published to another contact, the stream will also be disabled on the contact's side
If this stream is subscribed from another contact, disabling the stream will have no impact on the contact's side

Parameters:
Name Type Default Description
applyRemotely boolean false

This can be used on a remote stream. Set to true if disableAudio has to be applied remotely. ie : it will be applied for all conversation participants
Returns:
Type
Promise.<void>

disableAudioAnalysis()

Disables audio analysis of Stream
The Stream#audioAmplitude event will no longer be emitted

Returns:
Type
void

disableVideo(applyRemotely)

Disables this stream's video
If this stream is published to another contact, the stream will also be disabled on the contact's side
If this stream is subscribed from another contact, disabling the stream will have no impact on the contact's side

Parameters:
Name Type Default Description
applyRemotely boolean false

This can be used on a remote stream. Set to true if disableVideo has to be applied remotely. ie : it will be applied for all conversation participants
Returns:
Type
Promise.<void>

enableAudio(applyRemotely)

Enables this stream's audio
If this stream is published to another contact, the stream will also be enabled on the contact's side
If this stream is subscribed from another contact, enabling the stream will have no impact on the contact's side, moreover, it will not enable the stream if it has been disabled by the contact

Parameters:
Name Type Default Description
applyRemotely boolean false

This can be used on a remote stream. Set to true if enableAudio has to be applied remotely. ie : it will be applied for all conversation participants
Returns:
Type
Promise.<void>

enableAudioAnalysis()

Enables audio analysis of Stream
This allows the Stream#audioAmplitude event to be emitted

Returns:
Type
void

enableVideo(applyRemotely)

Enables this stream's video
If this stream is published to another contact, the stream will also be enabled on the contact's side
If this stream is subscribed from another contact, enabling the stream will have no impact on the contact's side, moreover, it will not enable the stream if it has been disabled by the contact

Parameters:
Name Type Default Description
applyRemotely boolean false

This can be used on a remote stream. Set to true if enableVideo has to be applied remotely. ie : it will be applied for all conversation participants
Returns:
Type
Promise.<void>

getAudioFlowStatus()

Returns the audio flow status of this stream (i.e. if you enabled/disabled it or if the track is muted or not)
The flow status returned is corresponding to this stream instance, if this is a subscribed stream do not be confused with the publisher flow status.

Returns:
Type
MediaStreamTrackFlowStatus

getCapabilities()

Get all capabilities that may be modified for this stream and their accepted value ranges. This function also work for a remote stream.

Returns:
Type
Promise.<MediaStreamCapabilities>

getConstraints()

Get applied constraints on this stream. This function also work for a remote stream.

Returns:
Type
Promise.<MediaStreamConstraints>

getContact()

Gets the stream's owner, returns null if the stream is local

Returns:
Type
Contact

getConversations()

Returns conversations the stream is published in

Returns:
Type
Array.<Conversation>

getData()

Gets the stream's MediaStream object, returns null if the stream has no data

Returns:
Type
MediaStream

getId()

Returns stream ID.

Returns:

Stream ID.

Type
string

getLabels()

Returns the labels of device source used for the stream.

Returns:
Type
StreamLabels

getOwner()

Returns the owner of the stream reprensented by this one.

Returns:
Type
UserAgent | Contact

getRemoteAudioFlowStatus()

To use on subscribed streams only
Returns the audio flow status of the stream on publisher side (i.e. if publisher enabled/disabled it or if the track is muted or not)

Returns:
Type
Promise.<MediaStreamTrackFlowStatus>

getRemoteVideoFlowStatus()

To use on subscribed streams only
Returns the video flow status of the stream on publisher side (i.e. if publisher enabled/disabled it or if the track is muted or not)

Returns:
Type
Promise.<MediaStreamTrackFlowStatus>

getSettings()

Get all capabilities for this stream and their actual values. This function also work for a remote stream.

Returns:
Type
Promise.<MediaTrackSettings>

getType()

Returns this stream's type

Returns:

type

Type
string

getVideoFlowStatus()

Returns the video flow status of this stream (i.e. if you enabled/disabled it or if the track is muted or not)
The flow status returned is corresponding to this stream instance, if this is a subscribed stream do not be confused with the publisher flow status.

Returns:
Type
MediaStreamTrackFlowStatus

hasAudio()

Checks if stream has at least one audio track

Returns:
Type
boolean

hasData()

Checks if stream has mediastream tracks or data

Returns:
Type
boolean

hasVideo()

Checks if stream has at least one video track

Returns:
Type
boolean

isAudioEnabled()

Returns whether the audio track is enabled.

Returns:

true if the audio track is enabled, false otherwise.

Type
boolean

isAudioMuted()

Returns whether the audio track is muted.

Returns:

true if the audio track is muted, false otherwise.

Type
boolean

isScreensharing()

Checks if stream is a screenshare

Returns:
Type
boolean

isScreensharingRemoteAccess()

Checks if stream is a screenshare related to a remote access

Returns:
Type
boolean

isVideoEnabled()

Returns whether the audio track is enabled.

Returns:

true if the audio track is enabled, false otherwise.

Type
boolean

isVideoMuted()

Returns whether the video track in muted.

Returns:

true if the video track is muted, false otherwise.

Type
boolean

muteAudio()

Deprecated - Mutes this stream's audio
If this stream is published to another contact, the stream will also be muted on the contact's side
If this stream is subscribed from another contact, muting the stream will have no impact on the contact's side

Returns:
Type
Void

muteVideo()

Deprecated - Mutes this stream's video
If this stream is published to another contact, the stream will also be muted on the contact's side
If this stream is subscribed from another contact, muting the stream will have no impact on the contact's side

Returns:
Type
Void

on(listener)

Adds a listener to a Observable event

Parameters:
Name Type Description
listener function
Inherited From:
Overrides:
Returns:

this instance for chaining

Type
Observable

pauseRecord()

Pause the recording of the stream with a promise

Returns:
Type
Promise.<void>

release(options)

Release all tracks (either video or audio) used by this stream

Parameters:
Name Type Description
options StreamReleaseOptions
Returns:
Type
Void

removeFromDiv(divId, mediaEltId)

Remove stream from DIV element

Parameters:
Name Type Description
divId string

Div Id where to add the stream
mediaEltId string

Id of the media element that will be added in the div
Returns:
Type
void

removeListener(eventType, listener)

Remove existing listener to Observable event

Parameters:
Name Type Description
eventType String
listener function
Inherited From:
Overrides:
Returns:

this instance for chaining

Type
Observable

resumeRecord()

Resume the recording of the stream with a promise

Returns:
Type
Promise.<void>

startNoiseReduction()

Creates a stream with a noise reduction filter applied.

Returns:
Type
Promise.<Stream>

startRecord(options)

Starts the recording of the stream with a promise
The stream is recorded locally
The stream can only have one record process active at a time

Parameters:
Name Type Description
options MediaRecorderOptions
Returns:
Type
Promise.<void>

stopAIAnnotations()

Stops the AI annotation filter process

Returns:
Type
void

stopAILogs()

Stops the AI annotation logs process

Returns:
Type
void

stopAISnapshots()

Stops the AI annotation snapshot process

Returns:
Type
void

stopNoiseReduction()

Stops the noised reduction filter if started for this stream and return the original stream.

stopRecord()

Stops the recording of the stream with a promise

Returns:

Blob of the recorded stream in promise

Type
Promise.<Blob>

takePhoto()

Takes a snapshot of the local stream and returns it as an Image object.

Returns:
Type
Promise.<Image>

takeSnapshot( [options])

Takes a dataURI/png snapshot from stream

Parameters:
Name Type Argument Description
options SnapshotOptions <optional>
Returns:

media PNG dataURI in promise

Type
Promise.<string>

unBackgroundImage()

Stops the background image process if started for this stream and return the original stream.
Can be applied on original Stream or on the backgrounded stream

Returns:
Type
Promise.<Stream>

unblur()

Stops the blur process if started for this stream and return the original stream.
Can be applied on original Stream or on the blurred stream

Returns:
Type
Promise.<Stream>

unmuteAudio()

Deprecated - Unmutes this stream's audio
If this stream is published to another contact, the stream will also be unmuted on the contact's side
If this stream is subscribed from another contact, unmuting the stream will have no impact on the contact's side, moreover, it will not unmute the stream if it has been muted by the contact

Returns:
Type
Void

unmuteVideo()

Deprecated - Unmutes this stream's video
If this stream is published to another contact, the stream will also be unmuted on the contact's side
If this stream is subscribed from another contact, muting the stream will have no impact on the contact's side, moreover, it will not unmute the stream if it has been muted by the contact

Returns:
Type
Void

Events

activeStateChange

Emitted when stream video or audio active state changed

Type: object
Properties:
Name Type Description
streamId number

stream identifier.
callId callId

identifier of related call.
type string

'video' or 'audio'
active boolean

new state

AIELog

Emitted when a log is generated after a new AI annotation

Type: object
Properties:
Name Type Description
log string

log informations

AIESnapshot

Emitted when a snapshot is taken of stream with AI annotation

Type: object
Properties:
Name Type Description
image Image

The snapshot

audioAmplitude

Stream current audio amplitude obtained from audio analysis

Type: number

audioAmplitudeInfo

Stream current audio amplitude & speaking status info obtained from audio analysis

Type: object
Properties:
Name Type Description
amplitude number

amplitude.
isSpeaking boolean

is sound/speaking detected considering threshold

audioFlowStatusChanged

Emitted when either enabled or muted value changed for the audio track of the stream

Type: MediaStreamTrackFlowStatus

backgroundSubstractionStopComputeTime

Emitted when the background substraction process is stopped due to bad filter frame rate

Type: object
Properties:
Name Type Description
streamId number

stream identifier.
userMediaStreamId string

user media stream identifier

backgroundSubstractionStopVisibilityChange

Emitted when a filter is applied on stream and the user hides current navigator tab

Type: object
Properties:
Name Type Description
streamId number

stream identifier.
userMediaStreamId string

user media stream identifier

constraintsChanged

Emitted, on a stream if constraints changed

Type: object

flowStatusChanged

Emitted when either enabled or muted value changed for a track of the stream

Type: MediaStreamTrackFlowStatusWithType

muteStateChange

Deprecated - Emitted when stream video or audio mute state changed

Type: object
Properties:
Name Type Description
streamId number

stream identifier.
userMediaStreamId string

user media stream identifier (optional).
callId string

related call identifier (optional).
type string

'video' or 'audio'
muted boolean

new state

release

Emitted, on a stream release

Type: object

remoteAudioFlowStatusChanged

Emitted, on a stream you subscribed, when either enabled or muted value changed for the audio track by the publisher

Type: MediaStreamTrackFlowStatus

remoteVideoFlowStatusChanged

Emitted, on a stream you subscribed, when either enabled or muted value changed for the video track by the publisher

Type: MediaStreamTrackFlowStatus

stopped

Emitted when user media is released or when related call is terminated.

Type: object
Properties:
Name Type Description
streamId number

stream identifier.
userMediaStreamId string

user media stream identifier (optional).
callId string

related call identifier (optional).

trackStopped

Signals a stream track was stopped (known issue: does not work on Firefox)

Type: object
Properties:
Name Type Description
type string

'video' or 'audio'
id string

track id

videoFlowStatusChanged

Emitted when either enabled or muted value changed for the video track of the stream

Type: MediaStreamTrackFlowStatus