Class: WebRtcEndpoint

Process an ICE candidate sent by the remote peer of the connection.

Closes an open data channel

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.

Start the ICE candidate gathering.

This method triggers the asynchronous discovery of ICE candidates (as per the Trickle ICE mechanism), and returns immediately. Every newly trickled candidate is reported to the application by means of an IceCandidateFound event. Finally, when all candidates have been gathered, the IceGatheringDone event is emitted.

Normally, you would call this method as soon as possible after calling SdpEndpoint::generateOffer or SdpEndpoint::processOffer, to quickly start discovering candidates and sending them to the remote peer.

You can also call this method before calling generateOffer or processOffer. Doing so will include any already gathered candidates into the resulting SDP. You can leverage this behavior to implement fully traditional ICE (without Trickle): first call gatherCandidates, then only handle the SDP messages after the IceGatheringDone event has been received. This way, you're making sure that all candidates have indeed been gathered, so the resulting SDP will include all of them.

Children of this MediaObject.

Connection state.

• CONNECTED
• DISCONNECTED

MediaObject creation time in seconds since Epoch.

Target video bitrate for media transcoding.

The bitrate of a video has a direct impact on its perceived image quality. Higher bitrate means higher quality, but also a larger amount of bytes to transmit or store. Use this parameter to set the desired average bitrate in videos that are transcoded by the media server.

This parameter is most useful for :rom:cls:`RecorderEndpoint` and :rom:cls:`RtpEndpoint`: when media is being transcoded (either for streaming or storing on disk), the resulting quality is directly controlled with this value.

For :rom:cls:`WebRtcEndpoint`, this value should be left as default, as remote WebRTC receivers will already send feedback to inform the media server about what is the optimal bitrate to send.

Setting a value will only work if done before the media starts to flow.

• Unit: bps (bits per second).
• Default: 300000 (300 kbps).

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

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

the ICE candidate pair (local and remote candidates) used by the ICE library for each stream.

the ICE connection state for all the connections.

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

Maximum inbound bitrate requested by this endpoint. Signaled to compatible WebRTC and RTP senders as part of Kurento's REMB bandwidth estimations, and also as an SDP bitrate attribute (b=AS:{value}, see RFC 8866 Section 5.8. Bandwidth Information) in sendrecv and recvonly SDP Offers.

• Unit: kbps (kilobits per second).
• Default: 0 (unlimited).

Maximum video bitrate for media transcoding.

This parameter can be used to fine tune the automatic bitrate selection that normally takes place within elements that are able to dynamically change the encoding bitrate according to the conditions of the streaming, such as :rom:cls:`WebRtcEndpoint`.

This should be left as default in most cases, given that remote WebRTC receivers already send feedback to inform the media server about what is the optimal bitrate to send. Otherwise, this parameter could be used for example to limit the total bitrate that is handled by the server, by setting a low maximum output for all endpoints.

This should be left as default in most cases, given that remote WebRTC receivers already send feedback to inform the media server about what is the optimal bitrate to send. Otherwise, this parameter could be used for example to limit the total bitrate that is handled by the server, by setting a low maximum output for all endpoints.

Setting a value will only work if done before the media starts to flow.

• Unit: bps (bits per second).
• Default: 0.
• 0 = unlimited. Encoding performed with bitrate as requested by receivers.

Maximum inbound bitrate requested by this endpoint. Signaled to compatible WebRTC and RTP senders as part of Kurento's REMB bandwidth estimations, and also as an SDP bitrate attribute (b=AS:{value}, see RFC 8866 Section 5.8. Bandwidth Information) in sendrecv and recvonly SDP Offers.

• Unit: kbps (kilobits per second).
• Default: 0 (unlimited).

Maximum outbound bitrate sent by this endpoint. Remote peers themselves might also announce a maximum bitrate as part of their REMB bandwidth estimations, and also as an SDP bitrate attribute (b=AS:{value}, see RFC 8866 Section 5.8. Bandwidth Information) in sendrecv and recvonly SDP Offers or Answers. Kurento will always give priority to bitrate limitations specified by remote peers, over internal configurations.

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.

Note that the default MaxVideoSendBandwidth is a VERY conservative value, 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).

MediaPipeline to which this MediaObject belongs. It returns itself when invoked for a pipeline object.

Media flow state.

• CONNECTED: There is an RTCP flow.
• DISCONNECTED: No RTCP packets have been received for at least 5 sec.

Minimum video bitrate for media transcoding.

This parameter can be used to fine tune the automatic bitrate selection that normally takes place within elements that are able to dynamically change the encoding bitrate according to the conditions of the streaming, such as :rom:cls:`WebRtcEndpoint`.

This should be left as default in most cases, given that remote WebRTC receivers already send feedback to inform the media server about what is the optimal bitrate to send. Otherwise, this parameter could be used for example to force a higher bitrate than what is being requested by receivers.

Setting a value will only work if done before the media starts to flow.

• Unit: bps (bits per second).
• Default: 0.

Minimum inbound bitrate requested by this endpoint. Signaled to compatible WebRTC and RTP senders, as part of the REMB bandwidth estimation protocol.

