WebRTC 1.0: Real-time Communication Between Browsers

WebRTC 1.0: Real-time Communication Between Browsers
WebRTC 1.0: Real-time Communication Between Browsers
W3C
Candidate Recommendation
02 November 2017
This version:
Latest published version:
Latest editor's draft:
Test suite:
Implementation report:
Previous version:
Editors:
Adam Bergkvist
, Ericsson
Daniel C. Burnett
, Invited Expert
Cullen Jennings
, Cisco
Anant Narayanan
, Mozilla (until November 2012)
Bernard Aboba
, Microsoft Corporation (until March 2017)
Taylor Brandstetter
, Google
Participate:
Mailing list
Browse open issues
IETF RTCWEB Working Group
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
W3C
MIT
ERCIM
Keio
Beihang
).
Document use
rules apply.
For the entire publication on the
W3C
site the
liability
and
trademark
rules apply.
Abstract
This document defines a set of ECMAScript APIs in WebIDL to allow media 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 developed by the Media Capture Task Force.
Status of This Document
This section describes the status of this document at the time of its publication. Other documents may supersede this document. 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/.
The API is based on preliminary work done in the WHATWG.
While the specification is feature complete and is expected to be stable, there are also a number of
known substantive issues
on the specification that will be addressed during the Candidate Recommendation period based on implementation experience feedback.
It might also evolve based on feedback gathered as its
associated test suite
evolves. This test suite will be used to build an
implementation report
of the API.
To go into Proposed Recommendation status, the group expects to demonstrate implementation of each feature in at least two deployed browsers, and at least one implementation of each optional feature. Mandatory feature with only one implementation may be marked as optional in a revised Candidate Recommendation where applicable.
The following features are marked as risk:
The value
negotiate
of RTCRtcpMuxPolicy
This document was published by the
Web Real-Time Communications Working Group
as a Candidate Recommendation. This document is intended to become a
W3C
Recommendation. Comments regarding this document are welcome. Please send them to
public-webrtc@w3.org
archives
).
W3C
publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected
to advance to Proposed Recommendation no earlier than 15 April 2018.
Publication as a Candidate Recommendation does not imply endorsement by the
W3C
Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It
is inappropriate to cite this document as other than work in progress.
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
1 March 2017
W3C
Process Document
1.
Introduction
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:
Connecting to remote peers using NAT-traversal technologies such as ICE, STUN, and TURN.
Sending the locally-produced tracks to remote peers and receiving tracks from remote peers.
Sending arbitrary data directly to remote peers.
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
Media
Capture Task Force
. An overview of the system can be found in [
RTCWEB-OVERVIEW
] and [
RTCWEB-SECURITY
].
2.
Conformance
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
SHALL
, and
SHOULD
are to be interpreted as described in [
RFC2119
].
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-1
],
as this specification uses that specification and terminology.
3.
Terminology
The
EventHandler
interface, representing a callback used for event handlers, and the
ErrorEvent
interface are defined in [
HTML51
].
The concepts
queue a
task
fire a
simple event
and
networking
task source
are defined in [
HTML51
].
The terms
event
event
handlers
and
event
handler event types
are defined in [
HTML51
].
The terms
MediaStream
MediaStreamTrack
, and
MediaStreamConstraints
are defined in [
GETUSERMEDIA
].
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 [
TRICKLE-ICE
] Section 2.
The term
RTCStatsType
is defined in [
WEBRTC-STATS
].
When referring to exceptions, the terms
throw
and
create
are defined in [
WEBIDL-1
].
The terms
fulfilled
rejected
resolved
pending
and
settled
used in the context of Promises are defined in [
ECMASCRIPT-6.0
].
4.
Peer-to-peer connections
4.1
Introduction
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
XMLHttpRequest
XMLHttpRequest
] or Web Sockets [
WEBSOCKETS-API
].
4.2
Configuration
4.2.1
RTCConfiguration
Dictionary
The
RTCConfiguration
defines a set of parameters to configure how the peer-to-peer communication established via
RTCPeerConnection
is established or re-established.
dictionary
RTCConfiguration
sequence
RTCIceServer
iceServers
RTCIceTransportPolicy
iceTransportPolicy
"all"
RTCBundlePolicy
bundlePolicy
"balanced"
RTCRtcpMuxPolicy
rtcpMuxPolicy
"require"
DOMString
peerIdentity
sequence
RTCCertificate
certificates
EnforceRange
octet
iceCandidatePoolSize
};
Dictionary
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
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.
peerIdentity
of type
DOMString
Sets the
target peer identity
for the
RTCPeerConnection
. The
RTCPeerConnection
will not establish a connection to a remote peer unless it can be successfully authenticated with the provided name.
certificates
of type
sequence<
RTCCertificate
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.
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
Size of the prefetched ICE pool as defined in
JSEP
] (
section 3.5.4.
and
section 4.1.1.
4.2.2
RTCIceCredentialType
Enum
enum
RTCIceCredentialType
"password"
"oauth"
};
Enumeration description
password
The credential is a long-term authentication username and password, as described in [
RFC5389
], Section 10.2.
oauth
An OAuth 2.0 based authentication method, as described in [
RFC7635
]. It uses the OAuth 2.0 Implicit Grant type, with PoP (Proof-of-Possession) Token type, as described in [
RFC6749
] and [
OAUTH-POP-KEY-DISTRIBUTION
].
The
OAuth Client
and the
Auhorization
Server
roles are defined in [
RFC6749
] Section 1.1.
If [
RFC7635
] is used in the WebRTC context then the
OAuth
Client
is responsible for refreshing the credential information, and updating the
ICE Agent
with fresh new credentials before the
accessToken
expires.
The
OAuth Client
can use the
RTCPeerConnection
setConfiguration
method to periodically refresh the TURN credentials.
For OAuth Authentication, the
ICE Agent
requires three pieces of credential information. The credential is composed of a
kid
, which
the
RTCIceServer
username
member is used for, and
macKey
and
accessToken
, which are placed in the
RTCOAuthCredential
dictionary. All of this information
can be extracted from the OAuth response parameters, which are received from the
Authorization Server
. The relevant OAuth response parameters are the
"kid", the "key", and the "access_token". These can be used to extract all the necessary credential infromation (the
kid
macKey
, and
accessToken
) that are required by the
ICE Agent
for the Authentication.
The [
OAUTH-POP-KEY-DISTRIBUTION
] defines
alg
parameter in Section 4.1 and 6. and describes that if
the
Authorization Server
doesn't have prior knowledge of the capabilities of the client, then the
OAuth Client
needs to provide information about the
ICE Agent
HMAC
alg
capabilities. This information helps the
Authorization Server
to generate the approriate HMAC key. The HMAC
alg
defines the input key length, and HMAC algorithm Familly (e.g. SHA), and HMAC algorithm type (e.g. symmetric/asymmetric).
The
OAuth Client
sends an
OAuth Request
to the
Authorization Server
with OAuth param
alg
and further OAuth related parameters, to get an
OAuth
Response
with the
access_token
key
kid
, and further OAuth related parameters.
However, this specification uses a simplified
alg
approach. The length of the HMAC key (
RTCOAuthCredential.macKey
MAY
be any integer number of bytes greater than 20 (160 bits). This negates the need to query the HMAC Algorithm capabilities of the
ICE Agent
, and
still allows for hash agility as described by [
STUN-BIS
], Section 15.3.
Note
According to [
RFC7635
] Section 4.1, the HMAC key
MUST
be a symmetric key.
Currently the STUN/TURN protocols use only SHA-1 and SHA-2 family hash algorithms for Message Integrity Protection, as defined in [
RFC5389
] Section 15.4, and [
STUN-BIS
Section 14.6.
When [
RFC7635
] is used in WebRTC context, this specification adds the following additional consideration to it.
The
OAuth Client
SHOULD
obtain the mac_key by requesting an
alg
value of
HS256
. This will result in a 256-bit HMAC key.
HS256
is defined in [
RFC7518
] Section 3.1. It is recommended here because:
The OAuth respose key parameter is received in JWK format according to [
OAUTH-POP-KEY-DISTRIBUTION
] Section 4.2. JWK's algorithms are normatively
registered in the IANA "JSON Web Signature and Encryption Algorithms" registry.
STUN/TURN currently use SHA family HMAC algorithms only.
The key
MUST
be symmetric, according to [
RFC7635
].
A 256-bit key is large enough to support all currently defined STUN message integrity attributes.
More details about OAuth PoP Client can be found in [
OAUTH-POP-KEY-DISTRIBUTION
] Section 4.
More details about
Access-Token
can be found in [
RFC7635
], Section 6.2.
4.2.3
RTCOAuthCredential
Dictionary
The
RTCOAuthCredential
dictionary is used to describe the OAuth auth credential information which is used by the STUN/TURN client (inside the
ICE Agent
to authenticate against a STUN/TURN server, as described in [
RFC7635
]. Note that the
kid
parameter is not located in this dictionary, but in
RTCIceServer
's
username
member.
dictionary
RTCOAuthCredential
required
DOMString
macKey
required
DOMString
accessToken
};
Dictionary
RTCOAuthCredential
Members
macKey
of type
DOMString
, required
The "mac_key", as described in [
RFC7635
], Section 6.2, in a base64-url encoded format. It is used in STUN message integrity hash calculation (as the password is used
in password based authentication). Note that the OAuth response "key" parameter is a JSON Web Key (JWK) or a JWK encrypted with a JWE format. Also note that this is the only OAuth parameter whose value is not used directly,
but must be extracted from the "k" parameter value from the JWK, which contains the needed base64-encoded "mac_key".
accessToken
of type
DOMString
, required
The "access_token", as described in [
RFC7635
], Section 6.2, in a base64-encoded format. This is an encrypted self-contained token that is opaque to the application.
Authenticated encryption is used for message encryption and integrity protection. The access token contains a non-encrypted nonce value, which is used by the Authorization Server for unique mac_key generation. The second
part of the token is protected by Authenticated Encryption. It contains the mac_key, a timestamp and a lifetime. The timestamp combined with lifetime provides expiry information; this information describes the time
window during which the token credential is valid and accepted by the TURN server.
An example of an RTCOAuthCredential dictionary is:
Example 1
macKey
"WmtzanB3ZW9peFhtdm42NzUzNG0="
accessToken:
"AAwg3kPHWPfvk9bDFL936wYvkoctMADzQ5VhNDgeMR3+ZlZ35byg972fW8QjpEl7bx91YLBPFsIhsxloWcXPhA=="
4.2.4
RTCIceServer
Dictionary
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.
dictionary
RTCIceServer
required
DOMString
or
sequence
DOMString
>)
urls
DOMString
username
DOMString
or
RTCOAuthCredential
credential
RTCIceCredentialType
credentialType
"password"
};
Dictionary
RTCIceServer
Members
urls
of type
(DOMString or
sequence)
, 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, and
credentialType
is
"password"
, then this attribute specifies the username to use with that TURN server.
If this
RTCIceServer
object represents a TURN server, and
credentialType
is
"oauth"
, then this attribute specifies the Key ID (
kid
) of the shared symmetric key, which is shared between the TURN server and the Authorization Server, as described in [
RFC7635
].
It is an ephemeral and unique key identifier. The
kid
allows the TURN server to select the appropriate keying material for decryption of the Access-Token, so the key identified by this
kid
is used in the Authenticated Encryption of the "access_token". The
kid
value is equal with the OAuth response "kid" parameter, as defined in [
RFC7515
] Section 4.1.4.
credential
of type
(DOMString or
RTCOAuthCredential
If this
RTCIceServer
object represents a TURN server, then this attribute specifies the credential to use with that TURN server.
If
credentialType
is
"password"
credential
is a DOMString, and represents a long-term authentication password, as described in [
RFC5389
], Section 10.2.
If
credentialType
is
"oauth"
credential
is an
RTCOAuthCredential
, which contains the OAuth access token and MAC key.
credentialType
of type
RTCIceCredentialType
, defaulting to
"password"
If this
RTCIceServer
object represents a TURN server, then this attribute specifies how
credential
should be used when that TURN server requests authorization.
An example array of RTCIceServer objects is:
Example 2
urls
"stun:stun1.example.net"
},
urls
: [
"turns:turn.example.org"
"turn:turn.example.net"
],
username
"user"
credential
"myPassword"
credentialType
"password"
},
urls
"turns:turn2.example.net"
username
"22BIjxU93h/IgwEb"
credential
: {
macKey
"WmtzanB3ZW9peFhtdm42NzUzNG0="
accessToken
"AAwg3kPHWPfvk9bDFL936wYvkoctMADzQ5VhNDgeMR3+ZlZ35byg972fW8QjpEl7bx91YLBPFsIhsxloWcXPhA=="
},
credentialType
"oauth"
4.2.5
RTCIceTransportPolicy
Enum
As described in
JSEP
] (
section 4.1.1.
, if the
iceTransportPolicy
member of the
RTCConfiguration
is specified, it defines the
ICE candidate policy
JSEP
] (
section 3.5.3.
the browser uses to surface the permitted candidates to the
application; only these candidates will be used for connectivity checks.
enum
RTCIceTransportPolicy
"relay"
"all"
};
Enumeration description (non-normative)
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.
ip
4.2.6
RTCBundlePolicy
Enum
As described in
JSEP
] (
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.
enum
RTCBundlePolicy
"balanced"
"max-compat"
"max-bundle"
};
Enumeration description (non-normative)
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.
4.2.7
RTCRtcpMuxPolicy
Enum
As described in
JSEP
] (
section 4.1.1.
, the RtcpMuxPolicy affects what ICE candidates are
gathered to support non-multiplexed RTCP.
enum
RTCRtcpMuxPolicy
// At risk due to lack of implementers' interest.
"negotiate"
"require"
};
Enumeration description (non-normative)
negotiate
Gather ICE candidates for both RTP and RTCP candidates. If the remote-endpoint is capable of multiplexing RTCP, multiplex RTCP on the RTP candidates. If it is not, use both the RTP and RTCP candidates separately. Note that,
as stated in
JSEP
] (
section 4.1.1.
, the user agent
MAY
not implement non-multiplexed RTCP, in which case it will reject attempts to construct an
RTCPeerConnection
with the
negotiate
policy.
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.
Feature at Risk 1
Aspects of this specification supporting non-multiplexed RTP/RTCP are marked as features at risk, since there is no clear commitment from implementers. This includes:
The value
negotiate
, since there is no clear commitment from implementers for the behavior associated with this.
Support for the
rtcpTransport
attribute within the
RTCRtpSender
and
RTCRtpReceiver
4.2.8
Offer/Answer Options
These dictionaries describe the options that can be used to control the offer/answer creation process.
dictionary
RTCOfferAnswerOptions
boolean
voiceActivityDetection
true
};
Dictionary
RTCOfferAnswerOptions
Members
voiceActivityDetection
of type
boolean
, defaulting to
true
Many codecs and systems are capable of detecting "silence" and changing their behavior in this case by doing things such as not transmitting any media. In many cases, such as when dealing with emergency calling or sounds
other than spoken voice, it is desirable to be able to turn off this behavior. This option allows the application to provide information about whether it wishes this type of processing enabled or disabled.
dictionary
RTCOfferOptions
RTCOfferAnswerOptions
boolean
iceRestart
false
};
Dictionary
RTCOfferOptions
Members
iceRestart
of type
boolean
, defaulting to
false
When the value of this dictionary member is true, the generated description will have ICE credentials that are different from the current credentials (as visible in the
localDescription
attribute's SDP). Applying the generated description will restart ICE, as described in section 9.1.1.1 of [
ICE
].
When the value of this dictionary member is false, and the
localDescription
attribute has valid ICE credentials, the generated description will have the same ICE credentials as the current value from the
localDescription
attribute.
The
RTCAnswerOptions
dictionary describe options specific to session description of type
answer
(none in this version of the specification).
dictionary
RTCAnswerOptions
RTCOfferAnswerOptions
};
4.3
State Definitions
4.3.1
RTCSignalingState
Enum
enum
RTCSignalingState
"stable"
"have-local-offer"
"have-remote-offer"
"have-local-pranswer"
"have-remote-pranswer"
"closed"
};
Enumeration 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
Figure
Non-normative signalling state transitions diagram
An example set of transitions might be:
Caller transition:
new RTCPeerConnection():
stable
setLocal(offer):
have-local-offer
setRemote(pranswer):
have-remote-pranswer
setRemote(answer):
stable
Callee transition:
new RTCPeerConnection():
stable
setRemote(offer):
have-remote-offer
setLocal(pranswer):
have-local-pranswer
setLocal(answer):
stable
4.3.2
RTCIceGatheringState
Enum
enum
RTCIceGatheringState
"new"
"gathering"
"complete"
};
Enumeration 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
"completed"
gathering state.
4.3.3
RTCPeerConnectionState
Enum
enum
RTCPeerConnectionState
"new"
"connecting"
"connected"
"disconnected"
"failed"
"closed"
};
Enumeration description
new
Any of the
RTCIceTransport
s or
RTCDtlsTransport
s are in the
"new"
state and none of the transports are in the
"connecting"
"checking"
"failed"
or
"disconnected"
state, or all transports are in the
"closed"
state, or there are no transports.
connecting
Any of the
RTCIceTransport
s or
RTCDtlsTransport
s are in the
"connecting"
or
"checking"
state and none of them is in the
"failed"
state.
connected
All
RTCIceTransport
s and
RTCDtlsTransport
s are in the
"connected"
"completed"
or
"closed"
state and at least one of them is in the
"connected"
or
"completed"
state.
disconnected
Any of the
RTCIceTransport
s or
RTCDtlsTransport
s are in the
"disconnected"
state and none of them are in the
"failed"
or
"connecting"
or
"checking"
state.
failed
Any of the
RTCIceTransport
s or
RTCDtlsTransport
s are in a
"failed"
state.
closed
The
RTCPeerConnection
object's
[[IsClosed]]
slot is
true
4.3.4
RTCIceConnectionState
Enum
enum
RTCIceConnectionState
"new"
"checking"
"connected"
"completed"
"failed"
"disconnected"
"closed"
};
Enumeration description
new
Any of the
RTCIceTransport
s are in the
"new"
state and none of them are in the
"checking"
"failed"
or
"disconnected"
state, or all
RTCIceTransport
s are in the
"closed"
state, or there are no transports.
checking
Any of the
RTCIceTransport
s are in the
"checking"
state and none of them are in the
"failed"
or
"disconnected"
state.
connected
All
RTCIceTransport
s are in the
"connected"
"completed"
or
"closed"
state and at least one of them is in the
"connected"
state.
completed
All
RTCIceTransport
s are in the
"completed"
or
"closed"
state and at least one of them is in the
"completed"
state.
failed
Any of the
RTCIceTransport
s are in the
"failed"
state.
disconnected
Any of the
RTCIceTransport
s are in the
"disconnected"
state and none of them are in the
"failed"
state.
closed
The
RTCPeerConnection
object's
[[IsClosed]]
slot is
true
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.
4.4
RTCPeerConnection Interface
The [
JSEP
] specification, as a whole, describes the details of how the
RTCPeerConnection
operates. References to specific subsections of [
JSEP
] are provided as appropriate.
4.4.1
Operation
Calling
new
RTCPeerConnection
configuration
creates an
RTCPeerConnection
object.
configuration
.servers
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
ICE
]. 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 [
JSEP
]. 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
4.4.1.1
Constructor
When the
RTCPeerConnection()
constructor is invoked, the user agent
MUST
run the following steps:
Let
connection
be a newly created
RTCPeerConnection
object.
If the
certificates
value in
configuration
is non-empty, check that the
expires
on each value is in the future. If a certificate has expired,
throw
an
InvalidAccessError
; otherwise, store the certificates. If no
certificates
value was specified, one or more new
RTCCertificate
instances are generated for use with this
RTCPeerConnection
instance. This
MAY
happen asynchronously and the value of
certificates
remains undefined for the subsequent steps.
If
configuration
rtcpMuxPolicy
is
"negotiate"
, and the user agent does not implement non-muxed RTCP,
throw
NotSupportedError
Initialize
connection
's
ICE Agent
Let
connection
have a
[[Configuration]]
internal slot.
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 queue
initialized to an empty list.
Let
connection
have an
[[LastOffer]]
internal slot, initialized to "".
Let
connection
have an
[[LastAnswer]]
internal slot, initialized to "".
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"
Set
connection
's
pendingLocalDescription
currentLocalDescription
pendingRemoteDescription
and
currentRemoteDescription
to null.
Return
connection
An
RTCPeerConnection
object has an
operations queue
[[Operations]]
, which ensures that only one asynchronous operation in
the queue is executed concurrently. If subsequent calls are made while the returned promise of a previous call is still not
settled
, they are added to the queue
and executed when all the previous calls have finished executing and their promises have
settled
4.4.1.2
Enqueue an operation
To
enqueue an operation
to an
RTCPeerConnection
object's operation queue, run the following steps:
Let
connection
be the
RTCPeerConnection
object.
If
connection
's
[[IsClosed]]
slot is
true
, return a promise
rejected
with a newly
created
InvalidStateError
Let
operation
be the operation to be enqueued.
Let
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
's
[[IsClosed]]
slot is
true
, abort these steps.
If the promise returned by
operation
was
fulfilled
with a value,
fulfill
with that value.
If the promise returned by
operation
was
rejected
with a value,
reject
with that value.
Upon
fulfillment
or
rejection
of
, execute the following steps:
If
connection
's
[[IsClosed]]
slot 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]]
Return
4.4.1.3
Update the connection state
An
RTCPeerConnection
object has an aggregated
connection state
. Whenever the state of an
RTCDtlsTransport
or
RTCIceTransport
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 a simple event named
connectionstatechange
at
connection
4.4.1.4
Update the ICE gathering state
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
's
[[IsClosed]]
slot 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 a simple event named
icegatheringstatechange
at
connection
If
newState
is
"completed"
fire an ice candidate event
named
icecandidate
with
null
at
connection
Note
The null candidate event is fired to ensure legacy compatibility. New code should monitor the gathering state of
RTCIceTransport
and/or
RTCPeerConnection
4.4.1.5
Update the ICE connection state
To
update the
ICE
connection state
of an
RTCPeerConnection
instance
connection
, the user agent
MUST
queue a task that runs the following steps:
If
connection
's
[[IsClosed]]
slot is
true
, abort these steps.
Let
newState
be the value of deriving a new state value as described by the
RTCIceConnectionState
enum.
If
connection
's
ICE connection state
is equal to
newState
, abort these steps.
Set
connection
's
ice connection state
to
newState
Fire a simple event named
iceconnectionstatechange
at
connection
4.4.1.6
Set the RTCSessionDescription
To
set an RTCSessionDescription
description
on an
RTCPeerConnection
object
connection
enqueue
the following steps to
connection
's operation queue:
Let
be a new promise.
In parallel, start the process to apply
description
as described in
JSEP
] (
section 5.5.
and
section 5.6.
If the process to apply
description
fails for any reason, then user agent
MUST
queue a task that runs the following steps:
If
connection
's
[[IsClosed]]
slot is
true
, then abort these steps.
If the
description
's
type
is invalid for the current
signaling state
of
connection
as described in
JSEP
] (
section 5.5.
and
section 5.6.
then
reject
with a newly
created
InvalidStateError
and abort these steps.
If
description
is set as a local description, if
description
.type
is
offer
and
description
.sdp
is not equal to
connection
's
[[LastOffer]]
slot, then
reject
with a newly
created
InvalidModificationError
and abort these steps.
If
description
is set as a local description, if
description
.type
is
"rollback"
and
signaling state
is
"stable"
then
reject
with a newly
created
InvalidStateError
and abort these steps.
If
description
is set as a local description, if
description
.type
is
"answer"
or
"pranswer"
and
description
.sdp
is not equal to
connection
's
[[LastAnswer]]
slot, then
reject
with a newly
created
InvalidModificationError
and abort these steps.
If the content of
description
is not valid SDP syntax, then
reject
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 the content of
description
is invalid, then
reject
with a newly
created
InvalidAccessError
and abort these steps.
For all other errors,
reject
with a newly
created
OperationError
If
description
is applied successfully, the user agent
MUST
queue a task that runs the following steps:
If
connection
's
[[IsClosed]]
slot is
true
, then abort these steps.
If
description
is set as a local description, then run one of the following steps:
If
description
is of type
"offer"
, set
connection
pendingLocalDescription
to
description
and
signaling state
to
"have-local-offer"
If
description
is of type
"answer"
, then this completes an offer answer negotiation. Set
connection
's
currentLocalDescription
to
description
and
currentRemoteDescription
to the value of
pendingRemoteDescription
. Set both
pendingRemoteDescription
and
pendingLocalDescription
to null. Finally set
connection
's
signaling state
to
"stable"
If
description
is of type
"rollback"
, then this is a rollback. Set
connection
pendingLocalDescription
to null and
signaling state
to
"stable"
If
description
is of type
"pranswer"
, then set
connection
pendingLocalDescription
to
description
and
signaling state
to
"have-local-pranswer"
Otherwise, if
description
is set as a remote description, then run one of the following steps:
If
description
is set as a remote description, if
description
.type
is
"rollback"
and
signaling state
is
"stable"
then
reject
with a newly
created
InvalidStateError
and abort these steps.
If
description
is of type
"offer"
, set
connection
pendingRemoteDescription
attribute to
description
and
signaling
state
to
"have-remote-offer"
If
description
is of type
"answer"
, then this completes an offer answer negotiation. Set
connection
's
currentRemoteDescription
to
description
and
currentLocalDescription
to the value of
pendingLocalDescription
. Set both
pendingRemoteDescription
and
pendingLocalDescription
to null. Finally set
connection
's
signaling state
to
"stable"
If
description
is of type
"rollback"
, then this is a rollback. Set
connection
pendingRemoteDescription
to null and
signaling state
to
"stable"
If
description
is of type
"pranswer"
, then set
connection
pendingRemoteDescription
to
description
and
signaling state
to
"have-remote-pranswer"
If
connection
's
signaling state
changed above, fire a simple event named
signalingstatechange
at
connection
If
description
is of type
"answer"
, and it initiates the closure of an existing SCTP association, as defined in [
SCTP-SDP
], Sections
10.3 and 10.4, set the value of
connection
's
[[SctpTransport]]
internal slot to
null
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 [
SCTP-SDP
], Sections 10.3 and 10.4, set the value of
connection
's
[[SctpTransport]]
internal slot to a newly created
RTCSctpTransport
If
description
negotiates the DTLS role of the SCTP transport, and there is an
RTCDataChannel
with a
null
id
, then generate an ID according to [
RTCWEB-DATA-PROTOCOL
]. If no available ID could be generated, then run the following steps:
Let
channel
be the
RTCDataChannel
object for which an ID could not be generated.
Set
channel
's
[[ReadyState]]
slot to
"closed"
Fire an event named
error
with an
OperationError
exception at
channel
Fire a simple event named
close
at
channel
If
description
is set as a local description, then run the following steps for each
media description
in
description
that is not yet
associated
with an
RTCRtpTransceiver
object:
Let
transceiver
be the
RTCRtpTransceiver
used to create the
media description
Set
transceiver
's
mid
value to the mid of the corresponding
media description
If
transceiver
's
[[Stopped]]
slot is
true
, abort these sub steps.
If
description
is of type
"answer"
or
"pranswer"
, then set
transceiver
's
[[CurrentDirection]]
slot to an
RTCRtpTransceiverDirection
value representing the direction of the corresponding
media description
If the
media description
is indicated as using an existing
media transport
according to [
BUNDLE
], let
transport
and
rtcpTransport
be the
RTCDtlsTransport
objects representing the RTP and RTCP components of that transport, respectively.
Otherwise, let
transport
and
rtcpTransport
be newly created
RTCDtlsTransport
objects, each with a new underlying
RTCIceTransport
. Though if RTCP multiplexing is negotiated according to [
RFC5761
], or if
connection
's
RTCRtcpMuxPolicy
is
require
, do not create any RTCP-specific transport objects, and instead let
rtcpTransport
equal
transport
Set
transceiver
[[Sender]]
[[SenderTransport]]
to
transport
Set
transceiver
[[Sender]]
[[SenderRtcpTransport]]
to
rtcpTransport
Set
transceiver
[[Receiver]]
[[ReceiverTransport]]
to
transport
Set
transceiver
[[Receiver]]
[[ReceiverRtcpTransport]]
to
rtcpTransport
If
description
is set as a remote description, then run the following steps:
Let
trackEvents
be an empty list.
Run the following steps for each
media description
in
description
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.
As described by
JSEP
] (
section 5.9.
, attempt
to find an existing
RTCRtpTransceiver
object,
transceiver
, to represent the
media
description
If no suitable transceiver is found (
transceiver
is unset), run the following steps:
Create an RTCRtpSender
sender
, from the
media description
Create an RTCRtpReceiver
receiver
, from the
media description
Create an RTCRtpTransceiver
with
sender
receiver
and
direction
set to
"recvonly"
, and let
transceiver
be the result.
Set
transceiver
's
mid
value to the mid of the corresponding
media description
. If the
media
description
has no MID, and
transceiver
's
mid
is unset, generate a random value as described in
JSEP
] (
section 5.9.
If
direction
is
"sendrecv"
or
"recvonly"
, and
transceiver
's
[[CurrentDirection]]
slot is neither
"sendrecv"
nor
"recvonly"
process the addition of a remote track
for the
media description
given
transceiver
and
trackEvents
If
direction
is
"sendonly"
or
"inactive"
, and
transceiver
's
[[CurrentDirection]]
slot is neither
"sendonly"
nor
"inactive"
process the removal of a remote track
for the
media description
given
transceiver
If
description
is of type
"answer"
or
"pranswer"
, then run the following steps:
Set
transceiver
's
[[CurrentDirection]]
slot to
direction
Let
transport
and
rtcpTransport
be the
RTCDtlsTransport
objects representing the RTP and RTCP components of the
media transport
used by
transceiver
's
associated
media description
according to [
BUNDLE
].
Set
transceiver
[[Sender]]
[[SenderTransport]]
to
transport
Set
transceiver
[[Sender]]
[[SenderRtcpTransport]]
to
rtcpTransport
Set
transceiver
[[Receiver]]
[[ReceiverTransport]]
to
transport
Set
transceiver
[[Receiver]]
[[ReceiverRtcpTransport]]
to
rtcpTransport
If the
media description
is rejected, and
transceiver
is not already stopped,
stop
the RTCRtpTransceiver
transceiver
For each
RTCTrackEvent
trackEvent
in
trackEvents
fire a track event
named
track
with
trackEvent
at the
connection
object.
If
description
is of type
"rollback"
, then run the following steps:
If the
mid
value of an
RTCRtpTransceiver
was set to a non-null value by the
RTCSessionDescription
that is being rolled back, set the
mid
value of that transceiver to null, as described by
JSEP
] (
section 4.1.8.2.
If an
RTCRtpTransceiver
was created by applying the
RTCSessionDescription
that is being rolled back, and a track has not been attached to it via
addTrack
, remove that transceiver from
connection
's
set of transceivers
as described by
JSEP
] (
section 4.1.8.2.
Restore the value of
connection
's
[[SctpTransport]]
internal slot to its value at the last
stable
signaling state
If
connection
's
signaling state
is now
"stable"
update the negotiation-needed
flag
. If
connection
's
[[NegotiationNeeded]]
slot was
true
both before and after this update, queue a task that runs the following
steps:
If
connection
's
[[IsClosed]]
slot is
true
, abort these steps.
If
connection
's
[[NegotiationNeeded]]
slot is
false
, abort these steps.
Fire a simple event named
negotiationneeded
at
connection
Resolve
with
undefined
Return
4.4.1.7
Set the configuration
To
set a configuration
, run the following steps:
Let
configuration
be the
RTCConfiguration
dictionary to be processed.
Let
connection
be the target
RTCPeerConnection
object.
If
configuration
.peerIdentity
is set and its value differs from the
target peer
identity
throw
an
InvalidModificationError
If
configuration
.certificates
is set and the set of certificates differs from the ones used when
connection
was constructed,
throw
an
InvalidModificationError
If the value of
configuration
bundlePolicy
differs from the
connection
's bundle policy,
throw
an
InvalidModificationError
If the value of
configuration
rtcpMuxPolicy
differs from the
connection
's rtcpMux policy,
throw
an
InvalidModificationError
If the value of
configuration
iceCandidatePoolSize
differs from the
connection
's previously set
iceCandidatePoolSize
, and
setLocalDescription
has already been called,
throw
an
InvalidModificationError
Set the
ICE Agent
's
ICE transports setting
to the value of
configuration
iceTransportPolicy
. As defined in
JSEP
] (
section 4.1.16.
, 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
JSEP
] (
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
JSEP
] (
section 4.1.16.
Let
validatedServers
be an empty list.
If
configuration
iceServers
is defined, then run the following steps for each element:
Let
server
be the current list element.
If
server
.urls
is a string, let
server
.urls
be a list consisting of just that string.
For each
url
in
server
.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
SyntaxError
. If the
scheme name
is not implemented by the browser
throw
NotSupportedError
. If
scheme name
is
turn
or
turns
, and parsing the
url
using the syntax defined in [
RFC7064
] fails,
throw
SyntaxError
. If
scheme
name
is
stun
or
stuns
, and parsing the
url
using the syntax defined in [
RFC7065
] fails,
throw
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
.credentialType
is
"password"
, and
server
.credential
is not a
DOMString
, then
throw
an
InvalidAccessError
and abort these steps.
If
scheme name
is
turn
or
turns
, and
server
.credentialType
is
"oauth"
, and
server
.credential
is not an
RTCOAuthCredential
, then throw an
InvalidAccessError
and abort these steps.
Append
server
to
validatedServers
Let
validatedServers
be the
ICE
Agent
's
ICE servers
list
As defined in
JSEP
] (
section 4.1.16.
, 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 the configuration in the
[[Configuration]]
internal slot.
4.4.2
Interface Definition
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.
Constructor
optional
RTCConfiguration
configuration
Exposed
Window
interface
RTCPeerConnection
EventTarget
Promise
RTCSessionDescriptionInit
createOffer
optional
RTCOfferOptions
options
);
Promise
RTCSessionDescriptionInit
createAnswer
optional
RTCAnswerOptions
options
);
Promise

