Class: WebRtcEndpoint

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.

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.

• CONNECTED
• DISCONNECTED

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

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

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

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

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.

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

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.

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

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

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

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.

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.

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

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

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

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

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

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

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

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

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

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.

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

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.

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

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

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.

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.

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

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

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

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