Methods

generateCertificate, static

The generateCertificate function causes the user agent to create and store an X.509 certificate [[!X509V3]] and corresponding private key. A handle to information is provided in the form of the RTCCertificate interface. The returned RTCCertificate can be used to control the certificate that is offered in the DTLS sessions established by RTCPeerConnection.

The keygenAlgorithm argument is used to control how the private key associated with the certificate is generated. The keygenAlgorithm argument uses the WebCrypto [[!WebCryptoAPI]] AlgorithmIdentifier type. The keygenAlgorithm value MUST be a valid argument to window.crypto.subtle.generateKey; that is, the value MUST produce a non-error result when normalized according to the WebCrypto algorithm normalization process [[!WebCryptoAPI]] with an operation name of generateKey and a [[supportedAlgorithms]] value specific to production of certificates for RTCPeerConnection. If the algorithm normalization process produces an error, the call to generateCertificate MUST be rejected with that error.

Signatures produced by the generated key are used to authenticate the DTLS connection. The identified algorithm (as identified by the name of the normalized AlgorithmIdentifier) MUST be an asymmetric algorithm that can be used to produce a signature.

The certificate produced by this process also contains a signature. The validity of this signature is only relevant for compatibility reasons. Only the public key and the resulting certificate fingerprint are used by RTCPeerConnection, but it is more likely that a certificate will be accepted if the certificate is well formed. The browser selects the algorithm used to sign the certificate; a browser SHOULD select SHA-256 [[!FIPS-180-4]] if a hash algorithm is needed.

The resulting certificate MUST NOT include information that can be linked to a user or user agent. Randomized values for distinguished name and serial number SHOULD be used.

A user agent MUST reject a call to generateCertificate() with a DOMException of type NotSupportedError if the keygenAlgorithm parameter identifies an algorithm that the user agent cannot or will not use to generate a certificate for RTCPeerConnection.

The following values MUST be supported by a user agent: { name: "RSASSA-PKCS1-v1_5", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" }, and { name: "ECDSA", namedCurve: "P-256" }.

It is expected that a user agent will have a small or even fixed set of values that it will accept.

Attributes

ontrack of type EventHandler

The event type of this event handler is track.

Methods

getSenders

Returns a sequence of RTCRtpSender objects representing the RTP senders that are currently attached to this RTCPeerConnection object.

The getSenders method MUST return the result of executing the CollectSenders algorithm.

We define the CollectSenders algorithm as follows:

1. Let transceivers be the result of executing the CollectTransceivers algorithm.
2. Let senderset be a new empty set.
3. For each transceiver in transceivers,
   1. Let sender be transceiver's [[\Sender]].
   2. Add sender to senderset.
4. Let senders be a new sequence consisting of all the RTCRtpSender objects in senderset. The conversion from the senders set to the sequence is user agent defined and the order does not have to be stable between calls.
5. Return senders.

getReceivers

Returns a sequence of RTCRtpReceiver objects representing the RTP receivers that are currently attached to this RTCPeerConnection object.

The getReceivers method MUST return the result of executing the CollectReceivers algorithm.

We define the CollectReceivers algorithm as follows:

1. Let transceivers be the result of executing the CollectTransceivers algorithm.
2. Let receiverset be a new empty set.
3. For each transceiver in transceivers,
   1. Let receiver be transceiver's [[\Receiver]].
   2. Add receiver to receiverset.
4. Let receivers be a new sequence consisting of all the RTCRtpReceiver objects in receiverset. The conversion from the receivers set to the sequence is user agent defined and the order does not have to be stable between calls.
5. Return receivers.

getTransceivers

Returns a sequence of RTCRtpTransceiver objects representing the RTP transceivers that are currently attached to this RTCPeerConnection object.

The getTransceivers method MUST return the result of executing the CollectTransceivers algorithm.

We define the CollectTransceivers algorithm as follows:

1. Let transceivers be a new sequence that represents a snapshot of all the RTCRtpTransceiver objects in this RTCPeerConnection object's set of transceivers. The conversion from the transceiver set to the sequence is user agent defined and the order does not have to be stable between calls.
2. Return transceivers.

addTrack

Adds a new track to the RTCPeerConnection, and indicates that it is contained in the specified MediaStreams.

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

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

2. Let track be the MediaStreamTrack object indicated by the method's first argument.

3. Let streams be a list of MediaStream objects constructed from the method's remaining arguments, or an empty list if the method was called with a single argument.

4. If connection's [[\IsClosed]] slot is true, throw an InvalidStateError.

5. Let senders be the result of executing the CollectSenders algorithm. If an RTCRtpSender for track already exists in senders, throw an InvalidAccessError.

6. The steps below describe how to determine if an existing sender can be reused. Doing so will cause future calls to createOffer and createAnswer to mark the corresponding media description as sendrecv or sendonly and add the MSID of the track added, as defined in [[!JSEP]].

   If any RTCRtpSender object in senders matches all the following criteria, let sender be that object, or null otherwise:

   • The sender's track is null.

   • The transceiver kind of the RTCRtpTransceiver, associated with the sender, matches track's kind.

   • The sender has never been used to send. More precisely, the [[\CurrentDirection]] slot of the RTCRtpTransceiver associated with the sender has never had a value of sendrecv or sendonly.

7. If sender is not null, run the following steps to use that sender:

   1. Set sender's [[\SenderTrack]] to track.

   2. Set sender's [[\AssociatedMediaStreams]] to streams.

   3. Let transceiver be the RTCRtpTransceiver associated with sender.

   4. If transceiver's [[\Direction]] slot is recvonly, set transceiver's [[\Direction]] slot to sendrecv.

   5. If transceiver's [[\Direction]] slot is inactive, set transceiver's [[\Direction]] slot to sendonly.

8. If sender is null, run the following steps:

   1. Create an RTCRtpSender with track and streams and let sender be the result.

   2. Create an RTCRtpReceiver with track.kind as kind and let receiver be the result.

   3. Create an RTCRtpTransceiver with sender, receiver and an RTCRtpTransceiverDirection value of sendrecv, and let transceiver be the result.

   4. Add transceiver to connection's set of transceivers

9. A track could have contents that are inaccessible to the application. This can be due to being marked with a peerIdentity option or anything that would make a track CORS cross-origin. These tracks can be supplied to the addTrack method, and have an RTCRtpSender created for them, but content MUST NOT be transmitted, unless they are also marked with peerIdentity and they meet the requirements for sending (see isolated streams and RTCPeerConnection).

   All other tracks that are not accessible to the application MUST NOT be sent to the peer, with silence (audio), black frames (video) or equivalently absent content being sent in place of track content.

   Note that this property can change over time.

10. Update the negotiation-needed flag for connection.

11. Return sender.

removeTrack

Stops sending media from sender. The RTCRtpSender will still appear in getSenders. Doing so will cause future calls to createOffer to mark the media description for the corresponding transceiver as recvonly or inactive, as defined in [[!JSEP]].

When the other peer stops sending a track in this manner, the track is removed from any remote MediaStreams that were initially revealed in the track event, and if the MediaStreamTrack is not already muted, a muted event is fired at the track.

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

1. Let sender be the argument to removeTrack.

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

3. If connection's [[\IsClosed]] slot is true, throw an InvalidStateError.

4. If sender was not created by connection, throw an InvalidAccessError.

5. Let senders be the result of executing the CollectSenders algorithm.

6. If sender is not in senders (which indicates that it was removed due to setting an RTCSessionDescription of type "rollback"), then abort these steps.

7. If sender's [[\SenderTrack]] is null, abort these steps.

8. Set sender's [[\SenderTrack]] to null.

9. Let transceiver be the RTCRtpTransceiver object corresponding to sender.

10. If transceiver's [[\Direction]] slot is sendrecv, set transceiver's [[\Direction]] slot to recvonly.

11. If transceiver's [[\Direction]] slot is sendonly, set transceiver's [[\Direction]] slot to inactive.

12. Update the negotiation-needed flag for connection.

addTransceiver

Create a new RTCRtpTransceiver and add it to the set of transceivers.

Adding a transceiver will cause future calls to createOffer to add a media description for the corresponding transceiver, as defined in [[!JSEP]].

The initial value of mid is null. Setting a new RTCSessionDescription may change it to a non-null value, as defined in [[!JSEP]].

The sendEncodings argument can be used to specify the number of offered simulcast encodings, and optionally their RIDs and encoding parameters.

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

1. Let init be the second argument.

2. Let streams be init's streams member.

3. Let sendEncodings be init's sendEncodings member.

4. Let direction be init's direction member.

5. If the first argument is a string, let it be kind and run the following steps:

   1. If kind is not a legal MediaStreamTrack kind, throw a TypeError.

   2. Let track be null.

6. If the first argument is a MediaStreamTrack, let it be track and let kind be track.kind.

7. Verify that each rid value in sendEncodings is composed only of alphanumeric characters (a-z, A-Z, 0-9) up to a maximum of 16 characters. If one of the RIDs does not meet these requirements, throw a TypeError.

8. If any RTCRtpEncodingParameters dictionary in sendEncodings contains a read-only parameter other than rid, throw an InvalidAccessError.

9. Verify that each scaleResolutionDownBy value in sendEncodings is greater than or equal to 1.0. If one of the scaleResolutionDownBy values does not meet this requirement, throw a RangeError.

10. Create an RTCRtpSender with track, streams and sendEncodings and let sender be the result.

    If sendEncodings is set, then subsequent calls to createOffer will be configured to send multiple RTP encodings as defined in [[!JSEP]]. When setRemoteDescription is called with a corresponding remote description that is able to receive multiple RTP encodings as defined in [[!JSEP]], the RTCRtpSender may send multiple RTP encodings and the parameters retrieved via the transceiver's sender.getParameters() will reflect the encodings negotiated.

11. Create an RTCRtpReceiver with kind and let receiver be the result. This specification does not define how to configure createOffer to receive multiple RTP encodings. However when setRemoteDescription is called with a corresponding remote description that is able to send multiple RTP encodings as defined in [[!JSEP]], the RTCRtpReceiver may receive multiple RTP encodings and the parameters retrieved via the transceiver's receiver.getParameters() will reflect the encodings negotiated.

12. Create an RTCRtpTransceiver with sender, receiver and direction, and let transceiver be the result.

13. Add transceiver to connection's set of transceivers

14. Update the negotiation-needed flag for connection.

15. Return transceiver.

Dictionary RTCRtpTransceiverInit Members

direction of type RTCRtpTransceiverDirection, defaulting to "sendrecv"

The direction of the RTCRtpTransceiver.

streams of type sequence<MediaStream>

When the remote PeerConnection's ontrack event fires corresponding to the RTCRtpReceiver being added, these are the streams that will be put in the event.

sendEncodings of type sequence<RTCRtpEncodingParameters>

A sequence containing parameters for sending RTP encodings of media.

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 track.muted is set to true, the RTCRtpSender sends silence (audio) or a black frame (video). 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.

rtcpTransport of type RTCDtlsTransport, readonly, nullable

The rtcpTransport attribute is the transport over which RTCP is sent and received. Prior to construction of the RTCDtlsTransport object, the rtcpTransport attribute will be null. When RTCP mux is used (or bundling, which mandates RTCP mux), rtcpTransport will be null, and both RTP and RTCP traffic will flow over the transport described by transport.

On getting, the attribute MUST return the value of the [[\SenderRtcpTransport]] 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.

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's [[\Sender]]).
4. Let N be the number of RTCRtpEncodingParameters stored in sender's internal [[\SendEncodings]] slot.
5. If transceiver's [[\Stopped]] slot is true, return a promise rejected with a newly created InvalidStateError.
6. If sender's [[\LastReturnedParameters]] internal slot is empty, meaning getParameters has never been called, return a promise rejected with a newly created InvalidStateError.
7. If parameters.encodings.length is different from N, or if any parameter in parameters, is marked as a Read-only parameter, has a value that is different from the corresponding parameter value in sender's [[\LastReturnedParameters]] internal slot, return a promise rejected with a newly created InvalidModificationError. Note that this also applies to transactionId.

8. For each value of i from 0 to the number of encodings, check whether parameters.encodings[i].codecPayloadType (if set) corresponds to a value of parameters.codecs[j].payloadType where j goes from 0 to the number of codecs. If there is no correspondence, or if the MIME subtype portion of parameters.codecs[j].mimeType is equal to "red", "cn", "telephone-event", "rtx" or a forward error correction codec ("ulpfec" [[RFC5109]] or "flexfec" [[FLEXFEC]]), reject p with a newly created InvalidAccessError.

9. If the scaleResolutionDownBy parameter in the parameters argument has a value less than 1.0, return a promise rejected with a newly created RangeError.
10. Let p be a new promise.
11. In parallel, configure the media stack to use parameters to transmit sender's [[\SenderTrack]].
    1. If the media stack is successfully configured with parameters, queue a task to run the following steps:
       1. Set sender's internal [[\SendEncodings]] slot to parameters.encodings.
       2. 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.
12. Return p.

If the application selects a codec via codecPayloadType, and this codec is removed from a subsequent offer/answer negotiation, codecPayloadType will be unset in the next call to getParameters, and the implementation will fall back to its default codec selection policy until a new codec is selected.

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 RTCRtpParameters 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 RTCRtpParameters dictionary is constructed as follows:

• transactionId is set to a new unique identifier, used to match this getParameters call to a setParameters call that may occur later.
• 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.
• The codecs sequence is populated based on the codecs that have been negotiated for sending, and which the user agent is currently capable of sending.
• 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.
• degradationPreference is set to the last value passed into setParameters, or the default value of "balanced" if setParameters hasn't been called.

The returned RTCRtpParameters dictionary MUST be stored in the RTCRtpSender object's [[\LastReturnedParameters]] internal slot.

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

async function updateParameters() {
  try {
    const params = sender.getParameters();
    // ... make changes to RTCRtpParameters
    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 track being sent with another track provided (or with a null track), without renegotiation.

To avoid track identifiers changing on the remote receiving end when a track is replaced, the sender MUST retain the original track identifier and stream associations and use these in subsequent negotiations.

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 that created sender.

4. If connection's [[\IsClosed]] slot is true, return a promise rejected with a newly created InvalidStateError and abort these steps.

5. If transceiver's [[\Stopped]] slot is true, return a promise rejected with a newly created InvalidStateError.

6. Let withTrack be the argument to this method.

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

8. If transceiver is not yet associated with a media description, then set sender's track attribute to withTrack, and return a promise resolved with undefined.

9. Let p be a new promise.

10. Run the following steps in parallel:

    1. Determine if negotiation is needed to transmit withTrack in place of the sender's existing track. Negotiation is not needed if withTrack is null or if the sender's existing track is ended (which appears as though the track was muted). Ignore which MediaStream the track resides in and the id attribute of the track in this determination. If negotiation is needed, then reject p with a newly created InvalidModificationError and abort these steps.

    2. If withTrack is null, have the sender stop sending, without negotiating. Otherwise, have the sender switch seamlessly to transmitting withTrack instead of the sender's existing track, without negotiating.

    3. Queue a task that runs the following steps:

       1. If connection's [[\IsClosed]] slot is true, abort these steps.

       2. Set sender's track attribute to withTrack.

       3. Resolve p with undefined.

11. Return p.

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.

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.

Dictionary RTCRtpParameters Members

transactionId of type DOMString

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

A sequence containing parameters for RTP encodings of media.

headerExtensions of type sequence<RTCRtpHeaderExtensionParameters>

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

rtcp of type RTCRtcpParameters

Parameters used for RTCP. Read-only parameter.

codecs of type sequence<RTCRtpCodecParameters>

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.

degradationPreference of type RTCDegradationPreference

When bandwidth is constrained and the RtpSender needs to choose between degrading resolution or degrading framerate, degradationPreference indicates which is preferred. If unset, the RtpSender defaults to the balanced policy.

For an RtpReceiver, degradationPreference is inapplicable and will always be undefined.

Dictionary RTCRtpEncodingParameters Members

codecPayloadType of type octet

For an RTCRtpSender, used to select a codec to be sent. Must reference a payload type from the codecs member of RTCRtpParameters. If left unset, the implementation will select a codec according to its default policy. This field is not used for RTCRtpReceivers.

dtx of type RTCDtxStatus

For an RTCRtpSender, indicates whether discontinuous transmission will be used. Setting it to disabled causes discontinuous transmission to be turned off. Setting it to enabled causes discontinuous transmission to be turned on if it was negotiated (either via a codec-specific parameter or via negotiation of the CN codec); if it was not negotiated (such as when setting voiceActivityDetection to false), then discontinuous operation will be turned off regardless of the value of dtx, and media will be sent even when silence is detected. This attribute is ignored by a receiver or video sender.

active of type boolean, defaulting to true

For an RTCRtpSender, 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. For an RTCRtpReceiver, a value of true indicates that this encoding is being decoded. A value of false indicates this encoding is no longer being decoded.

priority of type RTCPriorityType, defaulting to "low"

Indicates the priority of this encoding. It is specified in [[!RTCWEB-TRANSPORT]], Section 4.

ptime of type unsigned long

For an RTCRtpSender, indicates the preferred duration of media represented by a packet in milliseconds for this encoding. Typically, this is only relevant for audio encoding. The user agent MUST use this duration if possible, and otherwise use the closest available duration. This value MUST take precedence over any "ptime" attribute in the remote description, whose processing is described in [[!JSEP]]. Note that the user agent MUST still respect the limit imposed by any "maxptime" attribute, as defined in [[!RFC4566]], Section 6.

maxBitrate of type unsigned long

Indicates the maximum bitrate that can be used to send this encoding. The encoding may also be further constrained by other limits (such as maxFramerate or 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.

maxFramerate of type double

Indicates the maximum framerate that can be used to send this encoding, in frames per second.

rid of type DOMString

If set, this RTP encoding will be sent with the RID header extension as defined by [[!JSEP]]. The RID is not modifiable via setParameters. It can only be set or modified in addTransceiver.

scaleResolutionDownBy of type double

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, the sender will not apply any scaling, (i.e., scaleResolutionDownBy will be 1.0).

Usage of the attributes is defined in the table below:

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.

Dictionary RTCRtpHeaderExtensionParameters Members

uri of type DOMString

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

id of type unsigned short

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

encrypted of type boolean

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

Dictionary RTCRtpCodecParameters Members

payloadType of type octet

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

mimeType of type DOMString

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

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

channels of type unsigned short

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 [[!JSEP]]. For an RTCRtpSender, these parameters come from the remote description, and for an RTCRtpReceiver, they come from the local description. Read-only parameter.

Dictionary RTCRtpCapabilities Members

codecs of type sequence<RTCRtpCodecCapability>

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>

Supported RTP header extensions.

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

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

clockRate of type unsigned long

The codec clock rate expressed in Hertz.

channels of type unsigned short

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.

Dictionary RTCRtpHeaderExtensionCapability Members

uri of type DOMString

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

Attributes

track of type MediaStreamTrack, readonly

The track attribute is the track that is associated with this RTCRtpReceiver object receiver. When one of the SSRCs for RTP source media streams received by receiver is removed (either due to reception of a BYE or via timeout), the mute event is fired at track. If and when packets are received again, the unmute event is fired at track.

Note that track.stop() is final, although clones are not affected. Since receiver.track.stop() does not implicitly stop receiver, Receiver Reports continue to be sent. On getting, the attribute MUST return the value of the [[\ReceiverTrack]] slot.

transport of type RTCDtlsTransport, readonly, nullable

The transport attribute is the transport over which media for the receiver's track is received in the form of RTP packets. Prior to construction of the RTCDtlsTransport object, the transport attribute will be null. When bundling is used, multiple RTCRtpReceiver objects will share one transport and will all receive RTP and RTCP over the same transport.

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

rtcpTransport of type RTCDtlsTransport, readonly, nullable

The rtcpTransport attribute is the transport over which RTCP is sent and received. Prior to construction of the RTCDtlsTransport object, the rtcpTransport attribute will be null. When RTCP mux is used (or bundling, which mandates RTCP mux), rtcpTransport will be null, and both RTP and RTCP traffic will flow over transport.

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

Methods

getCapabilities, static

The getCapabilities() method returns the most optimistic view of the capabilities of the system for receiving 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.

getParameters

The getParameters() method returns the RTCRtpReceiver object's current parameters for how track is decoded.

When getParameters is called, the RTCRtpParameters dictionary is constructed as follows:

• encodings is populated based on RIDs present in the current remote description. Every member of the RTCRtpEncodingParameters dictionaries other than the RID fields is left undefined.

• The headerExtensions sequence is populated based on the header extensions that the receiver is currently prepared to receive.

• The codecs sequence is populated based on the codecs that the receiver is currently prepared to receive.

  Both the local and remote description may affect this list of codecs. For example, if three codecs are offered, the receiver will be prepared to receive each of them and will return them all from getParameters. But if the remote endpoint only answers with two, the absent codec will no longer be returned by getParameters as the receiver no longer needs to be prepared to receive it.
• rtcp.reducedSize is set to true if the receiver is currently prepared to receive reduced-size RTCP packets, and false otherwise. rtcp.cname is left undefined.
• transactionId and degradationPreference are left undefined.

getContributingSources

Returns an RTCRtpContributingSource for each unique CSRC identifier received by this RTCRtpReceiver in the last 10 seconds.

getSynchronizationSources

Returns an RTCRtpSynchronizationSource for each unique SSRC identifier received by this RTCRtpReceiver in the last 10 seconds.

getStats

Gathers stats for this receiver 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 RTCRtpReceiver 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.

Dictionary RTCRtpContributingSource Members

timestamp of type DOMHighResTimeStamp, required

The timestamp of type DOMHighResTimeStamp [[!HIGHRES-TIME]], indicating the most recent time of playout of an RTP packet containing the source. The timestamp is defined in [[!HIGHRES-TIME]] and corresponds to a local clock.

source of type unsigned long, required

The CSRC or SSRC identifier of the contributing or synchronization source.

audioLevel of type byte, required, nullable

The audio level contained in the last RTP packet played from this source. For CSRCs, audioLevel must be the level value defined in [[!RFC6465]] if the RFC 6465 header extension is present, otherwise null. For SSRCs, it must be the level value defined in [[!RFC6464]] if the RFC 6464 header extension is present, otherwise a browser computed value as if it had come from RFC 6464 (never null).

Both RFCs define the level as an integral value from 0 to 127 representing the audio level in negative decibels relative to the loudest signal that the system could possibly encode. Thus, 0 represents the loudest signal the system could possibly encode, and 127 represents silence.

Dictionary RTCRtpSynchronizationSource Members

voiceActivityFlag of type boolean, required, nullable

Whether the last RTP packet played from this source contains voice activity (true) or not (false). If the RFC 6464 extension header was not present, or if the peer has signaled that it is not using the V bit by setting the "vad" extension attribute to "off", as described in [[!RFC6464]], Section 4, voiceActivityFlag will be null.

Attributes

mid of type DOMString, readonly, nullable

The mid attribute is the mid negotatiated and present in the local and remote descriptions as defined in [[!JSEP]]. Before negotiation is complete, the mid value may be null. After rollbacks, the value may change from a non-null value to null.

sender of type RTCRtpSender, readonly

The sender attribute exposes the RTCRtpSender corresponding to the RTP media that may be sent with mid = mid. On getting, the attribute MUST return the value of the [[\Sender]] slot.

receiver of type RTCRtpReceiver, readonly

The receiver attribute is the RTCRtpReceiver corresponding to the RTP media that may be received with mid = mid. On getting the attribute MUST return the value of the [[\Receiver]] slot.

stopped of type boolean, readonly

The stopped attribute indicates that the sender of this transceiver will no longer send, and that the receiver will no longer receive. It is true if either stop has been called or if setting the local or remote description has caused the RTCRtpTransceiver to be stopped. On getting, this attribute MUST return the value of the [[\Stopped]] slot.

direction of type RTCRtpTransceiverDirection, readonly

As defined in [[!JSEP]], the direction attribute indicates the preferred direction of this transceiver, which will be used in calls to createOffer and createAnswer. An update of directionality does not take effect immediately. Instead, future calls to createOffer and createAnswer mark the corresponding media description as sendrecv, sendonly, recvonly or inactive as defined in [[!JSEP]]

On getting, this attribute MUST return the value of the [[\Direction]] slot.

On setting, the user agent MUST run the following steps:

1. Let transceiver be the RTCRtpTransceiver object on which the setter is invoked.

2. Let connection be the RTCPeerConnection object associated with transceiver.

3. If connection's [[\IsClosed]] slot is true, throw an InvalidStateError.

4. If transceiver's [[\Stopped]] slot is true, throw an InvalidStateError.

5. Let newDirection be the argument to the setter.

6. If newDirection is equal to transceiver's [[\Direction]] slot, abort these steps.

7. Set transceiver's [[\Direction]] slot to newDirection.

8. Update the negotiation-needed flag for connection.

currentDirection of type RTCRtpTransceiverDirection, readonly, nullable

As defined in [[!JSEP]], the currentDirection attribute indicates the current direction negotiated for this transceiver. The value of currentDirection is independent of the value of RTCRtpEncodingParameters.active since one cannot be deduced from the other. If this transceiver has never been represented in an offer/answer exchange, or if the transceiver is stopped, the value is null. On getting, this attribute MUST return the value of the [[\CurrentDirection]] slot.

Methods

stop

The stop method irreversibly stops the RTCRtpTransceiver. The sender of this transceiver will no longer send, the receiver will no longer receive. Calling stop() updates the negotiation-needed flag for the RTCRtpTransceiver's associated RTCPeerConnection.

Stopping a transceiver will cause future calls to createOffer to generate a zero port in the media description for the corresponding transceiver, as defined in [[!JSEP]].

When this method is invoked, to stop the RTCRtpTransceiver transceiver, the user agent MUST run the following steps:

1. If transceiver's [[\Stopped]] slot is true, abort these steps.

2. Let connection be the RTCPeerConnection object on which the transceiver is to be stopped.

3. If connection's [[\IsClosed]] slot is true, throw an InvalidStateError.

4. Let sender be transceiver's [[\Sender]].

5. Let receiver be transceiver's [[\Receiver]].

6. Stop sending media with sender.

7. Send an RTCP BYE for each RTP stream that was being sent by sender, as specified in [[!RFC3550]].

8. Stop receiving media with receiver.

9. receiver's [[\ReceiverTrack]] is now said to be ended.

10. Set transceiver's [[\Stopped]] slot to true.

11. Set transceiver's [[\CurrentDirection]] slot to null.

12. Update the negotiation-needed flag for connection.

When a remote description is applied with a zero port in the media description for the corresponding transceiver, as defined in [[!JSEP]], the user agent MUST run the above steps as if stop had been called. In addition, since the receiver's [[\ReceiverTrack]] has ended, the steps described in track ended MUST be followed.

setCodecPreferences

The setCodecPreferences method overrides the default codec preferences used by the user agent. When generating a session description using either createOffer or createAnswer, the user agent MUST use the indicated codecs, in the order specified in the codecs argument, for the media section corresponding to this RTCRtpTransceiver. Note that calls to createAnswer will use only the common subset of these codecs and the codecs that appear in the offer.

This method allows applications to disable the negotiation of specific codecs. It also allows an application to cause a remote peer to prefer the codec that appears first in the list for sending.

Codec preferences remain in effect for all calls to createOffer and createAnswer that include this RTCRtpTransceiver until this method is called again. Setting codecs to an empty sequence resets codec preferences to any default value.

The codecs sequence passed into setCodecPreferences can only contain codecs that are returned by RTCRtpSender.getCapabilities(kind) or RTCRtpReceiver.getCapabilities(kind), where kind is the kind of the RTCRtpTransceiver on which the method is called. Additionally, the RTCRtpCodecParameters dictionary members cannot be modified. If codecs does not fulfill these requirements, the user agent MUST throw an InvalidAccessError.

Attributes

transport of type RTCIceTransport, readonly

The transport attribute is the underlying transport that is used to send and receive packets. The underlying transport may not be shared between multiple active RTCDtlsTransport objects.

state of type RTCDtlsTransportState, readonly

The state attribute MUST, on getting, return the value of the [[\DtlsTransportState]] slot.

onstatechange of type EventHandler

The event type of this event handler is statechange.

onerror of type EventHandler

The event type of this event handler is error.

Methods

getRemoteCertificates

Returns the certificate chain in use by the remote side, with each certificate encoded in binary Distinguished Encoding Rules (DER) [[!X690]]. getRemoteCertificates() will return an empty list prior to selection of the remote certificate, which will be completed by the time RTCDtlsTransportState transitions to "connected".

Attributes

role of type RTCIceRole, readonly

The role attribute MUST return the ICE role of the transport.

component of type RTCIceComponent, readonly

The component attribute MUST return the ICE component of the transport. When RTCP mux is used, a single RTCIceTransport transports both RTP and RTCP and component is set to "RTP".

state of type RTCIceTransportState, readonly

The state attribute MUST, on getting, return the value of the [[\IceTransportState]] slot.

gatheringState of type RTCIceGathererState, readonly

The gathering state attribute MUST, on getting, return the value of the [[\IceGathererState]] slot.

onstatechange of type EventHandler

This event handler, of event handler event type statechange, MUST be fired any time the RTCIceTransport state changes.

ongatheringstatechange of type EventHandler

This event handler, of event handler event type gatheringstatechange, MUST be fired any time the RTCIceTransportgathering state changes.

onselectedcandidatepairchange of type EventHandler

This event handler, of event handler event type selectedcandidatepairchange, MUST be fired any time the RTCIceTransport's selected candidate pair changes.

Methods

getLocalCandidates

Returns a sequence describing the local ICE candidates gathered for this RTCIceTransport and sent in onicecandidate

getRemoteCandidates

Returns a sequence describing the remote ICE candidates received by this RTCIceTransport via addIceCandidate()

getSelectedCandidatePair

Returns the selected candidate pair on which packets are sent. This method MUST return the value of the [[\SelectedCandidatePair]] slot.

getLocalParameters

Returns the local ICE parameters received by this RTCIceTransport via setLocalDescription, or null if the parameters have not yet been received.

getRemoteParameters

Returns the remote ICE parameters received by this RTCIceTransport via setRemoteDescription or null if the parameters have not yet been received.

Dictionary RTCIceParameters Members

usernameFragment of type DOMString

The ICE username fragment as defined in [[!ICE]], Section 7.1.2.3.

password of type DOMString

The ICE password as defined in [[!ICE]], Section 7.1.2.3.

Dictionary RTCIceCandidatePair Members

local of type RTCIceCandidate

The local ICE candidate.

remote of type RTCIceCandidate

The remote ICE candidate.

Constructors

RTCTrackEvent

Attributes

receiver of type RTCRtpReceiver, readonly

The receiver attribute represents the RTCRtpReceiver object associated with the event.

track of type MediaStreamTrack, readonly

The track attribute represents the MediaStreamTrack object that is associated with the RTCRtpReceiver identified by receiver.

streams of type FrozenArray<MediaStream>, readonly

The streams attribute returns an array of MediaStream objects representing the MediaStreams that this event's track is a part of.

transceiver of type RTCRtpTransceiver, readonly

The transceiver attribute represents the RTCRtpTransceiver object associated with the event.

Dictionary RTCTrackEventInit Members

receiver of type RTCRtpReceiver, required

The receiver attribute represents the RTCRtpReceiver object associated with the event.

track of type MediaStreamTrack, required

The track attribute represents the MediaStreamTrack object that is associated with the RTCRtpReceiver identified by receiver.

streams of type sequence<MediaStream>, defaulting to []

The streams attribute returns an array of MediaStream objects representing the MediaStreams that this event's track is a part of.

transceiver of type RTCRtpTransceiver, required

The transceiver attribute represents the RTCRtpTransceiver object associated with the event.

Attributes

sctp of type RTCSctpTransport, readonly, nullable

The SCTP transport over which SCTP data is sent and received. If SCTP has not been negotiated, the value is null. This attribute MUST return the RTCSctpTransport object stored in the [[\SctpTransport]] internal slot.

ondatachannel of type EventHandler

The event type of this event handler is datachannel.

Methods

createDataChannel

Creates a new RTCDataChannel object with the given label. The RTCDataChannelInit dictionary can be used to configure properties of the underlying channel such as data reliability.

When the createDataChannel method is invoked, the user agent MUST run the following steps.

1. Let connection be the RTCPeerConnection object on which the method is invoked.

2. If connection's [[\IsClosed]] slot is true, throw an InvalidStateError.

3. Let channel be a newly created RTCDataChannel object.

4. Let channel have a [[\DataChannelLabel]] internal slot initialized to the value of the first argument.

5. If [[\DataChannelLabel]] is longer than 65535 bytes, throw a TypeError.

6. Let options be the second argument.

7. Let channel have a [[\MaxPacketLifeTime]] internal slot initialized to option's maxPacketLifeTime member, if present, otherwise null.

8. Let channel have a [[\ReadyState]] internal slot initialized to "connecting".

9. Let channel have a [[\MaxRetransmits]] internal slot initialized to option's maxRetransmits member, if present, otherwise null.

10. Let channel have an [[\Ordered]] internal slot initialized to option's ordered member.

11. Let channel have a [[\DataChannelProtocol]] internal slot initialized to option's protocol member.

12. If [[\DataChannelProtocol]] is longer than 65535 bytes long, throw a TypeError.

13. Let channel have a [[\Negotiated]] internal slot initialized to option's negotiated member.

14. Let channel have an [[\DataChannelId]] internal slot initialized to option's id member, if it is present and [[\Negotiated]] is true, otherwise null.

    This means the id member will be ignored if the data channel is negotiated in-band; this is intentional. Data channels negotiated in-band should have IDs selected based on the DTLS role, as specified in [[!RTCWEB-DATA-PROTOCOL]].

15. If [[\Negotiated]] is true and [[\DataChannelId]] is null, throw a TypeError.

16. Let channel have an [[\DataChannelPriority]] internal slot initialized to option's priority member.

17. If both [[\MaxPacketLifeTime]] and [[\MaxRetransmits]] attributes are set (not null), throw a TypeError.

18. If a setting, either [[\MaxPacketLifeTime]] or [[\MaxRetransmits]], has been set to indicate unreliable mode, and that value exceeds the maximum value supported by the user agent, the value MUST be set to the user agents maximum value.

19. If [[\DataChannelId]] is equal to 65535, which is greater than the maximum allowed ID of 65534 but still qualifies as an unsigned short, throw a TypeError.

20. If the [[\DataChannelId]] slot is null (due to no ID being passed into createDataChannel, or [[\Negotiated]] being false), and the DTLS role of the SCTP transport has already been negotiated, then initialize [[\DataChannelId]] to a value generated by the user agent, according to [[!RTCWEB-DATA-PROTOCOL]], and skip to the next step. If no available ID could be generated, or if the value of the [[\DataChannelId]] slot is being used by an existing RTCDataChannel, throw an OperationError exception.

    If the [[\DataChannelId]] slot is null after this step, it will be populated once the DTLS role is determined during the process of setting an RTCSessionDescription.

21. If channel is the first RTCDataChannel created on connection, update the negotiation-needed flag for connection.

22. Return channel and continue the following steps in parallel.

23. Create channel's associated underlying data transport and configure it according to the relevant properties of channel.