Class: Stream

Stream

Stream

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

acceptRemoteCapabilityRequest(contactId, roomName, streamId)

Accept a remote cabality control request for a given user, in a given room for a given stream. Parameters need to be the one extracted from the remoteCapabilityRequest event.

Parameters:
Name Type Description
contactId string

The id of the authorized user, you can get it by calling getId function on the requestor Contact object from the remoteCapabilityRequest event.

roomName string

The roomName concerned, you can find it on the remoteCapabilityRequest event.

streamId string

The stream id, you can find it on the remoteCapabilityRequest event.

Returns:
Type
void

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

applyConstraint(capability, value)

Modifies specified capability to specified value. Changes a single constraint values. This function also work on a remote stream if you asked the authorization before with the function askRemoteCapabilityAuthorization and the user accepted you request.

Parameters:
Name Type Description
capability string

The name of the constraint to modify

value any

The value to set. Type depends on the constraint

Returns:
Type
Promise.<void>

applyConstraints(capabilities)

Resets streams constraints and then applies specified constraints to specified values as webrtc applyConstraints function.

Parameters:
Name Type Description
capabilities StreamCapabilitiesValues

Constraints to modify and their values

Returns:
Type
Promise.<void>

askRemoteCapabilityAuthorization()

This function needs to be used on a remote stream. A request will be sent to the stream publisher to ask his authorization to remotely control his stream capability. The publisher needs to listen the event : remoteCapabilityRequest, and he may accept or refuse with functions : acceptRemoteCapabilityRequest and refuseRemoteCapabilityRequest

Returns:
Type
void

attachToElement(element)

Attaches stream to video DOM element

Parameters:
Name Type Description
element HTMLElement
Returns:
Type
void

blur()

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

Returns:
Type
void

disableAudioAnalysis()

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

Returns:
Type
void

enableAudioAnalysis()

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

Returns:
Type
void

getCapabilities()

Get all capabilities that may be modified for this stream and their accepted value ranges. The result is returned through the streamCapabilities event. This function also work for a remote stream.

Returns:
Type
void

getConstraints()

Get applied constraints on this stream and return them through the streamConstraints event. This function also work for a remote stream.

Returns:
Type
void

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

getSettings()

Get all capabilities for this stream and their actual values. The result is returned through the streamSettings event. This function also work for a remote stream.

Returns:
Type
void

getType()

Returns this stream's type

Returns:

type

Type
String

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

isAudioMuted()

Returns whether the audio track in muted.

Returns:

true if the audio track is muted, false otherwise.

Type
boolean

isScreensharing()

Checks if stream is a screenshare

Returns:
Type
boolean

isVideoMuted()

Returns whether the video track in muted.

Returns:

true if the video track is muted, false otherwise.

Type
boolean

muteAudio()

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()

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>

refuseRemoteCapabilityRequest(contactId, roomName, streamId)

Refuse a remote cabality control request for a given user, in a given room for a given stream. Parameters need to be the one extracted from the remoteCapabilityRequest event.

Parameters:
Name Type Description
contactId string

The id of the user refused, you can get it by calling getId function on the requestor Contact object from the remoteCapabilityRequest event.

roomName string

The roomName concerned, you can find it on the remoteCapabilityRequest event.

streamId string

The stream id, you can find it on the remoteCapabilityRequest event.

Returns:
Type
void

release()

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

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>

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

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 Description
options SnapshotOptions
Returns:

media PNG dataURI in promise

Type
Promise.<string>

unblur()

Stops the blur process if started for this stream.

Returns:
Type
void

unmuteAudio()

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()

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


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


muteStateChange

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


remoteCapabilityRequest

Emitted when a remote capability control request is received

Type: Object
Parameters:
Name Type Description
roomName string

The room name concerned

streamId string

The stream id concerned

requestor Contact

The Contact that has made the request


remoteCapabilityRequestAccepted

Emitted when a remote capability control request has been accepted

Type: Object

remoteCapabilityRequestRefused

Emitted when a remote capability control request has been refused

Type: Object

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).


streamCapabilities

Emitted when calling the function getCapabilities

Type: Object
Properties:
Name Type Argument Description
whiteBalanceMode Array.<string> <optional>

