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 processes the offer, and generates an answer. 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 be a string, containing an SDP answer.
    • 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 ports.
  • 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 with the invocation of the gatherCandidates method. Since the whole Trickle ICE purpose is to speed-up connectivity, candidates are generated asynchronously. Therefore, in order to capture the candidates, the user must subscribe to the event IceCandidateFound. It is important that the event listener is bound before invoking gatherCandidates, otherwise a suitable candidate might be lost, and connection might not be established.

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. order to be notified of state changes, the application can subscribe to events generated by the WebRtcEndpoint. Following is a full list of events generated by WebRtcEndpoint:

  • 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 level stuff, like DTLS handshake, RTCP flow, etc. This implies that, while the component state is CONNECTED, there might be no media flowing between the peers. This makes this event useful only to receive low-level information about connection between peers. Even more, while other events might leave a graceful period of time before firing, this event fires immediately after the state change is detected.
  • 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 a callback function. Each event provides different information, so it is recommended to consult the signature of the event listeners.

Flow control and congestion management is one of the most important features of WebRTC. WebRTC connections start with the lowest bandwidth configured and slowly ramps up to the maximum available bandwidth, or to the higher limit the exploration range in case no bandwidth limitation is detected. Notice that WebRtcEndpoints in Kurento are designed in a way that multiple WebRTC connections fed by the same stream share quality. When a new connection is added, as it requires to start with low bandwidth, it will cause the rest of connections to experience a transient period of degraded quality, until it stabilizes its bitrate. This doesn't apply when transcoding is involved. Transcoders will adjust their output bitrate based in bandwidth requirements, but it won't affect the original stream. If an incoming WebRTC stream needs to be transcoded, for whatever reason, all WebRtcEndpoints fed from transcoder output will share a separate quality than the ones connected directly to the original stream.

Note that the default VideoSendBandwidth range of the endpoint is a VERY conservative one, and leads to a low maximum video quality. Most applications will probably want to increase this to higher values such as 2000 kbps (2 mbps).

Check the extended documentation of these parameters in SdpEndpoint, BaseRtpEndpoint, and RembParams.

  • Input bandwidth: Values used to inform remote peers about the bitrate that can be sent to this endpoint.
    • MinVideoRecvBandwidth: Minimum input bitrate, requested from WebRTC senders with REMB (Default: 30 Kbps).
    • MaxAudioRecvBandwidth and MaxVideoRecvBandwidth: Maximum input bitrate, signaled in SDP Offers to WebRTC and RTP senders (Default: unlimited).
  • Output bandwidth: Values used to control bitrate of the video streams sent to remote peers. It is important to keep in mind that pushed bitrate depends on network and remote peer capabilities. Remote peers can also announce bandwidth limitation in their SDPs (through the b={modifier}:{value} attribute). Kurento will always enforce bitrate limitations specified by the remote peer over internal configurations.
    • MinVideoSendBandwidth: REMB override of minimum bitrate sent to WebRTC receivers (Default: 100 Kbps).
    • MaxVideoSendBandwidth: REMB override of maximum bitrate sent to WebRTC receivers (Default: 500 Kbps).
    • RembParams.rembOnConnect: Initial local REMB bandwidth estimation that gets propagated when a new endpoint is connected.

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 by specifying the maximum number of retransmissions or setting a time limit for retransmissions: the WebRTC stack will handle the acknowledgments and timeouts.

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 the createDataChannel method. The arguments for this method, all of them optional, provide the necessary configuration:

  • 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
recvonly external:Boolean <optional>
 Single direction, receive-only endpoint
sendonly external:Boolean <optional>
 Single direction, send-only endpoint
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.

Being supported means that the WebRtcEndpoint has been created with data channel support, the client also supports data channels, and they have been negotiated in the SDP exchange. Otherwise, the method throws an exception, indicating that the operation is not possible.

Data channels can work in either unreliable mode (analogous to User Datagram Protocol or UDP) or reliable mode (analogous to Transmission Control Protocol or TCP). 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.

