Class: WebRtcEndpoint

elements.WebRtcEndpoint

Control interface for Kurento WebRTC endpoint.

This endpoint is one side of a peer-to-peer WebRTC communication, being the other peer a WebRTC capable browser -using the RTCPeerConnection API-, a native WebRTC app or even another Kurento Media Server.

In order to establish a WebRTC communication, peers engage in an SDP negotiation process, where one of the peers (the offerer) sends an offer, while the other peer (the offeree) responds with an answer. This endpoint can function in both situations

  • As offerer: The negotiation process is initiated by the media server
    • KMS generates the SDP offer through the generateOffer method. This offer must then be sent to the remote peer (the offeree) through the signaling channel, for processing.
    • The remote peer process the offer, and generates an answer to this offer. The answer is sent back to the media server.
    • Upon receiving the answer, the endpoint must invoke the processAnswer method.
  • As offeree: The negotiation process is initiated by the remote peer
    • The remote peer, acting as offerer, generates an SDP offer and sends it to the WebRTC endpoint in Kurento.
    • The endpoint will process the offer invoking the processOffer method. The result of this method will
    • The SDP answer must be sent back to the offerer, so it can be processed.

SDPs are sent without ICE candidates, following the Trickle ICE optimization. Once the SDP negotiation is completed, both peers proceed with the ICE discovery process, intended to set up a bidirectional media connection. During this process, each peer

  • Discovers ICE candidates for itself, containing pairs of IPs and
  • ICE candidates are sent via the signaling channel as they are discovered, to the remote peer for probing.
  • ICE connectivity checks are run as soon as the new candidate description, from the remote peer, is available.
Once a suitable pair of candidates (one for each peer) is discovered, the media session can start. The harvesting process in Kurento, begins

It's important to keep in mind that WebRTC connection is an asynchronous process, when designing interactions between different MediaElements. For example, it would be pointless to start recording before media is flowing. In order to be notified of state changes, the

  • IceComponentStateChange: This event informs only about changes in the ICE connection state. Possible values are:
    • DISCONNECTED: No activity scheduled
    • GATHERING: Gathering local candidates
    • CONNECTING: Establishing connectivity
    • CONNECTED: At least one working candidate pair
    • READY: ICE concluded, candidate pair selection is now final
    • FAILED: Connectivity checks have been completed, but media connection was not established
    The transitions between states are covered in RFC5245. It could be said that it's network-only, as it only takes into account the state of the network connection, ignoring other higher
  • IceCandidateFound: Raised when a new candidate is discovered. ICE candidates must be sent to the remote peer of the connection. Failing to do so for some or all of the candidates might render the connection unusable.
  • IceGatheringDone: Raised when the ICE harvesting process is completed. This means that all candidates have already been discovered.
  • NewCandidatePairSelected: Raised when a new ICE candidate pair gets selected. The pair contains both local and remote candidates being used for a component. This event can be raised during a media session, if a new pair of candidates with higher priority in the link are found.
  • DataChannelOpen: Raised when a data channel is open.
  • DataChannelClose: Raised when a data channel is closed.

Registering to any of above events requires the application to provide

Flow control and congestion management is one of the most important features of WebRTC. WebRTC connections start with the lowest bandwidth

The default bandwidth range of the endpoint is 100kbps-500kbps, but it

  • Input bandwidth control mechanism: Configuration interval used to inform remote peer the range of bitrates that can be pushed into this WebRtcEndpoint object.
    • setMin/MaxVideoRecvBandwidth: sets Min/Max bitrate limits expected for received video stream.
    • setMin/MaxAudioRecvBandwidth: sets Min/Max bitrate limits expected for received audio stream.
    Max values are announced in the SDP, while min values are set to limit the lower value of REMB packages. It follows that min values
  • Output bandwidth control mechanism: Configuration interval used to
    • setMin/MaxVideoSendBandwidth: sets Min/Max bitrate limits for
All bandwidth control parameters must be changed before the SDP negotiation takes place, and can't be changed afterwards.

DataChannels allow other media elements that make use of the DataPad, to send arbitrary data. For instance, if there is a filter that publishes event information, it'll be sent to the remote peer through the channel. There is no API available for programmers to make use of this feature in the WebRtcElement. DataChannels can be configured to provide the following:

  • Reliable or partially reliable delivery of sent messages
  • In-order or out-of-order delivery of sent messages