A sequence of supported white balance modes

exposureMode Array.<string> <optional>

A sequence of supported exposure modes

focusMode Array.<string> <optional>

A sequence of supported focus modes

facingMode Array.<string> <optional>

A sequence of supported facing modes that describes the directions that the camera can face, as seen from the user's perspective

resizeMode Array.<string> <optional>

A sequence of resize modes that describes the means by which the resolution can be derived by the UA

width CapbilityRange <optional>

The width or width range, in pixels. As a capability, the range should span the video source's pre-set width values with min being the smallest width and max being the largest width

height CapbilityRange <optional>

The height or height range, in pixels. As a capability, the range should span the video source's pre-set height values with min being the smallest height and max being the largest height

aspectRatio CapbilityRange <optional>

The exact aspect ratio (width in pixels divided by height in pixels, represented as a double rounded to the tenth decimal place) or aspect ratio range

frameRate CapbilityRange <optional>

The exact frame rate (frames per second) or frame rate range

exposureCompensation CapbilityRange <optional>

This reflects the supported range of exposure compensation. The supported range can be, and usually is, centered around 0

colorTemperature CapbilityRange <optional>

This range reflects the supported correlated color temperatures to be used for the scene white balance calculation

iso CapbilityRange <optional>

This reflects the permitted range of ISO values

brightness CapbilityRange <optional>

This reflects the supported range of brightness setting of the camera. Values are numeric. Increasing values indicate increasing brightness

contrast CapbilityRange <optional>

This reflects the supported range of contrast. Values are numeric. Increasing values indicate increasing contrast

saturation CapbilityRange <optional>

This reflects the permitted range of saturation setting. Values are numeric. Increasing values indicate increasing saturation

sharpness CapbilityRange <optional>

This reflects the permitted sharpness range of the camera. Values are numeric. Increasing values indicate increasing sharpness, and the minimum value always implies no sharpness enhancement or processing

focusDistance CapbilityRange <optional>

This reflects the focus distance value range supported by the UA

zoom CapbilityRange <optional>

This reflects the zoom value range supported by the UA

torch boolean <optional>

A boolean indicating whether camera supports torch mode


streamConstraints

Emitted when calling the function getConstraints

Type: Object
Properties:
Name Type Argument Description
whiteBalanceMode string <optional>

Actual whiteBalanceMode value

exposureMode string <optional>

Actual exposureMode value

focusMode string <optional>

Actual focusMode value

facingMode string <optional>

Actual facingMode value

resizeMode string <optional>

Actual resizeMode value

width number <optional>

Actual width value

height number <optional>

Actual height value

aspectRatio number <optional>

Actual aspectRatio value

frameRate number <optional>

Actual frameRate value

exposureCompensation number <optional>

Actual exposureCompensation value

colorTemperature number <optional>

Actual colorTemperature value

iso number <optional>

Actual iso value

brightness number <optional>

Actual brightness value

contrast number <optional>

Actual contrast value

saturation number <optional>

Actual saturation value

sharpness number <optional>

Actual sharpness value

focusDistance number <optional>

Actual focusDistance value

zoom number <optional>

Actual zoom value

torch boolean <optional>

Actual torch value


streamSettings

Emitted when calling the function getSettings

Type: Object
Properties:
Name Type Argument Description
whiteBalanceMode string <optional>

Actual whiteBalanceMode value

exposureMode string <optional>

Actual exposureMode value

focusMode string <optional>

Actual focusMode value

facingMode string <optional>

Actual facingMode value

resizeMode string <optional>

Actual resizeMode value

width number <optional>

Actual width value

height number <optional>

Actual height value

aspectRatio number <optional>

Actual aspectRatio value

frameRate number <optional>

Actual frameRate value

exposureCompensation number <optional>

Actual exposureCompensation value

colorTemperature number <optional>

Actual colorTemperature value

iso number <optional>

Actual iso value

brightness number <optional>

Actual brightness value

contrast number <optional>

Actual contrast value

saturation number <optional>

Actual saturation value

sharpness number <optional>

Actual sharpness value

focusDistance number <optional>

Actual focusDistance value

zoom number <optional>

Actual zoom value

torch boolean <optional>

Actual torch value


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