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.
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.
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.
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]].
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.
Terminology
The EventHandler
interface, representing a callback used for event handlers, and the
ErrorEvent interface are defined in [[!HTML51]].
The concepts queue a
task and networking
task source are defined in [[!HTML51]].
The concept fire an
event is defined in [[!DOM]].
The terms event, event
handlers and event
handler event types are defined in [[!HTML51]].
performance.timeOrigin
and performance.now()
are defined in [[!HIGHRES-TIME]].
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 terms RTCStatsType, stats object and monitored object are defined in [[!WEBRTC-STATS]].
When referring to exceptions, the terms throw and
create are
defined in [[!WEBIDL-1]].
The term "throw" is used as specified in [[!INFRA]]: it terminates
the current processing steps.
The terms fulfilled, rejected, resolved, pending and
settled used in the context of Promises are defined in
[[!ECMASCRIPT-6.0]].
The terms bundle, bundle-only and bundle-policy
are defined in [[!JSEP]].
The OAuth Client and Authorization Server roles
are defined in [[!RFC6749]] Section 1.1.
The terms isolated stream,
peeridentity, request an identity assertion and
validate the identity are defined in [[!WEBRTC-IDENTITY]].
The terms permission, retrieve the permission
state, request permission to
use and create a permission storage
entry are defined in [[!PERMISSIONS]].
The general principles for Javascript APIs apply, including the principle
of
run-to-completion and no-data-races as defined in [[API-DESIGN-PRINCIPLES]].
That is, while a task is running, external events do
not influence what's visible to the Javascript application. For example,
the amount of data buffered on a data channel will increase due to
"send" calls while Javascript is executing, and the decrease due to
packets being sent will be visible after a task checkpoint.
It is the responsibility of the user agent to make sure the set of
values presented to the application is consistent - for instance that
getContributingSources() (which is synchronous) returns values for all
sources measured at the same time.
Peer-to-peer connections
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]].
Configuration
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.
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
0
Size of the prefetched ICE pool as defined in
[[!JSEP]].
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]].
For OAuth Authentication, the ICE Agent requires three
pieces of credential information. The credential is composed of
a kid, which the RTCIceServerusername member is used for, and
macKey and accessToken, which are
placed in the RTCOAuthCredential dictionary.
This specification does not define how an application (acting
as the OAuth Client) obtains the
accessToken, kid and
macKey from the Authorization Server, as
WebRTC only handles the interaction between the ICE
agent and TURN server. For example, the application may use
the OAuth 2.0 Implicit Grant type, with PoP (Proof-of-Possession)
Token type, as described in [[!RFC6749]] and
[[OAUTH-POP-KEY-DISTRIBUTION]]; an example of this is provided
in [[!RFC7635]], Appendix B.
The application, acting as 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.
The length of the HMAC key
(RTCOAuthCredential.macKey) MAY be any integer
number of bytes greater than 20 (160 bits).
According to [[!RFC7635]] Section 4.1, the
HMAC key MUST be a symmetric key, as asymmetric keys would
result in large access tokens which may not fit in a single
STUN message.
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.
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.
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:
urls of type (DOMString or
sequence<DOMString>), required
STUN or TURN URI(s) as defined in [[!RFC7064]] and
[[!RFC7065]] or other URI types.
username of type DOMString
If this RTCIceServer object represents a
TURN server, 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.
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.
If this RTCIceServer object represents a
TURN server, then this attribute specifies how
credential should be used when that TURN server
requests authorization.
As described in [[!JSEP]], if the
iceTransportPolicy member of
the RTCConfiguration is specified, it defines the
ICE candidate policy
[[!JSEP]] 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.
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.
The implementation can still use its own candidate
filtering policy in order to limit the IP addresses exposed
to the application, as noted in the description of
RTCIceCandidate.address.
RTCBundlePolicy Enum
As described in [[!JSEP]],
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.
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.
RTCRtcpMuxPolicy Enum
As described in [[!JSEP]], 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]], 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.
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.
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.
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.
Performing an ICE restart is recommended when
iceConnectionState transitions to
"failed".
An application may additionally choose to listen for the
iceConnectionState transition to
"disconnected"
and then use other sources of information (such as using
getStats to measure if the number of bytes sent
or received over the next couple of seconds increases) to determine
whether an ICE restart is advisable.
The RTCAnswerOptions dictionary describe options specific to session description of type answer (none in this version of the specification).
The previous state doesn't apply and any
RTCIceTransports are in the
"failed" state.
disconnected
None of the previous states apply and any
RTCIceTransports are in the
"disconnected" state.
new
None of the previous states apply and all
RTCIceTransports are in the
"new" or "closed" state,
or there are no transports.
checking
None of the previous states apply and any
RTCIceTransports are in the
"new" or "checking" state.
completed
None of the previous states apply and all
RTCIceTransports are in the
"completed" or "closed" state.
connected
None of the previous states apply and all
RTCIceTransports are in the
"connected", "completed" or
"closed" state.
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.
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.
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.
When the RTCPeerConnection() constructor
is invoked, the user agent MUST run the following steps:
If any of the steps enumerated below fails for a reason not
specified here, throw an UnknownError
with the "message" field set to an appropriate description.
Else, generate one or more new RTCCertificate instances
with this RTCPeerConnection instance and store them. This MAY happen
asynchronously and the value of certificates remains
undefined for the subsequent steps. As noted in Section 4.3.2.3 of
[[RTCWEB-SECURITY]], WebRTC utilizes self-signed rather than
Public Key Infrastructure (PKI) certificates, so that the expiration
check is to ensure that keys are not used indefinitely and additional
certificate checks are unnecessary.
Let connection have a
[[\PendingLocalDescription]] internal slot, initialized
to null.
Let connection have a
[[\CurrentLocalDescription]] internal slot, initialized
to null.
Let connection have a
[[\PendingRemoteDescription]] internal slot, initialized
to null.
Let connection have a
[[\CurrentRemoteDescription]] internal slot, initialized
to null.
Return connection.
Enqueue an operation
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.
To enqueue an operation to an
RTCPeerConnection object's operation queue, run
the following steps:
The null candidate event is fired to ensure
legacy compatibility. New code should monitor the gathering state
of RTCIceTransport and/or RTCPeerConnection.
To set an RTCSessionDescription
description on an RTCPeerConnection
object connection, enqueue the following steps to
connection's operation queue:
Let p be a new promise.
In parallel, start the process to apply description
as described in [[!JSEP]].
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]],
then rejectp with a newly
createdInvalidStateError 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 rejectp with a newly createdInvalidModificationError and abort these steps.
If description is set as a local description,
if description.type is "rollback"
and signaling state is "stable"
then rejectp with a newly createdInvalidStateError 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 rejectp with a newly createdInvalidModificationError and abort these steps.
If the content of description is not
valid SDP syntax, then rejectp 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 description is set as a remote description,
the connection's RTCRtcpMuxPolicy
is require
and the remote description does not use RTCP mux,
then rejectp with a newly createdInvalidAccessError and abort these steps.
If the content of description is invalid,
then rejectp with a newly
createdInvalidAccessError and abort these steps.
For all other errors, rejectp with a newly
createdOperationError.
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:
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 rejectp with a newly createdInvalidStateError and abort these steps.
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, create an
RTCSctpTransport with an initial state of
"connecting" and assign the result to the
[[\SctpTransport]] slot. Otherwise, if an SCTP
association is established,
but the "max-message-size" SDP attribute is updated,
update the data max message size of
connection's [[\SctpTransport]].
If description negotiates the DTLS role
of the SCTP transport, and there is an
RTCDataChannel with a nullid,
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.
If transceiver's [[\Stopped]] slot
is true, abort these sub steps.
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. 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 be null.
If direction is "sendrecv" or
"recvonly",
set transceiver's [[\Receptive]] slot
to true, otherwise set it to false.
If description is of type
"answer" or "pranswer",
then run the following steps:
Set
transceiver.[[\Sender]].[[\SendCodecs]]
to the codecs that description
negotiates for sending, and which the user agent
is currently capable of sending.
Set
transceiver.[[\Receiver]].[[\ReceiveCodecs]]
to the codecs that description
negotiates for receiving, and which the user
agent is currently prepared to receive.
If direction is
"sendonly" or "inactive",
and transceiver's
[[\FiredDirection]] slot is either
"sendrecv" or "recvonly",
then run the following steps:
Let direction be an RTCRtpTransceiverDirection value
representing the direction from the media
description, but with the send and receive
directions reversed to represent this peer's point
of view. If the media description is rejected
set direction to "inactive".
If no suitable transceiver is found
(transceiver is unset), run the following
steps:
If the description is of type "offer"
and contains a request to receive simulcast, use the order
of the rid values specified in the simulcast attribute to create
an RTCRtpEncodingParameters dictionary for
each of the simulcast layers, populating the rid member
according to the corresponding rid value, and let sendEncodings
be the list containing the created dictionaries. Otherwise,
let sendEncodings be an empty list.
If description is of type "answer"
or "pranswer", and transceiver.
[[\Sender]].[[\sendEncodings]] .length is
greater than 1, then run the following steps:
If description indicates that simulcast is
not supported or desired, then remove all dictionaries in
transceiver.[[\Sender]].[[\sendEncodings]]
except the first one and abort these sub steps.
If description rejects any of the offered layers,
then remove the dictionaries that correspond to rejected layers from
transceiver.[[\Sender]].[[\sendEncodings]].
Update the paused status as indicated by [[MMUSIC-SIMULCAST]] of
each simulcast layer by setting the
active
member on the corresponding dictionaries in
transceiver.[[\Sender]].[[\sendEncodings]]
to true for unpaused or to false for paused.
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]].
If direction is "sendrecv"
or "recvonly", let msids be a
list of the MSIDs that the media description indicates
transceiver.[[\Receiver]].[[\ReceiverTrack]]
is to be associated with. Otherwise, let
msids be an empty list.
If description is of type
"answer" or "pranswer", then run
the following steps:
Set
transceiver.[[\Sender]].[[\SendCodecs]]
to the codecs that description
negotiates for sending, and which the user agent
is currently capable of sending.
Set
transceiver.[[\Receiver]].[[\ReceiveCodecs]]
to the codecs that description
negotiates for receiving, and which the user
agent is currently prepared to receive.
If description is of type "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]].
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]].
For each track in muteTracks,
set the muted state of track to the
value true.
For each stream and track pair
in removeList, remove the tracktrack from stream.
For each stream and track pair
in addList, add the tracktrack to stream.
For each entry entry in trackEventInits,
fire an event named track using the
RTCTrackEvent interface with its
receiver attribute initialized to
entry.receiver, its
track attribute initialized to
entry.track, its
streams attribute initialized to
entry.streams and its
transceiver attribute initialized to
entry.transceiver
at the connection object.
If configuration.peerIdentity is
set and its value differs from the target peer
identity, throw an InvalidModificationError.
If configuration.certificates is
set, run the following steps:
If the length of configuration.certificates
is different from the length of
connection.[[\Configuration]].certificates,
throw an InvalidModificationError.
Let index be initialized to 0.
Let size be initialized to the length of
configuration.certificates.
While index is less than size,
run the following steps:
If the ECMAScript object represented by the value of
configuration.certificates at
index is not the same as the ECMAScript
object represented by the value of
connection.[[\Configuration]].certificates
at index, throw an
InvalidModificationError.
Increment index by 1.
If the value of configuration.bundlePolicy is set and its value
differs from the connection's bundle policy, throw
an InvalidModificationError.
If the value of configuration.rtcpMuxPolicy is set and its value
differs from the connection's rtcpMux policy, throw an
InvalidModificationError. If the value is
"negotiate" and the user agent does not implement
non-muxed RTCP, throw a NotSupportedError.
If the value of configuration.iceCandidatePoolSize is set and its
value 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]], 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]] 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]].
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.
Let urls be server.urls.
If urls is a string, set urls to a
list consisting of just that string.
Parse the
url using the generic URI syntax
defined in [[!RFC3986]] and obtain the
scheme name. If the parsing based
on the syntax defined in [[!RFC3986]] fails,
throw a SyntaxError. If
the scheme name is not implemented
by the browser throw a
NotSupportedError. If
scheme name is turn or
turns, and parsing the
url using the syntax defined in
[[!RFC7064]] fails, throw a
SyntaxError. If scheme
name is stun or
stuns, and parsing the
url using the syntax defined in
[[!RFC7065]] fails, throw a
SyntaxError.
If scheme name is turn or
turns, and either of
server.username or
server.credential are omitted,
then throw an InvalidAccessError.
If scheme name is turn or
turns, and
server.credentialType is
"password", and
server.credential is not a
DOMString, then
throw an InvalidAccessError.
If scheme name is turn or
turns, and
server.credentialType is
"oauth", and
server.credential is not an
RTCOAuthCredential, then throw an
InvalidAccessError.
Append server to
validatedServers.
Let validatedServers be the ICE
Agent's ICE servers
list.
As defined in [[!JSEP]], 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.
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.
It represents the local description that was successfully
negotiated the last time the RTCPeerConnection
transitioned into the stable state plus any local candidates
that have been generated by the ICE Agent since the offer
or answer was created.
It represents a local description that is in the
process of being negotiated plus any local candidates that have
been generated by the ICE Agent since the offer or
answer was created. If the RTCPeerConnection is in
the stable state, the value is null.
It represents the last remote description that was successfully
negotiated the last time the RTCPeerConnection
transitioned into the stable state plus any remote candidates
that have been supplied via addIceCandidate() since the
offer or answer was created.
It represents a remote description that is in the
process of being negotiated, complete with any remote
candidates that have been supplied via addIceCandidate() since the
offer or answer was created. If the
RTCPeerConnection is in the stable state, the
value is null.
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]]. Prior to the completion of
setRemoteDescription, this
value is null.
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
MediaStreamTracks 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 or preferred by the session (as
opposed to an answer, which will include only a specific
negotiated subset to use). In the event
createOffer is called after the session is
established, createOffer will generate an offer
that is compatible with the current session, incorporating any
changes that have been made to the session since the last
complete offer-answer exchange, such as addition or removal of
tracks. If no changes have been made, the offer will include
the capabilities of the current local description as well as
any additional capabilities that could be negotiated in an
updated offer.
The generated SDP will also contain the ICE agent's
usernameFragment,
password and
ICE options (as defined in [[!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.
The final steps to create an offer given a
promise p 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 p, and abort
these steps.
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 RTCRtpTransceivers, and the
identity assertion from provider (if non-null),
generate an SDP offer, sdpString, as described
in [[!JSEP]].
As described in [[!BUNDLE]] (Section 7), if bundling
is used (see RTCBundlePolicy) an offerer tagged
m= section must be selected in order to negotiate a
BUNDLE group. The user agent MUST choose the m= section
that corresponds to the first non-stopped transceiver in
the set of transceivers as the offerer tagged m=
section. This allows the remote endpoint to predict
which transceiver is the offerer tagged m= section
without having to parse the SDP.
The codec preferences of an m= section's
associated transceiver is said to be the value of the
RTCRtpTranceiver's
[[\PreferredCodecs]] slot with the following
filtering applied (or said not to be set if
[[\PreferredCodecs]] is empty):
If the direction is
"sendrecv", exclude any codecs not
included in the intersection of
RTCRtpSender.getCapabilities(kind).codecs
and RTCRtpReceiver.getCapabilities(kind).codecs.
If the direction is
"sendonly", exclude any codecs not
included in
RTCRtpSender.getCapabilities(kind).codecs.
If the direction is
"recvonly", exclude any codecs not
included in
RTCRtpReceiver.getCapabilities(kind).codecs.
The filtering MUST NOT change the order of the codec
preferences.
If the length of the [[\SendEncodings]] slot
of the RTCRtpSender is
larger than 1, then
for each encoding given in [[\SendEncodings]]
of the RTCRtpSender, add an "a=rid send" line to the
corresponding media section, and add an
"a=simulcast:send"
line giving the RIDs in the same order as
given in the "encodings" field. No RID restrictions
are set.
[[SDP-SIMULCAST]] section 5.2
specifies that the order of RIDs in the a=simulcast
line suggests a proposed order of preference.
If the browser decides not to transmit all encodings,
one should expect it to stop sending the last
encoding in the list first.
Let offer be a newly created
RTCSessionDescriptionInit dictionary
with its type member initialized to the string
"offer" and its sdp member
initialized to sdpString.
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 MediaStreamTracks
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]],
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.
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 createdInvalidStateError.
The final steps to create an answer given a
promise p 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 p, and abort
these steps.
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 RTCRtpTransceivers, and the
identity assertion from provider (if non-null),
generate an SDP answer, sdpString, as described
in [[!JSEP]].
The codec preferences of an m= section's
associated transceiver is said to be the value of the
RTCRtpTranceiver's
[[\PreferredCodecs]] slot with the following
filtering applied (or said not to be set if
[[\PreferredCodecs]] is empty):
If the direction is
"sendrecv", exclude any codecs not
included in the intersection of
RTCRtpSender.getCapabilities(kind).codecs
and RTCRtpReceiver.getCapabilities(kind).codecs.
If the direction is
"sendonly", exclude any codecs not
included in
RTCRtpSender.getCapabilities(kind).codecs.
If the direction is
"recvonly", exclude any codecs not
included in
RTCRtpReceiver.getCapabilities(kind).codecs.
The filtering MUST NOT change the order of the codec
preferences.
If the length of the [[\SendEncodings]] slot
of the RTCRtpSender is
larger than 1, then
for each encoding given in [[\SendEncodings]]
of the RTCRtpSender, add an "a=rid send" line to the
corresponding media section, and add an
"a=simulcast:send"
line giving the RIDs in the same order as
given in the "encodings" field. No RID restrictions
are set.
Let answer be a newly created
RTCSessionDescriptionInit dictionary
with its type member initialized to the string
"answer" and its sdp member
initialized to sdpString.
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]]
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.
If description.sdp is the
empty string and description.type
is "answer" or "pranswer",
set description.sdp to the value of
connection's [[\LastAnswer]] slot.
If description.sdp is the
empty string and description.type
is "offer", set description.sdp
to the value of connection's
[[\LastOffer]] slot.
As noted in [[!JSEP]],
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 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 candidate.candidate is not an empty string
and both candidate.sdpMid and
candidate.sdpMLineIndex are
null, return a promise rejected with a newly
createdTypeError.
Return the result of enqueuing the following
steps to connection's operation queue:
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,
rejectp with a newly
createdOperationError 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,
rejectp with a newly
createdOperationError 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, rejectp with a newly
created
OperationError and abort these steps.
In parallel, add the ICE candidate
candidate as described in [[!JSEP]]. Use
candidate.usernameFragment to identify the
ICE generation; if usernameFragment is null, process the
candidate for the most recent ICE
generation. If
candidate.candidate is an empty
string, process candidate as an
end-of-candidates indication for the corresponding
media description and ICE candidate
generation. If both candidate.sdpMid and
candidate.sdpMLineIndex are null, then
this applies to all media descriptions.
If candidate could not be
successfully added the user agent MUST queue a task
that runs the following steps:
If connection's
[[\IsClosed]] slot is true,
then abort these steps.
Rejectp with a newly
createdOperationError 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.
Due to WebIDL processing, addIceCandidate(null)
is interpreted as a call with the default dictionary present, which, in the
above algorithm, indicates end-of-candidates for all media
descriptions and ICE candidate generation. This is by design for
legacy reasons.
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.)
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.
The setConfiguration method updates the
configuration of this RTCPeerConnection
object. This includes changing the configuration of the ICE
Agent. As noted in [[!JSEP]], 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.
Let transceivers be the result of executing the
CollectTransceivers algorithm. For every
RTCRtpTransceivertransceiver in
transceivers, run the following steps:
If transceiver's [[\Stopped]] slot
is true, abort these sub steps.
This section is broken out for readability. Consider
partial interfaces here to be part of their main counterparts, as they
overload existing methods.
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.
The addStream method that used to exist on
RTCPeerConnection is easy to polyfill as:
This section describes a set of legacy extensions that may be used to
influence how an offer is created, in addition to the media added to
the RTCPeerConnection. Developers are encouraged to
use the RTCRtpTransceiver API instead.
When createOffer
is called with any of the legacy options specified in this section,
run the followings steps instead of the regular createOffer steps:
For each "offerToReceive<Kind>" member in options with
kind, kind, run the following steps:
If the value of the dictionary member is false,
For each non-stopped "sendrecv" transceiver of
transceiver kindkind, set
transceiver's [[\Direction]] slot to
"sendonly".
For each non-stopped "recvonly" transceiver of
transceiver kindkind, set
transceiver's [[\Direction]] slot to
"inactive".
Continue with the next option, if any.
If connection has any non-stopped "sendrecv"
or "recvonly" transceivers of transceiver kindkind, continue with the next option, if any.
Let transceiver be the result of invoking the
equivalent of
connection.addTransceiver(kind), except
that this operation MUST NOT update the
negotiation-needed flag.
If transceiver is unset because the previous
operation threw an error, abort these steps.
This setting provides additional control over the
directionality of audio. For example, it can be used to ensure
that audio can be received, regardless if audio is
sent or not.
offerToReceiveVideo of type boolean
This setting provides additional control over the
directionality of video. For example, it can be used to ensure
that video can be received, regardless if video is sent or
not.
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 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.
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.
RTCSessionDescription Class
The RTCSessionDescription class is used by
RTCPeerConnection to expose local and remote
session descriptions.
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.
The string representation of the SDP [[!SDP]]; if
type is "rollback", this member is unused.
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.
Setting Negotiation-Needed
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.
The negotiation-needed flag is cleared when an
RTCSessionDescription of type "answer" is applied, and the supplied description matches
the state of the
RTCRtpTransceivers and
RTCDataChannels 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.
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.
The negotiation-needed flag will be
updated once the state transitions to "stable", as part of the steps
for setting an RTCSessionDescription.
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.
If connection has created any
RTCDataChannels, 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.[[\Direction]] is
"sendrecv" or "sendonly",
and the associated m= section in description
either doesn't contain a single "a=msid" line, or the number
of MSIDs from the "a=msid" lines in this m= section,
or the MSID values themselves, differ from what is in
transceiver.sender.[[\AssociatedMediaStreamIds]],
return true.
If description is of type "answer",
and the direction of the associated m=
section in the description does not match
transceiver.[[\Direction]]
intersected with the offered direction (as described in
[[!JSEP]]), return
true.
If all the preceding checks were performed and true
was not returned, nothing remains to be negotiated; return
false.
Interfaces for Connectivity Establishment
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.
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.
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
RTCIceTransports.
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.
address of type DOMString, readonly, nullable
The address of the candidate, allowing for IPv4 addresses,
IPv6 addresses, and fully qualified domain names (FQDNs). This
corresponds to the connection-address field in
candidate-attribute.
The addresses exposed in candidates gathered via ICE
and made visibile to the application in
RTCIceCandidate instances can reveal more
information about the device and the user (e.g. location,
local network topology) than the user might have expected in
a non-WebRTC enabled browser.
These addresses are always exposed to the application,
and potentially exposed to the communicating party, and can
be exposed without any specific user consent (e.g. for peer
connections used with data channels, or to receive media
only).
These addresses can also be used as
temporary or persistent cross-origin states, and thus
contribute to the fingerprinting surface of the device.
Applications can avoid exposing addresses to the
communicating party, either temporarily or permanently, by
forcing the ICE Agent to report only relay candidates
via the iceTransportPolicy member of
RTCConfiguration.
To limit the addresses exposed to the application
itself, browsers can offer their users different policies
regarding sharing local addresses, as defined in
[[RTCWEB-IP-HANDLING]].
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", "usernameFragment"»:
Let value be the result of getting the underlying value of the attribute identified by attr, given this RTCIceCandidate object.
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]].
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.
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]].
RTCIceTcpCandidateType Enum
The RTCIceTcpCandidateType represents the type of the
ICE TCP candidate, as defined in [[!RFC6544]].
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.
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 RTCIceTransports 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.
The candidate attribute is the
RTCIceCandidate object with the new ICE
candidate that caused the event.
This attribute is set to null when an event is
generated to indicate the end of candidate gathering.
Even where there are multiple media components,
only one event containing a null candidate is
fired.
url of type DOMString, readonly, nullable
The url attribute is the STUN or TURN URL that
identifies the STUN or TURN server used to gather this
candidate. If the candidate was not gathered from a STUN or
TURN server, this parameter will be set to
null.
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
Members
hostCandidate of type DOMString
The local 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.
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.
See [[!RTCWEB-TRANSPORT]], Sections 4.1 and 4.2. Corresponds to "below
normal" as defined in [[!RTCWEB-DATA]].
low
See [[!RTCWEB-TRANSPORT]], Sections 4.1 and 4.2. Corresponds to
"normal" as defined in [[!RTCWEB-DATA]].
medium
See [[!RTCWEB-TRANSPORT]], Sections 4.1 and 4.2. Corresponds to "high"
as defined in [[!RTCWEB-DATA]].
high
See [[!RTCWEB-TRANSPORT]], Sections 4.1 and 4.2. 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.
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.
The generateCertificate function causes the
user agent to create and store an X.509 certificate
[[!X509V3]] and corresponding private key. A handle to
information is provided in the form of the
RTCCertificate interface. The returned
RTCCertificate can be used to control the
certificate that is offered in the DTLS sessions established by
RTCPeerConnection.
The keygenAlgorithm argument is used to control how
the private key associated with the certificate is generated. The
keygenAlgorithm argument uses the WebCrypto
[[!WebCryptoAPI]] AlgorithmIdentifier type. The
keygenAlgorithm value MUST be a valid argument to
window.crypto.subtle.generateKey; that is, the
value MUST produce a non-error result when normalized according
to the WebCrypto
algorithm normalization process [[!WebCryptoAPI]] with an
operation name of generateKey and a [[supportedAlgorithms]]
value specific to production of certificates for
RTCPeerConnection. If the algorithm normalization
process produces an error, the call to
generateCertificate MUST be rejected with that
error.
Signatures produced by the generated key are used to
authenticate the DTLS connection. The identified algorithm (as
identified by the name of the normalized
AlgorithmIdentifier) MUST be an asymmetric algorithm
that can be used to produce a signature.
The certificate produced by this process also contains a
signature. The validity of this signature is only relevant for
compatibility reasons. Only the public key and the resulting
certificate fingerprint are used by
RTCPeerConnection, but it is more likely that a
certificate will be accepted if the certificate is well formed.
The browser selects the algorithm used to sign the certificate; a
browser SHOULD select SHA-256 [[!FIPS-180-4]] if a hash algorithm
is needed.
The resulting certificate MUST NOT include information that
can be linked to a user or user agent. Randomized values
for distinguished name and serial number SHOULD be used.
A user agent MUST reject a call to
generateCertificate() with a
DOMException of type NotSupportedError
if the keygenAlgorithm parameter identifies an
algorithm that the user agent cannot or will not use to
generate a certificate for RTCPeerConnection.
The following values MUST be supported by a user agent:
{ name: "RSASSA-PKCS1-v1_5",
modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]),
hash: "SHA-256" }, and { name: "ECDSA",
namedCurve: "P-256"
}.
It is expected that a user agent will have
a small or even fixed set of values that it will accept.
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.
A 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.
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]]), a certificate
([[\Certificate]]) that RTCPeerConnection
uses to authenticate with a peer, and the origin ([[\Origin]])
that created the object.
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.
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. No mechanism is provided for
applications to access the [[\KeyingMaterial]] internal slot.
Implementations MUST support applications storing and retrieving
RTCCertificate objects from persistent storage.
In implementations where an RTCCertificate might not
directly hold private keying material (it might be stored in a
secure module), a reference to the private key can be held in
the [[\KeyingMaterial]] internal slot, allowing the
private key to be stored and used.
Initialize value's expires attribute to
contain serialized.[[\Expires]].
Set value's [[\Certificate]] slot to a copy of
serialized.[[\Certificate]].
Set value's [[\Origin]] slot to a copy of
serialized.[[\Origin]].
Set value's [[\KeyingMaterial]] slot to the private key material
resulting from deserializing serialized.[[\KeyingMaterial]]
Supporting structured cloning in this manner
allows RTCCertificate instances to be persisted to stores. It
also allows instances to be passed to other origins using APIs
like postMessage [[webmessaging]]. However, the object cannot
be used by any other origin than the one that originally created it.
RTP Media API
The RTP media API lets a web application send and receive
MediaStreamTracks over a peer-to-peer connection. Tracks, when
added to an RTCPeerConnection, result in signaling; when this
signaling is forwarded to a remote peer, it causes corresponding tracks to
be created on the remote side.
There is not an exact 1:1 correspondence between tracks sent
by one RTCPeerConnection and received by the other. For one,
IDs of tracks sent have no mapping to the IDs of tracks received. Also,
replaceTrack changes the
track sent by an RTCRtpSender without creating a new
track on the receiver side; the corresponding
RTCRtpReceiver will only have a single track,
potentially representing multiple sources of media stitched together. Both
addTransceiver and
replaceTrack can be used to
cause the same track to be sent multiple times, which will be observed on
the receiver side as multiple receivers each with its own separate track.
Thus it's more accurate to think of a 1:1 relationship between an
RTCRtpSender on one side and an
RTCRtpReceiver's track on the other side, matching senders
and receivers using the RTCRtpTransceiver's mid if necessary.
When sending media, the sender may need to rescale or
resample the media to meet various requirements including the
envelope negotiated by SDP.
Following the rules in [[!JSEP]], 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.
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. What to transmit if the integer
part of the scaled width or height is zero is implementation-specific.
The actual encoding and transmission of MediaStreamTracks
is managed through objects called RTCRtpSenders.
Similarly, the reception and decoding of MediaStreamTracks is
managed through objects called RTCRtpReceivers. 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
RTCRtpTransceivers, representing the paired
senders and receivers with some shared state. This set is initialized to
the empty set when the RTCPeerConnection object is
created. RTCRtpSenders and
RTCRtpReceivers are always created at the same time
as an RTCRtpTransceiver, which they will remain
attached to for their lifetime.
RTCRtpTransceivers 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.
RTCPeerConnection Interface Extensions
The RTP media API extends the RTCPeerConnection
interface as described below.
Adds a new track to the RTCPeerConnection,
and indicates that it is contained in the specified
MediaStreams.
When the addTrack method is invoked,
the user agent MUST run the following steps:
Let connection be the
RTCPeerConnection object on which this
method was invoked.
Let track be the
MediaStreamTrack object indicated by the
method's first argument.
Let kind be track.kind.
Let streams be a list of
MediaStream objects constructed from the
method's remaining arguments, or an empty list if the method
was called with a single argument.
Let senders be the result of executing the
CollectSenders algorithm. If an
RTCRtpSender for track already
exists in senders, throw an
InvalidAccessError.
The steps below describe how to determine if an existing
sender can be reused. Doing so will cause future calls to
createOffer and createAnswer to
mark the corresponding media description as
sendrecv or sendonly and add the
MSID of the sender's streams, as defined in [[!JSEP]].
If any RTCRtpSender object in
senders matches all the following criteria, let
sender be that object, or null
otherwise:
The transceiver is not stopped. More
precisely, the [[\Stopped]] slot of the
RTCRtpTransceiver associated with the
sender is false.
The sender has never been used to send. More
precisely, the [[\CurrentDirection]] slot of the
RTCRtpTransceiver associated with the
sender has never had a value of sendrecv or
sendonly.
If sender is not null, run the
following steps to use that sender:
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 stream).
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.
Stops sending media from sender. The
RTCRtpSender will still appear
in getSenders. Doing so will cause future
calls to createOffer to mark the
media description for the corresponding transceiver
as recvonly or inactive,
as defined in
[[!JSEP]].
When the other peer stops sending a track in this manner, the
track is removed from any remote MediaStreams
that were initially revealed in the track event, and
if the MediaStreamTrack is not already muted,
a muted event is
fired at the track.
When the removeTrack method is
invoked, the user agent MUST run the following steps:
Let sender be the argument to
removeTrack.
Let connection be the
RTCPeerConnection object on which
the method was invoked.
Validate sendEncodings by running the following steps:
Verify that each rid
value in sendEncodings conforms to the grammar specified in
Section 10 of [[!MMUSIC-RID]]. If one of the RIDs does not meet
these requirements, throw a TypeError.
Verify that each scaleResolutionDownBy
value in sendEncodings is greater than or equal to 1.0. If
one of the scaleResolutionDownBy values does not meet
this requirement, throw a RangeError.
Verify that each maxFramerate
value in sendEncodings is greater than or equal to 0.0. If
one of the maxFramerate values does not meet
this requirement, throw a RangeError.
Let maxN be the maximum number of total simultaneous
encodings the user agent may support for this kind, at
minimum 1.This should be an optimistic number since the
codec to be used is not known yet.
If the number of RTCRtpEncodingParameters
stored in sendEncodings exceeds maxN,
then trim sendEncodings from the tail until its length
is maxN.
If the number of RTCRtpEncodingParameters now
stored in sendEncodings is 1, then remove any
rid
member from the lone entry.
Providing a single, default
RTCRtpEncodingParameters in sendEncodings
allows the application to subsequently set encoding parameters using
setParameters, even
when simulcast isn't used.
Create an RTCRtpSender with track,
kind, streams and sendEncodings
and let sender be the result.
If sendEncodings is set, then subsequent calls
to createOffer will be configured to send
multiple RTP encodings as defined in [[!JSEP]]. When
setRemoteDescription is called with a
corresponding remote description that is able to receive
multiple RTP encodings as defined in [[!JSEP]], the
RTCRtpSender may send multiple RTP
encodings and the parameters retrieved via the transceiver's
sender.getParameters() will reflect the
encodings negotiated.
When the remote PeerConnection's track event fires
corresponding to the RTCRtpReceiver being
added, these are the streams that will be put in the event.
The RTCRtpTransceiver's
RTCRtpSendersender will offer to
send RTP, and will send RTP if the remote peer accepts and
sender.getParameters().encodings[i].active
is true for any value of i. The
RTCRtpTransceiver's
RTCRtpReceiver will offer to receive RTP, and
will receive RTP if the remote peer accepts.
sendonly
The RTCRtpTransceiver's
RTCRtpSendersender will offer to
send RTP, and will send RTP if the remote peer accepts and
sender.getParameters().encodings[i].active
is true for any value of i. The
RTCRtpTransceiver's
RTCRtpReceiver will not offer to receive RTP,
and will not receive RTP.
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]] given
RTCRtpTransceivertransceiver and
trackEventInits, the user agent MUST run the following steps:
Create a new RTCTrackEventInit
dictionary with receiver, track,
streams and transceiver as members
and add it to trackEventInits.
To
process the removal of a remote track for
an incoming media description [[!JSEP]] given
RTCRtpTransceivertransceiver and
muteTracks, the user agent MUST run the following steps:
To set the associated remote streams given
RTCRtpReceiverreceiver, msids,
addList, and removeList, 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 ids corresponding to
msids.
The RTCRtpSender interface allows an
application to control how a given MediaStreamTrack is
encoded and transmitted to a remote peer. When setParameters
is called on an RTCRtpSender object, the encoding is
changed appropriately.
To create an RTCRtpSender with a
MediaStreamTrack, track, a string,
kind, a list of
MediaStream objects, streams, and
optionally a list of RTCRtpEncodingParameters
objects, sendEncodings, run the following steps:
Let sender have a [[\SenderRtcpTransport]] internal
slot initialized to null.
Let sender have an
[[\AssociatedMediaStreamIds]] internal slot, representing a
list of Ids of MediaStream objects that this
sender is to be associated with. The
[[\AssociatedMediaStreamIds]] slot is used when
sender is represented in SDP as described in
[[!JSEP]].
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.
Let sender have a [[\SendCodecs]]
internal slot, representing a list of
RTCRtpCodecParameters dictionaries, and
initialized to an empty list.
Let sender have a [[\LastReturnedParameters]]
internal slot, which will be used to match
getParameters and
setParameters transactions.
The track attribute is the track that is
associated with this RTCRtpSender object. If
track is ended, or if the track's output is disabled,
i.e. the track is disabled and/or muted, the RTCRtpSender MUST send silence (audio), black
frames (video) or a zero-information-content equivalent. In the
case of video, the RTCRtpSender SHOULD send one
black frame per second. If track is null then
the RTCRtpSender does not send. On getting, the
attribute MUST return the value of the [[\SenderTrack]]
slot.
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.
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.
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]]).
If transceiver's [[\Stopped]] slot is
true, return a promise rejected with a newly
createdInvalidStateError.
If any of the following conditions are met, return a promise
rejected with a newly
createdInvalidModificationError:
encodings.length is different from N.
encodings has been re-ordered.
Any parameter in parameters is marked as a
Read-only parameter (such as RID) and has a
value that is different from the corresponding parameter
value in sender's [[\LastReturnedParameters]]
internal slot. Note that this also applies to transactionId.
Verify that each scaleResolutionDownBy
value in encodings is greater than or equal to 1.0. If
one of the scaleResolutionDownBy values does not meet
this requirement, return a promise rejected with a newly
createdRangeError.
Verify that each maxFramerate
value in encodings is greater than or equal to 0.0. If
one of the maxFramerate values does not meet
this requirement, return a promise rejected with a newly
createdRangeError.
Let p 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:
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, rejectp 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, rejectp with a newly created RTCError whose errorDetail
is set to "hardware-encoder-error" and abort these
steps.
For all other errors, rejectp
with a newly createdOperationError.
Return p.
setParameters does not cause SDP renegotiation
and can only be used to change what the media stack is sending or
receiving within the envelope negotiated by Offer/Answer. The
attributes in the RTCRtpSendParameters dictionary
are designed to not enable this, so attributes like
cname that cannot be changed are read-only. Other
things, like bitrate, are controlled using limits such as
maxBitrate, where the user agent needs to ensure it
does not exceed the maximum bitrate specified by
maxBitrate, while at the same time making sure it
satisfies constraints on bitrate specified in other places such
as the SDP.
getParameters
The getParameters() method
returns the RTCRtpSender object's current
parameters for how track is encoded and transmitted
to a remote RTCRtpReceiver.
When getParameters is called, the
RTCRtpSendParameters 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.
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.
Let sending be true if the
transceiver's [[\CurrentDirection]]
is "sendrecv" or "sendonly",
and false otherwise.
Run the following steps in parallel:
If sending is true, and
withTrack is null, have the
sender stop sending.
If sending is true, and
withTrack is not null,
determine if withTrack can be sent
immediately by the sender without violating the
sender's already-negotiated envelope, and if it
cannot, then rejectp with a newly
createdInvalidModificationError, and abort these
steps.
If sending is true, and
withTrack is not null, have
the sender switch seamlessly to transmitting
withTrack instead of the sender's existing
track.
Queue a task that runs the following steps:
If connection's [[\IsClosed]]
slot is true, abort these steps.
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.
setStreams
Sets the MediaStreams to be associated with this
sender's track.
When the setStreams method is invoked,
the user agent MUST run the following steps:
Let sender be the
RTCRtpSender object on which this method
was invoked.
Let connection be the
RTCPeerConnection object on which this
method was invoked.
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.
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.
When bandwidth is constrained and the
RTCRtpSender needs to choose between degrading
resolution or degrading framerate,
degradationPreference indicates which is
preferred.
Indicates the priority of an RTCRtpSender, which influences the
bandwidth allocation among RTCRtpSender objects. It is specified
in [[!RTCWEB-TRANSPORT]], Section 4. The user agent is free to sub-allocate bandwidth
between the encodings of an RTCRtpSender.
If set, this RTP encoding will be sent with the RID header
extension as defined by [[!JSEP]]. The RID is not modifiable via
setParameters. It can only be set or modified in
addTransceiver on the sending side.
Read-only parameter.
This member is only used if the sender's kind
is "audio". It 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.
active of type boolean, defaulting to
true
Indicates that this
encoding is actively being sent. Setting it to false
causes this encoding to no longer be sent. Setting it to true
causes this encoding to be sent.
ptime of type unsigned long
When present, indicates the
preferred duration of media represented by a packet in
milliseconds for this encoding. Typically, this is only relevant
for audio encoding. The user agent MUST use this duration if
possible, and otherwise use the closest available duration. This
value MUST take precedence over any "ptime" attribute in the
remote description, whose processing is described in [[!JSEP]]. Note that
the user agent MUST still respect the limit imposed by any
"maxptime" attribute, as defined in [[!RFC4566]], Section 6.
maxBitrate of type unsigned long
When present, indicates the maximum bitrate that can be used to send this
encoding. The user agent is free to allocate bandwidth between the encodings,
as long as the maxBitrate value is not exceeded.
The encoding may also be further constrained by other
limits (such as 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
When present, indicates the maximum framerate that can be used to send this
encoding, in frames per second. The user agent is free to allocate bandwidth
between the encodings, as long as the maxFramerate value is not
exceeded.
If changed with setParameters, the new framerate
takes effect after the current
picture is completed; setting the max framerate to zero thus has
the effect of freezing the video on the next frame.
scaleResolutionDownBy of type
double
This member is only present if the sender's kind
is "video". The video's
resolution will be scaled down in each dimension by the given
value before sending. For example, if the value is 2.0, the video
will be scaled down by a factor of 2 in each dimension, resulting
in sending a video of one quarter the size. If the value is 1.0,
the video will not be affected. The value must be greater than or
equal to 1.0. By default, the sender will not apply any scaling,
(i.e., scaleResolutionDownBy will be 1.0).
The RTCRtpHeaderExtensionParameters dictionary
enables an application to determine whether a header extension
is configured for use within an RTCRtpSender
or RTCRtpReceiver. For an
RTCRtpTransceivertransceiver, an
application can determine the "direction" parameter (defined in
Section 5 of [[RFC5285]]) of a header extension as follows
without having to parse SDP:
sendonly: The header extension is only included in
transceiver.sender.getParameters().headerExtensions.
recvonly: The header extension is only included in
transceiver.receiver.getParameters().headerExtensions.
sendrecv: The header extension is included in both
transceiver.sender.getParameters().headerExtensions and
transceiver.receiver.getParameters().headerExtensions.
inactive: The header extension is included in neither
transceiver.sender.getParameters().headerExtensions nor
transceiver.receiver.getParameters().headerExtensions.
RTCRtpCodecParameters Dictionary
dictionary RTCRtpCodecParameters {
required octet payloadType;
required DOMString mimeType;
required unsigned long clockRate;
unsigned short channels;
DOMString sdpFmtpLine;
};
When present, indicates the number of channels (mono=1, stereo=2). Read-only
parameter.
sdpFmtpLine of type DOMString
The "format specific parameters" field from the "a=fmtp" line
in the SDP corresponding to the codec, if one exists, as defined
by [[!JSEP]]. For an
RTCRtpSender, these parameters come from the
remote description, and for an
RTCRtpReceiver, they come from the local
description. Read-only parameter.
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.
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, required
The codec MIME media type/subtype. Valid media types and
subtypes are listed in [[IANA-RTP-2]].
clockRate of type unsigned long, required
The codec clock rate expressed in Hertz.
channels of type unsigned short
If present, indicates the maximum number of channels (mono=1, stereo=2).
sdpFmtpLine of type DOMString
The "format specific parameters" field from the "a=fmtp" line
in the SDP corresponding to the codec, if one exists.
Let track be a new MediaStreamTrack
object [[!GETUSERMEDIA]]. The source of track is a
remote source provided by receiver. Note that
the track.id is generated by the user agent and does
not map to any track IDs on the remote side.
Initialize track.kind to kind.
Initialize track.label to the result of concatenating
the string "remote " with kind.
Initialize track.readyState to live.
Initialize track.muted to true. See the
MediaStreamTrack section
about how the muted attribute reflects if a
MediaStreamTrack is receiving media data or
not.
Let receiver have a [[\ReceiverTrack]]
internal slot initialized to track.
Let receiver have a [[\ReceiverTransport]] internal
slot initialized to null.
Let receiver have a [[\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.
Let receiver have a [[\ReceiveCodecs]]
internal slot, representing a list of
RTCRtpCodecParameters dictionaries, and
initialized to an empty list.
The track
attribute is the track that is associated with this
RTCRtpReceiver object receiver.
Note that track.stop() is final, although
clones are not affected. Since
receiver.track.stop()
does not implicitly stop receiver, Receiver
Reports continue to be sent. On getting, the attribute MUST
return the value of the [[\ReceiverTrack]] slot.
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.
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.
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
RTCRtpReceiveParameters dictionary is
constructed as follows:
encodings
is populated based on the RIDs present in the current remote
description.
The headerExtensions
sequence is populated based on the header extensions that the
receiver is currently prepared to receive.
Both the local and remote description may
affect this list of codecs. For example, if three codecs are
offered, the receiver will be prepared to receive each of
them and will return them all from
getParameters. But if the remote endpoint only
answers with two, the absent codec will no longer be returned
by getParameters as the receiver no longer needs
to be prepared to receive it.
rtcp.reducedSize
is set to true if the receiver is currently prepared to
receive reduced-size RTCP packets, and false otherwise.
rtcp.cname is
left out.
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 p be a new promise, and run the following
steps in parallel:
The RTCRtpContributingSource and
RTCRtpSynchronizationSource dictionaries contain information
about a given contributing source (CSRC) or synchronization source (SSRC)
respectively, 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 or video 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 information for the
RTCRtpContributingSource and
RTCRtpSynchronizationSource dictionaries based on the
contents of the packet. The information relevant to the
RTCRtpSynchronizationSource dictionary corresponding
to the SSRC identifier, is updated each time, and if the RTP packet
contains CSRC identifiers, then the information relevant to the
RTCRtpContributingSource dictionaries corresponding to
those CSRC identifiers is also updated.
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 returned RTCRtpSynchronizationSource
and RTCRtpContributingSource dictionaries for a
particular RTCRtpReceiver contain information from a
single point in the RTP stream.
The timestamp of type DOMHighResTimeStamp [[!HIGHRES-TIME]],
indicating the most recent time of playout of media that arrived
in an RTP packet originating from this source. The timestamp is
defined as performance.timeOrigin +
performance.now() at the time of playout.
source of type unsigned long, required
The CSRC or SSRC identifier of the contributing or
synchronization source.
audioLevel of type double
Only present for audio receivers. This is a value between 0..1
(linear), where 1.0 represents 0 dBov, 0 represents silence, and
0.5 represents approximately 6 dBSPL change in the sound pressure
level from 0 dBov.
For CSRCs, this MUST be converted from the level value defined
in [[!RFC6465]] if the RFC 6465 header extension is present,
otherwise this member MUST be absent.
For SSRCs, this MUST be converted from the level value defined
in [[!RFC6464]]. If the RFC 6464 header extension is not present
in the received packets (such as if the other endpoint is not a
user agent or is a legacy endpoint), this value SHOULD be absent.
Both RFCs define the level as an integral value from 0 to 127
representing the audio level in negative decibels relative to the
loudest signal that the system could possibly encode. Thus,
0 represents the loudest signal the system could possibly encode,
and 127 represents silence.
To convert these values to the linear 0..1 range, a value of
127 is converted to 0, and all other values are converted using
the equation: 10^(-rfc_level/20).
Only present for audio receivers. 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 absent.
RTCRtpTransceiver Interface
The RTCRtpTransceiver interface represents a
combination of an RTCRtpSender and an
RTCRtpReceiver that share a common
mid. As defined in [[!JSEP]],
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 mid
attribute is the mid negotatiated and present in the
local and remote descriptions as defined in [[!JSEP]]. Before
negotiation is complete, the mid value may be null.
After rollbacks, the value may change from a non-null value
to null.
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.
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.
As defined in [[!JSEP]], the
direction attribute indicates the preferred direction
of this transceiver, which will be used in calls to createOffer and createAnswer. An update
of directionality does not take effect immediately. Instead,
future calls to createOffer
and createAnswer mark the corresponding media
description as sendrecv, sendonly,
recvonly or inactive as defined in
[[!JSEP]]
On getting, this attribute MUST return the value of the
[[\Direction]] slot.
On setting, the user agent MUST run the
following steps:
Let transceiver be the
RTCRtpTransceiver
object on which the setter is
invoked.
Let connection be the
RTCPeerConnection object
associated with transceiver.
As defined in [[!JSEP]], the
currentDirection attribute indicates the current
direction negotiated for this transceiver. The value of
currentDirection is independent of the value of
RTCRtpEncodingParameters.active since one cannot be
deduced from the other. If this transceiver has never been
represented in an offer/answer exchange, or if the transceiver is
stopped, the value is null. On getting, this
attribute MUST return the value of the [[\CurrentDirection]] slot.
Stopping a transceiver will cause future calls
to createOffer or createAnswer to
generate a zero port in the media description for the
corresponding transceiver, as defined in
[[!JSEP]].
If this method is called in between applying a
remote offer and creating an answer, and the transceiver is
associated with the "offerer tagged" media description as
defined in [[!BUNDLE]], this will cause all other transceivers
in the bundle group to be stopped as well. To avoid this, one
could instead stop the transceiver when
signalingState
is "stable"
and perform a subsequent offer/answer exchange.
When the stop method is invoked,
the user agent MUST run the following steps:
Let transceiver be the
RTCRtpTransceiver object on which the
method is invoked.
Let connection be the
RTCPeerConnection object associated with
transceiver.
If connection's signaling state is
have-remote-offer and transceiver is
associated with the "offerer tagged" media description
as defined in [[!BUNDLE]], then for each
RTCRtpTransceiverassociatedTransceiver that is associated with a
media description in the same BUNDLE group as
transceiver,
stop the
RTCRtpTransceiver specified by
associatedTransceiver.
The setCodecPreferences method overrides the
default codec preferences used by the user agent. When
generating a session description using either
createOffer or createAnswer, the
user agent MUST use the indicated codecs, in the order
specified in the codecs argument, for the media
section corresponding to this RTCRtpTransceiver.
This method allows applications to disable the negotiation of
specific codecs (including RTX/RED/FEC). It also allows an
application to cause a remote peer to prefer the codec that
appears first in the list for sending.
Codec preferences remain in effect for all calls to
createOffer and createAnswer that
include this RTCRtpTransceiver until this method is
called again. Setting codecs to an empty sequence
resets codec preferences to any default value.
The codecs sequence passed into
setCodecPreferences can only contain codecs that are
returned by RTCRtpSender.getCapabilities(kind) or
RTCRtpReceiver.getCapabilities(kind), where
kind is the kind of the
RTCRtpTransceiver on which the method is called.
Additionally, the RTCRtpCodecCapability dictionary
members cannot be modified. If codecs does not
fulfill these requirements, the user agent MUST throw an
InvalidAccessError.
Due to a recommendation in [[!SDP]], calls to
createAnswer SHOULD use only the common subset of
the codec preferences and the codecs that appear in the offer.
For example, if codec preferences are "C, B, A", but only codecs
"A, B" were offered, the answer should only contain codecs "B,
A". However, [[!JSEP]]
allows adding codecs that were not in the offer, so
implementations can behave differently.
When setCodecPreferences() in invoked, the user agent
MUST run the following steps:
Let transceiver be the RTCRtpTransceiver
object this method was invoked on.
Let codecs be the first argument.
If codecs is an empty list, set transceiver's
[[\PreferredCodecs]] slot to codecs and abort these steps.
Remove any duplicate values in codecs. Start at the back of the
list such that the priority of the codecs is maintained; the index of the
first occurrence of a codec within the list is the same before and after this
step.
If the intersection between codecs and
RTCRtpSender.getCapabilities(kind).codecs or the intersection
between codecs and
RTCRtpReceiver.getCapabilities(kind).codecs only contains RTX, RED
or FEC codecs or is an empty set,
throw InvalidModificationError. This ensures that we always have
something to offer, regardless of transceiver.direction.
Let codecCapabilities be the union of
RTCRtpSender.getCapabilities(kind).codecs and
RTCRtpReceiver.getCapabilities(kind).codecs.
For each codec in codecs,
If codec is not in codecCapabilities, throw
InvalidModificationError.
If set, the offerer's codec preferences will
decide the order of the codecs in the offer. If the answerer does
not have any codec preferences then the same order will be used in
the answer. However, if the answerer also has codec preferences,
these preferences override the order in the answer. In this case,
the offerer's preferences would affect which codecs were on offer
but not the final order.
Simulcast functionality
Simulcast functionality is provided via the addTransceiver method of the
RTCPeerConnection object and the setParameters method of the
RTCRtpSender object.
The addTransceiver method establishes the simulcast envelope which
includes the maximum number of simulcast streams that can be sent, as well as the ordering of the
encodings. While characteristics of individual simulcast streams can be modified using
the setParameters method, the simulcast envelope cannot be changed. One of the
implications of this model is that the addTrack method cannot provide simulcast
functionality since it does not take sendEncodings as an argument, and therefore cannot
configure an RTCRtpTransceiver to send simulcast.
Another implication is that the answerer cannot set the simulcast envelope directly.
Upon calling the setRemoteDescription method of the RTCPeerConnection
object, the simulcast envelope is configured on the RTCRtpTransceiver
to contain the layers described by the specified RTCSessionDescription.
Once the envelope is determined, layers cannot be removed. They can be marked as inactive by setting
the active attribute to false effectively disabling the layer.
While setParameters cannot modify the simulcast envelope, it is still possible
to control the number of streams that are sent and the characteristics of those streams. Using
setParameters, simulcast streams can be made inactive by setting the active
attribute to false, or can be reactivated by setting the active
attribute to true. Using setParameters, stream characteristics can be
changed by modifying attributes such as maxBitrate and maxFramerate.
As defined in [[!JSEP]], an offer from a user-agent will
only contain a "send" description and no "recv" description on the "a=simulcast" line.
Alternatives and restrictions (described in [[MMUSIC-SIMULCAST]]) are not supported.
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.
An RTCRtpReceiver can receive multiple RTP streams in a scenario
where a Selective Forwarding Unit (SFU) switches between simulcast streams it receives from user agents.
If the SFU does not rewrite RTP headers so as to arrange the switched streams into a single RTP
stream prior to forwarding, the RTCRtpReceiver will receive packets from distinct
RTP streams, each with their own SSRC and sequence number space. While the SFU may only forward a single
RTP stream at any given time, packets from multiple RTP streams can become intermingled at the receiver
due to reordering. An RTCRtpReceiver equipped to receive multiple RTP streams will
therefore need to be able to correctly order the received packets, recognize potential loss events and
react to them. Correct operation in this scenario is non-trivial and therefore is optional for
implementations of this specification.
Encoding Parameter Examples
Examples of simulcast scenarios implemented with encoding parameters:
// Example of 3-layer spatial simulcast with all but the lowest resolution layer disabled
var encodings = [
{rid: 'f', active: false},
{rid: 'h', active: false, scaleResolutionDownBy: 2.0},
{rid: 'q', active: true, scaleResolutionDownBy: 4.0}
];
// Example of 3-layer framerate simulcast with the middle layer disabled
var encodings = [
{rid: 'f', active: true, maxFramerate: 60},
{rid: 'h', active: false, maxFramerate: 30},
{rid: 'q', active: true, maxFramerate: 15}
];
"Hold" functionality
Together, the direction attribute and
the replaceTrack method enable
developers to implement "hold" scenarios.
To send music to a peer and cease rendering received audio (music-on-hold):
async function playMusicOnHold() {
try {
// Assume we have an audio transceiver and a music track named musicTrack
await audio.sender.replaceTrack(musicTrack);
// Mute received audio
audio.receiver.track.enabled = false;
// Set the direction to send-only (requires negotiation)
audio.direction = 'sendonly';
} catch (err) {
console.error(err);
}
}
To respond to a remote peer's "sendonly" offer:
async function handleSendonlyOffer() {
try {
// Apply the sendonly offer first,
// to ensure the receiver is ready for ICE candidates.
await pc.setRemoteDescription(sendonlyOffer);
// Stop sending audio
await audio.sender.replaceTrack(null);
// Align our direction to avoid further negotiation
audio.direction = 'recvonly';
// Call createAnswer and send a recvonly answer
await doAnswer();
} catch (err) {
// handle signaling error
}
}
To stop sending music and send audio captured from a microphone,
as well to render received audio:
async function stopOnHoldMusic() {
// Assume we have an audio transceiver and a microphone track named micTrack
await audio.sender.replaceTrack(micTrack);
// Unmute received audio
audio.receiver.track.enabled = true;
// Set the direction to sendrecv (requires negotiation)
audio.direction = 'sendrecv';
}
To respond to being taken off hold by a remote peer:
async function onOffHold() {
try {
// Apply the sendrecv offer first, to ensure receiver is ready for ICE candidates.
await pc.setRemoteDescription(sendrecvOffer);
// Start sending audio
await audio.sender.replaceTrack(micTrack);
// Set the direction sendrecv (just in time for the answer)
audio.direction = 'sendrecv';
// Call createAnswer and send a sendrecv answer
await doAnswer();
} catch (err) {
// handle signaling error
}
}
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
RTCRtpTransceivers if such a group has been
negotiated via [[!BUNDLE]].
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 and a
[[\RemoteCertificates]] slot initialized to an empty list.
When the underlying DTLS transport experiences an error, such as
a certificate validation failure, or a fatal alert (see [[RFC5246]]
section 7.2), the user agent MUST queue a task that runs the following
steps:
Let transport be the RTCDtlsTransport object to receive the state update
and error notification.
If the state of transport is
already failed, abort these steps.
Fire an event named
error
using the RTCErrorEvent interface with its
errorDetail attribute set to either "dtls-failure" or
"fingerprint-failure", as appropriate, and other fields
set as described under the RTCErrorDetailType enum
description, at transport.
When the underlying DTLS transport needs to update the state of the
corresponding RTCDtlsTransport object for any other
reason, the user agent
MUST queue a task that runs the following steps:
Let transport be the RTCDtlsTransport object to receive the state update.
If newState is
connected
then let newRemoteCertificates be the certificate chain in
use by the remote side, with each certificate encoded in binary
Distinguished Encoding Rules (DER) [[!X690]], and set
transport's [[\RemoteCertificates]] slot to
newRemoteCertificates.
The iceTransport attribute is the underlying
transport that is used to send and receive packets. The
underlying transport may not be shared between multiple active
RTCDtlsTransport objects.
One of the the hash function algorithms defined in the 'Hash
function Textual Names' registry [[!IANA-HASH-FUNCTION]].
value of type DOMString
The value of the certificate fingerprint in lowercase hex
string as expressed utilizing the syntax of 'fingerprint' in
[[!RFC4572]] Section 5.
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
RTCRtpTransceivers if such a group has been
negotiated via [[!BUNDLE]].
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:
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:
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:
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:
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".
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.
The RTCIceTransport is gathering
candidates and/or waiting for remote candidates to be supplied,
and has not yet started checking.
checking
The RTCIceTransport has received at least
one remote candidate and is checking candidate pairs and has
either not yet found a connection or consent checks [[!RFC7675]]
have failed on all previously successful candidate pairs. In
addition to checking, it may also still be gathering.
connected
The RTCIceTransport has found a usable
connection, but is still checking other candidate pairs to see if
there is a better connection. It may also still be gathering
and/or waiting for additional remote candidates. If consent
checks [[!RFC7675]] fail on the connection in use, and there are
no other successful candidate pairs available, then the state
transitions to "checking" (if there are candidate pairs remaining
to be checked) or "disconnected" (if there are no candidate pairs
to check, but the peer is still gathering and/or waiting for
additional remote candidates).
completed
The RTCIceTransport has finished
gathering, received an indication that there are no more remote
candidates, finished checking all candidate pairs and found a
connection. If consent checks [[!RFC7675]] subsequently fail on
all successful candidate pairs, the state transitions to
"failed".
disconnected
The ICE Agent has determined that connectivity is
currently lost for this RTCIceTransport.
This is a transient state that may
trigger intermittently (and resolve itself without action) on a
flaky network. The way this state is determined is
implementation dependent. Examples include:
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 not found a
connection (or consent checks [[!RFC7675]] once
successful, have now failed), but it is still gathering and/or
waiting for additional remote candidates.
failed
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.
This is a terminal state.
closed
The RTCIceTransport has shut down and is
no longer responding to STUN requests.
An ICE restart causes candidate gathering and connectity checks to
begin anew, causing a transition to connected if begun in the
completed state. If begun in the transient
disconnected state, it causes a transition to
checking, effectively forgetting that connectivity was
previously lost.
The failed and completed states require an
indication that there are no additional remote candidates. This can be
indicated by calling addIceCandidate with
a candidate value whose candidate property is set
to an empty string or by canTrickleIceCandidates being set to
false.
Some example state transitions are:
(RTCIceTransport first created, as a result of
setLocalDescription or setRemoteDescription):
new
(new, remote candidates received):
checking
(checking, found usable connection):
connected
(checking, checks fail but gathering still in
progress): disconnected
(checking, gave up): failed
(disconnected, new local candidates):
checking
(connected, finished all checks):
completed
(completed, lost connectivity):
disconnected
(disconnected or failed, ICE restart occurs):
checking
(completed, ICE restart occurs):
connected
RTCPeerConnection.close(): closed
Non-normative ICE transport state transition diagram
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 1 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 2 when encoded in
candidate-attribute.
The transceiver attribute represents the
RTCRtpTransceiver object associated with the
event.
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]].
RTCPeerConnection Interface Extensions
The Peer-to-peer data API extends the
RTCPeerConnection interface as described below.
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.
Initialize channel's [[\Negotiated]]
slot to option's negotiated member.
Initialize channel's [[\DataChannelId]]
slot to the value of option's
id member, if it is present and
[[\Negotiated]] is true, otherwise
null.
This means the id member will be ignored if
the data channel is negotiated in-band; this is
intentional. Data channels negotiated in-band should have
IDs selected based on the DTLS role, as specified in
[[!RTCWEB-DATA-PROTOCOL]].
If a setting, either [[\MaxPacketLifeTime]] or
[[\MaxRetransmits]],
has been set to indicate unreliable mode, and that value
exceeds the maximum value supported by the user agent, the
value MUST be set to the user agents maximum value.
If [[\DataChannelId]] is
equal to 65535, which is greater than the maximum allowed ID
of 65534 but still qualifies as an unsigned short, throw a
TypeError.
If the [[\DataChannelId]]
slot is null (due to no ID being passed into
createDataChannel, or [[\Negotiated]] being false),
and the DTLS role of the SCTP transport has already been
negotiated, then initialize [[\DataChannelId]]
to a value generated by the
user agent, according to [[!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.
Let remoteMaxMessageSize be the value of the
"max-message-size" SDP attribute read from the remote description,
as described in [[!SCTP-SDP]] (section 6), or 65536 if the
attribute is missing.
Let canSendSize be the number of bytes that this
client can send (i.e. the size of the local send buffer) or 0 if
the implementation can handle messages of any size.
If both remoteMaxMessageSize and
canSendSize are 0, set [[\MaxMessageSize]] to the
positive Infinity value.
Else, if either remoteMaxMessageSize or
canSendSize is 0, set [[\MaxMessageSize]] to the
larger of the two.
Else, set [[\MaxMessageSize]] to the smaller of
remoteMaxMessageSize or canSendSize.
Connected procedure
Once an SCTP transport
is connected, meaning the SCTP association of an
RTCSctpTransport has been established, run the following
steps:
The current state of the SCTP transport. On getting, this
attribute MUST return the value of the
[[\SctpTransportState]] slot.
maxMessageSize of type unrestricted double, readonly
The maximum size of data that can be passed to
RTCDataChannel's send() method. The attribute MUST,
on getting, return the value of the [[\MaxMessageSize]]
slot.
maxChannels of type
unsigned short
, readonly, nullable
The maximum amount of RTCDataChannel's
that can be used simultaneously. The attribute MUST, on
getting, return the value of the [[\MaxChannels]] slot.
This attribute's value will be
null until the SCTP transport went into the
connected state.
onstatechange of type EventHandler
The event type of this event handler is
statechange.
RTCSctpTransportState Enum
RTCSctpTransportState indicates the state of the SCTP
transport.
The RTCSctpTransport is in the process of
negotiating an association. This is the initial state of the
[[\SctpTransportState]] slot when an
RTCSctpTransport is created.
connected
When the negotiation of an association is completed, a task is
queued to update the [[\SctpTransportState]] slot to
"connected".
closed
A task is queued to update the [[\SctpTransportState]]
slot to "closed" when a SHUTDOWN or ABORT chunk
is received or when 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.
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
negotiatedRTCDataChannelInit 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 negotiatedRTCDataChannelInit 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
negotiatedRTCDataChannelInit 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 ids.
Each RTCDataChannel has an associated
underlying data transport that is
used to transport actual data to the other peer. In the case of SCTP
data channels utilizing an RTCSctpTransport (which
represents the state of the SCTP association), the underlying data
transport is the SCTP stream pair. The transport properties of
the underlying data transport, such as in order delivery
settings and reliability mode, are configured by the peer as the channel
is created. The properties of a channel cannot change after the channel
has been created. The actual wire protocol between the peers is specified
by the WebRTC DataChannel Protocol specification [[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.
Let channel have a [[\ReadyState]] internal
slot initialized to "connecting".
Let channel have a [[\BufferedAmount]]
internal slot initialized to 0.
Let channel have internal slots named
[[\DataChannelLabel]], [[\Ordered]],
[[\MaxPacketLifeTime]], [[\MaxRetransmits]],
[[\DataChannelProtocol]], [[\Negotiated]],
[[\DataChannelId]], and
[[\DataChannelPriority]].
Return channel.
When the user agent is to announce an RTCDataChannel as
open, the user agent MUST queue a task to run the following
steps:
When an underlying data transport is to be announced (the other
peer created a channel with negotiated unset or set to false), the
user agent of the peer that did not initiate the creation process MUST
queue a task to run the following steps:
Let 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]].
An RTCDataChannel object's underlying data
transport may be torn down in a non-abrupt manner by running the
closing procedure. When
that happens the user agent MUST queue a task to run the following
steps:
If the transport was closed
with an error, fire
an event named error using the
RTCErrorEvent interface with its
errorDetail attribute set to "sctp-failure"
at channel.
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:
When an
RTCDataChannel message has been received via
the underlying data transport with type type and data
rawData, the user agent MUST queue a task to run the following
steps:
Let channel be the RTCDataChannel
object for which the user agent has received a message.
If channel's [[\ReadyState]] slot is not
open, abort these steps and discard rawData.
Execute the sub step by switching on type and the
channel's binaryType:
If type indicates that rawData is a
string:
Let data be a DOMString that represents the
result of decoding rawData as UTF-8.
If type indicates that rawData is binary
and binaryType is "blob":
Let data be a new Blob object
containing rawData as its raw data source.
If type indicates that rawData is binary
and binaryType is "arraybuffer":
Let data be a new ArrayBuffer object
containing rawData as its raw data source.
Fire an event named message using the
MessageEvent interface
with its origin attribute initialized
to the origin of the document that created the channel's
associated RTCPeerConnection, and the data
attribute initialized to data at
channel.
The label
attribute represents a label that can be used to distinguish this
RTCDataChannel object from other
RTCDataChannel objects. Scripts are allowed
to create multiple RTCDataChannel objects
with the same label. On getting, the attribute MUST return the
value of the [[\DataChannelLabel]] slot.
ordered of type boolean, readonly
The ordered attribute
returns true if the RTCDataChannel is
ordered, and false if out of order delivery is allowed. On
getting, the attribute MUST return the value of the [[\Ordered]] slot.
maxPacketLifeTime of type unsigned short, readonly,
nullable
The maxPacketLifeTime
attribute returns the length of the time window (in milliseconds)
during which transmissions and retransmissions may occur in
unreliable mode. On getting, the attribute MUST return the value
of the [[\MaxPacketLifeTime]]
slot.
maxRetransmits of type unsigned short, readonly,
nullable
The maxRetransmits
attribute returns the maximum number of retransmissions that are
attempted in unreliable mode. On getting, the attribute MUST
return the value of the [[\MaxRetransmits]] slot.
protocol of type USVString, readonly
The protocol attribute
returns the name of the sub-protocol used with this
RTCDataChannel. On getting, the attribute MUST
return the value of the [[\DataChannelProtocol]]
slot.
negotiated of type boolean, readonly
The negotiated
attribute returns true if this RTCDataChannel
was negotiated by the application, or false otherwise. On getting,
the attribute MUST return the value of the [[\Negotiated]] slot.
id of type unsigned short, readonly, nullable
The id attribute returns the ID for this
RTCDataChannel. The value is initially null,
which is what will be returned
if the ID was not provided at channel creation time, and the DTLS
role of the SCTP transport has not yet been negotiated.
Otherwise, it will return the ID that was either selected by the
script or generated by the user agent according to
[[!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.
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.
The readyState
attribute represents the state of the RTCDataChannel
object. On getting, the attribute MUST return the value
of the [[\ReadyState]] slot.
bufferedAmount of type unsigned long, readonly
The bufferedAmount
attribute MUST, on getting, return the value of the
[[\BufferedAmount]] slot. The attribute exposes the number
of bytes of application data
(UTF-8 text and binary data) that have been queued using
send(). Even
though the data transmission can occur in parallel, the returned
value MUST NOT be decreased before the current task yielded back
to the event loop to prevent race conditions.
The value does not include framing overhead incurred by the
protocol, or buffering done by the operating system or network
hardware. The value of the [[\BufferedAmount]] slot will
only increase with each call to the send() method as long as the
[[\ReadyState]] slot is open; however, the
slot does not reset to zero once the channel closes. When the
underlying data transport sends data from its queue, the
user agent MUST queue a task that reduces
[[\BufferedAmount]] with the number of bytes that was
sent.
bufferedAmountLowThreshold of type unsigned long
The bufferedAmountLowThreshold
attribute sets the threshold at which the bufferedAmount is considered to be
low. When the bufferedAmount decreases from above
this threshold to equal or below it, the bufferedamountlow
event fires. The bufferedAmountLowThreshold is
initially zero on each new RTCDataChannel,
but the application may change its value at any time.
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.
The binaryType
attribute MUST, on getting, return the value to which it was
last set. On setting, if the new value is either the string
"blob" or the string "arraybuffer",
then set the IDL attribute to this new value. Otherwise,
throw a SyntaxError. When an
RTCDataChannel object is
created, the binaryType attribute MUST be
initialized to the string "blob".
This attribute controls how binary data is exposed to scripts.
See 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.
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.
If set to true, the application must also take
care to not send a message until the other peer has created a
data channel to receive it. Receiving a message on an SCTP stream
with no associated data channel is undefined behavior, and it may
be silently dropped. This will not be possible as long as both
endpoints create their data channel before the first offer/answer
exchange is complete.
id of type unsigned short
Overrides the default selection of ID for 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.
Execute the sub step that corresponds to the type of the methods
argument:
string object:
Let data be a byte buffer that represents the
result of encoding the method's argument as UTF-8.
Blob object:
Let data be the raw data represented by the
Blob object.
ArrayBuffer object:
Let data be the data stored in the buffer described
by the ArrayBuffer object.
ArrayBufferView object:
Let data be the data stored in the section of the
buffer described by the ArrayBuffer object that the
ArrayBufferView object references.
Any data argument type this method has not been
overloaded with will result in a TypeError. This includes
null and undefined.
If the byte size of data exceeds the value of maxMessageSize on
channel's associated RTCSctpTransport,
throw a TypeError.
Queue data for transmission on channel's
underlying data transport. If queuing data is not
possible because not enough buffer space is available, throw
an OperationError.
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.
Increase the value of the [[\BufferedAmount]] slot by
the byte size of data.
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]].
RTCRtpSender Interface Extensions
The Peer-to-peer DTMF API extends the RTCRtpSender
interface as described below.
On getting, the dtmf attribute returns the value
of the [[\Dtmf]]internal slot, which represents a RTCDTMFSender which can be used to send DTMF, or
null if unset. The [[\Dtmf]]internal slot is set
when the kind of an RTCRtpSender's
[[\SenderTrack]] is "audio".
RTCDTMFSender
To create an RTCDTMFSender, the user agent MUST
run the following steps:
The event type of this event handler is
tonechange.
canInsertDTMF of type boolean, readonly
Whether the RTCDTMFSenderdtmfSender is capable of sending
DTMF. On getting, the user agent MUST return the result of running
determine if DTMF can be sent for dtmfSender.
toneBuffer of type DOMString, readonly
The toneBuffer
attribute MUST return a list of the tones remaining to be played
out. For the syntax, content, and interpretation of this list,
see insertDTMF.
Methods
insertDTMF
An RTCDTMFSender object's insertDTMF
method is used to send DTMF tones.
The tones parameter is treated as a series of characters. The
characters 0 through 9, A through D, #, and * generate the
associated DTMF tones. The characters a to d MUST be normalized
to uppercase on entry and are equivalent to A to D. As noted in
[[RTCWEB-AUDIO]] Section 3, support for the characters 0 through
9, A through D, #, and * are required. The character ',' MUST be
supported, and indicates a delay of 2 seconds before processing
the next character in the tones parameter. All other characters
(and only those other characters) MUST be considered unrecognized.
The duration parameter indicates the duration in ms to use for
each character passed in the tones parameters. The duration
cannot be more than 6000 ms or less than 40 ms. The default
duration is 100 ms for each tone.
The interToneGap parameter indicates the gap between tones in
ms. The user agent clamps it to at least 30 ms and at most
6000 ms. The default value is 70 ms.
The browser MAY increase the duration and interToneGap times
to cause the times that DTMF start and stop to align with the
boundaries of RTP packets but it MUST not increase either of them
by more than the duration of a single RTP audio packet.
When the insertDTMF() method is invoked,
the user agent MUST run the following steps:
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.
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.
canInsertDTMF algorithm
To determine if DTMF can be sent for an RTCDTMFSender
instance dtmfSender, the user agent MUST queue a task that runs the following steps:
Let sender be the RTCRtpSender associated with
dtmfSender.
The tone attribute contains the
character for the tone (including ",") that has just
begun playout (see insertDTMF ). If
the value is the empty string, it indicates that the
[[\ToneBuffer]] slot is an empty string and that
the previous tones have completed playback.
The 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.
Statistics Model
Introduction
The basic statistics model is that the browser maintains a set of
statistics for monitored objects, in the form of stats objects.
A group of related objects may be
referenced by a selector. The
selector may, for example, be a MediaStreamTrack. For a
track to be a valid selector, it MUST be a MediaStreamTrack
that is sent or received by the RTCPeerConnection
object on which the stats request was issued. The calling Web application
provides the selector to the getStats() method and the browser emits
(in the JavaScript) a set of statistics that are relevant to the selector,
according to the stats selection algorithm. Note that that
algorithm takes the sender or receiver of a selector.
The statistics returned in stats objects are designed in such a
way that repeated queries can be linked by the
RTCStatsid dictionary
member. Thus, a Web application can make measurements over a given time
period by requesting measurements at the beginning and end of that period.
With a few exceptions, monitored objects, once created, exist for
the duration of their associated RTCPeerConnection.
This ensures statistics from them are available in the result from getStats()
even past the associated peer connection being closed.
Only a few monitored objects have shorter lifetimes. For these objects,
their lifetime ends when they are deleted
by algorithms. At the time of deletion, a record of their statistics is
emitted in a single statsended event containing an
RTCStatsReport object with statistics from all
objects deleted at the same time. Statistics from these objects are no
longer available in subsequent getStats() results. The object descriptions in
[[WEBRTC-STATS]] describe when these monitored objects are
deleted.
RTCPeerConnection Interface Extensions
The Statistics API extends the RTCPeerConnection
interface as described below.
The event type of this event handler
is statsended.
To delete stats for a set of monitored objects
associated with an RTCPeerConnection,
connection, the UA MUST run the following steps in
parallel:
Gather stats only for the set of monitored objects
to be deleted. These stats MUST represent final values at the
time of deletion. Stats for these monitored objects MUST NOT
appear in subsequent calls to 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
createdInvalidAccessError.
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).
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.
RTCStats Dictionary
An RTCStats dictionary represents the stats object
constructed by inspecting a specific monitored object.
The RTCStats dictionary is a base type that specifies
as set of default attributes, such as timestamp and type. Specific
stats are added by extending the RTCStats
dictionary.
Note that while stats names are standardized, any given implementation
may be using experimental values or values not yet known to the Web
application. Thus, applications MUST be prepared to deal with unknown
stats.
Statistics need to be synchronized with each other in order to yield
reasonable values in computation; for instance, if "bytesSent" and
"packetsSent" are both reported, they both need to be reported over the
same interval, so that "average packet size" can be computed as "bytes /
packets" - if the intervals are different, this will yield errors. Thus
implementations MUST return synchronized values for all stats in an
RTCStats-derived dictionary.
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.
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]].
The report
attribute contains the stats objects of the appropriate
subclass of RTCStats
object giving the value of the statistics for the monitored objects
whose lifetime have ended, at the time that it ended.
Contains the RTCStats objects giving the
stats for the objects whose lifetime have ended.
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.
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, kind,
transportId, codecId, nackCount
RTCReceivedRTPStreamStats, with all required attributes from its
inherited dictionaries, and also attributes packetsReceived,
packetsLost, jitter, packetsDiscarded
RTCInboundRTPStreamStats, with all required attributes from its
inherited dictionaries, and also attributes bytesReceived, trackId,
receiverId, 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 trackId, senderId, remoteId, framesEncoded
RTCRemoteOutboundRTPStreamStats, with all required attributes from
its inherited dictionaries, and also attributes localId, remoteTimestamp
RTCPeerConnectionStats, with attributes dataChannelsOpened,
dataChannelsClosed
RTCIceCandidateStats, with attributes address, port, protocol,
candidateType, 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.
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:
async function gatherStats() {
try {
const sender = pc.getSenders()[0];
const baselineReport = await sender.getStats();
await new Promise((resolve) => setTimeout(resolve, aBit)); // ... wait a bit
const currentReport = await sender.getStats();
// compare the elements from the current report with the baseline
for (let now of currentReport.values()) {
if (now.type != 'outbound-rtp') continue;
// get the corresponding stats from the baseline report
const base = baselineReport.get(now.id);
if (base) {
const remoteNow = currentReport.get(now.remoteId);
const remoteBase = baselineReport.get(base.remoteId);
const packetsSent = now.packetsSent - base.packetsSent;
const packetsReceived = remoteNow.packetsReceived - remoteBase.packetsReceived;
const fractionLost = (packetsSent - packetsReceived) / packetsSent;
if (fractionLost > 0.3) {
// if fractionLost is > 0.3, we have probably found the culprit
}
}
}
} catch (err) {
console.error(err);
}
}
Media Stream API Extensions for Network Use
Introduction
The MediaStreamTrack interface, as defined in the
[[!GETUSERMEDIA]] specification, typically represents a stream of data of
audio or video. One or more MediaStreamTracks can be
collected in a MediaStream (strictly speaking, a
MediaStream as defined in [[!GETUSERMEDIA]] may contain zero
or more MediaStreamTrack objects).
A MediaStreamTrack may be extended to represent a media
flow that either comes from or is sent to a remote peer (and not just the
local camera, for instance). The extensions required to enable this
capability on the MediaStreamTrack object will be described
in this section. How the media is transmitted to the peer is described in
[[!RTCWEB-RTP]], [[!RTCWEB-AUDIO]], and [[!RTCWEB-TRANSPORT]].
A MediaStreamTrack sent to another peer will appear as
one and only one MediaStreamTrack to the recipient. A peer
is defined as a user agent that supports this specification. In addition,
the sending side application can indicate what MediaStream
object(s) the MediaStreamTrack is a member of. The
corresponding MediaStream object(s) on the receiver side
will be created (if not already present) and populated accordingly.
As also described earlier in this document, the objects
RTCRtpSender and RTCRtpReceiver can be used by
the application to get more fine grained control over the transmission
and reception of MediaStreamTracks.
Channels are the smallest unit considered in the
MediaStream specification. Channels are intended to be
encoded together for transmission as, for instance, an RTP payload type.
All of the channels that a codec needs to encode jointly MUST be in the
same MediaStreamTrack and the codecs SHOULD be able to
encode, or discard, all the channels in the track.
The concepts of an input and output to a given
MediaStreamTrack apply in the case of
MediaStreamTrack objects transmitted over the network as
well. A MediaStreamTrack created by an
RTCPeerConnection object (as described previously in
this document) will take as input the data received from a remote peer.
Similarly, a MediaStreamTrack from a local source, for
instance a camera via [[!GETUSERMEDIA]], will have an output that
represents what is transmitted to a remote peer if the object is used
with an RTCPeerConnection object.
The concept of duplicating MediaStream and
MediaStreamTrack objects as described in [[!GETUSERMEDIA]]
is also applicable here. This feature can be used, for instance, in a
video-conferencing scenario to display the local video from the user's
camera and microphone in a local monitor, while only transmitting the
audio to the remote peer (e.g. in response to the user using a "video
mute" feature). Combining different MediaStreamTrack objects
into new MediaStream objects is useful in certain
situations.
In this document, we only specify aspects of the
following objects that are relevant when used along with an
RTCPeerConnection. Please refer to the original
definitions of the objects in the [[!GETUSERMEDIA]] document for general
information on using MediaStream and
MediaStreamTrack.
MediaStream
id
The id
attribute specified in MediaStream returns an id that is
unique to this stream, so that streams can be recognized at the remote
end of the RTCPeerConnection API.
When a MediaStream is created to represent a
stream obtained from a remote peer, the id
attribute is initialized from information provided by the remote
source.
The id of a MediaStream object is
unique to the source of the stream, but that does not mean it is not
possible to end up with duplicates. For example, the tracks of a
locally generated stream could be sent from one user agent to a remote
peer using RTCPeerConnection and then sent back to
the original user agent in the same manner, in which case the original
user agent will have multiple streams with the same id (the
locally-generated one and the one received from the remote peer).
MediaStreamTrack
A MediaStreamTrack object's reference to its
MediaStream in the non-local media source case (an RTP
source, as is the case for each MediaStreamTrack
associated with
an RTCRtpReceiver) is always strong.
The procedures
add a track,
remove a track and
set a track's
muted state are specified in [[!GETUSERMEDIA]].
When a MediaStreamTrack track produced by
an RTCRtpReceiverreceiver has
ended [[!GETUSERMEDIA]] (such as via a call to
receiver.track.stop), the user agent MAY
choose to free resources allocated for the incoming stream, by
for instance turning off the decoder of receiver.
MediaTrackSupportedConstraints, MediaTrackCapabilities,
MediaTrackConstraints and MediaTrackSettings
The basics of MediaTrackSupportedConstraints,
MediaTrackCapabilites, MediaTrackConstraints
and MediaTrackSettings is outlined in [[!GETUSERMEDIA]].
However, the MediaTrackSettings for a
MediaStreamTrack sourced by an
RTCPeerConnection will only be populated with
members to the extent that data is supplied by means of the remote
RTCSessionDescription applied via
setRemoteDescription and the actual RTP data. This means
that certain members, such as facingMode,
echoCancellation, latency,
deviceId and groupId, will always be
missing.
Direct Connection Permission API
The Direct Connection Permission API allows a web application to request permission to use a less strict policy regarding sharing local addresses as defined in [[RTCWEB-IP-HANDLING]]. This API and the behavioral requirements of the user agent ensure that permission can be requested in a use case neutral way. Once permission has been granted, it provides explicit user consent as required by [[RTCWEB-IP-HANDLING]].
The best available IP handling mode the user agent can offer SHOULD be Mode 1 (enumerate all addresses) and the default IP handling mode the user agent uses by default SHOULD be Mode 2 (default route and associated local addresses). However, the user agent MAY choose different modes determined by the user agents preferences.
RTCPeerConnection Interface Extensions
The Direct Connection Permission API extends the RTCPeerConnection interface as described below.
If the mode is being upgraded, the event will be fired. However, if the mode has been downgraded, the event will not fire and the downgrade will not be effective for the lifetime of the RTCPeerConnection.
Direct Connection Permission Usage Examples
A web application using the Direct Connection Permission API is recommended to only request this permission when really needed. If it does request the permission, it should provide context. Furthermore, it should not rely on a permission request being prompted. While the user agent may use a prompt, it may also use different techniques to enable explicit permission approval, for example in form of a toggle button next to the address bar of the browser.
The following examples will provide usage suggestions for a couple of use cases.
Upgrade connection
The following mechanism can be used for applications that want to establish a connection as soon as possible, albeit potentially not as direct as possible. In this example, the application tries to upgrade as soon as a connection has been established that is not considered ideal (or the connection could not be established).
pc.onconnectionupgradable = async () => {
// Initiate an ICE restart
const offer = await pc.createOffer({iceRestart: true});
// Exchange offer/answer via the signalling channel...
};
pc.onconnectionstatechange = async () => {
const state = pc.connectionState;
if (state === 'failed' || state === 'connected') {
// For audio/video...
const iceTransport = rtpReceiver.transport.iceTransport
// For data channels...
const iceTransport = pc.sctp.transport.iceTransport;
// Check if requesting a direct connection would be useful
const pair = iceTransport.getSelectedCandidatePair();
if (pair.local.type !== 'host') {
// Once granted, this will fire the 'connectionupgradable' event
RTCPeerConnection.registerDirectConnectionInterest();
}
}
};
Ideally, the application supplies a mechanism to coordinate the permission request on both sides (if needed), to prevent two consecutive ICE restarts.
Joining a session
Voice and video chats usually have the concept of a room that is being joined. When a user joins such a room, the permission could be requested which would provide sufficient context to the user.
pc.onconnectionupgradable = async () => {
// Initiate an ICE restart
const offer = await pc.createOffer({iceRestart: true});
// Exchange offer/answer via the signalling channel...
};
async function joinRoom() {
// Request camera/microphone access if desired
// Media devices may implicitly grant a direct connection permission
try {
await navigator.mediaDevices.getUserMedia(constraints);
} catch (err) {
console.error(err);
}
// Once granted, this will fire the 'connectionupgradable' event if needed
RTCPeerConnection.registerDirectConnectionInterest();
// Now, create the peer-to-peer connection
}
Sending a file
A file sharing application will eventually have to let the user choose a file to be transmitted. Once that selection has been made, requesting a direct connection should provide sufficient context to the user.
pc.onconnectionupgradable = async () => {
// Initiate an ICE restart
const offer = await pc.createOffer({iceRestart: true});
// Exchange offer/answer via the signalling channel...
};
async function onFileSelected(file) {
// Once granted, this will fire the 'connectionupgradable' event if needed
RTCPeerConnection.registerDirectConnectionInterest();
// Now, create the peer-to-peer connection
// Then, send the file via a data channel
}
Examples and Call Flows
Simple Peer-to-peer Example
When two peers decide they are going to set up a connection to each
other, they both go through these steps. The STUN/TURN server
configuration describes a server they can use to get things like their
public IP address or to set up NAT traversal. They also have to send
data for the signaling channel to each other using the same out-of-band
mechanism they used to establish that they were going to communicate in
the first place.
const signaling = new SignalingChannel(); // handles JSON.stringify/parse
const constraints = {audio: true, video: true};
const configuration = {iceServers: [{urls: 'stuns:stun.example.org'}]};
const pc = new RTCPeerConnection(configuration);
// send any ice candidates to the other peer
pc.onicecandidate = ({candidate}) => signaling.send({candidate});
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
try {
await pc.setLocalDescription(await pc.createOffer());
// send the offer to the other peer
signaling.send({desc: pc.localDescription});
} catch (err) {
console.error(err);
}
};
// once media for a remote track arrives, show it in the remote video element
pc.ontrack = (event) => {
// don't set srcObject again if it is already set.
if (remoteView.srcObject) return;
remoteView.srcObject = event.streams[0];
};
// call start() to initiate
async function start() {
try {
// get a local stream, show it in a self-view and add it to be sent
const stream = await navigator.mediaDevices.getUserMedia(constraints);
stream.getTracks().forEach((track) => pc.addTrack(track, stream));
selfView.srcObject = stream;
} catch (err) {
console.error(err);
}
}
signaling.onmessage = async ({desc, candidate}) => {
try {
if (desc) {
// if we get an offer, we need to reply with an answer
if (desc.type == 'offer') {
await pc.setRemoteDescription(desc);
const stream = await navigator.mediaDevices.getUserMedia(constraints);
stream.getTracks().forEach((track) => pc.addTrack(track, stream));
await pc.setLocalDescription(await pc.createAnswer());
signaling.send({desc: pc.localDescription});
} else if (desc.type == 'answer') {
await pc.setRemoteDescription(desc);
} else {
console.log('Unsupported SDP type. Your code may differ here.');
}
} else if (candidate) {
await pc.addIceCandidate(candidate);
}
} catch (err) {
console.error(err);
}
};
Advanced Peer-to-peer Example with Warm-up
When two peers decide they are going to set up a connection to each
other and want to have the ICE, DTLS, and media connections "warmed up"
such that they are ready to send and receive media immediately, they
both go through these steps.
const signaling = new SignalingChannel();
const configuration = {iceServers: [{urls: 'stuns:stun.example.org'}]};
const audio = null;
const audioSendTrack = null;
const video = null;
const videoSendTrack = null;
const started = false;
let pc;
// Call warmup() to warm-up ICE, DTLS, and media, but not send media yet.
async function warmup(isAnswerer) {
pc = new RTCPeerConnection(configuration);
if (!isAnswerer) {
audio = pc.addTransceiver('audio');
video = pc.addTransceiver('video');
}
// send any ice candidates to the other peer
pc.onicecandidate = (event) => {
signaling.send(JSON.stringify({candidate: event.candidate}));
};
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
try {
await pc.setLocalDescription(await pc.createOffer());
// send the offer to the other peer
signaling.send(JSON.stringify({desc: pc.localDescription}));
} catch (err) {
console.error(err);
}
};
// once media for the remote track arrives, show it in the remote video element
pc.ontrack = async (event) => {
try {
if (event.track.kind == 'audio') {
if (isAnswerer) {
audio = event.transceiver;
audio.direction = 'sendrecv';
if (started && audioSendTrack) {
await audio.sender.replaceTrack(audioSendTrack);
}
}
} else if (event.track.kind == 'video') {
if (isAnswerer) {
video = event.transceiver;
video.direction = 'sendrecv';
if (started && videoSendTrack) {
await video.sender.replaceTrack(videoSendTrack);
}
}
}
// don't set srcObject again if it is already set.
if (remoteView.srcObject) return;
remoteView.srcObject = event.streams[0];
} catch (err) {
console.error(err);
}
};
try {
// get a local stream, show it in a self-view and add it to be sent
const stream = await navigator.mediaDevices.getUserMedia({audio: true, video: true});
selfView.srcObject = stream;
audioSendTrack = stream.getAudioTracks()[0];
if (started) {
await audio.sender.replaceTrack(audioSendTrack);
}
videoSendTrack = stream.getVideoTracks()[0];
if (started) {
await video.sender.replaceTrack(videoSendTrack);
}
} catch (err) {
console.erro(err);
}
}
// Call start() to start sending media.
function start() {
started = true;
signaling.send(JSON.stringify({start: true}));
}
signaling.onmessage = async (event) => {
if (!pc) warmup(true);
try {
const message = JSON.parse(event.data);
if (message.desc) {
const desc = message.desc;
// if we get an offer, we need to reply with an answer
if (desc.type == 'offer') {
await pc.setRemoteDescription(desc);
await pc.setLocalDescription(await pc.createAnswer());
signaling.send(JSON.stringify({desc: pc.localDescription}));
} else {
await pc.setRemoteDescription(desc);
}
} else if (message.start) {
started = true;
if (audio && audioSendTrack) {
await audio.sender.replaceTrack(audioSendTrack);
}
if (video && videoSendTrack) {
await video.sender.replaceTrack(videoSendTrack);
}
} else {
await pc.addIceCandidate(message.candidate);
}
} catch (err) {
console.error(err);
}
};
Peer-to-peer Example with media before signaling
The answerer may wish to send media in parallel with sending the
answer, and the offerer may wish to render the media before the answer
arrives.
const signaling = new SignalingChannel();
const configuration = {iceServers: [{urls: 'stuns:stun.example.org'}]};
let pc;
// call start() to initiate
async function start() {
pc = new RTCPeerConnection(configuration);
// send any ice candidates to the other peer
pc.onicecandidate = (event) => {
signaling.send(JSON.stringify({candidate: event.candidate}));
};
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
try {
await pc.setLocalDescription(await pc.createOffer());
// send the offer to the other peer
signaling.send(JSON.stringify({desc: pc.localDescription}));
} catch (err) {
console.error(err);
}
};
try {
// get a local stream, show it in a self-view and add it to be sent
const stream = await navigator.mediaDevices.getUserMedia({audio: true, video: true});
selfView.srcObject = stream;
// Render the media even before ontrack fires.
remoteView.srcObject = new MediaStream(pc.getReceivers().map((r) => r.track));
} catch (err) {
console.error(err);
}
};
signaling.onmessage = async (event) => {
if (!pc) start();
try {
const message = JSON.parse(event.data);
if (message.desc) {
const desc = message.desc;
// if we get an offer, we need to reply with an answer
if (desc.type == 'offer') {
await pc.setRemoteDescription(desc);
await pc.setLocalDescription(await pc.createAnswer());
signaling.send(JSON.stringify({desc: pc.localDescription}));
} else {
await pc.setRemoteDescription(desc);
}
} else {
await pc.addIceCandidate(message.candidate);
}
} catch (err) {
console.error(err);
}
};
Simulcast Example
A client wants to send multiple RTP encodings (simulcast) to a
server.
const signaling = new SignalingChannel();
const configuration = {'iceServers': [{'urls': 'stuns:stun.example.org'}]};
let pc;
// call start() to initiate
async function start() {
pc = new RTCPeerConnection(configuration);
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
try {
await pc.setLocalDescription(await pc.createOffer());
// send the offer to the other peer
signaling.send(JSON.stringify({desc: pc.localDescription}));
} catch (err) {
console.error(err);
}
};
try {
// get a local stream, show it in a self-view and add it to be sent
const stream = await navigator.mediaDevices.getUserMedia({audio: true, video: true});
selfView.srcObject = stream;
pc.addTransceiver(stream.getAudioTracks()[0], {direction: 'sendonly'});
pc.addTransceiver(stream.getVideoTracks()[0], {
direction: 'sendonly',
sendEncodings: [
{rid: 'f'},
{rid: 'h', scaleResolutionDownBy: 2.0},
{rid: 'q', scaleResolutionDownBy: 4.0}
]
});
} catch (err) {
console.error(err);
}
}
signaling.onmessage = async (event) => {
try {
const message = JSON.parse(event.data);
if (message.desc) {
await pc.setRemoteDescription(message.desc);
} else {
await pc.addIceCandidate(message.candidate);
}
} catch (err) {
console.error(err);
}
};
Peer-to-peer Data Example
This example shows how to create an
RTCDataChannel object and perform the offer/answer
exchange required to connect the channel to the other peer. The
RTCDataChannel is used in the context of a simple
chat application and listeners are attached to monitor when the channel
is ready, messages are received and when the channel is closed.
const signaling = new SignalingChannel(); // handles JSON.stringify/parse
const configuration = {iceServers: [{urls: 'stuns:stun.example.org'}]};
let pc;
let channel;
// call start(true) to initiate
function start(isInitiator) {
pc = new RTCPeerConnection(configuration);
// send any ice candidates to the other peer
pc.onicecandidate = (candidate) => {
signaling.send({candidate});
};
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
try {
await pc.setLocalDescription(await pc.createOffer());
// send the offer to the other peer
signaling.send({desc: pc.localDescription});
} catch (err) {
console.error(err);
}
};
if (isInitiator) {
// create data channel and setup chat
channel = pc.createDataChannel('chat');
setupChat();
} else {
// setup chat on incoming data channel
pc.ondatachannel = (event) => {
channel = event.channel;
setupChat();
};
}
}
signaling.onmessage = async ({desc, candidate}) => {
if (!pc) start(false);
try {
if (desc) {
// if we get an offer, we need to reply with an answer
if (desc.type == 'offer') {
await pc.setRemoteDescription(desc);
await pc.setLocalDescription(await pc.createAnswer());
signaling.send({desc: pc.localDescription});
} else {
await pc.setRemoteDescription(desc);
}
} else {
await pc.addIceCandidate(candidate);
}
} catch (err) {
console.error(err);
}
};
function setupChat() {
// e.g. enable send button
channel.onopen = () => enableChat(channel);
channel.onmessage = (event) => showChatMessage(event.data);
}
Call Flow Browser to Browser
This shows an example of one possible call flow between two browsers.
This does not show the procedure to get access to local media or every
callback that gets fired but instead tries to reduce it down to only show
the key events and messages.
Sending the DTMF signal "1234" with 500 ms duration per tone:
if (sender.dtmf.canInsertDTMF) {
const duration = 500;
sender.dtmf.insertDTMF('1234', duration);
} else {
console.log('DTMF function not available');
}
Send the DTMF signal "123" and abort after sending "2".
async function sendDTMF() {
if (sender.dtmf.canInsertDTMF) {
sender.dtmf.insertDTMF('123');
await new Promise((r) => sender.dtmf.ontonechange = (e) => e.tone == '2' && r());
// empty the buffer to not play any tone after "2"
sender.dtmf.insertDTMF('');
} else {
console.log('DTMF function not available');
}
}
Send the DTMF signal "1234", and light up the active key using
lightKey(key) while the tone is playing (assuming that
lightKey("") will darken all the keys):
const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
if (sender.dtmf.canInsertDTMF) {
const duration = 500;
sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '1234', duration);
sender.dtmf.ontonechange = async (event) => {
if (!event.tone) return;
lightKey(event.tone); // light up the key when playout starts
await wait(duration);
lightKey(''); // turn off the light after tone duration
};
} else {
console.log('DTMF function not available');
}
It is always safe to append to the tone buffer. This example appends
before any tone playout has started as well as during playout.
if (sender.dtmf.canInsertDTMF) {
sender.dtmf.insertDTMF('123');
// append more tones to the tone buffer before playout has begun
sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '456');
sender.dtmf.ontonechange = (event) => {
if (event.tone == '1') {
// append more tones when playout has begun
sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '789');
}
};
} else {
console.log('DTMF function not available');
}
Send a 1-second "1" tone followed by a 2-second "2" tone:
if (sender.dtmf.canInsertDTMF) {
sender.dtmf.ontonechange = (event) => {
if (event.tone == '1') {
sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '2', 2000);
}
};
sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '1', 1000);
} else {
console.log('DTMF function not available');
}
Error Handling
Some operations throw or fire RTCError. This is an extension
of DOMException that carries additional WebRTC-specific
information.
Invoke the DOMException constructor of
e with the message argument set to
message and the name argument set to
"RTCError".
This name does not have a mapping to a legacy
code so e's code attribute will return
0.
Set all RTCError attributes of e to
the value of the corresponding attribute in init if
it is present, otherwise set it to null.
Return e.
Attributes
errorDetail of type RTCErrorDetailType, readonly
The WebRTC-specific error code for the type of error that
occurred.
sdpLineNumber of type long, readonly, nullable
If errorDetail is "sdp-syntax-error"
this is the line number where the error was detected (the first
line has line number 1).
httpRequestStatusCode of type
long, readonly,
nullable
If errorDetail is "idp-load-failure"
this is the HTTP status code of the IdP URI response.
sctpCauseCode of type long, readonly, nullable
If errorDetail is "sctp-failure" this
is the SCTP cause code of the failed SCTP negotiation.
receivedAlert of type unsigned long, readonly,
nullable
If errorDetail is "dtls-failure" and
a fatal DTLS alert was received, this is the value of the DTLS
alert received.
sentAlert of type unsigned long, readonly,
nullable
If errorDetail is "dtls-failure" and
a fatal DTLS alert was sent, this is the value of the DTLS alert
sent.
RTCErrorInit Dictionary
dictionary RTCErrorInit {
required RTCErrorDetailType errorDetail;
long sdpLineNumber;
long httpRequestStatusCode;
long sctpCauseCode;
unsigned long receivedAlert;
unsigned long sentAlert;
};
The errorDetail, sdpLineNumber, httpRequestStatusCode, sctpCauseCode, receivedAlert and sentAlert members of RTCErrorInit have the same definitions as the attributes of the same name of RTCError.
The error detail types whose names are prefixed with "idp-" are
used by the [[WEBRTC-IDENTITY]] specification. They are described
here because a WebIDL enum must be described in one place only.
Enumeration description
data-channel-failure
The data channel has failed.
dtls-failure
The DTLS negotiation has failed or the connection
has been terminated with a fatal error. The
message contains information relating to
the nature of error. If a fatal DTLS alert was received,
the receivedAlert attribute is set to the
value of the DTLS alert received. If a fatal DTLS alert was
sent, the sentAlert attribute is set to
the value of the DTLS alert sent.
fingerprint-failure
The RTCDtlsTransport's
remote certificate did not match any of the fingerprints
provided in the SDP. If the remote peer cannot match
the local certificate against the provided fingerprints,
this error is not generated. Instead a "bad_certificate"
(42) DTLS alert might be received from the remote peer,
resulting in a "dtls-failure".
idp-bad-script-failure
The script loaded from the identity provider is not valid
JavaScript or did not implement the correct interfaces.
idp-execution-failure
The identity provider has thrown an exception or
returned a rejected promise.
idp-load-failure
Loading of the IdP URI has failed. The
httpRequestStatusCode attribute is
set to the HTTP status code of the response.
idp-need-login
The identity provider requires the user to login. The
idpLoginUrl attribute is set to the URL that
can be used to login.
idp-timeout
The IdP timer has expired.
idp-tls-failure
The TLS certificate used for the IdP HTTPS connection
is not trusted.
idp-token-expired
The IdP token has expired.
idp-token-invalid
The IdP token is invalid.
sctp-failure
The SCTP negotiation has failed or the connection
has been terminated with a fatal error. The
sctpCauseCode attribute is set to the
SCTP cause code.
sdp-syntax-error
The SDP syntax is not valid. The sdpLineNumber
attribute is set to the line number in the SDP where the syntax
error was detected.
hardware-encoder-not-available
The hardware encoder resources required for the requested
operation are not available.
hardware-encoder-error
The hardware encoder does not support the provided
parameters.
RTCErrorEvent Interface
The RTCErrorEvent interface is defined for cases when an
RTCError is raised as an event:
The [[RTCWEB-IP-HANDLING]] mode for the RTCPeerConnection has been upgraded. The application needs to do an ICE restart if it wants to upgrade its connection to be potentially more direct.
The RTCDTMFSender object has either just
begun playout of a tone (returned as the tone attribute) or just ended
the playout of tones in the
toneBuffer
(returned as an empty value in the
tone
attribute).
This section is non-normative; it specifies no new behaviour, but
instead summarizes information already present in other parts of the
specification. The overall security considerations of the general set of
APIs and protocols used in WebRTC are described in
[[RTCWEB-SECURITY-ARCH]].
Impact on same origin policy
This document extends the Web platform with the ability to set up real
time, direct communication between browsers and other devices, including
other browsers.
This means that data and media can be shared between applications
running in different browsers, or between an application running in the
same browser and something that is not a browser, something that is an
extension to the usual barriers in the Web model against sending data
between entities with different origins.
The WebRTC specification provides no user prompts or chrome indicators
for communication; it assumes that once the Web page has been allowed to
access media, it is free to share that media with other entities as it
chooses. Peer-to-peer exchanges of data view WebRTC datachannels can thus
occur without any user explicit consent or involvement, similarly as a
server-mediated exchange (e.g. via Web Sockets) could occur without user
involvement.
The peerIdentity mechanism loads and executes
JavaScript code from a third-party server acting as an identity provider.
That code is executed in a separate JavaScript realm and does not affect
the protections afforded by the same origin policy.
Revealing IP addresses
Even without WebRTC, the Web server providing a Web application will
know the public IP address to which the application is delivered. Setting
up communications exposes additional information about the
browser’s network context to the web application, and may include
the set of (possibly private) IP addresses available to the browser for
WebRTC use. Some of this information has to be passed to the
corresponding party to enable the establishment of a communication
session.
Revealing IP addresses can leak location and means of connection; this
can be sensitive. Depending on the network environment, it can also
increase the fingerprinting surface and create persistent cross-origin
state that cannot easily be cleared by the user.
A connection will always reveal the IP addresses proposed for
communication to the corresponding party. The application can limit this
exposure by choosing not to use certain addresses using the settings
exposed by the RTCIceTransportPolicy dictionary, and by using
relays (for instance TURN servers) rather than direct connections between
participants. One will normally assume that the IP address of TURN
servers is not sensitive information. These choices can for instance be
made by the application based on whether the user has indicated consent
to start a media connection with the other party.
Mitigating the exposure of IP addresses to the application itself
requires limiting the IP addresses that can be used, which will impact
the ability to communicate on the most direct path between endpoints.
Browsers are encouraged to provide appropriate controls for deciding
which IP addresses are made available to applications, based on the
security posture desired by the user. The choice of which addresses to
expose is controlled by local policy (see [[RTCWEB-IP-HANDLING]] for
details).
Impact on local network
Since the browser is an active platform executing in a trusted network
environment (inside the firewall), it is important to limit the damage
that the browser can do to other elements on the local network, and it is
important to protect data from interception, manipulation and
modification by untrusted participants.
Mitigations include:
A user agent will always request permission from the correspondent
user agent to communicate using ICE. This ensures that the user agent
can only send to partners who you have shared credentials with.
A user agent will always request ongoing permission to continue
sending using ICE continued consent. This enables a receiver to
withdraw consent to receive.
A user agent will always encrypt data, with strong per-session
keying (DTLS-SRTP).
A user agent will always use congestion control. This ensures that
WebRTC cannot be used to flood the network.
These measures are specified in the relevant IETF documents.
Confidentiality of Communications
The fact that communication is taking place cannot be hidden from
adversaries that can observe the network, so this has to be regarded as
public information.
A mechanism, peerIdentity, is provided that gives
Javascript the option of requesting media that the same javascript cannot
access, but can only be sent to certain other entities.
Persistent information exposed by WebRTC
As described above, the list of IP addresses exposed by the WebRTC API
can be used as a persistent cross-origin state.
Beyond IP addresses, the WebRTC API exposes information about the
underlying media system via the RTCRtpSender.getCapabilities
and RTCRtpReceiver.getCapabilities methods, including
detailed and ordered information about the codecs that the system is able
to produce and consume. A subset of that information is likely to be
represented in the SDP session descriptions generated, exposed and
transmitted during session
negotiation. That information is in most cases persistent across time
and origins, and increases the fingerprint surface of a given device.
If set, the configured default ICE servers exposed by getDefaultIceServers on
RTCPeerConnection instances also provides persistent across
time and origins information which increases the fingerprinting surface
of a given browser.
When establishing DTLS connections, the WebRTC API can generate
certificates that can be persisted by the application (e.g. in
IndexedDB). These certificates are not shared across origins, and get
cleared when persistent storage is cleared for the origin.
Change Log
This section will be removed before publication.
Changes since October 02, 2017
[#1616] Add Duration, InterToneGap, ToneBuffer and CanInsertDTMF
internal slots of RTCDTMFSender
[#1614] createDataChannel: Update negotiation needed state on the
main thread
[#1553] Add API to expose what algorithms the browser supports
[#1430] Have createOffer call addTransceiver() on offerToReceive
[#1615] setParameters: Use more specific hardware encoder errors
[#1621] RTCPeerConnection.close should close Data Channels and
SctpTransports
[#1538] IdP protocol can only contain characters legal in a URI
[#1620] Add RTCSctpTransportState
[#1634] Add onstatechange event to SctpTransport Event table
[#1631] Explain the scope of DTLS/ICE transport objects in more
detail
[#1623] Describe how transport objects are assigned to
senders/receivers
[#1636] Simple text for scaling issue - no letterbox allowed
[#1641] Note about video dimension adaptation discussion added
Changes since August 22, 2017
[#1559] Reference rtcweb-data-channel for RTCPriorityType enum
[#1557] Make fields in RTCStats dictionary required
[#1556] Update mandatory to implement stats fields to sync with
webrtc-stats
[#1555] Fix reference to validating assertion result in requesting
assertions
[#1551] Clarify the meaning of session description sdp need not
match
[#1550] Validate binaryType value when setting it in
RTCDataChannel
[#1549] Allow createAnswer to be called only in valid signaling
state
[#1547] Wait for certificate to be generated before identity
assertion process
[#1544] Align stats example with WebRTC stast spec
(s/outboundrtp/outbound-rtp)
[#1539] Remove unnecessary type checking for selectorArg in getStats
[#1536] Define vhen dtmf attribute is set
[#1525] Update paragraph that introduces
senders/receivers/transceivers
[#1541] Specify getCapabilities behavior with an unsupported value of
kind
[#1487] Check for invalid rollback
[#1522] Formalize how createOffer interacts with identity
providers
[#1558] Throw if a DataChannel, to be negotiated by the script, lacks
id
[#1552] Harmonize and update our references to other
specifications
[#1443] SLD/SRD: Check if transceiver is stopped before setting
currentDirection
[#1548] Add note that IdP must treat contents as opaque
[#1561] Clarify which session description to check for if negotiation
is needed
[#1566] Add a section summarizing different ICE candidate events
[#1580] Add ICE candidates only to the applicable descriptions.
[#1572] Annotate all interfaces with Exposed extended attribute
[#1571] Remove unreferenced [HTML] ref using respec post
processing
[#1596] Add Promise terms to Terminology section
[#1595] Add note that null candidate is for legacy compatibility
[#1592] Select sent codec via "codecPayloadType" field rather than
reordering
[#1591] Add some text about how the AssociatedMediaStreams internal
slot is used
[#1590] Use internal slots for transceiver's sender/receiver and
receiver's track
[#1585] Use internal slot for RTCRtpSender's track
[#1604] Add 'resolved' (and variants) to Promise terminology
[#1582] RTCIceTransport: Use internal slots
[#1577] scaleResolutionDownBy: Specify how the User Agent should
behave when scaling video
[#1607] Update DTMF examples to match specified behavior
[#1581] RTCDtlsTransport: Use internal slots
[#1560] setParameters: Do argument checks in sync section and specify
parellel steps
Changes since June 05, 2017
[#1160] Remove getAlgorithm()
[#1298] Specify DTMF intertone gap maximum
[#1327] Remove fingerprint matching.
[#1329] Update maxBitrate definition
[#1337] Fix DTMF Examples (Section 11.7)
[#1348] Add a note on the absence of privacy impact of configured
default ICE
[#1349] Show RFC2119 keywords in small-caps (was broken by respec
update)
[#1350] Remove meaningless case-sensitive qualification of RID
characters
[#1359] createOffer/Answer: Remove sentence with vague 'reasonably
soon'
[#1356] createDataChannel: Use TypeError for bad reliability
arguments
[#1098] Attempt to update RTCRtpContributingSource objects at playout
time
[#1114] Mark Identity as a "feature at risk"
[#1119] Making legacy methods optional to implement
[#1122] RTCCertificate.getAlgorithm() to return a compatible
AlgorithmIdentifier
[#1130] Clarify that configuration.certificates remains undefined in
the RTCPeerConnection constructor
[#1131] RTCPeerConnection.createDataChannel: Drop
[TreatNullAs=EmptyString] for USVString
[#1129 Code examples: dont fiddle with srcObject if already set
[#1136] Fire the "track" event from a queued task
[#1137] Adding more detail about RTCDataChannel.id's default value
(null)
[#1139] Call RTCDtlsFingerprint a dictionary, not an object
[#1140] Add a link to web-platform-tests to the top of the spec
[#1133] Split getContributingSources into two methods, for CSRCs and
SSRCs
[#1145] FrozenArray, sequence and SameObject (Use sequence and
getters instead of FrozenArray for getFingerPrints and
getDefaultIceServers) (Use SameObject for RTCTrackEvent.streams)
[#1147] Add reference to ICE restart
Changes since December 19, 2016
[#985] Removed legacy getStats() method
[#982] Specify unit for maxPacketLifeTime
[#987] Make the ufrag optional in RTCIceCandidateInit, for backwards
compat.
[#993] Use lowercase values for RTCIceComponent
[#994] Changing "non-null" to "missing" to match IDL terminology.
[#996] Describe when an RTCSctpTransport is created/set to null.
[#999] Make transceiver.stop() send a BYE
[#1002] Dispatch event when a transceiver is stopped via remote
action
[#1003] Change setLocalDescription to require unchanged offer/answer
string
[#1004] Specify that currentRemoteDescription.sdp need not match
remoteDescription.sdp
[#1006] Make errorCode required in
RTCPeerConnectionIceErrorEventInit
[#1005] Add offerToReceive* as legacy extensions
[#1001] Specify the effect of a BYE on RtpReceiver.track
[#1015] Fix inconsistencies in description of
RTCDTMFToneChangeEvent.tone
[#1016] Ensure that "track" event is only fired for "send" direction
m-sections.
[#1018] Mark negotitate in RTCRtcpMuxPolicy at risk
[#1029] Add IdP token expired error
[#1028] Add IdP invalid token error
[#1027] Add string for extra info about idpErrors
[#1019] Clarify that it is possible to send the same track in several
copies
[#1023] Specify how media is centered, cropped, and scaled
[#1025] Mention that codecs can be reordered or removed but not
modified.
[#1038] Make RTCDataChannel.id nullable and describe when it's
set.
[#1036] Specify how transceivers get their mids in
setLocal/RemoteDescription
[#1037] Specify when random mid generation happens
[#1039] Clarify which timestamp RTCStats.timestamp represents
[#1041] Label 'Warm-up example' as 'advanced p2p example'
[#1031] Don't fire events on a closed peer connection
[#1045] Clarifying exactly what "sdpFmtpLine" represents
[#1047] Adding "[EnforceRange]" to RTCDataChannelInit.id
[#1054] Throw InvalidModificationError if changing pool size after
setLocalDescription
[#1055] Changing iceCandidatePoolSize to an octet and adding
EnforceRange WebIDL extended attribute
[#1057] Add clockrate, channels, sdpFmtpLine to codec capability
[#1058] Define 'generation of ICE candidates' and add reference
[#1059] Specify how remote tracks get muted
[#1060] Specify when to end a remote track
[#1061] Remove connecting event from Event summary
[#1066] Specify relation between RtpSender and track
[#1056] Switch to new, consistent terminology when talking about
exceptions
[#1030] Add stats selection algorithm based on sender or receiver of
selector
Changes since November 23, 2016
[#899] Make stats MTI, remove overlap with stats spec
[#920] Remove ICE Agent text from RTCPeerConnection due to
the new RTCICETransport objects.
[#937] Define what happens when transceiver.stop() is called.
[#938] Define what happens when setDirection() is called.
[#939] Remove "stopped" from removeTrack() and immediately
stop sender.
[#940] Remove "stopped" from close, insertDTMF, and
replaceTrack.
[#944] Clarify that sender does not send if sender.track is
set to null.
[#949] Give legacy callbacks RTCSessionDescriptionInit so
they can modify SDP.
[#956] Add API for setting QoS priority of data channels.
[#960] Allow replaceTrack(null)
[#963] Split transceiver direction into "direction" and
"currentDirection"
[#966] setParameters rejects with InvalidStateError if
transceiver.stopped is true.
[#968] Add ufrag to IceCandidate and use IceCandidate
for end-of-candidates.
[#970] Clarify that setParameters cannot add or remove
simulcast encodings.
[#972, #973] Add generic Error Object that can hold detailed
error information.
[#936, #953, #967] Editorial: remove old in-spec issue text,
update JSEP references, update hold examples, fix section titles
Changes since September 13, 2016
[#738] Add ability to get fingerprints of an
RTCCertificate
[#783] Clarify supported DTMF characters
[#785] Reject invalid DTMF characters when inserted
[#786] If track is ended or muted, send silence for audio or
black frame for video
[#790] Add checks that verify that a candidate matches a
remote media decription
[#791] Add text that fires the 'connectionstatechange'
event
[#793] Define DTMF tone attribute and make it required
[#796] Language cleanup around use of
MediaTrackSettings
[#797] Clarify when negotiation-needed flag is cleared
[#804] Clarify that JSEP is normative in some cases; also
numerous small editorial fixes
[#805] Reduce insertDTMF max duration from 8000 ms to 6000
ms
[#807] Clarify that empty string in DTMFToneChangeEvent
indicates that the previous tones (plural) have completed.
[#809] Clarify that InvalidStateError is thrown if
insertDTMF is called on a stopped sender.
[#815] Change IceConnectionState to match PeerConnection
state in certain edge cases.
All callback-based methods have been moved to a legacy section, and
replaced by same-named overloads using Promises instead.
[PR #194] Added first version of Security Considerations (more work
needed)
Updated identity provider structure.
Changes since June 4, 2014
Bug 25724: Allow garbage collection of closed PeerConnections
Bug 27214: Add onicegatheringstatechange event
Bug 26644: Fixing end of candidates event
Changes since April 10, 2014
Bug 25774: Mixed isolation
Changes since April 10, 2014
Bug 25855: Clarification about conformance requirements phrased as
algorithms
Bug 25892: SignalingStateChange event should be fired only if there
is a change in signaling state.
Bug 25152: createObjectURL used in examples is no longer supported by
Media Capture and Streams.
Bug 25976: DTMFSender.insertDTMF steps should validate the values of
duration and interToneGap.
Bug 25189: Mandatory errorCallback is missing in examples for
getStats.
Bug 25840: Creating DataChannel with same label.
Updated comment above example ice state transitions (discussed in Bug
25257).
Updated insertDTMF() algorithm to ignore unrecognized characters (as
discussed in bug 25977).
Made formatting of references to ice connection state
consistent.
Made insertDTMF() throw on unrecognized characters (used to
ignore).
Removed requestIdentity from RTCConfiguration and
RTCOfferAnswerOptions. Removed RTCOfferAnswerOptions as a result.
Adding isolated property and associated event to
MediaStreamTrack.
Changes since March 21, 2014
Changes to identity-related text:
Removed noaccess constraint
Add the ability to peerIdentity constrain RTCPeerConnection,
which limits communication to a single peer
Change the way that the browser communicates with IdP to a
message channel
(http://www.w3.org/TR/webmessaging/#message-channels)
Improved error feedback from IdP interactions (added new events
with more detailed context)
Changed the way that an IdP is able to request user login
(LOGINNEEDED message)
Bug 25155: maxRetransmitTime is not the name of the SCTP concept it
points to.
Changes since January 27, 2014
Refined identity assertion generation and validation.
Default DTMF gap changed from 50 to 70 ms.
Bug 24875: Examples in the WebRTC spec are not updated As per the
modified API.
Changes since August 30, 2013
Make RTCPeerConnection close method be idempotent.
Clarified ICE server configuration could contain URI types other than
STUN and TURN.
Changed the DTMF timing values.
Allow offerToReceiveAudio/video indicate number of streams to
offer.
ACTION-98: Added text about clamping of maxRetransmitTime and
maxRetransmits.
ACTION-88: Removed nullable types from dictionaries (added attribute
default values for attributes that would be left uninitialized without
the init dictionary present.
InvalidMediaStreamTrackError changed to InvalidParameter.
Fire NetworkError when the data transport is closed with an
error.
Add an exception for data channel with trying to use existing
code.
Change maxRetransmits to be an unsigned type.
Clarify state changes when ICE restarts.
Added InvalidStateError exception for operations on an
RTCPeerConnection that is closed.
Major changes to Identity Proxy section.
(ACTION: 95) Moved IceTransports (constraint) to RTCConfiguration
dictionary.
(ACTION: 95) Introduced RTCOfferAnswerOptions and RTCOfferOptions
dictionaries.
Added validation of the RTCConfiguration dictionary argument(s).
Added getConfiguration() on RTCPeerConnection.
Changes since June 3, 2013
Removed synchronous section left-overs.
RTCIceServer now accepts multiple URLs.
Redefined the meaning of negotiated for DataChannel.
Made iceServers a sequence (instead of an Array).
Updated error reporting (to use DOMError and camel cased names).
Added success and failure callbacks to addIceCandidate().
Made local/remoteDescription attributes nullable.
Added username member to RTCIceServer dictionary.
Changes since March 22, 2013
Added IceRestart constraint.
Big updates on DataChannel API to use new channel setup
procedures.
Changes since Feb 22, 2013
Example review: Updated DTMF and Stats examples. Added text about
when to fire "negotiationneeded" event to align with examples.
Updated RTCPeerConnection state machine. Added a shared processing
model for setLocalDescription()/setRemoteDescription().
Updated simple callflow to match the current API.
Changes since Jan 16, 2013
Initial import of Statistics API to version 2.
Integration of Statistics API version 2.5 started.
Updated Statistics API to match Boston/list discussions.
Extracted API extensions introduced by features, such as the P2P Data
API, from the RTCPeerConnection API.
Updated DTMF algorithm to dispatch an event when insertDTMF() is
called with an empty string to cancel future tones.
Updated DTMF algorithm to not cancel and reschedule if a playout task
is running (only update toneBuffer and other values).
Changes since Dec 12, 2012
Changed AudioMediaStreamTrack to RTCDTMFSender and gave it its own
section. Updated text to reflect most recent agreements. Also added
examples section.
Replaced the localStreams and remoteStreams attributes with functions
returning sequences of MediaStream objects.
Added spec text for attributes and methods adopted from the WebSocket
interface.
Changed the state ENUMs and transition diagrams.
Aligned the data channel processing model a bit more with WebSockets
(mainly closing the underlying transport).
Changes since Nov 13, 2012
Made some clarifications as to how operation queuing works, and fixed
a few errors with the error handling description.
Introduced new representation of tracks in a stream (removed
MediaStreamTrackList). Added algorithm for creating a track to represent
an incoming network media component.
Renamed MediaStream.label to MediaStream.id (the definition needs
some more work).
Changes since Nov 03, 2012
Added text describing the queuing mechanism for
RTCPeerConnection.
Updated simple P2P example to include all mandatory (error)
callbacks.
Updated P2P data example to include all mandatory (error) callbacks.
Also added some missing RTC prefixes.
Changes since Oct 19, 2012
Clarified how createOffer() and createAnswer() use their
callbacks.
Made all failure callbacks mandatory.
Added error object types, general error handling principles, and
rules for when errors should be thrown.
Changes since Sept 23, 2012
Restructured the document layout and created separate sections for
features like Peer-to-peer Data API, Statistics and Identity.
Changes since Aug 16, 2012
Replaced stringifier with serializer on RTCSessionDescription and
RTCIceCandidate (used when JSON.stringify() is called).
Removed offer and createProvisionalAnswer arguments from the
createAnswer() method.
Removed restart argument from the updateIce() method.
Made RTCDataChannel an EventTarget
Updated simple RTCPeerConnection example to match spec changes.
Added section about RTCDataChannel garbage collection.
Added stuff for identity proxy.
Added stuff for stats.
Added stuff peer and ice state reporting.
Minor changes to sequence diagrams.
Added a more complete RTCDataChannel example
Various fixes from Dan's Idp API review.
Patched the Stats API.
Changes since Aug 13, 2012
Made the RTCSessionDescription and RTCIceCandidate constructors take
dictionaries instead of a strings. Also added detailed stringifier
algorithm.
Went through the list of issues (issue numbers are only valid with
HEAD at fcda53c460). Closed (fixed/wontfix): 1, 8, 10, 13, 14, 16, 18,
19, 22, 23, 24. Converted to notes: 4, 12. Updated: 9.
Use an enum for DataChannelState and fix IDLs where using an optional
argument also requires all previous optional arguments to have a default
value.
Changes since Jul 20, 2012
Added RTC Prefix to names (including the notes below).
Moved to new definition of configuration and ice servers object.
Added correlating lines to candidate structure.
Converted setLocalDescription and setRemoteDescription to be
asynchronous.
Added call flows.
Changes since Jul 13, 2012
Removed peer attribute from RTCPeerConnectionIceEvent (duplicates
functionality of Event.target attribute).
Removed RTCIceCandidateCallback (no longer used).
Removed RTCPeerConnectionEvent (we use a simple event instead).
Removed RTCSdpType argument from setLocalDescription() and
setRemoteDescription(). Updated simple example to match.
Changes since May 28, 2012
Changed names to use RTC Prefix.
Changed the data structure used to pass in STUN and TURN servers in
configuration.
Updated simple RTCPeerConnection example (RTCPeerConnection
constructor arguments; use icecandidate event).
Initial import of new Data API.
Removed some left-overs from the old Data Stream API.
Renamed "underlying data channel" to "underlying data transport".
Fixed closing procedures. Fixed some typos.
Changes since April 27, 2012
Major rewrite of RTCPeerConnection section to line up with IETF JSEP
draft.
Added simple RTCPeerConnection example. Initial update of
RTCSessionDescription and RTCIceCandidate to support serialization and
construction.
Changes since 21 April 2012
Moved MediaStream and related definitions to getUserMedia.
Removed section "Obtaining local multimedia content".
Updated getUserMedia() calls in examples (changes in Media Capture TF
spec).
Introduced MediaStreamTrackList interface with support for adding and
removing tracks.
Updated the algorithm that is run when RTCPeerConnection receives a
stream (create new stream when negotiated instead of when data
arrives).
Changes since 12 January 2012
Clarified the relation of Stream, Track, and Channel.
Changes since 17 October 2011
Tweak the introduction text and add a reference to the IETF RTCWEB
group.
Changed the first argument to getUserMedia to be an object.
Added a MediaStreamHints object as a second argument to
RTCPeerConnection.addStream.
Added AudioMediaStreamTrack class and DTMF interface.
Changes since 23 August 2011
Separated the SDP and ICE Agent into separate agents and added
explicit state attributes for each.
Removed the send method from PeerConenction and associated callback
function.
Modified MediaStream() constructor to take a list of MediaStreamTrack
objects instead of a MediaStream. Removed text about MediaStream parent
and child relationship.
Added abstract.
Moved a few paragraphs from the MediaStreamTrack.label section to the
MediaStream.label section (where they belong).
Split MediaStream.tracks into MediaStream.audioTracks and
MediaStream.videoTracks.
Removed a sentence that implied that track access is limited to
LocalMediaStream.
Updated a few getUserMedia()-examples to use MediaStreamOptions.
Replaced calls to URL.getObjectURL() with URL.createObjectURL() in
example code.
Fixed some broken getUserMedia() links.
Introduced state handling on MediaStreamTrack (removed state handling
from MediaStream).
Reintroduced onended on MediaStream to simplify checking if all
tracks are ended.
Aligned the MediaStreamTrack ended event dispatching behavior with
that of MediaStream.
Updated the LocalMediaStream.stop() algorithm to implicitly use the
end track algorithm.
Replaced an occurrence the term finished track with ended track (to
align with rest of spec).
Moved (and extended) the explanation about track references and media
sources from LocalMediaStream to MediaStreamTrack.
Acknowledgements
The editors wish to thank the Working Group chairs and Team Contact,
Harald Alvestrand, Stefan Håkansson, Erik Lagerway and Dominique
Hazaël-Massieux, for their support. Substantial text in this
specification was provided by many people including Martin Thomson, Harald
Alvestrand, Justin Uberti, Eric Rescorla, Peter Thatcher, Jan-Ivar Bruaroey
and Peter Saint-Andre. Dan Burnett would like to acknowledge the
significant support received from Voxeo and Aspect during the development
of this specification.
The RTCRtpSender and RTCRtpReceiver objects were initially described in
the W3C ORTC CG, and have
been adapted for use in this specification.