If data channels are not supported, this method throws an exception.

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 that this forces unreliable mode, even if ordered has been
maxRetransmits external:Integer <optional>
 maximum number of retransmissions that are attempted in unreliable mode. Note that this forces unreliable mode, even if ordered has been
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 will be added to the SDP processed.

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}

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

getConnectionState(callbackopt) → {external:Promise}

Connection state.
  • 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

getExternalAddress(callbackopt) → {external:Promise}

External IP address of the media server.

Forces all local IPv4 and IPv6 ICE candidates to have the given address. This is really nothing more than a hack, but it's very effective to force a public IP address when one is known in advance for the media server. In doing so, KMS will not need a STUN or TURN server, but remote peers will still be able to contact it.

You can try using this setting if KMS is deployed on a publicly accessible server, without NAT, and with a static public IP address. But if it doesn't work for you, just go back to configuring a STUN or TURN server for ICE.

Only set this parameter if you know what you're doing, and you understand 100% WHY you need it. For the majority of cases, you should just prefer to configure a STUN or TURN server.

externalAddress is a single IPv4 or IPv6 address.

Examples:

  • externalAddress=198.51.100.1
  • externalAddress=2001:0db8:85a3:0000:0000:8a2e:0370:7334
Parameters:
Name Type Attributes Description
callback module:elements.WebRtcEndpoint~getExternalAddressCallback <optional>
Deprecated:
  • Use externalIPv4 and/or externalIPv6 instead.
Source:
Returns:
Type
external:Promise

getExternalIPv4(callbackopt) → {external:Promise}

External IPv4 address of the media server.

Forces all local IPv4 ICE candidates to have the given address. This is really nothing more than a hack, but it's very effective to force a public IP address when one is known in advance for the media server. In doing so, KMS will not need a STUN or TURN server, but remote peers will still be able to contact it.

You can try using this setting if KMS is deployed on a publicly accessible server, without NAT, and with a static public IP address. But if it doesn't work for you, just go back to configuring a STUN or TURN server for ICE.

Only set this parameter if you know what you're doing, and you understand 100% WHY you need it. For the majority of cases, you should just prefer to configure a STUN or TURN server.

externalIPv4 is a single IPv4 address.

Example:

  • externalIPv4=198.51.100.1
Parameters:
Name Type Attributes Description
callback module:elements.WebRtcEndpoint~getExternalIPv4Callback <optional>
Source:
Returns:
Type
external:Promise

getExternalIPv6(callbackopt) → {external:Promise}

External IPv6 address of the media server.

Forces all local IPv6 ICE candidates to have the given address. This is really nothing more than a hack, but it's very effective to force a public IP address when one is known in advance for the media server. In doing so, KMS will not need a STUN or TURN server, but remote peers will still be able to contact it.

You can try using this setting if KMS is deployed on a publicly accessible server, without NAT, and with a static public IP address. But if it doesn't work for you, just go back to configuring a STUN or TURN server for ICE.

Only set this parameter if you know what you're doing, and you understand 100% WHY you need it. For the majority of cases, you should just prefer to configure a STUN or TURN server.

externalIPv6 is a single IPv6 address.

Example:

  • externalIPv6=2001:0db8:85a3:0000:0000:8a2e:0370:7334
Parameters:
Name Type Attributes Description
callback module:elements.WebRtcEndpoint~getExternalIPv6Callback <optional>
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

getIceTcp(callbackopt) → {external:Promise}

Enable ICE-TCP candidate gathering.

This setting enables or disables using TCP for ICE candidate gathering in the underlying libnice library: https://libnice.freedesktop.org/libnice/NiceAgent.html#NiceAgent--ice-tcp

You might want to disable ICE-TCP to potentially speed up ICE gathering by avoiding TCP candidates in scenarios where they are not needed.

iceTcp is either 1 (ON) or 0 (OFF). Default: 1 (ON).

Parameters:
Name Type Attributes Description
callback module:elements.WebRtcEndpoint~getIceTcpCallback <optional>
Source:
Returns:
Type
external:Promise

getMaxAudioRecvBandwidth(callbackopt) → {external:Promise}

