5.2 RTCRtpSender Interface

The RTCRtpSender interface allows an application to control how a given MediaStreamTrack is encoded and transmitted to a remote peer. When setParameters is called on an RTCRtpSender object, the encoding is changed appropriately.

To create an RTCRtpSender with a MediaStreamTrack, track, a string, kind, a list of MediaStream objects, streams, and optionally a list of RTCRtpEncodingParameters objects, sendEncodings, run the following steps:

1. Let sender be a new RTCRtpSender object.

2. Let sender have a [[SenderTrack]] internal slot initialized to track.

3. Let sender have a [[SenderTransport]] internal slot initialized to null.

4. Let sender have a [[LastStableStateSenderTransport]] internal slot initialized to null.

5. Let sender have a [[Dtmf]] internal slot initialized to null.

6. If kind is "audio" then create an RTCDTMFSender dtmf and set the [[Dtmf]] internal slot to dtmf.

7. Let sender have an [[AssociatedMediaStreamIds]] internal slot, representing a list of Ids of MediaStream objects that this sender is to be associated with. The [[AssociatedMediaStreamIds]] slot is used when sender is represented in SDP as described in [RFC8829] (section 5.2.1.).

8. Set sender.[[AssociatedMediaStreamIds]] to an empty set.

9. For each stream in streams, add stream.id to [[AssociatedMediaStreamIds]] if it’s not already there.

10. Let sender have a [[SendEncodings]] internal slot, representing a list of RTCRtpEncodingParameters dictionaries.

11. If sendEncodings is given as input to this algorithm, and is non-empty, set the [[SendEncodings]] slot to sendEncodings. Otherwise, set it to a list containing a single RTCRtpEncodingParameters with active set to true.

12. Let sender have a [[SendCodecs]] internal slot, representing a list of RTCRtpCodecParameters dictionaries, and initialized to an empty list.

13. Let sender have a [[LastReturnedParameters]] internal slot, which will be used to match getParameters and setParameters transactions.

14. Return sender.

WebIDL[Exposed=Window]
interface RTCRtpSender {
  readonly attribute MediaStreamTrack? track;
  readonly attribute RTCDtlsTransport? transport;
  static RTCRtpCapabilities? getCapabilities(DOMString kind);
  Promise<undefined> setParameters(RTCRtpSendParameters parameters);
  RTCRtpSendParameters getParameters();
  Promise<undefined> replaceTrack(MediaStreamTrack? withTrack);
  undefined setStreams(MediaStream... streams);
  Promise<RTCStatsReport> getStats();
};

Attributes

track of type MediaStreamTrack, readonly, nullable

The track attribute is the track that is associated with this RTCRtpSender object. If track is ended, or if the track’s output is disabled, i.e. the track is disabled and/or muted, the RTCRtpSender MUST send black frames (video) and MUST NOT send (audio). In the case of video, the RTCRtpSender SHOULD send one black frame per second. If track is null then the RTCRtpSender does not send. On getting, the attribute MUST return the value of the [[SenderTrack]] slot.

transport of type RTCDtlsTransport, readonly, nullable

The transport attribute is the transport over which media from track is sent in the form of RTP packets. Prior to construction of the RTCDtlsTransport object, the transport attribute will be null. When bundling is used, multiple RTCRtpSender objects will share one transport and will all send RTP and RTCP over the same transport.

On getting, the attribute MUST return the value of the [[SenderTransport]] slot.

Methods

getCapabilities, static

The getCapabilities() method returns the most optimistic view of the capabilities of the system for sending media of the given kind. It does not reserve any resources, ports, or other state but is meant to provide a way to discover the types of capabilities of the browser including which codecs may be supported. User agents MUST support kind values of "audio" and "video". If the system has no capabilities corresponding to the value of the kind argument, getCapabilities returns null.

These capabilities provide generally persistent cross-origin information on the device and thus increases the fingerprinting surface of the application. In privacy-sensitive contexts, browsers can consider mitigations such as reporting only a common subset of the capabilities.

Note

The codec capabilities returned affect the setCodecPreferences() algorithm and what inputs it throws InvalidModificationError on, and should also be consistent with information revealed by createOffer() and createAnswer() about codecs negotiated for sending, to ensure any privacy mitigations are effective.

