Methods

generateCertificate, static

The {{generateCertificate}} function causes the user agent to create 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 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.

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.

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

1. Let keygenAlgorithm be the first argument to {{generateCertificate}}.

2. Let expires be a {{DOMTimeStamp}} value of 2592000000.

   This means the certificate will by default expire in 30 days from the time of the {{generateCertificate}} call.

3. If keygenAlgorithm is an object, run the following steps:

   1. Let certificateExpiration be the result of converting the ECMAScript object represented by keygenAlgorithm to an {{RTCCertificateExpiration}} dictionary.

   2. If the conversion fails with an error, return a promise that is [= rejected =] with error.

   3. If certificateExpiration.{{RTCCertificateExpiration/expires}} is not undefined, set expires to certificateExpiration.{{RTCCertificateExpiration/expires}}.

   4. If expires is greater than 31536000000, set expires to 31536000000.

      This means the certificate cannot be valid for longer than 365 days from the time of the {{generateCertificate}} call.

      A user agent MAY further cap the value of expires.

4. Let normalizedKeygenAlgorithm be the result of normalizing an algorithm with an operation name of generateKey and a supportedAlgorithms value specific to production of certificates for {{RTCPeerConnection}}.

5. If the above normalization step fails with an error, return a promise that is [= rejected =] with error.

6. If the normalizedKeygenAlgorithm parameter identifies an algorithm that the user agent cannot or will not use to generate a certificate for {{RTCPeerConnection}}, return a promise that is [= rejected =] with a {{DOMException}} of type {{NotSupportedError}}. In particular, normalizedKeygenAlgorithm MUST be an asymmetric algorithm that can be used to produce a signature used to authenticate DTLS connections.

7. Let p be a new promise.

8. Run the following steps in parallel:

   1. Perform the generate key operation specified by normalizedKeygenAlgorithm using keygenAlgorithm.

   2. Let generatedKeyingMaterial and generatedKeyCertificate be the private keying material and certificate generated by the above step.

   3. Let certificate be a new {{RTCCertificate}} object.

   4. Set certificate.[[\Expires]] to the current time plus expires value.

   5. Set certificate.{{RTCCertificate/[[Origin]]}} to the [= relevant settings object =]'s [=environment settings object/origin=].

   6. Store the generatedKeyingMaterial in a secure module, and let handle be a reference identifier to it.

   7. Set certificate.{{RTCCertificate/[[KeyingMaterialHandle]]}} to handle.

   8. Set certificate.{{RTCCertificate/[[Certificate]]}} to generatedCertificate.

   9. Resolve p with certificate.

9. Return p.

Attributes

ontrack of type EventHandler

The event type of this event handler is {{RTCPeerConnection/track}}.

Methods

getSenders

Returns a sequence of {{RTCRtpSender}} objects representing the RTP senders that belong to non-stopped {{RTCRtpTransceiver}} objects currently attached to this {{RTCPeerConnection}} object.

When the {{getSenders}} method is invoked, the user agent 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 senders be a new empty sequence.
3. For each transceiver in transceivers,
   1. If transceiver.{{RTCRtpTransceiver/[[Stopped]]}} is false, add transceiver.{{RTCRtpTransceiver/[[Sender]]}} to senders.
4. Return senders.

getReceivers

Returns a sequence of {{RTCRtpReceiver}} objects representing the RTP receivers that belong to non-stopped {{RTCRtpTransceiver}} objects currently attached to this {{RTCPeerConnection}} object.

When the {{getReceivers}} method is invoked, the user agent MUST run the following steps:

1. Let transceivers be the result of executing the {{CollectTransceivers}} algorithm.
2. Let receivers be a new empty sequence.
3. For each transceiver in transceivers,
   1. If transceiver.{{RTCRtpTransceiver/[[Stopped]]}} is false, add transceiver.{{RTCRtpTransceiver/[[Receiver]]}} to receivers.
4. 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 consisting of all {{RTCRtpTransceiver}} objects in this {{RTCPeerConnection}} object's [= set of transceivers =], in insertion order.
2. Return transceivers.

addTrack

Adds a new track to the {{RTCPeerConnection}}, and indicates that it is contained in the specified {{MediaStream}}s.

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 kind be track.kind.

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

5. If connection.{{RTCPeerConnection/[[IsClosed]]}} is true, [= exception/throw =] an {{InvalidStateError}}.

6. Let senders be the result of executing the {{CollectSenders}} algorithm. If an {{RTCRtpSender}} for track already exists in senders, [= exception/throw =] an {{InvalidAccessError}}.

7. The steps below describe how to determine if an existing sender can be reused. Doing so will cause future calls to {{RTCPeerConnection/createOffer}} and {{RTCPeerConnection/createAnswer}} to mark the corresponding [= media description =] as sendrecv or sendonly and add the MSID of the sender's streams, as defined in [[!RFC8829]].

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

   • The {{RTCRtpTransceiver/[[Stopping]]}} slot of the {{RTCRtpTransceiver}} associated with the sender is false.

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

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

   1. Set sender.{{RTCRtpSender/[[SenderTrack]]}} to track.

   2. Set sender.{{RTCRtpSender/[[AssociatedMediaStreamIds]]}} to an empty set.

   3. For each stream in streams, add stream.id to {{RTCRtpSender/[[AssociatedMediaStreamIds]]}} if it's not already there.

   4. Let transceiver be the {{RTCRtpTransceiver}} associated with sender.

   5. If transceiver.{{RTCRtpTransceiver/[[Direction]]}} is {{RTCRtpTransceiverDirection/"recvonly"}}, set transceiver.{{RTCRtpTransceiver/[[Direction]]}} to {{RTCRtpTransceiverDirection/"sendrecv"}}.

   6. If transceiver.{{RTCRtpTransceiver/[[Direction]]}} is {{RTCRtpTransceiverDirection/"inactive"}}, set transceiver.{{RTCRtpTransceiver/[[Direction]]}} to {{RTCRtpTransceiverDirection/"sendonly"}}.

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

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

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

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

   4. Add transceiver to connection's [= set of transceivers =].

10. A track could have contents that are inaccessible to the application. This can be due to anything that would make a track CORS cross-origin. These tracks can be supplied to the {{RTCPeerConnection/addTrack()}} method, and have an {{RTCRtpSender}} created for them, but content MUST NOT be transmitted. Silence (audio), black frames (video) or equivalently absent content is sent in place of track content.

    Note that this property can change over time.

11. [= Update the negotiation-needed flag =] for connection.

12. 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 {{RTCRtpTransceiverDirection/"recvonly"}} or {{RTCRtpTransceiverDirection/"inactive"}}, as defined in [[!RFC8829]].