Maximum input bitrate, signaled in SDP Offers to WebRTC and RTP senders.

This is used to put a limit on the bitrate that the remote peer will send to this endpoint. The net effect of setting this parameter is that when Kurento generates an SDP Offer, an 'Application Specific' (AS) maximum bandwidth attribute will be added to the SDP media section: b=AS:{value}.

Note: This parameter has to be set before the SDP is generated.

  • Unit: kbps (kilobits per second).
  • Default: 0.
  • 0 = unlimited.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.SdpEndpoint~getMaxAudioRecvBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMaxOuputBitrate(callbackopt) → {external:Promise}

Maximum video bandwidth for transcoding.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getMaxOuputBitrateCallback <optional>
Inherited From:
Deprecated:
  • Deprecated due to a typo. Use module:core/abstracts.MediaElement#maxOutputBitrate instead of this function.
Source:
Returns:
Type
external:Promise

getMaxOutputBitrate(callbackopt) → {external:Promise}

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

getMaxVideoRecvBandwidth(callbackopt) → {external:Promise}

Maximum input bitrate, signaled in SDP Offers to WebRTC and RTP senders.

This is used to put a limit on the bitrate that the remote peer will send to this endpoint. The net effect of setting this parameter is that when Kurento generates an SDP Offer, an 'Application Specific' (AS) maximum bandwidth attribute will be added to the SDP media section: b=AS:{value}.

Note: This parameter has to be set before the SDP is generated.

  • Unit: kbps (kilobits per second).
  • Default: 0.
  • 0 = unlimited.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.SdpEndpoint~getMaxVideoRecvBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMaxVideoSendBandwidth(callbackopt) → {external:Promise}

REMB override of maximum bitrate sent to WebRTC receivers.

With this parameter you can control the maximum video quality that will be sent when reacting to good network conditions. Setting this parameter to a high value permits the video quality to raise when the network conditions get better.

This parameter provides a way to limit the bitrate requested by remote REMB bandwidth estimations: the bitrate sent will be always equal or less than this parameter, even if the remote peer requests higher bitrates.

Note that the default value of 500 kbps is a VERY conservative one, and leads to a low maximum video quality. Most applications will probably want to increase this to higher values such as 2000 kbps (2 mbps).

The REMB congestion control algorithm works by gradually increasing the output video bitrate, until the available bandwidth is fully used or the maximum send bitrate has been reached. This is a slow, progressive change, which starts at 300 kbps by default. You can change the default starting point of REMB estimations, by setting RembParams.rembOnConnect.

  • Unit: kbps (kilobits per second).
  • Default: 500.
  • 0 = unlimited: the video bitrate will grow until all the available network bandwidth is used by the stream.
    Note that this might have a bad effect if more than one stream is running (as all of them would try to raise the video bitrate indefinitely, until the network gets saturated).
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.
  • CONNECTED: There is an RTCP flow.
  • DISCONNECTED: No RTCP packets have been received for at least 5 sec.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.BaseRtpEndpoint~getMediaStateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMinOuputBitrate(callbackopt) → {external:Promise}

Minimum video bandwidth for transcoding.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getMinOuputBitrateCallback <optional>
Inherited From:
Deprecated:
  • Deprecated due to a typo. Use module:core/abstracts.MediaElement#minOutputBitrate instead of this function.
Source:
Returns:
Type
external:Promise

getMinOutputBitrate(callbackopt) → {external:Promise}

Minimum video bitrate for transcoding.
  • Unit: bps (bits per second).
  • Default: 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 input bitrate, requested from WebRTC senders with REMB.

This is used to set a minimum value of local REMB during bandwidth estimation, if supported by the implementing class. The REMB estimation will then be sent to remote peers, requesting them to send at least the indicated video bitrate. It follows that min values will only have effect in remote peers that support this congestion control mechanism, such as Chrome.

  • Unit: kbps (kilobits per second).
  • Default: 0.
  • Note: The absolute minimum REMB value is 30 kbps, even if a lower value is set here.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.BaseRtpEndpoint~getMinVideoRecvBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMinVideoSendBandwidth(callbackopt) → {external:Promise}

REMB override of minimum bitrate sent to WebRTC receivers.

With this parameter you can control the minimum video quality that will be sent when reacting to bad network conditions. Setting this parameter to a low value permits the video quality to drop when the network conditions get worse.

This parameter provides a way to override the bitrate requested by remote REMB bandwidth estimations: the bitrate sent will be always equal or greater than this parameter, even if the remote peer requests even lower bitrates.

Note that if you set this parameter too high (trying to avoid bad video quality altogether), you would be limiting the adaptation ability of the congestion control algorithm, and your stream might be unable to ever recover from adverse network conditions.

  • Unit: kbps (kilobits per second).
  • Default: 100.
  • 0 = unlimited: the video bitrate will drop as needed, even to the lowest possible quality, which might make the video completely blurry and pixelated.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.BaseRtpEndpoint~getMinVideoSendBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMtu(callbackopt) → {external:Promise}

Maximum Transmission Unit (MTU) used for RTP.

This setting affects the maximum size that will be used by RTP payloads. You can change it from the default, if you think that a different value would be beneficial for the typical network settings of your application.

The default value is 1200 Bytes. This is the same as in libwebrtc (from webrtc.org), as used by Firefox or Chrome . You can read more about this value in Why RTP max packet size is 1200 in WebRTC? .

WARNING: Change this value ONLY if you really know what you are doing and you have strong reasons to do so. Do NOT change this parameter just because it seems to work better for some reduced scope tests. The default value is a consensus chosen by people who have deep knowledge about network optimization.

  • Unit: Bytes.
  • Default: 1200.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.BaseRtpEndpoint~getMtuCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getName(callbackopt) → {external:Promise}

This MediaObject's name.

This is just sugar to simplify developers' life debugging, it is not used internally for indexing nor identifying 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

getNetworkInterfaces(callbackopt) → {external:Promise}

Local network interfaces used for ICE gathering.

If you know which network interfaces should be used to perform ICE (for WebRTC connectivity), you can define them here. Doing so has several advantages:

  • The WebRTC ICE gathering process will be much quicker. Normally, it needs gather local candidates for all of the network interfaces, but this step can be made faster if you limit it to only the interface that you know will work.
  • It will ensure that the media server always decides to use the correct network interface. With WebRTC ICE gathering it's possible that, under some circumstances (in systems with virtual network interfaces such as docker0) the ICE process ends up choosing the wrong local IP.

networkInterfaces is a comma-separated list of network interface names.

Examples:

  • networkInterfaces=eth0
  • networkInterfaces=eth0,enp0s25
Parameters:
Name Type Attributes Description
callback module:elements.WebRtcEndpoint~getNetworkInterfacesCallback <optional>
Source:
Returns:
Type
external:Promise

getParent(callbackopt) → {external:Promise}

Parent of this MediaObject.

The parent of a Hub or a MediaElement is its MediaPipeline. A MediaPipeline has no parent, so this property will be null.

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}

STUN server IP address.

The ICE process uses STUN to punch holes through NAT firewalls.

stunServerAddress MUST be an IP address; domain names are NOT supported.

You need to use a well-working STUN server. Use this to check if it works:
https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/
srflx).

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.

When STUN is not enough to open connections through some NAT firewalls, using TURN is the remaining alternative.

Note that TURN is a superset of STUN, so you don't need to configure STUN if you are using TURN.

The provided URL should follow one of these formats:

  • user:password@ipaddress:port
  • user:password@ipaddress:port?transport=[udp|tcp|tls]

ipaddress MUST be an IP address; domain names are NOT supported.
transport is OPTIONAL. Possible values: udp, tcp, tls. Default: udp.

You need to use a well-working TURN server. Use this to check if it works:
https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/
srflx) AND one Relay Candidate (type relay).

Parameters:
Name Type Attributes Description
callback module:elements.WebRtcEndpoint~getTurnUrlCallback <optional>
Source:
Returns:
Type
external:Promise