setParameters

The setParameters method updates how track is encoded and transmitted to a remote peer.

When the setParameters method is called, the user agent MUST run the following steps:

1. Let parameters be the method’s first argument.
2. Let sender be the RTCRtpSender object on which setParameters is invoked.
3. Let transceiver be the RTCRtpTransceiver object associated with sender (i.e. sender is transceiver.[[Sender]]).
4. If transceiver.[[Stopped]] is true, return a promise rejected with a newly created InvalidStateError.
5. If sender.[[LastReturnedParameters]] is null, return a promise rejected with a newly created InvalidStateError.

6. Validate parameters by running the following steps:

   1. Let encodings be parameters.encodings.
   2. Let codecs be parameters.codecs.
   3. Let N be the number of RTCRtpEncodingParameters stored in sender.[[SendEncodings]].
   4. If any of the following conditions are met, return a promise rejected with a newly created InvalidModificationError:
      1. encodings.length is different from N.
      2. encodings has been re-ordered.
      3. Any parameter in parameters is marked as a Read-only parameter (such as RID) and has a value that is different from the corresponding parameter value in sender.[[LastReturnedParameters]]. Note that this also applies to transactionId.
   5. Verify that each encoding in encodings has a scaleResolutionDownBy member whose value is greater than or equal to 1.0. If one of the scaleResolutionDownBy values does not meet this requirement, return a promise rejected with a newly created RangeError.

7. Let p be a new promise.

8. In parallel, configure the media stack to use parameters to transmit sender.[[SenderTrack]].
   1. If the media stack is successfully configured with parameters, queue a task to run the following steps:
      1. Set sender.[[LastReturnedParameters]] to null.
      2. Set sender.[[SendEncodings]] to parameters.encodings.
      3. Resolve p with undefined.
   2. If any error occurred while configuring the media stack, queue a task to run the following steps:
      1. If an error occurred due to hardware resources not being available, reject p with a newly created RTCError whose errorDetail is set to “hardware-encoder-not-available“ and abort these steps.
      2. If an error occurred due to a hardware encoder not supporting parameters, reject p with a newly created RTCError whose errorDetail is set to “hardware-encoder-error“ and abort these steps.
      3. For all other errors, reject p with a newly created OperationError.
9. Return p.

setParameters does not cause SDP renegotiation and can only be used to change what the media stack is sending or receiving within the envelope negotiated by Offer/Answer. The attributes in the RTCRtpSendParameters dictionary are designed to not enable this, so attributes like cname that cannot be changed are read-only. Other things, like bitrate, are controlled using limits such as maxBitrate, where the user agent needs to ensure it does not exceed the maximum bitrate specified by maxBitrate, while at the same time making sure it satisfies constraints on bitrate specified in other places such as the SDP.

getParameters

The getParameters() method returns the RTCRtpSender object’s current parameters for how track is encoded and transmitted to a remote RTCRtpReceiver.

When getParameters is called, the user agent MUST run the following steps:

1. Let sender be the RTCRtpSender object on which the getter was invoked.

2. If sender.[[LastReturnedParameters]] is not null, return sender.[[LastReturnedParameters]], and abort these steps.

3. Let result be a new RTCRtpSendParameters dictionary constructed as follows:

   • transactionId is set to a new unique identifier.
   • encodings is set to the value of the [[SendEncodings]] internal slot.
   • The headerExtensions sequence is populated based on the header extensions that have been negotiated for sending.
   • codecs is set to the value of the [[SendCodecs]] internal slot.
   • rtcp.cname is set to the CNAME of the associated RTCPeerConnection. rtcp.reducedSize is set to true if reduced-size RTCP has been negotiated for sending, and false otherwise.

4. Set sender.[[LastReturnedParameters]] to result.

5. Queue a task that sets sender.[[LastReturnedParameters]] to null.

6. Return result.

getParameters may be used with setParameters to change the parameters in the following way:

Example 2

async function updateParameters() {
  try {
    const params = sender.getParameters();
    // ... make changes to parameters
    params.encodings[0].active = false;
    await sender.setParameters(params);
  } catch (err) {
    console.error(err);
  }
}

After a completed call to setParameters, subsequent calls to getParameters will return the modified set of parameters.