This is used to set a minimum value of local REMB during bandwidth estimation. The REMB estimation will then be sent to remote peers, causing them to send at least the indicated video bitrate. It follows that this parameter will only have effect for remote peers that support the REMB bandwidth estimation protocol (such as e.g. most web browsers compatible with WebRTC).

• Unit: kbps (kilobits per second).
• Default: 0.
• Note: The actual minimum value is 30 kbps, even if a lower value is set.

Minimum outbound bitrate sent by this endpoint.

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.

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 could make the video completely blurry and pixelated, but would adapt better to losses caused by network congestion.

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.

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.

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

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.

Advanced parameters to configure the congestion control algorithm.

Flag activating or deactivating sending the element's tags in fired events.

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

Port of the STUN server

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

Target video bitrate for media transcoding.

The bitrate of a video has a direct impact on its perceived image quality. Higher bitrate means higher quality, but also a larger amount of bytes to transmit or store. Use this parameter to set the desired average bitrate in videos that are transcoded by the media server.

This parameter is most useful for :rom:cls:`RecorderEndpoint` and :rom:cls:`RtpEndpoint`: when media is being transcoded (either for streaming or storing on disk), the resulting quality is directly controlled with this value.

For :rom:cls:`WebRtcEndpoint`, this value should be left as default, as remote WebRTC receivers will already send feedback to inform the media server about what is the optimal bitrate to send.

Setting a value will only work if done before the media starts to flow.

• Unit: bps (bits per second).
• Default: 300000 (300 kbps).

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

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

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

Maximum inbound bitrate requested by this endpoint. Signaled to compatible WebRTC and RTP senders as part of Kurento's REMB bandwidth estimations, and also as an SDP bitrate attribute (b=AS:{value}, see RFC 8866 Section 5.8. Bandwidth Information) in sendrecv and recvonly SDP Offers.

• Unit: kbps (kilobits per second).
• Default: 0 (unlimited).

Maximum video bitrate for media transcoding.

This parameter can be used to fine tune the automatic bitrate selection that normally takes place within elements that are able to dynamically change the encoding bitrate according to the conditions of the streaming, such as :rom:cls:`WebRtcEndpoint`.

This should be left as default in most cases, given that remote WebRTC receivers already send feedback to inform the media server about what is the optimal bitrate to send. Otherwise, this parameter could be used for example to limit the total bitrate that is handled by the server, by setting a low maximum output for all endpoints.

This should be left as default in most cases, given that remote WebRTC receivers already send feedback to inform the media server about what is the optimal bitrate to send. Otherwise, this parameter could be used for example to limit the total bitrate that is handled by the server, by setting a low maximum output for all endpoints.

Setting a value will only work if done before the media starts to flow.

• Unit: bps (bits per second).
• Default: 0.
• 0 = unlimited. Encoding performed with bitrate as requested by receivers.

Maximum inbound bitrate requested by this endpoint. Signaled to compatible WebRTC and RTP senders as part of Kurento's REMB bandwidth estimations, and also as an SDP bitrate attribute (b=AS:{value}, see RFC 8866 Section 5.8. Bandwidth Information) in sendrecv and recvonly SDP Offers.

• Unit: kbps (kilobits per second).
• Default: 0 (unlimited).

Maximum outbound bitrate sent by this endpoint. Remote peers themselves might also announce a maximum bitrate as part of their REMB bandwidth estimations, and also as an SDP bitrate attribute (b=AS:{value}, see RFC 8866 Section 5.8. Bandwidth Information) in sendrecv and recvonly SDP Offers or Answers. Kurento will always give priority to bitrate limitations specified by remote peers, over internal configurations.

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.

Note that the default MaxVideoSendBandwidth is a VERY conservative value, 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).

Minimum video bitrate for media transcoding.

This parameter can be used to fine tune the automatic bitrate selection that normally takes place within elements that are able to dynamically change the encoding bitrate according to the conditions of the streaming, such as :rom:cls:`WebRtcEndpoint`.

This should be left as default in most cases, given that remote WebRTC receivers already send feedback to inform the media server about what is the optimal bitrate to send. Otherwise, this parameter could be used for example to force a higher bitrate than what is being requested by receivers.

Setting a value will only work if done before the media starts to flow.

• Unit: bps (bits per second).
• Default: 0.

Minimum inbound bitrate requested by this endpoint. Signaled to compatible WebRTC and RTP senders, as part of the REMB bandwidth estimation protocol.

This is used to set a minimum value of local REMB during bandwidth estimation. The REMB estimation will then be sent to remote peers, causing them to send at least the indicated video bitrate. It follows that this parameter will only have effect for remote peers that support the REMB bandwidth estimation protocol (such as e.g. most web browsers compatible with WebRTC).

• Unit: kbps (kilobits per second).
• Default: 0.
• Note: The actual minimum value is 30 kbps, even if a lower value is set.

Minimum outbound bitrate sent by this endpoint.

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.

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 could make the video completely blurry and pixelated, but would adapt better to losses caused by network congestion.

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.

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.

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

Advanced parameters to configure the congestion control algorithm.

Flag activating or deactivating sending the element's tags in fired events.

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

Port of the STUN server

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