setExternalAddress(externalAddress, callbackopt) → {external:Promise}

External IP address of the media server.

Forces all local IPv4 and IPv6 ICE candidates to have the given address. This is really nothing more than a hack, but it's very effective to force a public IP address when one is known in advance for the media server. In doing so, KMS will not need a STUN or TURN server, but remote peers will still be able to contact it.

You can try using this setting if KMS is deployed on a publicly accessible server, without NAT, and with a static public IP address. But if it doesn't work for you, just go back to configuring a STUN or TURN server for ICE.

Only set this parameter if you know what you're doing, and you understand 100% WHY you need it. For the majority of cases, you should just prefer to configure a STUN or TURN server.

externalAddress is a single IPv4 or IPv6 address.

Examples:

  • externalAddress=198.51.100.1
  • externalAddress=2001:0db8:85a3:0000:0000:8a2e:0370:7334
Parameters:
Name Type Attributes Description
externalAddress external:String
callback module:elements.WebRtcEndpoint~setExternalAddressCallback <optional>
Deprecated:
  • Use externalIPv4 and/or externalIPv6 instead.
Source:
Returns:
Type
external:Promise

setExternalIPv4(externalIPv4, callbackopt) → {external:Promise}

External IPv4 address of the media server.

Forces all local IPv4 ICE candidates to have the given address. This is really nothing more than a hack, but it's very effective to force a public IP address when one is known in advance for the media server. In doing so, KMS will not need a STUN or TURN server, but remote peers will still be able to contact it.

You can try using this setting if KMS is deployed on a publicly accessible server, without NAT, and with a static public IP address. But if it doesn't work for you, just go back to configuring a STUN or TURN server for ICE.

Only set this parameter if you know what you're doing, and you understand 100% WHY you need it. For the majority of cases, you should just prefer to configure a STUN or TURN server.

externalIPv4 is a single IPv4 address.

Example:

  • externalIPv4=198.51.100.1
Parameters:
Name Type Attributes Description
externalIPv4 external:String
callback module:elements.WebRtcEndpoint~setExternalIPv4Callback <optional>
Source:
Returns:
Type
external:Promise

setExternalIPv6(externalIPv6, callbackopt) → {external:Promise}

External IPv6 address of the media server.

Forces all local IPv6 ICE candidates to have the given address. This is really nothing more than a hack, but it's very effective to force a public IP address when one is known in advance for the media server. In doing so, KMS will not need a STUN or TURN server, but remote peers will still be able to contact it.

You can try using this setting if KMS is deployed on a publicly accessible server, without NAT, and with a static public IP address. But if it doesn't work for you, just go back to configuring a STUN or TURN server for ICE.

Only set this parameter if you know what you're doing, and you understand 100% WHY you need it. For the majority of cases, you should just prefer to configure a STUN or TURN server.

externalIPv6 is a single IPv6 address.

Example:

  • externalIPv6=2001:0db8:85a3:0000:0000:8a2e:0370:7334
Parameters:
Name Type Attributes Description
externalIPv6 external:String
callback module:elements.WebRtcEndpoint~setExternalIPv6Callback <optional>
Source:
Returns:
Type
external:Promise

setIceTcp(iceTcp, callbackopt) → {external:Promise}

Enable ICE-TCP candidate gathering.

This setting enables or disables using TCP for ICE candidate gathering in the underlying libnice library: https://libnice.freedesktop.org/libnice/NiceAgent.html#NiceAgent--ice-tcp

You might want to disable ICE-TCP to potentially speed up ICE gathering by avoiding TCP candidates in scenarios where they are not needed.

iceTcp is either 1 (ON) or 0 (OFF). Default: 1 (ON).

Parameters:
Name Type Attributes Description
iceTcp external:Boolean
callback module:elements.WebRtcEndpoint~setIceTcpCallback <optional>
Source:
Returns:
Type
external:Promise

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

Maximum input bitrate, signaled in SDP Offers to WebRTC and RTP senders.