setLocalDescription
RTCSessionDescriptionInit
description
);
readonly attribute
RTCSessionDescription
localDescription
readonly attribute
RTCSessionDescription
currentLocalDescription
readonly attribute
RTCSessionDescription
pendingLocalDescription
Promise

setRemoteDescription
RTCSessionDescriptionInit
description
);
readonly attribute
RTCSessionDescription
remoteDescription
readonly attribute
RTCSessionDescription
currentRemoteDescription
readonly attribute
RTCSessionDescription
pendingRemoteDescription
Promise

addIceCandidate
RTCIceCandidateInit
or
RTCIceCandidate
candidate
);
readonly attribute
RTCSignalingState
signalingState
readonly attribute
RTCIceGatheringState
iceGatheringState
readonly attribute
RTCIceConnectionState
iceConnectionState
readonly attribute
RTCPeerConnectionState
connectionState
readonly attribute
boolean
canTrickleIceCandidates
static
sequence
RTCIceServer
getDefaultIceServers
();
RTCConfiguration
getConfiguration
();
void
setConfiguration
RTCConfiguration
configuration
);
void
close
();
attribute
EventHandler
onnegotiationneeded
attribute
EventHandler
onicecandidate
attribute
EventHandler
onicecandidateerror
attribute
EventHandler
onsignalingstatechange
attribute
EventHandler
oniceconnectionstatechange
attribute
EventHandler
onicegatheringstatechange
attribute
EventHandler
onconnectionstatechange
};
Constructors
RTCPeerConnection
See the
RTCPeerConnection
constructor algorithm
Attributes
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
description.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 represents the local
RTCSessionDescription
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.
The
currentLocalDescription
attribute
MUST
return the last value that algorithms in this specification set it to, complete with any local candidates that have been generated by the
ICE Agent
since the offer or answer was created. Prior to being set, it returns null.
pendingLocalDescription
of type
RTCSessionDescription
, readonly,
nullable
The
pendingLocalDescription
attribute represents a local
RTCSessionDescription
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. This attribute is updated by
setLocalDescription
The
pendingLocalDescription
attribute
MUST
return the last value that algorithms in this specification set it to, complete with any local candidates that have been generated by the
ICE Agent
since the offer or answer was created. Prior to being set, it returns 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
description.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 represents the last remote
RTCSessionDescription
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.
The
currentRemoteDescription
attribute
MUST
return the value that algorithms in this specification set it to, complete with any remote candidates that have been supplied via
addIceCandidate()
since the offer or answer was created. Prior to being set, it returns null.
pendingRemoteDescription
of type
RTCSessionDescription
, readonly,
nullable
The
pendingRemoteDescription
attribute represents a remote
RTCSessionDescription
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. This attribute is updated by
setLocalDescription
The
pendingRemoteDescription
attribute
MUST
return the value that algorithms in this specification set it to, completed with any remote candidates that have been supplied via
addIceCandidate()
since the offer or answer was created. Prior to being set, it returns 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 [
TRICKLE-ICE
]. The value is determined based on whether a remote description indicates support
for trickle ICE, as defined in
JSEP
] (
section 4.1.15.
. Prior to the
completion of
setRemoteDescription
, this value is
null
onnegotiationneeded
of type
EventHandler
The event type of this event handler is
negotiationneeded
onicecandidate
of type
EventHandler
The event type of this event handler is
icecandidate
onicecandidateerror
of type
EventHandler
The event type of this event handler is
icecandidateerror
onsignalingstatechange
of type
EventHandler
The event type of this event handler is
signalingstatechange
oniceconnectionstatechange
of type
EventHandler
The event type of this event handler is
iceconnectionstatechange
onicegatheringstatechange
of type
EventHandler
The event type of this event handler is
icegatheringstatechange
onconnectionstatechange
of type
EventHandler
The event type of this event handler is
connectionstatechange
Methods
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 [
JSEP
]. As an offer, the generated SDP
will contain the full set of codec/RTP/RTCP capabilities supported 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 [
ICE
],
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 and as
input to requests for identity assertions.
If the
RTCPeerConnection
is configured to generate Identity assertions by calling
setIdentityProvider
, then the session description
SHALL
contain an appropriate assertion.
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
's
[[IsClosed]]
slot is
true
, return a promise
rejected
with a newly
created
InvalidStateError
If
connection
is configured with an identity provider, then begin
the identity
assertion request process
if it has not already begun.
Return the result of
enqueuing
the following steps to
connection
's operation queue:
Let
be a new promise.
In parallel, begin the
steps to create an
offer
, given
Return
The
steps to create an offer
given a promise
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.
Let
provider
be
connection
's currently configured identity provider if one has been configured, or
null
otherwise.
If
provider
is non-null, wait for
the
identity assertion request process
to complete.
If
provider
was unable to produce an identity assertion,
reject
with a newly
created
NotReadableError
and abort these steps.
Inspect the system state to determine the currently available resources as necessary for generating the offer, as described in
JSEP
] (
section 4.1.6.
If this inspection failed for any reason,
reject
with a newly
created
OperationError
and abort these steps.
Queue a task that runs the
final steps to create an
offer
, given
The
final steps to create an offer
given a promise
are as follows:
If
connection
's
[[IsClosed]]
slot is
true
, then abort these steps.
If
connection
was modified in such a way that additional inspection of the system state is necessary, or if its configured indentity provider is no longer
provider
, then in parallel begin the
steps to
create an offer
again, given
, and abort these steps.
Note
This may be necessary if, for example,
createOffer
was called when only an audio
RTCRtpTransceiver
was added to
connection
, but while performing the
steps
to create an offer
in parallel, 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, and the identity assertion from
provider
(if non-null), generate an SDP offer,
sdpString
, as described in
JSEP
] (
section 5.2.
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
[[LastOffer]]
internal slot to
sdpString
Resolve
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 [
JSEP
].
The generated SDP will also contain the
ICE agent
's
usernameFragment
password
and ICE options (as defined in [
ICE
],
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 and as
input to requests for identity assertions.
An answer can be marked as provisional, as described in
JSEP
] (
section 4.1.8.1.
, by setting the
type
to
"pranswer"
If the
RTCPeerConnection
is configured to generate Identity assertions by calling
setIdentityProvider
, then the session description
SHALL
contain an appropriate assertion.
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
's
[[IsClosed]]
slot is
true
, return a promise
rejected
with a newly
created
InvalidStateError
If
connection
is configured with an identity provider, then begin
the identity
assertion request process
if it has not already begun.
Return the result of
enqueuing
the following steps to
connection
's operation queue:
If
connection
's
signaling state
is neither
"have-remote-offer"
nor
"have-local-pranswer"
, return a promise
rejected
with a newly
created
InvalidStateError
Let
be a new promise.
In parallel, begin the
steps to create an
answer
, given
Return
The
steps to create an answer
given a promise
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.
Let
provider
be
connection
's currently configured identity provider if one has been configured, or
null
otherwise.
If
provider
is non-null, wait for
the
identity assertion request process
to complete.
If
provider
was unable to produce an identity assertion,
reject
with a newly
created
NotReadableError
and abort these steps.
Inspect the system state to determine the currently available resources as necessary for generating the answer, as described in
JSEP
] (
section 4.1.7.
If this inspection failed for any reason,
reject
with a newly
created
OperationError
and abort these steps.
Queue a task that runs the
final steps to create an
answer
, given
The
final steps to create an answer
given a promise
are as follows:
If
connection
's
[[IsClosed]]
slot is
true
, then abort these steps.
If
connection
was modified in such a way that additional inspection of the system state is necessary, or if its configured indentity provider is no longer
provider
, then in parallel begin the
steps to
create an answer
again, given
, and abort these steps.
Note
This may be necessary if, for example,
createAnswer
was called when an
RTCRtpTransceiver
's direction was
"recvonly"
, but while performing the
steps to create
an answer
in parallel, 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, and the identity assertion from
provider
(if non-null), generate an SDP answer,
sdpString
, as described in
JSEP
] (
section 5.3.
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
[[LastAnswer]]
internal slot to
sdpString
Resolve
with
answer
setLocalDescription
The
setLocalDescription
method instructs the
RTCPeerConnection
to apply the supplied
RTCSessionDescriptionInit
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.
As noted in
JSEP
] (
section 5.4.
the SDP returned from
createOffer
or
createAnswer
MUST NOT
be changed before passing it to
setLocalDescription
. As a result, when the method is invoked, the user agent
MUST
run the following steps:
Let
description
be the first argument to
setLocalDescription
Let
lastOffer
be the result returned by the last call to
createOffer
Let
lastAnswer
be the result returned by the last call to
createAnswer
If
description
.sdp
is the empty string and
description
.type
is
"answer"
or
"pranswer"
, set
description
.sdp
to
lastAnswer
If
description
.sdp
is the empty string and
description
.type
is
"offer"
, set
description
.sdp
to
lastOffer
Return the result of
setting
the RTCSessionDescription
indicated by
description
Note
As noted in
JSEP
] (
section 5.8.
, 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
return the result of
setting the
RTCSessionDescription
indicated by the method's first argument.
In addition, a remote description is processed to determine and verify the identity of the peer.
If an
a=identity
attribute is present in the session description, the browser
validates the identity
assertion.
If the "peerIdentity" configuration is applied to the
RTCPeerConnection
, this establishes a
target peer identity
of the provided value. Alternatively, if the
RTCPeerConnection
has previously authenticated the identity of the peer (that is, there is a current value for
peerIdentity
), then this also establishes a
target peer identity
The
target peer identity
cannot be changed once set. Once set, if a different value is provided, the user agent
MUST
reject
the returned promise with a newly
created
InvalidModificationError
and abort this operation. The
RTCPeerConnection
MUST
be closed if the validated peer identity does not match the
target peer
identity
If there is no
target peer identity
, then
setRemoteDescription
does not await the completion of identity validation.
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 both
sdpMid
and
sdpMLineIndex
are
null
, return a promise
rejected
with a newly
created
TypeError
Return the result of
enqueuing
the following steps to
connection
's operation queue:
If
remoteDescription
is
null
return a promise
rejected
with a newly
created
InvalidStateError
Let
be a new promise.
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
reject
with a newly
created
OperationError
and abort these steps.
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
reject
with a newly
created
OperationError
and abort these steps.
If
candidate
.usernameFragment
is neither
undefined
nor
null
, and is not equal to any username fragment present in the corresponding
media description
of an applied remote description,
reject
with a newly
created
OperationError
and abort these steps.
In parallel, add the ICE candidate
candidate
as described in
JSEP
] (
section 4.1.17.
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
candidate
could not be successfully added the user agent
MUST
queue a task that runs the following steps:
If
connection
's
[[IsClosed]]
slot is
true
, then abort these steps.
Reject
with a
DOMException
object whose
name
attribute has the value
OperationError
and abort these steps.
If
candidate
is applied successfully, the user agent
MUST
queue a task that runs the following steps:
If
connection
's
[[IsClosed]]
slot is
true
, then abort these steps.
If
connection
pendingRemoteDescription
is non-null, and represents the ICE
generation
for which
candidate
was processed, add
candidate
to
connection
pendingRemoteDescription
If
connection
currentRemoteDescription
is non-null, and represents the ICE
generation
for which
candidate
was processed, add
candidate
to
connection
currentRemoteDescription
Resolve
with
undefined
Return
getDefaultIceServers
Returns a list of ICE servers that are configured into the browser. A browser might be configured to use local or private STUN or TURN servers. This method allows an application to learn about these servers and optionally
use them.
This list is likely to be persistent and is the same across origins. It thus increases the fingerprinting surface of the browser. In privacy-sensitive contexts, browsers can consider mitigations such as only providing this
data to whitelisted origins (or not providing it at all.)
Note
Since the use of this information is left to the discretion of application developers, configuring a user agent with these defaults does not per se increase a user's ability to limit the exposure of their IP addresses.
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
JSEP
] (
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
's
[[IsClosed]]
slot 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.
If
connection
's
[[IsClosed]]
slot is
true
, abort these steps.
Set
connection
's
[[IsClosed]]
slot to
true
Set
connection
's
signaling state
to
"closed"
Let
transceivers
be the result of executing the
CollectTransceivers
algorithm. For every
RTCRtpTransceiver
transceiver
in
transceivers
, run the following steps:
If
transceiver
's
[[Stopped]]
slot is
true
, abort these steps.
Let
sender
be
transceiver
's
[[Sender]]
Let
receiver
be
transceiver
's
[[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
Set the
readyState
of
receiver
's
[[ReceiverTrack]]
to
"ended"
Set
transceiver
's
[[Stopped]]
slot to
true
Set the
[[ReadyState]]
slot of each of
connection
's
RTCDataChannel
s to
"closed"
Set the
[[SctpTransportState]]
slot of each of
connection
's
RTCSctpTransport
s 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"
4.4.3
Legacy Interface Extensions
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.
Note
The 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));
};
4.4.3.1
Method extensions
partial interface
RTCPeerConnection
Promise

createOffer
RTCSessionDescriptionCallback
successCallback
RTCPeerConnectionErrorCallback
failureCallback
optional
RTCOfferOptions
options
);
Promise