replaceTrack

Attempts to replace the RTCRtpSender‘s current track with another track provided (or with a null track), without renegotiation.

When the replaceTrack method is invoked, the user agent MUST run the following steps:

1. Let sender be the RTCRtpSender object on which replaceTrack is invoked.

2. Let transceiver be the RTCRtpTransceiver object associated with sender.

3. Let connection be the RTCPeerConnection object associated with sender.

4. Let withTrack be the argument to this method.

5. If withTrack is non-null and withTrack.kind differs from the transceiver kind of transceiver, return a promise rejected with a newly created TypeError.

6. Return the result of chaining the following steps to connection’s operations chain:

   1. If transceiver.[[Stopped]] is true, return a promise rejected with a newly created InvalidStateError.

   2. Let p be a new promise.

   3. Let sending be true if transceiver.[[CurrentDirection]] is “sendrecv“ or “sendonly“, and false otherwise.

   4. Run the following steps in parallel:

      1. If sending is true, and withTrack is null, have the sender stop sending.

      2. If sending is true, and withTrack is not null, determine if withTrack can be sent immediately by the sender without violating the sender’s already-negotiated envelope, and if it cannot, then reject p with a newly created InvalidModificationError, and abort these steps.

      3. If sending is true, and withTrack is not null, have the sender switch seamlessly to transmitting withTrack instead of the sender’s existing track.

      4. Queue a task that runs the following steps:

         1. If connection.[[IsClosed]] is true, abort these steps.

         2. Set sender.[[SenderTrack]] to withTrack.

         3. Resolve p with undefined.

   5. Return p.

Note

Changing dimensions and/or frame rates might not require negotiation. Cases that may require negotiation include:

1. Changing a resolution to a value outside of the negotiated imageattr bounds, as described in [RFC6236].
2. Changing a frame rate to a value that causes the block rate for the codec to be exceeded.
3. A video track differing in raw vs. pre-encoded format.
4. An audio track having a different number of channels.
5. Sources that also encode (typically hardware encoders) might be unable to produce the negotiated codec; similarly, software sources might not implement the codec that was negotiated for an encoding source.

setStreams

Sets the MediaStreams to be associated with this sender’s track.

When the setStreams method is invoked, the user agent MUST run the following steps:

1. Let sender be the RTCRtpSender object on which this method was invoked.

2. Let connection be the RTCPeerConnection object on which this method was invoked.

3. If connection.[[IsClosed]] is true, throw an InvalidStateError.

4. Let streams be a list of MediaStream objects constructed from the method’s arguments, or an empty list if the method was called without arguments.

5. Set sender.[[AssociatedMediaStreamIds]] to an empty set.

6. For each stream in streams, add stream.id to [[AssociatedMediaStreamIds]] if it’s not already there.

7. Update the negotiation-needed flag for connection.

getStats

Gathers stats for this sender only and reports the result asynchronously.

When the getStats() method is invoked, the user agent MUST run the following steps:

1. Let selector be the RTCRtpSender object on which the method was invoked.

2. Let p be a new promise, and run the following steps in parallel:

   1. Gather the stats indicated by selector according to the stats selection algorithm.

   2. Resolve p with the resulting RTCStatsReport object, containing the gathered stats.

3. Return p.

5.2.1 RTCRtpParameters Dictionary

WebIDLdictionary RTCRtpParameters {
  required sequence<RTCRtpHeaderExtensionParameters> headerExtensions;
  required RTCRtcpParameters rtcp;
  required sequence<RTCRtpCodecParameters> codecs;
};

Dictionary RTCRtpParameters Members

headerExtensions of type sequence<RTCRtpHeaderExtensionParameters>, required

A sequence containing parameters for RTP header extensions. Read-only parameter.

rtcp of type RTCRtcpParameters, required

Parameters used for RTCP. Read-only parameter.

codecs of type sequence<RTCRtpCodecParameters>, required

A sequence containing the media codecs that an RTCRtpSender will choose from, as well as entries for RTX, RED and FEC mechanisms. Corresponding to each media codec where retransmission via RTX is enabled, there will be an entry in codecs with a mimeType attribute indicating retransmission via audio/rtx or video/rtx, and an sdpFmtpLine attribute (providing the “apt” and “rtx-time” parameters). Read-only parameter.

