Constructor
new WebRtcEndpoint()
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 | |
qosDscp |
module:elements/complexTypes.DSCPValue |
<optional> |
DSCP value to be used in network traffic sent from this endpoint
If this parameter is present with a value different to NO_VALUE, all traffic sent from this WebRTCEndpoint will be marked with the correspondent DSCP value according to the DiffServ architecture. This may provide better handling of network traffic according to its characteristics associated to its DSCP value. This better handling includes priority in forwarding traffic and probability of packet drop in case of network congestion. It must be taken into account that on Internet not all intermediate routers are guaranteed to enforce those DSCP values, even it is possible that certain routers just block traffic marked with specific DSCP values, as discussed here https://datatracker.ietf.org/doc/html/rfc8835#section-4.2. So, this feature must be managed with care and is mostly intended for private networks, where the network proprietor can configure and guarantee DSCP management in all routers. |
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 |
(static) events
Methods
(static) addIceCandidate(candidate, callbackopt) → {external:Promise}
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
candidate |
module:elements/complexTypes.IceCandidate | Remote ICE candidate | |
callback |
module:elements.WebRtcEndpoint~addIceCandidateCallback |
<optional> |
Returns:
- Type
- external:Promise
(static) closeDataChannel(channelId, callbackopt) → {external:Promise}
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
channelId |
external:Integer | The channel identifier | |
callback |
module:elements.WebRtcEndpoint~closeDataChannelCallback |
<optional> |
Returns:
- Type
- external:Promise
(static) createDataChannel(labelopt, orderedopt, maxPacketLifeTimeopt, maxRetransmitsopt, protocolopt, callbackopt) → {external:Promise}
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> |
Returns:
- Type
- external:Promise
(static) gatherCandidates(callbackopt) → {external:Promise}
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
module:elements.WebRtcEndpoint~gatherCandidatesCallback |
<optional> |
Returns:
- Type
- external:Promise
getChildren(callbackopt) → {external:Promise}
MediaObject
.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
module:core/abstracts.MediaObject~getChildrenCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
getConnectionState(callbackopt) → {external:Promise}
- 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
getEncoderBitrate(callbackopt) → {external:Promise}
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).
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
module:core/abstracts.MediaElement~getEncoderBitrateCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
getExternalIPv4(callbackopt) → {external:Promise}
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> |
Returns:
- Type
- external:Promise
getExternalIPv6(callbackopt) → {external:Promise}
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> |
Returns:
- Type
- external:Promise
getICECandidatePairs(callbackopt) → {external:Promise}
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
module:elements.WebRtcEndpoint~getICECandidatePairsCallback |
<optional> |
Returns:
- Type
- external:Promise
getIceConnectionState(callbackopt) → {external:Promise}
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
module:elements.WebRtcEndpoint~getIceConnectionStateCallback |
<optional> |
Returns:
- Type
- external:Promise
getIceTcp(callbackopt) → {external:Promise}
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> |
Returns:
- Type
- external:Promise
getMaxAudioRecvBandwidth(callbackopt) → {external:Promise}
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).
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
module:core/abstracts.SdpEndpoint~getMaxAudioRecvBandwidthCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
getMaxEncoderBitrate(callbackopt) → {external:Promise}
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
module:core/abstracts.MediaElement~getMaxEncoderBitrateCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
getMaxVideoRecvBandwidth(callbackopt) → {external:Promise}
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).
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
module:core/abstracts.SdpEndpoint~getMaxVideoRecvBandwidthCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
getMaxVideoSendBandwidth(callbackopt) → {external:Promise}
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).
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
module:core/abstracts.BaseRtpEndpoint~getMaxVideoSendBandwidthCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
getMediaPipeline(callbackopt) → {external:Promise}
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}
- 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
getMinEncoderBitrate(callbackopt) → {external:Promise}
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
module:core/abstracts.MediaElement~getMinEncoderBitrateCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
getMinVideoRecvBandwidth(callbackopt) → {external:Promise}
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
module:core/abstracts.BaseRtpEndpoint~getMinVideoRecvBandwidthCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
getMinVideoSendBandwidth(callbackopt) → {external:Promise}
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
module:core/abstracts.BaseRtpEndpoint~getMinVideoSendBandwidthCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
getMtu(callbackopt) → {external:Promise}
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}
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}
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> |
Returns:
- Type
- external:Promise
getParent(callbackopt) → {external:Promise}
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}
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
module:core/abstracts.BaseRtpEndpoint~getRembParamsCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
getSendTagsInEvents(callbackopt) → {external:Promise}
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
module:core/abstracts.MediaObject~getSendTagsInEventsCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
getStunServerAddress(callbackopt) → {external:Promise}
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> |
Returns:
- Type
- external:Promise
getStunServerPort(callbackopt) → {external:Promise}
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
module:elements.WebRtcEndpoint~getStunServerPortCallback |
<optional> |
Returns:
- Type
- external:Promise
getTurnUrl(callbackopt) → {external:Promise}
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> |
Returns:
- Type
- external:Promise
setEncoderBitrate(encoderBitrate, callbackopt) → {external:Promise}
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).
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
encoderBitrate |
external:Integer | ||
callback |
module:core/abstracts.MediaElement~setEncoderBitrateCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
setExternalIPv4(externalIPv4, callbackopt) → {external:Promise}
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> |
Returns:
- Type
- external:Promise
setExternalIPv6(externalIPv6, callbackopt) → {external:Promise}
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> |
Returns:
- Type
- external:Promise
setIceTcp(iceTcp, callbackopt) → {external:Promise}
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> |
Returns:
- Type
- external:Promise
setMaxAudioRecvBandwidth(maxAudioRecvBandwidth, callbackopt) → {external:Promise}
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).
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
maxAudioRecvBandwidth |
external:Integer | ||
callback |
module:core/abstracts.SdpEndpoint~setMaxAudioRecvBandwidthCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
setMaxEncoderBitrate(maxEncoderBitrate, callbackopt) → {external:Promise}
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
maxEncoderBitrate |
external:Integer | ||
callback |
module:core/abstracts.MediaElement~setMaxEncoderBitrateCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
setMaxVideoRecvBandwidth(maxVideoRecvBandwidth, callbackopt) → {external:Promise}
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).
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}
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).
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
maxVideoSendBandwidth |
external:Integer | ||
callback |
module:core/abstracts.BaseRtpEndpoint~setMaxVideoSendBandwidthCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
setMinEncoderBitrate(minEncoderBitrate, callbackopt) → {external:Promise}
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
minEncoderBitrate |
external:Integer | ||
callback |
module:core/abstracts.MediaElement~setMinEncoderBitrateCallback |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- external:Promise
setMinVideoRecvBandwidth(minVideoRecvBandwidth, callbackopt) → {external:Promise}
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.
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}
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.
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}
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}
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}
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> |
Returns:
- Type
- external:Promise
setRembParams(rembParams, callbackopt) → {external:Promise}
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}
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}
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> |
Returns:
- Type
- external:Promise
setStunServerPort(stunServerPort, callbackopt) → {external:Promise}
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
stunServerPort |
external:Integer | ||
callback |
module:elements.WebRtcEndpoint~setStunServerPortCallback |
<optional> |
Returns:
- Type
- external:Promise
setTurnUrl(turnUrl, callbackopt) → {external:Promise}
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> |
Returns:
- Type
- external:Promise
Type Definitions
addIceCandidateCallback(error)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error |
closeDataChannelCallback(error)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error |
createDataChannelCallback(error)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error |
gatherCandidatesCallback(error)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error |
getExternalIPv4Callback(error, result)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error | |
result |
external:String |
getExternalIPv6Callback(error, result)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error | |
result |
external:String |
getICECandidatePairsCallback(error, result)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error | |
result |
module:elements/complexTypes.IceCandidatePair |
getIceConnectionStateCallback(error, result)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error | |
result |
module:elements/complexTypes.IceConnection |
getIceTcpCallback(error, result)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error | |
result |
external:Boolean |
getNetworkInterfacesCallback(error, result)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error | |
result |
external:String |
getStunServerAddressCallback(error, result)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error | |
result |
external:String |
getStunServerPortCallback(error, result)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error | |
result |
external:Integer |
getTurnUrlCallback(error, result)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error | |
result |
external:String |
setExternalIPv4Callback(error)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error |
setExternalIPv6Callback(error)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error |
setIceTcpCallback(error)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error |
setNetworkInterfacesCallback(error)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error |
setStunServerAddressCallback(error)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error |
setStunServerPortCallback(error)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error |
setTurnUrlCallback(error)
Parameters:
Name | Type | Description |
---|---|---|
error |
external:Error |