setLocalDescription
RTCSessionDescriptionInit
description
VoidFunction
successCallback
RTCPeerConnectionErrorCallback
failureCallback
);
Promise

createAnswer
RTCSessionDescriptionCallback
successCallback
RTCPeerConnectionErrorCallback
failureCallback
);
Promise

setRemoteDescription
RTCSessionDescriptionInit
description
VoidFunction
successCallback
RTCPeerConnectionErrorCallback
failureCallback
);
Promise

addIceCandidate
RTCIceCandidateInit
or
RTCIceCandidate
candidate
VoidFunction
successCallback
RTCPeerConnectionErrorCallback
failureCallback
);
};
Methods
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
be the resulting promise.
Upon
fulfillment
of
with value
offer
, invoke
successCallback
with
offer
as the argument.
Upon
rejection
of
with reason
, invoke
failureCallback
with
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
be the resulting promise.
Upon
fulfillment
of
, invoke
successCallback
with
undefined
as the argument.
Upon
rejection
of
with reason
, invoke
failureCallback
with
as the argument.
Return a promise
resolved
with
undefined
createAnswer
Note
The legacy
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
be the resulting promise.
Upon
fulfillment
of
with value
answer
, invoke
successCallback
with
answer
as the argument.
Upon
rejection
of
with reason
, invoke
failureCallback
with
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
be the resulting promise.
Upon
fulfillment
of
, invoke
successCallback
with
undefined
as the argument.
Upon
rejection
of
with reason
, invoke
failureCallback
with
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
be the resulting promise.
Upon
fulfillment
of
, invoke
successCallback
with
undefined
as the argument.
Upon
rejection
of
with reason
, invoke
failureCallback
with
as the argument.
Return a promise
resolved
with
undefined
Callback Definitions
These callbacks are only used on the legacy APIs.
RTCPeerConnectionErrorCallback
callback
RTCPeerConnectionErrorCallback
void
DOMException
error
);
Callback
RTCPeerConnectionErrorCallback
Parameters
error
of type
DOMException
An error object encapsulating information about what went wrong.
RTCSessionDescriptionCallback
callback
RTCSessionDescriptionCallback
void
RTCSessionDescriptionInit
description
);
Callback
RTCSessionDescriptionCallback
Parameters
description
of type
RTCSessionDescriptionInit
The object containing the SDP [
SDP
].
4.4.3.2
Legacy configuration extensions
partial dictionary
RTCOfferOptions
boolean
offerToReceiveAudio
boolean
offerToReceiveVideo
};
Attributes
offerToReceiveAudio
of type
boolean
Whenever this is given a non-false value, and the
RTCPeerConnection
has no non-stopped "sendrecv" or "recvonly" audio transceivers, createOffer()
MUST
as its first step invoke the equivalent of
addTransceiver("audio")
on the
RTCPeerConnection
object, except that this
MUST NOT
Update the negotiation-needed flag
, and, provided this does not fail,
proceed with createOffer()'s regular steps.
In all other situations, it will be disregarded.
offerToReceiveVideo
of type
boolean
Whenever this is given a non-false value, and the
RTCPeerConnection
has no non-stopped "sendrecv" or "recvonly" video transceivers, createOffer()
MUST
as its first step invoke the equivalent of
addTransceiver("video")
on the
RTCPeerConnection
object, except that this
MUST NOT
Update the negotiation-needed flag
, and, provided this does not fail,
proceed with createOffer()'s regular steps.
In all other situations, it will be disregarded.
4.4.4
Garbage collection
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.
4.5
Error Handling
4.5.1
General Principles
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.
Legacy-methods may only throw exceptions to indicate invalid state and other programming errors. For example, when a legacy-method is called when the
RTCPeerConnection
is in an invalid state or a state in which that particular method is not allowed to be executed, it will throw an exception. In all other cases, legacy methods
MUST
provide an error object to the
error callback.
4.6
Session Description Model
4.6.1
RTCSdpType
The RTCSdpType enum describes the type of an
RTCSessionDescriptionInit
or
RTCSessionDescription
instance.
enum
RTCSdpType
"offer"
"pranswer"
"answer"
"rollback"
};
Enumeration description
offer
An
RTCSdpType
of
offer
indicates that a description
MUST
be treated as an [
SDP
] offer.
pranswer
An
RTCSdpType
of
pranswer
indicates that a description
MUST
be treated as an [
SDP
] answer, but not a
final answer. A description used as an SDP
pranswer
may be applied as a response to an SDP offer, or an update to a previously sent SDP pranswer.
answer
An
RTCSdpType
of
answer
indicates that a description
MUST
be treated as an [
SDP
] final answer, and the
offer-answer exchange
MUST
be considered complete. A description used as an SDP answer may be applied as a response to an SDP offer or as an update to a previously sent SDP
pranswer.
rollback
An
RTCSdpType
of
rollback
indicates that a description
MUST
be treated as canceling the current SDP negotiation and moving the SDP [
SDP
offer and answer back to what it was in the previous stable state. Note the local or remote SDP descriptions in the previous stable state could be null if there has not yet been a successful offer-answer negotiation.
4.6.2
RTCSessionDescription
Class
The
RTCSessionDescription
class is used by
RTCPeerConnection
to expose local and remote session descriptions.
Constructor
RTCSessionDescriptionInit
descriptionInitDict
Exposed
Window
interface
RTCSessionDescription
readonly attribute
RTCSdpType
type
readonly attribute
DOMString
sdp
Default
object
toJSON
();
};
Constructors
RTCSessionDescription
The
RTCSessionDescription()
constructor takes a dictionary argument,
descriptionInitDict
, whose content is used to initialize the new
RTCSessionDescription
object. This constructor is deprecated; it exists for legacy compatibility reasons only.
Attributes
type
of type
RTCSdpType
, readonly
The type of this RTCSessionDescription.
sdp
of type
DOMString
, readonly
The string representation of the SDP [
SDP
].
Methods
toJSON()
When called, run [
WEBIDL
]'s
default toJSON
operation
dictionary
RTCSessionDescriptionInit
required
RTCSdpType
type
DOMString
sdp
""
};
Dictionary
RTCSessionDescriptionInit
Members
type
of type
RTCSdpType
, required
DOMString sdp
sdp
of type
DOMString
The string representation of the SDP [
SDP
]; if
type
is
"rollback"
, this member is unused.
4.7
Session Negotiation Model
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.
4.7.1
Setting Negotiation-Needed
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.
4.7.2
Clearing Negotiation-Needed
This section is non-normative.
The negotiation-needed flag is cleared when an
RTCSessionDescription
of type "answer"
is applied
, 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.
4.7.3
Updating the Negotiation-Needed flag
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
queue a task to
update the negotiation-needed
flag
To
update the negotiation-needed flag
for
connection
, run the following steps:
If
connection
's
[[IsClosed]]
slot is
true
, abort these steps.
If
connection
's
signaling state
is not
"stable"
, abort these steps.
Note
The negotiation-needed flag will be updated once the state transitions to "stable", as part of the steps for
setting an RTCSessionDescription
If the result of
checking if negotiation is needed
is
false
clear the negotiation-needed flag
by setting
connection
's
[[NegotiationNeeded]]
slot to
false
, and abort these steps.
If
connection
's
[[NegotiationNeeded]]
slot is already
true
, abort these steps.
Set
connection
's
[[NegotiationNeeded]]
slot to
true
Queue a task that runs the following steps:
If
connection
's
[[IsClosed]]
slot is
true
, abort these steps.
If
connection
's
[[NegotiationNeeded]]
slot is
false
, abort these steps.
Fire a simple event named
negotiationneeded
at
connection
Note
This queueing prevents
negotiationneeded
from firing prematurely, in the common situation where multiple modifications to
connection
are being made at once.
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
Let
description
be
connection
's
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
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
's
[[Direction]]
slot is
"sendrecv"
or
"sendonly"
, and the
associated
m= section in
description
doesn't contain an "a=msid"
line, return
true
If
description
is of type
"offer"
, and the direction of the
associated
m= section in neither
connection
's
currentLocalDescription
nor
currentRemoteDescription
matches
transceiver
's
[[Direction]]
slot, return
true
If
description
is of type
"answer"
, and the direction of the
associated
m= section in the
description
does
not match
transceiver
's
[[Direction]]
slot intersected with the offered direction (as described in
JSEP
] (
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
's
currentLocalDescription
or
currentRemoteDescription
, return
true
If all the preceding checks were performed and
true
was not returned, nothing remains to be negotiated; return
false
4.8
Interfaces for Connectivity Establishment
4.8.1
RTCIceCandidate
Interface
This interface describes an ICE candidate, described in [
ICE
] 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.
Constructor
optional
RTCIceCandidateInit
candidateInitDict
Exposed
Window
interface
RTCIceCandidate
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
ip
readonly attribute
RTCIceProtocol
protocol
readonly attribute
unsigned short
port
readonly attribute
RTCIceCandidateType
type
readonly attribute
RTCIceTcpCandidateType
tcpType
readonly attribute
DOMString
relatedAddress
readonly attribute
unsigned short
relatedPort
readonly attribute
DOMString
usernameFragment
RTCIceCandidateInit
toJSON
();
};
Constructor
RTCIceCandidate
The
RTCIceCandidate()
constructor takes a dictionary argument,
candidateInitDict
, whose content is used to initialize the new
RTCIceCandidate
object.
When invoked, run the following steps:
If both the
sdpMid
and
sdpMLineIndex
dictionary members in
candidateInitDict
are
null
throw
TypeError
Let
iceCandidate
be a newly created
RTCIceCandidate
object.
Initialize the following attributes of
iceCandidate
to
null
foundation
component
priority
ip
protocol
port
type
tcpType
relatedAddress
and
relatedPort
Set the
candidate
sdpMid
sdpMLineIndex
usernameFragment
attributes of
iceCandidate
with the corresponding dictionary member values of
candidateInitDict
Let
candidate
be the
candidate
dictionary member of
candidateInitDict
. If
candidate
is not an empty string, run the following steps:
Parse
candidate
using the
candidate-attribute
grammar.
If parsing of
candidate-attribute
has failed, abort these steps.
If any field in the parse result represents an invalid value for the corresponding attribute in
iceCandidate
, abort these steps.
Set the corresponding attributes in
iceCandidate
to the field values of the parsed result.
Return
iceCandidate
Note
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
Attributes
Most attributes below are defined in section 15.1 of [
ICE
].
candidate
of type
DOMString
, readonly
This carries the
candidate-attribute
as defined in section 15.1 of [
ICE
].
If this
RTCIceCandidate
represents an end-of-candidates indication,
candidate
is an empty string.
sdpMid
of type
DOMString
, readonly, nullable
If not
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
If not
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
A unique identifier that allows ICE to correlate candidates that appear on multiple
RTCIceTransport
s.
component
of type
RTCIceComponent
, readonly, nullable
The assigned network component of the candidate (
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
The assigned priority of the candidate.
ip
of type
DOMString
, readonly, nullable
The IP address of the candidate. This corresponds to the
connection-address
field in
candidate-attribute
Note
The IP 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 IP 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 IP 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 IP 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 IP addresses exposed to the application itself, browsers can offer their users different policies regarding sharing local IP addresses, as defined in [
RTCWEB-IP-HANDLING
].
protocol
of type
RTCIceProtocol
, readonly, nullable
The protocol of the candidate (
udp
tcp
). This corresponds to the
transport
field in
candidate-attribute
port
of type
unsigned short
, readonly, nullable
The port of the candidate.
type
of type
RTCIceCandidateType
, readonly, nullable
The type of the candidate. This corresponds to the
candidate-types
field in
candidate-attribute
tcpType
of type
RTCIceTcpCandidateType
, readonly,
nullable
If
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
For a candidate that is derived from another, such as a relay or reflexive candidate, the
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
For a candidate that is derived from another, such as a relay or reflexive candidate, the
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
This carries the
ufrag
as defined in section 15.4 of [
ICE
].
Methods
toJSON()
To invoke the
toJSON()
operation of the
RTCIceCandidate
interface, run the following steps:
Let
json
be a new
RTCIceCandidateInit
dictionary.
For each attribute identifier
attr
in «"candidate", "sdpMid", "sdpMLineIndex", "description"»:
Let
value
be the result of getting the underlying value of the attribute identified by
attr
, given this
RTCIceCandidate
object.
Set
json
attr
to
value
Return
json
dictionary
RTCIceCandidateInit
DOMString
candidate
""
DOMString
sdpMid
null
unsigned short
sdpMLineIndex
null
DOMString
usernameFragment
};
Dictionary
RTCIceCandidateInit
Members
candidate
of type
DOMString
, defaulting to
""
This carries the
candidate-attribute
as defined in section 15.1 of [
ICE
]. If this represents an end-of-candidates indication,
candidate
is an empty
string.
sdpMid
of type
DOMString
, nullable, defaulting to
null
If not
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
If not
null
, this indicates the index (starting at zero) of the
media description
in the SDP this candidate is associated with.
usernameFragment
of type
DOMString
This carries the
ufrag
as defined in section 15.4 of [
ICE
].
4.8.1.1
candidate-attribute
Grammar
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 [
ICE
]. 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.
4.8.1.2
RTCIceProtocol
Enum
The
RTCIceProtocol
represents the protocol of the ICE candidate.
enum
RTCIceProtocol
"udp"
"tcp"
};
Enumeration description
udp
A UDP candidate, as described in [
ICE
].
tcp
A TCP candidate, as described in [
RFC6544
].
4.8.1.3
RTCIceTcpCandidateType
Enum
The
RTCIceTcpCandidateType
represents the type of the ICE TCP candidate, as defined in [
RFC6544
].
enum
RTCIceTcpCandidateType
"active"
"passive"
"so"
};
Enumeration 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
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.
Note
The user agent will typically only gather
active
ICE TCP candidates.
4.8.1.4
RTCIceCandidateType
Enum
The
RTCIceCandidateType
represents the type of the ICE candidate, as defined in [
ICE
] section 15.1.
enum
RTCIceCandidateType
"host"
"srflx"
"prflx"
"relay"
};
Enumeration description
host
A host candidate, as defined in Section 4.1.1.1 of [
ICE
].
srflx
A server reflexive candidate, as defined in Section 4.1.1.2 of [
ICE
].
prflx
A peer reflexive candidate, as defined in Section 4.1.1.2 of [
ICE
].
relay
A relay candidate, as defined in Section 7.1.3.2.1 of [
ICE
].
4.8.2
RTCPeerConnectionIceEvent
The
icecandidate
event of the RTCPeerConnection uses the
RTCPeerConnectionIceEvent
interface.
Firing an
ice candidate event named
with an
RTCIceCandidate
candidate
means that an event with the name
, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the
RTCPeerConnectionIceEvent
interface with the
candidate
attribute set to the new ICE candidate,
MUST
be created and dispatched at the given target.
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.
Note
The
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 [
TRICKLE-ICE
].
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.
Constructor
DOMString
type
optional
RTCPeerConnectionIceEventInit
eventInitDict
Exposed
Window
interface
RTCPeerConnectionIceEvent
Event
readonly attribute
RTCIceCandidate
candidate
readonly attribute
DOMString
url
};
Constructors
RTCPeerConnectionIceEvent
Attributes
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.
Note
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
dictionary
RTCPeerConnectionIceEventInit
EventInit
RTCIceCandidate
candidate
DOMString
url
};
Dictionary
RTCPeerConnectionIceEventInit
Members
candidate
of type
RTCIceCandidate
, nullable
See the
candidate
attribute of the
RTCPeerConnectionIceEvent
interface.
url
of type
DOMString
, nullable
The
url
attribute is the STUN or TURN URL that identifies the STUN or TURN server used to gather this candidate.
4.8.3
RTCPeerConnectionIceErrorEvent
The
icecandidateerror
event of the RTCPeerConnection uses the
RTCPeerConnectionIceErrorEvent
interface.
Constructor
DOMString
type
RTCPeerConnectionIceErrorEventInit
eventInitDict
Exposed
Window
interface
RTCPeerConnectionIceErrorEvent
Event
readonly attribute
DOMString
hostCandidate
readonly attribute
DOMString
url
readonly attribute
unsigned short
errorCode
readonly attribute
USVString
errorText
};
Constructors
RTCPeerConnectionIceErrorEvent
Attributes
hostCandidate
of type
DOMString
, readonly
The
hostCandidate
attribute is the local IP address and port 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 use of multiple interfaces has been prohibited for privacy reasons, this attribute will be set to 0.0.0.0:0 or [::]:0, as appropriate.
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.
dictionary
RTCPeerConnectionIceErrorEventInit
EventInit
DOMString
hostCandidate
DOMString
url
required
unsigned short
errorCode
USVString
statusText
};
Dictionary
RTCPeerConnectionIceErrorEventInit
Members
hostCandidate
of type
DOMString
The local IP address and port used to communicate with the STUN or TURN server.
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.
statusText
of type
USVString
The STUN reason text returned by the STUN or TURN server.
4.9
Priority and QoS Model
Many applications have multiple media flows of the same data type and often some of the flows are more important than others. WebRTC uses the priority and Quality of Service (QoS) framework described in [
RTCWEB-TRANSPORT
] and [
TSVWG-RTCWEB-QOS
] to provide priority and DSCP marking for packets that will help provide
QoS in some networking environments. The priority setting can be used to indicate the relative priority of various flows. The priority API allows the JavaScript applications to tell the browser whether a particular media flow is high,
medium, low or of very low importance to the application by setting the
priority
property of
RTCRtpEncodingParameters
objects to one of the following values.
4.9.1
RTCPriorityType
Enum
enum
RTCPriorityType
"very-low"
"low"
"medium"
"high"
};
Enumeration description
very-low
See [
RTCWEB-TRANSPORT
], Section 4. Corresponds to "below normal" as defined in [
RTCWEB-DATA
].
low
See [
RTCWEB-TRANSPORT
], Section 4. Corresponds to "normal" as defined in [
RTCWEB-DATA
].
medium
See [
RTCWEB-TRANSPORT
], Section 4. Corresponds to "high" as defined in [
RTCWEB-DATA
].
high
See [
RTCWEB-TRANSPORT
], Section 4. Corresponds to "extra high" as defined in [
RTCWEB-DATA
].
Applications that use this API should be aware that often better overall user experience is obtained by lowering the priority of things that are not as important rather than raising the priority of the things that are.
4.10
Certificate Management
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.
partial interface
RTCPeerConnection
static
Promise
RTCCertificate
generateCertificate
AlgorithmIdentifier
keygenAlgorithm
);
};
Methods
generateCertificate
, static
The
generateCertificate
function causes the
user agent
to create and store an X.509 certificate [
X509V3
] and corresponding private key. A handle to information is provided in the form of the
RTCCertificate
interface. The returned
RTCCertificate
can be used to control the certificate that is offered in the DTLS sessions established by
RTCPeerConnection
The
keygenAlgorithm
argument is used to control how the private key associated with the certificate is generated. The
keygenAlgorithm
argument uses the WebCrypto [
WebCryptoAPI
AlgorithmIdentifier
type. The
keygenAlgorithm
value
MUST
be a valid argument to
window.crypto.subtle.generateKey
; that is, the value
MUST
produce a non-error result when normalized according to the WebCrypto
algorithm normalization process
WebCryptoAPI
] with an operation name of
generateKey
and a [[
supportedAlgorithms
]]
value specific to production of certificates for
RTCPeerConnection
. If the algorithm normalization process produces an error, the call to
generateCertificate
MUST
be rejected with that error.
Signatures produced by the generated key are used to authenticate the DTLS connection. The identified algorithm (as identified by the
name
of the normalized
AlgorithmIdentifier
MUST
be an asymmetric algorithm that can be used to produce a signature.
The certificate produced by this process also contains a signature. The validity of this signature is only relevant for compatibility reasons. Only the public key and the resulting certificate fingerprint are used by
RTCPeerConnection
, but it is more likely that a certificate will be accepted if the certificate is well formed. The browser selects the algorithm used to sign the certificate; a browser
SHOULD
select SHA-256 [
FIPS-180-4
] if a hash algorithm is needed.
The resulting certificate
MUST NOT
include information that can be linked to a user or
user agent
. Randomized
values for distinguished name and serial number
SHOULD
be used.
user agent
MUST
reject a call to
generateCertificate()
with a
DOMException
of type
NotSupportedError
if the
keygenAlgorithm
parameter identifies an algorithm that the
user agent
cannot or will not use to generate a certificate for
RTCPeerConnection
The following values
MUST
be supported by a
user agent
{ name: "
RSASSA-PKCS1-v1_5
",
modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]),
hash: "SHA-256" }
, and
{ name: "
ECDSA
",
namedCurve: "
P-256
Note
It is expected that a
user agent
will have a small or even fixed set of values that it will accept.
4.10.1
RTCCertificateExpiration
Dictionary
RTCCertificateExpiration
is used to set an expiration date on certificates generated by
generateCertificate
dictionary
RTCCertificateExpiration
EnforceRange
DOMTimeStamp
expires
};
expires
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 that the
RTCCertificate
is valid for relative to the current time.
When
generateCertificate
is called with an
object
argument, the
user agent
attempts to convert the object into an
RTCCertificateExpiration
. If this is unsuccessful, immediately return a promise that is
rejected
with a newly
created
TypeError
and abort processing.
user agent
generates a certificate that has an expiration date set to the current time plus the value of the
expires
attribute. The
expires
attribute of the returned
RTCCertificate
is set to the expiration time of the certificate. A
user agent
MAY
choose to limit the value of the
expires
attribute.
4.10.2
RTCCertificate
Interface
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 (
[[KeyingMaterial]]
) and a certificate (
[[Certificate]]
]]) that
RTCPeerConnection
uses to authenticate with a peer.
Exposed
Window
interface
RTCCertificate
readonly attribute
DOMTimeStamp
expires
static
sequence

