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
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
whosekind
isaudio
, 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 eitherenabled
ordisabled
. 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 arevery-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
isvideo
, 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 aRangeError
).
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 togetParameters()
. 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
, orbalanced
. The default value isbalanced
.
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.
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
.
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