5.2.2 RTCRtpSendParameters Dictionary

WebIDL            dictionary RTCRtpSendParameters : RTCRtpParameters {
  required DOMString transactionId;
  required sequence<RTCRtpEncodingParameters> encodings;
};

Dictionary RTCRtpSendParameters Members

transactionId of type DOMString, required

A unique identifier for the last set of parameters applied. Ensures that setParameters can only be called based on a previous getParameters, and that there are no intervening changes. Read-only parameter.

encodings of type sequence<RTCRtpEncodingParameters>, required

A sequence containing parameters for RTP encodings of media.

5.2.3 RTCRtpReceiveParameters Dictionary

WebIDL            dictionary RTCRtpReceiveParameters : RTCRtpParameters {
};

5.2.4 RTCRtpCodingParameters Dictionary

WebIDLdictionary RTCRtpCodingParameters {
  DOMString rid;
};

Dictionary RTCRtpCodingParameters Members

rid of type DOMString

If set, this RTP encoding will be sent with the RID header extension as defined by [RFC8829] (section 5.2.1.). The RID is not modifiable via setParameters. It can only be set or modified in addTransceiver on the sending side. Read-only parameter.

5.2.5 RTCRtpDecodingParameters Dictionary

WebIDLdictionary RTCRtpDecodingParameters : RTCRtpCodingParameters {};

5.2.6 RTCRtpEncodingParameters Dictionary

WebIDL            dictionary RTCRtpEncodingParameters : RTCRtpCodingParameters {
  boolean active = true;
  unsigned long maxBitrate;
  double scaleResolutionDownBy;
};

Dictionary RTCRtpEncodingParameters Members

active of type boolean, defaulting to true

Indicates that this encoding is actively being sent. Setting it to false causes this encoding to no longer be sent. Setting it to true causes this encoding to be sent. Since setting the value to false does not cause the SSRC to be removed, an RTCP BYE is not sent.

maxBitrate of type unsigned long

When present, indicates the maximum bitrate that can be used to send this encoding. The user agent is free to allocate bandwidth between the encodings, as long as the maxBitrate value is not exceeded. The encoding may also be further constrained by other limits (such as per-transport or per-session bandwidth limits) below the maximum specified here. maxBitrate is computed the same way as the Transport Independent Application Specific Maximum (TIAS) bandwidth defined in [RFC3890] Section 6.2.2, which is the maximum bandwidth needed without counting IP or other transport layers like TCP or UDP. The unit of maxBitrate is bits per second.

Note

How the bitrate is achieved is media and encoding dependent. For video, a frame will always be sent as fast as possible, but frames may be dropped until bitrate is low enough. Thus, even a bitrate of zero will allow sending one frame. For audio, it might be necessary to stop playing if the bitrate does not allow the chosen encoding enough bandwidth to be sent.

scaleResolutionDownBy of type double

This member is only present if the sender’s kind is "video". The video’s resolution will be scaled down in each dimension by the given value before sending. For example, if the value is 2.0, the video will be scaled down by a factor of 2 in each dimension, resulting in sending a video of one quarter the size. If the value is 1.0, the video will not be affected. The value must be greater than or equal to 1.0. By default, scaling is applied by a factor of two to the power of the layer’s number, in order of smaller to higher resolutions, e.g. 4:2:1. If there is only one layer, the sender will by default not apply any scaling, (i.e. scaleResolutionDownBy will be 1.0).

5.2.7 RTCRtcpParameters Dictionary

WebIDLdictionary RTCRtcpParameters {
  DOMString cname;
  boolean reducedSize;
};

Dictionary RTCRtcpParameters Members

cname of type DOMString

The Canonical Name (CNAME) used by RTCP (e.g. in SDES messages). Read-only parameter.

reducedSize of type boolean

Whether reduced size RTCP [RFC5506] is configured (if true) or compound RTCP as specified in [RFC3550] (if false). Read-only parameter.

5.2.8 RTCRtpHeaderExtensionParameters Dictionary

WebIDLdictionary RTCRtpHeaderExtensionParameters {
  required DOMString uri;
  required unsigned short id;
  boolean encrypted = false;
};