getSupportedAlgorithms
();
sequence
RTCDtlsFingerprint
getFingerprints
();
};
Attributes
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
RTCPeerConnection
using this certificate fail.
Note that this value might not be reflected in a
notAfter
parameter in the certificate itself.
Methods
getSupportedAlgorithms
Returns a sequence providing a representative set of supported certificate algorithms. At least one algorithm
MUST
be returned.
Note
For example, the "RSASSA-PKCS1-v1_5" algorithm dictionary,
RsaHashedKeyGenParams
, contains fields for the modulus length, public exponent, and hash algorithm. Implementations are likely to support a wide range of modulus lengths and exponents, but a finite
number of hash algorithms. So in this case, it would be reasonable for the implementation to return one
AlgorithmIdentifier
for each supported hash algorithm that can be used with RSA, using default/recommended values for
modulusLength
and
publicExponent
(such as 1024 and 65537, respectively).
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.
Note that an
RTCCertificate
might not directly hold private keying material, this might be stored in a secure module.
The
RTCCertificate
object can be stored and retrieved from persistent storage by an application. When a
user agent
is required to obtain a structured clone
HTML51
] of an
RTCCertificate
object, it performs the following steps:
Let
input
and
memory
be the corresponding inputs defined by the internal structured cloning algorithm, where
input
represents an
RTCCertificate
object to be cloned.
Let
output
be a newly constructed
RTCCertificate
object.
Copy the value of the
expires
attribute from
input
to
output
Let the
[[Certificate]]
internal slot of
output
be set to the result of invoking the internal structured clone algorithm recursively on
the corresponding internal slots of
input
, with the slot contents as the new "
input
" argument and
memory
as the new "
memory
" argument.
Let the
[[KeyingMaterial]]
internal slot of
output
refer to the same private keying material represented by the
[[KeyingMaterial]]
internal slot of
input
5.
RTP Media API
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.
When sending media, the sender may need to rescale or resample the media to meet various requirements including the envelope negotiated by SDP.
Following the rules in
JSEP
] (
section 3.6.
, the video
MAY
be
downscaled in order to fit the SDP constraints. 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.
Note
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
scaleResolutionDownBy
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 ( https://tc39.github.io/ecma262/#eqn-floor).
What to transmit if the integer part of the scaled width or height is zero is implementation-specific.
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; volume, 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
, 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.
Note
There are several ways to initiate the sending of a
MediaStreamTrack
over a peer-to-peer connection. One way is to use the
addTrack
method on the
RTCPeerConnection
. Another way is to use the
replaceTrack
method on an existing
RTCRtpSender
. Yet another way is to create a new
RTCRtpSender
via the
addTransceiver
method (with or without a
MediaStreamTrack
argument). While
addTrack
checks if the
MediaStreamTrack
given as an argument is already being sent to avoid sending the same
MediaStreamTrack
twice, the other ways do not, allowing the same
MediaStreamTrack
(possibly using different
RTCRtpParameters
with different
RTCRtpSender
s) to be sent several times simultaneously. Doing this implies that at the receiving end of the peer-to-peer connection there are several
MediaStreamTrack
s with an identical
id
5.1
RTCPeerConnection Interface Extensions
The RTP media API extends the
RTCPeerConnection
interface as described below.
partial interface
RTCPeerConnection
sequence
RTCRtpSender
getSenders
();
sequence
RTCRtpReceiver
getReceivers
();
sequence
RTCRtpTransceiver
getTransceivers
();
RTCRtpSender
addTrack
MediaStreamTrack
track
MediaStream
...
streams
);
void
removeTrack
RTCRtpSender
sender
);
RTCRtpTransceiver
addTransceiver
MediaStreamTrack
or
DOMString
trackOrKind
optional
RTCRtpTransceiverInit
init
);
attribute
EventHandler
ontrack
};
Attributes
ontrack
of type
EventHandler
The event type of this event handler is
track
Methods
getSenders
Returns a sequence of
RTCRtpSender
objects representing the RTP senders that are currently attached to this
RTCPeerConnection
object.
The
getSenders
method
MUST
return the result of executing the
CollectSenders
algorithm.
We define the
CollectSenders
algorithm as follows:
Let
transceivers
be the result of executing the
CollectTransceivers
algorithm.
Let
senderset
be a new empty set.
For each
transceiver
in
transceivers
Let
sender
be
transceiver
's
[[Sender]]
Add
sender
to
senderset
Let
senders
be a new sequence consisting of all the
RTCRtpSender
objects in
senderset
. The conversion from the senders set to the sequence is user agent defined and the order does not have to be stable between calls.
Return
senders
getReceivers
Returns a sequence of
RTCRtpReceiver
objects representing the RTP receivers that are currently attached to this
RTCPeerConnection
object.
The
getReceivers
method
MUST
return the result of executing the
CollectReceivers
algorithm.
We define the
CollectReceivers
algorithm as follows:
Let
transceivers
be the result of executing the
CollectTransceivers
algorithm.
Let
receiverset
be a new empty set.
For each
transceiver
in
transceivers
Let
receiver
be
transceiver
's
[[Receiver]]
Add
receiver
to
receiverset
Let
receivers
be a new sequence consisting of all the
RTCRtpReceiver
objects in
receiverset
. The conversion from the receivers set to the sequence is user agent defined and the order does not have to be stable between calls.
Return
receivers
getTransceivers
Returns a sequence of
RTCRtpTransceiver
objects representing the RTP transceivers that are currently attached to this
RTCPeerConnection
object.
The
getTransceivers
method
MUST
return the result of executing the
CollectTransceivers
algorithm.
We define the
CollectTransceivers
algorithm as follows:
Let
transceivers
be a new sequence that represents a snapshot of all the
RTCRtpTransceiver
objects in this
RTCPeerConnection
object's
set of
transceivers
. The conversion from the transceiver set to the sequence is user agent defined and the order does not have to be stable between calls.
Return
transceivers
addTrack
Adds a new track to the
RTCPeerConnection
, and indicates that it is contained in the specified
MediaStream
s.
When the
addTrack
method is invoked, the user
agent
MUST
run the following steps:
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
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
's
[[IsClosed]]
slot 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 track added, as defined in
JSEP
] (
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
track
's kind.
The sender has never been used to send. More precisely, the
[[CurrentDirection]]
slot of the
RTCRtpTransceiver
associated with the sender has never had a value of
sendrecv
or
sendonly
If
sender
is not
null
, run the following steps to use that sender:
Set
sender
's
[[SenderTrack]]
to
track
Set
sender
's
[[AssociatedMediaStreams]]
to
streams
Let
transceiver
be the
RTCRtpTransceiver
associated with
sender
If
transceiver
's
[[Direction]]
slot is
recvonly
, set
transceiver
's
[[Direction]]
slot to
sendrecv
If
transceiver
's
[[Direction]]
slot is
inactive
, set
transceiver
's
[[Direction]]
slot to
sendonly
If
sender
is
null
, run the following steps:
Create an RTCRtpSender
with
track
and
streams
and let
sender
be the result.
Create an RTCRtpReceiver
with
track.kind
as 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 being marked with a
peerIdentity
option or anything that would make a track
CORS cross-origin
. These tracks can be supplied to the
addTrack
method, and have an
RTCRtpSender
created for them, but content
MUST NOT
be transmitted, unless they are also marked with
peerIdentity
and they meet the requirements for sending (see
isolated streams and
RTCPeerConnection
).
All other tracks that are not accessible to the application
MUST NOT
be sent to the peer, with silence (audio), black frames (video) or equivalently absent content being sent
in place of track content.
Note that this property can change over time.
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
JSEP
] (
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
muted
event is fired at the track.
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
's
[[IsClosed]]
slot 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 that it was removed due to
setting an RTCSessionDescription
of type "rollback"), then abort these steps.
If
sender
's
[[SenderTrack]]
is null, abort these steps.
Set
sender
's
[[SenderTrack]]
to null.
Let
transceiver
be the
RTCRtpTransceiver
object corresponding to
sender
If
transceiver
's
[[Direction]]
slot is
sendrecv
, set
transceiver
's
[[Direction]]
slot to
recvonly
If
transceiver
's
[[Direction]]
slot is
sendonly
, set
transceiver
's
[[Direction]]
slot 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
JSEP
] (
section 5.2.2.
The initial value of
mid
is null. Setting a new
RTCSessionDescription
may change it to a non-null value, as defined in
JSEP
] (
section 5.5.
and
section 5.6.
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
's
streams
member.
Let
sendEncodings
be
init
's
sendEncodings
member.
Let
direction
be
init
's
direction
member.
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
TypeError
Let
track
be
null
If the first argument is a
MediaStreamTrack
, let it be
track
and let
kind
be
track.kind
Verify that each
rid
value in
sendEncodings
is composed only of alphanumeric characters (a-z, A-Z, 0-9) up to a maximum of 16 characters. If one of the RIDs does not meet these requirements,
throw
TypeError
If any
RTCRtpEncodingParameters
dictionary in
sendEncodings
contains a
read-only parameter
other than
rid
throw
an
InvalidAccessError
Verify that each
scaleResolutionDownBy
value in
sendEncodings
is greater than or equal to 1.0. If one of the
scaleResolutionDownBy
values does not meet this requirement,
throw
RangeError
Create an RTCRtpSender
with
track
streams
and
sendEncodings
and let
sender
be the result.
If
sendEncodings
is set, then subsequent calls to
createOffer
will be configured to send multiple RTP encodings as defined in
JSEP
] (
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
JSEP
] (
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. This specification does not define how to
configure
createOffer
to receive multiple RTP encodings. However when
setRemoteDescription
is called with a corresponding remote description that is able to send multiple RTP encodings as defined in [
JSEP
], the
RTCRtpReceiver
may receive multiple RTP encodings and the parameters retrieved via the transceiver's
receiver.getParameters()
will reflect the encodings negotiated.
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
dictionary
RTCRtpTransceiverInit
RTCRtpTransceiverDirection
direction
"sendrecv"
sequence
MediaStream
streams
[]
sequence
RTCRtpEncodingParameters
sendEncodings
[]
};
Dictionary
RTCRtpTransceiverInit
Members
direction
of type
RTCRtpTransceiverDirection
defaulting to
"sendrecv"
The direction of the
RTCRtpTransceiver
streams
of type
sequence<
MediaStream
When the remote PeerConnection's ontrack event fires corresponding to the
RTCRtpReceiver
being added, these are the streams that will be put in the event.
sendEncodings
of type
sequence<
RTCRtpEncodingParameters
A sequence containing parameters for sending RTP encodings of media.
enum
RTCRtpTransceiverDirection
"sendrecv"
"sendonly"
"recvonly"
"inactive"
};
RTCRtpTransceiverDirection
Enumeration 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
. 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
. 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.
5.1.1
Processing Remote MediaStreamTracks
An application can reject incoming media descriptions by calling
RTCRtpTransceiver
.stop()
to stop both directions, or set the transceiver's direction to "sendonly" to reject only the incoming
side.
To
process the addition of a remote track
for an incoming media description
JSEP
] (
section 5.9.
given
RTCRtpTransceiver
transceiver
and
trackEvents
, the user agent
MUST
run the following steps:
Let
receiver
be
transceiver
's
[[Receiver]]
Let
track
be
receiver
's
[[ReceiverTrack]]
Set the associated remote streams
given
receiver
and a list of the MSIDs that the media description indicates
track
is to be associated with.
Let
streams
be
receiver
's
[[AssociatedRemoteMediaStreams]]
slot.
Add a new
RTCTrackEvent
with
transceiver
track
, and
streams
to
trackEvents
To
process the removal of a remote track
for an incoming media description
JSEP
] (
section 5.9.
given
RTCRtpTransceiver
transceiver
, the user agent
MUST
run the following steps:
Let
receiver
be
transceiver
's
[[Receiver]]
Let
track
be
receiver
's
[[ReceiverTrack]]
Set the associated remote streams
for the media description, given
receiver
and an empty list.
If
track.muted
is
false
update the muted state
of
track
with the value
true
To
set the associated remote streams
given
RTCRtpReceiver
receiver
and a list
msids
, the user agent
MUST
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
For each
stream
in
receiver
's
[[AssociatedRemoteMediaStreams]]
that is not present in
streams
, remove
track
from
stream
Note
This will result in a removetrack event being fired at each MediaStream as described in [
GETUSERMEDIA
].
For each
stream
in
streams
that is not present in
receiver
's
[[AssociatedRemoteMediaStreams]]
, add
track
to
stream
Note
This will result in an addtrack event being fired at each MediaStream as described in [
GETUSERMEDIA
].
Set
receiver
's
[[AssociatedRemoteMediaStreams]]
slot to
streams
5.2
RTCRtpSender
Interface
The
RTCRtpSender
interface allows an application to control how a given
MediaStreamTrack
is encoded and transmitted to a remote peer. When
setParameters
is called on an
RTCRtpSender
object, the encoding is changed appropriately.
To
create an RTCRtpSender
with a
MediaStreamTrack
track
, a list of
MediaStream
objects,
streams
, and optionally a list of
RTCRtpEncodingParameters
objects,
sendEncodings
, run the following steps:
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
[[SenderRtcpTransport]]
internal slot initialized to
null
Let
sender
have an
[[AssociatedMediaStreams]]
internal slot, representing a list of
MediaStream
objects that the
MediaStreamTrack
object of this sender is associated with. The
[[AssociatedMediaStreams]]
slot is used when
sender
is represented in SDP
as described in
JSEP
] (
section 5.2.1.
Set
sender
's
[[AssociatedMediaStreams]]
slot to
streams
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
RTCRtpEncodingParameters
with
active
set to
true
Note
Providing a single, default
RTCRtpEncodingParameters
allows the application to set encoding parameters using
setParameters
, even when simulcast isn't used.
Let
sender
have a
[[LastReturnedParameters]]
internal slot, which will be used to match
getParameters
and
setParameters
transactions.
Return
sender
Exposed
Window
interface
RTCRtpSender
readonly attribute
MediaStreamTrack
track
readonly attribute
RTCDtlsTransport
transport
readonly attribute
RTCDtlsTransport
rtcpTransport
// Feature at risk
static
RTCRtpCapabilities
getCapabilities
DOMString
kind
);
Promise