This is used to put a limit on the bitrate that the remote peer will send to this endpoint. The net effect of setting this parameter is that when Kurento generates an SDP Offer, an 'Application Specific' (AS) maximum bandwidth attribute will be added to the SDP media section: b=AS:{value}.

Note: This parameter has to be set before the SDP is generated.

  • Unit: kbps (kilobits per second).
  • Default: 0.
  • 0 = unlimited.
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}

Maximum video bandwidth for transcoding.
Parameters:
Name Type Attributes Description
maxOuputBitrate external:Integer
callback module:core/abstracts.MediaElement~setMaxOuputBitrateCallback <optional>
Inherited From:
Deprecated:
  • Deprecated due to a typo. Use module:core/abstracts.MediaElement#maxOutputBitrate instead of this function.
Source:
Returns:
Type
external:Promise

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

Maximum video bitrate for transcoding.
  • Unit: bps (bits per second).
  • Default: MAXINT.
  • 0 = unlimited.
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 input bitrate, signaled in SDP Offers to WebRTC and RTP senders.

This is used to put a limit on the bitrate that the remote peer will send to this endpoint. The net effect of setting this parameter is that when Kurento generates an SDP Offer, an 'Application Specific' (AS) maximum bandwidth attribute will be added to the SDP media section: b=AS:{value}.

Note: This parameter has to be set before the SDP is generated.

  • Unit: kbps (kilobits per second).
  • Default: 0.
  • 0 = unlimited.
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}

REMB override of maximum bitrate sent to WebRTC receivers.

With this parameter you can control the maximum video quality that will be sent when reacting to good network conditions. Setting this parameter to a high value permits the video quality to raise when the network conditions get better.

This parameter provides a way to limit the bitrate requested by remote REMB bandwidth estimations: the bitrate sent will be always equal or less than this parameter, even if the remote peer requests higher bitrates.

Note that the default value of 500 kbps is a VERY conservative one, and leads to a low maximum video quality. Most applications will probably want to increase this to higher values such as 2000 kbps (2 mbps).

The REMB congestion control algorithm works by gradually increasing the output video bitrate, until the available bandwidth is fully used or the maximum send bitrate has been reached. This is a slow, progressive change, which starts at 300 kbps by default. You can change the default starting point of REMB estimations, by setting RembParams.rembOnConnect.

  • Unit: kbps (kilobits per second).
  • Default: 500.
  • 0 = unlimited: the video bitrate will grow until all the available network bandwidth is used by the stream.
    Note that this might have a bad effect if more than one stream is running (as all of them would try to raise the video bitrate indefinitely, until the network gets saturated).
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}

Minimum video bandwidth for transcoding.
Parameters:
Name Type Attributes Description
minOuputBitrate external:Integer
callback module:core/abstracts.MediaElement~setMinOuputBitrateCallback <optional>
Inherited From:
Deprecated:
  • Deprecated due to a typo. Use module:core/abstracts.MediaElement#minOutputBitrate instead of this function.
Source:
Returns:
Type
external:Promise

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

Minimum video bitrate for transcoding.
  • Unit: bps (bits per second).
  • Default: 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 input bitrate, requested from WebRTC senders with REMB.

This is used to set a minimum value of local REMB during bandwidth estimation, if supported by the implementing class. The REMB estimation will then be sent to remote peers, requesting them to send at least the indicated video bitrate. It follows that min values will only have effect in remote peers that support this congestion control mechanism, such as Chrome.

  • Unit: kbps (kilobits per second).
  • Default: 0.
  • Note: The absolute minimum REMB value is 30 kbps, even if a lower value is set here.
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}

REMB override of minimum bitrate sent to WebRTC receivers.

With this parameter you can control the minimum video quality that will be sent when reacting to bad network conditions. Setting this parameter to a low value permits the video quality to drop when the network conditions get worse.

This parameter provides a way to override the bitrate requested by remote REMB bandwidth estimations: the bitrate sent will be always equal or greater than this parameter, even if the remote peer requests even lower bitrates.

Note that if you set this parameter too high (trying to avoid bad video quality altogether), you would be limiting the adaptation ability of the congestion control algorithm, and your stream might be unable to ever recover from adverse network conditions.

  • Unit: kbps (kilobits per second).
  • Default: 100.
  • 0 = unlimited: the video bitrate will drop as needed, even to the lowest possible quality, which might make the video completely blurry and pixelated.
Parameters:
Name Type Attributes Description
minVideoSendBandwidth external:Integer
callback module:core/abstracts.BaseRtpEndpoint~setMinVideoSendBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setMtu(mtu, callbackopt) → {external:Promise}

Maximum Transmission Unit (MTU) used for RTP.

This setting affects the maximum size that will be used by RTP payloads. You can change it from the default, if you think that a different value would be beneficial for the typical network settings of your application.

The default value is 1200 Bytes. This is the same as in libwebrtc (from webrtc.org), as used by Firefox or Chrome . You can read more about this value in Why RTP max packet size is 1200 in WebRTC? .

WARNING: Change this value ONLY if you really know what you are doing and you have strong reasons to do so. Do NOT change this parameter just because it seems to work better for some reduced scope tests. The default value is a consensus chosen by people who have deep knowledge about network optimization.

  • Unit: Bytes.
  • Default: 1200.
Parameters:
Name Type Attributes Description
mtu external:Integer
callback module:core/abstracts.BaseRtpEndpoint~setMtuCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

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

This MediaObject's name.

This is just sugar to simplify developers' life debugging, it is not used internally for indexing nor identifying 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

setNetworkInterfaces(networkInterfaces, callbackopt) → {external:Promise}

Local network interfaces used for ICE gathering.

If you know which network interfaces should be used to perform ICE (for WebRTC connectivity), you can define them here. Doing so has several advantages:

  • The WebRTC ICE gathering process will be much quicker. Normally, it needs gather local candidates for all of the network interfaces, but this step can be made faster if you limit it to only the interface that you know will work.
  • It will ensure that the media server always decides to use the correct network interface. With WebRTC ICE gathering it's possible that, under some circumstances (in systems with virtual network interfaces such as docker0) the ICE process ends up choosing the wrong local IP.

networkInterfaces is a comma-separated list of network interface names.

Examples:

  • networkInterfaces=eth0
  • networkInterfaces=eth0,enp0s25
Parameters:
Name Type Attributes Description
networkInterfaces external:String
callback module:elements.WebRtcEndpoint~setNetworkInterfacesCallback <optional>
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}

STUN server IP address.

The ICE process uses STUN to punch holes through NAT firewalls.

stunServerAddress MUST be an IP address; domain names are NOT supported.

You need to use a well-working STUN server. Use this to check if it works:
https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/
srflx).

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.

When STUN is not enough to open connections through some NAT firewalls, using TURN is the remaining alternative.

Note that TURN is a superset of STUN, so you don't need to configure STUN if you are using TURN.

The provided URL should follow one of these formats:

  • user:password@ipaddress:port
  • user:password@ipaddress:port?transport=[udp|tcp|tls]

ipaddress MUST be an IP address; domain names are NOT supported.
transport is OPTIONAL. Possible values: udp, tcp, tls. Default: udp.

You need to use a well-working TURN server. Use this to check if it works:
https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/
srflx) AND one Relay Candidate (type relay).

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:

getExternalAddressCallback(error, result)

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

getExternalIPv4Callback(error, result)

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

getExternalIPv6Callback(error, result)

Parameters:
Name Type Description
error external:Error
result external:String
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:

getIceTcpCallback(error, result)

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

getNetworkInterfacesCallback(error, result)

Parameters:
Name Type Description
error external:Error
result external:String
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:

setExternalAddressCallback(error)

Parameters:
Name Type Description
error external:Error
Source:

setExternalIPv4Callback(error)

Parameters:
Name Type Description
error external:Error
Source:

setExternalIPv6Callback(error)

Parameters:
Name Type Description
error external:Error
Source:

setIceTcpCallback(error)

Parameters:
Name Type Description
error external:Error
Source:

setNetworkInterfacesCallback(error)

Parameters:
Name Type Description
error external:Error
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: