RTCRtpSender: getParameters() method

The getParameters() method of the RTCRtpSender interface returns an object describing the current configuration for how the sender's track will be encoded and transmitted to a remote RTCRtpReceiver.

Syntax

js
getParameters()

Parameters

None.

Return value

An object indicating the current configuration of the sender.

encodings

An array of objects, each specifying the parameters and settings for a single codec that could be used to encode the track's media. The properties of the objects include:

active

true (the default) if the encoding is being sent, false if it is not being sent or used.

dtx Deprecated Non-standard

Only used for an RTCRtpSender whose kind is audio, this property indicates whether or not discontinuous transmission is being used (a feature by which a phone is turned off or the microphone muted automatically in the absence of voice activity). The value is taken either enabled or disabled.

maxBitrate

A positive integer indicating the maximum number of bits per second that the user agent is allowed to grant to tracks encoded with this encoding. Other parameters may further constrain the bit rate, such as the value of maxFramerate, or the bandwidth available for the transport or physical network.

The value is computed using the standard Transport Independent Application Specific Maximum (TIAS) bandwidth as defined by RFC 3890, section 6.2.2; this is the maximum bandwidth needed without considering protocol overheads from IP, TCP or UDP, and so forth.

Note that the bitrate can be achieved in a number of ways, depending on the media and encoding. For example, for video a low bit rate might be achieved by dropping frames (a bitrate of zero might allow just one frame to be sent), while for audio the track might have to stop playing if the bitrate is too low for it to be sent.

maxFramerate

A value specifying the maximum number of frames per second to allow for this encoding.

priority

A string indicating the priority of the RTCRtpSender, which may determine how the user agent allocates bandwidth between senders. Allowed values are very-low, low (default), medium, high.

rid

A string which, if set, specifies an RTP stream ID (RID) to be sent using the RID header extension. This parameter cannot be modified using setParameters(). Its value can only be set when the transceiver is first created.

scaleResolutionDownBy

Only used for senders whose track's kind is video, this is a floating-point value specifying a factor by which to scale down the video during encoding. The default value, 1.0, means that the video will be encoded at its original size. A value of 2.0 scales the video frames down by a factor of 2 in each dimension, resulting in a video 1/4 the size of the original. The value must not be less than 1.0 (attempting to scale the video to a larger size will throw a RangeError).

transactionId

A string containing a unique ID. This value is used to ensure that setParameters() can only be called to modify the parameters returned by a specific previous call to getParameters(). This parameter cannot be changed by the caller.

codecs

An array of RTCRtpCodecParameters objects describing the set of codecs from which the sender or receiver will choose. This parameter cannot be changed once initially set.

headerExtensions

An array of zero or more RTP header extensions, each identifying an extension supported by the sender or receiver. Header extensions are described in RFC 3550, section 5.3.1. This parameter cannot be changed once initially set.

rtcp

An RTCRtcpParameters object providing the configuration parameters used for RTCP on the sender or receiver. This parameter cannot be changed once initially set.

degradationPreference Deprecated Optional

Specifies the preferred way the WebRTC layer should handle optimizing bandwidth against quality in constrained-bandwidth situations. The possible values are maintain-framerate, maintain-resolution, or balanced. The default value is balanced.

Examples

This example gets the sender's current transaction ID; the transaction ID uniquely identifies the current set of parameters, to ensure that calls to setParameters() are always handled in the correct order, avoiding inadvertently overwriting parameters with older parameters.

js
function getSenderTransactionID(sender) {
  let parameters = sender.getParameters();

  return parameters.transactionId;
}

In the same, way, this code gets the canonical name (CNAME) being used for RTCP on an RTCRtpSender.

js
function getRtpCNAME(sender) {
  let parameters = sender.getParameters();

  return parameters.rtcp.cname;
}

Specifications

Specification
WebRTC: Real-Time Communication in Browsers
# dom-rtcrtpsender-getparameters

Browser compatibility

BCD tables only load in the browser

See also