Unreliable, out-of-order delivery is equivalent to raw UDP semantics. The message may make it, or it may not, and order is not important. However, the channel can be configured to be partially reliable

The possibility to create DataChannels in a WebRtcEndpoint must be explicitly enabled when creating the endpoint, as this feature is disabled by default. If this is the case, they can be created invoking

  • label: assigns a label to the DataChannel. This can help identify each possible channel separately.
  • ordered: specifies if the DataChannel guarantees order, which is the default mode. If maxPacketLifetime and maxRetransmits have not been set, this enables reliable mode.
  • maxPacketLifeTime: The time window in milliseconds, during which transmissions and retransmissions may take place in unreliable mode. This forces unreliable mode, even if ordered has been activated.
  • maxRetransmits: maximum number of retransmissions that are attempted in unreliable mode. This forces unreliable mode, even if ordered has been activated.
  • Protocol: Name of the subprotocol used for data communication.

Constructor

new WebRtcEndpoint()

Builder for the WebRtcEndpoint
Source:
Fires:

Extends

Members

(static) constructorParams

Properties:
Name Type Attributes Description
certificateKeyType module:elements/complexTypes.CertificateKeyType <optional>
 Define the type of the certificate used in dtls
mediaPipeline module:core.MediaPipeline the MediaPipeline to which the endpoint belongs
useDataChannels external:Boolean <optional>
 Activate data channels support
Source:

(static) events

Source:

Methods

(static) addIceCandidate(candidate, callbackopt) → {external:Promise}

Process an ICE candidate sent by the remote peer of the connection.
Parameters:
Name Type Attributes Description
candidate module:elements/complexTypes.IceCandidate Remote ICE candidate
callback module:elements.WebRtcEndpoint~addIceCandidateCallback <optional>
Source:
Returns:
Type
external:Promise

(static) closeDataChannel(channelId, callbackopt) → {external:Promise}

Closes an open data channel
Parameters:
Name Type Attributes Description
channelId external:Integer The channel identifier
callback module:elements.WebRtcEndpoint~closeDataChannelCallback <optional>
Source:
Returns:
Type
external:Promise

(static) createDataChannel(labelopt, orderedopt, maxPacketLifeTimeopt, maxRetransmitsopt, protocolopt, callbackopt) → {external:Promise}

Create a new data channel, if data channels are supported. If they are not supported, this method throws an exception. Being supported means that the WebRtcEndpoint has been created with Otherwise, the method throws an exception, indicating that the operation is not possible.
Data channels can work in either unreliable mode (analogous to User The two modes have a simple distinction:
  • Reliable mode guarantees the transmission of messages and also the order in which they are delivered. This takes extra overhead, thus potentially making this mode slower.
  • Unreliable mode does not guarantee every message will get to the other side nor what order they get there. This removes the overhead, allowing this mode to work much faster.
Parameters:
Name Type Attributes Description
label external:String <optional>
 Channel's label
ordered external:Boolean <optional>
 If the data channel should guarantee order or not. If true, and maxPacketLifeTime and maxRetransmits have not been provided, reliable mode is activated.
maxPacketLifeTime external:Integer <optional>
 The time window (in milliseconds) during which transmissions and retransmissions may take place in unreliable mode.
Note This forces unreliable mode, even if ordered has been activated
maxRetransmits external:Integer <optional>
 maximum number of retransmissions that are attempted in unreliable mode.
Note This forces unreliable mode, even if ordered has been activated
protocol external:String <optional>
 Name of the subprotocol used for data communication
callback module:elements.WebRtcEndpoint~createDataChannelCallback <optional>
Source:
Returns:
Type
external:Promise

(static) gatherCandidates(callbackopt) → {external:Promise}

Start the gathering of ICE candidates.
It must be called after SdpEndpoint::generateOffer or SdpEndpoint::processOffer for Trickle ICE. If invoked before generating or processing an SDP offer, the candidates gathered
Parameters:
Name Type Attributes Description
callback module:elements.WebRtcEndpoint~gatherCandidatesCallback <optional>
Source:
Returns:
Type
external:Promise

getChildren(callbackopt) → {external:Promise}

children of this MediaObject.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaObject~getChildrenCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getChilds(callbackopt) → {external:Promise}

Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaObject~getChildsCallback <optional>
Inherited From:
Deprecated:
  • (Use children instead) children of this MediaObject.
Source:
Returns:
Type
external:Promise

getConnectionState(callbackopt) → {external:Promise}

Connection state. Possible values are
  • CONNECTED
  • DISCONNECTED
Parameters:
Name Type Attributes Description
callback module:core/abstracts.BaseRtpEndpoint~getConnectionStateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getCreationTime(callbackopt) → {external:Promise}

MediaObject creation time in seconds since Epoch.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaObject~getCreationTimeCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getICECandidatePairs(callbackopt) → {external:Promise}

the ICE candidate pair (local and remote candidates) used by the ice library for each stream.
Parameters:
Name Type Attributes Description
callback module:elements.WebRtcEndpoint~getICECandidatePairsCallback <optional>
Source:
Returns:
Type
external:Promise

getIceConnectionState(callbackopt) → {external:Promise}

the ICE connection state for all the connections.
Parameters:
Name Type Attributes Description
callback module:elements.WebRtcEndpoint~getIceConnectionStateCallback <optional>
Source:
Returns:
Type
external:Promise

getMaxAudioRecvBandwidth(callbackopt) → {external:Promise}

Maximum bandwidth for audio reception, in kbps. The default value is 500. A value of 0 sets this as leaves this unconstrained.
Note This has
Parameters:
Name Type Attributes Description
callback module:core/abstracts.SdpEndpoint~getMaxAudioRecvBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMaxOuputBitrate(callbackopt) → {external:Promise}

Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getMaxOuputBitrateCallback <optional>
Inherited From:
Deprecated:
  • Deprecated due to a typo. Use maxOutputBitrate instead of this function. Maximum video bandwidth for transcoding. 0 = unlimited. Unit: bps(bits per second). Default value: MAXINT
Source:
Returns:
Type
external:Promise

getMaxOutputBitrate(callbackopt) → {external:Promise}

Maximum video bitrate for transcoding. 0 = unlimited. Unit: bps(bits per second). Default value: MAXINT
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getMaxOutputBitrateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMaxVideoRecvBandwidth(callbackopt) → {external:Promise}

Maximum bandwidth for video reception, in kbps. The default value is 500. A value of 0 sets this as unconstrained.
Note This has to be set before the SDP is generated.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.SdpEndpoint~getMaxVideoRecvBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMaxVideoSendBandwidth(callbackopt) → {external:Promise}

Maximum bandwidth for video transmission, in kbps. The default value is 500 kbps. 0 is considered unconstrained.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.BaseRtpEndpoint~getMaxVideoSendBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMediaPipeline(callbackopt) → {external:Promise}

MediaPipeline to which this MediaObject belongs. It returns itself when invoked for a pipeline object.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaObject~getMediaPipelineCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMediaState(callbackopt) → {external:Promise}

Media flow state. Possible values are
  • CONNECTED: There is an RTCP flow.
  • DISCONNECTED: No RTCP packets have been received for at least
Parameters:
Name Type Attributes Description
callback module:core/abstracts.BaseRtpEndpoint~getMediaStateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMinOuputBitrate(callbackopt) → {external:Promise}

Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getMinOuputBitrateCallback <optional>
Inherited From:
Deprecated:
  • Deprecated due to a typo. Use minOutputBitrate instead of this function. Minimum video bandwidth for transcoding. Unit: bps(bits per second). Default value: 0
Source:
Returns:
Type
external:Promise

getMinOutputBitrate(callbackopt) → {external:Promise}

Minimum video bitrate for transcoding. Unit: bps(bits per second). Default value: 0
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getMinOutputBitrateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMinVideoRecvBandwidth(callbackopt) → {external:Promise}

Minimum bandwidth announced for video reception, in kbps. The default value is 100 kbps. 0 is considered unconstrained.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.BaseRtpEndpoint~getMinVideoRecvBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMinVideoSendBandwidth(callbackopt) → {external:Promise}

Minimum bandwidth for video transmission, in kbps. The default value is 100 kbps. 0 is considered unconstrained.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.BaseRtpEndpoint~getMinVideoSendBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getName(callbackopt) → {external:Promise}

this MediaObject's name. This is just a comodity to simplify developers' life debugging, it is not used internally for indexing nor idenfiying the objects. By default, it's the object's ID.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaObject~getNameCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getParent(callbackopt) → {external:Promise}

parent of this MediaObject. The parent of a Hub or a
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaObject~getParentCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getRembParams(callbackopt) → {external:Promise

Advanced parameters to configure the congestion control algorithm.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.BaseRtpEndpoint~getRembParamsCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getSendTagsInEvents(callbackopt) → {external:Promise}

flag activating or deactivating sending the element's tags in fired events.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaObject~getSendTagsInEventsCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getStunServerAddress(callbackopt) → {external:Promise}

address of the STUN server (Only IP address are supported)
Parameters:
Name Type Attributes Description
callback module:elements.WebRtcEndpoint~getStunServerAddressCallback <optional>
Source:
Returns:
Type
external:Promise

getStunServerPort(callbackopt) → {external:Promise}

port of the STUN server
Parameters:
Name Type Attributes Description
callback module:elements.WebRtcEndpoint~getStunServerPortCallback <optional>
Source:
Returns:
Type
external:Promise

getTurnUrl(callbackopt) → {external:Promise}

TURN server URL with this format: user:password@address:port(?transport=[udp|tcp|tls]).
address
Parameters:
Name Type Attributes Description
callback module:elements.WebRtcEndpoint~getTurnUrlCallback <optional>
Source:
Returns:
Type
external:Promise

setMaxAudioRecvBandwidth(maxAudioRecvBandwidth, callbackopt) → {external:Promise}

Maximum bandwidth for audio reception, in kbps. The default value is 500. A value of 0 sets this as leaves this unconstrained.
Note This has
Parameters:
Name Type Attributes Description
maxAudioRecvBandwidth external:Integer
callback module:core/abstracts.SdpEndpoint~setMaxAudioRecvBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setMaxOuputBitrate(maxOuputBitrate, callbackopt) → {external:Promise}

Parameters:
Name Type Attributes Description
maxOuputBitrate external:Integer
callback module:core/abstracts.MediaElement~setMaxOuputBitrateCallback <optional>
Inherited From:
Deprecated:
  • Deprecated due to a typo. Use maxOutputBitrate instead of this function. Maximum video bandwidth for transcoding. 0 = unlimited. Unit: bps(bits per second). Default value: MAXINT
Source:
Returns:
Type
external:Promise

setMaxOutputBitrate(maxOutputBitrate, callbackopt) → {external:Promise}

Maximum video bitrate for transcoding. 0 = unlimited. Unit: bps(bits per second). Default value: MAXINT
Parameters:
Name Type Attributes Description
maxOutputBitrate external:Integer
callback module:core/abstracts.MediaElement~setMaxOutputBitrateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setMaxVideoRecvBandwidth(maxVideoRecvBandwidth, callbackopt) → {external:Promise}

Maximum bandwidth for video reception, in kbps. The default value is 500. A value of 0 sets this as unconstrained.
Note This has to be set before the SDP is generated.
Parameters:
Name Type Attributes Description
maxVideoRecvBandwidth external:Integer
callback module:core/abstracts.SdpEndpoint~setMaxVideoRecvBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setMaxVideoSendBandwidth(maxVideoSendBandwidth, callbackopt) → {external:Promise}

Maximum bandwidth for video transmission, in kbps. The default value is 500 kbps. 0 is considered unconstrained.
Parameters:
Name Type Attributes Description
maxVideoSendBandwidth external:Integer
callback module:core/abstracts.BaseRtpEndpoint~setMaxVideoSendBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setMinOuputBitrate(minOuputBitrate, callbackopt) → {external:Promise}

Parameters:
Name Type Attributes Description
minOuputBitrate external:Integer
callback module:core/abstracts.MediaElement~setMinOuputBitrateCallback <optional>
Inherited From:
Deprecated:
  • Deprecated due to a typo. Use minOutputBitrate instead of this function. Minimum video bandwidth for transcoding. Unit: bps(bits per second). Default value: 0
Source:
Returns:
Type
external:Promise

setMinOutputBitrate(minOutputBitrate, callbackopt) → {external:Promise}

Minimum video bitrate for transcoding. Unit: bps(bits per second). Default value: 0
Parameters:
Name Type Attributes Description
minOutputBitrate external:Integer
callback module:core/abstracts.MediaElement~setMinOutputBitrateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setMinVideoRecvBandwidth(minVideoRecvBandwidth, callbackopt) → {external:Promise}

Minimum bandwidth announced for video reception, in kbps. The default value is 100 kbps. 0 is considered unconstrained.
Parameters:
Name Type Attributes Description
minVideoRecvBandwidth external:Integer
callback module:core/abstracts.BaseRtpEndpoint~setMinVideoRecvBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setMinVideoSendBandwidth(minVideoSendBandwidth, callbackopt) → {external:Promise}

Minimum bandwidth for video transmission, in kbps. The default value is 100 kbps. 0 is considered unconstrained.
Parameters:
Name Type Attributes Description
minVideoSendBandwidth external:Integer
callback module:core/abstracts.BaseRtpEndpoint~setMinVideoSendBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setName(name, callbackopt) → {external:Promise}

this MediaObject's name. This is just a comodity to simplify developers' life debugging, it is not used internally for indexing nor idenfiying the objects. By default, it's the object's ID.
Parameters:
Name Type Attributes Description
name external:String
callback module:core/abstracts.MediaObject~setNameCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setRembParams(rembParams, callbackopt) → {external:Promise}

Advanced parameters to configure the congestion control algorithm.
Parameters:
Name Type Attributes Description
rembParams module:core/complexTypes.RembParams
callback module:core/abstracts.BaseRtpEndpoint~setRembParamsCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setSendTagsInEvents(sendTagsInEvents, callbackopt) → {external:Promise}

flag activating or deactivating sending the element's tags in fired events.
Parameters:
Name Type Attributes Description
sendTagsInEvents external:Boolean
callback module:core/abstracts.MediaObject~setSendTagsInEventsCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setStunServerAddress(stunServerAddress, callbackopt) → {external:Promise}

address of the STUN server (Only IP address are supported)
Parameters:
Name Type Attributes Description
stunServerAddress external:String
callback module:elements.WebRtcEndpoint~setStunServerAddressCallback <optional>
Source:
Returns:
Type
external:Promise

setStunServerPort(stunServerPort, callbackopt) → {external:Promise}

port of the STUN server
Parameters:
Name Type Attributes Description
stunServerPort external:Integer
callback module:elements.WebRtcEndpoint~setStunServerPortCallback <optional>
Source:
Returns:
Type
external:Promise

setTurnUrl(turnUrl, callbackopt) → {external:Promise}

TURN server URL with this format: user:password@address:port(?transport=[udp|tcp|tls]).
address
Parameters:
Name Type Attributes Description
turnUrl external:String
callback module:elements.WebRtcEndpoint~setTurnUrlCallback <optional>
Source:
Returns:
Type
external:Promise

Type Definitions

addIceCandidateCallback(error)

Parameters:
Name Type Description
error external:Error
Source:

closeDataChannelCallback(error)

Parameters:
Name Type Description
error external:Error
Source:

createDataChannelCallback(error)

Parameters:
Name Type Description
error external:Error
Source:

gatherCandidatesCallback(error)

Parameters:
Name Type Description
error external:Error
Source:

getICECandidatePairsCallback(error, result)

Parameters:
Name Type Description
error external:Error
result module:elements/complexTypes.IceCandidatePair
Source:

getIceConnectionStateCallback(error, result)

Parameters:
Name Type Description
error external:Error
result module:elements/complexTypes.IceConnection
Source:

getStunServerAddressCallback(error, result)

Parameters:
Name Type Description
error external:Error
result external:String
Source:

getStunServerPortCallback(error, result)

Parameters:
Name Type Description
error external:Error
result external:Integer
Source:

getTurnUrlCallback(error, result)

Parameters:
Name Type Description
error external:Error
result external:String
Source:

setStunServerAddressCallback(error)

Parameters:
Name Type Description
error external:Error
Source:

setStunServerPortCallback(error)

Parameters:
Name Type Description
error external:Error
Source:

setTurnUrlCallback(error)

Parameters:
Name Type Description
error external:Error
Source: