See also translations.
Initial Author of this Specification was Ian Hickson, Google Inc., with
the following copyright statement:
© Copyright 2004-2011 Apple Computer, Inc., Mozilla Foundation, and Opera
Software ASA. You are granted a license to use, reproduce and create
derivative works of this document. All subsequent changes since 26 July
2011 done by the W3C WebRTC Working Group are under the following
Copyright:
Copyright © 2011-2023 World Wide Web Consortium. W3C® liability, trademark and document use rules apply.
This document defines a set of ECMAScript APIs in WebIDL to allow media and generic application data to be sent to and received from another browser or device implementing the appropriate set of real-time protocols. This specification is being developed in conjunction with a protocol specification developed by the IETF RTCWEB group and an API specification to get access to local media devices.
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document includes Candidate Amendments to the current W3C Recommendation dated January 26, 2021.
Its associated test suite has been used to build an implementation report of the API at the time of its initial publication as a Recommendation.
This document was published by the Web Real-Time Communications Working Group as a Recommendation using the Recommendation track. It includes candidate amendments, introducing substantive changes and new features since the previous Recommendation.
W3C recommends the wide deployment of this specification as a standard for the Web.
A W3C Recommendation is a specification that, after extensive consensus-building, is endorsed by W3C and its Members, and has commitments from Working Group members to royalty-free licensing for implementations. Future updates to this Recommendation may incorporate new features.
Candidate additions are marked in the document.
Candidate corrections are marked in the document.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 2 November 2021 W3C Process Document.
This section is non-normative.
There are a number of facets to peer-to-peer communications and video-conferencing in HTML covered by this specification:
This document defines the APIs used for these features. This specification is being developed in conjunction with a protocol specification developed by the IETF RTCWEB group and an API specification to get access to local media devices [GETUSERMEDIA] developed by the WebRTC Working Group. An overview of the system can be found in [RFC8825] and [RFC8826].
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.
The EventHandler
interface, representing a callback used for event
handlers, is defined in [HTML].
The concepts queue a task and networking task source are defined in [HTML].
The concept fire an event is defined in [DOM].
The terms event, event handlers and event handler event types are defined in [HTML].
Performance
.timeOrigin
and Performance
.now
()
are defined in
[hr-time].
The terms serializable objects, serialization steps, and deserialization steps are defined in [HTML].
The terms MediaStream
, MediaStreamTrack
, and
MediaStreamConstraints
are defined in [GETUSERMEDIA]. Note that
MediaStream
is extended in 9.2
MediaStream
in this document while MediaStreamTrack
is extended in 9.3
MediaStreamTrack in this document.
The term Blob
is defined in [FILEAPI].
The term media description is defined in [RFC4566].
The term media transport is defined in [RFC7656].
The term generation is defined in [RFC8838] Section 2.
The terms stats object and monitored object are defined in [WEBRTC-STATS].
When referring to exceptions, the terms throw and created are defined in [WEBIDL].
The callback VoidFunction
is defined in [WEBIDL].
The term "throw" is used as specified in [INFRA]: it terminates the current processing steps.
The terms fulfilled, rejected, resolved, and settled used in the context of Promises are defined in [ECMASCRIPT-6.0].
The AlgorithmIdentifier is defined in [WebCryptoAPI].
The general principles for Javascript APIs apply, including the
principle of run-to-completion
and no-data-races as defined in [API-DESIGN-PRINCIPLES]. That is,
while a task is running, external events do not influence what's
visible to the Javascript application. For example, the amount of data
buffered on a data channel will increase due to "send" calls while
Javascript is executing, and the decrease due to packets being sent
will be visible after a task checkpoint.
It is the responsibility of the user agent to make sure the set of
values presented to the application is consistent - for instance that
getContributingSources() (which is synchronous) returns values for all
sources measured at the same time.
This section is non-normative.
An RTCPeerConnection
instance allows an application to establish
peer-to-peer communications with another RTCPeerConnection
instance in another browser, or to another endpoint implementing the
required protocols. Communications are coordinated by the exchange of
control messages (called a signaling protocol) over a signaling
channel which is provided by unspecified means, but generally by a
script in the page via the server, e.g. using WebSocket
or
XMLHttpRequest
.
The RTCConfiguration
defines a set of parameters to configure
how the peer-to-peer communication established via
RTCPeerConnection
is established or re-established.
WebIDLdictionary RTCConfiguration
{
sequence<RTCIceServer
> iceServers
= [];
RTCIceTransportPolicy
iceTransportPolicy
= "all";
RTCBundlePolicy
bundlePolicy
= "balanced";
RTCRtcpMuxPolicy
rtcpMuxPolicy
= "require";
sequence<RTCCertificate
> certificates
= [];
[EnforceRange] octet iceCandidatePoolSize
= 0;
};
RTCConfiguration
dictionary, aligning it with current implementations (PR #2691)RTCConfiguration
Members
iceServers
of type sequence<RTCIceServer
>
An array of objects describing servers available to be used by ICE, such as STUN and TURN servers.
iceTransportPolicy
of type
RTCIceTransportPolicy
.
Indicates which candidates the ICE Agent is allowed to use.
bundlePolicy
of type RTCBundlePolicy
.
Indicates which media-bundling policy to use when gathering ICE candidates.
rtcpMuxPolicy
of type RTCRtcpMuxPolicy
.
Indicates which rtcp-mux policy to use when gathering ICE candidates.
certificates
of type sequence<RTCCertificate
>
A set of certificates that the
uses
to authenticate.
RTCPeerConnection
Valid values for this parameter are created through calls
to the generateCertificate
()
function.
Although any given DTLS connection will use only one
certificate, this attribute allows the caller to provide
multiple certificates that support different algorithms.
The final certificate will be selected based on the DTLS
handshake, which establishes which certificates are
allowed. The
implementation selects
which of the certificates is used for a given connection;
how certificates are selected is outside the scope of this
specification.
RTCPeerConnection
Existing implementations only utilize the first certificate provided; the others are ignored.
If this value is absent, then a default set of certificates
is generated for each
instance.
RTCPeerConnection
This option allows applications to establish key
continuity. An
can be persisted in
[INDEXEDDB] and reused. Persistence and reuse also
avoids the cost of key generation.
RTCCertificate
The value for this configuration option cannot change after its value is initially selected.
iceCandidatePoolSize
of type
octet, defaulting to
0
Size of the prefetched ICE pool as defined in [RFC8829] (section 3.5.4. and section 4.1.1.).
RTCConfiguration
Members
iceServers
of type sequence<RTCIceServer
>,
defaulting to []
.
An array of objects describing servers available to be used by ICE, such as STUN and TURN servers. If the number of ICE servers exceeds an implementation-defined limit, ignore the ICE servers above the threshold. This implementation defined limit MUST be at least 32.
iceTransportPolicy
of type
RTCIceTransportPolicy
,
defaulting to "all"
.
Indicates which candidates the ICE Agent is allowed to use.
bundlePolicy
of type RTCBundlePolicy
, defaulting to
"balanced"
.
Indicates which media-bundling policy to use when gathering ICE candidates.
rtcpMuxPolicy
of type RTCRtcpMuxPolicy
, defaulting to
"require"
.
Indicates which rtcp-mux policy to use when gathering ICE candidates.
certificates
of type sequence<RTCCertificate
>,
defaulting to []
.
A set of certificates that the RTCPeerConnection
uses
to authenticate.
Valid values for this parameter are created through calls
to the generateCertificate
()
function.
Although any given DTLS connection will use only one
certificate, this attribute allows the caller to provide
multiple certificates that support different algorithms.
The final certificate will be selected based on the DTLS
handshake, which establishes which certificates are
allowed. The RTCPeerConnection
implementation selects
which of the certificates is used for a given connection;
how certificates are selected is outside the scope of this
specification.
Existing implementations only utilize the first certificate provided; the others are ignored.
If this value is absent, then a default set of certificates
is generated for each RTCPeerConnection
instance.
This option allows applications to establish key
continuity. An RTCCertificate
can be persisted in
[INDEXEDDB] and reused. Persistence and reuse also
avoids the cost of key generation.
The value for this configuration option cannot change after its value is initially selected.
iceCandidatePoolSize
of type
octet, defaulting to
0
Size of the prefetched ICE pool as defined in [RFC8829] (section 3.5.4. and section 4.1.1.).
RTCIceCredentialType
Enum
WebIDLenumRTCIceCredentialType
{ "password
" };
Enumeration description | |
---|---|
password
|
The credential is a long-term authentication username and password, as described in [RFC5389], Section 10.2. |
RTCIceServer
Dictionary
The
dictionary is used to describe the STUN and
TURN servers that can be used by the ICE Agent to establish a
connection with a peer.
RTCIceServer
WebIDLdictionaryRTCIceServer
{ required (DOMString or sequence<DOMString>)urls
; DOMStringusername
; DOMStringcredential
;RTCIceCredentialType
credentialType
= "password"; };
RTCIceServer
Members
urls
of type (DOMString or
sequence<DOMString>), required
STUN or TURN URI(s) as defined in [RFC7064] and [RFC7065] or other URI types.
username
of type DOMString
If this
object represents a TURN server,
and RTCIceServer
is
"credentialType
", then this attribute
specifies the username to use with that TURN server.
password
credential
of type DOMString
If this
object represents a TURN server,
then this attribute specifies the credential to use with
that TURN server.
RTCIceServer
If
is
"credentialType
", password
represents a long-term authentication password, as
described in [RFC5389], Section 10.2.
credential
To support additional values of
,
credentialType
may evolve in future as a union.
credential
credentialType
of type RTCIceCredentialType
, defaulting
to "password
"
If this
object represents a TURN server,
then this attribute specifies how credential
should be used when that TURN server requests
authorization.
RTCIceServer
An example array of
objects is:
RTCIceServer
[
{urls: 'stun:stun1.example.net'},
{urls: ['turns:turn.example.org', 'turn:turn.example.net'],
username: 'user',
credential: 'myPassword',
credentialType: 'password'},
];
The RTCIceServer
dictionary is used to describe the STUN and
TURN servers that can be used by the ICE Agent to establish a
connection with a peer.
WebIDLdictionary RTCIceServer
{
required (DOMString or sequence<DOMString>) urls
;
DOMString username
;
DOMString credential
;
};
RTCIceServer
Members
urls
of type (DOMString or
sequence<DOMString>), required
STUN or TURN URI(s) as defined in [RFC7064] and [RFC7065] or other URI types.
username
of type DOMString
If this RTCIceServer
object represents a TURN server,
then this attribute specifies the username to use with
that TURN server.
credential
of type DOMString
If this RTCIceServer
object represents a TURN server,
then this attribute specifies the credential to use with
that TURN server.
credential
represents a long-term authentication
password, as described in [RFC5389], Section 10.2.
An example array of RTCIceServer
objects is:
[
{urls: 'stun:stun1.example.net'},
{urls: ['turns:turn.example.org', 'turn:turn.example.net'],
username: 'user',
credential: 'myPassword',
];
As described in [RFC8829] (section 4.1.1.), if
the iceTransportPolicy
member of the
RTCConfiguration
is specified, it defines the ICE candidate policy [RFC8829] (section 3.5.3.) the
browser uses to surface the permitted candidates to the
application; only these candidates will be used for connectivity
checks.
WebIDLenum RTCIceTransportPolicy
{
"relay
",
"all
"
};
Enum value | Description |
---|---|
relay
|
The ICE Agent uses only media relay candidates such as candidates passing through a TURN server. Note
This can be used to prevent the remote endpoint from
learning the user's IP addresses, which may be desired in
certain use cases. For example, in a "call"-based
application, the application may want to prevent an
unknown caller from learning the callee's IP addresses
until the callee has consented in some way.
|
all
|
The ICE Agent can use any type of candidate when this value is specified. Note
The implementation can still use its own candidate
filtering policy in order to limit the IP addresses
exposed to the application, as noted in the description
of RTCIceCandidate .address .
|
As described in [RFC8829] (section 4.1.1.), bundle policy affects which media tracks are negotiated if the remote endpoint is not bundle-aware, and what ICE candidates are gathered. If the remote endpoint is bundle-aware, all media tracks and data channels are bundled onto the same transport.
WebIDLenum RTCBundlePolicy
{
"balanced
",
"max-compat
",
"max-bundle
"
};
Enum value | Description |
---|---|
balanced
|
Gather ICE candidates for each media type in use (audio, video, and data). If the remote endpoint is not bundle-aware, negotiate only one audio and video track on separate transports. |
max-compat
|
Gather ICE candidates for each track. If the remote endpoint is not bundle-aware, negotiate all media tracks on separate transports. |
max-bundle
|
Gather ICE candidates for only one track. If the remote endpoint is not bundle-aware, negotiate only one media track. |
As described in [RFC8829] (section 4.1.1.), the
RTCRtcpMuxPolicy
affects what ICE candidates are gathered to
support non-multiplexed RTCP. The only value defined in this spec
is "require
".
WebIDLenum RTCRtcpMuxPolicy
{
"require
"
};
Enum value | Description |
---|---|
require
|
Gather ICE candidates only for RTP and multiplex RTCP on the RTP candidates. If the remote endpoint is not capable of rtcp-mux, session negotiation will fail. |
These dictionaries describe the options that can be used to control the offer/answer creation process.
WebIDLdictionary RTCOfferAnswerOptions
{};
WebIDLdictionary RTCOfferOptions
: RTCOfferAnswerOptions
{
boolean iceRestart
= false;
};
iceRestart
of type boolean, defaulting to
false
When the value of this dictionary member is
true
, or the relevant RTCPeerConnection
object's [[LocalIceCredentialsToReplace]]
slot is
not empty, then the generated description will have ICE
credentials that are different from the current credentials
(as visible in the
currentLocalDescription
attribute's
SDP). Applying the generated description will restart ICE,
as described in section 9.1.1.1 of [RFC5245].
When the value of this dictionary member is
false
, and the relevant RTCPeerConnection
object's [[LocalIceCredentialsToReplace]]
slot is
empty, and the
currentLocalDescription
attribute has
valid ICE credentials, then the generated description will
have the same ICE credentials as the current value from the
currentLocalDescription
attribute.
Performing an ICE restart is recommended when
iceConnectionState
transitions to
"failed
". An application may
additionally choose to listen for the
iceConnectionState
transition to
"disconnected
" and then use other
sources of information (such as using
getStats
to measure if the number of
bytes sent or received over the next couple of seconds
increases) to determine whether an ICE restart is
advisable.
The RTCAnswerOptions
dictionary describe options
specific to session description of type "answer
"
(none in this version of the specification).
WebIDLdictionary RTCAnswerOptions
: RTCOfferAnswerOptions
{};
WebIDLenum RTCSignalingState
{
"stable
",
"have-local-offer
",
"have-remote-offer
",
"have-local-pranswer
",
"have-remote-pranswer
",
"closed
"
};
Enum value | Description |
---|---|
stable
|
There is no offer/answer exchange in progress. This is also the initial state, in which case the local and remote descriptions are empty. |
have-local-offer
|
A local description, of type "offer ", has
been successfully applied.
|
have-remote-offer
|
A remote description, of type "offer ", has
been successfully applied.
|
have-local-pranswer
|
A remote description of type "offer " has
been successfully applied and a local description of type
"pranswer " has been successfully applied.
|
have-remote-pranswer
|
A local description of type "offer " has been
successfully applied and a remote description of type
"pranswer " has been successfully applied.
|
closed
|
The RTCPeerConnection has been closed; its
[[IsClosed]] slot is true .
|
An example set of transitions might be:
stable
"
have-local-offer
"
have-remote-pranswer
"
stable
"
stable
"
have-remote-offer
"
have-local-pranswer
"
stable
"
WebIDLenum RTCIceGatheringState
{
"new
",
"gathering
",
"complete
"
};
RTCIceGatheringState
to clarify the relevant transport it represents (PR #2680)Enumeration description | |
---|---|
new
|
Any of the s are in the
" " gathering state and none of
the transports are in the
" " state, or there are no
transports.
|
gathering
|
Any of the s are in the
" " state.
|
complete
|
At least one exists, and all
s are in the
" " gathering state.
|
The set of transports considered is the set of transports presently referenced by the PeerConnection's set of transceivers.
Enum value | Description |
---|---|
new
|
Any of the RTCIceTransport s are in the
"new " gathering state and none of
the transports are in the
"gathering " state, or there are no
transports.
|
gathering
|
Any of the RTCIceTransport s are in the
"gathering " state.
|
complete
|
At least one RTCIceTransport exists, and all
RTCIceTransport s are in the
"complete " gathering state.
|
The set of transports considered is the one
presently referenced by the PeerConnection's
set of transceivers and the PeerConnection's
[[SctpTransport]]
internal slot if not null
.
WebIDLenum RTCPeerConnectionState
{
"closed
",
"failed
",
"disconnected
",
"new
",
"connecting
",
"connected
"
};
RTCPeerConnectionState
to clarify the relevant transport it represents (PR #2680)connecting
state happens whenever a ICE or DTLS transport is new (PR #2687)Enumeration description | |
---|---|
closed
|
The object's [[IsClosed]]
slot is true .
|
failed
|
The previous state doesn't apply and any
s are in the
" " state or any
s are in the
" " state.
|
disconnected
|
None of the previous states apply and any
s are in the
" " state.
|
new
|
None of the previous states apply and all
s are in the
" " or
" " state, and all
s are in the
" " or
" " state, or there are no
transports.
|
connecting
|
None of the previous states apply and any
is in the
" " state or any
is in the
" " state.
|
connected
|
None of the previous states apply and all
s are in the
" ",
" " or
" " state, and all
s are in the
" " or
" " state.
|
The set of transports considered is the set of transports presently referenced by the PeerConnection's set of transceivers.
Enum value | Description |
---|---|
closed
|
The RTCPeerConnection object's [[IsClosed]]
slot is true .
|
failed
|
The previous state doesn't apply and any
RTCIceTransport s are in the
"failed " state or any
RTCDtlsTransport s are in the
"failed " state.
|
disconnected
|
None of the previous states apply and any
RTCIceTransport s are in the
"disconnected " state.
|
new
|
None of the previous states apply and all
RTCIceTransport s are in the
"new " or
"closed " state, and all
RTCDtlsTransport s are in the
"new " or
"closed " state, or there are no
transports.
|
connecting
|
None of the previous states apply and any
RTCIceTransport is in the "new "
or "checking " state or any
RTCDtlsTransport is in the "new "
or "connecting " state.
|
connected
|
None of the previous states apply and all
RTCIceTransport s are in the
"connected ",
"completed " or
"closed " state, and all
RTCDtlsTransport s are in the
"connected " or
"closed " state.
|
The set of transports considered is the one
presently referenced by the PeerConnection's
set of transceivers and the PeerConnection's
[[SctpTransport]]
internal slot if not null
.
WebIDLenum RTCIceConnectionState
{
"closed
",
"failed
",
"disconnected
",
"new
",
"checking
",
"completed
",
"connected
"
};
RTCIceConnectionState
to clarify the relevant transport it represents (PR #2680)Enumeration description | |
---|---|
closed
|
The object's [[IsClosed]]
slot is true .
|
failed
|
The previous state doesn't apply and any
s are in the
" " state.
|
disconnected
|
None of the previous states apply and any
s are in the
" " state.
|
new
|
None of the previous states apply and all
s are in the
" " or
" " state, or there are no
transports.
|
checking
|
None of the previous states apply and any
s are in the
" " or
" " state.
|
completed
|
None of the previous states apply and all
s are in the
" " or
" " state.
|
connected
|
None of the previous states apply and all
s are in the
" ",
" " or
" " state.
|
The set of transports considered is the set of transports presently referenced by the PeerConnection's set of transceivers.
Note that if an
is discarded as a result of
signaling (e.g. RTCP mux or bundling), or created as a result of
signaling (e.g. adding a new media description), the state
may advance directly from one state to another.
RTCIceTransport
Enum value | Description |
---|---|
closed
|
The RTCPeerConnection object's [[IsClosed]]
slot is true .
|
failed
|
The previous state doesn't apply and any
RTCIceTransport s are in the
"failed " state.
|
disconnected
|
None of the previous states apply and any
RTCIceTransport s are in the
"disconnected " state.
|
new
|
None of the previous states apply and all
RTCIceTransport s are in the
"new " or
"closed " state, or there are no
transports.
|
checking
|
None of the previous states apply and any
RTCIceTransport s are in the
"new " or
"checking " state.
|
completed
|
None of the previous states apply and all
RTCIceTransport s are in the
"completed " or
"closed " state.
|
connected
|
None of the previous states apply and all
RTCIceTransport s are in the
"connected ",
"completed " or
"closed " state.
|
The set of transports considered is the one
presently referenced by the PeerConnection's
set of transceivers and the PeerConnection's
[[SctpTransport]]
internal slot if not null
.
Note that if an RTCIceTransport
is discarded as a result of
signaling (e.g. RTCP mux or bundling), or created as a result of
signaling (e.g. adding a new media description), the state
may advance directly from one state to another.
The [RFC8829] specification, as a whole, describes the details of how
the RTCPeerConnection
operates. References to specific
subsections of [RFC8829] are provided as appropriate.
Calling new
creates an
RTCPeerConnection
(configuration)RTCPeerConnection
object.
configuration.iceServers
contains
information used to find and access the servers used by ICE. The
application can supply multiple servers of each type, and any TURN
server MAY also be used as a STUN server for the purposes of
gathering server reflexive candidates.
An RTCPeerConnection
object has a signaling state, a
connection state, an ICE gathering state, and
an ICE connection state. These are initialized when the
object is created.
The ICE protocol implementation of an RTCPeerConnection
is
represented by an ICE agent [RFC5245]. Certain
RTCPeerConnection
methods involve interactions with the ICE Agent, namely addIceCandidate
, setConfiguration
,
setLocalDescription
, setRemoteDescription
and close
.
These interactions are described in the relevant sections in this
document and in [RFC8829]. The ICE Agent also provides
indications to the user agent when the state of its internal
representation of an RTCIceTransport
changes, as described in
5.6
RTCIceTransport
Interface.
The task source for the tasks listed in this section is the networking task source.
The state of the SDP negotiation is represented by the signaling state and the internal variables
[[CurrentLocalDescription]]
,
[[CurrentRemoteDescription]]
,
[[PendingLocalDescription]]
and
[[PendingRemoteDescription]]
. These are only set inside the
setLocalDescription
and setRemoteDescription
operations,
and modified by the addIceCandidate
operation and the surface a candidate procedure. In each case, all the
modifications to all the five variables are completed before the
procedures fire any events or invoke any callbacks, so the
modifications are made visible at a single point in time.
As one of the unloading document cleanup steps, run the following steps:
Let window be document's relevant global object.
For each RTCPeerConnection
object connection
whose relevant global object is window, close the connection with connection and the value true
.
When the RTCPeerConnection.constructor()
is
invoked, the user agent MUST run the following steps:
If any of the steps enumerated below fails for a reason not
specified here, throw an UnknownError
with the message
attribute set to an
appropriate description.
Let connection be a newly created
RTCPeerConnection
object.
Let connection have a [[DocumentOrigin]] internal slot, initialized to the relevant settings object's origin.
If the certificates
value in
configuration is non-empty, run the following
steps for each certificate in certificates:
If the value of
certificate.expires
is less
than the current time, throw an
InvalidAccessError
.
If certificate.[[Origin]]
is not
same origin with
connection.[[DocumentOrigin]]
, throw an InvalidAccessError
.
Store certificate.
Else, generate one or more new RTCCertificate
instances
with this RTCPeerConnection
instance and store them. This
MAY happen asynchronously and the value of
certificates
remains
undefined
for the subsequent steps. As noted in
Section 4.3.2.3 of [RFC8826], WebRTC utilizes
self-signed rather than Public Key Infrastructure (PKI)
certificates, so that the expiration check is to ensure that
keys are not used indefinitely and additional certificate
checks are unnecessary.
If
configuration.iceServer
is an array
truncate it to the maximum number of supported elements.
Initialize connection's ICE Agent.
Let connection have a
[[Configuration]]
internal slot, initialized to null
.
Set the configuration specified by configuration.
Let connection have an [[IsClosed]]
internal slot, initialized to false
.
Let connection have a
[[NegotiationNeeded]] internal slot, initialized
to false
.
Let connection have an
[[SctpTransport]] internal slot, initialized to
null
.
Let connection have an [[Operations]] internal slot, representing an operations chain, initialized to an empty list.
Let connection have a
[[UpdateNegotiationNeededFlagOnEmptyChain]]
internal slot, initialized to false
.
Let connection have an
[[LastCreatedOffer]] internal slot, initialized
to ""
.
Let connection have an
[[LastCreatedAnswer]] internal slot, initialized
to ""
.
Let connection have an [[EarlyCandidates]] internal slot, initialized to an empty list.
Set connection's signaling state to
"stable
".
Set connection's ICE connection state to
"new
".
Set connection's ICE gathering state to
"new
".
Set connection's connection state to
"new
".
Let connection have a
[[PendingLocalDescription]] internal slot,
initialized to null
.
Let connection have a
[[CurrentLocalDescription]] internal slot,
initialized to null
.
Let connection have a
[[PendingRemoteDescription]] internal slot,
initialized to null
.
Let connection have a
[[CurrentRemoteDescription]] internal slot,
initialized to null
.
Let connection have a [[LocalIceCredentialsToReplace]] internal slot, initialized to an empty set.
Return connection.
An RTCPeerConnection
object has an operations
chain, [[Operations]]
, which ensures that only one
asynchronous operation in the chain executes concurrently. If
subsequent calls are made while the returned promise of a
previous call is still not settled, they are added to the
chain and executed when all the previous calls have finished
executing and their promises have settled.
To chain an operation to an
RTCPeerConnection
object's operations chain, run the
following steps:
Let connection be the RTCPeerConnection
object.
If connection.[[IsClosed]]
is
true
, return a promise rejected with a
newly created InvalidStateError
.
Let operation be the operation to be chained.
Let p be a new promise.
Append operation to [[Operations]]
.
If the length of [[Operations]]
is exactly 1, execute
operation.
Upon fulfillment or rejection of the promise returned by the operation, run the following steps:
If connection.[[IsClosed]]
is
true
, abort these steps.
If the promise returned by operation was fulfilled with a value, fulfill p with that value.
If the promise returned by operation was rejected with a value, reject p with that value.
Upon fulfillment or rejection of p, execute the following steps:
If connection.[[IsClosed]]
is
true
, abort these steps.
Remove the first element of [[Operations]]
.
If [[Operations]]
is non-empty, execute the
operation represented by the first element of
[[Operations]]
, and abort these steps.
If
connection.[[UpdateNegotiationNeededFlagOnEmptyChain]]
is false
, abort these steps.
Set
connection.[[UpdateNegotiationNeededFlagOnEmptyChain]]
to false
.
Update the negotiation-needed flag for connection.
Return p.
An RTCPeerConnection
object has an aggregated connection state. Whenever the state of an RTCDtlsTransport
changes
or when the [[IsClosed]]
slot turns true
,
the user agent MUST update the connection state by queueing a
task that runs the following steps:
Let connection be this RTCPeerConnection
object.
Let newState be the value of deriving a new state
value as described by the RTCPeerConnectionState
enum.
If connection's connection state is equal to newState, abort these steps.
Let connection's connection state be newState.
Fire an event named connectionstatechange
at
connection.
To update the ICE gathering state of an RTCPeerConnection
instance
connection, the user agent MUST queue a task that runs
the following steps:
If connection.[[IsClosed]]
is
true
, abort these steps.
Let newState be the value of deriving a new state
value as described by the RTCIceGatheringState
enum.
If connection's ICE gathering state is equal to newState, abort these steps.
Set connection's ICE gathering state to newState.
Fire an event named icegatheringstatechange
at
connection.
If newState is
"complete
", fire an event
named icecandidate
using the
RTCPeerConnectionIceEvent
interface with the candidate
attribute set to null
at connection.
RTCIceTransport
and/or RTCPeerConnection
.
To
set a local session description description on
an RTCPeerConnection
object connection, set the session description
description on connection with the additional
value false
.
To
set a remote session description description
on an RTCPeerConnection
object connection, set the session description
description on connection with the additional
value true
.
To set
a session description description on an
RTCPeerConnection
object connection, given a
remote boolean, run the following steps:
Let p be a new promise.
If description.type
is
"rollback
" and connection's signaling state is either "stable
",
"have-local-pranswer
", or
"have-remote-pranswer
", then reject p with a newly created
InvalidStateError
and abort these steps.
Let jsepSetOfTransceivers be a shallow copy of connection's set of transceivers.
In parallel, start the process to apply description as described in [RFC8829] (section 5.5. and section 5.6.), with these additional restrictions:
Use jsepSetOfTransceivers as the source of
truth with regard to what "RtpTransceivers" exist, and
their [[JsepMid]]
internal slot as their "mid
property".
If remote is false
and this
triggers the ICE candidate gathering process in [RFC8829] (section 5.9.), the ICE Agent
MUST NOT gather candidates that would be
administratively prohibited.
If remote is true
and this
triggers ICE connectivity checks in [RFC8829] (section 5.10.), the
ICE Agent MUST NOT attempt to connect to candidates
that are administratively prohibited.
If remote is true
, validate
back-to-back offers as if answers were applied in
between, by running the check for subsequent offers as if
it were in stable state.
If applying description leads to modifying a transceiver transceiver, and transceiver.[[Sender]].[[SendEncodings]] is non-empty, and not equal to the encodings that would result from processing description, the process of applying description fails. This specification does not allow remotely initiated RID renegotiation.
If the process to apply description fails for any reason, then the user agent MUST queue a task that runs the following steps:
If connection.[[IsClosed]]
is
true
, then abort these steps.
If
description.type
is invalid for the current signaling state of
connection as described in
[RFC8829] (section 5.5. and section 5.6.), then reject p with
a newly created InvalidStateError
and abort these steps.
If the content of description is not valid
SDP syntax, then reject p with an
RTCError
(with errorDetail
set to
"sdp-syntax-error
" and the
sdpLineNumber
attribute set to the line
number in the SDP where the syntax error was
detected) and abort these steps.
If remote is true
, the
connection's RTCRtcpMuxPolicy
is
require
and the description does
not use RTCP mux, then reject p with
a newly created
InvalidAccessError
and abort these steps.
If the description attempted to renegotiate RIDs, as
described above, then reject p with
a newly created
InvalidAccessError
and abort these steps.
If the content of description is invalid,
then reject p with a newly created InvalidAccessError
and abort
these steps.
For all other errors, reject p with
a newly created OperationError
.
If description is applied successfully, the user agent MUST queue a task that runs the following steps:
If connection.[[IsClosed]]
is
true
, then abort these steps.
If remote is true
and
description is of type
"offer
", then if any
addTrack
()
methods on
connection succeeded
during the process to apply description,
abort these steps and start the process over as if
they had succeeded prior, to include the extra
transceiver(s) in the process.
If any promises from setParameters
methods on RTCRtpSender
s associated with
connection are not settled, abort these
steps and start the process over.
If description is of type
"offer
" and the signaling state
of connection is
"stable
" then for each
transceiver in connection's set of transceivers, run the following steps:
Set transceiver.[[Sender]].[[LastStableStateSenderTransport]] to transceiver.[[Sender]].[[SenderTransport]].
Set transceiver.[[Receiver]].[[LastStableStateReceiverTransport]] to transceiver.[[Receiver]].[[ReceiverTransport]].
Set transceiver.[[Receiver]].[[LastStableStateAssociatedRemoteMediaStreams]] to transceiver.[[Receiver]].[[AssociatedRemoteMediaStreams]].
Set transceiver.[[Receiver]].[[LastStableStateReceiveCodecs]] to transceiver.[[Receiver]].[[ReceiveCodecs]].
Set
transceiver.[[Sender]]
.[[LastStableStateSenderTransport]]
to
transceiver.[[Sender]]
.[[SenderTransport]]
.
If
transceiver.[[Sender]]
.[[SendEncodings]]
.length
is 1
and the lone encoding contains no rid
member,
then set
transceiver.[[Sender]]
.[[LastStableRidlessSendEncodings]]
to
transceiver.[[Sender]]
.[[SendEncodings]]
;
Otherwise, set
transceiver.[[Sender]]
.[[LastStableRidlessSendEncodings]]
to null
.
Set
transceiver.[[Receiver]]
.[[LastStableStateReceiverTransport]]
to
transceiver.[[Receiver]]
.[[ReceiverTransport]]
.
Set
transceiver.[[Receiver]]
.[[LastStableStateAssociatedRemoteMediaStreams]]
to
transceiver.[[Receiver]]
.[[AssociatedRemoteMediaStreams]]
.
Set
transceiver.[[Receiver]]
.[[LastStableStateReceiveCodecs]]
to
transceiver.[[Receiver]]
.[[ReceiveCodecs]]
.
If remote is false
, then run
one of the following steps:
If description is of type
"offer
", set
connection.[[PendingLocalDescription]]
to a new RTCSessionDescription
object
constructed from description, set
connection's signaling state to
"have-local-offer
", and release early candidates.
If description is of type
"answer
", then this completes an
offer answer negotiation. Set
connection.[[CurrentLocalDescription]]
to a new RTCSessionDescription
object
constructed from description, and set
connection.[[CurrentRemoteDescription]]
to
connection.[[PendingRemoteDescription]]
.
Set both
connection.[[PendingRemoteDescription]]
and
connection.[[PendingLocalDescription]]
to null
. Set both
connection.[[LastCreatedOffer]]
and
connection.[[LastCreatedAnswer]]
to ""
, set connection's
signaling state to
"stable
", and release early candidates. Finally, if none of the ICE
credentials in
connection.[[LocalIceCredentialsToReplace]]
are present in description, then set
connection.[[LocalIceCredentialsToReplace]]
to an empty set.
If description is of type
"pranswer
", then set
connection.[[PendingLocalDescription]]
to a new RTCSessionDescription
object
constructed from description, set
connection's signaling state to
"have-local-pranswer
", and
release early candidates.
Otherwise, (if remote is
true
) run one of the following steps:
If description is of type
"offer
", set
connection.[[PendingRemoteDescription]]
attribute to a new RTCSessionDescription
object constructed from description,
and set connection's signaling state to
"have-remote-offer
".
If description is of type
"answer
", then this completes an
offer answer negotiation. Set
connection.[[CurrentRemoteDescription]]
to a new RTCSessionDescription
object
constructed from description, and set
connection.[[CurrentLocalDescription]]
to
connection.[[PendingLocalDescription]]
.
Set both
connection.[[PendingRemoteDescription]]
and
connection.[[PendingLocalDescription]]
to null
. Set both
connection.[[LastCreatedOffer]]
and
connection.[[LastCreatedAnswer]]
to ""
, and set
connection's signaling state to
"stable
". Finally, if none
of the ICE credentials in
connection.[[LocalIceCredentialsToReplace]]
are present in the newly set
connection.[[CurrentLocalDescription]]
,
then set
connection.[[LocalIceCredentialsToReplace]]
to an empty set.
If description is of type
"pranswer
", then set
connection.[[PendingRemoteDescription]]
to a new RTCSessionDescription
object
constructed from description and set
connection's signaling state to
"have-remote-pranswer
".
If description is of type
"answer
", and it initiates the closure
of an existing SCTP association, as defined in
[RFC8841], Sections 10.3 and 10.4, set the value
of connection.[[SctpTransport]]
to
null
.
Let trackEventInits, muteTracks, addList, removeList and errorList be empty lists.
If description is of type
"answer
" or "pranswer
",
then run the following steps:
If description initiates the
establishment of a new SCTP association, as
defined in [RFC8841], Sections 10.3 and 10.4,
create an RTCSctpTransport with an initial
state of "connecting
"
and assign the result to the
[[SctpTransport]]
slot. Otherwise, if an
SCTP association is established, but the
max-message-size
SDP
attribute is updated, update the data max message size of
connection.[[SctpTransport]]
.
If description negotiates the DTLS
role of the SCTP transport, then for each
RTCDataChannel
, channel, with a
null
id
, run the
following step:
[[ReadyState]]
to
"closed
", and add
channnel to errorList.
If description is not of type
"rollback
", then run the following
steps:
If remote is false
, then
run the following steps for each media description in description:
If the media description was not yet associated with an
object then run the following steps:
RTCRtpTransceiver
Let transceiver be the
used to create the
media description.
RTCRtpTransceiver
Set transceiver.[[Mid]] to transceiver.[[JsepMid]].
If
transceiver.[[Stopped]]
is true
, abort these sub
steps.
If the media description is
indicated as using an existing media
transport according to [RFC8843],
let transport be the
object representing
the RTP/RTCP component of that transport.
RTCDtlsTransport
Otherwise, let transport be a
newly created
object
with a new underlying
RTCDtlsTransport
.
RTCIceTransport
Set transceiver.[[Sender]].[[SenderTransport]] to transport.
Set transceiver.[[Receiver]].[[ReceiverTransport]] to transport.
Let transceiver be the
associated with
the media description.
RTCRtpTransceiver
If transceiver.[[Stopped]]
is true
, abort these sub steps.
Let direction be an
value
representing the direction from the media
description.
RTCRtpTransceiverDirection
If direction is
"
" or
"sendrecv
",
set
transceiver.[[Receptive]]
to recvonly
true
, otherwise set it to
false
.
Set transceiver.[[Receiver]].[[ReceiveCodecs]] to the codecs that description negotiates for receiving and which the user agent is currently prepared to receive.
If description is of type
"
" or
"answer
", then run the
following steps:
pranswer
Set
transceiver.[[Sender]].[[SendCodecs]]
to the codecs that description
negotiates for sending and which the user
agent is currently capable of sending,
and set
transceiver.[[Sender]].[[LastReturnedParameters]]
to null
.
If direction is
"
"
or
"sendonly
",
and
transceiver.[[FiredDirection]]
is either
"inactive
"
or
"sendrecv
",
then run the following steps:
recvonly
Set the associated remote streams given transceiver.[[Receiver]], an empty list, another empty list, and removeList.
process the removal of a remote track for the media description, given transceiver and muteTracks.
Set transceiver.[[CurrentDirection]] and transceiver.[[FiredDirection]] to direction.
If the media description was not yet associated with an RTCRtpTransceiver
object then run the following steps:
Let transceiver be the
RTCRtpTransceiver
used to create the
media description.
Set
transceiver.[[Mid]]
to
transceiver.[[JsepMid]]
.
If
transceiver.[[Stopped]]
is true
, abort these sub
steps.
If the media description is
indicated as using an existing media transport according to [RFC8843],
let transport be the
RTCDtlsTransport
object representing
the RTP/RTCP component of that transport.
Otherwise, let transport be a
newly created RTCDtlsTransport
object
with a new underlying
RTCIceTransport
.
Set
transceiver.[[Sender]]
.[[SenderTransport]]
to transport.
Set
transceiver.[[Receiver]]
.[[ReceiverTransport]]
to transport.
Let transceiver be the
RTCRtpTransceiver
associated with
the media description.
If transceiver.[[Stopped]]
is true
, abort these sub steps.
Let direction be an
RTCRtpTransceiverDirection
value
representing the direction from the media description.
If direction is
"sendrecv
" or
"recvonly
",
set
transceiver.[[Receptive]]
to true
, otherwise set it to
false
.
Set
transceiver.[[Receiver]]
.[[ReceiveCodecs]]
to the codecs that description
negotiates for receiving and which the user
agent is currently prepared to receive.
If description is of type
"answer
" or
"pranswer
", then run the
following steps:
If transceiver.
[[Sender]]
.[[SendEncodings]]
.length is greater than 1
, then
run the following steps:
If description is missing
all of the previously negotiated layers,
then remove all dictionaries in
transceiver.[[Sender]]
.[[SendEncodings]]
except the first one, and skip the next
step.
If description is missing any of
the previously negototiated layers, then
remove the dictionaries that correspond to
the missing layers from
transceiver.[[Sender]]
.[[SendEncodings]]
.
Set
transceiver.[[Sender]]
.[[SendCodecs]]
to the codecs that description
negotiates for sending and which the user
agent is currently capable of sending,
and set
transceiver.[[Sender]]
.[[LastReturnedParameters]]
to null
.
If direction is
"sendonly
"
or
"inactive
",
and
transceiver.[[FiredDirection]]
is either
"sendrecv
"
or
"recvonly
",
then run the following steps:
Set the associated remote streams given
transceiver.[[Receiver]]
,
an empty list, another empty list,
and removeList.
process the removal of a remote track for the media description, given transceiver and muteTracks.
Set
transceiver.[[CurrentDirection]]
and
transceiver.[[FiredDirection]]
to direction.
Otherwise, (if remote is
true
) run the following steps for
each media description in
description:
If the description is of type
"
" and contains a request
to receive simulcast, use the order of the
rid values specified in the simulcast
attribute to create an
offer
dictionary for
each of the simulcast layers, populating the
RTCRtpEncodingParameters
member
according to the corresponding rid value, and
let sendEncodings be the list
containing the created dictionaries.
Otherwise, let sendEncodings be an
empty list.
rid
scaleResolutionDownBy
to 2^(length of sendEncodings -
encoding index - 1)
.
As described by [RFC8829] (section 5.10.),
attempt to find an existing
object,
transceiver, to represent the media description.
RTCRtpTransceiver
If a suitable transceiver was found
(transceiver is set) and
sendEncodings is non-empty, set
transceiver.[[Sender]].[[SendEncodings]]
to sendEncodings, and set
transceiver.[[Sender]].[[LastReturnedParameters]]
to null
.
If no suitable transceiver was found (transceiver is unset), run the following steps:
Create an RTCRtpSender, sender, from the media description using sendEncodings.
Create an RTCRtpReceiver, receiver, from the media description.
Create an RTCRtpTransceiver with
sender, receiver
and an
value of
"RTCRtpTransceiverDirection
",
and let transceiver be the
result.
recvonly
Add transceiver to the connection's set of transceivers.
If description is of type
"
" or
"answer
", and
transceiver.
[[Sender]].[[SendEncodings]]
.length is greater than pranswer
1
, then
run the following steps:
If description indicates that simulcast is not supported or desired, then remove all dictionaries in transceiver.[[Sender]].[[SendEncodings]] except the first one and abort these sub steps.
If description rejects any of the offered layers, then remove the dictionaries that correspond to rejected layers from transceiver.[[Sender]].[[SendEncodings]].
Update the paused status as indicated by
[RFC8853] of each simulcast
layer by setting the
member on the corresponding dictionaries
in
transceiver.[[Sender]].[[SendEncodings]]
to active
true
for unpaused or to
false
for paused.
Set transceiver.[[Mid]] to transceiver.[[JsepMid]].
Let direction be an
value
representing the direction from the media
description, but with the send and receive
directions reversed to represent this peer's
point of view. If the media description
is rejected, set direction to
"RTCRtpTransceiverDirection
".
inactive
If direction is
"
" or
"sendrecv
",
let msids be a list of the MSIDs
that the media description indicates
transceiver.[[Receiver]].[[ReceiverTrack]]
is to be associated with. Otherwise, let
msids be an empty list.
recvonly
Process remote tracks with transceiver, direction, msids, addList, removeList, and trackEventInits.
Set transceiver.[[Receiver]].[[ReceiveCodecs]] to the codecs that description negotiates for receiving and which the user agent is currently prepared to receive.
If description is of type
"
" or
"answer
", then run the
following steps:
pranswer
Set transceiver.[[Sender]].[[SendCodecs]] to the codecs that description negotiates for sending and which the user agent is currently capable of sending.
Set transceiver.[[CurrentDirection]] and transceiver.[[Direction]]s to direction.
Let transport be the
object representing
the RTP/RTCP component of the media
transport used by
transceiver's associated
media description, according to
[RFC8843].
RTCDtlsTransport
Set transceiver.[[Sender]].[[SenderTransport]] to transport.
Set transceiver.[[Receiver]].[[ReceiverTransport]] to transport.
Set the [[IceRole]] of transport according to the rules of [RFC8445].
unknown
, do not modify
[[IceRole]].
controlling
.
a=ice-lite
,
set [[IceRole]] to
controlling
.
a=ice-lite
,
set [[IceRole]] to
controlled
.
If the media description is rejected,
and
transceiver.[[Stopped]] is
false
, then stop the
RTCRtpTransceiver transceiver.
If the description is of type
"offer
" and the
media description contains a request
to receive simulcast, use the order of the
rid values specified in the simulcast
attribute to create an
RTCRtpEncodingParameters
dictionary for
each of the simulcast layers, populating the
rid
member
according to the corresponding rid value
(using only the first value if
comma-separated alternatives exist), and
let proposedSendEncodings be the
list containing the created dictionaries.
Otherwise, let proposedSendEncodings
be an empty list.
For each encoding, encoding, in
proposedSendEncodings in reverse
order, if encoding's
rid
matches that of
another encoding in
proposedSendEncodings, remove
encoding
from proposedSendEncodings.
scaleResolutionDownBy
to 2^(length of proposedSendEncodings -
encoding index - 1)
.
As described by [RFC8829] (section 5.10.),
attempt to find an existing
RTCRtpTransceiver
object,
transceiver, to represent the media description.
If a suitable transceiver was found (transceiver is set), and proposedSendEncodings is non-empty, run the following steps:
If the length of
transceiver.[[Sender]]
.[[SendEncodings]]
is 1
, and the lone encoding
contains no
rid
member, set
transceiver.[[Sender]]
.[[SendEncodings]]
to proposedSendEncodings, and set
transceiver.[[Sender]]
.[[LastReturnedParameters]]
to null
.
If no suitable transceiver was found (transceiver is unset), run the following steps:
Create an RTCRtpSender, sender, from the media description using proposedSendEncodings.
Create an RTCRtpReceiver, receiver, from the media description.
Create an RTCRtpTransceiver with
sender, receiver
and an RTCRtpTransceiverDirection
value of
"recvonly
",
and let transceiver be the
result.
Add transceiver to the connection's set of transceivers.
If description is of type
"answer
" or
"pranswer
", and
transceiver.
[[Sender]]
.[[SendEncodings]]
.length is greater than 1
, then
run the following steps:
If description indicates that
simulcast is not supported or desired, or
description is missing all of
the previously negotiated layers,
then remove all dictionaries in
transceiver.[[Sender]]
.[[SendEncodings]]
except the first one and abort these sub
steps.
If description is missing any of
the previously negotiated layers, then
remove the dictionaries that correspond to
the missing layers from
transceiver.[[Sender]]
.[[SendEncodings]]
.
Set transceiver.[[Mid]]
to
transceiver.[[JsepMid]]
.
Let direction be an
RTCRtpTransceiverDirection
value
representing the direction from the media description, but with the send and receive
directions reversed to represent this peer's
point of view. If the media description
is rejected, set direction to
"inactive
".
If direction is
"sendrecv
" or
"recvonly
",
let msids be a list of the MSIDs
that the media description indicates
transceiver.[[Receiver]]
.[[ReceiverTrack]]
is to be associated with. Otherwise, let
msids be an empty list.
Process remote tracks with transceiver, direction, msids, addList, removeList, and trackEventInits.
Set
transceiver.[[Receiver]]
.[[ReceiveCodecs]]
to the codecs that description
negotiates for receiving and which the user
agent is currently prepared to receive.
If description is of type
"answer
" or
"pranswer
", then run the
following steps:
Set
transceiver.[[Sender]]
.[[SendCodecs]]
to the codecs that description
negotiates for sending and which the user
agent is currently capable of sending.
Set
transceiver.[[CurrentDirection]]
to direction.
Let transport be the
RTCDtlsTransport
object representing
the RTP/RTCP component of the media transport used by
transceiver's associated
media description, according to
[RFC8843].
Set
transceiver.[[Sender]]
.[[SenderTransport]]
to transport.
Set
transceiver.[[Receiver]]
.[[ReceiverTransport]]
to transport.
Set the [[IceRole]]
of
transport according to the
rules of [RFC8445].
[[IceRole]]
is not
unknown
, do not modify
[[IceRole]]
.
controlling
.
a=ice-lite
,
set [[IceRole]]
to
controlling
.
a=ice-lite
,
set [[IceRole]]
to
controlled
.
[[IceRole]]
always has a value
after the first offer is processed.
If the media description is rejected,
and
transceiver.[[Stopped]]
is
false
, then stop the RTCRtpTransceiver transceiver.
Otherwise, (if description is of type
"rollback
") run the following steps:
Let pendingDescription be either
connection.[[PendingLocalDescription]]
or
connection.[[PendingRemoteDescription]]
,
whichever one is not null
.
For each transceiver in the connection's set of transceivers run the following steps:
If transceiver was not associated with a media description
prior to pendingDescription being set,
disassociate it and set both
transceiver.[[JsepMid]]
and transceiver.[[Mid]] to
null
.
Set transceiver.[[Sender]].[[SenderTransport]] to transceiver.[[Sender]].[[LastStableStateSenderTransport]].
Set transceiver.[[Receiver]].[[ReceiverTransport]] to transceiver.[[Receiver]].[[LastStableStateReceiverTransport]].
Set transceiver.[[Receiver]].[[ReceiveCodecs]] to transceiver.[[Receiver]].[[LastStableStateReceiveCodecs]].
If the signaling state of
connection is
"
",
run the following sub steps:
have-remote-offer
Let msids be a list of the
id
s of all
MediaStream
objects in
transceiver.[[Receiver]].[[LastStableStateAssociatedRemoteMediaStreams]],
or an empty list if there are none.
Process remote tracks with transceiver, transceiver.[[CurrentDirection]], msids, addList, removeList, and trackEventInits.
If transceiver was created when
pendingDescription was set, and a
track has never been attached to it via
addTrack
()
, then stop the RTCRtpTransceiver
transceiver, and remove it from
connection's set of
transceivers.
If transceiver was not associated with a media description
prior to pendingDescription being set,
disassociate it and set both
transceiver.[[JsepMid]]
and transceiver.[[Mid]]
to
null
.
Set
transceiver.[[Sender]]
.[[SenderTransport]]
to
transceiver.[[Sender]]
.[[LastStableStateSenderTransport]]
.
If
transceiver.[[Sender]]
.[[LastStableRidlessSendEncodings]]
is not null
, and any encoding in
transceiver.[[Sender]]
.[[SendEncodings]]
contains a
rid
member, then set
transceiver.[[Sender]]
.[[SendEncodings]]
to
transceiver.[[Sender]]
.[[LastStableRidlessSendEncodings]]
.
Set
transceiver.[[Receiver]]
.[[ReceiverTransport]]
to
transceiver.[[Receiver]]
.[[LastStableStateReceiverTransport]]
.
Set
transceiver.[[Receiver]]
.[[ReceiveCodecs]]
to
transceiver.[[Receiver]]
.[[LastStableStateReceiveCodecs]]
.
If the signaling state of
connection is
"have-remote-offer
",
run the following sub steps:
Let msids be a list of the
id
s of all
MediaStream
objects in
transceiver.[[Receiver]]
.[[LastStableStateAssociatedRemoteMediaStreams]]
,
or an empty list if there are none.
Process remote tracks with
transceiver,
transceiver.[[CurrentDirection]]
,
msids, addList,
removeList, and
trackEventInits.
If transceiver was created when
pendingDescription was set, and a
track has never been attached to it via
addTrack
()
, then stop the RTCRtpTransceiver
transceiver, and remove it from
connection's set of transceivers.
Set
connection.[[PendingLocalDescription]]
and
connection.[[PendingRemoteDescription]]
to null
, and set
connection's signaling state to
"stable
".
If description is of type
"answer
", then run the following
steps:
For each transceiver in the connection's set of transceivers run the following steps:
If transceiver is
stopped
, associated with an m= section and the associated m=
section is rejected in
connection.[[CurrentLocalDescription]]
or
connection.[[CurrentRemoteDescription]]
,
remove the transceiver from the
connection's set of transceivers.
If connection's signaling state is
now "stable
", run the following
steps:
For any transceiver that was removed
from the set of transceivers in a previous
step, if any of its transports
(transceiver.[[Sender]]
.[[SenderTransport]]
or
transceiver.[[Receiver]]
.[[ReceiverTransport]]
)
are still not closed and they're no longer
referenced by a non-stopped transceiver, close
the RTCDtlsTransport
s and their associated
RTCIceTransport
s. This results in events
firing on these objects in a queued task.
Clear the negotiation-needed flag and update the negotiation-needed flag.
If connection's signaling state
changed above, fire an event named
signalingstatechange
at connection.
For each channel in errorList,
fire an event named error
using the RTCErrorEvent
interface with the
errorDetail
attribute set to
"data-channel-failure
" at
channel.
For each track in muteTracks,
set the muted state of track to the
value true
.
For each stream and track pair in removeList, remove the track track from stream.
For each stream and track pair in addList, add the track track to stream.
For each entry entry in
trackEventInits, fire an event named
track
using the RTCTrackEvent
interface with
its receiver
attribute initialized
to entry.receiver
,
its track
attribute initialized to
entry.track
, its
streams
attribute initialized to
entry.streams
and
its transceiver
attribute
initialized to
entry.transceiver
at
the connection object.
Resolve p with
undefined
.
Return p.
RTCConfiguration
dictionary, aligning it with current implementations (PR #2691)To set a configuration, run the following steps:
Let configuration be the
dictionary to be processed.
RTCConfiguration
Let connection be the target
object.
RTCPeerConnection
If configuration.
is set, run the following steps:
certificates
If the length of
configuration.
is different from the length of
connection.[[Configuration]].certificates
,
throw an certificates
InvalidModificationError
.
Let index be initialized to 0.
Let size be initialized to the length of
configuration.
.
certificates
While index is less than size, run the following steps:
If the ECMAScript object represented by the value of
configuration.
at index is not the same as the ECMAScript
object represented by the value of
connection.[[Configuration]].certificates
at index, throw an
certificates
InvalidModificationError
.
Increment index by 1.
If the value of
configuration.
is
set and its value differs from the connection's
bundle policy, throw an
bundlePolicy
InvalidModificationError
.
If the value of
configuration.
is set and its value differs from the connection's
rtcpMux policy, throw an
rtcpMuxPolicy
InvalidModificationError
.
If the value of
configuration.
is set and its value differs from the connection's
previously set iceCandidatePoolSize
, and
iceCandidatePoolSize
has already been
called, throw an
setLocalDescription
InvalidModificationError
.
Set the ICE Agent's ICE transports setting to the
value of
configuration.
.
As defined in [RFC8829] (section 4.1.18.), if the new ICE
transports setting changes the existing setting, no action
will be taken until the next gathering phase. If a script
wants this to happen immediately, it should do an ICE
restart.
iceTransportPolicy
Set the ICE Agent's prefetched ICE candidate pool
size as defined in [RFC8829] (section 3.5.4. and section 4.1.1.) to the
value of
configuration.
.
If the new ICE candidate pool size changes the existing
setting, this may result in immediate gathering of new pooled
candidates, or discarding of existing pooled candidates, as
defined in [RFC8829] (section 4.1.18.).
iceCandidatePoolSize
Let validatedServers be an empty list.
If configuration.
is defined, then run the following steps for each element:
iceServers
Let server be the current list element.
Let urls be
server.
.
urls
If urls is a string, set urls to a list consisting of just that string.
If urls is empty, throw a
SyntaxError
.
For each url in urls run the following steps:
Parse the url using the generic URI syntax
defined in [RFC3986] and obtain the scheme
name. If the parsing based on the syntax
defined in [RFC3986] fails, throw
a SyntaxError
. If the scheme name is
not implemented by the browser throw
a NotSupportedError
. If scheme name is
turn
or turns
, and parsing the url
using the syntax defined in [RFC7065] fails, throw a SyntaxError
. If scheme
name is stun
or
stuns
, and parsing the
url using the syntax defined in
[RFC7064] fails, throw a
SyntaxError
.
If scheme name is turn
or turns
, and either of
server.
or
server.username
are
omitted, then throw an
credential
InvalidAccessError
.
If scheme name is turn
or turns
, and
server.
is
"credentialType
", and
server.password
is not
a DOMString, then
throw an credential
InvalidAccessError
.
Append server to validatedServers.
Set the ICE Agent's ICE servers list to validatedServers.
As defined in [RFC8829] (section 4.1.18.), if a new list of servers replaces the ICE Agent's existing ICE servers list, no action will be taken until the next gathering phase. If a script wants this to happen immediately, it should do an ICE restart. However, if the ICE candidate pool has a nonzero size, any existing pooled candidates will be discarded, and new candidates will be gathered from the new servers.
Store configuration in the [[Configuration]] internal slot.
To set a configuration with configuration, run the following steps:
Let connection be the target RTCPeerConnection
object.
Let oldConfig be
connection.[[Configuration]]
.
If oldConfig is not null
, run the
following steps, and if any of them fail, throw
an InvalidModificationError
:
If the length of
configuration.certificates
is different from the length of
oldConfig.certificates
,
fail.
Let index be 0.
While index is less than the length of
configuration.certificates
,
run the following steps:
If the ECMAScript object represented by the value of
configuration.certificates
at index is not the same as the ECMAScript
object represented by the value of
oldConfig.certificates
at index, then fail.
Increment index by 1.
If the value of
configuration.bundlePolicy
differs from
oldConfig.bundlePolicy
,
then fail.
If the value of
configuration.rtcpMuxPolicy
differs from
oldConfig.rtcpMuxPolicy
,
then fail.
If the value of
configuration.iceCandidatePoolSize
differs from
oldConfig.iceCandidatePoolSize
,
and setLocalDescription
has already been
called, then fail.
For each server in
configuration.iceServers
,
run the following steps:
Let urls be
server.urls
.
If urls is a string, set urls to a list consisting of just that string.
If urls is empty, throw a
SyntaxError
.
For each url in urls run the following steps:
Parse the url using the generic URI syntax
defined in [RFC3986] and obtain the scheme
name. If the parsing based on the syntax
defined in [RFC3986] fails, throw
a SyntaxError
. If the scheme name is
not implemented by the browser throw
a NotSupportedError
. If scheme name is
turn
or turns
, and parsing the url
using the syntax defined in [RFC7065] fails, throw a SyntaxError
. If scheme
name is stun
or
stuns
, and parsing the
url using the syntax defined in
[RFC7064] fails, throw a
SyntaxError
.
If scheme name is turn
or turns
, and either of
server.username
or
server.credential
are
omitted, then throw an
InvalidAccessError
.
If scheme name is turn
or turns
, and
server.credential
is not
a DOMString, then
throw an InvalidAccessError
.
Set the ICE Agent's ICE transports setting to the
value of
configuration.iceTransportPolicy
.
As defined in [RFC8829] (section 4.1.18.), if the new ICE transports setting changes the existing setting, no action
will be taken until the next gathering phase. If a script
wants this to happen immediately, it should do an ICE
restart.
Set the ICE Agent's prefetched ICE candidate pool
size as defined in [RFC8829] (section 3.5.4. and section 4.1.1.) to the
value of
configuration.iceCandidatePoolSize
.
If the new ICE candidate pool size changes the existing
setting, this may result in immediate gathering of new pooled
candidates, or discarding of existing pooled candidates, as
defined in [RFC8829] (section 4.1.18.).
Set the ICE Agent's ICE
servers list to
configuration.iceServers
.
As defined in [RFC8829] (section 4.1.18.), if a new list of servers replaces the ICE Agent's existing ICE servers list, no action will be taken until the next gathering phase. If a script wants this to happen immediately, it should do an ICE restart. However, if the ICE candidate pool has a nonzero size, any existing pooled candidates will be discarded, and new candidates will be gathered from the new servers.
Store configuration in the
[[Configuration]]
internal slot.
The RTCPeerConnection
interface presented in this
section is extended by several partial interfaces throughout this
specification. Notably, the RTP Media API section, which adds
the APIs to send and receive MediaStreamTrack
objects.
WebIDL[Exposed=Window]
interface RTCPeerConnection
: EventTarget {
constructor
(optional RTCConfiguration
configuration = {});
Promise<RTCSessionDescriptionInit
> createOffer
(optional RTCOfferOptions
options = {});
Promise<RTCSessionDescriptionInit
> createAnswer
(optional RTCAnswerOptions
options = {});
Promise<undefined> setLocalDescription
(optional RTCLocalSessionDescriptionInit
description = {});
readonly attribute RTCSessionDescription
? localDescription
;
readonly attribute RTCSessionDescription
? currentLocalDescription
;
readonly attribute RTCSessionDescription
? pendingLocalDescription
;
Promise<undefined> setRemoteDescription
(RTCSessionDescriptionInit
description);
readonly attribute RTCSessionDescription
? remoteDescription
;
readonly attribute RTCSessionDescription
? currentRemoteDescription
;
readonly attribute RTCSessionDescription
? pendingRemoteDescription
;
Promise<undefined> addIceCandidate
(optional RTCIceCandidateInit
candidate = {});
readonly attribute RTCSignalingState
signalingState
;
readonly attribute RTCIceGatheringState
iceGatheringState
;
readonly attribute RTCIceConnectionState
iceConnectionState
;
readonly attribute RTCPeerConnectionState
connectionState
;
readonly attribute boolean? canTrickleIceCandidates
;
undefined restartIce
();
RTCConfiguration
getConfiguration
();
undefined setConfiguration
(optional RTCConfiguration
configuration = {});
undefined close
();
attribute EventHandler onnegotiationneeded
;
attribute EventHandler onicecandidate
;
attribute EventHandler onicecandidateerror
;
attribute EventHandler onsignalingstatechange
;
attribute EventHandler oniceconnectionstatechange
;
attribute EventHandler onicegatheringstatechange
;
attribute EventHandler onconnectionstatechange
;
// Legacy Interface Extensions
// Supporting the methods in this section is optional.
// If these methods are supported
// they must be implemented as defined
// in section "Legacy Interface Extensions"
Promise<undefined> createOffer
(RTCSessionDescriptionCallback
successCallback,
RTCPeerConnectionErrorCallback
failureCallback,
optional RTCOfferOptions
options = {});
Promise<undefined> setLocalDescription
(RTCLocalSessionDescriptionInit
description,
VoidFunction successCallback,
RTCPeerConnectionErrorCallback
failureCallback);
Promise<undefined> createAnswer
(RTCSessionDescriptionCallback
successCallback,
RTCPeerConnectionErrorCallback
failureCallback);
Promise<undefined> setRemoteDescription
(RTCSessionDescriptionInit
description,
VoidFunction successCallback,
RTCPeerConnectionErrorCallback
failureCallback);
Promise<undefined> addIceCandidate
(RTCIceCandidateInit
candidate,
VoidFunction successCallback,
RTCPeerConnectionErrorCallback
failureCallback);
};
localDescription
of type RTCSessionDescription
, readonly,
nullable
The localDescription
attribute MUST return
[[PendingLocalDescription]]
if it is not
null
and otherwise it MUST return
[[CurrentLocalDescription]]
.
Note that
[[CurrentLocalDescription]]
.sdp
and
[[PendingLocalDescription]]
.sdp
need not be string-wise identical to the
sdp
value passed to the
corresponding setLocalDescription
call (i.e. SDP may be
parsed and reformatted, and ICE candidates may be added).
currentLocalDescription
of type RTCSessionDescription
, readonly,
nullable
The currentLocalDescription
attribute MUST return
[[CurrentLocalDescription]]
.
It represents the local description that was successfully
negotiated the last time the RTCPeerConnection
transitioned into the stable state plus any local
candidates that have been generated by the ICE Agent
since the offer or answer was created.
pendingLocalDescription
of type RTCSessionDescription
, readonly,
nullable
The pendingLocalDescription
attribute MUST return
[[PendingLocalDescription]]
.
It represents a local description that is in the process of
being negotiated plus any local candidates that have been
generated by the ICE Agent since the offer or answer
was created. If the RTCPeerConnection
is in the stable
state, the value is null
.
remoteDescription
of type RTCSessionDescription
, readonly,
nullable
The remoteDescription
attribute MUST return
[[PendingRemoteDescription]]
if it is not
null
and otherwise it MUST return
[[CurrentRemoteDescription]]
.
Note that
[[CurrentRemoteDescription]]
.sdp
and
[[PendingRemoteDescription]]
.sdp
need not be string-wise identical to the
sdp
value passed to the
corresponding setRemoteDescription
call (i.e. SDP may be
parsed and reformatted, and ICE candidates may be added).
currentRemoteDescription
of type RTCSessionDescription
, readonly,
nullable
The currentRemoteDescription
attribute MUST return
[[CurrentRemoteDescription]]
.
It represents the last remote description that was
successfully negotiated the last time the
RTCPeerConnection
transitioned into the stable state
plus any remote candidates that have been supplied via
addIceCandidate
()
since the offer or
answer was created.
pendingRemoteDescription
of type RTCSessionDescription
, readonly,
nullable
The pendingRemoteDescription
attribute MUST return
[[PendingRemoteDescription]]
.
It represents a remote description that is in the process
of being negotiated, complete with any remote candidates
that have been supplied via
addIceCandidate
()
since the offer or
answer was created. If the RTCPeerConnection
is in the
stable state, the value is null
.
signalingState
of
type RTCSignalingState
,
readonly
The signalingState
attribute MUST return the
RTCPeerConnection
object's signaling state.
iceGatheringState
of type RTCIceGatheringState
, readonly
The iceGatheringState
attribute MUST return the ICE gathering state of the RTCPeerConnection
instance.
iceConnectionState
of type RTCIceConnectionState
, readonly
The iceConnectionState
attribute MUST return the ICE connection state of the RTCPeerConnection
instance.
connectionState
of type RTCPeerConnectionState
, readonly
The connectionState
attribute MUST return the connection state of the RTCPeerConnection
instance.
canTrickleIceCandidates
of type
boolean, readonly, nullable
The canTrickleIceCandidates
attribute indicates whether
the remote peer is able to accept trickled ICE candidates
[RFC8838]. The value is determined based on whether a
remote description indicates support for trickle ICE, as
defined in [RFC8829] (section 4.1.17.).
Prior to the completion of
setRemoteDescription
, this value is
null
.
onnegotiationneeded
of type
EventHandler
negotiationneeded
.
onicecandidate
of type EventHandler
icecandidate
.
onicecandidateerror
of type
EventHandler
icecandidateerror
.
onsignalingstatechange
of type
EventHandler
signalingstatechange
.
oniceconnectionstatechange
of type
EventHandler
iceconnectionstatechange
onicegatheringstatechange
of type
EventHandler
icegatheringstatechange
.
onconnectionstatechange
of type
EventHandler
connectionstatechange
.
createOffer
The createOffer
method generates a blob of SDP that
contains an RFC 3264 offer with the supported
configurations for the session, including descriptions of
the local MediaStreamTrack
s attached to this
RTCPeerConnection
, the codec/RTP/RTCP capabilities
supported by this implementation, and parameters of the ICE agent and the DTLS connection. The
options parameter may be supplied to provide
additional control over the offer generated.
If a system has limited resources (e.g. a finite number of
decoders), createOffer
needs to return an offer that
reflects the current state of the system, so that
setLocalDescription
will succeed when it attempts to
acquire those resources. The session descriptions MUST
remain usable by setLocalDescription
without causing an
error until at least the end of the fulfillment
callback of the returned promise.
Creating the SDP MUST follow the appropriate process for
generating an offer described in [RFC8829], except the user
agent MUST treat a stopping
transceiver as stopped
for the
purposes of RFC8829 in this case.
As an offer, the generated SDP will contain the full set of
codec/RTP/RTCP capabilities supported or preferred by the
session (as opposed to an answer, which will include only a
specific negotiated subset to use). In the event
createOffer
is called after the session is established,
createOffer
will generate an offer that is compatible
with the current session, incorporating any changes that
have been made to the session since the last complete
offer-answer exchange, such as addition or removal of
tracks. If no changes have been made, the offer will
include the capabilities of the current local description
as well as any additional capabilities that could be
negotiated in an updated offer.
The generated SDP will also contain the ICE agent's
usernameFragment
,
password
and ICE options (as defined
in [RFC5245], Section 14) and may also contain any local
candidates that have been gathered by the agent.
The certificates
value in
configuration for the RTCPeerConnection
provides the certificates configured by the application for
the RTCPeerConnection
. These certificates, along with
any default certificates are used to produce a set of
certificate fingerprints. These certificate fingerprints
are used in the construction of SDP.
The process of generating an SDP exposes a subset of the
media capabilities of the underlying system, which provides
generally persistent cross-origin information on the
device. It thus increases the fingerprinting surface of the
application. In privacy-sensitive contexts, browsers can
consider mitigations such as generating SDP matching only a
common subset of the capabilities.
When the method is called, the user agent MUST run the following steps:
Let connection be the RTCPeerConnection
object on which the method was invoked.
If connection.[[IsClosed]]
is
true
, return a promise rejected with
a newly created InvalidStateError
.
Return the result of chaining the result of creating an offer with connection to connection's operations chain.
To create an offer given connection run the following steps:
If connection's signaling state is
neither "stable
" nor
"have-local-offer
", return a
promise rejected with a newly created InvalidStateError
.
Let p be a new promise.
In parallel, begin the in-parallel steps to create an offer given connection and p.
Return p.
The in-parallel steps to create an offer given connection and a promise p are as follows:
If connection was not constructed with a set of certificates, and one has not yet been generated, wait for it to be generated.
Inspect the offerer's system state to determine the currently available resources as necessary for generating the offer, as described in [RFC8829] (section 4.1.8.).
If this inspection failed for any reason, reject
p with a newly created
OperationError
and abort these steps.
Queue a task that runs the final steps to create an offer given connection and p.
The final steps to create an offer given connection and a promise p are as follows:
If connection.[[IsClosed]]
is
true
, then abort these steps.
If connection was modified in such a way that additional inspection of the offerer's system state is necessary, then in parallel begin the in-parallel steps to create an offer again, given connection and p, and abort these steps.
createOffer
was called when only an audio RTCRtpTransceiver
was
added to connection, but while performing
the in-parallel steps to create an offer, a video
RTCRtpTransceiver
was added, requiring additional
inspection of video system resources.
Given the information that was obtained from previous
inspection, the current state of connection
and its RTCRtpTransceiver
s, generate an SDP offer,
sdpString, as described in [RFC8829] (section 5.2.).
As described in [RFC8843] (Section 7), if
bundling is used (see RTCBundlePolicy
) an
offerer tagged m= section must be selected in order
to negotiate a BUNDLE group. The user agent MUST
choose the m= section that corresponds to the first
non-stopped transceiver in the set of transceivers as the offerer tagged m= section.
This allows the remote endpoint to predict which
transceiver is the offerer tagged m= section
without having to parse the SDP.
The codec preferences of a media description's associated transceiver is
said to be the value of the
RTCRtpTransceiver
.[[PreferredCodecs]]
with the following filtering applied (or said not
to be set if [[PreferredCodecs]]
is empty):
If the direction
is
"sendrecv
",
exclude any codecs not included in the
intersection of
RTCRtpSender
.getCapabilities
(kind).codecs
and
RTCRtpReceiver
.getCapabilities
(kind).codecs
.
If the direction
is
"sendonly
",
exclude any codecs not included in
RTCRtpSender
.getCapabilities
(kind).codecs
.
If the direction
is
"recvonly
",
exclude any codecs not included in
RTCRtpReceiver
.getCapabilities
(kind).codecs
.
The filtering MUST NOT change the order of the codec preferences.
If the length of the [[SendEncodings]]
slot
of the RTCRtpSender
is larger than 1, then for
each encoding given in [[SendEncodings]]
of
the RTCRtpSender
, add an a=rid send
line to the corresponding
media section, and add an a=simulcast:send
line giving the RIDs
in the same order as given in the
encodings
field. No RID
restrictions are set.
[RFC8853] section 5.2 specifies that the order of RIDs in the a=simulcast line suggests a proposed order of preference. If the browser decides not to transmit all encodings, one should expect it to stop sending the last encoding in the list first.
Let offer be a newly created
RTCSessionDescriptionInit
dictionary with its
type
member initialized
to the string "offer
" and its
sdp
member initialized to
sdpString.
Set the [[LastCreatedOffer]]
internal slot to
sdpString.
Resolve p with offer.
createAnswer
The createAnswer
method generates an [SDP] answer
with the supported configuration for the session that is
compatible with the parameters in the remote configuration.
Like createOffer
, the returned blob of SDP contains
descriptions of the local MediaStreamTrack
s attached to
this RTCPeerConnection
, the codec/RTP/RTCP options
negotiated for this session, and any candidates that have
been gathered by the ICE Agent. The
options parameter may be supplied to provide
additional control over the generated answer.
Like createOffer
, the returned description SHOULD
reflect the current state of the system. The session
descriptions MUST remain usable by setLocalDescription
without causing an error until at least the end of the fulfillment callback of the returned promise.
As an answer, the generated SDP will contain a specific codec/RTP/RTCP configuration that, along with the corresponding offer, specifies how the media plane should be established. The generation of the SDP MUST follow the appropriate process for generating an answer described in [RFC8829].
The generated SDP will also contain the ICE agent's
usernameFragment
,
password
and ICE options (as defined
in [RFC5245], Section 14) and may also contain any local
candidates that have been gathered by the agent.
The certificates
value in
configuration for the RTCPeerConnection
provides the certificates configured by the application for
the RTCPeerConnection
. These certificates, along with
any default certificates are used to produce a set of
certificate fingerprints. These certificate fingerprints
are used in the construction of SDP.
An answer can be marked as provisional, as described in
[RFC8829] (section 4.1.10.1.), by setting
the type
to
"pranswer
".
When the method is called, the user agent MUST run the following steps:
Let connection be the RTCPeerConnection
object on which the method was invoked.
If connection.[[IsClosed]]
is
true
, return a promise rejected with
a newly created InvalidStateError
.
Return the result of chaining the result of creating an answer with connection to connection's operations chain.
To create an answer given connection run the following steps:
If connection's signaling state is
neither "have-remote-offer
" nor
"have-local-pranswer
", return a
promise rejected with a newly created InvalidStateError
.
Let p be a new promise.
In parallel, begin the in-parallel steps to create an answer given connection and p.
Return p.
The in-parallel steps to create an answer given connection and a promise p are as follows:
If connection was not constructed with a set of certificates, and one has not yet been generated, wait for it to be generated.
Inspect the answerer's system state to determine the currently available resources as necessary for generating the answer, as described in [RFC8829] (section 4.1.9.).
If this inspection failed for any reason, reject
p with a newly created
OperationError
and abort these steps.
Queue a task that runs the final steps to create an answer given p.
The final steps to create an answer given a promise p are as follows:
If connection.[[IsClosed]]
is
true
, then abort these steps.
If connection was modified in such a way that additional inspection of the answerer's system state is necessary, then in parallel begin the in-parallel steps to create an answer again given connection and p, and abort these steps.
createAnswer
was called when an RTCRtpTransceiver
's direction
was "recvonly
", but
while performing the in-parallel steps to create an answer, the direction was changed to
"sendrecv
", requiring
additional inspection of video encoding resources.
Given the information that was obtained from previous
inspection and the current state of
connection and its RTCRtpTransceiver
s,
generate an SDP answer, sdpString, as
described in [RFC8829] (section 5.3.).
The codec preferences of an m= section's
associated transceiver is said to be the value of
the
.[[PreferredCodecs]]
with the following filtering applied (or said not
to be set if [[PreferredCodecs]] is empty):
RTCRtpTransceiver
If the
is
"direction
",
exclude any codecs not included in the
intersection of
sendrecv
.RTCRtpSender
(kind).getCapabilities
and
codecs
.RTCRtpReceiver
(kind).getCapabilities
.
codecs
If the
is
"direction
",
exclude any codecs not included in
sendonly
.RTCRtpSender
(kind).getCapabilities
.
codecs
If the
is
"direction
",
exclude any codecs not included in
recvonly
.RTCRtpReceiver
(kind).getCapabilities
.
codecs
The filtering MUST NOT change the order of the codec preferences.
If the length of the [[SendEncodings]] slot
of the
is larger than 1, then for
each encoding given in [[SendEncodings]] of
the RTCRtpSender
, add an RTCRtpSender
a=rid send
line to the corresponding
media section, and add an a=simulcast:send
line giving the RIDs
in the same order as given in the
field. No RID
restrictions are set.
encodings
The codec preferences of an m= section's
associated transceiver is said to be the value of
the
RTCRtpTransceiver
.[[PreferredCodecs]]
with the following filtering applied (or said not
to be set if [[PreferredCodecs]]
is empty):
If the direction
is
"sendrecv
",
exclude any codecs not included in the
intersection of
RTCRtpSender
.getCapabilities
(kind).codecs
and
RTCRtpReceiver
.getCapabilities
(kind).codecs
.
If the direction
is
"sendonly
",
exclude any codecs not included in
RTCRtpSender
.getCapabilities
(kind).codecs
.
If the direction
is
"recvonly
",
exclude any codecs not included in
RTCRtpReceiver
.getCapabilities
(kind).codecs
.
The filtering MUST NOT change the order of the codec preferences.
If this is an answer to an offer to receive simulcast, then for each media section requesting to receive simulcast, run the following steps:
If the a=simulcast
attribute contains comma-separated alternatives
for RIDs, remove all but the first ones.
If there are any identically named RIDs in the
a=simulcast
attribute,
remove all but the first one. No RID
restrictions are set.
Exclude from the media section in the answer any
RID not found in the corresponding transceiver's
[[Sender]]
.[[SendEncodings]]
.
When a
setRemoteDescription
(offer)
establishes a transceiver's proposed envelope,
the transceiver's
[[Sender]]
.[[SendEncodings]]
is updated in
"have-remote-offer
", exposing
it to rollback. However, once a
simulcast envelope has been established for
the transceiver, subsequent pruning of the
transceiver's
[[Sender]]
.[[SendEncodings]]
happen when this answer is set with
setLocalDescription
.
Let answer be a newly created
RTCSessionDescriptionInit
dictionary with its
type
member initialized
to the string "answer
" and its
sdp
member initialized to
sdpString.
Set the [[LastCreatedAnswer]]
internal slot to
sdpString.
Resolve p with answer.
setLocalDescription
The setLocalDescription
method instructs the
RTCPeerConnection
to apply the supplied
RTCLocalSessionDescriptionInit
as the local
description.
This API changes the local media state. In order to
successfully handle scenarios where the application wants
to offer to change from one media format to a different,
incompatible format, the RTCPeerConnection
MUST be able
to simultaneously support use of both the current and
pending local descriptions (e.g. support codecs that exist
in both descriptions) until a final answer is received, at
which point the RTCPeerConnection
can fully adopt the
pending local description, or rollback to the current
description if the remote side rejected the change.
Passing in a description is optional. If left out, then
setLocalDescription
will implicitly create an offer or create an answer, as needed. As noted in
[RFC8829] (section 5.4.), if a
description with SDP is passed in, that SDP is not allowed
to have changed from when it was returned from either
createOffer
or createAnswer
.
When the method is invoked, the user agent MUST run the following steps:
Let description be the method's first argument.
Let connection be the RTCPeerConnection
object on which the method was invoked.
Let sdp be
description.sdp
.
Return the result of chaining the following steps to connection's operations chain:
Let type be
description.type
if present, or "offer
" if not
present and connection's signaling state is either "stable
",
"have-local-offer
", or
"have-remote-pranswer
";
otherwise "answer
".
If type is "offer
", and
sdp is not the empty string and not
equal to
connection.[[LastCreatedOffer]]
,
then return a promise rejected with a newly
created
InvalidModificationError
and abort these steps.
If type is "answer
" or
"pranswer
", and sdp is
not the empty string and not equal to
connection.[[LastCreatedAnswer]]
,
then return a promise rejected with a newly
created
InvalidModificationError
and abort these steps.
If sdp is the empty string, and
type is "offer
", then run
the following sub steps:
Set sdp to the value of
connection.[[LastCreatedOffer]]
.
If sdp is the empty string, or if it no longer accurately represents the offerer's system state of connection, then let p be the result of creating an offer with connection, and return the result of reacting to p with a fulfillment step that sets the local session description indicated by its first argument.
If sdp is the empty string, and
type is "answer
" or
"pranswer
", then run the following
sub steps:
Set sdp to the value of
connection.[[LastCreatedAnswer]]
.
If sdp is the empty string, or if it no longer accurately represents the answerer's system state of connection, then let p be the result of creating an answer with connection, and return the result of reacting to p with the following fulfillment steps:
Let answer be the first argument to these fulfillment steps.
Return the result of setting the local session description indicated by
{type,
answer.
.
sdp
}
Return the result of setting the local session description indicated by {type, sdp}
.
As noted in [RFC8829] (section 5.9.), calling this method may trigger the ICE candidate gathering process by the ICE Agent.
setRemoteDescription
The setRemoteDescription
method instructs the
RTCPeerConnection
to apply the supplied
RTCSessionDescriptionInit
as the remote offer or
answer. This API changes the local media state.
When the method is invoked, the user agent MUST run the following steps:
Let description be the method's first argument.
Let connection be the RTCPeerConnection
object on which the method was invoked.
Return the result of chaining the following steps to connection's operations chain:
If
description.type
is "offer
" and is invalid for the
current signaling state of
connection as described in
[RFC8829] (section 5.5. and section 5.6.),
then run the following sub steps:
Let p be the result of setting the local session description indicated by
{type:
"
.
rollback
"}
Return the result of reacting to p with a fulfillment step that sets the remote session description description, and abort these steps.
Return the result of setting the remote session description description.
addIceCandidate
The addIceCandidate
method provides a remote candidate
to the ICE Agent. This method can also be used to
indicate the end of remote candidates when called with an
empty string for the candidate
member.
The only members of the argument used by this method are
candidate
, sdpMid
,
sdpMLineIndex
, and
usernameFragment
; the rest are ignored.
When the method is invoked, the user agent MUST run the
following steps:
Let candidate be the method's argument.
Let connection be the RTCPeerConnection
object on which the method was invoked.
If candidate.candidate
is not an empty string and both
candidate.sdpMid
and
candidate.sdpMLineIndex
are null
, return a promise rejected
with a newly created TypeError
.
Return the result of chaining the following steps to connection's operations chain:
If remoteDescription
is
null
return a promise rejected
with a newly created
InvalidStateError
.
If candidate.sdpMid
is not null
, run the following steps:
If
candidate.sdpMid
is not equal to the mid of any media
description in
remoteDescription
, return
a promise rejected with a newly created OperationError
.
Else, if
candidate.sdpMLineIndex
is not null
, run the following steps:
If
candidate.sdpMLineIndex
is equal to or larger than the number of media
descriptions in
remoteDescription
, return
a promise rejected with a newly created OperationError
.
If either
candidate.sdpMid
or
candidate.sdpMLineIndex
indicate a media description in
remoteDescription
whose
associated transceiver is stopped
, return a promise resolved with
undefined
.
If
candidate.usernameFragment
is not null
, and is not equal to any
username fragment present in the corresponding media description of an applied remote
description, return a promise rejected with a
newly created OperationError
.
Let p be a new promise.
In parallel, if the candidate is not administratively prohibited, add the ICE
candidate candidate as described in
[RFC8829] (section 4.1.19.).
Use
candidate.usernameFragment
to identify the ICE generation; if
usernameFragment
is
null
, process the candidate
for the most recent ICE generation.
If
candidate.candidate
is an empty string, process candidate as
an end-of-candidates indication for the
corresponding media description and ICE
candidate generation. If both
candidate.sdpMid
and
candidate.sdpMLineIndex
are null
, then this end-of-candidates
indication applies to all media descriptions.
If candidate could not be successfully added the user agent MUST queue a task that runs the following steps:
If
connection.[[IsClosed]]
is true
, then abort these
steps.
Reject p with a newly created OperationError
and
abort these steps.
If candidate is applied successfully, or if the candidate was administratively prohibited the user agent MUST queue a task that runs the following steps:
If
connection.[[IsClosed]]
is true
, then abort these
steps.
If
connection.[[PendingRemoteDescription]]
is not null
, and represents
the ICE generation for which
candidate was processed, add
candidate to
connection.[[PendingRemoteDescription]]
.sdp.
If
connection.[[CurrentRemoteDescription]]
is not null
, and represents
the ICE generation for which
candidate was processed, add
candidate to
connection.[[CurrentRemoteDescription]]
.sdp.
Resolve p with
undefined
.
Return p.
A candidate is administratively prohibited if the UA has decided not to allow connection attempts to this address.
For privacy reasons, there is no indication to the developer about whether or not an address/port is blocked; it behaves exactly as if there was no response from the address.
The UA MUST prohibit connections to addresses on the [Fetch] block bad port list, and MAY choose to prohibit connections to other addresses.
If the iceTransportPolicy
member of
the RTCConfiguration
is
relay
, candidates requiring
external resolution, such as mDNS candidates and DNS
candidates, MUST be prohibited.
Due to WebIDL processing,
addIceCandidate
(null
) is
interpreted as a call with the default dictionary present,
which, in the above algorithm, indicates end-of-candidates
for all media descriptions and ICE candidate generation.
This is by design for legacy reasons.
restartIce
The restartIce
method tells the RTCPeerConnection
that ICE should be restarted. Subsequent calls to
createOffer
will create descriptions that will restart
ICE, as described in section 9.1.1.1 of [RFC5245].
When this method is invoked, the user agent MUST run the following steps:
Let connection be the RTCPeerConnection
on which the method was invoked.
Empty
connection.[[LocalIceCredentialsToReplace]]
,
and populate it with all ICE credentials (ice-ufrag and
ice-pwd as defined in section 15.4 of [RFC5245]) found
in
connection.[[CurrentLocalDescription]]
,
as well as all ICE credentials found in
connection.[[PendingLocalDescription]]
.
Update the negotiation-needed flag for connection.
getConfiguration
Returns an RTCConfiguration
object representing the
current configuration of this RTCPeerConnection
object.
When this method is called, the user agent MUST return the
RTCConfiguration
object stored in the
[[Configuration]]
internal slot.
setConfiguration
The setConfiguration
method updates the configuration
of this RTCPeerConnection
object. This includes
changing the configuration of the ICE Agent. As noted
in [RFC8829] (section 3.5.1.),
when the ICE configuration changes in a way that requires a
new gathering phase, an ICE restart is required.
When the setConfiguration
method is invoked, the user
agent MUST run the following steps:
Let connection be the RTCPeerConnection
on which the method was invoked.
If connection.[[IsClosed]]
is
true
, throw an
InvalidStateError
.
Set the configuration specified by configuration.
close
When the close
method is invoked, the user agent MUST
run the following steps:
Let connection be the RTCPeerConnection
object on which the method was invoked.
false
.
The close the connection algorithm given a connection and a disappear boolean, is as follows:
If connection.[[IsClosed]]
is
true
, abort these steps.
Set connection.[[IsClosed]]
to
true
.
Set connection's signaling state to
"closed
". This does not fire any
event.
Let transceivers be the result of executing
the CollectTransceivers
algorithm. For every
RTCRtpTransceiver
transceiver in
transceivers, run the following steps:
If transceiver.[[Stopped]]
is
true
, abort these sub steps.
Stop the RTCRtpTransceiver with transceiver and disappear.
Set the [[ReadyState]]
slot of each of
connection's RTCDataChannel
s to
"closed
".
RTCDataChannel
s will be closed abruptly and the
closing procedure will not be invoked.
If connection.[[SctpTransport]]
is
not null
, tear down the underlying SCTP
association by sending an SCTP ABORT chunk and set the
[[SctpTransportState]]
to
"closed
".
Set the [[DtlsTransportState]]
slot of each of
connection's RTCDtlsTransport
s to
"closed
".
Destroy connection's ICE Agent, abruptly ending any active ICE processing and releasing any relevant resources (e.g. TURN permissions).
Set the [[IceTransportState]]
slot of each of
connection's RTCIceTransport
s to
"closed
".
Set connection's ICE connection state
to "closed
". This does not
fire any event.
Set connection's connection state to
"closed
". This does not fire
any event.
RTCPeerConnection
interface since overloaded
functions are not allowed to be defined in partial interfaces.
Supporting the methods in this section is optional. However, if these methods are supported it is mandatory to implement according to what is specified here.
addStream
method that used to exist on
RTCPeerConnection
is easy to polyfill as:
RTCPeerConnection.prototype.addStream = function(stream) {
stream.getTracks().forEach((track) => this.addTrack(track, stream));
};
createOffer
When the createOffer
method
is called, the user agent MUST run the following steps:
Let successCallback be the method's first argument.
Let failureCallback be the callback indicated by the method's second argument.
Let options be the callback indicated by the method's third argument.
Run the steps specified by RTCPeerConnection
's
createOffer
()
method with
options as the sole argument, and let
p be the resulting promise.
Upon fulfillment of p with value offer, invoke successCallback with offer as the argument.
Upon rejection of p with reason r, invoke failureCallback with r as the argument.
Return a promise resolved with
undefined
.
setLocalDescription
When the setLocalDescription
method is called,
the user agent MUST run the following steps:
Let description be the method's first argument.
Let successCallback be the callback indicated by the method's second argument.
Let failureCallback be the callback indicated by the method's third argument.
Run the steps specified by RTCPeerConnection
's
setLocalDescription
method with
description as the sole argument, and let
p be the resulting promise.
Upon fulfillment of p, invoke
successCallback with
undefined
as the argument.
Upon rejection of p with reason r, invoke failureCallback with r as the argument.
Return a promise resolved with
undefined
.
createAnswer
createAnswer
method does not take an RTCAnswerOptions
parameter,
since no known legacy createAnswer
implementation ever
supported it.
When the createAnswer
method is called, the user agent MUST run the following
steps:
Let successCallback be the method's first argument.
Let failureCallback be the callback indicated by the method's second argument.
Run the steps specified by RTCPeerConnection
's
createAnswer
()
method with no
arguments, and let p be the resulting
promise.
Upon fulfillment of p with value answer, invoke successCallback with answer as the argument.
Upon rejection of p with reason r, invoke failureCallback with r as the argument.
Return a promise resolved with
undefined
.
setRemoteDescription
When the setRemoteDescription
method is called,
the user agent MUST run the following steps:
Let description be the method's first argument.
Let successCallback be the callback indicated by the method's second argument.
Let failureCallback be the callback indicated by the method's third argument.
Run the steps specified by RTCPeerConnection
's
setRemoteDescription
method
with description as the sole argument, and
let p be the resulting promise.
Upon fulfillment of p, invoke
successCallback with
undefined
as the argument.
Upon rejection of p with reason r, invoke failureCallback with r as the argument.
Return a promise resolved with
undefined
.
addIceCandidate
When the addIceCandidate
method is called, the user agent MUST run the following
steps:
Let candidate be the method's first argument.
Let successCallback be the callback indicated by the method's second argument.
Let failureCallback be the callback indicated by the method's third argument.
Run the steps specified by RTCPeerConnection
's
addIceCandidate
()
method with
candidate as the sole argument, and let
p be the resulting promise.
Upon fulfillment of p, invoke
successCallback with
undefined
as the argument.
Upon rejection of p with reason r, invoke failureCallback with r as the argument.
Return a promise resolved with
undefined
.
These callbacks are only used on the legacy APIs.
WebIDLcallback RTCPeerConnectionErrorCallback
= undefined (DOMException error);
RTCPeerConnectionErrorCallback
Parameters
error
of type
DOMException
WebIDLcallback RTCSessionDescriptionCallback
= undefined (RTCSessionDescriptionInit
description);
RTCSessionDescriptionCallback
Parameters
RTCSessionDescriptionInit
This section describes a set of legacy extensions that may be
used to influence how an offer is created, in addition to the
media added to the RTCPeerConnection
. Developers are
encouraged to use the RTCRtpTransceiver
API instead.
When createOffer
is called with any of the
legacy options specified in this section, run the followings
steps instead of the regular createOffer
steps:
Let options be the methods first argument.
Let connection be the current
RTCPeerConnection
object.
For each offerToReceive<Kind>
member in options with kind, kind, run
the following steps:
For each non-stopped
"sendrecv
" transceiver
of transceiver kind kind, set
transceiver.[[Direction]]
to
"sendonly
".
For each non-stopped
"recvonly
" transceiver
of transceiver kind kind, set
transceiver.[[Direction]]
to
"inactive
".
Continue with the next option, if any.
If connection has any non-stopped
"sendrecv
" or
"recvonly
" transceivers of
transceiver kind kind, continue with the
next option, if any.
Let transceiver be the result of invoking the
equivalent of
connection.addTransceiver
(kind),
except that this operation MUST NOT update the negotiation-needed flag.
If transceiver is unset because the previous operation threw an error, abort these steps.
Set transceiver.[[Direction]]
to
"recvonly
".
Run the steps specified by createOffer
to create the offer.
WebIDLpartial dictionary RTCOfferOptions
{
boolean offerToReceiveAudio
;
boolean offerToReceiveVideo
;
};
offerToReceiveAudio
of type boolean
This setting provides additional control over the directionality of audio. For example, it can be used to ensure that audio can be received, regardless if audio is sent or not.
offerToReceiveVideo
of type boolean
This setting provides additional control over the directionality of video. For example, it can be used to ensure that video can be received, regardless if video is sent or not.
An RTCPeerConnection
object MUST not be garbage collected as
long as any event can cause an event handler to be triggered on the
object. When the object's [[IsClosed]]
internal slot is
true
, no such event handler can be triggered and it is
therefore safe to garbage collect the object.
All RTCDataChannel
and MediaStreamTrack
objects that are
connected to an RTCPeerConnection
have a strong reference to
the RTCPeerConnection
object.
All methods that return promises are governed by the standard error handling rules of promises. Methods that do not return promises may throw exceptions to indicate errors.
The RTCSdpType
enum describes the type of an
RTCSessionDescriptionInit
, RTCLocalSessionDescriptionInit
,
or RTCSessionDescription
instance.
WebIDLenum RTCSdpType
{
"offer
",
"pranswer
",
"answer
",
"rollback
"
};
Enum value | Description |
---|---|
offer
|
An |
pranswer
|
An |
answer
|
An |
rollback
|
An |
The RTCSessionDescription
class is used by
RTCPeerConnection
to expose local and remote session
descriptions.
WebIDL[Exposed=Window]
interface RTCSessionDescription
{
constructor
(RTCSessionDescriptionInit
descriptionInitDict);
readonly attribute RTCSdpType
type
;
readonly attribute DOMString sdp
;
[Default] object toJSON
();
};
constructor()
The RTCSessionDescription
()
constructor takes a dictionary argument,
description, whose content is used to initialize
the new RTCSessionDescription
object. This constructor
is deprecated; it exists for legacy compatibility reasons
only.
type
of type RTCSdpType
, readonly
sdp
of type DOMString, readonly, defaulting to
""
toJSON()
WebIDLdictionary RTCSessionDescriptionInit
{
required RTCSdpType
type
;
DOMString sdp
= "";
};
type
of type RTCSdpType
, required
sdp
of type DOMString
type
is "rollback
",
this member is unused.
WebIDLdictionary RTCLocalSessionDescriptionInit
{
RTCSdpType
type
;
DOMString sdp
= "";
};
type
of type RTCSdpType
setLocalDescription
will infer the type
based on the RTCPeerConnection
's signaling state.
sdp
of type DOMString
type
is
"rollback
", this member is unused.
Many changes to state of an RTCPeerConnection
will require
communication with the remote side via the signaling channel, in
order to have the desired effect. The app can be kept informed as to
when it needs to do signaling, by listening to the
negotiationneeded
event. This event is fired
according
to the state of the connection's negotiation-needed flag,
represented by a [[NegotiationNeeded]]
internal slot.
This section is non-normative.
If an operation is performed on an RTCPeerConnection
that
requires signaling, the connection will be marked as needing
negotiation. Examples of such operations include adding or stopping
an RTCRtpTransceiver
, or adding the first RTCDataChannel
.
Internal changes within the implementation can also result in the connection being marked as needing negotiation.
Note that the exact procedures for updating the negotiation-needed flag are specified below.
This section is non-normative.
The negotiation-needed flag is cleared when a session description
of type "answer
" is set successfully, and the supplied description
matches the state of the RTCRtpTransceiver
s and
RTCDataChannel
s that currently exist on the
RTCPeerConnection
. Specifically, this means that all
non-stopped
transceivers have an associated section in the local description with matching
properties, and, if any data channels have been created, a data
section exists in the local description.
Note that the exact procedures for updating the negotiation-needed flag are specified below.
The process below occurs where referenced elsewhere in this document. It also may occur as a result of internal changes within the implementation that affect negotiation. If such changes occur, the user agent MUST update the negotiation-needed flag.
To update the negotiation-needed flag for connection, run the following steps:
If the length of connection.[[Operations]]
is not 0
, then set
connection.[[UpdateNegotiationNeededFlagOnEmptyChain]]
to true
, and abort these steps.
Queue a task to run the following steps:
If connection.[[IsClosed]]
is
true
, abort these steps.
If the length of
connection.[[Operations]]
is not
0
, then set
connection.[[UpdateNegotiationNeededFlagOnEmptyChain]]
to true
, and abort these steps.
If connection's signaling state is not
"stable
", abort these steps.
The negotiation-needed flag will be updated once the state
transitions to "stable
", as part of
the steps for setting a session description.
If the result of checking if negotiation is needed is false
,
clear the negotiation-needed flag by setting
connection.[[NegotiationNeeded]]
to
false
, and abort these steps.
If connection.[[NegotiationNeeded]]
is
already true
, abort these steps.
Set connection.[[NegotiationNeeded]]
to
true
.
Fire an event named negotiationneeded
at
connection.
The task queueing prevents negotiationneeded
from firing
prematurely, in the common situation where multiple
modifications to connection are being made at
once.
Additionally, we avoid racing with negotiation methods by
only firing negotiationneeded
when the operations chain is empty.
To check if negotiation is needed for connection, perform the following checks:
If any implementation-specific negotiation is required, as
described at the start of this section, return
true
.
If
connection.[[LocalIceCredentialsToReplace]]
is not empty, return true
.
Let description be
connection.[[CurrentLocalDescription]]
.
If connection has created any RTCDataChannel
s,
and no m= section in description has been negotiated
yet for data, return true
.
For each transceiver in connection's set of transceivers, perform the following checks:
If transceiver.[[Stopping]]
is
true
and
transceiver.[[Stopped]]
is
false
, return true
.
If transceiver isn't stopped
and isn't yet associated with an m= section
in description, return true
.
If transceiver isn't stopped
and is associated with an m= section in
description then perform the following checks:
If transceiver.[[Direction]]
is
"sendrecv
" or
"sendonly
", and the associated m= section in description
either doesn't contain a single a=msid
line, or the number of MSIDs from
the a=msid
lines in this
m=
section, or the MSID values
themselves, differ from what is in
transceiver.sender.[[AssociatedMediaStreamIds]]
,
return true
.
If description is of type
"offer
", and the direction of the associated m= section in neither
connection.[[CurrentLocalDescription]]
nor
connection.[[CurrentRemoteDescription]]
matches transceiver.[[Direction]]
,
return true
. In this step, when the
direction is compared with a direction found in
[[CurrentRemoteDescription]]
, the description's
direction must be reversed to represent the peer's
point of view.
If description is of type
"answer
", and the direction of the associated m= section in the description
does not match
transceiver.[[Direction]]
intersected with the offered direction (as described in
[RFC8829] (section 5.3.1.)),
return true
.
If transceiver is stopped
and is associated with an m= section, but the
associated m= section is not yet rejected in
connection.[[CurrentLocalDescription]]
or
connection.[[CurrentRemoteDescription]]
,
return true
.
If all the preceding checks were performed and
true
was not returned, nothing remains to be
negotiated; return false
.
This interface describes an ICE candidate, described in [RFC5245]
Section 2. Other than candidate
,
sdpMid
,
sdpMLineIndex
, and
usernameFragment
, the remaining attributes
are derived from parsing the candidate
member in candidateInitDict, if it is well formed.
WebIDL[Exposed=Window] interfaceRTCIceCandidate
{constructor
(optionalRTCIceCandidateInit
candidateInitDict = {}); readonly attribute DOMStringcandidate
; readonly attribute DOMString?sdpMid
; readonly attribute unsigned short?sdpMLineIndex
; readonly attribute DOMString?foundation
; readonly attributeRTCIceComponent
?component
; readonly attribute unsigned long?priority
; readonly attribute DOMString?address
; readonly attributeRTCIceProtocol
?protocol
; readonly attribute unsigned short?port
; readonly attributeRTCIceCandidateType
?type
; readonly attributeRTCIceTcpCandidateType
?tcpType
; readonly attribute DOMString?relatedAddress
; readonly attribute unsigned short?relatedPort
; readonly attribute DOMString?usernameFragment
;RTCIceCandidateInit
toJSON
(); };
WebIDL[Exposed=Window]
interface RTCIceCandidate
{
constructor
(optional RTCIceCandidateInit
candidateInitDict = {});
readonly attribute DOMString candidate
;
readonly attribute DOMString? sdpMid
;
readonly attribute unsigned short? sdpMLineIndex
;
readonly attribute DOMString? foundation
;
readonly attribute RTCIceComponent
? component
;
readonly attribute unsigned long? priority
;
readonly attribute DOMString? address
;
readonly attribute RTCIceProtocol
? protocol
;
readonly attribute unsigned short? port
;
readonly attribute RTCIceCandidateType
? type
;
readonly attribute RTCIceTcpCandidateType
? tcpType
;
readonly attribute DOMString? usernameFragment
;
readonly attribute RTCIceServerTransportProtocol
? relayProtocol
;
readonly attribute DOMString? url
;
RTCIceCandidateInit
toJSON
();
};
constructor()
The RTCIceCandidate()
constructor
takes a dictionary argument, candidateInitDict,
whose content is used to initialize the new
RTCIceCandidate
object.
When invoked, run the following steps:
sdpMid
and
sdpMLineIndex
members of
candidateInitDict are null
, throw a TypeError
.
Return the result of creating an RTCIceCandidate with candidateInitDict.
To create an RTCIceCandidate with a candidateInitDict dictionary, run the following steps:
RTCIceCandidate
object.
null
:
foundation
, component
, priority
, address
,
protocol
, port
, type
, tcpType
,
relatedAddress
, and relatedPort
.
candidate
, sdpMid
,
sdpMLineIndex
, usernameFragment
.
candidate
dictionary member of
candidateInitDict. If candidate is
not an empty string, run the following steps:
candidate-attribute
grammar.
candidate-attribute
has failed,
abort these steps.
The constructor for RTCIceCandidate
only does basic
parsing and type checking for the dictionary members in
candidateInitDict. Detailed validation on the
well-formedness of candidate
,
sdpMid
,
sdpMLineIndex
,
usernameFragment
with the
corresponding session description is done when passing
the RTCIceCandidate
object to
addIceCandidate
()
.
To maintain backward compatibility, any error on parsing
the candidate attribute is ignored. In such
case, the candidate
attribute holds the raw
candidate
string given in
candidateInitDict, but derivative attributes
such as foundation
, priority
, etc are set to
null
.
Most attributes below are defined in section 15.1 of [RFC5245].
candidate
of type DOMString, readonly
candidate-attribute
as defined in
section 15.1 of [RFC5245]. If this RTCIceCandidate
represents an end-of-candidates indication or a peer
reflexive remote candidate, candidate
is an empty string.
sdpMid
of type DOMString, readonly, nullable
null
, this contains the media stream
"identification-tag" defined in [RFC5888] for the
media component this candidate is associated with.
sdpMLineIndex
of type unsigned short, readonly, nullable
null
, this indicates the index (starting
at zero) of the media description in the SDP this
candidate is associated with.
foundation
of type DOMString, readonly, nullable
RTCIceTransport
s.
component
of type RTCIceComponent
, readonly, nullable
rtp
" or "rtcp
").
This corresponds to the component-id
field in candidate-attribute
, decoded to the string
representation as defined in RTCIceComponent
.
priority
of type unsigned long, readonly, nullable
address
of type DOMString, readonly, nullable
The address of the candidate, allowing for IPv4 addresses,
IPv6 addresses, and fully qualified domain names (FQDNs).
This corresponds to the connection-address
field in candidate-attribute
.
Remote candidates may be exposed, for instance via
[[SelectedCandidatePair]]
.remote
.
By default, the user agent MUST leave the
address
attribute as null
for any exposed remote candidate. Once a
RTCPeerConnection
instance learns on an address by the
web application using
addIceCandidate
, the user agent can
expose the address
attribute value in any
RTCIceCandidate
of the RTCPeerConnection
instance
representing a remote candidate with that newly learnt
address.
The addresses exposed in candidates gathered via ICE and
made visibile to the application in RTCIceCandidate
instances can reveal more information about the device
and the user (e.g. location, local network topology) than
the user might have expected in a non-WebRTC enabled
browser.
These addresses are always exposed to the application, and potentially exposed to the communicating party, and can be exposed without any specific user consent (e.g. for peer connections used with data channels, or to receive media only).
These addresses can also be used as temporary or
persistent cross-origin states, and thus contribute to
the fingerprinting surface of the device.
Applications can avoid exposing addresses to the
communicating party, either temporarily or permanently,
by forcing the ICE Agent to report only relay
candidates via the
iceTransportPolicy
member of
RTCConfiguration
.
To limit the addresses exposed to the application itself, browsers can offer their users different policies regarding sharing local addresses, as defined in [RFC8828].
protocol
of type RTCIceProtocol
, readonly, nullable
udp
"/"tcp
"). This
corresponds to the transport
field
in candidate-attribute
.
port
of type unsigned short, readonly, nullable
type
of type RTCIceCandidateType
, readonly,
nullable
candidate-types
field in candidate-attribute
.
tcpType
of type RTCIceTcpCandidateType
, readonly,
nullable
protocol
is "tcp
", tcpType
represents the type of TCP candidate. Otherwise, tcpType
is null
. This corresponds to the tcp-type
field in candidate-attribute
.
relatedAddress
of type DOMString, readonly, nullable
relatedAddress
is the IP
address of the candidate that it is derived from. For host
candidates, the relatedAddress
is null
. This
corresponds to the rel-address
field
in candidate-attribute
.
relatedPort
of type unsigned short, readonly, nullable
relatedPort
is the port of
the candidate that it is derived from. For host candidates,
the relatedPort
is null
. This corresponds to
the rel-port
field in candidate-attribute
.
usernameFragment
of type DOMString, readonly, nullable
ufrag
as defined in
section 15.4 of [RFC5245].
relayProtocol
of type RTCIceServerTransportProtocol
The protocol used by the endpoint to communicate with the TURN server. This is only present for local relay candidates.
url
of type DOMString
For local candidates of type "srflx
" or type
"relay
" this is the URL of the ICE server
from which the candidate was obtained.
toJSON()
toJSON
()
operation of the
RTCIceCandidate
interface, run the following steps:
RTCIceCandidateInit
dictionary.
candidate
, sdpMid
,
sdpMLineIndex
, usernameFragment
»:
RTCIceCandidate
object.
json[attr]
to value.
WebIDLdictionary RTCIceCandidateInit
{
DOMString candidate
= "";
DOMString? sdpMid
= null;
unsigned short? sdpMLineIndex
= null;
DOMString? usernameFragment
= null;
};
candidate
of type DOMString, defaulting to
""
candidate-attribute
as defined in
section 15.1 of [RFC5245]. If this represents an
end-of-candidates indication, candidate
is an empty
string.
sdpMid
of type DOMString, nullable, defaulting to
null
null
, this contains the media stream "identification-tag" defined in [RFC5888] for the media
component this candidate is associated with.
sdpMLineIndex
of type unsigned short, nullable, defaulting
to null
null
, this indicates the index (starting
at zero) of the media description in the SDP this
candidate is associated with.
usernameFragment
of type DOMString, nullable, defaulting to
null
null
, this carries the ufrag
as defined in section 15.4 of [RFC5245].
The candidate-attribute
grammar is used to parse the
candidate
member of
candidateInitDict in the RTCIceCandidate
()
constructor.
The primary grammar for candidate-attribute
is defined in
section 15.1 of [RFC5245]. In addition, the browser MUST support
the grammar extension for ICE TCP as defined in section 4.5 of
[RFC6544].
The browser MAY support other grammar extensions for candidate-attribute
as defined in other RFCs.
The RTCIceProtocol
represents the protocol of the ICE
candidate.
WebIDLenum RTCIceProtocol
{
"udp
",
"tcp
"
};
Enum value | Description |
---|---|
udp
|
A UDP candidate, as described in [RFC5245]. |
tcp
|
A TCP candidate, as described in [RFC6544]. |
The RTCIceTcpCandidateType
represents the type of the ICE TCP
candidate, as defined in [RFC6544].
WebIDLenum RTCIceTcpCandidateType
{
"active
",
"passive
",
"so
"
};
Enum value | Description |
---|---|
active
|
An "active " TCP candidate is
one for which the transport will attempt to open an
outbound connection but will not receive incoming
connection requests.
|
passive
|
A "passive " TCP candidate is
one for which the transport will receive incoming
connection attempts but not attempt a connection.
|
so
|
An "so " candidate is one for
which the transport will attempt to open a connection
simultaneously with its peer.
|
The user agent will typically only gather
active
ICE TCP candidates.
The RTCIceCandidateType
represents the type of the ICE
candidate, as defined in [RFC5245] section 15.1.
WebIDLenum RTCIceCandidateType
{
"host
",
"srflx
",
"prflx
",
"relay
"
};
Enum value | Description |
---|---|
host
|
A host candidate, as defined in Section 4.1.1.1 of [RFC5245]. |
srflx
|
A server reflexive candidate, as defined in Section 4.1.1.2 of [RFC5245]. |
prflx
|
A peer reflexive candidate, as defined in Section 4.1.1.2 of [RFC5245]. |
relay
|
A relay candidate, as defined in Section 7.1.3.2.1 of [RFC5245]. |
The RTCIceServerTransportProtocol
represents the type of the transport
protocol used between the client and the server, as defined in [RFC8656] section 3.1.
WebIDLenum RTCIceServerTransportProtocol
{
"udp
",
"tcp
",
"tls
",
};
Enum value | Description |
---|---|
udp
|
The TURN client is using UDP as transport to the server. |
tcp
|
The TURN client is using TCP as transport to the server. |
tls
|
The TURN client is using TLS as transport to the server. |
The icecandidate
event of the
RTCPeerConnection
uses the RTCPeerConnectionIceEvent
interface.
When firing an RTCPeerConnectionIceEvent
event that contains an
RTCIceCandidate
object, it MUST include values for both
sdpMid
and sdpMLineIndex
.
If the RTCIceCandidate
is of type
"srflx
" or type
"relay
", the
url
property of the event MUST be set
to the URL of the ICE server from which the candidate was obtained.
icecandidate
event is used for three different types of
indications:
A candidate has been gathered. The
candidate
member of the event
will be populated normally. It should be signaled to the
remote peer and passed into
addIceCandidate
.
An RTCIceTransport
has finished gathering a generation of candidates, and is providing an end-of-candidates
indication as defined by Section 8.2 of [RFC8838]. This
is indicated by
candidate
.candidate
being set to an empty string. The
candidate
object should be
signaled to the remote peer and passed into
addIceCandidate
like a typical ICE
candidate, in order to provide the end-of-candidates
indication to the remote peer.
All RTCIceTransport
s have finished gathering candidates,
and the RTCPeerConnection
's RTCIceGatheringState
has
transitioned to "complete
". This is
indicated by the candidate
member of the event being set to null
. This only
exists for backwards compatibility, and this event does not
need to be signaled to the remote peer. It's equivalent to an
icegatheringstatechange
event with the
"complete
" state.
WebIDL[Exposed=Window]
interface RTCPeerConnectionIceEvent
: Event {
constructor
(DOMString type, optional RTCPeerConnectionIceEventInit
eventInitDict = {});
readonly attribute RTCIceCandidate
? candidate
;
readonly attribute DOMString? url
;
};
RTCPeerConnectionIceEvent.constructor()
candidate
of type RTCIceCandidate
, readonly, nullable
The candidate
attribute is the RTCIceCandidate
object with the new ICE candidate that caused the event.
This attribute is set to null
when an event is
generated to indicate the end of candidate gathering.
Even where there are multiple media components, only one
event containing a null
candidate is fired.
url
of type DOMString, readonly, nullable
The url
attribute is the STUN or TURN URL that
identifies the STUN or TURN server used to gather this
candidate. If the candidate was not gathered from a STUN or
TURN server, this parameter will be set to
null
.
This attribute is deprecated; it exists for legacy compatibility reasons only.
Prefer the candidate url
.
WebIDLdictionary RTCPeerConnectionIceEventInit
: EventInit {
RTCIceCandidate
? candidate
;
DOMString? url
;
};
candidate
of type RTCIceCandidate
, nullable
See the candidate
attribute
of the RTCPeerConnectionIceEvent
interface.
url
of type DOMString, nullable
url
attribute is the STUN or TURN URL that identifies
the STUN or TURN server used to gather this candidate.
The icecandidateerror
event of the
RTCPeerConnection
uses the RTCPeerConnectionIceErrorEvent
interface.
WebIDL[Exposed=Window]
interface RTCPeerConnectionIceErrorEvent
: Event {
constructor
(DOMString type, RTCPeerConnectionIceErrorEventInit
eventInitDict);
readonly attribute DOMString? address
;
readonly attribute unsigned short? port
;
readonly attribute DOMString url
;
readonly attribute unsigned short errorCode
;
readonly attribute USVString errorText
;
};
RTCPeerConnectionIceErrorEvent.constructor()
address
of type DOMString, readonly, nullable
The address
attribute is the local IP address used to
communicate with the STUN or TURN server.
On a multihomed system, multiple interfaces may be used to contact the server, and this attribute allows the application to figure out on which one the failure occurred.
If the local IP address value is not already exposed as
part of a local candidate, the address
attribute will
be set to null
.
port
of type unsigned short, readonly, nullable
The port
attribute is the port used to communicate with
the STUN or TURN server.
If the address
attribute is null
, the
port
attribute is also set to null
.
url
of type DOMString, readonly
The url
attribute is the STUN or TURN URL that
identifies the STUN or TURN server for which the failure
occurred.
errorCode
of type unsigned short, readonly
The errorCode
attribute is the numeric STUN error code
returned by the STUN or TURN server [STUN-PARAMETERS].
If no host candidate can reach the server, errorCode
will be set to the value 701 which is outside the STUN
error code range. This error is only fired once per server
URL while in the RTCIceGatheringState
of
"gathering
".
errorText
of type USVString, readonly
The errorText
attribute is the STUN reason text
returned by the STUN or TURN server [STUN-PARAMETERS].
If the server could not be reached, errorText
will be
set to an implementation-specific value providing details
about the error.
WebIDLdictionary RTCPeerConnectionIceErrorEventInit
: EventInit {
DOMString? address
;
unsigned short? port
;
DOMString url
;
required unsigned short errorCode
;
USVString errorText
;
};
address
of type DOMString, nullable
The local address used to communicate with the STUN or TURN
server, or null
.
port
of type unsigned short, nullable
The local port used to communicate with the STUN or TURN
server, or null
.
url
of type DOMString
The STUN or TURN URL that identifies the STUN or TURN server for which the failure occurred.
errorCode
of type unsigned short, required
The numeric STUN error code returned by the STUN or TURN server.
errorText
of type USVString
The STUN reason text returned by the STUN or TURN server.
The certificates that RTCPeerConnection
instances use to
authenticate with peers use the RTCCertificate
interface. These
objects can be explicitly generated by applications using the
generateCertificate
method and can be provided
in the RTCConfiguration
when constructing a new
RTCPeerConnection
instance.
The explicit certificate management functions provided here are
optional. If an application does not provide the
certificates
configuration option when
constructing an RTCPeerConnection
a new set of certificates MUST
be generated by the user agent. That set MUST include an ECDSA
certificate with a private key on the P-256 curve and a signature
with a SHA-256 hash.
WebIDLpartial interface RTCPeerConnection
{
static Promise<RTCCertificate
>
generateCertificate
(AlgorithmIdentifier keygenAlgorithm);
};
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:
Let keygenAlgorithm be the first argument to
generateCertificate
.
Let expires be a value of 2592000000 (30*24*60*60*1000)
This means the certificate will by default expire in 30
days from the time of the generateCertificate
call.
If keygenAlgorithm is an object, run the following steps:
Let certificateExpiration be the result of
converting
the ECMAScript object represented by
keygenAlgorithm to an
RTCCertificateExpiration
dictionary.
If the conversion fails with an error, return a promise that is rejected with error.
If
certificateExpiration.expires
is not undefined
, set expires
to
certificateExpiration.expires
.
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.
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
.
If the above normalization step fails with an error, return a promise that is rejected with error.
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.
Let p be a new promise.
Run the following steps in parallel:
Perform the generate key operation specified by normalizedKeygenAlgorithm using keygenAlgorithm.
Let generatedKeyingMaterial and generatedKeyCertificate be the private keying material and certificate generated by the above step.
Let certificate be a new
RTCCertificate
object.
Set certificate.[[Expires]] to the current time plus expires value.
Set certificate.[[Origin]]
to the
relevant settings object's
origin.
Store the generatedKeyingMaterial in a secure module, and let handle be a reference identifier to it.
Set certificate.[[KeyingMaterialHandle]]
to handle.
Set certificate.[[Certificate]]
to
generatedCertificate.
Resolve p with certificate.
Return p.
RTCCertificateExpiration
Dictionary
is used to set an expiration date on
certificates generated by
RTCCertificateExpiration
.
generateCertificate
WebIDLdictionaryRTCCertificateExpiration
{ [EnforceRange] DOMTimeStampexpires
; };
expires
, of type DOMTimeStamp
An optional
attribute MAY be added to the
definition of the algorithm that is passed to
expires
. If this parameter is
present it indicates the maximum time that the
generateCertificate
is valid for relative to the current time.
RTCCertificate
RTCCertificateExpiration
is used to set an expiration date on
certificates generated by
generateCertificate
.
WebIDLdictionary RTCCertificateExpiration
{
[EnforceRange] unsigned long long expires
;
};
expires
, of type unsigned long long
An optional expires
attribute MAY be added to the
definition of the algorithm that is passed to
generateCertificate
. If this parameter is
present it indicates the maximum time in milliseconds that the
RTCCertificate
is valid for, measured from the time the
certificate is created.
RTCCertificate
Interface
The
interface represents a certificate used to
authenticate WebRTC communications. In addition to the visible
properties, internal slots contain a handle to the generated
private keying materal ([[KeyingMaterialHandle]]), a
certificate ([[Certificate]]) that
RTCCertificate
uses to authenticate with a peer, and the
origin ([[Origin]]) that created the object.
RTCPeerConnection
WebIDL[Exposed=Window, Serializable] interfaceRTCCertificate
{ readonly attribute DOMTimeStampexpires
; sequence<RTCDtlsFingerprint
>getFingerprints
(); };
expires
of type DOMTimeStamp, readonly
The expires attribute indicates the date and
time in milliseconds relative to 1970-01-01T00:00:00Z after
which the certificate will be considered invalid by the
browser. After this time, attempts to construct an
using this certificate fail.
RTCPeerConnection
Note that this value might not be reflected in a
notAfter
parameter in the
certificate itself.
getFingerprints
Returns the list of certificate fingerprints, one of which is computed with the digest algorithm used in the certificate signature.
For the purposes of this API, the [[Certificate]] slot
contains unstructured binary data. No mechanism is provided for
applications to access the [[KeyingMaterialHandle]]
internal slot or the keying material it references. Implementations
MUST support applications storing and retrieving
objects from persistent storage, in a manner that also preserves
the keying material referenced by [[KeyingMaterialHandle]].
Implementations SHOULD store the sensitive keying material in a
secure module safe from same-process memory attacks. This allows
the private key to be stored and used, but not easily read using a
memory attack.
RTCCertificate
objects are serializable objects
[HTML]. Their serialization steps, given value
and serialized, are:
RTCCertificate
expires
attribute.
Their deserialization steps, given serialized and value, are:
expires
attribute to contain serialized.[[Expires]].
Supporting structured cloning in this manner allows
instances to be persisted to stores. It also
allows instances to be passed to other origins using APIs like
RTCCertificate
postMessage
(message, options)
[html]. However, the object cannot
be used by any other origin than the one that originally created
it.
The RTCCertificate
interface represents a certificate used to
authenticate WebRTC communications. In addition to the visible
properties, internal slots contain a handle to the generated
private keying materal ([[KeyingMaterialHandle]]), a
certificate ([[Certificate]]) that
RTCPeerConnection
uses to authenticate with a peer, and the
origin ([[Origin]]) that created the object.
WebIDL[Exposed=Window, Serializable]
interface RTCCertificate
{
readonly attribute EpochTimeStamp expires
;
sequence<RTCDtlsFingerprint
> getFingerprints
();
};
expires
of type EpochTimeStamp
, readonly
The expires attribute indicates the date and
time in milliseconds relative to 1970-01-01T00:00:00Z after
which the certificate will be considered invalid by the
browser. After this time, attempts to construct an
RTCPeerConnection
using this certificate fail.
Note that this value might not be reflected in a
notAfter
parameter in the
certificate itself.
getFingerprints
Returns the list of certificate fingerprints, one of which is computed with the digest algorithm used in the certificate signature.
For the purposes of this API, the [[Certificate]]
slot
contains unstructured binary data. No mechanism is provided for
applications to access the [[KeyingMaterialHandle]]
internal slot or the keying material it references. Implementations
MUST support applications storing and retrieving RTCCertificate
objects from persistent storage, in a manner that also preserves
the keying material referenced by [[KeyingMaterialHandle]]
.
Implementations SHOULD store the sensitive keying material in a
secure module safe from same-process memory attacks. This allows
the private key to be stored and used, but not easily read using a
memory attack.
RTCCertificate
objects are serializable objects
[HTML]. Their serialization steps, given value
and serialized, are:
expires
attribute.
[[Certificate]]
.
[[Origin]]
.
[[KeyingMaterialHandle]]
(not the private
keying material itself).
Their deserialization steps, given serialized and value, are:
expires
attribute to contain serialized.[[Expires]].
[[Certificate]]
to a copy of
serialized.[[Certificate]]
[[Origin]]
to a copy of
serialized.[[Origin]]
[[KeyingMaterialHandle]]
to the
private keying material handle resulting from deserializing
serialized.[[KeyingMaterialHandle]]
Supporting structured cloning in this manner allows
RTCCertificate
instances to be persisted to stores. It also
allows instances to be passed to other origins using APIs like
postMessage
(message, options)
[html]. However, the object cannot
be used by any other origin than the one that originally created
it.
The RTP media API lets a web application send and receive
MediaStreamTrack
s over a peer-to-peer connection. Tracks, when
added to an RTCPeerConnection
, result in signaling; when this
signaling is forwarded to a remote peer, it causes corresponding tracks
to be created on the remote side.
There is not an exact 1:1 correspondence between tracks sent by one
RTCPeerConnection
and received by the other. For one, IDs of tracks
sent have no mapping to the IDs of tracks received. Also,
replaceTrack
changes the track sent by an
RTCRtpSender
without creating a new track on the receiver side; the
corresponding RTCRtpReceiver
will only have a single track,
potentially representing multiple sources of media stitched together.
Both addTransceiver
and
replaceTrack
can be used to cause the same track to be
sent multiple times, which will be observed on the receiver side as
multiple receivers each with its own separate track. Thus it's more
accurate to think of a 1:1 relationship between an RTCRtpSender
on
one side and an RTCRtpReceiver
's track on the other side, matching
senders and receivers using the RTCRtpTransceiver
's
mid
if necessary.
When sending media, the sender may need to rescale or resample the media to meet various requirements, including the envelope negotiated by SDP, alignment restrictions of the encoder, or even CPU overuse detection or bandwidth estimation.
Following the rules in [RFC8829] (section 3.6.), the video MAY be downscaled. The media MUST NOT be upscaled to create fake data that did not occur in the input source, the media MUST NOT be cropped except as needed to satisfy constraints on pixel counts, and the aspect ratio MUST NOT be changed.
The WebRTC Working Group is seeking implementation feedback on the need and timeline for a more complex handling of this situation. Some possible designs have been discussed in GitHub issue 1283.
When video is rescaled, for example for certain combinations of width
or height and
values, situations when the resulting width or height is not an integer
may occur. In such situations the user agent MUST use the integer part of the
result. What to transmit if the integer part of the scaled width or
height is zero is implementation-specific.
scaleResolutionDownBy
Whenever video is rescaled as a result of
scaleResolutionDownBy
,
situations when the resulting width or height is not an integer
may occur. The user agent MUST NOT transmit video larger than
the integer part
of the scaled width and height from
scaleResolutionDownBy
, except to respect an
encoder's minimum resolution. What to transmit if the integer part of
the scaled width or height is zero is implementation-defined.
The actual encoding and transmission of MediaStreamTrack
s is
managed through objects called RTCRtpSender
s. Similarly, the
reception and decoding of MediaStreamTrack
s is managed through
objects called RTCRtpReceiver
s. Each RTCRtpSender
is associated
with at most one track, and each track to be received is associated
with exactly one RTCRtpReceiver
.
The encoding and transmission of each MediaStreamTrack
SHOULD be
made such that its characteristics (width
,
height
and frameRate
for video tracks; sampleSize
, sampleRate
and
channelCount
for audio tracks) are to a
reasonable degree retained by the track created on the remote side.
There are situations when this does not apply, there may for example be
resource constraints at either endpoint or in the network or there may
be RTCRtpSender
settings applied that instruct the implementation
to act differently.
An RTCPeerConnection
object contains a set of RTCRtpTransceiver
s,
representing the paired senders and receivers with some shared state.
This set is
initialized to the empty set when the RTCPeerConnection
object is
created. RTCRtpSender
s and RTCRtpReceiver
s are always
created at the same time as an RTCRtpTransceiver
, which they will
remain attached to for their lifetime. RTCRtpTransceiver
s are
created implicitly when the application attaches a MediaStreamTrack
to an RTCPeerConnection
via the addTrack
()
method, or explicitly when the application uses the
addTransceiver
method. They are also created when
a remote description is applied that includes a new media description.
Additionally, when a remote description is applied that indicates the
remote endpoint has media to send, the relevant MediaStreamTrack
and RTCRtpReceiver
are surfaced to the application via the
track
event.
In order for an RTCRtpTransceiver
to send and/or receive media with
another endpoint this must be negotiated with SDP such that both
endpoints have an RTCRtpTransceiver
object that is associated
with the same media description.
When creating an offer, enough media descriptions will be generated to cover all transceivers on that end. When this offer is set as the local description, any disassociated transceivers get associated with media descriptions in the offer.
When an offer is set as the remote description, any media descriptions
in it not yet associated with a transceiver get associated with a new
or existing transceiver. In this case, only disassociated transceivers
that were created via the addTrack
()
method may
be associated. Disassociated transceivers created via the
addTransceiver
()
method, however, won't get
associated even if media descriptions are available in the remote
offer. Instead, new transceivers will be created and associated if
there aren't enough addTrack
()
-created
transceivers. This sets addTrack
()
-created and
addTransceiver
()
-created transceivers apart in a
critical way that is not observable from inspecting their attributes.
When creating an answer, only media descriptions that were
present in the offer may be listed in the answer. As a consequence, any
transceivers that were not associated when setting the remote offer
remain disassociated after setting the local answer. This can be
remedied by the answerer creating a follow-up offer, initiating another
offer/answer exchange, or in the case of using
addTrack
()
-created transceivers, making sure that
enough media descriptions are offered in the initial exchange.
The RTP media API extends the RTCPeerConnection
interface as
described below.
WebIDL partial interface RTCPeerConnection
{
sequence<RTCRtpSender
> getSenders
();
sequence<RTCRtpReceiver
> getReceivers
();
sequence<RTCRtpTransceiver
> getTransceivers
();
RTCRtpSender
addTrack
(MediaStreamTrack track, MediaStream... streams);
undefined removeTrack
(RTCRtpSender
sender);
RTCRtpTransceiver
addTransceiver
((MediaStreamTrack or DOMString) trackOrKind,
optional RTCRtpTransceiverInit
init = {});
attribute EventHandler ontrack
;
};
ontrack
of type EventHandler
The event type of this event handler is track
.
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:
CollectTransceivers
algorithm.
[[Stopped]]
is
false
, add
transceiver.[[Sender]]
to
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:
CollectTransceivers
algorithm.
[[Stopped]]
is
false
, add
transceiver.[[Receiver]]
to
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:
RTCRtpTransceiver
objects in this RTCPeerConnection
object's set of transceivers, in insertion order.
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:
Let connection be the RTCPeerConnection
object on which this method was invoked.
Let track be the MediaStreamTrack
object
indicated by the method's first argument.
Let kind be track.kind.
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.
If connection.[[IsClosed]]
is
true
, throw an
InvalidStateError
.
Let senders be the result of executing the
CollectSenders
algorithm. If an RTCRtpSender
for
track already exists in senders, throw an InvalidAccessError
.
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 sender's
streams, as defined in [RFC8829] (section 5.2.2. and section 5.3.2.).
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 [[Stopping]]
slot of the
RTCRtpTransceiver
associated with the sender is
false
.
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
".
If sender is not null
, run the
following steps to use that sender:
Set sender.[[SenderTrack]]
to
track.
Set
sender.[[AssociatedMediaStreamIds]]
to an empty set.
For each stream in streams, add
stream.id to
[[AssociatedMediaStreamIds]]
if it's not
already there.
Let transceiver be the
RTCRtpTransceiver
associated with
sender.
If transceiver.[[Direction]]
is
"recvonly
", set
transceiver.[[Direction]]
to
"sendrecv
".
If transceiver.[[Direction]]
is
"inactive
", set
transceiver.[[Direction]]
to
"sendonly
".
If sender is null
, run the
following steps:
Create an RTCRtpSender with track, kind and streams, and let sender be the result.
Create an RTCRtpReceiver with kind, and let receiver be the result.
Create an RTCRtpTransceiver with
sender, receiver and an
RTCRtpTransceiverDirection
value of
"sendrecv
", and let
transceiver be the result.
Add transceiver to connection's set of transceivers.
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
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.
Update the negotiation-needed flag for connection.
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
[RFC8829] (section 5.2.2.).
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 track
event, and if the MediaStreamTrack
is not already muted,
a mute
event is fired at the
track.
removeTrack
()
can be achieved by
setting the
RTCRtpTransceiver
.direction
attribute of the corresponding transceiver and invoking
RTCRtpSender
.replaceTrack
(null) on the
sender. One minor difference is that
replaceTrack
()
is asynchronous and
removeTrack
()
is synchronous.
When the removeTrack
method is invoked, the user agent
MUST run the following steps:
Let sender be the argument to removeTrack
.
Let connection be the RTCPeerConnection
object on which the method was invoked.
If connection.[[IsClosed]]
is
true
, throw an
InvalidStateError
.
If sender was not created by
connection, throw an
InvalidAccessError
.
Let senders be the result of executing the
CollectSenders
algorithm.
If sender is not in senders (which
indicates its transceiver was stopped or removed due to
setting a session description of
type
"rollback
"), then abort these steps.
If sender.[[SenderTrack]]
is null,
abort these steps.
Set sender.[[SenderTrack]]
to null.
Let transceiver be the RTCRtpTransceiver
object corresponding to sender.
If transceiver.[[Direction]]
is
"sendrecv
", set
transceiver.[[Direction]]
to
"recvonly
".
If transceiver.[[Direction]]
is
"sendonly
", set
transceiver.[[Direction]]
to
"inactive
".
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] (section 5.2.2.).
The initial value of mid
is null.
Setting a session description may later change it to a
non-null value.
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:
Let init be the second argument.
Let streams be
init.
.
streams
Let sendEncodings be
init.
.
sendEncodings
Let direction be
init.
.
direction
If the first argument is a string, let it be kind and run the following steps:
If kind is not a legal
MediaStreamTrack
kind
,
throw a TypeError
.
Let track be null
.
If the first argument is a MediaStreamTrack
, let it
be track and let kind be
track.kind.
If connection.[[IsClosed]] is
true
, throw an
InvalidStateError
.
Verify that each
value
in sendEncodings conforms to the grammar
specified in Section 10 of [RFC8851]. If one of
the RIDs does not meet these requirements, throw a rid
TypeError
.
If any
dictionary in
sendEncodings contains a read-only
parameter other than
RTCRtpEncodingParameters
, throw
an rid
InvalidAccessError
.
Verify that the value of each
member in sendEncodings that is defined
is greater than or equal to 1.0. If one of the
scaleResolutionDownBy
values does not meet this requirement, throw a scaleResolutionDownBy
RangeError
.
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.
If sendEncodings contains any encoding
whose
attribute is defined, set any undefined
scaleResolutionDownBy
of
the other encodings to 1.0.
scaleResolutionDownBy
If the number of
stored
in sendEncodings exceeds maxN,
then trim sendEncodings from the tail
until its length is maxN.
RTCRtpEncodingParameters
scaleResolutionDownBy
attribues of sendEncodings are still
undefined, initialize each encoding's
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.
If the number of
now
stored in sendEncodings is RTCRtpEncodingParameters
1
,
then remove any
member
from the lone entry.
rid
RTCRtpEncodingParameters
in
sendEncodings allows the application to
subsequently set encoding parameters using
setParameters
, even when simulcast
isn't used.
Create an RTCRtpSender with track, kind, streams and sendEncodings and let sender be the result.
If sendEncodings is set, then subsequent calls
to
will be configured to send multiple
RTP encodings as defined in [RFC8829] (section 5.2.2. and section 5.2.1.). When
createOffer
is called with
a corresponding remote description that is able to
receive multiple RTP encodings as defined in
[RFC8829] (section 3.7.), the
setRemoteDescription
may send multiple RTP encodings and the
parameters retrieved via the transceiver's
RTCRtpSender
.sender
getParameters
()
will reflect the encodings negotiated.
Create an RTCRtpReceiver with kind and let receiver be the result.
Create an RTCRtpTransceiver with sender, receiver and direction, and let transceiver be the result.
Add transceiver to connection's set of transceivers.
Update the negotiation-needed flag for connection.
Return transceiver.
Let init be the second argument.
Let streams be
init.streams
.
Let sendEncodings be
init.sendEncodings
.
Let direction be
init.direction
.
If the first argument is a string, let kind be the first argument and run the following steps:
If the first argument is a MediaStreamTrack
, let
track be the first argument and let kind be
track.kind
.
If connection.[[IsClosed]]
is
true
, throw an
InvalidStateError
.
RTCRtpEncodingParameters
dictionary in it is an "encoding":
If any encoding contains a
rid
member whose value
does not conform to the grammar requirements specified
in Section 10 of [RFC8851], throw a TypeError
.
If some but not all encodings contain a
rid
member, throw a TypeError
.
If any encoding contains a
rid
member whose value
is the same as that of a rid
contained in another encoding in
sendEncodings, throw a
TypeError
.
If any encoding contains a read-only
parameter other than
rid
, throw
an InvalidAccessError
.
If kind is "audio"
, remove the
scaleResolutionDownBy
and
maxFramerate
members from all encodings that contain any of
them.
If any encoding contains a
scaleResolutionDownBy
member whose value is less than 1.0
, throw a RangeError
.
Verify that the value of each
maxFramerate
member in sendEncodings that is defined
is greater than 0.0. If one of the
maxFramerate
values does not meet this requirement, throw a RangeError
.
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.
If any encoding contains a
scaleResolutionDownBy
member, then for each encoding without one,
add a scaleResolutionDownBy
member with the value 1.0
.
If the number of encodings stored in sendEncodings exceeds maxN, then trim sendEncodings from the tail until its length is maxN.
If kind is "video"
and none of the
encodings contain a
scaleResolutionDownBy
member, then for each encoding, add a
scaleResolutionDownBy
member with the value
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.
If the number of encodings now
stored in sendEncodings is 1
,
then remove any rid
member
from the lone entry.
RTCRtpEncodingParameters
in
sendEncodings allows the application to
subsequently set encoding parameters using
setParameters
, even when simulcast
isn't used.
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] (section 5.2.2. and section 5.2.1.). When
setRemoteDescription
is called with
a corresponding remote description that is able to
receive multiple RTP encodings as defined in
[RFC8829] (section 3.7.), the
RTCRtpSender
may send multiple RTP encodings and the
parameters retrieved via the transceiver's
sender
.getParameters
()
will reflect the encodings negotiated.
Create an RTCRtpReceiver with kind and let receiver be the result.
Create an RTCRtpTransceiver with sender, receiver and direction, and let transceiver be the result.
Add transceiver to connection's set of transceivers.
Update the negotiation-needed flag for connection.
Return transceiver.
WebIDLdictionary RTCRtpTransceiverInit
{
RTCRtpTransceiverDirection
direction
= "sendrecv";
sequence<MediaStream> streams
= [];
sequence<RTCRtpEncodingParameters
> sendEncodings
= [];
};
direction
of type RTCRtpTransceiverDirection
,
defaulting to "sendrecv
"
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.
WebIDLenum RTCRtpTransceiverDirection
{
"sendrecv
",
"sendonly
",
"recvonly
",
"inactive
",
"stopped
"
};
Enum value | Description |
---|---|
sendrecv
|
The RTCRtpTransceiver 's RTCRtpSender
sender will offer to send RTP, and will send RTP
if the remote peer accepts and
sender.getParameters () .encodings [i].active
is true for any value of i. The
RTCRtpTransceiver 's RTCRtpReceiver will offer to
receive RTP, and will receive RTP if the remote peer accepts.
|
sendonly
|
The RTCRtpTransceiver 's RTCRtpSender
sender will offer to send RTP, and will send RTP
if the remote peer accepts and
sender.getParameters () .encodings [i].active
is true for any value of i. The
RTCRtpTransceiver 's RTCRtpReceiver will not offer to
receive RTP, and will not receive RTP.
|
recvonly
|
The RTCRtpTransceiver 's RTCRtpSender will not offer
to send RTP, and will not send RTP. The
RTCRtpTransceiver 's RTCRtpReceiver will offer to
receive RTP, and will receive RTP if the remote peer accepts.
|
inactive
|
The RTCRtpTransceiver 's RTCRtpSender will not offer
to send RTP, and will not send RTP. The
RTCRtpTransceiver 's RTCRtpReceiver will not offer to
receive RTP, and will not receive RTP.
|
stopped
|
The RTCRtpTransceiver will neither send nor receive RTP.
It will generate a zero port in the offer. In answers, its
RTCRtpSender will not offer to send RTP, and its
RTCRtpReceiver will not offer to receive RTP. This is a
terminal state.
|
An application can reject incoming media descriptions by setting
the transceiver's direction to either
"inactive
" to turn off both
directions temporarily, or to
"sendonly
" to reject only the
incoming side. To permanently reject an m-line in a manner that
makes it available for reuse, the application would need to call
RTCRtpTransceiver
.stop
()
and subsequently
initiate negotiation from its end.
To process remote tracks
given an RTCRtpTransceiver
transceiver,
direction, msids, addList,
removeList, and trackEventInits, run the
following steps:
Set the associated remote streams with
transceiver.[[Receiver]]
, msids,
addList, and removeList.
If direction is
"sendrecv
" or
"recvonly
" and
transceiver.[[FiredDirection]]
is neither
"sendrecv
" nor
"recvonly
", or the previous step
increased the length of addList, process the
addition of a remote track with transceiver and
trackEventInits.
If direction is
"sendonly
" or
"inactive
", set
transceiver.[[Receptive]]
to
false
.
If direction is
"sendonly
" or
"inactive
", and
transceiver.[[FiredDirection]]
is either
"sendrecv
" or
"recvonly
", process the
removal of a remote track for the media description,
with transceiver and muteTracks.
Set transceiver.[[FiredDirection]]
to
direction.
To process the addition of
a remote track given an RTCRtpTransceiver
transceiver and trackEventInits, run the
following steps:
Let receiver be
transceiver.[[Receiver]]
.
Let track be
receiver.[[ReceiverTrack]]
.
Let streams be
receiver.[[AssociatedRemoteMediaStreams]]
.
Create a new RTCTrackEventInit
dictionary with
receiver, track, streams and
transceiver as members and add it to
trackEventInits.
To process the removal of a
remote track with an RTCRtpTransceiver
transceiver and muteTracks, run the following
steps:
Let receiver be
transceiver.[[Receiver]]
.
Let track be
receiver.[[ReceiverTrack]]
.
If track.muted is false
, add
track to muteTracks.
To set the associated
remote streams given RTCRtpReceiver
receiver,
msids, addList, and removeList,
run the following steps:
Let connection be the RTCPeerConnection
object
associated with receiver.
For each MSID in msids, unless a MediaStream
object has previously been created with that id
for this connection, create a
MediaStream
object with that id
.
Let streams be a list of the MediaStream
objects
created for this connection with the id
s corresponding to msids.
Let track be
receiver.[[ReceiverTrack]]
.
For each stream in
receiver.[[AssociatedRemoteMediaStreams]]
that is not present in streams, add
stream and track as a pair to
removeList.
For each stream in streams that is not
present in
receiver.[[AssociatedRemoteMediaStreams]]
,
add stream and track as a pair to
addList.
Set
receiver.[[AssociatedRemoteMediaStreams]]
to
streams.
The RTCRtpSender
interface allows an application to control how a
given MediaStreamTrack
is encoded and transmitted to a remote
peer. When setParameters
is called on an
RTCRtpSender
object, the encoding is changed appropriately.
To create an RTCRtpSender with a MediaStreamTrack
,
track, a string, kind, a list of
MediaStream
objects, streams, and optionally a list of
RTCRtpEncodingParameters
objects, sendEncodings, run
the following steps:
Let sender be a new
object.
RTCRtpSender
Let sender have a [[SenderTrack]] internal slot initialized to track.
Let sender have a [[SenderTransport]]
internal slot initialized to null
.
Let sender have a
[[LastStableStateSenderTransport]] internal slot
initialized to null
.
Let sender have a [[Dtmf]] internal slot
initialized to null
.
If kind is "audio"
then create an
RTCDTMFSender dtmf and set the [[Dtmf]]
internal slot to dtmf.
Let sender have an
[[AssociatedMediaStreamIds]] internal slot,
representing a list of Ids of MediaStream
objects that this
sender is to be associated with. The
[[AssociatedMediaStreamIds]] slot is used when
sender is represented in SDP as described in
[RFC8829] (section 5.2.1.).
Set sender.[[AssociatedMediaStreamIds]] to an empty set.
For each stream in streams, add stream.id to [[AssociatedMediaStreamIds]] if it's not already there.
Let sender have a [[SendEncodings]]
internal slot, representing a list of
dictionaries.
RTCRtpEncodingParameters
If sendEncodings is given as input to this algorithm,
and is non-empty, set the [[SendEncodings]] slot to
sendEncodings. Otherwise, set it to a list containing
a single
with
RTCRtpEncodingParameters
set to active
true
.
Let sender have a [[SendCodecs]] internal
slot, representing a list of
dictionaries, and initialized to an empty list.
RTCRtpCodecParameters
Let sender have a
[[LastReturnedParameters]] internal slot, which will
be used to match
and
getParameters
transactions.
setParameters
Return sender.
Let sender be a new RTCRtpSender
object.
Let sender have a [[SenderTrack]] internal slot initialized to track.
Let sender have a [[SenderTransport]]
internal slot initialized to null
.
Let sender have a
[[LastStableStateSenderTransport]] internal slot
initialized to null
.
Let sender have a [[Dtmf]] internal slot
initialized to null
.
If kind is "audio"
then create an
RTCDTMFSender dtmf and set the [[Dtmf]]
internal slot to dtmf.
Let sender have an
[[AssociatedMediaStreamIds]] internal slot,
representing a list of Ids of MediaStream
objects that this
sender is to be associated with. The
[[AssociatedMediaStreamIds]]
slot is used when
sender is represented in SDP as described in
[RFC8829] (section 5.2.1.).
Set sender.[[AssociatedMediaStreamIds]]
to an
empty set.
For each stream in streams, add
stream.id to [[AssociatedMediaStreamIds]]
if
it's not already there.
Let sender have a [[SendEncodings]]
internal slot, representing a list of
RTCRtpEncodingParameters
dictionaries.
If sendEncodings is given as input to this algorithm,
and is non-empty, set the [[SendEncodings]]
slot to
sendEncodings. Otherwise, set it to a list containing
a single new RTCRtpEncodingParameters
dictionary, and if
kind is "video"
, add a
scaleResolutionDownBy
member with the
value 1.0
to that dictionary.
RTCRtpEncodingParameters
dictionaries contain
active
members whose values are
true
by default.
Let sender have a
[[LastStableRidlessSendEncodings]] internal slot
initialized to null
.
Let sender have a [[SendCodecs]] internal
slot, representing a list of RTCRtpCodecParameters
dictionaries, and initialized to an empty list.
Let sender have a
[[LastReturnedParameters]] internal slot, which will
be used to match getParameters
and
setParameters
transactions.
Return sender.
WebIDL[Exposed=Window]
interface RTCRtpSender
{
readonly attribute MediaStreamTrack? track
;
readonly attribute RTCDtlsTransport
? transport
;
static RTCRtpCapabilities
? getCapabilities
(DOMString kind);
Promise<undefined> setParameters
(RTCRtpSendParameters
parameters);
RTCRtpSendParameters
getParameters
();
Promise<undefined> replaceTrack
(MediaStreamTrack? withTrack);
undefined setStreams
(MediaStream... streams);
Promise<RTCStatsReport
> getStats
();
};
track
of type MediaStreamTrack
, readonly, nullable
The track
attribute is the track that is associated with
this RTCRtpSender
object. If track
is ended, or if
the track's output is disabled, i.e. the track is disabled
and/or muted, the RTCRtpSender
MUST send black frames
(video) and MUST NOT send (audio). In the case of video, the
RTCRtpSender
SHOULD send one black frame per second. If
track
is null
then the RTCRtpSender
does
not send. On getting, the attribute MUST return the value of
the [[SenderTrack]]
slot.
transport
of type RTCDtlsTransport
, readonly, nullable
The transport
attribute is the transport over which media
from track
is sent in the form of RTP packets. Prior to
construction of the RTCDtlsTransport
object, the
transport
attribute will be null. When bundling is used,
multiple RTCRtpSender
objects will share one
transport
and will all send RTP and RTCP over the same
transport.
On getting, the attribute MUST return the value of the
[[SenderTransport]]
slot.
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
setCodecPreferences
()
algorithm and
what inputs it throws InvalidModificationError
on,
and should also be consistent with information revealed by
createOffer
()
and createAnswer
()
about codecs
negotiated for sending, to ensure any
privacy mitigations are effective.
setParameters
The setParameters
method updates how track
is encoded
and transmitted to a remote peer.
When the setParameters
method is called, the user agent
MUST run the following steps:
RTCRtpSender
object on which setParameters
is
invoked.
RTCRtpTransceiver
object associated with
sender (i.e. sender is
transceiver.[[Sender]]).
true
, return a promise rejected with a
newly created InvalidStateError
.
null
, return a promise rejected with a
newly created InvalidStateError
.
encodings
.
codecs
.
RTCRtpEncodingParameters
stored in
sender.[[SendEncodings]].
InvalidModificationError
:
encodings.length
is
different from N.
Verify that each encoding in encodings has
a
member whose value is greater than or equal to 1.0. If one of the
scaleResolutionDownBy
values does not meet this requirement, return a
promise rejected with a newly created scaleResolutionDownBy
RangeError
.
null
.
encodings
.
undefined
.
RTCError
whose
errorDetail
is set to
"hardware-encoder-not-available
"
and abort these steps.
RTCError
whose
errorDetail
is set to
"hardware-encoder-error
" and
abort these steps.
OperationError
.
RTCRtpSender
object on which setParameters
is
invoked.
RTCRtpTransceiver
object associated with
sender (i.e. sender is
transceiver.[[Sender]]
).
[[Stopped]]
is
true
, return a promise rejected with a
newly created InvalidStateError
.
[[LastReturnedParameters]]
is
null
, return a promise rejected with a
newly created InvalidStateError
.
encodings
.
codecs
.
RTCRtpEncodingParameters
stored in
sender.[[SendEncodings]]
.
InvalidModificationError
:
encodings.length
is
different from N.
[[LastReturnedParameters]]
.
Note that this also applies to
transactionId.
If transceiver kind is "audio"
, remove the
scaleResolutionDownBy
and
maxFramerate
members from all encodings that
contain any of them.
If transceiver kind is "video"
, then for
each encoding in encodings that doesn't
contain a
scaleResolutionDownBy
member, add a
scaleResolutionDownBy
member with the value 1.0
.
If transceiver kind is "video"
,
and any encoding in encodings
contains a
scaleResolutionDownBy
member whose value is less than 1.0
, return a
promise rejected with a newly created RangeError
.
Verify that each encoding in encodings has
a maxFramerate
member whose value is greater than or equal to 0.0. If one of the
maxFramerate
values does not meet this requirement, return a
promise rejected with a newly created RangeError
.
[[SenderTrack]]
.
[[LastReturnedParameters]]
to null
.
[[SendEncodings]]
to
parameters.encodings
.
undefined
.
RTCError
whose
errorDetail
is set to
"hardware-encoder-not-available
"
and abort these steps.
RTCError
whose
errorDetail
is set to
"hardware-encoder-error
" and
abort these steps.
OperationError
.
setParameters
does not cause SDP renegotiation and can
only be used to change what the media stack is sending or
receiving within the envelope negotiated by Offer/Answer. The
attributes in the RTCRtpSendParameters
dictionary are
designed to not enable this, so attributes like
cname
that cannot be changed are
read-only. Other things, like bitrate, are controlled using
limits such as maxBitrate
, where
the user agent needs to ensure it does not exceed the maximum
bitrate specified by maxBitrate
,
while at the same time making sure it satisfies constraints
on bitrate specified in other places such as the SDP.
getParameters
The getParameters
()
method returns the RTCRtpSender
object's current parameters for how track
is encoded and
transmitted to a remote RTCRtpReceiver
.
When getParameters
is called, the user agent MUST run the
following steps:
Let sender be the RTCRtpSender
object on
which the getter was invoked.
If sender.[[LastReturnedParameters]]
is not null
, return
sender.[[LastReturnedParameters]]
, and
abort these steps.
Let result be a new RTCRtpSendParameters
dictionary constructed as follows:
transactionId
is set to a new
unique identifier.
encodings
is set to the value of
the [[SendEncodings]]
internal slot.
headerExtensions
sequence is
populated based on the header extensions that have been
negotiated for sending.
codecs
is set to the value of the
[[SendCodecs]]
internal slot.
rtcp
.cname
is
set to the CNAME of the associated RTCPeerConnection
.
rtcp
.reducedSize
is set to true
if reduced-size RTCP has been
negotiated for sending, and false
otherwise.
Set sender.[[LastReturnedParameters]]
to result.
Queue a task that sets
sender.[[LastReturnedParameters]]
to
null
.
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:
Let sender be the RTCRtpSender
object on
which replaceTrack
is invoked.
Let transceiver be the RTCRtpTransceiver
object associated with sender.
Let connection be the RTCPeerConnection
object associated with sender.
Let withTrack be the argument to this method.
If withTrack is non-null and
withTrack.kind
differs from the
transceiver kind of transceiver, return
a promise rejected with a newly created TypeError
.
Return the result of chaining the following steps to connection's operations chain:
If transceiver.[[Stopped]]
is
true
, return a promise rejected
with a newly created
InvalidStateError
.
Let p be a new promise.
Let sending be true
if
transceiver.[[CurrentDirection]]
is "sendrecv
" or
"sendonly
", and
false
otherwise.
Run the following steps in parallel:
If sending is true
, and
withTrack is null
, have
the sender stop sending.
If sending is true
, and
withTrack is not null
,
determine if withTrack can be sent
immediately by the sender without violating the
sender's already-negotiated envelope, and if it
cannot, then reject p with a
newly created
InvalidModificationError
, and abort these
steps.
If sending is true
, and
withTrack is not null
,
have the sender switch seamlessly to transmitting
withTrack instead of the sender's
existing track.
Queue a task that runs the following steps:
If connection.[[IsClosed]]
is true
, abort these steps.
Set sender.[[SenderTrack]]
to withTrack.
Resolve p with
undefined
.
Return p.
Changing dimensions and/or frame rates might not require negotiation. Cases that may require negotiation include:
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:
Let sender be the RTCRtpSender
object on
which this method was invoked.
Let connection be the RTCPeerConnection
object on which this method was invoked.
If connection.[[IsClosed]]
is
true
, throw an
InvalidStateError
.
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.
Set
sender.[[AssociatedMediaStreamIds]]
to
an empty set.
For each stream in streams, add
stream.id to
[[AssociatedMediaStreamIds]]
if it's not already
there.
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:
Let selector be the RTCRtpSender
object on
which the method was invoked.
Let p be a new promise, and run the following steps in parallel:
Gather the stats indicated by selector according to the stats selection algorithm.
Resolve p with the resulting
RTCStatsReport
object, containing the gathered
stats.
Return p.
WebIDLdictionary RTCRtpParameters
{
required sequence<RTCRtpHeaderExtensionParameters
> headerExtensions
;
required RTCRtcpParameters
rtcp
;
required sequence<RTCRtpCodecParameters
> codecs
;
};
RTCRtpParameters
Members
headerExtensions
of type sequence<RTCRtpHeaderExtensionParameters
>,
required
A sequence containing parameters for RTP header extensions. Read-only parameter.
rtcp
of type RTCRtcpParameters
, required
Parameters used for RTCP. Read-only parameter.
codecs
of type sequence<RTCRtpCodecParameters
>,
required
A sequence containing the media codecs that an
RTCRtpSender
will choose from, as well as entries for
RTX, RED and FEC mechanisms. Corresponding to each media
codec where retransmission via RTX is enabled, there will
be an entry in codecs
with a
mimeType
attribute indicating
retransmission via audio/rtx
or
video/rtx
, and an
sdpFmtpLine
attribute (providing
the "apt" and "rtx-time" parameters). Read-only
parameter.
WebIDLdictionary RTCRtpSendParameters
: RTCRtpParameters
{
required DOMString transactionId
;
required sequence<RTCRtpEncodingParameters
> encodings
;
};
RTCRtpSendParameters
Members
transactionId
of type DOMString, required
A unique identifier for the last set of parameters applied.
Ensures that setParameters
can only be
called based on a previous getParameters
,
and that there are no intervening changes. Read-only parameter.
encodings
of type sequence<RTCRtpEncodingParameters
>,
required
A sequence containing parameters for RTP encodings of media.
WebIDLdictionary RTCRtpReceiveParameters
: RTCRtpParameters
{
};
WebIDLdictionary RTCRtpCodingParameters
{
DOMString rid
;
};
RTCRtpCodingParameters
Members
rid
of type DOMString
If set, this RTP encoding will be sent with the RID header
extension as defined by [RFC8829] (section 5.2.1.). The RID is not
modifiable via setParameters
. It can only
be set or modified in addTransceiver
on the sending side. Read-only parameter.
RTCRtpDecodingParameters
Dictionary
WebIDLdictionaryRTCRtpDecodingParameters
:RTCRtpCodingParameters
{};
WebIDL dictionaryRTCRtpEncodingParameters
:RTCRtpCodingParameters
{ booleanactive
= true; unsigned longmaxBitrate
; doublescaleResolutionDownBy
; };
WebIDLdictionary RTCRtpEncodingParameters
: RTCRtpCodingParameters
{
boolean active
= true;
unsigned long maxBitrate
;
double maxFramerate
;
double scaleResolutionDownBy
;
};
RTCRtpEncodingParameters
Members
active
of type boolean, defaulting to
true
Indicates that this encoding is actively being sent.
Setting it to false
causes this encoding to no
longer be sent. Setting it to true
causes this
encoding to be sent. Since setting the value to
false
does not cause the SSRC to be removed,
an RTCP BYE is not sent.
maxBitrate
of type unsigned long
When present, indicates the maximum bitrate that can be
used to send this encoding. The user agent is free to
allocate bandwidth between the encodings, as long as the
maxBitrate
value is not exceeded. The encoding may also
be further constrained by other limits (such as
per-transport or per-session bandwidth limits) below the
maximum specified here. maxBitrate
is computed the same
way as the Transport Independent Application Specific
Maximum (TIAS) bandwidth defined in [RFC3890] Section
6.2.2, which is the maximum bandwidth needed without
counting IP or other transport layers like TCP or UDP. The
unit of maxBitrate
is bits per second.
How the bitrate is achieved is media and encoding dependent. For video, a frame will always be sent as fast as possible, but frames may be dropped until bitrate is low enough. Thus, even a bitrate of zero will allow sending one frame. For audio, it might be necessary to stop playing if the bitrate does not allow the chosen encoding enough bandwidth to be sent.
maxFramerate
of type double
This member can only be present if the sender's kind
is "video"
.
When present, indicates the maximum frame rate that can be used to
send this encoding, in frames per second. The user agent is free
to allocate bandwidth between the encodings, as long as the
maxFramerate
value is not exceeded.
If changed with setParameters
()
, the new frame rate takes
effect after the current picture is completed; setting the max frame
rate to zero thus has the effect of freezing the video on the next
frame.
scaleResolutionDownBy
of type
double
This member is only present if the sender's kind
is "video"
. The video's
resolution will be scaled down in each dimension by the
given value before sending. For example, if the value is
2.0, the video will be scaled down by a factor of 2 in each
dimension, resulting in sending a video of one quarter the
size. If the value is 1.0, the video will not be affected.
The value must be greater than or equal to 1.0. By default,
scaling is applied by a factor of two to the power of the
layer's number, in order of smaller to higher resolutions,
e.g. 4:2:1. If there is only one layer, the sender will by
default not apply any scaling, (i.e.
scaleResolutionDownBy
will be
1.0).
WebIDLdictionary RTCRtcpParameters
{
DOMString cname
;
boolean reducedSize
;
};
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.
WebIDLdictionary RTCRtpHeaderExtensionParameters
{
required DOMString uri
;
required unsigned short id
;
boolean encrypted
= false;
};
RTCRtpHeaderExtensionParameters
Members
uri
of type DOMString, required
The URI of the RTP header extension, as defined in [RFC5285]. Read-only parameter.
id
of type unsigned short, required
The value put in the RTP packet to identify the header extension. Read-only parameter.
encrypted
of type boolean
Whether the header extension is encrypted or not. Read-only parameter.
The RTCRtpHeaderExtensionParameters
dictionary enables an
application to determine whether a header extension is configured
for use within an RTCRtpSender
or RTCRtpReceiver
. For an
RTCRtpTransceiver
transceiver, an application can
determine the "direction" parameter (defined in Section 5 of
[RFC5285]) of a header extension as follows without having to
parse SDP:
sender
.getParameters
()
.headerExtensions
.
receiver
.getParameters
()
.headerExtensions
.
sender
.getParameters
()
.headerExtensions
and
transceiver.receiver
.getParameters
()
.headerExtensions
.
sender
.getParameters
()
.headerExtensions
nor
transceiver.receiver
.getParameters
()
.headerExtensions
.
WebIDLdictionary RTCRtpCodecParameters
{
required octet payloadType
;
required DOMString mimeType
;
required unsigned long clockRate
;
unsigned short channels
;
DOMString sdpFmtpLine
;
};
RTCRtpCodecParameters
Members
payloadType
of type octet, required
The RTP payload type used to identify this codec. Read-only parameter.
mimeType
of type DOMString, required
The codec MIME media type/subtype. Valid media types and subtypes are listed in [IANA-RTP-2]. Read-only parameter.
clockRate
of type unsigned long, required
The codec clock rate expressed in Hertz. Read-only parameter.
channels
of type unsigned short
When present, indicates the number of channels (mono=1, stereo=2). Read-only parameter.
sdpFmtpLine
of type DOMString
The "format specific parameters" field from the
a=fmtp
line in the SDP
corresponding to the codec, if one exists, as defined by
[RFC8829] (section 5.8.). For an
RTCRtpSender
, these parameters come from the
[[CurrentRemoteDescription]]
, and for an
RTCRtpReceiver
, they come from the
local description (which is
[[PendingLocalDescription]]
if not null
, and
[[CurrentLocalDescription]]
otherwise).
Read-only parameter.
WebIDLdictionary RTCRtpCapabilities
{
required sequence<RTCRtpCodecCapability
> codecs
;
required sequence<RTCRtpHeaderExtensionCapability
> headerExtensions
;
};
RTCRtpCapabilities
Members
codecs
of type sequence<RTCRtpCodecCapability
>,
required
Supported media codecs as well as entries for RTX, RED and
FEC mechanisms. There will only be a single entry in
codecs
for retransmission via RTX, with
sdpFmtpLine
not present.
headerExtensions
of type sequence<RTCRtpHeaderExtensionCapability
>,
required
Supported RTP header extensions.
WebIDLdictionary RTCRtpCodecCapability
{
required DOMString mimeType
;
required unsigned long clockRate
;
unsigned short channels
;
DOMString sdpFmtpLine
;
};
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:
mimeType
of type DOMString, required
The codec MIME media type/subtype. Valid media types and subtypes are listed in [IANA-RTP-2].
clockRate
of type unsigned long, required
The codec clock rate expressed in Hertz.
channels
of type unsigned short
If present, indicates the maximum number of channels (mono=1, stereo=2).
sdpFmtpLine
of type DOMString
The "format specific parameters" field from the
a=fmtp
line in the SDP
corresponding to the codec, if one exists.
WebIDLdictionary RTCRtpHeaderExtensionCapability
{
DOMString uri
;
};
RTCRtpHeaderExtensionCapability
Members
uri
of type DOMString
The URI of the RTP header extension, as defined in [RFC5285].
The RTCRtpReceiver
interface allows an application to inspect the
receipt of a MediaStreamTrack
.
To create an RTCRtpReceiver with a string, kind, run the following steps:
Let receiver be a new RTCRtpReceiver
object.
Let track be a new MediaStreamTrack
object
[GETUSERMEDIA]. The source of track is a
remote source provided by receiver. Note
that the track.id
is
generated by the user agent and does not map to any track
IDs on the remote side.
Initialize track.kind to kind.
Initialize track.label to the result of concatenating
the string "remote "
with kind.
Initialize track.readyState to live
.
Initialize track.muted to true
. See the
MediaStreamTrack
section about how the muted
attribute
reflects if a MediaStreamTrack
is receiving media data or
not.
Let receiver have a [[ReceiverTrack]] internal slot initialized to track.
Let receiver have a [[ReceiverTransport]]
internal slot initialized to null
.
Let receiver have a
[[LastStableStateReceiverTransport]] internal slot
initialized to null
.
Let receiver have an
[[AssociatedRemoteMediaStreams]] internal slot,
representing a list of MediaStream
objects that the
MediaStreamTrack
object of this receiver is associated with,
and initialized to an empty list.
Let receiver have a [[LastStableStateAssociatedRemoteMediaStreams]] internal slot and initialize it to an empty list.
Let receiver have a [[ReceiveCodecs]]
internal slot, representing a list of RTCRtpCodecParameters
dictionaries, and initialized to an empty list.
Let receiver have a [[LastStableStateReceiveCodecs]] internal slot and initialize it to an empty list.
Return receiver.
WebIDL[Exposed=Window]
interface RTCRtpReceiver
{
readonly attribute MediaStreamTrack track
;
readonly attribute RTCDtlsTransport
? transport
;
static RTCRtpCapabilities
? getCapabilities
(DOMString kind);
RTCRtpReceiveParameters
getParameters
();
sequence<RTCRtpContributingSource
> getContributingSources
();
sequence<RTCRtpSynchronizationSource
> getSynchronizationSources
();
Promise<RTCStatsReport
> getStats
();
};
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 [[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.
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
setCodecPreferences
()
algorithm and
what inputs it throws InvalidModificationError
on,
and should also be consistent with information revealed by
createOffer
()
and createAnswer
()
about codecs
negotiated for 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:
headerExtensions
sequence is populated
based on the header extensions that the receiver is currently
prepared to receive.
codecs
is set to the value of the
[[ReceiveCodecs]]
internal slot.
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
out.
getContributingSources
Returns an RTCRtpContributingSource
for each unique CSRC
identifier received by this RTCRtpReceiver
in the last 10
seconds, in descending timestamp
order.
getSynchronizationSources
Returns an RTCRtpSynchronizationSource
for each unique
SSRC identifier received by this RTCRtpReceiver
in the
last 10 seconds, in descending
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:
Let selector be the RTCRtpReceiver
object
on which the method was invoked.
Let p be a new promise, and run the following steps in parallel:
Gather the stats indicated by selector according to the stats selection algorithm.
Resolve p with the resulting
RTCStatsReport
object, containing the gathered
stats.
Return p.
The RTCRtpContributingSource
and
RTCRtpSynchronizationSource
dictionaries contain
information about a given contributing source (CSRC) or
synchronization source (SSRC) respectively. When an audio or video
frame from one or more RTP packets is delivered to the
RTCRtpReceiver
's MediaStreamTrack
, the user agent MUST queue
a task to update the relevant information for the
RTCRtpContributingSource
and RTCRtpSynchronizationSource
dictionaries based on the content of those packets. The information
relevant to the RTCRtpSynchronizationSource
dictionary
corresponding to the SSRC identifier, is updated each time, and if an
RTP packet contains CSRC identifiers, then the information relevant
to the RTCRtpContributingSource
dictionaries corresponding to
those CSRC identifiers is also updated. The user agent MUST process
RTP packets in order of ascending RTP timestamps. The user agent MUST
keep information from RTP packets delivered to the
RTCRtpReceiver
's MediaStreamTrack
in the previous 10 seconds.
MediaStreamTrack
is not attached to any sink for
playout, getSynchronizationSources
and
getContributingSources
returns up-to-date
information as long as the track is not ended; sinks are not a
prerequisite for decoding RTP packets.
RTCRtpSynchronizationSource
and
RTCRtpContributingSource
dictionaries for a particular
RTCRtpReceiver
contain information from a single point in the RTP
stream.
WebIDLdictionary RTCRtpContributingSource
{
required DOMHighResTimeStamp timestamp
;
required unsigned long source
;
double audioLevel
;
required unsigned long rtpTimestamp
;
};
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.
WebIDLdictionary RTCRtpSynchronizationSource
: RTCRtpContributingSource
{};
The RTCRtpSynchronizationSource
dictionary is expected to serve as an extension point for the specification to surface data only available in SSRCs.
The RTCRtpTransceiver
interface represents a combination of an
RTCRtpSender
and an RTCRtpReceiver
that share a common media stream "identification-tag". As defined in [RFC8829] (section 3.4.1.), an RTCRtpTransceiver
is said
to be associated with a media description if its
"mid" property is non-null and matches a media stream "identification-tag" in the media description; otherwise it
is said to be disassociated with that media description.
A RTCRtpTransceiver
may become associated with a new pending
description in RFC8829 while still being disassociated with the
current description. This may happen in check if negotiation is needed.
The transceiver kind of an RTCRtpTransceiver
is
defined by the kind of the associated RTCRtpReceiver
's
MediaStreamTrack
object.
To create an RTCRtpTransceiver with an RTCRtpReceiver
object, receiver, RTCRtpSender
object,
sender, and an RTCRtpTransceiverDirection
value,
direction, run the following steps:
Let transceiver be a new RTCRtpTransceiver
object.
Let transceiver have a [[Sender]] internal slot, initialized to sender.
Let transceiver have a [[Receiver]] internal slot, initialized to receiver.
Let transceiver have a [[Stopping]]
internal slot, initialized to false
.
Let transceiver have a [[Stopped]]
internal slot, initialized to false
.
Let transceiver have a [[Direction]] internal slot, initialized to direction.
Let transceiver have a [[Receptive]]
internal slot, initialized to false
.
Let transceiver have a
[[CurrentDirection]] internal slot, initialized to
null
.
Let transceiver have a [[FiredDirection]]
internal slot, initialized to null
.
Let transceiver have a [[PreferredCodecs]] internal slot, initialized to an empty list.
Let transceiver have a [[JsepMid]]
internal slot, initialized to null
. This is the
"RtpTransceiver mid property" defined in [RFC8829] (section 5.2.1. and section 5.3.1.), and is only
modified there.
Let transceiver have a [[Mid]] internal
slot, initialized to null
.
Return transceiver.
RTCDtlsTransport
and RTCIceTransport
objects. This will only
occur as part of the process of setting a session description.
WebIDL[Exposed=Window]
interface RTCRtpTransceiver
{
readonly attribute DOMString? mid
;
[SameObject] readonly attribute RTCRtpSender
sender
;
[SameObject] readonly attribute RTCRtpReceiver
receiver
;
attribute RTCRtpTransceiverDirection
direction
;
readonly attribute RTCRtpTransceiverDirection
? currentDirection
;
undefined stop
();
undefined setCodecPreferences
(sequence<RTCRtpCodecCapability
> codecs);
};
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 [[Mid]]
slot.
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.
direction
of type RTCRtpTransceiverDirection
As defined in [RFC8829] (section 4.2.4.), 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 [RFC8829] (section 5.2.2. and section 5.3.2.)
On getting, the user agent MUST run the following steps:
Let transceiver be the RTCRtpTransceiver
object on which the getter is invoked.
If transceiver.[[Stopping]]
is
true
, return
"stopped
".
Otherwise, return the value of the [[Direction]]
slot.
On setting, the user agent MUST run the following steps:
Let transceiver be the RTCRtpTransceiver
object on which the setter is invoked.
Let connection be the RTCPeerConnection
object associated with transceiver.
If transceiver.[[Stopping]]
is
true
, throw an
InvalidStateError
.
Let newDirection be the argument to the setter.
If newDirection is equal to
transceiver.[[Direction]]
, abort these
steps.
Set transceiver.[[Direction]]
to
newDirection.
Update the negotiation-needed flag for connection.
currentDirection
of type RTCRtpTransceiverDirection
, readonly,
nullable
As defined in [RFC8829] (section 4.2.5.), 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, the value is null
. If the transceiver
is stopped
, the value is
"stopped
".
On getting, the user agent MUST run the following steps:
Let transceiver be the RTCRtpTransceiver
object on which the getter is invoked.
If transceiver.[[Stopped]]
is
true
, return
"stopped
".
Otherwise, return the value of the
[[CurrentDirection]]
slot.
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 updates the negotiation-needed flag for the RTCRtpTransceiver
's associated
RTCPeerConnection
.
A stopping transceiver will cause future calls to
createOffer
to generate a zero port in
the media description for the corresponding
transceiver, as defined in [RFC8829] (section 4.2.1.) (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
createAnswer
.
A stopped transceiver will cause future calls to
createOffer
or
createAnswer
to generate a zero port in
the media description for the corresponding
transceiver, as defined in [RFC8829] (section 4.2.1.).
The transceiver will remain in the stopping
state, unless
it becomes stopped
by
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:
Let transceiver be the RTCRtpTransceiver
object on which the method is invoked.
Let connection be the RTCPeerConnection
object associated with transceiver.
If connection.[[IsClosed]]
is
true
, throw an
InvalidStateError
.
If transceiver.[[Stopping]]
is
true
, abort these steps.
Stop sending and receiving with transceiver.
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:
Let sender be
transceiver.[[Sender]]
.
Let receiver be
transceiver.[[Receiver]]
.
Stop sending media with sender.
Send an RTCP BYE for each RTP stream that was being sent by sender, as specified in [RFC3550].
Stop receiving media with receiver.
If disappear is false
, execute
the steps for
receiver.[[ReceiverTrack]]
to be
ended. This
fires an event.
Set transceiver.[[Direction]]
to
"inactive
".
Set transceiver.[[Stopping]]
to
true
.
The stop the RTCRtpTransceiver algorithm given a
transceiver and, optionally, a
disappear boolean defaulting to
false
, is as follows:
If transceiver.[[Stopping]]
is
false
, stop sending and receiving with
transceiver and disappear.
Set transceiver.[[Stopped]]
to
true
.
Set transceiver.[[Receptive]]
to
false
.
Set transceiver.[[CurrentDirection]]
to null
.
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
.
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
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.
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
.getCapabilities
(kind)
or
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 throw an InvalidModificationError
.
Due to a recommendation in [SDP], calls to
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] (section 5.3.1.) 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:
Let transceiver be the RTCRtpTransceiver
object this method was invoked on.
Let codecs be the first argument.
If codecs is an empty list, set
transceiver.[[PreferredCodecs]]
to
codecs and abort these steps.
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.
Let kind be the transceiver's transceiver kind.
If the intersection between codecs and
RTCRtpSender
.getCapabilities
(kind).codecs
or the intersection between codecs and
RTCRtpReceiver
.getCapabilities
(kind).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.direction
.
Let codecCapabilities be the union of
RTCRtpSender
.getCapabilities
(kind).codecs
and
RTCRtpReceiver
.getCapabilities
(kind).codecs
.
For each codec in codecs,
InvalidModificationError
.
Set transceiver.[[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.
Simulcast functionality is provided via the
method of the
addTransceiver
object and the RTCPeerConnection
method of the setParameters
object.
RTCRtpSender
The
method establishes the
simulcast envelope which includes the maximum number of
simulcast streams that can be sent, as well as the ordering of the
addTransceiver
. While characteristics of
individual simulcast streams can be modified using the
encodings
method, the simulcast envelope
cannot be changed. One of the implications of this model is that
the setParameters
addTrack
()
method cannot provide
simulcast functionality since it does not take
as an argument, and
therefore cannot configure an sendEncodings
to send
simulcast.
RTCRtpTransceiver
Another implication is that the answerer cannot set the simulcast envelope directly. Upon calling the
method of the
setRemoteDescription
object, the simulcast envelope is
configured on the RTCPeerConnection
to contain the layers
described by the specified session description. Once the
envelope is determined, layers cannot be removed. They can be
marked as inactive by setting the
RTCRtpTransceiver
member to active
false
effectively disabling the layer.
While
cannot modify the simulcast
envelope, it is still possible to control the number of streams
that are sent and the characteristics of those streams. Using
setParameters
, simulcast streams can be made
inactive by setting the setParameters
member
to active
false
, or can be reactivated by setting the
member to active
true
.
Using
, stream characteristics can be
changed by modifying attributes such as
setParameters
.
maxBitrate
Simulcast is frequently used to send multiple encodings to an SFU,
which will then forward one of the simulcast streams to the end
user. The user agent is therefore expected to allocate bandwidth
between encodings in such a way that all simulcast streams are
usable on their own; for instance, if two simulcast streams have
the same
, one would expect
to see a similar bitrate on both streams. If bandwidth does not
permit all simulcast streams to be sent in an usable form, the user
agent is expected to stop sending some of the simulcast streams.
maxBitrate
As defined in [RFC8829] (section 3.7.), an
offer from a user-agent will only contain a "send" description and
no "recv" description on the a=simulcast
line. Alternatives and restrictions (described in
[RFC8853]) are not supported.
This specification does not define how to configure reception of
multiple RTP encodings using
,
createOffer
or
createAnswer
. However when
addTransceiver
is called with a
corresponding remote description that is able to send multiple RTP
encodings as defined in [RFC8829], and the browser supports
receiving multiple RTP encodings, the setRemoteDescription
may
receive multiple RTP encodings and the parameters retrieved via the
transceiver's
RTCRtpReceiver
.receiver
getParameters
()
will reflect the encodings negotiated.
An
can receive multiple RTP streams in a
scenario where a Selective Forwarding Unit (SFU) switches between
simulcast streams it receives from user agents. If the SFU does not
rewrite RTP headers so as to arrange the switched streams into a
single RTP stream prior to forwarding, the RTCRtpReceiver
will
receive packets from distinct RTP streams, each with their own SSRC
and sequence number space. While the SFU may only forward a single
RTP stream at any given time, packets from multiple RTP streams can
become intermingled at the receiver due to reordering. An
RTCRtpReceiver
equipped to receive multiple RTP streams will
therefore need to be able to correctly order the received packets,
recognize potential loss events and react to them. Correct
operation in this scenario is non-trivial and therefore is optional
for implementations of this specification.
RTCRtpReceiver
This section is non-normative.
Examples of simulcast scenarios implemented with encoding parameters:
// Example of 3-layer spatial simulcast with all but the lowest resolution layer disabled
var encodings = [
{rid: 'q', active: true, scaleResolutionDownBy: 4.0}
{rid: 'h', active: false, scaleResolutionDownBy: 2.0},
{rid: 'f', active: false},
];
Simulcast sending functionality is enabled by the
addTransceiver
method via its
sendEncodings
argument, or the
setRemoteDescription
method with a remote
offer to receive simulcast, which are both methods on the
RTCPeerConnection
object. Additionally,
the setParameters
method on each RTCRtpSender
object can be used to inspect and modify the functionality.
An RTCRtpTransceiver
's simulcast envelope is
established in the first successful negotiation that involves it
sending simulcast instead of unicast, and includes the maximum number of
simulcast streams that can be sent, as well as the ordering of its
encodings
. This simulcast envelope
may be narrowed (reducing the number of layers) in subsequent
renegotiation, but cannot be reexpanded. Characteristics of
individual simulcast streams can be modified using the
setParameters
method, but the simulcast envelope
itself cannot be changed by that method.
While the addTrack
()
method lacks the
sendEncodings
argument necessary to
configure simulcast, transceivers can be promoted to
simulcast when the user agent is the answerer. Upon calling the
setRemoteDescription
method with a remote
offer to receive simulcast, a proposed envelope is
configured on a RTCRtpTransceiver
to contain the layers
described in the specified session description. As long as this
description isn't rolled back, the proposed envelope becomes
the RTCRtpTransceiver
's simulcast envelope when negotiation
completes. As above, this simulcast envelope may be narrowed
in subsequent renegotiation, but not reexpanded.
While setParameters
cannot modify the simulcast envelope, it is still possible to control the number of streams
that are sent and the characteristics of those streams. Using
setParameters
, simulcast streams can be made
inactive by setting the active
member
to false
, or can be reactivated by setting the
active
member to true
.
[RFC7728] (RTP Pause/Resume) is not supported, nor is signaling
of pause/resume via SDP Offer/Answer.
Using setParameters
, stream characteristics can be
changed by modifying attributes such as
maxBitrate
.
Simulcast is frequently used to send multiple encodings to an SFU,
which will then forward one of the simulcast streams to the end
user. The user agent is therefore expected to allocate bandwidth
between encodings in such a way that all simulcast streams are
usable on their own; for instance, if two simulcast streams have
the same maxBitrate
, one would expect
to see a similar bitrate on both streams. If bandwidth does not
permit all simulcast streams to be sent in an usable form, the user
agent is expected to stop sending some of the simulcast streams.
As defined in [RFC8829] (section 3.7.), an
offer from a user-agent will only contain a "send" description and
no "recv" description on the a=simulcast
line. Alternatives and restrictions (described in
[RFC8853]) are not supported.
This specification does not define how to configure reception of
multiple RTP encodings using createOffer
,
createAnswer
or
addTransceiver
. However when
setRemoteDescription
is called with a
corresponding remote description that is able to send multiple RTP
encodings as defined in [RFC8829], and the browser supports
receiving multiple RTP encodings, the RTCRtpReceiver
may
receive multiple RTP encodings and the parameters retrieved via the
transceiver's
receiver
.getParameters
()
will reflect the encodings negotiated.
An RTCRtpReceiver
can receive multiple RTP streams in a
scenario where a Selective Forwarding Unit (SFU) switches between
simulcast streams it receives from user agents. If the SFU does not
rewrite RTP headers so as to arrange the switched streams into a
single RTP stream prior to forwarding, the RTCRtpReceiver
will
receive packets from distinct RTP streams, each with their own SSRC
and sequence number space. While the SFU may only forward a single
RTP stream at any given time, packets from multiple RTP streams can
become intermingled at the receiver due to reordering. An
RTCRtpReceiver
equipped to receive multiple RTP streams will
therefore need to be able to correctly order the received packets,
recognize potential loss events and react to them. Correct
operation in this scenario is non-trivial and therefore is optional
for implementations of this specification.
This section is non-normative.
Examples of simulcast scenarios implemented with encoding parameters:
// Example of 3-layer spatial simulcast with all but the lowest resolution layer disabled
var encodings = [
{rid: 'q', active: true, scaleResolutionDownBy: 4.0}
{rid: 'h', active: false, scaleResolutionDownBy: 2.0},
{rid: 'f', active: false},
];
This section is non-normative.
Together, the direction
attribute and the
replaceTrack
method enable developers to implement
"hold" scenarios.
To send music to a peer and cease rendering received audio (music-on-hold):
async function playMusicOnHold() {
try {
// Assume we have an audio transceiver and a music track named musicTrack
await audio.sender.replaceTrack(musicTrack);
// Mute received audio
audio.receiver.track.enabled = false;
// Set the direction to send-only (requires negotiation)
audio.direction = 'sendonly';
} catch (err) {
console.error(err);
}
}
To respond to a remote peer's "sendonly" offer:
async function handleSendonlyOffer() {
try {
// Apply the sendonly offer first,
// to ensure the receiver is ready for ICE candidates.
await pc.setRemoteDescription(sendonlyOffer);
// Stop sending audio
await audio.sender.replaceTrack(null);
// Align our direction to avoid further negotiation
audio.direction = 'recvonly';
// Call createAnswer and send a recvonly answer
await doAnswer();
} catch (err) {
// handle signaling error
}
}
To stop sending music and send audio captured from a microphone, as well to render received audio:
async function stopOnHoldMusic() {
// Assume we have an audio transceiver and a microphone track named micTrack
await audio.sender.replaceTrack(micTrack);
// Unmute received audio
audio.receiver.track.enabled = true;
// Set the direction to sendrecv (requires negotiation)
audio.direction = 'sendrecv';
}
To respond to being taken off hold by a remote peer:
async function onOffHold() {
try {
// Apply the sendrecv offer first, to ensure receiver is ready for ICE candidates.
await pc.setRemoteDescription(sendrecvOffer);
// Start sending audio
await audio.sender.replaceTrack(micTrack);
// Set the direction sendrecv (just in time for the answer)
audio.direction = 'sendrecv';
// Call createAnswer and send a sendrecv answer
await doAnswer();
} catch (err) {
// handle signaling error
}
}
The RTCDtlsTransport
interface allows an application access to
information about the Datagram Transport Layer Security (DTLS)
transport over which RTP and RTCP packets are sent and received by
RTCRtpSender
and RTCRtpReceiver
objects, as well other data
such as SCTP packets sent and received by data channels. In
particular, DTLS adds security to an underlying transport, and the
RTCDtlsTransport
interface allows access to information about the
underlying transport and the security added. RTCDtlsTransport
objects are constructed as a result of calls to
setLocalDescription
()
and
setRemoteDescription
()
. Each
RTCDtlsTransport
object represents the DTLS transport layer for
the RTP or RTCP component
of a specific
RTCRtpTransceiver
, or a group of RTCRtpTransceiver
s if such a
group has been negotiated via [RFC8843].
RTCRtpTransceiver
will be
represented by an existing RTCDtlsTransport
object, whose
state
will be updated accordingly, as opposed to
being represented by a new object.
An RTCDtlsTransport
has a [[DtlsTransportState]]
internal slot initialized to "new
" and a
[[RemoteCertificates]] slot initialized to an empty list.
When the underlying DTLS transport experiences an error, such as a certificate validation failure, or a fatal alert (see [RFC5246] section 7.2), the user agent MUST queue a task that runs the following steps:
Let transport be the RTCDtlsTransport
object to
receive the state update and error notification.
If the state of transport is already
"failed
", abort these steps.
Set transport.[[DtlsTransportState]]
to
"failed
".
Fire an event named error
using the
RTCErrorEvent
interface with its errorDetail attribute set to
either "dtls-failure
" or
"fingerprint-failure
", as appropriate, and
other fields set as described under the RTCErrorDetailType
enum description, at transport.
Fire an event named statechange
at
transport.
When the underlying DTLS transport needs to update the state of the
corresponding RTCDtlsTransport
object for any other reason, the
user agent MUST queue a task that runs the following steps:
Let transport be the RTCDtlsTransport
object to
receive the state update.
Let newState be the new state.
Set transport.[[DtlsTransportState]]
to
newState.
If newState is connected
then let newRemoteCertificates be the certificate
chain in use by the remote side, with each certificate encoded in
binary Distinguished Encoding Rules (DER) [X690], and set
transport.[[RemoteCertificates]]
to
newRemoteCertificates.
Fire an event named statechange
at
transport.
WebIDL[Exposed=Window]
interface RTCDtlsTransport
: EventTarget {
[SameObject] readonly attribute RTCIceTransport
iceTransport
;
readonly attribute RTCDtlsTransportState
state
;
sequence<ArrayBuffer> getRemoteCertificates
();
attribute EventHandler onstatechange
;
attribute EventHandler onerror
;
};
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 [[DtlsTransportState]]
slot.
onstatechange
of type EventHandler
statechange
.
onerror
of type EventHandler
error
.
getRemoteCertificates
Returns the value of [[RemoteCertificates]]
.
WebIDLenum RTCDtlsTransportState
{
"new
",
"connecting
",
"connected
",
"closed
",
"failed
"
};
Enum value | Description |
---|---|
new
|
DTLS has not started negotiating yet. |
connecting
|
DTLS is in the process of negotiating a secure connection and verifying the remote fingerprint. |
connected
|
DTLS has completed negotiation of a secure connection and verified the remote fingerprint. |
closed
|
The transport has been closed intentionally as the result of
receipt of a close_notify alert, or calling
close () .
|
failed
|
The transport has failed as the result of an error (such as receipt of an error alert or failure to validate the remote fingerprint). |
The RTCDtlsFingerprint
dictionary includes the hash function
algorithm and certificate fingerprint as described in [RFC4572].
WebIDLdictionary RTCDtlsFingerprint
{
DOMString algorithm
;
DOMString value
;
};
algorithm
of type DOMString
One of the the hash function algorithms defined in the 'Hash function Textual Names' registry [IANA-HASH-FUNCTION].
value
of type DOMString
The value of the certificate fingerprint in lowercase hex string as expressed utilizing the syntax of 'fingerprint' in [RFC4572] Section 5.
The RTCIceTransport
interface allows an application access to
information about the ICE transport over which packets are sent and
received. In particular, ICE manages peer-to-peer connections which
involve state which the application may want to access.
RTCIceTransport
objects are constructed as a result of calls to
setLocalDescription
()
and
setRemoteDescription
()
. The underlying ICE
state is managed by the ICE agent; as such, the state of an
RTCIceTransport
changes when the ICE Agent provides
indications to the user agent as described below. Each
RTCIceTransport
object represents the ICE transport layer for the
RTP or RTCP component
of a specific
RTCRtpTransceiver
, or a group of RTCRtpTransceiver
s if such a
group has been negotiated via [RFC8843].
RTCRtpTransceiver
will be
represented by an existing RTCIceTransport
object, whose
state
will be updated accordingly, as opposed to
being represented by a new object.
When the ICE Agent indicates that it began gathering a generation of candidates for an RTCIceTransport
, the user
agent MUST queue a task that runs the following steps:
Let connection be the RTCPeerConnection
object
associated with this ICE Agent.
If connection.[[IsClosed]]
is
true
, abort these steps.
Let transport be the RTCIceTransport
for which
candidate gathering began.
Set transport.[[IceGathererState]]
to
gathering
.
Fire an event named gatheringstatechange
at
transport.
Update the ICE gathering state of connection.
When the ICE Agent is finished gathering a generation of
candidates for an RTCIceTransport
, and those candidates have been
surfaced to the application, the user agent MUST queue a task that
runs the following steps:
Let connection be the RTCPeerConnection
object
associated with this ICE Agent.
If connection.[[IsClosed]]
is
true
, abort these steps.
Let transport be the RTCIceTransport
for which
candidate gathering finished.
Let newCandidate be the result of creating an RTCIceCandidate with a new dictionary whose
sdpMid
and
sdpMLineIndex
are set to the values
associated with this RTCIceTransport
,
usernameFragment
is set to the username
fragment of the generation of candidates for which
gathering finished, and candidate
is set
to an empty string.
Fire an event named icecandidate
using the
RTCPeerConnectionIceEvent
interface with the candidate
attribute set to newCandidate at
connection.
If another generation of candidates is still being gathered, abort these steps.
Set transport.[[IceGathererState]]
to
complete
.
Fire an event named gatheringstatechange
at
transport.
Update the ICE gathering state of connection.
When the ICE Agent indicates that a new ICE candidate is
available for an RTCIceTransport
, either by taking one from the
ICE candidate pool or gathering it
from scratch, the user agent MUST queue a task that runs the
following steps:
Let candidate be the available ICE candidate.
Let connection be the RTCPeerConnection
object
associated with this ICE Agent.
If connection.[[IsClosed]]
is
true
, abort these steps.
If either
connection.[[PendingLocalDescription]]
or
connection.[[CurrentLocalDescription]]
are not
null
, and represent the ICE generation for
which candidate was gathered, surface the candidate with candidate and connection, and abort
these steps.
Otherwise, append candidate to
connection.[[EarlyCandidates]]
.
When the ICE Agent signals that the ICE role has changed due to
an ICE binding request with a role collision per [RFC8445] section
7.3.1.1, the UA will queue a task to set the value of
[[IceRole]]
to the new value.
To release early candidates of a connection, run the following steps:
For each candidate, candidate, in
connection.[[EarlyCandidates]]
, queue a task
to surface the candidate with candidate and
connection.
Set connection.[[EarlyCandidates]]
to an empty
list.
To surface a candidate with candidate and connection, run the following steps:
If connection.[[IsClosed]]
is
true
, abort these steps.
Let transport be the RTCIceTransport
for which
candidate is being made available.
If connection.[[PendingLocalDescription]]
is
not null
, and represents the ICE generation
for which candidate was gathered, add
candidate to
connection.[[PendingLocalDescription]]
.sdp.
If connection.[[CurrentLocalDescription]]
is
not null
, and represents the ICE generation
for which candidate was gathered, add
candidate to
connection.[[CurrentLocalDescription]]
.sdp.
Let newCandidate be the result of creating an RTCIceCandidate with a new dictionary whose
sdpMid
and
sdpMLineIndex
are set to the values
associated with this RTCIceTransport
,
usernameFragment
is set to the username
fragment of the candidate, and candidate
is set to a string encoded using the candidate-attribute
grammar to represent candidate.
Add newCandidate to transport's set of local candidates.
Fire an event named icecandidate
using the
RTCPeerConnectionIceEvent
interface with the candidate
attribute set to newCandidate at
connection.
The RTCIceTransportState
of an RTCIceTransport
may change
because a candidate pair with a usable connection was found and
selected or it may change without the selected candidate pair
changing. The selected pair and RTCIceTransportState
are related
and are handled in the same task.
When the ICE Agent indicates that an RTCIceTransport
has
changed either the selected candidate pair, the
RTCIceTransportState
or both, the user agent MUST queue a task
that runs the following steps:
Let connection be the RTCPeerConnection
object
associated with this ICE Agent.
If connection.[[IsClosed]]
is
true
, abort these steps.
Let transport be the RTCIceTransport
whose state
is changing.
Let selectedCandidatePairChanged be
false
.
Let transportIceConnectionStateChanged be
false
.
Let connectionIceConnectionStateChanged be
false
.
Let connectionStateChanged be false
.
If transport's selected candidate pair was changed, run the following steps:
Let newCandidatePair be a newly created
RTCIceCandidatePair
representing the indicated pair if
one is selected, and null
otherwise.
Set transport.[[SelectedCandidatePair]]
to
newCandidatePair.
Set selectedCandidatePairChanged to
true
.
If transport's RTCIceTransportState
was changed,
run the following steps:
Set transport.[[IceTransportState]]
to the
new indicated RTCIceTransportState
.
Set transportIceConnectionStateChanged to
true
.
Set connection's ICE connection state to the
value of deriving a new state value as described by the
RTCIceConnectionState
enum.
If the ice connection state changed in the previous
step, set connectionIceConnectionStateChanged to
true
.
Set connection's connection state to the
value of deriving a new state value as described by the
RTCPeerConnectionState
enum.
If the connection state changed in the previous step,
set connectionStateChanged to true
.
If selectedCandidatePairChanged is true
,
fire an event named selectedcandidatepairchange
at
transport.
If transportIceConnectionStateChanged is
true
, fire an event named statechange
at
transport.
If connectionIceConnectionStateChanged is
true
, fire an event named
iceconnectionstatechange
at connection.
If connectionStateChanged is true
, fire an event named connectionstatechange
at
connection.
An RTCIceTransport
object has the following internal slots:
new
"
new
"
null
unknown
"
WebIDL[Exposed=Window]
interface RTCIceTransport
: EventTarget {
readonly attribute RTCIceRole
role
;
readonly attribute RTCIceComponent
component
;
readonly attribute RTCIceTransportState
state
;
readonly attribute RTCIceGathererState
gatheringState
;
sequence<RTCIceCandidate
> getLocalCandidates
();
sequence<RTCIceCandidate
> getRemoteCandidates
();
RTCIceCandidatePair
? getSelectedCandidatePair
();
RTCIceParameters
? getLocalParameters
();
RTCIceParameters
? getRemoteParameters
();
attribute EventHandler onstatechange
;
attribute EventHandler ongatheringstatechange
;
attribute EventHandler onselectedcandidatepairchange
;
};
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 "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 gatheringState
attribute MUST, on getting, return the
value of the [[IceGathererState]]
slot.
onstatechange
of type EventHandler
statechange
, MUST be fired any time the RTCIceTransport
state
changes.
ongatheringstatechange
of type
EventHandler
gatheringstatechange
, MUST be fired any time the
RTCIceTransport
ICE gathering state changes.
onselectedcandidatepairchange
of type
EventHandler
selectedcandidatepairchange
, MUST be fired any time the
RTCIceTransport
's selected candidate pair changes.
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
()
.
getRemoteCandidates
will not expose peer reflexive
candidates since they are not received via
addIceCandidate
()
.
getSelectedCandidatePair
Returns the selected candidate pair on which packets are
sent. This method MUST return the value of the
[[SelectedCandidatePair]]
slot. When
RTCIceTransport
.state
is
"new
" or
"closed
"
getSelectedCandidatePair
returns null
.
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.
WebIDLdictionary RTCIceParameters
{
DOMString usernameFragment
;
DOMString password
;
};
RTCIceParameters
Members
WebIDLdictionary RTCIceCandidatePair
{
RTCIceCandidate
local
;
RTCIceCandidate
remote
;
};
RTCIceCandidatePair
Members
local
of type RTCIceCandidate
The local ICE candidate.
remote
of type RTCIceCandidate
The remote ICE candidate.
WebIDLenum RTCIceGathererState
{
"new
",
"gathering
",
"complete
"
};
Enum value | Description |
---|---|
new
|
The RTCIceTransport was just created, and has not
started gathering candidates yet.
|
gathering
|
The RTCIceTransport is in the process of gathering
candidates.
|
complete
|
The RTCIceTransport has completed gathering and the
end-of-candidates indication for this transport has been
sent. It will not gather candidates again until an ICE
restart causes it to restart.
|
WebIDLenum RTCIceTransportState
{
"new
",
"checking
",
"connected
",
"completed
",
"disconnected
",
"failed
",
"closed
"
};
Enum value | Description |
---|---|
new
|
The RTCIceTransport is gathering candidates and/or
waiting for remote candidates to be supplied, and has not
yet started checking.
|
checking
|
The RTCIceTransport has received at least one remote
candidate and is checking candidate pairs and has either
not yet found a connection or consent checks [RFC7675]
have failed on all previously successful candidate pairs.
In addition to checking, it may also still be gathering.
|
connected
|
The RTCIceTransport has found a usable connection, but
is still checking other candidate pairs to see if there is
a better connection. It may also still be gathering and/or
waiting for additional remote candidates. If consent checks
[RFC7675] fail on the connection in use, and there are
no other successful candidate pairs available, then the
state transitions to "checking "
(if there are candidate pairs remaining to be checked) or
"disconnected " (if there are no
candidate pairs to check, but the peer is still gathering
and/or waiting for additional remote candidates).
|
completed
|
The RTCIceTransport has finished gathering, received an
indication that there are no more remote candidates,
finished checking all candidate pairs and found a
connection. If consent checks [RFC7675] subsequently
fail on all successful candidate pairs, the state
transitions to "failed ".
|
disconnected
|
The ICE Agent has determined that connectivity is
currently lost for this RTCIceTransport . This is a
transient state that may trigger intermittently (and
resolve itself without action) on a flaky network. The way
this state is determined is implementation dependent.
Examples include:
RTCIceTransport has finished
checking all existing candidates pairs and not found a
connection (or consent checks [RFC7675] once successful,
have now failed), but it is still gathering and/or waiting
for additional remote candidates.
|
failed
|
Candidate Correction 8:Put ICE transport connection in failed state when no candidates are received (PR #2704) has finished gathering, received an
indication that there are no more remote candidates,
finished checking all candidate pairs, and all pairs have
either failed connectivity checks or have lost consent.
This is a terminal state until ICE is restarted. Since an
ICE restart may cause connectivity to resume, entering the
" " state does not cause DTLS
transports, SCTP associations or the data channels that run
over them to close, or tracks to mute.
The
RTCIceTransport has finished gathering, received an
indication that there are no more remote candidates,
finished checking all candidate pairs, and all pairs have
either failed connectivity checks or lost consent, and
either zero local candidates were gathered or the PAC timer
has expired [RFC8863].
This is a terminal state until ICE is restarted. Since an
ICE restart may cause connectivity to resume, entering the
"failed " state does not cause DTLS
transports, SCTP associations or the data channels that run
over them to close, or tracks to mute.
|
closed
|
The RTCIceTransport has shut down and is no longer
responding to STUN requests.
|
The most common transitions for a successful call will be new ->
checking -> connected -> completed, but under specific
circumstances (only the last checked candidate succeeds, and
gathering and the no-more candidates indication both occur prior to
success), the state can transition directly from
"checking
" to
"completed
".
An ICE restart causes candidate gathering and connectivity checks to
begin anew, causing a transition to
"connected
" if begun in the
"completed
" state. If begun in the
transient "disconnected
" state, it causes
a transition to "checking
", effectively
forgetting that connectivity was previously lost.
The "failed
" and
"completed
" states require an indication
that there are no additional remote candidates. This can be
indicated by calling addIceCandidate
with a
candidate value whose candidate
property is set
to an empty string or by
canTrickleIceCandidates
being set to
false
.
Some example state transitions are:
RTCIceTransport
first created, as a result of
setLocalDescription
or
setRemoteDescription
):
"new
"
new
", remote candidates received):
"checking
"
checking
", found usable connection):
"connected
"
checking
", checks fail but gathering
still in progress): "disconnected
"
checking
", gave up):
"failed
"
disconnected
", new local
candidates): "checking
"
connected
", finished all checks):
"completed
"
completed
", lost connectivity):
"disconnected
"
disconnected
" or
"failed
", ICE restart occurs):
"checking
"
completed
", ICE restart occurs):
"connected
"
RTCPeerConnection
.close
()
:
"closed
"
WebIDLenum RTCIceRole
{
"unknown
",
"controlling
",
"controlled
"
};
Enum value | Description |
---|---|
unknown
|
An agent whose role as defined by [RFC5245], Section 3, has not yet been determined. |
controlling
|
A controlling agent as defined by [RFC5245], Section 3. |
controlled
|
A controlled agent as defined by [RFC5245], Section 3. |
WebIDLenum RTCIceComponent
{
"rtp
",
"rtcp
"
};
Enum value | Description |
---|---|
rtp
|
The ICE Transport is used for RTP (or RTCP multiplexing),
as defined in [RFC5245], Section 4.1.1.1. Protocols
multiplexed with RTP (e.g. data channel) share its
component ID. This represents the component-id value 1 when encoded
in candidate-attribute .
|
rtcp
|
The ICE Transport is used for RTCP as defined by [RFC5245],
Section 4.1.1.1. This represents the component-id value 2 when encoded
in candidate-attribute .
|
The track
event uses the RTCTrackEvent
interface.
WebIDL[Exposed=Window]
interface RTCTrackEvent
: Event {
constructor
(DOMString type, RTCTrackEventInit
eventInitDict);
readonly attribute RTCRtpReceiver
receiver
;
readonly attribute MediaStreamTrack track
;
[SameObject] readonly attribute FrozenArray<MediaStream> streams
;
readonly attribute RTCRtpTransceiver
transceiver
;
};
RTCTrackEvent.constructor()
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.
WebIDLdictionary RTCTrackEventInit
: EventInit {
required RTCRtpReceiver
receiver
;
required MediaStreamTrack track
;
sequence<MediaStream> streams
= [];
required RTCRtpTransceiver
transceiver
;
};
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 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.
The Peer-to-peer Data API lets a web application send and receive generic application data peer-to-peer. The API for sending and receiving data models the behavior of Web Sockets.
The Peer-to-peer data API extends the RTCPeerConnection
interface
as described below.
WebIDL partial interface RTCPeerConnection
{
readonly attribute RTCSctpTransport
? sctp
;
RTCDataChannel
createDataChannel
(USVString label,
optional RTCDataChannelInit
dataChannelDict = {});
attribute EventHandler ondatachannel
;
};
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
datachannel
.
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.
Let connection be the RTCPeerConnection
object on which the method is invoked.
If connection.[[IsClosed]]
is
true
, throw an
InvalidStateError
.
Create an RTCDataChannel, channel.
Initialize
channel.[[DataChannelLabel]]
to the
value of the first argument.
If the UTF-8 representation of
[[DataChannelLabel]]
is longer than 65535 bytes,
throw a TypeError
.
Let options be the second argument.
Initialize
channel.[[MaxPacketLifeTime]]
to
option.maxPacketLifeTime
,
if present, otherwise null
.
Initialize channel.[[MaxRetransmits]]
to
option.maxRetransmits
,
if present, otherwise null
.
Initialize channel.[[Ordered]]
to
option.ordered
.
Initialize
channel.[[DataChannelProtocol]]
to
option.protocol
.
If the UTF-8 representation of
[[DataChannelProtocol]]
is longer than 65535
bytes, throw a TypeError
.
Initialize channel.[[Negotiated]]
to
option.negotiated
.
Initialize channel.[[DataChannelId]]
to the value of
option.id
, if it is
present and [[Negotiated]]
is true, otherwise
null
.
If [[Negotiated]]
is true
and
[[DataChannelId]]
is null
, throw a TypeError
.
If both [[MaxPacketLifeTime]]
and
[[MaxRetransmits]]
attributes are set (not null),
throw a TypeError
.
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.
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
.
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 [RFC8832], 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.
[[DataChannelId]]
slot is
null
after this step, it will be populated
during the RTCSctpTransport connected procedure.
Let transport be
connection.[[SctpTransport]]
.
If the [[DataChannelId]]
slot is not
null
, transport is in the
"connected
" state and
[[DataChannelId]]
is greater or equal to
transport.[[MaxChannels]]
, throw an OperationError
.
If channel is the first RTCDataChannel
created on connection, update the negotiation-needed flag for connection.
Return channel and continue the following steps in parallel.
Create channel's associated underlying data transport and configure it according to the relevant properties of channel.
The RTCSctpTransport
interface allows an application access to
information about the SCTP data channels tied to a particular SCTP
association.
To create an RTCSctpTransport
with an initial
state, initialState, run the following steps:
Let transport be a new RTCSctpTransport
object.
Let transport have a [[SctpTransportState]] internal slot initialized to initialState.
Let transport have a [[MaxMessageSize]] internal slot and run the steps labeled update the data max message size to initialize it.
Let transport have a [[MaxChannels]]
internal slot initialized to null
.
Return transport.
To update the data max message size of an
RTCSctpTransport
run the following steps:
Let transport be the RTCSctpTransport
object
to be updated.
Let remoteMaxMessageSize be the value of the
max-message-size
SDP attribute read
from the remote description, as described in [RFC8841]
(section 6), or 65536 if the attribute is missing.
Let canSendSize be the number of bytes that this client can send (i.e. the size of the local send buffer) or 0 if the implementation can handle messages of any size.
If both remoteMaxMessageSize and
canSendSize are 0, set [[MaxMessageSize]]
to the positive Infinity value.
Else, if either remoteMaxMessageSize or
canSendSize is 0, set [[MaxMessageSize]]
to the larger of the two.
Else, set [[MaxMessageSize]]
to the smaller of
remoteMaxMessageSize or canSendSize.
Once an SCTP transport
is connected, meaning the SCTP association of an RTCSctpTransport
has been established, run the following steps:
Let transport be the RTCSctpTransport
object.
Let connection be the RTCPeerConnection
object
associated with transport.
Set [[MaxChannels]]
to the minimum of the negotiated
amount of incoming and outgoing SCTP streams.
For each of connection's RTCDataChannel
:
Let channel be the RTCDataChannel
object.
If channel.[[DataChannelId]]
is
null
, initialize [[DataChannelId]]
to the value generated by the underlying sctp data
channel, according to [RFC8832].
If channel.[[DataChannelId]]
is
greater or equal to
transport.[[MaxChannels]]
, or the
previous step failed to assign an id, close the channel due
to a failure. Otherwise, announce the channel as open.
Fire an event named statechange
at
transport.
This event is fired before the open
events fired by announcing the channel as open;
the open
events are fired from a
queued task.
WebIDL[Exposed=Window]
interface RTCSctpTransport
: EventTarget {
readonly attribute RTCDtlsTransport
transport
;
readonly attribute RTCSctpTransportState
state
;
readonly attribute unrestricted double maxMessageSize
;
readonly attribute unsigned short? maxChannels
;
attribute EventHandler onstatechange
;
};
transport
of type RTCDtlsTransport
, readonly
The transport over which all SCTP packets for data channels will be sent and received.
state
of type RTCSctpTransportState
, readonly
The current state of the SCTP transport. On getting, this
attribute MUST return the value of the
[[SctpTransportState]]
slot.
maxMessageSize
of type unrestricted double, readonly
The maximum size of data that can be passed to
RTCDataChannel
's send
()
method. The
attribute MUST, on getting, return the value of the
[[MaxMessageSize]]
slot.
maxChannels
of type unsigned short , readonly, nullable
The maximum amount of RTCDataChannel
's that can be used
simultaneously. The attribute MUST, on getting, return the
value of the [[MaxChannels]]
slot.
null
until the
SCTP transport goes into the
"connected
" state.
onstatechange
of type EventHandler
The event type of this event handler is
statechange
.
RTCSctpTransportState
indicates the state of the SCTP
transport.
WebIDLenum RTCSctpTransportState
{
"connecting
",
"connected
",
"closed
"
};
Enum value | Description |
---|---|
connecting
|
The |
connected
|
When the negotiation of an association is completed, a
task is queued to update the [[SctpTransportState]] slot
to " |
closed
|
A task is queued to update the [[SctpTransportState]]
slot to "
Note that the last transition is logical due to the fact that an SCTP association requires an established DTLS connection - [RFC8261] section 6.1 specifies that SCTP over DTLS is single-homed - and that no way of of switching to an alternate transport is defined in this API. |
The RTCDataChannel
interface represents a bi-directional data
channel between two peers. An RTCDataChannel
is created via a
factory method on an RTCPeerConnection
object. The messages sent
between the browsers are described in [RFC8831] and
[RFC8832].
There are two ways to establish a connection with RTCDataChannel
.
The first way is to simply create an RTCDataChannel
at one of the
peers with the negotiated
RTCDataChannelInit
dictionary member unset or set to its default
value false. This will announce the new channel in-band and trigger
an RTCDataChannelEvent
with the corresponding RTCDataChannel
object at the other peer. The second way is to let the application
negotiate the RTCDataChannel
. To do this, create an
RTCDataChannel
object with the negotiated
RTCDataChannelInit
dictionary member set to true, and signal
out-of-band (e.g. via a web server) to the other side that it SHOULD
create a corresponding RTCDataChannel
with the
negotiated
RTCDataChannelInit
dictionary
member set to true and the same id
. This will
connect the two separately created RTCDataChannel
objects. The
second way makes it possible to create channels with asymmetric
properties and to create channels in a declarative way by specifying
matching id
s.
Each RTCDataChannel
has an associated underlying data transport that is used to
transport actual data to the other peer. In the case of SCTP data
channels utilizing an RTCSctpTransport
(which represents the
state of the SCTP association), the underlying data transport is the
SCTP stream pair. The transport properties of the underlying data transport, such as in order delivery settings and reliability
mode, are configured by the peer as the channel is created. The
properties of a channel cannot change after the channel has been
created. The actual wire protocol between the peers is specified by
the WebRTC DataChannel Protocol specification [RFC8831].
An RTCDataChannel
can be configured to operate in different
reliability modes. A reliable channel ensures that the data is
delivered at the other peer through retransmissions. An unreliable
channel is configured to either limit the number of retransmissions (
maxRetransmits
) or set a time during which
transmissions (including retransmissions) are allowed (
maxPacketLifeTime
). These properties can not
be used simultaneously and an attempt to do so will result in an
error. Not setting any of these properties results in a reliable
channel.
An RTCDataChannel
, created with
createDataChannel
or dispatched via an
RTCDataChannelEvent
, MUST initially be in the
"connecting
" state. When the
RTCDataChannel
object's underlying data transport is ready,
the user agent MUST announce the RTCDataChannel as open.
To create an RTCDataChannel
, run the following
steps:
Let channel be a newly created RTCDataChannel
object.
Let channel have a [[ReadyState]]
internal slot initialized to
"connecting
".
Let channel have a [[BufferedAmount]]
internal slot initialized to 0
.
Let channel have internal slots named [[DataChannelLabel]], [[Ordered]], [[MaxPacketLifeTime]], [[MaxRetransmits]], [[DataChannelProtocol]], [[Negotiated]], and [[DataChannelId]].
Return channel.
When the user agent is to announce an RTCDataChannel
as
open, the user agent MUST queue a task to run the following
steps:
If the associated RTCPeerConnection
object's
[[IsClosed]]
slot is true
, abort these
steps.
Let channel be the RTCDataChannel
object to be
announced.
If channel.[[ReadyState]]
is
"closing
" or
"closed
", abort these steps.
Set channel.[[ReadyState]]
to
"open
".
Fire an event named open
at channel.
When an underlying data transport is to be announced (the
other peer created a channel with negotiated
unset or set to false), the user agent of the peer that did not
initiate the creation process MUST queue a task to run the
following steps:
Let connection be the RTCPeerConnection
object
associated with the underlying data transport.
If connection.[[IsClosed]]
is
true
, abort these steps.
Create an RTCDataChannel, channel.
Let configuration be an information bundle received from the other peer as a part of the process to establish the underlying data transport described by the WebRTC DataChannel Protocol specification [RFC8832].
Initialize channel.[[DataChannelLabel]]
,
[[Ordered]]
, [[MaxPacketLifeTime]]
,
[[MaxRetransmits]]
, [[DataChannelProtocol]]
,
and [[DataChannelId]]
internal slots to the
corresponding values in configuration.
Initialize channel.[[Negotiated]]
to
false
.
Set channel.[[ReadyState]]
to
"open
" (but do not fire the open
event, yet).
datachannel
event handler prior to the open
event being
fired.
Fire an event named datachannel
using the
RTCDataChannelEvent
interface with the
channel
attribute set to
channel at connection.
An RTCDataChannel
object's underlying data transport may
be torn down in a non-abrupt manner by running the closing procedure. When
that happens the user agent MUST queue a task to run the following
steps:
Let channel be the RTCDataChannel
object whose
underlying data transport was closed.
Unless the procedure was initiated by
channel.close
, set
channel.[[ReadyState]]
to
"closing
" and fire an event named
closing
at channel.
Run the following steps in parallel:
Finish sending all currently pending messages of the channel.
Follow the closing procedure defined for the channel's underlying data transport :
Close the channel's data transport by following the associated procedure.
When an RTCDataChannel
object's underlying data transport
has been closed, the user agent MUST queue a task to run the
following steps:
Let channel be the RTCDataChannel
object whose
underlying data transport was closed.
[[ReadyState]]
is
"closed
", abort these steps.
Set channel.[[ReadyState]]
to
"closed
".
If the transport was closed
with an error, fire an event named error
using the RTCErrorEvent
interface with its errorDetail
attribute set to
"sctp-failure
" at channel.
Fire an event named close at channel.
In some cases, the user agent may be unable to create an
RTCDataChannel
's underlying data transport. For
example, the data channel's id
may be outside
the range negotiated by the [RFC8831] implementations in the
SCTP handshake. When the user agent determines that an
RTCDataChannel
's underlying data transport cannot be
created, the user agent MUST queue a task to run the following
steps:
Let channel be the RTCDataChannel
object for
which the user agent could not create an underlying data transport.
Set channel.[[ReadyState]]
to
"closed
".
Fire an event named error
using the
RTCErrorEvent
interface with the errorDetail
attribute set to "data-channel-failure
"
at channel.
Fire an event named close at channel.
When an RTCDataChannel
message has
been received via the underlying data transport with
type type and data rawData, the user agent
MUST queue a task to run the following steps:
Let channel be the RTCDataChannel
object for
which the user agent has received a message.
Let connection be the RTCPeerConnection
object
associated with channel.
If channel.[[ReadyState]]
is not
"open
", abort these steps and discard
rawData.
Execute the sub step by switching on type and
channel.binaryType
:
If type indicates that rawData is a
string
:
Let data be a DOMString that represents the result of decoding rawData as UTF-8.
If type indicates that rawData is
binary and binaryType
is "blob"
:
Let data be a new Blob
object containing
rawData as its raw data source.
If type indicates that rawData is
binary and binaryType
is "arraybuffer"
:
Let data be a new ArrayBuffer
object
containing rawData as its raw data source.
Fire an event named message
using the
MessageEvent
interface with its origin
attribute initialized to the
serialization of an origin of
connection.[[DocumentOrigin]]
, and the
data
attribute initialized to
data at channel.
WebIDL[Exposed=Window]
interface RTCDataChannel
: EventTarget {
readonly attribute USVString label
;
readonly attribute boolean ordered
;
readonly attribute unsigned short? maxPacketLifeTime
;
readonly attribute unsigned short? maxRetransmits
;
readonly attribute USVString protocol
;
readonly attribute boolean negotiated
;
readonly attribute unsigned short? id
;
readonly attribute RTCDataChannelState
readyState
;
readonly attribute unsigned long bufferedAmount
;
[EnforceRange] attribute unsigned long bufferedAmountLowThreshold
;
attribute EventHandler onopen
;
attribute EventHandler onbufferedamountlow
;
attribute EventHandler onerror
;
attribute EventHandler onclosing
;
attribute EventHandler onclose
;
undefined close
();
attribute EventHandler onmessage
;
attribute BinaryType binaryType
;
undefined send
(USVString data);
undefined send
(Blob data);
undefined send
(ArrayBuffer data);
undefined send
(ArrayBufferView data);
};
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
[[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 [[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
[[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
[[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
[[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 [[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
[[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 [[ReadyState]]
slot.
bufferedAmount
of type unsigned long,
readonly
The bufferedAmount
attribute MUST, on getting, return the
value of the [[BufferedAmount]]
slot. The attribute
exposes the number of bytes of application data (UTF-8 text
and binary data) that have been queued using
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
[[BufferedAmount]]
slot will only increase with each
call to the send
()
method as long as the
[[ReadyState]]
slot is
"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 [[BufferedAmount]]
with the number of bytes that was sent.
bufferedAmountLowThreshold
of type
unsigned long
The bufferedAmountLowThreshold
attribute sets the
threshold at which the bufferedAmount
is
considered to be low. When the
bufferedAmount
decreases from above this
threshold to equal or below it, the bufferedamountlow
event fires. The
bufferedAmountLowThreshold
is initially
zero on each new RTCDataChannel
, but the application may
change its value at any time.
onopen
of type EventHandler
open
.
onbufferedamountlow
of type EventHandler
bufferedamountlow
.
onerror
of type EventHandler
The event type of this event handler is RTCErrorEvent
.
errorDetail
contains "sctp-failure",
sctpCauseCode
contains the SCTP Cause Code
value, and message
contains the SCTP
Cause-Specific-Information, possibly with additional text.
onclosing
of type EventHandler
The event type of this event handler is 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 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, throw a SyntaxError
. When an
RTCDataChannel
object is created, the
binaryType
attribute MUST be initialized
to the string "blob"
.
This attribute controls how binary data is exposed to
scripts. See Web Socket's binaryType
.
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:
Let channel be the RTCDataChannel
object
which is about to be closed.
If channel.[[ReadyState]]
is
"closing
" or
"closed
", then abort these steps.
Set channel.[[ReadyState]]
to
"closing
".
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:
Let channel be the RTCDataChannel
object on
which data is to be sent.
If channel.[[ReadyState]]
is not
"open
", throw an
InvalidStateError
.
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.
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.
TypeError
. This includes
null
and undefined
.
If the byte size of data exceeds the value of
maxMessageSize
on channel's
associated RTCSctpTransport
, throw a
TypeError
.
Queue data for transmission on
channel's underlying data transport. If
queuing data is not possible because not enough
buffer space is available, throw an
OperationError
.
onerror
.
Increase the value of the [[BufferedAmount]]
slot by
the byte size of data.
WebIDLdictionary RTCDataChannelInit
{
boolean ordered
= true;
[EnforceRange] unsigned short maxPacketLifeTime
;
[EnforceRange] unsigned short maxRetransmits
;
USVString protocol
= "";
boolean negotiated
= false;
[EnforceRange] unsigned short id
;
};
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
id
at the other peer.
id
of type unsigned short
Sets the channel ID when negotiated
is
true. Ignored when negotiated
is
false.
WebIDLenum RTCDataChannelState
{
"connecting
",
"open
",
"closing
",
"closed
"
};
Enum value | Description |
---|---|
connecting
|
The user agent is attempting to establish the underlying data transport. This is the initial state of an
|
open
|
The underlying data transport is established and communication is possible. |
closing
|
The procedure to close down the underlying data transport has started. |
closed
|
The underlying data transport has been |
The datachannel
event uses the RTCDataChannelEvent
interface.
WebIDL[Exposed=Window]
interface RTCDataChannelEvent
: Event {
constructor
(DOMString type, RTCDataChannelEventInit
eventInitDict);
readonly attribute RTCDataChannel
channel
;
};
RTCDataChannelEvent.constructor()
channel
of type
RTCDataChannel
, readonly
The channel
attribute represents the RTCDataChannel
object associated with the event.
WebIDLdictionary RTCDataChannelEventInit
: EventInit {
required RTCDataChannel
channel
;
};
channel
of type RTCDataChannel
, required
The RTCDataChannel
object to be announced by the event.
An RTCDataChannel
object MUST not be garbage collected if its
[[ReadyState]]
slot is
"connecting
" and at least one event
listener is registered for open
events, message
events,
error
events, closing
events, or close events.
[[ReadyState]]
slot is "open
" and
at least one event listener is registered for
message
events, error
events, closing
events, or
close events.
[[ReadyState]]
slot is "closing
"
and at least one event listener is registered for
error
events, or close
events.
underlying data transport is established and data is queued to be transmitted.
This section describes an interface on RTCRtpSender
to send DTMF
(phone keypad) values across an RTCPeerConnection
. Details of how
DTMF is sent to the other peer are described in [RFC7874].
The Peer-to-peer DTMF API extends the RTCRtpSender
interface as
described below.
WebIDL partial interface RTCRtpSender
{
readonly attribute RTCDTMFSender
? dtmf
;
};
dtmf
of type RTCDTMFSender
, readonly, nullable
On getting, the dtmf
attribute returns the value of the
[[Dtmf]]
internal slot, which represents a
RTCDTMFSender
which can be used to send DTMF, or
null
if unset. The [[Dtmf]]
internal
slot is set when the kind of an RTCRtpSender
's
[[SenderTrack]]
is "audio"
.
To create an RTCDTMFSender, the user agent MUST run the following steps:
Let dtmf be a newly created RTCDTMFSender
object.
Let dtmf have a [[Duration]] internal slot.
Let dtmf have a [[InterToneGap]] internal slot.
Let dtmf have a [[ToneBuffer]] internal slot.
WebIDL[Exposed=Window]
interface RTCDTMFSender
: EventTarget {
undefined insertDTMF
(DOMString tones, optional unsigned long duration = 100, optional unsigned long interToneGap = 70);
attribute EventHandler ontonechange
;
readonly attribute boolean canInsertDTMF
;
readonly attribute DOMString toneBuffer
;
};
ontonechange
of type EventHandler
The event type of this event handler is 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
.
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:
RTCRtpSender
used to send DTMF.
Let transceiver be the RTCRtpTransceiver
object associated with sender.
RTCDTMFSender
associated with sender.
false
, throw an InvalidStateError
.
unrecognized
characters, throw an InvalidCharacterError
.
[[ToneBuffer]]
slot to
tones.
[[Duration]]
to the value of
duration.
[[InterToneGap]]
to the value
of interToneGap.
[[Duration]]
to 40 ms.
[[Duration]]
to 6000 ms.
[[InterToneGap]]
to 30 ms.
[[InterToneGap]]
to 6000 ms.
[[CurrentDirection]]
is
neither "sendrecv
" nor
"sendonly
", abort these
steps.
[[ToneBuffer]]
slot contains the empty
string, fire an event named tonechange
using
the RTCDTMFToneChangeEvent
interface with the
tone
attribute set to an empty
string at the RTCDTMFSender
object and abort these
steps.
[[ToneBuffer]]
slot and let that character be
tone.
","
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.
","
start
playout of tone for [[Duration]]
ms on
the associated RTP media stream, using the appropriate
codec, then queue a task to be executed in
[[Duration]]
+ [[InterToneGap]]
ms from
now that runs the steps labelled Playout task.
tonechange
using the
RTCDTMFToneChangeEvent
interface with the
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 [[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.
To determine if DTMF can be sent for an
instance dtmfSender, the user agent MUST queue a task that
runs the following steps:
RTCDTMFSender
To determine if DTMF can be sent for an RTCDTMFSender
instance dtmfSender, the user agent MUST run the following
steps:
RTCRtpSender
associated with dtmfSender.
RTCRtpTransceiver
associated with sender.
RTCPeerConnection
associated with transceiver.
RTCPeerConnectionState
is not
"connected
" return false
.
[[SenderTrack]]
is null
return false
.
[[CurrentDirection]]
is neither
"sendrecv
" nor
"sendonly
" return false
.
[[SendEncodings]]
[0]
.active
is false
return false
.
"audio/telephone-event"
has been negotiated for sending
with this sender, return false
.
true
.
The tonechange
event uses the RTCDTMFToneChangeEvent
interface.
WebIDL[Exposed=Window]
interface RTCDTMFToneChangeEvent
: Event {
constructor
(DOMString type, optional RTCDTMFToneChangeEventInit
eventInitDict = {});
readonly attribute DOMString tone
;
};
RTCDTMFToneChangeEvent.constructor()
tone
of type DOMString, readonly
The tone
attribute contains the character for the tone
(including ","
) that has just begun playout (see
insertDTMF
). If the value is the empty
string, it indicates that the [[ToneBuffer]]
slot is
an empty string and that the previous tones have completed
playback.
WebIDL dictionary RTCDTMFToneChangeEventInit
: EventInit {
DOMString tone
= "";
};
tone
of type DOMString, defaulting to ""
The tone
attribute contains the character for the tone
(including ","
) that has just begun playout (see
insertDTMF
). If the value is the empty
string, it indicates that the [[ToneBuffer]]
slot is
an empty string and that the previous tones have completed
playback.
The basic statistics model is that the browser maintains a set of statistics for monitored objects, in the form of stats objects.
A group of related objects may be referenced by a selector. The selector may, for example, be a
MediaStreamTrack
. For a track to be a valid selector, it MUST be
a MediaStreamTrack
that is sent or received by the
RTCPeerConnection
object on which the stats request was issued.
The calling Web application provides the selector to the
getStats
()
method and the browser emits (in the
JavaScript) a set of statistics that are relevant to the selector,
according to the stats selection algorithm. Note that that
algorithm takes the sender or receiver of a selector.
The statistics returned in stats objects are designed in such a
way that repeated queries can be linked by the RTCStats
id
dictionary member. Thus, a Web application can make
measurements over a given time period by requesting measurements at
the beginning and end of that period.
With a few exceptions, monitored objects, once created, exist
for the duration of their associated RTCPeerConnection
. This
ensures statistics from them are available in the result from
getStats
()
even past the associated peer
connection being close
d.
Only a few monitored objects have shorter lifetimes. Statistics from these objects are no longer available in subsequent getStats() results. The object descriptions in [WEBRTC-STATS] describe when these monitored objects are deleted.
The Statistics API extends the RTCPeerConnection
interface as
described below.
WebIDL partial interface RTCPeerConnection
{
Promise<RTCStatsReport
> getStats
(optional MediaStreamTrack? selector = null);
};
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:
Let selectorArg be the method's first argument.
Let connection be the RTCPeerConnection
object on which the method was invoked.
If selectorArg is null
, let
selector be null
.
If selectorArg is a MediaStreamTrack
let
selector be an RTCRtpSender
or
RTCRtpReceiver
on connection which
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 created InvalidAccessError
.
Let p be a new promise.
Run the following steps in parallel:
Gather the stats indicated by selector according to the stats selection algorithm.
Resolve p with the resulting
RTCStatsReport
object, containing the gathered
stats.
Return p.
The getStats
()
method delivers a successful
result in the form of an RTCStatsReport
object. An
RTCStatsReport
object is a map between strings that identify the
inspected objects (id
attribute in RTCStats
instances), and their corresponding RTCStats
-derived
dictionaries.
An RTCStatsReport
may be composed of several RTCStats
-derived
dictionaries, each reporting stats for one underlying object that the
implementation thinks is relevant for the selector. One
achieves the total for the selector by summing over all the
stats of a certain type; for instance, if an RTCRtpSender
uses
multiple SSRCs to carry its track over the network, the
RTCStatsReport
may contain one RTCStats
-derived dictionary
per SSRC (which can be distinguished by the value of the
ssrc
stats attribute).
WebIDL[Exposed=Window]
interface RTCStatsReport
{
readonly maplike<DOMString, object>;
};
Use these to retrieve the various dictionaries descended from
RTCStats
that this stats report is composed of. The set of
supported property names [WEBIDL] is defined as the ids of all
the RTCStats
-derived dictionaries that have been generated for
this stats report.
An RTCStats
dictionary represents the stats object
constructed by inspecting a specific monitored object. The
RTCStats
dictionary is a base type that specifies as set of
default attributes, such as timestamp
and
type
. Specific stats are added by extending the
RTCStats
dictionary.
Note that while stats names are standardized, any given implementation may be using experimental values or values not yet known to the Web application. Thus, applications MUST be prepared to deal with unknown stats.
Statistics need to be synchronized with each other in order to yield
reasonable values in computation; for instance, if
bytesSent
and
packetsSent
are both reported, they both
need to be reported over the same interval, so that "average packet
size" can be computed as "bytes / packets" - if the intervals are
different, this will yield errors. Thus implementations MUST return
synchronized values for all stats in an RTCStats
-derived
dictionary.
WebIDLdictionary RTCStats
{
required DOMHighResTimeStamp timestamp
;
required RTCStatsType type
;
required DOMString id
;
};
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.
The set of valid values for RTCStatsType
, and the dictionaries
derived from RTCStats that they indicate, are documented in
[WEBRTC-STATS].
The stats selection algorithm is as follows:
RTCStatsReport
.
null
,
gather stats for the whole connection, add them to
result, return result, and abort these steps.
RTCRtpSender
, gather stats for and
add the following objects to result:
RTCOutboundRtpStreamStats
objects representing RTP
streams being sent by selector.
RTCOutboundRtpStreamStats
objects added.
RTCRtpReceiver
, gather stats for and
add the following objects to result:
RTCInboundRtpStreamStats
objects representing RTP
streams being received by selector.
RTCInboundRtpStreamStats
added.
The stats listed in [WEBRTC-STATS] are intended to cover a wide range of use cases. Not all of them have to be implemented by every WebRTC implementation.
An implementation MUST support generating statistics of the following
type
s when the corresponding objects exist on a
RTCPeerConnection
, with the fields that are listed when they are
valid for that object in addition to the generic fields defined in
the RTCStats
dictionary:
An implementation MAY support generating any other statistic defined in [WEBRTC-STATS], and MAY generate statistics that are not documented.
Consider the case where the user is experiencing bad sound and the application wants to determine if the cause of it is packet loss. The following example code might be used:
async function gatherStats(pc) {
try {
const [sender] = pc.getSenders();
const baselineReport = await sender.getStats();
await new Promise(resolve => setTimeout(resolve, aBit)); // wait a bit
const currentReport = await sender.getStats();
// compare the elements from the current report with the baseline
for (const now of currentReport.values()) {
if (now.type != 'outbound-rtp') continue;
// get the corresponding stats from the baseline report
const base = baselineReport.get(now.id);
if (!base) continue;
const remoteNow = currentReport.get(now.remoteId);
const remoteBase = baselineReport.get(base.remoteId);
const packetsSent = now.packetsSent - base.packetsSent;
const packetsReceived = remoteNow.packetsReceived -
remoteBase.packetsReceived;
const fractionLost = (packetsSent - packetsReceived) / packetsSent;
if (fractionLost > 0.3) {
// if fractionLost is > 0.3, we have probably found the culprit
}
}
} catch (err) {
console.error(err);
}
}
The MediaStreamTrack
interface, as defined in the
[GETUSERMEDIA] specification, typically represents a stream of
data of audio or video. One or more MediaStreamTrack
s can be
collected in a MediaStream
(strictly speaking, a MediaStream
as defined in [GETUSERMEDIA] may contain zero or more
MediaStreamTrack
objects).
A MediaStreamTrack
may be extended to represent a media flow that
either comes from or is sent to a remote peer (and not just the local
camera, for instance). The extensions required to enable this
capability on the MediaStreamTrack
object will be described in
this section. How the media is transmitted to the peer is described
in [RFC8834], [RFC7874], and [RFC8835].
A MediaStreamTrack
sent to another peer will appear as one and
only one MediaStreamTrack
to the recipient. A peer is defined as
a user agent that supports this specification. In addition, the
sending side application can indicate what MediaStream
object(s)
the MediaStreamTrack
is a member of. The corresponding
MediaStream
object(s) on the receiver side will be created (if
not already present) and populated accordingly.
As also described earlier in this document, the objects
RTCRtpSender
and RTCRtpReceiver
can be used by the
application to get more fine grained control over the transmission
and reception of MediaStreamTrack
s.
Channels are the smallest unit considered in the Media Capture and
Streams specification. Channels are intended to be encoded together
for transmission as, for instance, an RTP payload type. All of the
channels that a codec needs to encode jointly MUST be in the same
MediaStreamTrack
and the codecs SHOULD be able to encode, or
discard, all the channels in the track.
The concepts of an input and output to a given MediaStreamTrack
apply in the case of MediaStreamTrack
objects transmitted over
the network as well. A MediaStreamTrack
created by an
RTCPeerConnection
object (as described previously in this
document) will take as input the data received from a remote peer.
Similarly, a MediaStreamTrack
from a local source, for instance a
camera via [GETUSERMEDIA], will have an output that represents
what is transmitted to a remote peer if the object is used with an
RTCPeerConnection
object.
The concept of duplicating MediaStream
and MediaStreamTrack
objects as described in [GETUSERMEDIA] is also applicable here.
This feature can be used, for instance, in a video-conferencing
scenario to display the local video from the user's camera and
microphone in a local monitor, while only transmitting the audio to
the remote peer (e.g. in response to the user using a "video mute"
feature). Combining different MediaStreamTrack
objects into new
MediaStream
objects is useful in certain situations.
In this document, we only specify aspects of the following objects
that are relevant when used along with an RTCPeerConnection
.
Please refer to the original definitions of the objects in the
[GETUSERMEDIA] document for general information on using
MediaStream
and MediaStreamTrack
.
The id
attribute specified in MediaStream
returns an id that is unique to this stream, so that streams can be
recognized at the remote end of the RTCPeerConnection
API.
When a MediaStream
is created to represent a stream obtained
from a remote peer, the id
attribute is initialized
from information provided by the remote source.
The id
of a MediaStream
object is unique to the
source of the stream, but that does not mean it is not possible to
end up with duplicates. For example, the tracks of a locally
generated stream could be sent from one user agent to a remote peer
using RTCPeerConnection
and then sent back to the original user
agent in the same manner, in which case the original user agent
will have multiple streams with the same id (the locally-generated
one and the one received from the remote peer).
A MediaStreamTrack
object's reference to its MediaStream
in
the non-local media source case (an RTP source, as is the case for
each MediaStreamTrack
associated with an RTCRtpReceiver
) is
always strong.
Whenever an RTCRtpReceiver
receives data on an RTP source whose
corresponding MediaStreamTrack
is muted, but not ended, and the
[[Receptive]]
slot of the RTCRtpTransceiver
object the
RTCRtpReceiver
is a member of is true
, it MUST queue
a task to set the muted state of the corresponding
MediaStreamTrack
to false
.
When one of the SSRCs for RTP source media streams received by an
RTCRtpReceiver
is removed either due to reception of a BYE or via
timeout, it MUST queue a task to set the muted state of the
corresponding MediaStreamTrack
to true
. Note that
setRemoteDescription
can also lead to the setting of the muted state of the
track
to the value true
.
The procedures add a track, remove a track and set a track's muted state are specified in [GETUSERMEDIA].
When a MediaStreamTrack
track produced by an RTCRtpReceiver
receiver has ended
[GETUSERMEDIA] (such as via a call to
receiver.track
.stop
), the user agent MAY choose to free resources
allocated for the incoming stream, by for instance turning off the
decoder of receiver.
The concept of constraints and constrainable properties, including
MediaTrackConstraints
(MediaStreamTrack
.getConstraints()
, MediaStreamTrack
.applyConstraints()
), and MediaTrackSettings
(MediaStreamTrack
.getSettings()
) are
outlined in [GETUSERMEDIA]. However, the constrainable
properties of tracks sourced from a peer connection are different
than those sourced by getUserMedia()
; the
constraints and settings applicable to MediaStreamTrack
s
sourced from a remote source are defined here. The settings
of a remote track represent the latest frame received.
MediaStreamTrack
.getCapabilities()
MUST always return the empty set and
MediaStreamTrack
.applyConstraints()
MUST always reject with OverconstrainedError
on remote tracks for constraints
defined here.
The following constrainable properties are defined to apply to
video MediaStreamTrack
s sourced from a remote source:
Property Name | Values | Notes |
---|---|---|
width |
ConstrainULong
|
As a setting, this is the width, in pixels, of the latest frame received. |
height |
ConstrainULong
|
As a setting, this is the height, in pixels, of the latest frame received. |
frameRate |
ConstrainDouble
|
As a setting, this is an estimate of the frame rate based on recently received frames. |
aspectRatio |
ConstrainDouble
|
As a setting, this is the aspect ratio of the latest frame; this is the width in pixels divided by height in pixels as a double rounded to the tenth decimal place. |
This document does not define any constrainable properties to apply
to audio MediaStreamTrack
s sourced from a remote source.
This section is non-normative.
When two peers decide they are going to set up a connection to each other, they both go through these steps. The STUN/TURN server configuration describes a server they can use to get things like their public IP address or to set up NAT traversal. They also have to send data for the signaling channel to each other using the same out-of-band mechanism they used to establish that they were going to communicate in the first place.
const signaling = new SignalingChannel(); // handles JSON.stringify/parse
const constraints = {audio: true, video: true};
const configuration = {iceServers: [{urls: 'stun:stun.example.org'}]};
const pc = new RTCPeerConnection(configuration);
// send any ice candidates to the other peer
pc.onicecandidate = ({candidate}) => signaling.send({candidate});
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
try {
await pc.setLocalDescription();
// send the offer to the other peer
signaling.send({description: pc.localDescription});
} catch (err) {
console.error(err);
}
};
pc.ontrack = ({track, streams}) => {
// once media for a remote track arrives, show it in the remote video element
track.onunmute = () => {
// don't set srcObject again if it is already set.
if (remoteView.srcObject) return;
remoteView.srcObject = streams[0];
};
};
// call start() to initiate
function start() {
addCameraMic();
}
// add camera and microphone to connection
async function addCameraMic() {
try {
// get a local stream, show it in a self-view and add it to be sent
const stream = await navigator.mediaDevices.getUserMedia(constraints);
for (const track of stream.getTracks()) {
pc.addTrack(track, stream);
}
selfView.srcObject = stream;
} catch (err) {
console.error(err);
}
}
signaling.onmessage = async ({data: {description, candidate}}) => {
try {
if (description) {
await pc.setRemoteDescription(description);
// if we got an offer, we need to reply with an answer
if (description.type == 'offer') {
if (!selfView.srcObject) {
// blocks negotiation on permission (not recommended in production code)
await addCameraMic();
}
await pc.setLocalDescription();
signaling.send({description: pc.localDescription});
}
} else if (candidate) {
await pc.addIceCandidate(candidate);
}
} catch (err) {
console.error(err);
}
};
When two peers decide they are going to set up a connection to each other and want to have the ICE, DTLS, and media connections "warmed up" such that they are ready to send and receive media immediately, they both go through these steps.
const signaling = new SignalingChannel(); // handles JSON.stringify/parse
const constraints = {audio: true, video: true};
const configuration = {iceServers: [{urls: 'stun:stun.example.org'}]};
let pc;
let audio;
let video;
let started = false;
// Call warmup() before media is ready, to warm-up ICE, DTLS, and media.
async function warmup(isAnswerer) {
pc = new RTCPeerConnection(configuration);
if (!isAnswerer) {
audio = pc.addTransceiver('audio');
video = pc.addTransceiver('video');
}
// send any ice candidates to the other peer
pc.onicecandidate = ({candidate}) => signaling.send({candidate});
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
try {
await pc.setLocalDescription();
// send the offer to the other peer
signaling.send({description: pc.localDescription});
} catch (err) {
console.error(err);
}
};
pc.ontrack = async ({track, transceiver}) => {
try {
// once media for the remote track arrives, show it in the video element
event.track.onunmute = () => {
// don't set srcObject again if it is already set.
if (!remoteView.srcObject) {
remoteView.srcObject = new MediaStream();
}
remoteView.srcObject.addTrack(track);
}
if (isAnswerer) {
if (track.kind == 'audio') {
audio = transceiver;
} else if (track.kind == 'video') {
video = transceiver;
}
if (started) await addCameraMicWarmedUp();
}
} catch (err) {
console.error(err);
}
};
try {
// get a local stream, show it in a self-view and add it to be sent
selfView.srcObject = await navigator.mediaDevices.getUserMedia(constraints);
if (started) await addCameraMicWarmedUp();
} catch (err) {
console.error(err);
}
}
// call start() after warmup() to begin transmitting media from both ends
function start() {
signaling.send({start: true});
signaling.onmessage({data: {start: true}});
}
// add camera and microphone to already warmed-up connection
async function addCameraMicWarmedUp() {
const stream = selfView.srcObject;
if (audio && video && stream) {
await Promise.all([
audio.sender.replaceTrack(stream.getAudioTracks()[0]),
video.sender.replaceTrack(stream.getVideoTracks()[0]),
]);
}
}
signaling.onmessage = async ({data: {start, description, candidate}}) => {
if (!pc) warmup(true);
try {
if (start) {
started = true;
await addCameraMicWarmedUp();
} else if (description) {
await pc.setRemoteDescription(description);
// if we got an offer, we need to reply with an answer
if (description.type == 'offer') {
await pc.setLocalDescription();
signaling.send({description: pc.localDescription});
}
} else {
await pc.addIceCandidate(candidate);
}
} catch (err) {
console.error(err);
}
};
A client wants to send multiple RTP encodings (simulcast) to a server.
const signaling = new SignalingChannel(); // handles JSON.stringify/parse
const constraints = {audio: true, video: true};
const configuration = {'iceServers': [{'urls': 'stun:stun.example.org'}]};
let pc;
// call start() to initiate
async function start() {
pc = new RTCPeerConnection(configuration);
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
try {
await pc.setLocalDescription();
// send the offer to the other peer
signaling.send({description: pc.localDescription});
} catch (err) {
console.error(err);
}
};
try {
// get a local stream, show it in a self-view and add it to be sent
const stream = await navigator.mediaDevices.getUserMedia(constraints);
selfView.srcObject = stream;
pc.addTransceiver(stream.getAudioTracks()[0], {direction: 'sendonly'});
pc.addTransceiver(stream.getVideoTracks()[0], {
direction: 'sendonly',
sendEncodings: [
{rid: 'q', scaleResolutionDownBy: 4.0}
{rid: 'h', scaleResolutionDownBy: 2.0},
{rid: 'f'},
]
});
} catch (err) {
console.error(err);
}
}
signaling.onmessage = async ({data: {description, candidate}}) => {
try {
if (description) {
await pc.setRemoteDescription(description);
// if we got an offer, we need to reply with an answer
if (description.type == 'offer') {
await pc.setLocalDescription();
signaling.send({description: pc.localDescription});
}
} else if (candidate) {
await pc.addIceCandidate(candidate);
}
} catch (err) {
console.error(err);
}
};
This example shows how to create an RTCDataChannel
object and
perform the offer/answer exchange required to connect the channel
to the other peer. The RTCDataChannel
is used in the context of
a simple chat application using an input
field for
user input.
const signaling = new SignalingChannel(); // handles JSON.stringify/parse
const configuration = {iceServers: [{urls: 'stun:stun.example.org'}]};
let pc, channel;
// call start() to initiate
function start() {
pc = new RTCPeerConnection(configuration);
// send any ice candidates to the other peer
pc.onicecandidate = ({candidate}) => signaling.send({candidate});
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
try {
await pc.setLocalDescription();
// send the offer to the other peer
signaling.send({description: pc.localDescription});
} catch (err) {
console.error(err);
}
};
// create data channel and setup chat using "negotiated" pattern
channel = pc.createDataChannel('chat', {negotiated: true, id: 0});
channel.onopen = () => input.disabled = false;
channel.onmessage = ({data}) => showChatMessage(data);
input.onkeydown = ({key}) => {
if (key != 'Enter') return;
channel.send(input.value);
}
}
signaling.onmessage = async ({data: {description, candidate}}) => {
if (!pc) start();
try {
if (description) {
await pc.setRemoteDescription(description);
// if we got an offer, we need to reply with an answer
if (description.type == 'offer') {
await pc.setLocalDescription();
signaling.send({description: pc.localDescription});
}
} else if (candidate) {
await pc.addIceCandidate(candidate);
}
} catch (err) {
console.error(err);
}
};
This shows an example of one possible call flow between two browsers. This does not show the procedure to get access to local media or every callback that gets fired but instead tries to reduce it down to only show the key events and messages.
Examples assume that sender is an RTCRtpSender
.
Sending the DTMF signal "1234" with 500 ms duration per tone:
if (sender.dtmf.canInsertDTMF) {
const duration = 500;
sender.dtmf.insertDTMF('1234', duration);
} else {
console.log('DTMF function not available');
}
Send the DTMF signal "123" and abort after sending "2".
async function sendDTMF() {
if (sender.dtmf.canInsertDTMF) {
sender.dtmf.insertDTMF('123');
await new Promise(r => sender.dtmf.ontonechange = e => e.tone == '2' && r());
// empty the buffer to not play any tone after "2"
sender.dtmf.insertDTMF('');
} else {
console.log('DTMF function not available');
}
}
Send the DTMF signal "1234", and light up the active key using
lightKey(key)
while the tone is playing
(assuming that lightKey("")
will darken
all the keys):
const wait = ms => new Promise(resolve => setTimeout(resolve, ms));
if (sender.dtmf.canInsertDTMF) {
const duration = 500; // ms
sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '1234', duration);
sender.dtmf.ontonechange = async ({tone}) => {
if (!tone) return;
lightKey(tone); // light up the key when playout starts
await wait(duration);
lightKey(''); // turn off the light after tone duration
};
} else {
console.log('DTMF function not available');
}
It is always safe to append to the tone buffer. This example appends before any tone playout has started as well as during playout.
if (sender.dtmf.canInsertDTMF) {
sender.dtmf.insertDTMF('123');
// append more tones to the tone buffer before playout has begun
sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '456');
sender.dtmf.ontonechange = ({tone}) => {
// append more tones when playout has begun
if (tone != '1') return;
sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '789');
};
} else {
console.log('DTMF function not available');
}
Send a 1-second "1" tone followed by a 2-second "2" tone:
if (sender.dtmf.canInsertDTMF) {
sender.dtmf.ontonechange = ({tone}) => {
if (tone == '1') {
sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '2', 2000);
}
};
sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '1', 1000);
} else {
console.log('DTMF function not available');
}
Perfect negotiation is a recommended pattern to manage negotiation
transparently, abstracting this asymmetric task away from the rest of
an application. This pattern has advantages over one side always
being the offerer, as it lets applications operate on both peer
connection objects simultaneously without risk of glare (an offer
coming in outside of "stable
" state). The rest
of the application may use any and all modification methods and
attributes, without worrying about signaling state races.
It designates different roles to the two peers, with behavior to resolve signaling collisions between them:
The polite peer uses rollback to avoid collision with an incoming offer.
The impolite peer ignores an incoming offer when this would collide with its own.
Together, they manage signaling for the rest of the application in a manner that doesn't deadlock. The example assumes a polite boolean variable indicating the designated role:
const signaling = new SignalingChannel(); // handles JSON.stringify/parse
const constraints = {audio: true, video: true};
const configuration = {iceServers: [{urls: 'stun:stun.example.org'}]};
const pc = new RTCPeerConnection(configuration);
// call start() anytime on either end to add camera and microphone to connection
async function start() {
try {
const stream = await navigator.mediaDevices.getUserMedia(constraints);
for (const track of stream.getTracks()) {
pc.addTrack(track, stream);
}
selfView.srcObject = stream;
} catch (err) {
console.error(err);
}
}
pc.ontrack = ({track, streams}) => {
// once media for a remote track arrives, show it in the remote video element
track.onunmute = () => {
// don't set srcObject again if it is already set.
if (remoteView.srcObject) return;
remoteView.srcObject = streams[0];
};
};
// - The perfect negotiation logic, separated from the rest of the application ---
// keep track of some negotiation state to prevent races and errors
let makingOffer = false;
let ignoreOffer = false;
let isSettingRemoteAnswerPending = false;
// send any ice candidates to the other peer
pc.onicecandidate = ({candidate}) => signaling.send({candidate});
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
try {
makingOffer = true;
await pc.setLocalDescription();
signaling.send({description: pc.localDescription});
} catch (err) {
console.error(err);
} finally {
makingOffer = false;
}
};
signaling.onmessage = async ({data: {description, candidate}}) => {
try {
if (description) {
// An offer may come in while we are busy processing SRD(answer).
// In this case, we will be in "stable" by the time the offer is processed
// so it is safe to chain it on our Operations Chain now.
const readyForOffer =
!makingOffer &&
(pc.signalingState == "stable" || isSettingRemoteAnswerPending);
const offerCollision = description.type == "offer" && !readyForOffer;
ignoreOffer = !polite && offerCollision;
if (ignoreOffer) {
return;
}
isSettingRemoteAnswerPending = description.type == "answer";
await pc.setRemoteDescription(description); // SRD rolls back as needed
isSettingRemoteAnswerPending = false;
if (description.type == "offer") {
await pc.setLocalDescription();
signaling.send({description: pc.localDescription});
}
} else if (candidate) {
try {
await pc.addIceCandidate(candidate);
} catch (err) {
if (!ignoreOffer) throw err; // Suppress ignored offer's candidates
}
}
} catch (err) {
console.error(err);
}
}
Note that this is timing sensitive, and deliberately uses versions of
setLocalDescription
(without arguments) and
setRemoteDescription
(with implicit rollback)
to avoid races with other signaling messages being serviced.
The ignoreOffer variable is needed, because the
RTCPeerConnection
object on the impolite side is never told about
ignored offers. We must therefore suppress errors from incoming
candidates belonging to such offers.
Some operations throw or fire RTCError
. This is an extension of
DOMException
that carries additional WebRTC-specific information.
WebIDL[Exposed=Window]
interface RTCError
: DOMException {
constructor
(RTCErrorInit
init, optional DOMString message = "");
readonly attribute RTCErrorDetailType
errorDetail
;
readonly attribute long? sdpLineNumber
;
readonly attribute long? sctpCauseCode
;
readonly attribute unsigned long? receivedAlert
;
readonly attribute unsigned long? sentAlert
;
};
constructor()
Run the following steps:
Let init be the constructor's first argument.
Let message be the constructor's second argument.
Let e be a new RTCError
object.
Invoke the DOMException
constructor of e
with the message
argument set to
message and the name
argument
set to "OperationError"
.
This name does not have a mapping to a legacy code so
e.code
will return 0.
Set all RTCError
attributes of e to the
value of the corresponding attribute in init if
it is present, otherwise set it to null
.
Return e.
errorDetail
of type RTCErrorDetailType, readonly
The WebRTC-specific error code for the type of error that occurred.
sdpLineNumber
of type long, readonly, nullable
If errorDetail
is
"sdp-syntax-error
" this is the line
number where the error was detected (the first line has line
number 1).
sctpCauseCode
of type long, readonly, nullable
If errorDetail
is
"sctp-failure
" this is the SCTP cause
code of the failed SCTP negotiation.
receivedAlert
of type unsigned long, readonly, nullable
If errorDetail
is
"dtls-failure
" and a fatal DTLS alert
was received, this is the value of the DTLS alert received.
sentAlert
of type unsigned long, readonly, nullable
If errorDetail
is
"dtls-failure
" and a fatal DTLS alert
was sent, this is the value of the DTLS alert sent.
All attributes defined in RTCError
are marked at risk due
to lack of implementation (errorDetail
,
sdpLineNumber
, sctpCauseCode
, receivedAlert
and
sentAlert
). This does not include attributes inherited
from DOMException
.
WebIDLdictionary RTCErrorInit
{
required RTCErrorDetailType
errorDetail
;
long sdpLineNumber
;
long sctpCauseCode
;
unsigned long receivedAlert
;
unsigned long sentAlert
;
};
The errorDetail
, sdpLineNumber
, sctpCauseCode
,
receivedAlert
and sentAlert
members of RTCErrorInit
have the same
definitions as the attributes of the same name of RTCError
.
WebIDLenum RTCErrorDetailType
{
"data-channel-failure
",
"dtls-failure
",
"fingerprint-failure
",
"sctp-failure
",
"sdp-syntax-error
",
"hardware-encoder-not-available
",
"hardware-encoder-error
"
};
Enum value | Description |
---|---|
data-channel-failure
|
The data channel has failed. |
dtls-failure
|
The DTLS negotiation has failed or the connection has been
terminated with a fatal error. The message
contains information relating to the nature of error. If a
fatal DTLS alert was received, the receivedAlert
attribute is set to the value of the DTLS alert received. If a
fatal DTLS alert was sent, the sentAlert attribute
is set to the value of the DTLS alert sent.
|
fingerprint-failure
|
The RTCDtlsTransport 's remote certificate did not match any
of the fingerprints provided in the SDP. If the remote peer
cannot match the local certificate against the provided
fingerprints, this error is not generated. Instead a
"bad_certificate" (42) DTLS alert might be received from the
remote peer, resulting in a
"dtls-failure ".
|
sctp-failure
|
The SCTP negotiation has failed or the connection has been
terminated with a fatal error. The sctpCauseCode
attribute is set to the SCTP cause code.
|
sdp-syntax-error
|
The SDP syntax is not valid. The sdpLineNumber
attribute is set to the line number in the SDP where the syntax
error was detected.
|
hardware-encoder-not-available
|
The hardware encoder resources required for the requested operation are not available. |
hardware-encoder-error
|
The hardware encoder does not support the provided parameters. |
The RTCErrorEvent
interface is defined for cases when an
RTCError
is raised as an event:
WebIDL[Exposed=Window]
interface RTCErrorEvent
: Event {
constructor
(DOMString type, RTCErrorEventInit
eventInitDict);
[SameObject] readonly attribute RTCError
error
;
};
constructor()
Constructs a new RTCErrorEvent
.
error
of type RTCError
, readonly
The RTCError
describing the error that triggered the event.
WebIDL dictionary RTCErrorEventInit
: EventInit {
required RTCError
error
;
};
error
of type RTCError
The RTCError
describing the error associated with the event
(if any).
This section is non-normative.
The following events fire on RTCDataChannel
objects:
Event name | Interface | Fired when... |
---|---|---|
open |
Event
|
The RTCDataChannel object's underlying data transport
has been established (or re-established).
|
message |
MessageEvent
[html]
|
A message was successfully received. |
bufferedamountlow |
Event
|
The RTCDataChannel object's bufferedAmount
decreases from above its
bufferedAmountLowThreshold to less than or
equal to its bufferedAmountLowThreshold .
|
error |
RTCErrorEvent
|
An error occurred on the data channel. |
closing |
Event
|
The RTCDataChannel object transitions to the
"closing " state
|
close |
Event
|
The RTCDataChannel object's underlying data transport
has been closed.
|
The following events fire on RTCPeerConnection
objects:
Event name | Interface | Fired when... |
---|---|---|
track |
RTCTrackEvent
|
New incoming media has been negotiated for a specific
RTCRtpReceiver , and that receiver's track
has been added to any associated remote MediaStream s.
|
negotiationneeded |
Event
|
The browser wishes to inform the application that session negotiation needs to be done (i.e. a createOffer call followed by setLocalDescription). |
signalingstatechange |
Event
|
The signaling state has changed. This state change is the
result of either setLocalDescription or
setRemoteDescription being invoked.
|
iceconnectionstatechange |
Event
|
The RTCPeerConnection 's ICE connection state has
changed.
|
icegatheringstatechange |
Event
|
The RTCPeerConnection 's ICE gathering state has
changed.
|
icecandidate |
RTCPeerConnectionIceEvent
|
A new RTCIceCandidate is made available to the script.
|
connectionstatechange |
Event
|
The RTCPeerConnection .connectionState
has changed.
|
icecandidateerror |
RTCPeerConnectionIceErrorEvent
|
A failure occured when gathering ICE candidates. |
datachannel |
RTCDataChannelEvent
|
A new RTCDataChannel is dispatched to the script in response
to the other peer creating a channel.
|
The following events fire on RTCDTMFSender
objects:
Event name | Interface | Fired when... |
---|---|---|
tonechange |
RTCDTMFToneChangeEvent
|
The RTCDTMFSender object has either just begun playout of a
tone (returned as the tone attribute)
or just ended the playout of tones in the
toneBuffer (returned as an empty value in the
tone attribute).
|
The following events fire on RTCIceTransport
objects:
Event name | Interface | Fired when... |
---|---|---|
statechange |
Event
|
The RTCIceTransport state changes.
|
gatheringstatechange |
Event
|
The RTCIceTransport gathering state changes.
|
selectedcandidatepairchange |
Event
|
The RTCIceTransport 's selected candidate pair changes.
|
The following events fire on RTCDtlsTransport
objects:
Event name | Interface | Fired when... |
---|---|---|
statechange |
Event
|
The RTCDtlsTransport state changes.
|
error |
RTCErrorEvent
|
An error occurred on the RTCDtlsTransport (either
"dtls-failure " or
"fingerprint-failure ").
|
The following events fire on RTCSctpTransport
objects:
Event name | Interface | Fired when... |
---|---|---|
statechange |
Event
|
The RTCSctpTransport state changes.
|
This section is non-normative.
This section is non-normative; it specifies no new behaviour, but instead summarizes information already present in other parts of the specification. The overall security considerations of the general set of APIs and protocols used in WebRTC are described in [RFC8827].
This document extends the Web platform with the ability to set up real-time, direct communication between browsers and other devices, including other browsers.
This means that data and media can be shared between applications running in different browsers, or between an application running in the same browser and something that is not a browser, something that is an extension to the usual barriers in the Web model against sending data between entities with different origins.
The WebRTC specification provides no user prompts or chrome indicators for communication; it assumes that once the Web page has been allowed to access media, it is free to share that media with other entities as it chooses. Peer-to-peer exchanges of data view WebRTC datachannels can thus occur without any user explicit consent or involvement, similarly as a server-mediated exchange (e.g. via Web Sockets) could occur without user involvement.
Even without WebRTC, the Web server providing a Web application will know the public IP address to which the application is delivered. Setting up communications exposes additional information about the browser’s network context to the web application, and may include the set of (possibly private) IP addresses available to the browser for WebRTC use. Some of this information has to be passed to the corresponding party to enable the establishment of a communication session.
Revealing IP addresses can leak location and means of connection; this can be sensitive. Depending on the network environment, it can also increase the fingerprinting surface and create persistent cross-origin state that cannot easily be cleared by the user.
A connection will always reveal the IP addresses proposed for
communication to the corresponding party. The application can limit
this exposure by choosing not to use certain addresses using the
settings exposed by the RTCIceTransportPolicy
dictionary, and by
using relays (for instance TURN servers) rather than direct
connections between participants. One will normally assume that the
IP address of TURN servers is not sensitive information. These
choices can for instance be made by the application based on whether
the user has indicated consent to start a media connection with the
other party.
Mitigating the exposure of IP addresses to the application itself requires limiting the IP addresses that can be used, which will impact the ability to communicate on the most direct path between endpoints. Browsers are encouraged to provide appropriate controls for deciding which IP addresses are made available to applications, based on the security posture desired by the user. The choice of which addresses to expose is controlled by local policy (see [RFC8828] for details).
Since the browser is an active platform executing in a trusted network environment (inside the firewall), it is important to limit the damage that the browser can do to other elements on the local network, and it is important to protect data from interception, manipulation and modification by untrusted participants.
Mitigations include:
These measures are specified in the relevant IETF documents.
The fact that communication is taking place cannot be hidden from adversaries that can observe the network, so this has to be regarded as public information.
Communication certificates may be opaquely shared using
postMessage
(message, options)
in anticipation of future needs. User
agents are strongly encouraged to isolate the private keying material
these objects hold a handle to, from the processes that have access
to the RTCCertificate
objects, to reduce memory attack surface.
As described above, the list of IP addresses exposed by the WebRTC API can be used as a persistent cross-origin state.
Beyond IP addresses, the WebRTC API exposes information about the
underlying media system via the
RTCRtpSender
.getCapabilities
and
RTCRtpReceiver
.getCapabilities
methods,
including detailed and ordered information about the codecs that the
system is able to produce and consume. A subset of that information
is likely to be represented in the SDP session descriptions
generated, exposed and transmitted during session negotiation. That
information is in most cases persistent across time and origins, and
increases the fingerprint surface of a given device.
When establishing DTLS connections, the WebRTC API can generate certificates that can be persisted by the application (e.g. in IndexedDB). These certificates are not shared across origins, and get cleared when persistent storage is cleared for the origin.
setRemoteDescription
guards against malformed
and invalid SDP by throwing exceptions, but makes no attempt to guard
against SDP that might be unexpected by the application. Setting the
remote description can cause significant resources to be allocated
(including image buffers and network ports), media to start flowing
(which may have privacy and bandwidth implications) among other
things. An application that does not guard against malicious SDP
could be at risk of resource deprivation, unintentionally allowing
incoming media or at risk of not having certain events fire like
ontrack
if the other endpoint does not
negotiate sending. Applications need to be on guard against
malevolent SDP.
This section is non-normative.
The WebRTC 1.0 specification exposes an API to control protocols (defined within the IETF) necessary to establish real-time audio, video and data exchange.
The Telecommunications Device for the Deaf (TDD/TTY) enables individuals who are hearing or speech impaired (among others) to communicate over telephone lines. Real-Time Text, defined in [RFC4103], utilizes T.140 encapsulated in RTP to enable the transition from TDD/TTY devices to IP-based communications, including emergency communication with Public Safety Access Points (PSAP).
Since Real-Time Text requires the ability to send and receive data in near real time, it can be best supported via the WebRTC 1.0 data channel API. As defined by the IETF, the data channel protocol utilizes the SCTP/DTLS/UDP protocol stack, which supports both reliable and unreliable data channels. The IETF chose to standardize SCTP/DTLS/UDP over proposals for an RTP data channel which relied on SRTP key management and were focused on unreliable communications.
Since the IETF chose a different approach than the RTP data channel as part of the WebRTC suite of protocols, as of the time of this publication there is no standardized way for the WebRTC APIs to directly support Real-Time Text as defined at IETF and implemented in U.S. (FCC) regulations. The WebRTC working Group will evaluate whether the developing IETF protocols in this space warrant direct exposure in the browser APIs and is looking for input from the relevant user communities on this potential gap.
Within the IETF MMUSIC Working Group, work is ongoing to enable Real-time text to be sent over the WebRTC data channel, allowing gateways to be deployed to translate between the SCTP data channel protocol and RFC 4103 Real-Time Text. This work, once completed, is expected to enable a unified and interoperable approach for integrating real-time text in WebRTC user-agents (including browsers) - through a gateway or otherwise.
At the time of this publication, gateways that enable effective RTT support in WebRTC clients can be developed e.g. through a custom WebRTC data channel. This is deemed sufficient until such time as future standardized gateways are enabled via IETF protocols such as the SCTP data channel protocol and RFC 4103 Real-Time Text. This will need to be defined at IETF in conjunction with related work at W3C groups to effectively and consistently standardise RTT support internationally.
Since its publication as a W3C Recommendation in January 2021, the following candidate amendments have been integrated in this document.
RTCConfiguration
dictionary, aligning it with current implementations - section
Dictionary RTCConfiguration Members
(PR #2691)RTCConfiguration
dictionary, aligning it with current implementations - section 4.4.1.6
Set the configuration
(PR #2691)RTCIceGatheringState
to clarify the relevant transport it represents - section 4.3.2
RTCIceGatheringState Enum
(PR #2680)RTCPeerConnectionState
to clarify the relevant transport it represents - section 4.3.3
RTCPeerConnectionState Enum
(PR #2680)RTCIceConnectionState
to clarify the relevant transport it represents - section 4.3.4
RTCIceConnectionState Enum
(PR #2680)connecting
state happens whenever a ICE or DTLS transport is new - section 4.3.3
RTCPeerConnectionState Enum
(PR #2687)DOMTimeStamp
in the definition of the RTCCertificateExpiration.expires
and of RTCCertificate.expires
, and change its origin to certificate creation time - section 4.9.1
RTCCertificateExpiration Dictionary
(PR #2686, PR #2700)DOMTimeStamp
in the definition of the RTCCertificateExpiration.expires
and of RTCCertificate.expires
, and change its origin to certificate creation time - section 4.9.2
RTCCertificate Interface
(PR #2686, PR #2700)failed
state when no candidates are received - section 5.6.4
RTCIceTransportState Enum
(PR #2704)The editors wish to thank the Working Group chairs and Team Contact, Harald Alvestrand, Stefan Håkansson, Erik Lagerway and Dominique Hazaël-Massieux, for their support. Substantial text in this specification was provided by many people including Martin Thomson, Harald Alvestrand, Justin Uberti, Eric Rescorla, Peter Thatcher, Jan-Ivar Bruaroey and Peter Saint-Andre. Dan Burnett would like to acknowledge the significant support received from Voxeo and Aspect during the development of this specification.
The RTCRtpSender
and RTCRtpReceiver
objects were initially
described in the W3C ORTC
CG, and have been adapted for use in this specification.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: