Class: RtpEndpoint

elements.RtpEndpoint()

Endpoint that provides bidirectional content delivery capabilities through the RTP or SRTP protocols.

An RtpEndpoint contains paired sink and source :rom:cls:`MediaPad` for audio and video. This endpoint inherits from BaseRtpEndpoint.

In order to establish RTP/SRTP communications, peers first engage in an SDP Offer/Answer negotiation process, where one of the peers (the offerer) sends an SDP Offer, while the other peer (the answerer) responds with an SDP Answer. This endpoint can work in both roles.

  • As offerer: The negotiation process is initiated by the media server.
    • Kurento generates the SDP Offer through the generateOffer() method. This offer must then be sent to remote peer (the answerer) through the signaling channel.
    • The remote peer process the SDP Offer, and generates an SDP Answer. This answer is then sent back to the media server.
    • Upon receiving the SDP Answer, this endpoint must process it with the processAnswer() method.
  • As answerer: The negotiation process is initiated by the remote peer.
    • The remote peer, acting as offerer, generates an SDP Offer and sends to this endpoint.
    • This endpoint processes the SDP Offer with the processOffer() method. The result of this method will be a string, containing an SDP Answer.
    • The SDP Answer must then be sent back to the offerer, so it can be processed by it.

In case of unidirectional connections (i.e. only one peer is going to send media), the process is simpler, as only the sender needs to process an SDP Offer. On top of the information about media codecs and types, the SDP must contain the IP of the remote peer, and the port where it will be listening. This way, the SDP can be mangled without needing to go through the exchange process, as the receiving peer does not need to process any answer.

Bitrate management

Check the documentation of BaseRtpEndpoint for detailed information about bitrate management.

Constructor

new RtpEndpoint()

Builder for the RtpEndpoint
Source:
Fires:

Extends

Members

(static) constructorParams

Properties:
Name Type Attributes Description
crypto module:elements/complexTypes.SDES <optional>
SDES-type param. If present, this parameter indicates that the communication
mediaPipeline module:core.MediaPipeline the MediaPipeline to which the endpoint belongs
useIpv6 external:Boolean <optional>
This configures the endpoint to use IPv6 instead of IPv4.
Source:

(static) events

Source:

Methods

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

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

getEncoderBitrate(callbackopt) → {external:Promise}

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).
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getEncoderBitrateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMaxAudioRecvBandwidth(callbackopt) → {external:Promise}

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).
Parameters:
Name Type Attributes Description
callback module:core/abstracts.SdpEndpoint~getMaxAudioRecvBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMaxEncoderBitrate(callbackopt) → {external:Promise}

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.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getMaxEncoderBitrateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMaxVideoRecvBandwidth(callbackopt) → {external:Promise}

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).
Parameters:
Name Type Attributes Description
callback module:core/abstracts.SdpEndpoint~getMaxVideoRecvBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMaxVideoSendBandwidth(callbackopt) → {external:Promise}

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

getMinEncoderBitrate(callbackopt) → {external:Promise}

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.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getMinEncoderBitrateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMinVideoRecvBandwidth(callbackopt) → {external:Promise}

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.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.BaseRtpEndpoint~getMinVideoRecvBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMinVideoSendBandwidth(callbackopt) → {external:Promise}

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

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

setEncoderBitrate(encoderBitrate, callbackopt) → {external:Promise}

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).
Parameters:
Name Type Attributes Description
encoderBitrate external:Integer
callback module:core/abstracts.MediaElement~setEncoderBitrateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

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

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

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

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).
Parameters:
Name Type Attributes Description
maxVideoRecvBandwidth external:Integer
callback module:core/abstracts.SdpEndpoint~setMaxVideoRecvBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

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

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

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

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.
Parameters:
Name Type Attributes Description
minVideoRecvBandwidth external:Integer
callback module:core/abstracts.BaseRtpEndpoint~setMinVideoRecvBandwidthCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

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

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

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