setParameters
optional
RTCRtpParameters
parameters
);
RTCRtpParameters
getParameters
();
Promise

replaceTrack
MediaStreamTrack
withTrack
);
Promise
RTCStatsReport
getStats
();
};
Attributes
track
of type
MediaStreamTrack
, readonly,
nullable
The
track
attribute is the track that is associated with this
RTCRtpSender
object. If
track
is ended, or if
track
muted
is set to
true
, the
RTCRtpSender
sends silence (audio) or a black frame (video). If
track
is null then the
RTCRtpSender
does not send.
On getting, the attribute
MUST
return the value of the
[[SenderTrack]]
slot.
transport
of type
RTCDtlsTransport
, readonly,
nullable
The
transport
attribute is the transport over which media from
track
is sent in the form of RTP packets. Prior to construction of the
RTCDtlsTransport
object, the
transport
attribute will be null. When bundling is used, multiple
RTCRtpSender
objects will share one
transport
and will all send RTP and RTCP over the same transport.
On getting, the attribute
MUST
return the value of the
[[SenderTransport]]
slot.
rtcpTransport
of type
RTCDtlsTransport
, readonly,
nullable
The
rtcpTransport
attribute is the transport over which RTCP is sent and received. Prior to construction of the
RTCDtlsTransport
object, the
rtcpTransport
attribute will be null. When RTCP mux is used (or bundling, which mandates RTCP mux),
rtcpTransport
will be null, and both RTP and RTCP traffic will flow over the transport described by
transport
On getting, the attribute
MUST
return the value of the
[[SenderRtcpTransport]]
slot.
Methods
getCapabilities
, static
The
getCapabilities()
method
returns the most optimistic view of the capabilities of the system for sending media of the given kind. It does not reserve any resources, ports, or other state but is meant to provide a way to discover the types of capabilities
of the browser including which codecs may be supported. User agents
MUST
support
kind
values of
"audio"
and
"video"
. If the system has no capabilities corresponding to the value of the
kind
argument,
getCapabilities
returns
null
These capabilities provide generally persistent cross-origin information on the device and thus increases the fingerprinting surface of the application. In privacy-sensitive contexts, browsers can consider mitigations such
as reporting only a common subset of the capabilities.
setParameters
The
setParameters
method updates how
track
is encoded and transmitted to a remote peer.
When the
setParameters
method is called, the user agent
MUST
run the following steps:
Let
parameters
be the method's first argument.
Let
sender
be the
RTCRtpSender
object on which
setParameters
is invoked.
Let
transceiver
be the
RTCRtpTransceiver
object associated with
sender
(i.e.
sender
is
transceiver
's
[[Sender]]
).
Let
be the number of
RTCRtpEncodingParameters
stored in
sender
's internal
[[SendEncodings]]
slot.
If
transceiver
's
[[Stopped]]
slot is
true
, return a promise
rejected
with a newly
created
InvalidStateError
If
sender
's
[[LastReturnedParameters]]
internal slot is empty, meaning
getParameters
has never been called, return a promise
rejected
with a newly
created
InvalidStateError
If
parameters
.encodings.length
is different from
, or if any parameter in
parameters
, is marked as a
Read-only parameter
has a value that is different from the corresponding parameter value in
sender
's
[[LastReturnedParameters]]
internal slot, return a promise
rejected
with a newly
created
InvalidModificationError
. Note that this also applies to
transactionId
For each value of
from 0 to the number of encodings, check whether
parameters
.encodings[
].codecPayloadType
(if set) corresponds to a value of
parameters
.codecs[
].payloadType
where
goes from 0 to the number of codecs. If there is no correspondence, or if the MIME subtype portion of
parameters
.codecs[
].mimeType
is equal to "red", "cn", "telephone-event", "rtx" or a forward error correction codec ("ulpfec" [
RFC5109
or "flexfec" [
FLEXFEC
]), reject
with a newly
created
InvalidAccessError
If the
scaleResolutionDownBy
parameter in the
parameters
argument has a value less than 1.0, return a promise
rejected
with a newly
created
RangeError
Let
be a new promise.
In parallel, configure the media stack to use
parameters
to transmit
sender
's
[[SenderTrack]]
If the media stack is successfully configured with
parameters
, queue a task to run the following steps:
Set
sender
's internal
[[SendEncodings]]
slot to
parameters
.encodings
Resolve
with
undefined
If any error occurred while configuring the media stack, queue a task to run the following steps:
If an error occurred due to hardware resources not being available,
reject
with a newly created
RTCError
whose
errorDetail
is set to "hardware-encoder-not-available" and abort these steps.
If an error occurred due to a hardware encoder not supporting
parameters
reject
with a newly created
RTCError
whose
errorDetail
is set to "hardware-encoder-error" and abort these steps.
For all other errors,
reject
with a newly
created
OperationError
Return
If the application selects a codec via
codecPayloadType
, and this codec is removed from a subsequent offer/answer negotiation,
codecPayloadType
will be unset in the next call to
getParameters
, and the implementation will fall back to its default codec selection policy until a new codec is selected.
setParameters
does not cause SDP renegotiation and can only be used to change what the media stack is sending or receiving within the envelope negotiated by Offer/Answer. The attributes in the
RTCRtpParameters
dictionary are designed to not enable this, so attributes like
cname
that cannot be changed are read-only. Other things, like bitrate, are controlled using limits such as
maxBitrate
, where the user agent needs to ensure it does not exceed the maximum bitrate specified by
maxBitrate
, while at the same time making sure it satisfies constraints on bitrate specified in other places such as the SDP.
getParameters
The
getParameters()
method returns
the
RTCRtpSender
object's current parameters for how
track
is encoded and transmitted to a remote
RTCRtpReceiver
When
getParameters
is called, the
RTCRtpParameters
dictionary is constructed as follows:
transactionId
is set to a new unique identifier, used to match this
getParameters
call to a
setParameters
call that may occur later.
encodings
is set to the value of the
[[SendEncodings]]
internal slot.
The
headerExtensions
sequence is populated based on the header extensions that have been negotiated for sending.
The
codecs
sequence is populated based on the codecs that have been negotiated for sending, and which the user agent is currently capable of sending.
rtcp
.cname
is set to the CNAME of the associated
RTCPeerConnection
rtcp
.reducedSize
is set to
true
if reduced-size RTCP has been negotiated for sending, and
false
otherwise.
degradationPreference
is set to the last value passed into
setParameters
, or the default value of "balanced" if
setParameters
hasn't been called.
The returned
RTCRtpParameters
dictionary
MUST
be stored in the
RTCRtpSender
object's
[[LastReturnedParameters]]
internal slot.
getParameters
may be used with
setParameters
to change the parameters in the following way:
Example 3
var
params = sender.getParameters();
// ... make changes to RTCRtpParameters
params.encodings[
].active =
false
sender.setParameters(params)
After a completed call to
setParameters
, subsequent calls to
getParameters
will return the modified set of parameters.
replaceTrack
Attempts to replace the track being sent with another track provided (or with a null track), without renegotiation.
To avoid track identifiers changing on the remote receiving end when a track is replaced, the sender
MUST
retain the original track identifier and stream associations and use these in subsequent
negotiations.
When the
replaceTrack
method is invoked,
the user agent
MUST
run the following steps:
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 that created
sender
If
connection
's
[[IsClosed]]
slot is
true
, return a promise
rejected
with a newly
created
InvalidStateError
and abort these steps.
If
transceiver
's
[[Stopped]]
slot is
true
, return a promise
rejected
with a newly
created
InvalidStateError
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
If
transceiver
is not yet
associated
with a
media description
, then set
sender
's
track
attribute to
withTrack
, and return a promise
resolved
with
undefined
Let
be a new promise.
Run the following steps in parallel:
Determine if negotiation is needed to transmit
withTrack
in place of the sender's existing track. Negotiation is not needed if
withTrack
is null or if the sender's existing track is ended (which appears as though the track was muted).
Ignore which
MediaStream
the track resides in and the
id
attribute of the track in this determination. If negotiation is needed, then
reject
with a newly
created
InvalidModificationError
and abort these steps.
If
withTrack
is null, have the sender stop sending, without negotiating. Otherwise, have the sender switch seamlessly to transmitting
withTrack
instead of the sender's existing track, without negotiating.
Queue a task that runs the following steps:
If
connection
's
[[IsClosed]]
slot is
true
, abort these steps.
Set
sender
's
track
attribute to
withTrack
Resolve
with
undefined
Return
Note
Changing dimensions and/or frame rates might not require negotiation. Cases that may require negotiation include:
Changing a resolution to a value outside of the negotiated imageattr bounds, as described in [
RFC6236
].
Changing a frame rate to a value that causes the block rate for the codec to be exceeded.
A video track differing in raw vs. pre-encoded format.
An audio track having a different number of channels.
Sources that also encode (typically hardware encoders) might be unable to produce the negotiated codec; similarly, software sources might not implement the codec that was negotiated for an encoding source.
getStats
Gathers stats for this sender only and reports the result asynchronously.
When the
getStats()
method is invoked, the user agent
MUST
run the following steps:
Let
selector
be the
RTCRtpSender
object on which the method was invoked.
Let
be a new promise, and run the following steps in parallel:
Gather the stats indicated by
selector
according to the
stats selection algorithm
Resolve
with the resulting
RTCStatsReport
object, containing the gathered stats.
Return
dictionary
RTCRtpParameters
DOMString
transactionId
sequence
RTCRtpEncodingParameters
encodings
sequence
RTCRtpHeaderExtensionParameters
headerExtensions
RTCRtcpParameters
rtcp
sequence
RTCRtpCodecParameters
codecs
RTCDegradationPreference
degradationPreference
};
Dictionary
RTCRtpParameters
Members
transactionId
of type
DOMString
An unique identifier for the last set of parameters applied. Ensures that setParameters can only be called based on a previous getParameters, and that there are no intervening changes.
Read-only parameter
encodings
of type
sequence<
RTCRtpEncodingParameters
A sequence containing parameters for RTP encodings of media.
headerExtensions
of type
sequence<
RTCRtpHeaderExtensionParameters
A sequence containing parameters for RTP header extensions.
Read-only parameter
rtcp
of type
RTCRtcpParameters
Parameters used for RTCP.
Read-only parameter
codecs
of type
sequence<
RTCRtpCodecParameters
A sequence containing the media codecs that an
RTCRtpSender
will choose from, as well as entries for RTX, RED and FEC mechanisms. Corresponding to each media codec where retransmission via RTX is enabled, there will be an entry in
codecs[]
with a
mimeType
attribute indicating retransmission via "audio/rtx" or "video/rtx", and an
sdpFmtpLine
attribute (providing the "apt" and "rtx-time" parameters).
Read-only parameter
degradationPreference
of type
RTCDegradationPreference
When bandwidth is constrained and the
RtpSender
needs to choose between degrading resolution or degrading framerate,
degradationPreference
indicates which is preferred. If unset, the
RtpSender
defaults to the
balanced
policy.
For an
RtpReceiver
degradationPreference
is inapplicable and will always be
undefined
dictionary
RTCRtpEncodingParameters
octet
codecPayloadType
RTCDtxStatus
dtx
boolean
active
true
RTCPriorityType
priority
"low"
unsigned long
ptime
unsigned long
maxBitrate
double
maxFramerate
DOMString
rid
double
scaleResolutionDownBy
};
Dictionary
RTCRtpEncodingParameters
Members
codecPayloadType
of type
octet
For an
RTCRtpSender
, used to select a codec to be sent. Must reference a payload type from the
codecs
member of
RTCRtpParameters
. If left unset, the implementation will select a codec according to its default policy. This field is not used for
RTCRtpReceiver
s.
dtx
of type
RTCDtxStatus
For an
RTCRtpSender
, indicates whether discontinuous transmission will be used. Setting it to
disabled
causes discontinuous transmission to be turned off. Setting it to
enabled
causes discontinuous transmission to be turned on if it was negotiated (either via a codec-specific parameter
or via negotiation of the CN codec); if it was not negotiated (such as when setting
voiceActivityDetection
to
false
), then discontinuous operation will be turned off regardless of the value of
dtx
, and media will be sent even when silence is detected. This attribute
is ignored by a receiver or video sender.
active
of type
boolean
, defaulting to
true
For an
RTCRtpSender
, indicates that this encoding is actively being sent. Setting it to
false
causes this encoding to no longer be sent. Setting it to
true
causes this encoding to be sent. For an
RTCRtpReceiver
, a value of
true
indicates that this encoding is being decoded. A value of
false
indicates this encoding is no longer being decoded.
priority
of type
RTCPriorityType
, defaulting to
"low"
Indicates the priority of this encoding. It is specified in [
RTCWEB-TRANSPORT
], Section 4.
ptime
of type
unsigned long
For an
RTCRtpSender
, indicates the preferred duration of media represented by a packet in milliseconds for this encoding. Typically, this is only relevant for audio encoding. The user agent
MUST
use this
duration if possible, and otherwise use the closest available duration. This value
MUST
take precedence over any "ptime" attribute in the remote description, whose processing is described
in
JSEP
] (
section 5.9.
. Note that the user agent
MUST
still respect the limit imposed by any "maxptime" attribute, as defined in [
RFC4566
], Section 6.
maxBitrate
of type
unsigned long
Indicates the maximum bitrate that can be used to send this encoding. The encoding may also be further constrained by other limits (such as maxFramerate or per-transport or per-session bandwidth limits) below the maximum specified
here. maxBitrate is computed the same way as the Transport Independent Application Specific Maximum (TIAS) bandwidth defined in [
RFC3890
] Section 6.2.2, which is the
maximum bandwidth needed without counting IP or other transport layers like TCP or UDP.
maxFramerate
of type
double
Indicates the maximum framerate that can be used to send this encoding, in frames per second.
rid
of type
DOMString
If set, this RTP encoding will be sent with the RID header extension as defined by
JSEP
] (
section 5.2.1.
The RID is not modifiable via
setParameters
. It can only be set or modified in
addTransceiver
scaleResolutionDownBy
of type
double
If the sender's
kind
is "video", the video's resolution will be scaled down in each dimension by the given value before sending. For example, if the value is 2.0, the video will be scaled down by a factor of 2
in each dimension, resulting in sending a video of one quarter the size. If the value is 1.0, the video will not be affected. The value must be greater than or equal to 1.0. By default, the sender will not apply any scaling,
(i.e.,
scaleResolutionDownBy
will be 1.0).
Usage of the attributes is defined in the table below:
Attribute
Type
Receiver/Sender
Read/Write
codecPayloadType
octet
Sender
Read/Write
dtx
RTCDtxStatus
Sender
Read/Write
active
boolean
Sender
Read/Write
priority
RTCPriorityType
Sender
Read/Write
ptime
unsigned long
Sender
Read/Write
maxBitrate
unsigned long
Sender
Read/Write
maxFramerate
double
Sender
Read/Write
scaleResolutionDownBy
double
Sender
Read/Write
rid
DOMString
Receiver/Sender
Read-only
enum
RTCDtxStatus
"disabled"
"enabled"
};
RTCDtxStatus
Enumeration description
disabled
Discontinuous transmission is disabled.
enabled
Discontinuous transmission is enabled if negotiated.
enum
RTCDegradationPreference
"maintain-framerate"
"maintain-resolution"
"balanced"
};
RTCDegradationPreference
Enumeration description
maintain-framerate
Degrade resolution in order to maintain framerate.
maintain-resolution
Degrade framerate in order to maintain resolution.
balanced
Degrade a balance of framerate and resolution.
dictionary
RTCRtcpParameters
DOMString
cname
boolean
reducedSize
};
Dictionary
RTCRtcpParameters
Members
cname
of type
DOMString
The Canonical Name (CNAME) used by RTCP (e.g. in SDES messages).
Read-only parameter
reducedSize
of type
boolean
Whether reduced size RTCP [
RFC5506
] is configured (if true) or compound RTCP as specified in [
RFC3550
] (if false).
Read-only parameter
dictionary
RTCRtpHeaderExtensionParameters
DOMString
uri
unsigned short
id
boolean
encrypted
};
Dictionary
RTCRtpHeaderExtensionParameters
Members
uri
of type
DOMString
The URI of the RTP header extension, as defined in [
RFC5285
].
Read-only parameter
id
of type
unsigned short
The value put in the RTP packet to identify the header extension.
Read-only parameter
encrypted
of type
boolean
Whether the header extension is encryted or not.
Read-only
parameter
dictionary
RTCRtpCodecParameters
octet
payloadType
DOMString
mimeType
unsigned long
clockRate
unsigned short
channels
DOMString
sdpFmtpLine
};
Dictionary
RTCRtpCodecParameters
Members
payloadType
of type
octet
The RTP payload type used to identify this codec.
Read-only
parameter
mimeType
of type
DOMString
The codec MIME media type/subtype. Valid media types and subtypes are listed in [
IANA-RTP-2
].
Read-only
parameter
clockRate
of type
unsigned long
The codec clock rate expressed in Hertz.
Read-only
parameter
channels
of type
unsigned short
The number of channels (mono=1, stereo=2).
Read-only
parameter
sdpFmtpLine
of type
DOMString
The "format specific parameters" field from the "a=fmtp" line in the SDP corresponding to the codec, if one exists, as defined by
JSEP
] (
section 5.7.
For an
RTCRtpSender
, these parameters come from the remote description, and for an
RTCRtpReceiver
, they come from the local description.
Read-only parameter
dictionary
RTCRtpCapabilities
sequence
RTCRtpCodecCapability
codecs
sequence
RTCRtpHeaderExtensionCapability
headerExtensions
};
Dictionary
RTCRtpCapabilities
Members
codecs
of type
sequence<
RTCRtpCodecCapability
Supported media codecs as well as entries for RTX, RED and FEC mechanisms. There will only be a single entry in
codecs[]
for retransmission via RTX, with
sdpFmtpLine
not present.
headerExtensions
of type
sequence<
RTCRtpHeaderExtensionCapability
Supported RTP header extensions.
dictionary
RTCRtpCodecCapability
DOMString
mimeType
unsigned long
clockRate
unsigned short
channels
DOMString
sdpFmtpLine
};
Dictionary
RTCRtpCodecCapability
Members
The
RTCRtpCodecCapability
dictionary provides information about codec capabilities. Only capability combinations that would utilize distinct payload types in a generated SDP offer are provided. For example:
Two H.264/AVC codecs, one for each of two supported packetization-mode values.
Two CN codecs with different clock rates.
mimeType
of type
DOMString
The codec MIME media type/subtype. Valid media types and subtypes are listed in [
IANA-RTP-2
].
clockRate
of type
unsigned long
The codec clock rate expressed in Hertz.
channels
of type
unsigned short
The maximum number of channels (mono=1, stereo=2).
sdpFmtpLine
of type
DOMString
The "format specific parameters" field from the "a=fmtp" line in the SDP corresponding to the codec, if one exists.
dictionary
RTCRtpHeaderExtensionCapability
DOMString
uri
};
Dictionary
RTCRtpHeaderExtensionCapability
Members
uri
of type
DOMString
The URI of the RTP header extension, as defined in [
RFC5285
].
5.3
RTCRtpReceiver
Interface
The
RTCRtpReceiver
interface allows an application to inspect the receipt of a
MediaStreamTrack
To
create an RTCRtpReceiver
with kind,
kind
, and optionally an id string,
id
, 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
Initialize
track.kind
to
kind
If an id string,
id
, was given as input to this algorithm, initialize
track.id
to
id
. (Otherwise the value generated when
track
was created will be used.)
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
[[ReceiverRtcpTransport]]
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.
Return
receiver
Exposed
Window
interface
RTCRtpReceiver
readonly attribute
MediaStreamTrack
track
readonly attribute
RTCDtlsTransport
transport
readonly attribute
RTCDtlsTransport
rtcpTransport
// Feature at risk
static
RTCRtpCapabilities
getCapabilities
DOMString
kind
);
RTCRtpParameters
getParameters
();
sequence
RTCRtpContributingSource
getContributingSources
();
sequence
RTCRtpSynchronizationSource
getSynchronizationSources
();
Promise
RTCStatsReport
getStats
();
};
Attributes
track
of type
MediaStreamTrack
, readonly
The
track
attribute is the track that is associated with this
RTCRtpReceiver
object
receiver
. When one of the SSRCs for RTP source media streams received by
receiver
is removed (either due to reception of a BYE or via timeout), the
mute
event is fired at
track
. If and when packets are received again, the
unmute
event is fired at
track
Note that
track.stop()
is final, although clones are not affected. Since
receiver
.track.stop()
does not implicitly stop
receiver
, Receiver Reports continue to be sent. On getting, the attribute
MUST
return the value of
the
[[ReceiverTrack]]
slot.
transport
of type
RTCDtlsTransport
, readonly,
nullable
The
transport
attribute is the transport over which media for the receiver's
track
is received in the form of RTP packets. Prior to construction of the
RTCDtlsTransport
object, the
transport
attribute will be null. When bundling is used, multiple
RTCRtpReceiver
objects will share one
transport
and will all receive RTP and RTCP over the same transport.
On getting, the attribute
MUST
return the value of the
[[ReceiverTransport]]
slot.
rtcpTransport
of type
RTCDtlsTransport
, readonly,
nullable
The
rtcpTransport
attribute is the transport over which RTCP is sent and
received. Prior to construction of the
RTCDtlsTransport
object, the
rtcpTransport
attribute will be null. When RTCP mux is used (or bundling, which mandates RTCP mux),
rtcpTransport
will be null, and both RTP and RTCP traffic will flow over
transport
On getting, the attribute
MUST
return the value of the
[[ReceiverRtcpTransport]]
slot.
Methods
getCapabilities
, static
The
getCapabilities()
method returns the most optimistic view of the capabilities of the system for receiving media of the given kind. It does not reserve any resources, ports, or other state but is meant to provide a way to discover the types
of capabilities of the browser including which codecs may be supported. User agents
MUST
support
kind
values of
"audio"
and
"video"
. If the system has no capabilities corresponding to the value of the
kind
argument,
getCapabilities
returns
null
These capabilities provide generally persistent cross-origin information on the device and thus increases the fingerprinting surface of the application. In privacy-sensitive contexts, browsers can consider mitigations such
as reporting only a common subset of the capabilities.
getParameters
The
getParameters()
method returns
the
RTCRtpReceiver
object's current parameters for how
track
is decoded.
When
getParameters
is called, the
RTCRtpParameters
dictionary is constructed as follows:
encodings
is populated based on RIDs present in the current remote description. Every member of the
RTCRtpEncodingParameters
dictionaries other than the RID fields is left
undefined
The
headerExtensions
sequence is populated based on the header extensions that the receiver is currently prepared to receive.
The
codecs
sequence is populated based on the codecs that the receiver is currently prepared to receive.
Note
Both the local and remote description may affect this list of codecs. For example, if three codecs are offered, the receiver will be prepared to receive each of them and will return them all from
getParameters
. But if the remote endpoint only answers with two, the absent codec will no longer be returned by
getParameters
as the receiver no longer needs to be prepared to receive
it.
rtcp
.reducedSize
is set to
true
if the receiver is currently prepared to receive reduced-size RTCP packets, and
false
otherwise.
rtcp
.cname
is left
undefined
transactionId
and
degradationPreference
are left
undefined
getContributingSources
Returns an
RTCRtpContributingSource
for each unique CSRC identifier received by this RTCRtpReceiver in the last 10 seconds.
getSynchronizationSources
Returns an
RTCRtpSynchronizationSource
for each unique SSRC identifier received by this RTCRtpReceiver in the last 10 seconds.
getStats
Gathers stats for this receiver only and reports the result asynchronously.
When the
getStats()
method is invoked, the user agent
MUST
run the following steps:
Let
selector
be the
RTCRtpReceiver
object on which the method was invoked.
Let
be a new promise, and run the following steps in parallel:
Gather the stats indicated by
selector
according to the
stats selection algorithm
Resolve
with the resulting
RTCStatsReport
object, containing the gathered stats.
Return
The
RTCRtpContributingSource
and
RTCRtpSynchronizationSource
objects contain information about a given contributing source
(CSRC) or synchronization source (SSRC), including the most recent time a packet that the source contributed to was played out. The browser
MUST
keep information from RTP packets received in the previous
10 seconds. When the first audio frame contained in an RTP packet is delivered to the
RTCRtpReceiver
's
MediaStreamTrack
for playout, the user agent
MUST
queue a task to update the relevant
RTCRtpContributingSource
and
RTCRtpSynchronizationSource
objects based on the contents of the packet. The
RTCRtpSynchronizationSource
object corresponding to the SSRC identifier is updated each time, and if the RTP packet contains CSRC identifiers, then the
RTCRtpContributingSource
objects corresponding to those CSRC identifiers are also updated.
Note
As stated in the
conformance
section
, requirements phrased as algorithms may be implemented in any manner so long as the end result is equivalent. So, an implementaion does not need to literally queue a task for every packet, as long as the end result is that within a single
event loop task execution, all
RTCRtpSynchronizationSource
and
RTCRtpContributingSource
objects for a particular
RTCRtpReceiver
return information from a single point in the RTP stream.
Exposed
Window
interface
RTCRtpContributingSource
readonly attribute
DOMHighResTimeStamp
timestamp
readonly attribute
unsigned long
source
readonly attribute
byte
audioLevel
};
Attributes
timestamp
of type
DOMHighResTimeStamp
, readonly
The timestamp of type DOMHighResTimeStamp [
HIGHRES-TIME
], indicating the most recent time of playout of an RTP packet containing the source. The timestamp is defined
in [
HIGHRES-TIME
] and corresponds to a local clock.
source
of type
unsigned long
, readonly
The CSRC identifier of the contributing source.
audioLevel
of type
byte
, readonly , nullable
The audio level contained in the last RTP packet played from this source.
audioLevel
will be the level value defined in [
RFC6465
] if the RFC 6465 header extension
is present, and otherwise
null
. RFC 6465 defines the level as a 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.
Exposed
Window
interface
RTCRtpSynchronizationSource
readonly attribute
DOMHighResTimeStamp
timestamp
readonly attribute
unsigned long
source
readonly attribute
byte
audioLevel
readonly attribute
boolean
voiceActivityFlag
};
Attributes
timestamp
of type
DOMHighResTimeStamp
, readonly
The timestamp of type DOMHighResTimeStamp [
HIGHRES-TIME
], indicating the most recent time of playout of an RTP packet from the source. The timestamp is defined in
HIGHRES-TIME
] and corresponds to a local clock.
source
of type
unsigned long
, readonly
The SSRC identifier of the synchronization source.
audioLevel
of type
byte
, readonly, nullable
The audio level contained in the last RTP packet played from this source.
audioLevel
will be the level value defined in [
RFC6464
], if the RFC 6464 header extension
is present. If the RFC 6464 extension header is not present, the browser will compute a value for
audioLevel
as if it had come from RFC 6464.
voiceActivityFlag
of type
boolean
, readonly, nullable
Whether the last RTP packet played from this source contains voice activity (true) or not (false). If the RFC 6464 extension header was not present, or if the peer has signaled that it is not using the V bit by setting the
"vad" extension attribute to "off", as described in [
RFC6464
], Section 4,
voiceActivityFlag
will be
null
5.4
RTCRtpTransceiver
Interface
The
RTCRtpTransceiver
interface represents a combination of an
RTCRtpSender
and an
RTCRtpReceiver
that share a common
mid
. As defined in
JSEP
] (
section 3.4.1.
, an
RTCRtpTransceiver
is said to be
associated
with a
media description
if its
mid
property is non-null; otherwise it is said to be disassociated. Conceptually, an
associated
transceiver is one that's represented in the last applied session description.
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
[[Stopped]]
internal slot, initialized to
false
Let
transceiver
have a
[[Direction]]
internal slot, initialized to
direction
Let
transceiver
have a
[[CurrentDirection]]
internal slot, initialized to null.
Return
transceiver
Note
Creating a transceiver does not create the underlying
RTCDtlsTransport
and
RTCIceTransport
objects. This will only occur as part of the process of
setting an
RTCSessionDescription
Exposed
Window
interface
RTCRtpTransceiver
readonly attribute
DOMString
mid
SameObject
readonly attribute
RTCRtpSender
sender
SameObject
readonly attribute
RTCRtpReceiver
receiver
readonly attribute
boolean
stopped
readonly attribute
RTCRtpTransceiverDirection
direction
readonly attribute
RTCRtpTransceiverDirection
currentDirection
void
setDirection
RTCRtpTransceiverDirection
direction
);
void
stop
();
void
setCodecPreferences
sequence
RTCRtpCodecCapability
codecs
);
};
Attributes
mid
of type
DOMString
, readonly, nullable
The
mid
attribute is the
mid
negotatiated and present in the local and remote
descriptions as defined in
JSEP
] (
section 5.2.1.
and
section 5.3.1.
Before negotiation is complete, the
mid
value may be null. After rollbacks, the value may change from a non-null value to null.
sender
of type
RTCRtpSender
, readonly
The
sender
attribute exposes the
RTCRtpSender
corresponding to the RTP media that may be sent with mid =
mid
. On getting, the attribute
MUST
return the value of the
[[Sender]]
slot.
receiver
of type
RTCRtpReceiver
, readonly
The
receiver
attribute is the
RTCRtpReceiver
corresponding to the RTP media that may be received with mid =
mid
. On getting the attribute
MUST
return the value of the
[[Receiver]]
slot.
stopped
of type
boolean
, readonly
The
stopped
attribute indicates that the sender of this transceiver will no longer send, and that the receiver will no longer receive. It is true if either
stop
has been called or if setting the local
or remote description has caused the
RTCRtpTransceiver
to be stopped. On getting, this attribute
MUST
return the value of the
[[Stopped]]
slot.
direction
of type
RTCRtpTransceiverDirection
readonly
As defined in
JSEP
] (
section 4.2.4.
, the
direction
attribute indicates the preferred direction of this transceiver, which will be used in calls to
createOffer
and
createAnswer
. On getting, this attribute
MUST
return the value of the
[[Direction]]
slot.
currentDirection
of type
RTCRtpTransceiverDirection
readonly, nullable
As defined in
JSEP
] (
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, or if the transceiver is
stopped
, the value is null. On getting, this attribute
MUST
return the value of the
[[CurrentDirection]]
slot.
Methods
setDirection
The
setDirection
method sets the
direction of the
RTCRtpTransceiver
. Calls to
setDirection()
do not take effect immediately. Instead, future calls to
createOffer
and
createAnswer
mark the corresponding
media description as
sendrecv
sendonly
recvonly
or
inactive
as defined in
JSEP
] (
section 5.2.2.
and
section 5.3.2.
Calling
setDirection()
updates the
negotiation-needed flag
for the
RTCRtpTransceiver
's associated
RTCPeerConnection
When this 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
's
[[IsClosed]]
slot is
true
throw
an
InvalidStateError
If
transceiver
's
[[Stopped]]
slot is
true
throw
an
InvalidStateError
Let
newDirection
be the argument to
setDirection
If
newDirection
is equal to
transceiver
's
[[Direction]]
slot, abort these steps.
Set
transceiver
's
[[Direction]]
slot to
newDirection
Update the negotiation-needed flag
for
connection
stop
The
stop
method irreversibly stops the
RTCRtpTransceiver
. The sender of this transceiver will no longer send, the receiver will no longer receive. Calling
stop()
updates the
negotiation-needed flag
for the
RTCRtpTransceiver
's associated
RTCPeerConnection
Stopping a transceiver will cause future calls to
createOffer
to generate a zero port in the
media description
for the corresponding
transceiver, as defined in
JSEP
] (
section 4.2.1
When this method is invoked, to
stop the
RTCRtpTransceiver
transceiver
, the user agent
MUST
run the following steps:
If
transceiver
's
[[Stopped]]
slot is
true
, abort these steps.
Let
connection
be the
RTCPeerConnection
object on which the
transceiver
is to be stopped.
If
connection
's
[[IsClosed]]
slot is
true
throw
an
InvalidStateError
Let
sender
be
transceiver
's
[[Sender]]
Let
receiver
be
transceiver
's
[[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
receiver
's
[[ReceiverTrack]]
is now said to be
ended
Set
transceiver
's
[[Stopped]]
slot to
true
Set
transceiver
's
[[CurrentDirection]]
slot to
null
Update the negotiation-needed flag
for
connection
When a remote description is applied with a zero port in the
media description
for the corresponding transceiver, as defined in
JSEP
] (
section 4.2.2
, the user agent
MUST
run the above steps
as if
stop
had been called. In addition, since the
receiver
's
[[ReceiverTrack]]
has ended, the steps described in
track ended
MUST
be followed.
setCodecPreferences
The
setCodecPreferences
method overrides the default codec preferences used by the
user agent
. When generating a session description using
either
createOffer
or
createAnswer
, the
user agent
MUST
use the indicated codecs, in the order specified in the
codecs
argument, for the media
section corresponding to this
RTCRtpTransceiver
. Note that calls to
createAnswer
will use only the common subset of these codecs and the codecs that appear in the offer.
This method allows applications to disable the negotiation of specific codecs. It also allows an application to cause a remote peer to prefer the codec that appears first in the list for sending.
Codec preferences remain in effect for all calls to
createOffer
and
createAnswer
that include this
RTCRtpTransceiver
until this method is called again. Setting
codecs
to an empty sequence resets codec preferences to any default
value.
The
codecs
sequence passed into
setCodecPreferences
can only contain codecs that are returned by
RTCRtpSender.getCapabilities(kind)
or
RTCRtpReceiver.getCapabilities(kind)
, where
kind
is the kind of the
RTCRtpTransceiver
on which the method is called. Additionally, the
RTCRtpCodecParameters
dictionary members cannot be modified. If
codecs
does not fulfill these requirements, the user
agent
MUST
throw
an InvalidAccessError.
5.4.1
"Hold" functionality
Together, the
setDirection
and
replaceTrack
methods enable developers to implement "hold" scenarios.
To send music to a peer and cease rendering received audio (music-on-hold):
Example 4
// Assume we have an audio transceiver and a music track named musicTrack
audio.sender.replaceTrack(musicTrack);
// Mute received audio
audio.receiver.track.enabled =
false
// Set the direction to send-only (requires negotiation)
audio.setDirection(
"sendonly"
);
To respond to a remote peer's "sendonly" offer:
Example 5
// Stop sending audio
audio.sender.replaceTrack(
null
);
// Set the direction recvonly (requires negotiation)
audio.setDirection(
"recvonly"
);
// Apply the sendonly offer, and then call createAnswer
// and send a recvonly answer
pc.setRemoteDescription(sendonlyOffer).then(doAnswer).catch(onSignalingError);
To stop sending music and send audio captured from a microphone, as well to render received audio:
Example 6
//assume we have an audio transceiver and a microphone track named micTrack
audio.sender.replaceTrack(micTrack);
// Unmute received audio
audio.receiver.track.enabled =
true
// // Set the direction to sendrecv (requires negotiation)
audio.setDirection(
"sendrecv"
);
To respond to being taken off hold by a remote peer:
Example 7
// Start sending audio
audio.sender.replaceTrack(micTrack);
// Set the direction sendrecv (requires negotiation)
audio.setDirection(
"sendrecv"
);
// Apply the sendrecv offer, and then call createAnswer
// and send a sendrecv answer
pc.setRemoteDescription(sendrecvOffer).then(doAnswer).catch(onSignalingError);
5.5
RTCDtlsTransport
Interface
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 [
BUNDLE
].
Note
A new DTLS association for an existing
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
When the underlying DTLS transport needs to update the state of the corresponding
RTCDtlsTransport
object, 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
's
[[DtlsTransportState]]
slot to
newState
Fire a simple event named
statechange
at
transport
Exposed
Window
interface
RTCDtlsTransport
EventTarget
readonly attribute
RTCIceTransport
transport
readonly attribute
RTCDtlsTransportState
state
sequence
ArrayBuffer
getRemoteCertificates
();
attribute
EventHandler
onstatechange
attribute
EventHandler
onerror
};
Attributes
transport
of type
RTCIceTransport
, readonly
The
transport
attribute is the underlying transport that is used to send and receive packets. The underlying transport may not be shared between multiple active
RTCDtlsTransport
objects.
state
of type
RTCDtlsTransportState
, readonly
The
state
attribute
MUST
, on getting, return the value of the
[[DtlsTransportState]]
slot.
onstatechange
of type
EventHandler
The event type of this event handler is
statechange
onerror
of type
EventHandler
The event type of this event handler is
error
Methods
getRemoteCertificates
Returns the certificate chain in use by the remote side, with each certificate encoded in binary Distinguished Encoding Rules (DER) [
X690
].
getRemoteCertificates()
will return an empty list prior to selection of the remote certificate, which will be completed by the time
RTCDtlsTransportState
transitions to "connected".
RTCDtlsTransportState
Enum
enum
RTCDtlsTransportState
"new"
"connecting"
"connected"
"closed"
"failed"
};
Enumeration description
new
DTLS has not started negotiating yet.
connecting
DTLS is in the process of negotiating a secure connection.
connected
DTLS has completed negotiation of a secure connection.
closed
The transport has been closed.
failed
The transport has failed as the result of an error (such as a failure to validate the remote fingerprint).
5.5.1
RTCDtlsFingerprint
Dictionary
The
RTCDtlsFingerprint
dictionary includes the hash function algorithm and certificate fingerprint as described in [
RFC4572
].
dictionary
RTCDtlsFingerprint
DOMString
algorithm
DOMString
value
};
Dictionary RTCDtlsFingerprint Members
algorithm
of type
DOMString
One of the the hash function algorithms defined in the 'Hash function Textual Names' registry, initially specified in [
RFC4572
] Section 8.
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.
5.6
RTCIceTransport
Interface
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 [
BUNDLE
].
Note
An ICE restart for an existing
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
's
[[IsClosed]]
slot is
true
, abort these steps.
Let
transport
be the
RTCIceTransport
for which candidate gathering began.
Set
transport
's
[[IceGathererState]]
slot to
gathering
Fire a simple event named
gatheringstatechange
at
transport
Update the ICE gathering state
of
connection
When the
ICE Agent
indicates that it finished 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
's
[[IsClosed]]
slot is
true
, abort these steps.
Let
transport
be the
RTCIceTransport
for which candidate gathering finished.
Create an
RTCIceCandidate
instance
newCandidate
, with
sdpMid
and
sdpMLineIndex
set to the values associated with this
RTCIceTransport
, with
usernameFragment
set to the username fragment of the
generation
of candidates for which gathering finished, with
candidate
set to an empty string, and with all other nullable members set to null.
Fire an ice candidate event
named
icecandidate
with
newCandidate
at
connection
If another
generation
of candidates is still being gathered, abort these steps.
Note
This may occur if an ICE restart is initiated while the ICE agent is still gathering the previous
generation
of candidates.
Set
transport
's
[[IceGathererState]]
slot to
complete
Fire a simple 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
connection
be the
RTCPeerConnection
object associated with this
ICE Agent
If
connection
's
[[IsClosed]]
slot is
true
, abort these steps.
Let
transport
be the
RTCIceTransport
for which this candidate is being made available.
If
connection
pendingLocalDescription
is non-null, and represents the ICE
generation
for which
candidate
was gathered, add
candidate
to
connection
pendingLocalDescription
If
connection
currentLocalDescription
is non-null, and represents the ICE
generation
for which
candidate
was gathered, add
candidate
to
connection
currentLocalDescription
Create an
RTCIceCandidate
instance to represent the candidate. Let
newCandidate
be that object.
Add
newCandidate
to
transport
's set of local candidates.
Fire an ice candidate event
named
icecandidate
with
newCandidate
at
connection
When the
ICE Agent
indicates that the
RTCIceTransportState
for an
RTCIceTransport
has changed, 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
's
[[IsClosed]]
slot is
true
, abort these steps.
Let
transport
be the
RTCIceTransport
whose state is changing.
Let
newState
be the new indicated
RTCIceTransportState
Set
transport
's
[[IceTransportState]]
slot to
newState
Fire a simple event named
statechange
at
transport
Update the ICE connection state
of
connection
Update the connection state
of
connection
When the
ICE Agent
indicates that the selected candidate pair for an
RTCIceTransport
has changed, 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
's
[[IsClosed]]
slot is
true
, abort these steps.
Let
transport
be the
RTCIceTransport
whose selected candidate pair is changing.
Let
newCandidatePair
be a newly created
RTCIceCandidatePair
representing the indicated pair if one is selected, and
null
otherwise.
Set
transport
's
[[SelectedCandidatePair]]
slot to
newCandidatePair
Fire a simple event named
selectedcandidatepairchange
at
transport
An
RTCIceTransport
object has the following internal slots:
[[IceTransportState]]
initialized to
new
[[IceGathererState]]
initialized to
new
[[SelectedCandidatePair]]
initialized to
null
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
};
Attributes
role
of type
RTCIceRole
, readonly
The
role
attribute
MUST
return the ICE role of the
transport.
component
of type
RTCIceComponent
, readonly
The
component
attribute
MUST
return the
ICE component of the transport. When RTCP mux is used, a single
RTCIceTransport
transports both RTP and RTCP and
component
is set to "RTP".
state
of type
RTCIceTransportState
, readonly
The
state
attribute
MUST
, on getting, return the
value of the
[[IceTransportState]]
slot.
gatheringState
of type
RTCIceGathererState
, readonly
The
gathering
state
attribute
MUST
, on getting, return the value of the
[[IceGathererState]]
slot.
onstatechange
of type
EventHandler
This event handler, of event handler event type
statechange
MUST
be fired any time the
RTCIceTransport
state changes.
ongatheringstatechange
of type
EventHandler
This event handler, of event handler event type
gatheringstatechange
MUST
be fired any time the
RTCIceTransport
gathering state changes.
onselectedcandidatepairchange
of type
EventHandler
This event handler, of event handler event type
selectedcandidatepairchange
MUST
be fired any time the
RTCIceTransport
's selected candidate pair changes.
Methods
getLocalCandidates
Returns a sequence describing the local ICE candidates gathered for this
RTCIceTransport
and sent in
onicecandidate
getRemoteCandidates
Returns a sequence describing the remote ICE candidates received by this
RTCIceTransport
via
addIceCandidate()
getSelectedCandidatePair
Returns the selected candidate pair on which packets are sent. This method
MUST
return the value of the
[[SelectedCandidatePair]]
slot.
getLocalParameters
Returns the local ICE parameters received by this
RTCIceTransport
via
setLocalDescription
, or
null
if the parameters have not yet been received.
getRemoteParameters
Returns the remote ICE parameters received by this
RTCIceTransport
via
setRemoteDescription
or
null
if the parameters have not yet been received.
dictionary
RTCIceParameters
DOMString
usernameFragment
DOMString
password
};
Dictionary
RTCIceParameters
Members
usernameFragment
of type
DOMString
The ICE username fragment as defined in [
ICE
], Section 7.1.2.3.
password
of type
DOMString
The ICE password as defined in [
ICE
], Section 7.1.2.3.
dictionary
RTCIceCandidatePair
RTCIceCandidate
local
RTCIceCandidate
remote
};
Dictionary
RTCIceCandidatePair
Members
local
of type
RTCIceCandidate
The local ICE candidate.
remote
of type
RTCIceCandidate
The remote ICE candidate.
RTCIceGathererState
Enum
enum
RTCIceGathererState
"new"
"gathering"
"complete"
};
Enumeration 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.
RTCIceTransportState
Enum
enum
RTCIceTransportState
"new"
"checking"
"connected"
"completed"
"failed"
"disconnected"
"closed"
};
Enumeration 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".
failed
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 have lost consent.
disconnected
The
ICE Agent
has determined that connectivity is currently lost for this
RTCIceTransport
. This is more aggressive than
failed
, and may trigger intermittently (and resolve itself without action) on a flaky network. The way this state is determined is implementation dependent. Examples include:
Losing the network interface for the connection in use.
Repeatedly failing to receive a response to STUN requests.
Alternatively, the
RTCIceTransport
has finished checking all existing candidates pairs and failed to find a connection (or consent checks [
RFC7675
] once successful, have now failed), but it is still
gathering and/or waiting for additional remote candidates.
closed
The
RTCIceTransport
has shut down and is no longer responding to STUN requests.
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 transitions might be:
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
(any state, ICE restart occurs):
new
RTCPeerConnection.close()
closed
Figure
Non-normative ICE transport state transition diagram
RTCIceRole
Enum
enum
RTCIceRole
"controlling"
"controlled"
};
Enumeration description
controlling
A controlling agent as defined by [
ICE
], Section 3.
controlled
A controlled agent as defined by [
ICE
], Section 3.
RTCIceComponent
Enum
enum
RTCIceComponent
"rtp"
"rtcp"
};
Enumeration description
rtp
The ICE Transport is used for RTP (or RTCP multiplexing), as defined in [
ICE
], Section 4.1.1.1. Protocols multiplexed with RTP (e.g. data channel) share its component ID. This
represents the
component-id
value
when encoded in
candidate-attribute
rtcp
The ICE Transport is used for RTCP as defined by [
ICE
], Section 4.1.1.1. This represents the
component-id
value
when encoded in
candidate-attribute
5.7
RTCTrackEvent
The
track
event uses the
RTCTrackEvent
interface.
Firing a
track event named
with an
RTCRtpReceiver
receiver
, a
MediaStreamTrack
track
and a
MediaStream
[]
streams
, means that an event with the name
, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the
RTCTrackEvent
interface with the
receiver
attribute set to
receiver
track
attribute set to
track
streams
attribute set to
streams
MUST
be created and dispatched at the given target.
Constructor
DOMString
type
RTCTrackEventInit
eventInitDict
Exposed
Window
interface
RTCTrackEvent
Event
readonly attribute
RTCRtpReceiver
receiver
readonly attribute
MediaStreamTrack
track
SameObject
readonly attribute
FrozenArray
MediaStream
streams
readonly attribute
RTCRtpTransceiver
transceiver
};
Constructors
RTCTrackEvent
Attributes
receiver
of type
RTCRtpReceiver
, readonly
The
receiver
attribute represents the
RTCRtpReceiver
object associated with the event.
track
of type
MediaStreamTrack
, readonly
The
track
attribute represents the
MediaStreamTrack
object that is associated with the
RTCRtpReceiver
identified by
receiver
streams
of type
FrozenArray<
MediaStream
readonly
The
streams
attribute returns an array of
MediaStream
objects representing the
MediaStream
s that this event's
track
is a part of.
transceiver
of type
RTCRtpTransceiver
, readonly
The
transceiver
attribute represents the
RTCRtpTransceiver
object associated with the event.
dictionary
RTCTrackEventInit
EventInit
required
RTCRtpReceiver
receiver
required
MediaStreamTrack
track
sequence
MediaStream
streams
[]
required
RTCRtpTransceiver
transceiver
};
Dictionary
RTCTrackEventInit
Members
receiver
of type
RTCRtpReceiver
, required
The
receiver
attribute represents the
RTCRtpReceiver
object associated with the event.
track
of type
MediaStreamTrack
, required
The
track
attribute represents the
MediaStreamTrack
object that is associated with the
RTCRtpReceiver
identified by
receiver
streams
of type
sequence<
MediaStream
defaulting to
[]
The
streams
attribute returns an array of
MediaStream
objects representing the
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.
6.
Peer-to-peer Data API
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 WebSockets [
WEBSOCKETS-API
].
6.1
RTCPeerConnection Interface Extensions
The Peer-to-peer data API extends the
RTCPeerConnection
interface as described below.
partial interface
RTCPeerConnection
readonly attribute
RTCSctpTransport
sctp
RTCDataChannel
createDataChannel
USVString
label
optional
RTCDataChannelInit
dataChannelDict
);
attribute
EventHandler
ondatachannel
};
Attributes
sctp
of type
RTCSctpTransport
, readonly,
nullable
The SCTP transport over which SCTP data is sent and received. If SCTP has not been negotiated, the value is null. This attribute
MUST
return the
RTCSctpTransport
object stored in the
[[SctpTransport]]
internal slot.
ondatachannel
of type
EventHandler
The event type of this event handler is
datachannel
Methods
createDataChannel
Creates a new
RTCDataChannel
object with the given label. The
RTCDataChannelInit
dictionary can be used to configure properties of the underlying channel such as
data reliability.
When the
createDataChannel
method is invoked, the user agent
MUST
run the following steps.
Let
connection
be the
RTCPeerConnection
object on which the method is invoked.
If
connection
's
[[IsClosed]]
slot is
true
throw
an
InvalidStateError
Let
channel
be a newly created
RTCDataChannel
object.
Let
channel
have a
[[DataChannelLabel]]
internal slot initialized to the value of the first argument.
If
[[DataChannelLabel]]
is longer than 65535 bytes,
throw
TypeError
Let
options
be the second argument.
Let
channel
have a
[[MaxPacketLifeTime]]
internal slot initialized to
option
's
maxPacketLifeTime
member, if present, otherwise
null
Let
channel
have a
[[ReadyState]]
internal slot initialized to
"connecting"
Let
channel
have a
[[MaxRetransmits]]
internal slot initialized to
option
's
maxRetransmits
member, if present, otherwise
null
Let
channel
have an
[[Ordered]]
internal slot initialized to
option
's
ordered
member.
Let
channel
have a
[[DataChannelProtocol]]
internal slot initialized to
option
's
protocol
member.
If
[[DataChannelProtocol]]
is longer than 65535 bytes long,
throw
TypeError
Let
channel
have a
[[Negotiated]]
internal slot initialized to
option
's
negotiated
member.
Let
channel
have an
[[DataChannelId]]
internal slot initialized to
option
's
id
member, if it is present and
[[Negotiated]]
is true, otherwise
null
Note
This means the
id
member will be ignored if the data channel is negotiated in-band; this is intentional. Data channels negotiated in-band should have IDs selected based on the DTLS role, as specified
in [
RTCWEB-DATA-PROTOCOL
].
If
[[Negotiated]]
is
true
and
[[DataChannelId]]
is
null
throw
TypeError
Let
channel
have an
[[DataChannelPriority]]
internal slot initialized to
option
's
priority
member.
If both
[[MaxPacketLifeTime]]
and
[[MaxRetransmits]]
attributes are set (not null),
throw
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
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 [
RTCWEB-DATA-PROTOCOL
],
and skip to the next step. If no available ID could be generated, or if the value of the
[[DataChannelId]]
slot is being used
by an existing
RTCDataChannel
throw
an
OperationError
exception.
Note
If the
[[DataChannelId]]
slot is
null
after this step, it will be populated once the DTLS role is determined
during the process of
setting an
RTCSessionDescription
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
6.1.1
RTCSctpTransport
Interface
The
RTCSctpTransport
interface allows an application access to information about the SCTP data channels tied to a particular SCTP association.
Exposed
Window
interface
RTCSctpTransport
readonly attribute
RTCDtlsTransport
transport
readonly attribute
RTCSctpTransportState
state
readonly attribute
unsigned long
maxMessageSize
attribute
EventHandler
onstatechange
};
Attributes
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, it returns the value of the
[[SctpTransportState]]
internal slot.
maxMessageSize
of type
unsigned long
, readonly
The maximum size of data that can be passed to
RTCDataChannel
's
send()
method.
onstatechange
of type
EventHandler
The event type of this event handler is
statechange
6.1.2
RTCSctpTransportState
Enum
RTCSctpTransportState
indicates the state of the SCTP transport.
enum
RTCSctpTransportState
"new"
"connecting"
"connected"
"closed"
};
Enumeration description
new
The
RTCSctpTransport
has not started negotiating yet.
connecting
The
RTCSctpTransport
is in the process of negotiating an association. This is the initial state when an
RTCSctpTransport
is created by applying an Answer.
connected
The
RTCSctpTransport
has completed negotiation of an association.
closed
The SCTP association has been closed intentionally (such as by closing the peer connection or applying a remote description that rejects data or changes the SCTP port) or via receipt of a SHUTDOWN or ABORT chunk.
6.2
RTCDataChannel
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 [
RTCWEB-DATA
] and [
RTCWEB-DATA-PROTOCOL
].
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. 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 [
RTCWEB-DATA
].
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
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.
Set
channel
's
[[ReadyState]]
slot to
open
Fire a simple 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:
If the associated
RTCPeerConnection
object's
[[IsClosed]]
slot is
true
, abort these steps.
Let
channel
be a newly created
RTCDataChannel
object.
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 [
RTCWEB-DATA-PROTOCOL
].
Initialize
channel
's
[[DataChannelLabel]]
[[Ordered]]
[[MaxPacketLifeTime]]
[[MaxRetransmits]]
[[DataChannelProtocol]]
, and
[[DataChannelId]]
internal slots to the corresponding values in
configuration
Initialize
channel
's
[[Negotiated]]
internal slot to
false
Initialize
channel
's
[[DataChannelPriority]]
internal slot based on the integer priority value in
configuration
, according to the following mapping:
configuration
priority value
RTCPriorityType
value
0 to 128
very-low
129 to 256
low
257 to 512
medium
513 and greater
high
Set
channel
's
[[ReadyState]]
slot to
connecting
Fire a datachannel event
named
datachannel
with
channel
at the
RTCPeerConnection
object.
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
, unless the procedure was initiated by the
close
method, queue a task that sets the object's
[[ReadyState]]
slot to
closing
. This will eventually render the
data transport
closed
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
transport
was closed.
Set
channel
's
[[ReadyState]]
slot to
closed
If the
transport
was closed
with an error
, fire an
RTCError
event at
channel
with
errorDetail
set to "sctp-failure".
Fire a simple 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 [
RTCWEB-DATA
] 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
's
[[ReadyState]]
slot to
closed
Fire an
RTCError
event at
channel
with
errorDetail
set to "data-channel-failure".
Fire a simple event named
close
at
channel
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
RTCPriorityType
priority
readonly attribute
RTCDataChannelState
readyState
readonly attribute
unsigned long
bufferedAmount
attribute
unsigned long
bufferedAmountLowThreshold
attribute
EventHandler
onopen
attribute
EventHandler
onbufferedamountlow
attribute
EventHandler
onerror
attribute
EventHandler
onclose
void
close
();
attribute
EventHandler
onmessage
attribute
DOMString
binaryType
void
send
USVString
data
);
void
send
Blob
data
);
void
send
ArrayBuffer
data
);
void
send
ArrayBufferView
data
);
};
Attributes
label
of type
USVString
, readonly
The
label
attribute represents a label that can be used to distinguish this
RTCDataChannel
object from other
RTCDataChannel
objects. Scripts are allowed to create multiple
RTCDataChannel
objects with the same label. On getting, the attribute
MUST
return the value of the
[[DataChannelLabel]]
slot.
ordered
of type
boolean
, readonly
The
ordered
attribute returns true if the
RTCDataChannel
is ordered, and false if other 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 initally 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 [
RTCWEB-DATA-PROTOCOL
]. 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.
priority
of type
RTCPriorityType
, readonly
The
priority
attribute returns the priority for this
RTCDataChannel
. The priority is assigned by the user agent at channel creation time. On getting, the attribute
MUST
return the value of the
[[DataChannelPriority]]
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
return the number of bytes of application data (UTF-8 text and binary data) that have been queued using
send()
but that, as of the last time the event loop started executing a task, had not yet been transmitted to the network. (This thus includes any text sent during the execution of the current task, regardless of whether the user
agent is able to transmit text asynchronously with script execution.) This does not include framing overhead incurred by the protocol, or buffering done by the operating system or network hardware. If the channel is closed,
this attribute's value will only increase with each call to the
send()
method (the attribute does not reset to zero once the channel closes).
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
The event type of this event handler is
open
onbufferedamountlow
of type
EventHandler
The event type of this event handler is
bufferedamountlow
onerror
of type
EventHandler
The event type of this event handler is
RTCErrorEvent
errorDetail
contains "sctp-failure",
sctpCauseCode
contains the SCTP Cause Code value, and
message
contains the SCTP Cause-Specific-Information, possibly with additional text.
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
DOMString
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
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 the [
WEBSOCKETS-API
] for more information.
Methods
close
Closes the
RTCDataChannel
. It may be called regardless of whether the
RTCDataChannel
object was created by this peer or the remote peer.
When the
close
method is called, the user agent
MUST
run the following steps:
Let
channel
be the
RTCDataChannel
object which is about to be closed.
If
channel
's
[[ReadyState]]
slot is
closing
or
closed
, then abort these steps.
Set
channel
's
[[ReadyState]]
slot 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.
dictionary
RTCDataChannelInit
boolean
ordered
true
unsigned short
maxPacketLifeTime
unsigned short
maxRetransmits
USVString
protocol
""
boolean
negotiated
false
EnforceRange
unsigned short
id
RTCPriorityType
priority
"low"
};
Dictionary
RTCDataChannelInit
Members
ordered
of type
boolean
, defaulting to
true
If set to false, data is allowed to be delivered out of order. The default value of true, guarantees that data will be delivered in order.
maxPacketLifeTime
of type
unsigned short
Limits the time (in milliseconds) during which the channel will transmit or retransmit data if not acknowledged. This value may be clamped if it exceeds the maximum value supported by the user agent.
maxRetransmits
of type
unsigned short
Limits the number of times a channel will retransmit data if not successfully delivered. This value may be clamped if it exceeds the maximum value supported by the user agent.
protocol
of type
USVString
, defaulting to
""
Subprotocol name used for this channel.
negotiated
of type
boolean
, defaulting to
false
The default value of false tells the user agent to announce the channel in-band and instruct the other peer to dispatch a corresponding
RTCDataChannel
object. If set to true, it is up to the application to negotiate the channel and create an
RTCDataChannel
object with the same
id
at the other peer.
id
of type
unsigned short
Overrides the default selection of ID for this channel.
priority
of type
RTCPriorityType
, defaulting to
low
Priority of this channel.
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
's
[[ReadyState]]
slot is not
open
throw
an
InvalidStateError
Execute the sub step that corresponds to the type of the methods argument:
string
object:
Let
data
be the object and increase the
bufferedAmount
attribute by the number of bytes needed to express
data
as UTF-8.
Blob
object:
Let
data
be the raw data represented by the
Blob
object and increase the
bufferedAmount
attribute by the size of data, in bytes.
ArrayBuffer
object:
Let
data
be the data stored in the buffer described by the
ArrayBuffer
object and increase the
bufferedAmount
attribute by the length of the
ArrayBuffer
in bytes.
ArrayBufferView
object:
Let
data
be the data stored in the section of the buffer described by the
ArrayBuffer
object that the
ArrayBufferView
object references and increase the
bufferedAmount
attribute by the length of the
ArrayBufferView
in bytes.
If the size of
data
exceeds the value of
maxMessageSize
on
channel
's associated
RTCSctpTransport
throw
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
Note
The actual transmission of data occurs in parallel. If sending data leads to an SCTP-level error, the application will be notified asynchronously through
onerror
enum
RTCDataChannelState
"connecting"
"open"
"closing"
"closed"
};
RTCDataChannelState
Enumeration description
connecting
The user agent is attempting to establish the
underlying
data transport
. This is the initial state of an
RTCDataChannel
object created with
createDataChannel
open
The
underlying data transport
is established and communication is possible. This is the initial state of an
RTCDataChannel
object dispatched as a part of an
RTCDataChannelEvent
closing
The
procedure
to close down the
underlying data transport
has started.
closed
The
underlying data transport
has been
closed
or could not be established.
6.3
RTCDataChannelEvent
The
datachannel
event uses the
RTCDataChannelEvent
interface.
Firing a datachannel event named
with an
RTCDataChannel
channel
means that an event with the name
, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the
RTCDataChannelEvent
interface with the
channel
attribute set to
channel
MUST
be created and dispatched at the given target.
Constructor
DOMString
type
RTCDataChannelEventInit
eventInitDict
Exposed
Window
interface
RTCDataChannelEvent
Event
readonly attribute
RTCDataChannel
channel
};
Constructors
RTCDataChannelEvent
Attributes
channel
of type
RTCDataChannel
, readonly
The
channel
attribute represents the
RTCDataChannel
object associated with the event.
dictionary
RTCDataChannelEventInit
EventInit
required
RTCDataChannel
channel
};
Dictionary
RTCDataChannelEventInit
Members
channel
of type
RTCDataChannel
, required
The
RTCDataChannel
object to be announced by the event.
6.4
Garbage Collection
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, or
close
events.
[[ReadyState]]
slot is
open
and at least one event listener is registered for
message
events,
error
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.
7.
Peer-to-peer DTMF
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 [
RTCWEB-AUDIO
].
7.1
RTCRtpSender Interface Extensions
The Peer-to-peer DTMF API extends the
RTCRtpSender
interface as described below.
partial interface
RTCRtpSender
readonly attribute
RTCDTMFSender
dtmf
};
Attributes
dtmf
of type
RTCDTMFSender
, readonly, nullable
The
dtmf
attribute returns an RTCDTMFSender which can be used to send DTMF, or null if unset.
The attribute is set when the kind of an
RTCRtpSender
's
[[SenderTrack]]
is
"audio"
7.2
RTCDTMFSender
To create an
RTCDTMFSender
, the user agent
MUST
run the following steps:
Let
dtmf
be a newly created
RTCDTMFSender
object.
Let
dtmf
have a
[[CanInsertDtmf]]
internal slot, initialized to
false
Let
dtmf
have a
[[Duration]]
internal slot.
Let
dtmf
have a
[[InterToneGap]]
internal slot.
Let
dtmf
have a
[[ToneBuffer]]
internal slot.
Exposed
Window
interface
RTCDTMFSender
EventTarget
void
insertDTMF
DOMString
tones
optional
unsigned long
duration
100
optional
unsigned long
interToneGap
70
);
attribute
EventHandler
ontonechange
readonly attribute
boolean
canInsertDTMF
readonly attribute
DOMString
toneBuffer
};
Attributes
ontonechange
of type
EventHandler
The event type of this event handler is
tonechange
canInsertDTMF
of type
boolean
, readonly
Whether the
RTCDTMFSender
is capable of sending DTMF.
toneBuffer
of type
DOMString
, readonly
The
toneBuffer
attribute
MUST
return a list
of the tones remaining to be played out. For the syntax, content, and interpretation of this list, see
insertDTMF
Methods
insertDTMF
An
RTCDTMFSender
object's
insertDTMF
method is used to send
DTMF tones.
The tones parameter is treated as a series of characters. The characters 0 through 9, A through D, #, and * generate the associated DTMF tones. The characters a to d
MUST
be normalized
to uppercase on entry and are equivalent to A to D. As noted in [
RTCWEB-AUDIO
] Section 3, support for the characters 0 through 9, A through D, #, and * are required. The character ','
MUST
be supported, and indicates a delay of 2 seconds before processing the next character in the tones parameter. All other characters (and only those other characters)
MUST
be considered
unrecognized
The duration parameter indicates the duration in ms to use for each character passed in the tones parameters. The duration cannot be more than 6000 ms or less than 40 ms. The default duration is 100 ms for each tone.
The interToneGap parameter indicates the gap between tones in ms. The user agent clamps it to at least 30 ms and at most 6000 ms. The default value is 70 ms.
The browser
MAY
increase the duration and interToneGap times to cause the times that DTMF start and stop to align with the boundaries of RTP packets but it
MUST
not increase either of them by more than the duration of a single RTP audio packet.
When the
insertDTMF()
method is invoked, the user agent
MUST
run the following steps:
Let
sender
be the
RTCRtpSender
used to send DTMF.
Let
transceiver
be the
RTCRtpTransceiver
object associated with
sender
If
transceiver
's
[[Stopped]]
slot is
true
throw
an
InvalidStateError
If
transceiver
's
[[CurrentDirection]]
slot is
recvonly
or
inactive
throw
an
InvalidStateError
Let
dtmf
be the
RTCDTMFSender
associated with
sender
If
dtmf
's
[[CanInsertDTMF]]
internal slot is
false
throw
an
InvalidStateError
Let
tones
be the method's first argument.
If
tones
contains any
unrecognized
characters,
throw
an
InvalidCharacterError
Set the object's
[[ToneBuffer]]
slot to
tones
Set
dtmf
's
[[Duration]]
slot to the value of the
duration
parameter.
Set
dtmf
's
[[InterToneGap]]
slot to the value of the
interToneGap
parameter.
If the value of the
duration
parameter is less than 40 ms, set
dtmf
's
[[Duration]]
slot to 40 ms.
If the value of the
duration
parameter is greater than 6000 ms, set
dtmf
's
[[Duration]]
slot to 6000 ms.
If the value of the
interToneGap
parameter is less than 30 ms, set
dtmf
's
[[InterToneGap]]
slot to 30 ms.
If the value of the
interToneGap
parameter is greater than 6000 ms, set
dtmf
's
[[InterToneGap]]
slot to 6000
ms.
If
[[ToneBuffer]]
slot is an empty string, abort these steps.
If a
Playout task
is scheduled to be run, abort these steps; otherwise queue a task that runs the following steps (
Playout task
):
If
transceiver
's
[[Stopped]]
slot is
true
, abort these steps.
If
transceiver
's
[[CurrentDirection]]
slot is
recvonly
or
inactive
, abort these steps.
If the
[[ToneBuffer]]
slot contains the empty string, fire an event named
tonechange
with an empty string at the
RTCDTMFSender
object and abort these steps.
Remove the first character from the
[[ToneBuffer]]
slot and let that character be
tone
If
tone
is "," delay sending tones for
2000
ms on the associated RTP media stream, and queue a task to be executed in
2000
ms from now that runs the steps labelled
Playout task
If
tone
is not "," 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
Fire a tonechange event
named
tonechange
with a string consisting of
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.
7.3
RTCDTMFToneChangeEvent
The
tonechange
event uses the
RTCDTMFToneChangeEvent
interface.
Firing a tonechange event named
with a
DOMString
tone
means that an event with the name
, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the
RTCDTMFToneChangeEvent
interface with the
tone
attribute set to
tone
MUST
be created and dispatched at the given target.
Constructor
DOMString
type
RTCDTMFToneChangeEventInit
eventInitDict
Exposed
Window
interface
RTCDTMFToneChangeEvent
Event
readonly attribute
DOMString
tone
};
Constructors
RTCDTMFToneChangeEvent
Attributes
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.
dictionary
RTCDTMFToneChangeEventInit
EventInit
required
DOMString
tone
};
Dictionary
RTCDTMFToneChangeEventInit
Members
tone
of type
DOMString
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.
8.
Statistics Model
8.1
Introduction
The basic statistics model is that the browser maintains a set of statistics 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 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.
8.2
RTCPeerConnection Interface Extensions
The Statistics API extends the
RTCPeerConnection
interface as described below.
partial interface
RTCPeerConnection
Promise
RTCStatsReport
getStats
optional
MediaStreamTrack
selector
null
);
};
Methods
getStats
Gathers stats for the given
selector
and reports the result asynchronously.
When the
getStats()
method is invoked, the user agent
MUST
run the following steps:
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
member 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
be a new promise.
Run the following steps in parallel:
Gather the stats indicated by
selector
according to the
stats selection algorithm
Resolve
with the resulting
RTCStatsReport
object, containing the gathered stats.
Return
8.3
RTCStatsReport
Object
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).
Exposed
Window
interface
RTCStatsReport
readonly maplike<
DOMString
object
>;
};
This interface has "entries", "forEach", "get", "has", "keys", "values", @@iterator methods and a "size" getter brought by
readonly maplike
Use these to retrieve the various dictionaries descended from
RTCStats
that this stats report is composed of. The set of supported property names [
WEBIDL-1
] is defined as the ids of all the
RTCStats
-derived dictionaries that have been generated for this stats report.
8.4
RTCStats
Dictionary
An
RTCStats
dictionary represents the stats gathered by inspecting a specific object relevant to a
selector
. 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.
dictionary
RTCStats
required
DOMHighResTimeStamp
timestamp
required
RTCStatsType
type
required
DOMString
id
};
Dictionary
RTCStats
Members
timestamp
of type
DOMHighResTimeStamp
The
timestamp
, of type
DOMHighResTimeStamp
HIGHRES-TIME
], 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. User agents are free to pick any format for the id as long as it meets the requirements
above.
The set of valid values for
RTCStatsType
, and the dictionaries derived from RTCStats that they indicate, are documented in [
WEBRTC-STATS
].
8.5
The stats selection algorithm
The
stats selection algorithm
is as follows:
Let
result
be an empty RTCStatsReport.
If
selector
is
null
, gather stats for the whole
connection
, add them to
result
, return
result
, and abort these steps.
If
selector
is an
RTCRtpSender
, gather stats for and add the following objects to
result
All
RTCOutboundRTPStreamStats
objects representing RTP streams being sent by
selector
All stats objects referenced directly or indirectly by the
RTCOutboundRTPStreamStats
objects added.
If
selector
is an
RTCRtpReceiver
, gather stats for and add the following objects to
result
All
RTCInboundRTPStreamStats
objects representing RTP streams being received by
selector
All stats objects referenced directly or indirectly by the
RTCInboundRTPStreamStats
added.
Return
result
8.6
Mandatory To Implement Stats
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 types when the corresponding objects exist on a PeerConnection, with the attributes that are listed when they are valid for that object:
RTCRTPStreamStats, with attributes ssrc, mediaType, trackId, transportId, codecId, nackCount
RTCReceivedRTPStreamStats, with all required attributes from its inherited dictionaries, and also attributes packetsReceived, bytesReceived, packetsLost, jitter, packetsDiscarded
RTCInboundRTPStreamStats, with all required attributes from its inherited dictionaries, and also attributes remoteId, framesDecoded
RTCRemoteInboundRTPStreamStats, with all required attributes from its inherited dictionaries, and also attributes localId, roundTripTime
RTCSentRTPStreamStats, with all required attributes from its inherited dictionaries, and also attributes packetsSent, bytesSent
RTCOutboundRTPStreamStats, with all required attributes from its inherited dictionaries, and also attributes remoteId, framesEncoded
RTCRemoteOutboundRTPStreamStats, with all required attributes from its inherited dictionaries, and also attributes localId, remoteTimestamp
RTCPeerConnectionStats, with attributes dataChannelsOpened, dataChannelsClosed
RTCDataChannelStats, with attributes label, protocol, datachannelId, state, messagesSent, bytesSent, messagesReceived, bytesReceived
RTCMediaStreamStats, with attributes streamIdentifer, trackIds
RTCMediaStreamTrackStats, with attributes trackIdentifier, remoteSource, ended, detached, frameWidth, frameHeight, framesPerSecond, framesSent, framesReceived, framesDecoded, framesDropped, framesCorrupted, audioLevel
RTCCodecStats, with attributes payloadType, codec, clockRate, channels, sdpFmtpLine
RTCTransportStats, with attributes bytesSent, bytesReceived, rtcpTransportStatsId, selectedCandidatePairId, localCertificateId, remoteCertificateId
RTCIceCandidatePairStats, with attributes transportId, localCandidateId, remoteCandidateId, state, priority, nominated, bytesSent, bytesReceived, totalRoundTripTime, currentRoundTripTime
RTCIceCandidateStats, with attributes ip, port, protocol, candidateType, priority, url
RTCCertificateStats, with attributes fingerprint, fingerprintAlgorithm, base64Certificate, issuerCertificateId
An implementation
MAY
support generating any other statistic defined in [
WEBRTC-STATS
], and
MAY
generate
statistics that are not documented.
8.7
GetStats Example
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:
Example 8
var
baselineReport, currentReport;
var
selector = pc.getSenders()[
].track;