When the other peer stops sending a track in this manner, the track is removed from any remote {{MediaStream}}s that were initially revealed in the {{RTCPeerConnection/track}} event, and if the {{MediaStreamTrack}} is not already muted, a mute event is fired at the track.

The same effect as {{removeTrack()}} can be achieved by setting the {{RTCRtpTransceiver}}.{{RTCRtpTransceiver/direction}} attribute of the corresponding transceiver and invoking {{RTCRtpSender}}.{{RTCRtpSender/replaceTrack}}(null) on the sender. One minor difference is that {{RTCRtpSender/replaceTrack()}} is asynchronous and {{removeTrack()}} is synchronous.

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.{{RTCPeerConnection/[[IsClosed]]}} is true, [= exception/throw =] an {{InvalidStateError}}.

4. If sender was not created by connection, [= exception/throw =] an {{InvalidAccessError}}.

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

6. If sender is not in senders (which indicates its transceiver was stopped or removed due to [= setting a session description =] of {{RTCSessionDescriptionInit/type}} {{RTCSdpType/"rollback"}}), then abort these steps.

7. If sender.{{RTCRtpSender/[[SenderTrack]]}} is null, abort these steps.

8. Set sender.{{RTCRtpSender/[[SenderTrack]]}} to null.

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

10. If transceiver.{{RTCRtpTransceiver/[[Direction]]}} is {{RTCRtpTransceiverDirection/"sendrecv"}}, set transceiver.{{RTCRtpTransceiver/[[Direction]]}} to {{RTCRtpTransceiverDirection/"recvonly"}}.

11. If transceiver.{{RTCRtpTransceiver/[[Direction]]}} is {{RTCRtpTransceiverDirection/"sendonly"}}, set transceiver.{{RTCRtpTransceiver/[[Direction]]}} to {{RTCRtpTransceiverDirection/"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 [[!RFC8829]].

The initial value of {{RTCRtpTransceiver/mid}} is null. [= Setting a session description =] may later change it to a non-null value.

The {{RTCRtpTransceiverInit/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.{{RTCRtpTransceiverInit/streams}}.

3. Let sendEncodings be init.{{RTCRtpTransceiverInit/sendEncodings}}.

4. Let direction be init.{{RTCRtpTransceiverInit/direction}}.

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, [= exception/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. If connection.{{RTCPeerConnection/[[IsClosed]]}} is true, [= exception/throw =] an {{InvalidStateError}}.

8. Validate sendEncodings by running the following steps:

   1. Verify that each {{RTCRtpCodingParameters/rid}} value in sendEncodings conforms to the grammar specified in Section 10 of [[RFC8851]]. If one of the RIDs does not meet these requirements, [= exception/throw =] a {{TypeError}}.

   2. If any {{RTCRtpEncodingParameters}} dictionary in sendEncodings contains a read-only parameter other than {{RTCRtpCodingParameters/rid}}, [= exception/throw =] an {{InvalidAccessError}}.

   3. Verify that the value of each {{RTCRtpEncodingParameters/scaleResolutionDownBy}} member in sendEncodings that is defined is greater than or equal to 1.0. If one of the {{RTCRtpEncodingParameters/scaleResolutionDownBy}} values does not meet this requirement, [= exception/throw =] a {{RangeError}}.

   4. Let maxN be the maximum number of total simultaneous encodings the user agent may support for this kind, at minimum 1.This should be an optimistic number since the codec to be used is not known yet.

   5. If sendEncodings contains any encoding whose {{RTCRtpEncodingParameters/scaleResolutionDownBy}} attribute is defined, set any undefined {{RTCRtpEncodingParameters/scaleResolutionDownBy}} of the other encodings to 1.0.

   6. If the number of {{RTCRtpEncodingParameters}} stored in sendEncodings exceeds maxN, then trim sendEncodings from the tail until its length is maxN.

   7. If the {{RTCRtpEncodingParameters/scaleResolutionDownBy}} attribues of sendEncodings are still undefined, initialize each encoding's {{RTCRtpEncodingParameters/scaleResolutionDownBy}} to 2^(length of sendEncodings - encoding index - 1). This results in smaller-to-larger resolutions where the last encoding has no scaling applied to it, e.g. 4:2:1 if the length is 3.

   8. If the number of {{RTCRtpEncodingParameters}} now stored in sendEncodings is 1, then remove any {{RTCRtpCodingParameters/rid}} member from the lone entry.

      Providing a single, default {{RTCRtpEncodingParameters}} in sendEncodings allows the application to subsequently set encoding parameters using {{RTCRtpSender/setParameters}}, even when simulcast isn't used.

9. Create an RTCRtpSender with track, kind, 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 [[!RFC8829]]. When {{RTCPeerConnection/setRemoteDescription}} is called with a corresponding remote description that is able to receive multiple RTP encodings as defined in [[!RFC8829]], the {{RTCRtpSender}} may send multiple RTP encodings and the parameters retrieved via the transceiver's {{RTCRtpTransceiver/sender}}.{{RTCRtpSender/getParameters()}} will reflect the encodings negotiated.

10. Create an RTCRtpReceiver with kind and let receiver be the result.

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

12. Add transceiver to connection's [= set of transceivers =].

13. [= Update the negotiation-needed flag =] for connection.

14. Return transceiver.

Dictionary RTCRtpTransceiverInit Members

direction of type {{RTCRtpTransceiverDirection}}, defaulting to {{RTCRtpTransceiverDirection/"sendrecv"}}

The direction of the {{RTCRtpTransceiver}}.

streams of type sequence<{{MediaStream}}>

When the remote PeerConnection's track 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 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 {{RTCRtpSender/[[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 {{RTCRtpSender/[[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.

The codec capabilities returned affect the {{RTCRtpTransceiver/setCodecPreferences()}} algorithm and what inputs it throws {{InvalidModificationError}} on, and should also be consistent with information revealed by {{RTCPeerConnection/createOffer()}} and {{RTCPeerConnection/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.{{RTCRtpTransceiver/[[Sender]]}}).
4. If transceiver.{{RTCRtpTransceiver/[[Stopped]]}} is true, return a promise [= rejected =] with a newly [= exception/created =] {{InvalidStateError}}.
5. If sender.{{RTCRtpSender/[[LastReturnedParameters]]}} is null, return a promise [= rejected =] with a newly [= exception/created =] {{InvalidStateError}}.
6. Validate parameters by running the following steps:
   1. Let encodings be parameters.{{RTCRtpSendParameters/encodings}}.
   2. Let codecs be parameters.{{RTCRtpParameters/codecs}}.
   3. Let N be the number of {{RTCRtpEncodingParameters}} stored in sender.{{RTCRtpSender/[[SendEncodings]]}}.
   4. If any of the following conditions are met, return a promise [= rejected =] with a newly [= exception/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.{{RTCRtpSender/[[LastReturnedParameters]]}}. Note that this also applies to transactionId.

   5. Verify that each encoding in encodings has a {{RTCRtpEncodingParameters/scaleResolutionDownBy}} member whose value is greater than or equal to 1.0. If one of the {{RTCRtpEncodingParameters/scaleResolutionDownBy}} values does not meet this requirement, return a promise [= rejected =] with a newly [= exception/created =] {{RangeError}}.

7. Let p be a new promise.
8. In parallel, configure the media stack to use parameters to transmit sender.{{RTCRtpSender/[[SenderTrack]]}}.
   1. If the media stack is successfully configured with parameters, queue a task to run the following steps:
      1. Set sender.{{RTCRtpSender/[[LastReturnedParameters]]}} to null.
      2. Set sender.{{RTCRtpSender/[[SendEncodings]]}} to parameters.{{RTCRtpSendParameters/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 {{RTCError/errorDetail}} is set to {{RTCErrorDetailType/"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 {{RTCError/errorDetail}} is set to {{RTCErrorDetailType/"hardware-encoder-error"}} and abort these steps.
      3. For all other errors, [= reject =] p with a newly [= exception/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 {{RTCRtcpParameters/cname}} that cannot be changed are read-only. Other things, like bitrate, are controlled using limits such as {{RTCRtpEncodingParameters/maxBitrate}}, where the user agent needs to ensure it does not exceed the maximum bitrate specified by {{RTCRtpEncodingParameters/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.{{RTCRtpSender/[[LastReturnedParameters]]}} is not null, return sender.{{RTCRtpSender/[[LastReturnedParameters]]}}, and abort these steps.

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

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

4. Set sender.{{RTCRtpSender/[[LastReturnedParameters]]}} to result.

5. Queue a task that sets sender.{{RTCRtpSender/[[LastReturnedParameters]]}} to null.

6. Return result.

{{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 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 [= exception/created =] {{TypeError}}.

6. Return the result of [= chaining =] the following steps to connection's [= operations chain =]:

   1. If transceiver.{{RTCRtpTransceiver/[[Stopped]]}} is true, return a promise [= rejected =] with a newly [= exception/created =] {{InvalidStateError}}.

   2. Let p be a new promise.

   3. Let sending be true if transceiver.{{RTCRtpTransceiver/[[CurrentDirection]]}} is {{RTCRtpTransceiverDirection/"sendrecv"}} or {{RTCRtpTransceiverDirection/"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 [= exception/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.{{RTCPeerConnection/[[IsClosed]]}} is true, abort these steps.

         2. Set sender.{{RTCRtpSender/[[SenderTrack]]}} to withTrack.

         3. [= Resolve =] p with undefined.

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

setStreams

Sets the {{MediaStream}}s 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.{{RTCPeerConnection/[[IsClosed]]}} is true, [= exception/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.{{RTCRtpSender/[[AssociatedMediaStreamIds]]}} to an empty set.

6. For each stream in streams, add stream.id to {{RTCRtpSender/[[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.

Attributes

track of type {{MediaStreamTrack}}, readonly

The {{track}} attribute is the track that is associated with this {{RTCRtpReceiver}} object receiver.

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 {{RTCRtpReceiver/[[ReceiverTrack]]}} slot.

transport of type {{RTCDtlsTransport}}, readonly, nullable

The {{transport}} attribute is the transport over which media for the receiver's {{RTCRtpReceiver/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 {{RTCRtpReceiver/[[ReceiverTransport]]}} 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.

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

getParameters

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

When {{getParameters}} is called, the {{RTCRtpReceiveParameters}} dictionary is constructed as follows:

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

• {{RTCRtpParameters/codecs}} には、{{RTCRtpReceiver/[[ReceiveCodecs]]}} 内部スロットの値が設定されます。

  ローカルとリモートの両方の記述が、このコーデックのリストに影響を与える可能性があります。例えば、3つのコーデックが提供された場合、受信者はそれぞれのコーデックを受信する準備をし、{{getParameters}} からすべてのコーデックを返します。しかし、リモートエンドポイントが 2 つしか答えなかった場合、不在のコーデックは、受信者が受信の準備をする必要がないため、{{getParameters}} から返されなくなります。
• {{RTCRtpParameters/rtcp}}.{{RTCRtcpParameters/reducedSize}} は、受信機が縮小されたサイズの RTCP パケットを受信する準備が現在できている場合は true に設定され、そうでない場合は false に設定されます。{{RTCRtpParameters/rtcp}}.{{RTCRtcpParameters/cname}} は省略されます。

getContributingSources

Returns an {{RTCRtpContributingSource}} for each unique CSRC identifier received by this {{RTCRtpReceiver}} in the last 10 seconds, in descending {{RTCRtpContributingSource/timestamp}} order.

getSynchronizationSources

Returns an {{RTCRtpSynchronizationSource}} for each unique SSRC identifier received by this {{RTCRtpReceiver}} in the last 10 seconds, in descending {{RTCRtpContributingSource/timestamp}} order.

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}} indicating the most recent time a frame from an RTP packet, originating from this source, was delivered to the {{RTCRtpReceiver}}'s {{MediaStreamTrack}}. The {{timestamp}} is defined as {{Performance.timeOrigin}} + {{Performance.now()}} at that time.

source of type unsigned long, required

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

audioLevel of type double

Only present for audio receivers. This is a value between 0..1 (linear), where 1.0 represents 0 dBov, 0 represents silence, and 0.5 represents approximately 6 dBSPL change in the sound pressure level from 0 dBov.

For CSRCs, this MUST be converted from the level value defined in [[!RFC6465]] if the RFC 6465 header extension is present, otherwise this member MUST be absent.

For SSRCs, this MUST be converted from the level value defined in [[!RFC6464]]. If the RFC 6464 header extension is not present in the received packets (such as if the other endpoint is not a user agent or is a legacy endpoint), this value SHOULD be absent.

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.

To convert these values to the linear 0..1 range, a value of 127 is converted to 0, and all other values are converted using the equation: 10^(-rfc_level/20).

rtpTimestamp of type unsigned long, required

The RTP timestamp, as defined in [[!RFC3550]] Section 5.1, of the media played out at timestamp.

Attributes

mid of type DOMString, readonly, nullable

The {{mid}} attribute is the [= media stream "identification-tag" =] negotiated and present in the local and remote descriptions. On getting, the attribute MUST return the value of the {{RTCRtpTransceiver/[[Mid]]}} slot.

sender of type {{RTCRtpSender}}, readonly

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

receiver of type {{RTCRtpReceiver}}, readonly

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

direction of type {{RTCRtpTransceiverDirection}}

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

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

1. Let transceiver be the {{RTCRtpTransceiver}} object on which the getter is invoked.

2. If transceiver.{{RTCRtpTransceiver/[[Stopping]]}} is true, return {{RTCRtpTransceiverDirection/"stopped"}}.

3. Otherwise, return the value of the {{RTCRtpTransceiver/[[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 transceiver.{{RTCRtpTransceiver/[[Stopping]]}} is true, [= exception/throw =] an {{InvalidStateError}}.

4. Let newDirection be the argument to the setter.

5. If newDirection is equal to transceiver.{{RTCRtpTransceiver/[[Direction]]}}, abort these steps.

6. If newDirection is equal to {{RTCRtpTransceiverDirection/"stopped"}}, [= exception/throw =] a {{TypeError}}.

7. Set transceiver.{{RTCRtpTransceiver/[[Direction]]}} to newDirection.

8. Update the negotiation-needed flag for connection.

currentDirection of type {{RTCRtpTransceiverDirection}}, readonly, nullable

As defined in [[!RFC8829]], the currentDirection attribute indicates the current direction negotiated for this transceiver. The value of currentDirection is independent of the value of {{RTCRtpEncodingParameters}}.{{RTCRtpEncodingParameters/active}} since one cannot be deduced from the other. If this transceiver has never been represented in an offer/answer exchange, the value is null. If the transceiver is {{stopped}}, the value is {{RTCRtpTransceiverDirection/"stopped"}}.

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

1. Let transceiver be the {{RTCRtpTransceiver}} object on which the getter is invoked.

2. If transceiver.{{RTCRtpTransceiver/[[Stopped]]}} is true, return {{RTCRtpTransceiverDirection/"stopped"}}.

3. Otherwise, return the value of the {{RTCRtpTransceiver/[[CurrentDirection]]}} slot.

Methods

stop

Irreversibly marks the transceiver as {{stopping}}, unless it is already {{stopped}}. This will immediately cause the transceiver's sender to no longer send, and its receiver to no longer receive. Calling {{stop()}} also [= update the negotiation-needed flag | updates the negotiation-needed flag =] for the {{RTCRtpTransceiver}}'s associated {{RTCPeerConnection}}.

A stopping transceiver will cause future calls to {{RTCPeerConnection/createOffer}} to generate a zero port in the [= media description =] for the corresponding transceiver, as defined in [[!RFC8829]] (The user agent MUST treat a {{stopping}} transceiver as {{stopped}} for the purposes of RFC8829 only in this case). However, to avoid problems with [[RFC8843]], a transceiver that is {{stopping}}, but not {{stopped}}, will not affect {{RTCPeerConnection/createAnswer}}.

A stopped transceiver will cause future calls to {{RTCPeerConnection/createOffer}} or {{RTCPeerConnection/createAnswer}} to generate a zero port in the [= media description =] for the corresponding transceiver, as defined in [[!RFC8829]].

The transceiver will remain in the {{stopping}} state, unless it becomes {{stopped}} by {{RTCPeerConnection/setRemoteDescription}} processing a rejected m-line in a remote offer or answer.

A transceiver that is {{stopping}} but not {{stopped}} will always need negotiation. In practice, this means that calling {{stop()}} on a transceiver will cause the transceiver to become {{stopped}} eventually, provided negotiation is allowed to complete on both ends.

When the {{stop}} method is invoked, the user agent MUST run the following steps:

1. Let transceiver be the {{RTCRtpTransceiver}} object on which the method is invoked.

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

3. If connection.{{RTCPeerConnection/[[IsClosed]]}} is true, [= exception/throw =] an {{InvalidStateError}}.

4. If transceiver.{{RTCRtpTransceiver/[[Stopping]]}} is true, abort these steps.

5. [= Stop sending and receiving =] with transceiver.

6. Update the negotiation-needed flag for connection.

The stop sending and receiving algorithm given a transceiver and, optionally, a disappear boolean defaulting to false, is as follows:

1. Let sender be transceiver.{{RTCRtpTransceiver/[[Sender]]}}.

2. Let receiver be transceiver.{{RTCRtpTransceiver/[[Receiver]]}}.

3. Stop sending media with sender.

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

5. Stop receiving media with receiver.

6. If disappear is false, execute the steps for receiver.{{RTCRtpReceiver/[[ReceiverTrack]]}} to be ended. This fires an event.

7. Set transceiver.{{RTCRtpTransceiver/[[Direction]]}} to {{RTCRtpTransceiverDirection/"inactive"}}.

8. Set transceiver.{{RTCRtpTransceiver/[[Stopping]]}} to true.

The stop the RTCRtpTransceiver algorithm given a transceiver and, optionally, a disappear boolean defaulting to false, is as follows:

1. If transceiver.{{RTCRtpTransceiver/[[Stopping]]}} is false, [= stop sending and receiving =] with transceiver and disappear.

2. Set transceiver.{{RTCRtpTransceiver/[[Stopped]]}} to true.

3. Set transceiver.{{RTCRtpTransceiver/[[Receptive]]}} to false.

4. Set transceiver.{{RTCRtpTransceiver/[[CurrentDirection]]}} to null.

setCodecPreferences

The {{setCodecPreferences}} method overrides the default codec preferences used by the user agent. When generating a session description using either {{RTCPeerConnection/createOffer}} or {{RTCPeerConnection/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}}.

This method allows applications to disable the negotiation of specific codecs (including RTX/RED/FEC). 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 {{RTCPeerConnection/createOffer}} and {{RTCPeerConnection/createAnswer}} that include this {{RTCRtpTransceiver}} until this method is called again. Setting codecs to an empty sequence resets codec preferences to any default value.

Codecs have their payload types listed under each m= section in the SDP, defining the mapping between payload types and codecs. These payload types are referenced by the m=video or m=audio lines in the order of preference, and codecs that are not negotiated do not appear in this list as defined in section 5.2.1 of [[!RFC8829]]. A previously negotiated codec that is subsequently removed disappears from the m=video or m=audio line, and while its codec payload type is not to be reused in future offers or answers, its payload type may also be removed from the mapping of payload types in the SDP.

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

Due to a recommendation in [[!SDP]], calls to {{RTCPeerConnection/createAnswer}} SHOULD use only the common subset of the codec preferences and the codecs that appear in the offer. For example, if codec preferences are "C, B, A", but only codecs "A, B" were offered, the answer should only contain codecs "B, A". However, [[!RFC8829]] allows adding codecs that were not in the offer, so implementations can behave differently.

When {{setCodecPreferences()}} is invoked, the user agent MUST run the following steps:

1. Let transceiver be the {{RTCRtpTransceiver}} object this method was invoked on.

2. Let codecs be the first argument.

3. If codecs is an empty list, set transceiver.{{RTCRtpTransceiver/[[PreferredCodecs]]}} to codecs and abort these steps.

4. Remove any duplicate values in codecs. Start at the back of the list such that the priority of the codecs is maintained; the index of the first occurrence of a codec within the list is the same before and after this step.

5. Let kind be the transceiver's [= transceiver kind =].

6. If the intersection between codecs and {{RTCRtpSender}}.{{RTCRtpSender/getCapabilities}}(kind).{{RTCRtpParameters/codecs}} or the intersection between codecs and {{RTCRtpReceiver}}.{{RTCRtpReceiver/getCapabilities}}(kind).{{RTCRtpParameters/codecs}} only contains RTX, RED or FEC codecs or is an empty set, throw {{InvalidModificationError}}. This ensures that we always have something to offer, regardless of transceiver.{{RTCRtpTransceiver/direction}}.

7. Let codecCapabilities be the union of {{RTCRtpSender}}.{{RTCRtpSender/getCapabilities}}(kind).{{RTCRtpParameters/codecs}} and {{RTCRtpReceiver}}.{{RTCRtpReceiver/getCapabilities}}(kind).{{RTCRtpParameters/codecs}}.

8. For each codec in codecs,

   1. If codec is not in codecCapabilities, throw {{InvalidModificationError}}.

9. Set transceiver.{{RTCRtpTransceiver/[[PreferredCodecs]]}} to codecs.

If set, the offerer's codec preferences will decide the order of the codecs in the offer. If the answerer does not have any codec preferences then the same order will be used in the answer. However, if the answerer also has codec preferences, these preferences override the order in the answer. In this case, the offerer's preferences would affect which codecs were on offer but not the final order.

Attributes

iceTransport of type {{RTCIceTransport}}, readonly

The {{iceTransport}} 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 {{RTCDtlsTransport/[[DtlsTransportState]]}} slot.

onstatechange of type EventHandler

The event type of this event handler is {{RTCDtlsTransport/statechange}}.

onerror of type EventHandler

The event type of this event handler is {{RTCDtlsTransport/error}}.

Methods

getRemoteCertificates

Returns the value of {{RTCDtlsTransport/[[RemoteCertificates]]}}.

Attributes

role of type {{RTCIceRole}}, readonly

The {{role}} attribute MUST, on getting, return the value of the [[\IceRole]] internal slot.

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 {{RTCIceComponent/"rtp"}}.

state of type {{RTCIceTransportState}}, readonly

The {{state}} attribute MUST, on getting, return the value of the {{RTCIceTransport/[[IceTransportState]]}} slot.

gatheringState of type {{RTCIceGathererState}}, readonly

The {{gatheringState}} attribute MUST, on getting, return the value of the {{RTCIceTransport/[[IceGathererState]]}} slot.

onstatechange of type EventHandler

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

ongatheringstatechange of type EventHandler

This event handler, of event handler event type {{gatheringstatechange}}, MUST be fired any time the {{RTCIceTransport}} [= ICE gathering state =] changes.

onselectedcandidatepairchange of type EventHandler

This event handler, of event handler event type {{RTCIceTransport/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 {{RTCPeerConnection/onicecandidate}}.

getRemoteCandidates

Returns a sequence describing the remote ICE candidates received by this {{RTCIceTransport}} via {{RTCPeerConnection/addIceCandidate()}}.

{{getRemoteCandidates}} will not expose peer reflexive candidates since they are not received via {{RTCPeerConnection/addIceCandidate()}}.

getSelectedCandidatePair

Returns the selected candidate pair on which packets are sent. This method MUST return the value of the {{RTCIceTransport/[[SelectedCandidatePair]]}} slot. When {{RTCIceTransport}}.{{RTCIceTransport/state}} is {{RTCIceTransportState/"new"}} or {{RTCIceTransportState/"closed"}} {{getSelectedCandidatePair}} returns null.

getLocalParameters

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

getRemoteParameters

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

Constructors

RTCTrackEvent.constructor()

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 {{MediaStream}}s 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}} member represents the {{RTCRtpReceiver}} object associated with the event.

track of type {{MediaStreamTrack}}, required

The {{track}} member represents the {{MediaStreamTrack}} object that is associated with the {{RTCRtpReceiver}} identified by {{RTCTrackEventInit/receiver}}.

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

The {{streams}} member is an array of {{MediaStream}} objects representing the {{MediaStream}}s 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 {{RTCPeerConnection/[[SctpTransport]]}} internal slot.

ondatachannel of type EventHandler

The event type of this event handler is {{RTCPeerConnection/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.{{RTCPeerConnection/[[IsClosed]]}} is true, [= exception/throw =] an {{InvalidStateError}}.

3. [= Create an RTCDataChannel =], channel.

4. Initialize channel.{{RTCDataChannel/[[DataChannelLabel]]}} to the value of the first argument.

5. If the UTF-8 representation of {{RTCDataChannel/[[DataChannelLabel]]}} is longer than 65535 bytes, [= exception/throw =] a {{TypeError}}.

6. Let options be the second argument.

7. Initialize channel.{{RTCDataChannel/[[MaxPacketLifeTime]]}} to option.{{RTCDataChannelInit/maxPacketLifeTime}}, if present, otherwise null.

8. Initialize channel.{{RTCDataChannel/[[MaxRetransmits]]}} to option.{{RTCDataChannelInit/maxRetransmits}}, if present, otherwise null.

9. Initialize channel.{{RTCDataChannel/[[Ordered]]}} to option.{{RTCDataChannelInit/ordered}}.

10. Initialize channel.{{RTCDataChannel/[[DataChannelProtocol]]}} to option.{{RTCDataChannelInit/protocol}}.

11. If the UTF-8 representation of {{RTCDataChannel/[[DataChannelProtocol]]}} is longer than 65535 bytes, [= exception/throw =] a {{TypeError}}.

12. Initialize channel.{{RTCDataChannel/[[Negotiated]]}} to option.{{RTCDataChannelInit/negotiated}}.

13. Initialize channel.{{RTCDataChannel/[[DataChannelId]]}} to the value of option.{{RTCDataChannelInit/id}}, if it is present and {{RTCDataChannel/[[Negotiated]]}} is true, otherwise null.

    This means the {{RTCDataChannelInit/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 [[RFC8832]].

14. If {{RTCDataChannel/[[Negotiated]]}} is true and {{RTCDataChannel/[[DataChannelId]]}} is null, [= exception/throw =] a {{TypeError}}.

15. If both {{RTCDataChannel/[[MaxPacketLifeTime]]}} and {{RTCDataChannel/[[MaxRetransmits]]}} attributes are set (not null), [= exception/throw =] a {{TypeError}}.

16. If a setting, either {{RTCDataChannel/[[MaxPacketLifeTime]]}} or {{RTCDataChannel/[[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.

17. If {{RTCDataChannel/[[DataChannelId]]}} is equal to 65535, which is greater than the maximum allowed ID of 65534 but still qualifies as an unsigned short, [= exception/throw =] a {{TypeError}}.

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

    If the {{RTCDataChannel/[[DataChannelId]]}} slot is null after this step, it will be populated during the [= RTCSctpTransport connected =] procedure.

19. Let transport be connection.{{RTCPeerConnection/[[SctpTransport]]}}.

    If the {{RTCDataChannel/[[DataChannelId]]}} slot is not null, transport is in the {{RTCSctpTransportState/"connected"}} state and {{RTCDataChannel/[[DataChannelId]]}} is greater or equal to transport.{{RTCSctpTransport/[[MaxChannels]]}}, [= exception/throw =] an {{OperationError}}.

20. If channel is the first {{RTCDataChannel}} created on connection, [= update the negotiation-needed flag =] for connection.

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

22. Create channel's associated [= underlying data transport =] and configure it according to the relevant properties of channel.

Attributes

label of type USVString, readonly

The {{label}} attribute represents a label that can be used to distinguish this {{RTCDataChannel}} object from other {{RTCDataChannel}} objects. Scripts are allowed to create multiple {{RTCDataChannel}} objects with the same label. On getting, the attribute MUST return the value of the {{RTCDataChannel/[[DataChannelLabel]]}} slot.

ordered of type boolean, readonly

The {{ordered}} attribute returns true if the {{RTCDataChannel}} is ordered, and false if out of order delivery is allowed. On getting, the attribute MUST return the value of the {{RTCDataChannel/[[Ordered]]}} slot.

maxPacketLifeTime of type unsigned short, readonly, nullable

The {{maxPacketLifeTime}} attribute returns the length of the time window (in milliseconds) during which transmissions and retransmissions may occur in unreliable mode. On getting, the attribute MUST return the value of the {{RTCDataChannel/[[MaxPacketLifeTime]]}} slot.

maxRetransmits of type unsigned short, readonly, nullable

The {{maxRetransmits}} attribute returns the maximum number of retransmissions that are attempted in unreliable mode. On getting, the attribute MUST return the value of the {{RTCDataChannel/[[MaxRetransmits]]}} slot.

protocol of type USVString, readonly

The {{protocol}} attribute returns the name of the sub-protocol used with this {{RTCDataChannel}}. On getting, the attribute MUST return the value of the {{RTCDataChannel/[[DataChannelProtocol]]}} slot.

negotiated of type boolean, readonly

The {{negotiated}} attribute returns true if this {{RTCDataChannel}} was negotiated by the application, or false otherwise. On getting, the attribute MUST return the value of the {{RTCDataChannel/[[Negotiated]]}} slot.

id of type unsigned short, readonly, nullable

The {{id}} attribute returns the ID for this {{RTCDataChannel}}. The value is initially null, which is what will be returned if the ID was not provided at channel creation time, and the DTLS role of the SCTP transport has not yet been negotiated. Otherwise, it will return the ID that was either selected by the script or generated by the user agent according to [[RFC8832]]. After the ID is set to a non-null value, it will not change. On getting, the attribute MUST return the value of the {{RTCDataChannel/[[DataChannelId]]}} slot.

readyState of type {{RTCDataChannelState}}, readonly

The {{readyState}} attribute represents the state of the {{RTCDataChannel}} object. On getting, the attribute MUST return the value of the {{RTCDataChannel/[[ReadyState]]}} slot.

bufferedAmount of type unsigned long, readonly

The {{bufferedAmount}} attribute MUST, on getting, return the value of the {{RTCDataChannel/[[BufferedAmount]]}} slot. The attribute exposes the number of bytes of application data (UTF-8 text and binary data) that have been queued using {{RTCDataChannel/send()}}. Even though the data transmission can occur in parallel, the returned value MUST NOT be decreased before the current task yielded back to the event loop to prevent race conditions. The value does not include framing overhead incurred by the protocol, or buffering done by the operating system or network hardware. The value of the {{RTCDataChannel/[[BufferedAmount]]}} slot will only increase with each call to the {{RTCDataChannel/send()}} method as long as the {{RTCDataChannel/[[ReadyState]]}} slot is {{RTCDataChannelState/"open"}}; however, the slot does not reset to zero once the channel closes. When the [= underlying data transport =] sends data from its queue, the user agent MUST queue a task that reduces {{RTCDataChannel/[[BufferedAmount]]}} with the number of bytes that was sent.

bufferedAmountLowThreshold of type unsigned long

The {{bufferedAmountLowThreshold}} attribute sets the threshold at which the {{RTCDataChannel/bufferedAmount}} is considered to be low. When the {{RTCDataChannel/bufferedAmount}} decreases from above this threshold to equal or below it, the {{bufferedamountlow}} event fires. The {{RTCDataChannel/bufferedAmountLowThreshold}} is initially zero on each new {{RTCDataChannel}}, but the application may change its value at any time.

onopen of type EventHandler

The event type of this event handler is {{RTCDataChannel/open}}.

onbufferedamountlow of type EventHandler

The event type of this event handler is {{bufferedamountlow}}.

onerror of type EventHandler

The event type of this event handler is {{RTCErrorEvent}}. {{RTCError/errorDetail}} contains "sctp-failure", {{RTCError/sctpCauseCode}} contains the SCTP Cause Code value, and {{DOMException/message}} contains the SCTP Cause-Specific-Information, possibly with additional text.

onclosing of type EventHandler

The event type of this event handler is {{RTCDataChannel/closing}}.

onclose of type EventHandler

The event type of this event handler is close.

onmessage of type EventHandler

The event type of this event handler is {{RTCDataChannel/message}}.

binaryType of type BinaryType

The {{binaryType}} attribute MUST, on getting, return the value to which it was last set. On setting, if the new value is either the string "blob" or the string "arraybuffer", then set the IDL attribute to this new value. Otherwise, [= exception/throw =] a {{SyntaxError}}. When an {{RTCDataChannel}} object is created, the {{RTCDataChannel/binaryType}} attribute MUST be initialized to the string "blob".

This attribute controls how binary data is exposed to scripts. See Web Socket's {{WebSocket/binaryType}}.

Methods

close()

Closes the {{RTCDataChannel}}. It may be called regardless of whether the {{RTCDataChannel}} object was created by this peer or the remote peer.

When the {{close}} method is called, the user agent MUST run the following steps:

1. Let channel be the {{RTCDataChannel}} object which is about to be closed.

2. If channel.{{RTCDataChannel/[[ReadyState]]}} is {{RTCDataChannelState/"closing"}} or {{RTCDataChannelState/"closed"}}, then abort these steps.

3. Set channel.{{RTCDataChannel/[[ReadyState]]}} to {{RTCDataChannelState/"closing"}}.

4. If the [= closing procedure =] has not started yet, start it.

send

Run the steps described by the [= send() algorithm =] with argument type string object.

send

Run the steps described by the [= send() algorithm =] with argument type {{Blob}} object.

send

Run the steps described by the [= send() algorithm =] with argument type {{ArrayBuffer}} object.

send

Run the steps described by the [= send() algorithm =] with argument type {{ArrayBufferView}} object.

The send() method is overloaded to handle different data argument types. When any version of the method is called, the user agent MUST run the following steps:

1. Let channel be the {{RTCDataChannel}} object on which data is to be sent.

2. If channel.{{RTCDataChannel/[[ReadyState]]}} is not {{RTCDataChannelState/"open"}}, [= exception/throw =] an {{InvalidStateError}}.

3. Execute the sub step that corresponds to the type of the methods argument:

   • string object:

     Let data be a byte buffer that represents the result of encoding the method's argument as UTF-8.

   • {{Blob}} object:

     Let data be the raw data represented by the {{Blob}} object.

     Although the actual retrieval of data from a {{Blob}} object can happen asynchronously, the user agent will make sure to queue the data on the channel's [= underlying data transport =] in the same order as the send method is called. The byte size of data needs to be known synchronously.

   • {{ArrayBuffer}} object:

     Let data be the data stored in the buffer described by the {{ArrayBuffer}} object.

   • {{ArrayBufferView}} object:

     Let data be the data stored in the section of the buffer described by the {{ArrayBuffer}} object that the {{ArrayBufferView}} object references.

   Any data argument type this method has not been overloaded with will result in a {{TypeError}}. This includes null and undefined.

4. If the byte size of data exceeds the value of {{RTCSctpTransport/maxMessageSize}} on channel's associated {{RTCSctpTransport}}, [= exception/throw =] a {{TypeError}}.

5. Queue data for transmission on channel's [= underlying data transport =]. If queuing data is not possible because not enough buffer space is available, [= exception/throw =] an {{OperationError}}.

   The actual transmission of data occurs in parallel. If sending data leads to an SCTP-level error, the application will be notified asynchronously through {{RTCDataChannel/onerror}}.

6. Increase the value of the {{RTCDataChannel/[[BufferedAmount]]}} slot by the byte size of data.

Dictionary RTCDataChannelInit Members

ordered of type boolean, defaulting to true

If set to false, data is allowed to be delivered out of order. The default value of true, guarantees that data will be delivered in order.

maxPacketLifeTime of type unsigned short

Limits the time (in milliseconds) during which the channel will transmit or retransmit data if not acknowledged. This value may be clamped if it exceeds the maximum value supported by the user agent.

maxRetransmits of type unsigned short

Limits the number of times a channel will retransmit data if not successfully delivered. This value may be clamped if it exceeds the maximum value supported by the user agent.

protocol of type USVString, defaulting to ""

Subprotocol name used for this channel.

negotiated of type boolean, defaulting to false

The default value of false tells the user agent to announce the channel in-band and instruct the other peer to dispatch a corresponding {{RTCDataChannel}} object. If set to true, it is up to the application to negotiate the channel and create an {{RTCDataChannel}} object with the same {{RTCDataChannel/id}} at the other peer.

If set to true, the application must also take care to not send a message until the other peer has created a data channel to receive it. Receiving a message on an SCTP stream with no associated data channel is undefined behavior, and it may be silently dropped. This will not be possible as long as both endpoints create their data channel before the first offer/answer exchange is complete.

id of type unsigned short

Sets the channel ID when {{RTCDataChannelInit/negotiated}} is true. Ignored when {{RTCDataChannelInit/negotiated}} is false.

Constructors

RTCDataChannelEvent.constructor()

Attributes

channel of type {{RTCDataChannel}}, readonly

The {{channel}} attribute represents the {{RTCDataChannel}} object associated with the event.

Dictionary RTCDataChannelEventInit Members

channel of type {{RTCDataChannel}}, required

The {{RTCDataChannel}} object to be announced by the event.

Attributes

dtmf of type {{RTCDTMFSender}}, readonly, nullable

On getting, the {{dtmf}} attribute returns the value of the {{RTCRtpSender/[[Dtmf]]}} internal slot, which represents a {{RTCDTMFSender}} which can be used to send DTMF, or null if unset. The {{RTCRtpSender/[[Dtmf]]}} internal slot is set when the kind of an {{RTCRtpSender}}'s {{RTCRtpSender/[[SenderTrack]]}} is "audio".

Attributes

ontonechange of type EventHandler

The event type of this event handler is {{RTCDTMFSender/tonechange}}.

canInsertDTMF of type boolean, readonly

Whether the {{RTCDTMFSender}} dtmfSender is capable of sending DTMF. On getting, the user agent MUST return the result of running [= determine if DTMF can be sent =] for dtmfSender.

toneBuffer of type DOMString, readonly

The {{toneBuffer}} attribute MUST return a list of the tones remaining to be played out. For the syntax, content, and interpretation of this list, see {{insertDTMF}}.

Methods

insertDTMF

An {{RTCDTMFSender}} object's {{insertDTMF}} method is used to send DTMF tones.

The tones parameter is treated as a series of characters. The characters 0 through 9, A through D, #, and * generate the associated DTMF tones. The characters a to d MUST be normalized to uppercase on entry and are equivalent to A to D. As noted in [[RTCWEB-AUDIO]] Section 3, support for the characters 0 through 9, A through D, #, and * are required. The character ',' MUST be supported, and indicates a delay of 2 seconds before processing the next character in the tones parameter. All other characters (and only those other characters) MUST be considered unrecognized.

The duration parameter indicates the duration in ms to use for each character passed in the tones parameters. The duration cannot be more than 6000 ms or less than 40 ms. The default duration is 100 ms for each tone.

The interToneGap parameter indicates the gap between tones in ms. The user agent clamps it to at least 30 ms and at most 6000 ms. The default value is 70 ms.

The browser MAY increase the duration and interToneGap times to cause the times that DTMF start and stop to align with the boundaries of RTP packets but it MUST not increase either of them by more than the duration of a single RTP audio packet.

When the {{insertDTMF()}} method is invoked, the user agent MUST run the following steps:

1. Let sender be the {{RTCRtpSender}} used to send DTMF.

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

3. Let dtmf be the {{RTCDTMFSender}} associated with sender.
4. If [= determine if DTMF can be sent =] for dtmf returns false, [= exception/throw =] an {{InvalidStateError}}.
5. Let tones be the method's first argument.
6. Let duration be the method's second argument.
7. Let interToneGap be the method's third argument.
8. If tones contains any {{unrecognized}} characters, [= exception/throw =] an {{InvalidCharacterError}}.
9. Set the object's {{RTCDTMFSender/[[ToneBuffer]]}} slot to tones.
10. Set dtmf.{{RTCDTMFSender/[[Duration]]}} to the value of duration.
11. Set dtmf.{{RTCDTMFSender/[[InterToneGap]]}} to the value of interToneGap.
12. If the value of duration is less than 40 ms, set dtmf.{{RTCDTMFSender/[[Duration]]}} to 40 ms.
13. If the value of duration parameter is greater than 6000 ms, set dtmf.{{RTCDTMFSender/[[Duration]]}} to 6000 ms.
14. If the value of interToneGap is less than 30 ms, set dtmf.{{RTCDTMFSender/[[InterToneGap]]}} to 30 ms.
15. If the value of interToneGap is greater than 6000 ms, set dtmf.{{RTCDTMFSender/[[InterToneGap]]}} to 6000 ms.
16. If [[\ToneBuffer]] slot is an empty string, abort these steps.
17. If a Playout task is scheduled to be run, abort these steps; otherwise queue a task that runs the following steps (Playout task):
    1. If transceiver.{{RTCRtpTransceiver/[[CurrentDirection]]}} is neither {{RTCRtpTransceiverDirection/"sendrecv"}} nor {{RTCRtpTransceiverDirection/"sendonly"}}, abort these steps.
    2. If the {{RTCDTMFSender/[[ToneBuffer]]}} slot contains the empty string, [= fire an event =] named {{RTCDTMFSender/tonechange}} using the {{RTCDTMFToneChangeEvent}} interface with the {{RTCDTMFToneChangeEvent/tone}} attribute set to an empty string at the {{RTCDTMFSender}} object and abort these steps.
    3. Remove the first character from the {{RTCDTMFSender/[[ToneBuffer]]}} slot and let that character be tone.
    4. If tone is "," delay sending tones for 2000 ms on the associated RTP media stream, and queue a task to be executed in 2000 ms from now that runs the steps labelled Playout task.
    5. If tone is not "," start playout of tone for {{RTCDTMFSender/[[Duration]]}} ms on the associated RTP media stream, using the appropriate codec, then queue a task to be executed in {{RTCDTMFSender/[[Duration]]}} + {{RTCDTMFSender/[[InterToneGap]]}} ms from now that runs the steps labelled Playout task.
    6. [= Fire an event =] named {{RTCDTMFSender/tonechange}} using the {{RTCDTMFToneChangeEvent}} interface with the {{RTCDTMFToneChangeEvent/tone}} attribute set to tone at the {{RTCDTMFSender}} object.

Since {{insertDTMF}} replaces the tone buffer, in order to add to the DTMF tones being played, it is necessary to call {{insertDTMF}} with a string containing both the remaining tones (stored in the {{RTCDTMFSender/[[ToneBuffer]]}} slot) and the new tones appended together. Calling {{insertDTMF}} with an empty tones parameter can be used to cancel all tones queued to play after the currently playing tone.

Constructors

RTCDTMFToneChangeEvent.constructor()

Attributes

tone of type DOMString, readonly

The {{tone}} attribute contains the character for the tone (including ",") that has just begun playout (see {{RTCDTMFSender/insertDTMF}} ). If the value is the empty string, it indicates that the {{RTCDTMFSender/[[ToneBuffer]]}} slot is an empty string and that the previous tones have completed playback.

Dictionary RTCDTMFToneChangeEventInit Members

tone of type DOMString, defaulting to ""

The {{tone}} attribute contains the character for the tone (including ",") that has just begun playout (see {{RTCDTMFSender/insertDTMF}} ). If the value is the empty string, it indicates that the {{RTCDTMFSender/[[ToneBuffer]]}} slot is an empty string and that the previous tones have completed playback.

Methods

getStats

Gathers stats for the given [= selector =] and reports the result asynchronously.

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

1. Let selectorArg be the method's first argument.

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

3. If selectorArg is null, let selector be null.

4. If selectorArg is a {{MediaStreamTrack}} let selector be an {{RTCRtpSender}} or {{RTCRtpReceiver}} on connection which {{RTCRtpSender/track}} attribute matches selectorArg. If no such sender or receiver exists, or if more than one sender or receiver fit this criteria, return a promise [= rejected =] with a newly [= exception/created =] {{InvalidAccessError}}.

5. Let p be a new promise.

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

7. Return p.

Dictionary {{RTCStats}} Members

timestamp of type DOMHighResTimeStamp

The {{timestamp}}, of type {{DOMHighResTimeStamp}}, associated with this object. The time is relative to the UNIX epoch (Jan 1, 1970, UTC). For statistics that came from a remote source (e.g., from received RTCP packets), {{timestamp}} represents the time at which the information arrived at the local endpoint. The remote timestamp can be found in an additional field in an {{RTCStats}}-derived dictionary, if applicable.

type of type {{RTCStatsType}}

The type of this object.

The {{type}} attribute MUST be initialized to the name of the most specific type this {{RTCStats}} dictionary represents.

id of type DOMString

A unique {{id}} that is associated with the object that was inspected to produce this {{RTCStats}} object. Two {{RTCStats}} objects, extracted from two different {{RTCStatsReport}} objects, MUST have the same id if they were produced by inspecting the same underlying object.

Stats ids MUST NOT be predictable by an application. This prevents applications from depending on a particular user agent's way of generating ids, since this prevents an application from getting stats objects by their id unless they have already read the id of that specific stats object.

User agents are free to pick any format for the id as long as it meets the requirements above.

A user agent can turn a predictably generated string into an unpredictable string using a hash function, as long as it uses a salt that is unique to the peer connection. This allows an implementation to have predictable ids internally, which may make it easier to guarantee that stats objects have stable ids across getStats() calls.