Dictionary RTCRtpHeaderExtensionParameters Members

uri of type DOMString, required

The URI of the RTP header extension, as defined in [RFC5285]. Read-only parameter.

id of type unsigned short, required

The value put in the RTP packet to identify the header extension. Read-only parameter.

encrypted of type boolean

Whether the header extension is encrypted or not. Read-only parameter.

Note

The RTCRtpHeaderExtensionParameters dictionary enables an application to determine whether a header extension is configured for use within an RTCRtpSender or RTCRtpReceiver. For an RTCRtpTransceiver transceiver, an application can determine the “direction” parameter (defined in Section 5 of [RFC5285]) of a header extension as follows without having to parse SDP:

1. sendonly: The header extension is only included in transceiver.sender.getParameters().headerExtensions.
2. recvonly: The header extension is only included in transceiver.receiver.getParameters().headerExtensions.
3. sendrecv: The header extension is included in both transceiver.sender.getParameters().headerExtensions and transceiver.receiver.getParameters().headerExtensions.
4. inactive: The header extension is included in neither transceiver.sender.getParameters().headerExtensions nor transceiver.receiver.getParameters().headerExtensions.

5.2.9 RTCRtpCodecParameters Dictionary

WebIDLdictionary RTCRtpCodecParameters {
  required octet payloadType;
  required DOMString mimeType;
  required unsigned long clockRate;
  unsigned short channels;
  DOMString sdpFmtpLine;
};

Dictionary RTCRtpCodecParameters Members

payloadType of type octet, required

The RTP payload type used to identify this codec. Read-only parameter.

mimeType of type DOMString, required

The codec MIME media type/subtype. Valid media types and subtypes are listed in [IANA-RTP-2]. Read-only parameter.

clockRate of type unsigned long, required

The codec clock rate expressed in Hertz. Read-only parameter.

channels of type unsigned short

When present, indicates the number of channels (mono=1, stereo=2). Read-only parameter.

sdpFmtpLine of type DOMString

The “format specific parameters” field from the a=fmtp line in the SDP corresponding to the codec, if one exists, as defined by [RFC8829] (section 5.8.). For an RTCRtpSender, these parameters come from the remote description, and for an RTCRtpReceiver, they come from the local description. Read-only parameter.

5.2.10 RTCRtpCapabilities Dictionary

WebIDLdictionary RTCRtpCapabilities {
  required sequence<RTCRtpCodecCapability> codecs;
  required sequence<RTCRtpHeaderExtensionCapability> headerExtensions;
};

Dictionary RTCRtpCapabilities Members

codecs of type sequence<RTCRtpCodecCapability>, required

Supported media codecs as well as entries for RTX, RED and FEC mechanisms. There will only be a single entry in codecs for retransmission via RTX, with sdpFmtpLine not present.

headerExtensions of type sequence<RTCRtpHeaderExtensionCapability>, required

Supported RTP header extensions.

5.2.11 RTCRtpCodecCapability Dictionary

WebIDLdictionary RTCRtpCodecCapability {
  required DOMString mimeType;
  required unsigned long clockRate;
  unsigned short channels;
  DOMString sdpFmtpLine;
};

Dictionary RTCRtpCodecCapability Members

The RTCRtpCodecCapability dictionary provides information about codec capabilities. Only capability combinations that would utilize distinct payload types in a generated SDP offer are provided. For example:

1. Two H.264/AVC codecs, one for each of two supported packetization-mode values.
2. Two CN codecs with different clock rates.

mimeType of type DOMString, required

The codec MIME media type/subtype. Valid media types and subtypes are listed in [IANA-RTP-2].

clockRate of type unsigned long, required

The codec clock rate expressed in Hertz.

channels of type unsigned short

If present, indicates the maximum number of channels (mono=1, stereo=2).

sdpFmtpLine of type DOMString

The “format specific parameters” field from the a=fmtp line in the SDP corresponding to the codec, if one exists.

5.2.12 RTCRtpHeaderExtensionCapability Dictionary

WebIDLdictionary RTCRtpHeaderExtensionCapability {
  DOMString uri;
};

Dictionary RTCRtpHeaderExtensionCapability Members

uri of type DOMString

The URI of the RTP header extension, as defined in [RFC5285].