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.
Status of This Document
This section describes the status of this
document at the time of its publication. Other documents may supersede
this document. A list of current W3C publications and the latest revision
of this technical report can be found in the
W3C technical reports index at
https://www.w3.org/TR/.
The API is based on preliminary work done in the WHATWG.
GitHub Issues are preferred for
discussion of this specification.
Alternatively, you can send comments to our mailing list.
Please send them to
public-webrtc@w3.org
(archives).
Publication as a Proposed Recommendation does not imply endorsement
by the W3C Membership.
This is a draft document and may be updated, replaced
or obsoleted by other documents at any time. It is inappropriate to cite this
document as other than work in progress.
Future updates to this specification may incorporate
new features.
The W3C Membership and other interested parties are
invited to review the document and send comments through
15 January 2021. Advisory Committee Representatives should consult
their
WBS questionnaires. Note that substantive technical comments were expected during the
Candidate Recommendation review period that ended 24 September 2020.
This document was produced by a group
operating under the
W3C Patent
Policy.
W3C maintains a
public list of any patent disclosures
made in connection with the deliverables of
the group; that page also includes
instructions for disclosing a patent. An individual who has actual
knowledge of a patent which the individual believes contains
Essential Claim(s)
must disclose the information in accordance with
section 6 of the W3C Patent Policy.
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 WebRTC Working Group. An overview of the system can be
found in [RTCWEB-OVERVIEW] and [RTCWEB-SECURITY].
2. Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, and SHOULD in this document
are to be interpreted as described in
BCP 14
[RFC2119] [RFC8174]
when, and only when, they appear in all capitals, as shown here.
This specification defines conformance criteria that apply to a single
product: the user agent that implements the interfaces that
it contains.
Conformance requirements phrased as algorithms or specific steps may be
implemented in any manner, so long as the end result is equivalent. (In
particular, the algorithms defined in this specification are intended
to be easy to follow, and not intended to be performant.)
Implementations that use ECMAScript to implement the APIs defined in
this specification MUST implement them in a manner consistent with the
ECMAScript Bindings defined in the Web IDL specification [WEBIDL],
as this specification uses that specification and terminology.
3.
Terminology
The EventHandler interface, representing a callback used for event
handlers, is defined in [HTML].
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.
4.
Peer-to-peer connections
4.1
Introduction
An RTCPeerConnection instance allows an application to establish
peer-to-peer communications with another RTCPeerConnection
instance in another browser, or to another endpoint implementing the
required protocols. Communications are coordinated by the exchange of
control messages (called a signaling protocol) over a signaling
channel which is provided by unspecified means, but generally by a
script in the page via the server, e.g. using Web
Sockets or XMLHttpRequest [xhr].
4.2
Configuration
4.2.1
RTCConfiguration Dictionary
The RTCConfiguration defines a set of parameters to configure
how the peer-to-peer communication established via
RTCPeerConnection is established or re-established.
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.
Note
Existing implementations only utilize the first certificate
provided; the others are ignored.
If this value is absent, then a default set of certificates
is generated for each RTCPeerConnection instance.
This option allows applications to establish key
continuity. An RTCCertificate can be persisted in
[INDEXEDDB] and reused. Persistence and reuse also
avoids the cost of key generation.
The value for this configuration option cannot change after
its value is initially selected.
iceCandidatePoolSize of type
octet, defaulting to
0
Size of the prefetched ICE pool as defined in
[JSEP].
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,
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.
The ICE Agent uses only media relay candidates such
as candidates passing through a TURN server.
Note
This can be used to prevent the remote endpoint from
learning the user's IP addresses, which may be desired in
certain use cases. For example, in a "call"-based
application, the application may want to prevent an
unknown caller from learning the callee's IP addresses
until the callee has consented in some way.
all
The ICE Agent can use any type of candidate when
this value is specified.
Note
The implementation can still use its own candidate
filtering policy in order to limit the IP addresses
exposed to the application, as noted in the description
of RTCIceCandidate.address.
4.2.5
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.
4.2.6
RTCRtcpMuxPolicy Enum
As described in [JSEP], the
RTCRtcpMuxPolicy affects what ICE candidates are gathered to
support non-multiplexed RTCP. The only value defined in this spec
is "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.
4.2.7
Offer/Answer Options
These dictionaries describe the options that can be used to control
the offer/answer creation process.
When the value of this dictionary member is
true, or the relevant RTCPeerConnection
object's [[LocalIceCredentialsToReplace]] slot is
not empty, then the generated description will have ICE
credentials that are different from the current credentials
(as visible in the
currentLocalDescription attribute's
SDP). Applying the generated description will restart ICE,
as described in section 9.1.1.1 of [ICE].
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 set of transports considered is the set of transports
presently referenced by the PeerConnection's
set of transceivers.
Note that if an RTCIceTransport is discarded as a result of
signaling (e.g. RTCP mux or bundling), or created as a result of
signaling (e.g. adding a new media description), the state
may advance directly from one state to another.
4.4
RTCPeerConnection Interface
The [JSEP] specification, as a whole, describes the details of how
the RTCPeerConnection operates. References to specific
subsections of [JSEP] are provided as appropriate.
configuration.iceServers contains
information used to find and access the servers used by ICE. The
application can supply multiple servers of each type, and any TURN
server MAY also be used as a STUN server for the purposes of
gathering server reflexive candidates.
An RTCPeerConnection object has a signaling state, a
connection state, an ICE gathering state, and
an ICE connection state. These are initialized when the
object is created.
When the RTCPeerConnection.constructor() is
invoked, the user agent MUST run the following steps:
If any of the steps enumerated below fails for a reason not
specified here, throw an UnknownError
with the message attribute set to an
appropriate description.
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.
Let connection have a
[[LocalIceCredentialsToReplace]] internal slot,
initialized to an empty set.
Return connection.
4.4.1.2
Chain an asynchronous operation
An RTCPeerConnection object has an operations
chain, [[Operations]], which ensures that only one
asynchronous operation in the chain executes concurrently. If
subsequent calls are made while the returned promise of a
previous call is still not settled, they are added to the
chain and executed when all the previous calls have finished
executing and their promises have settled.
An RTCPeerConnection object has an aggregated connection
state. Whenever the state of an RTCDtlsTransport changes
or when the [[IsClosed]] slot turns true,
the user agent MUST update the connection state by queueing a
task that runs the following steps:
The null candidate event is fired to ensure legacy
compatibility. New code should monitor the gathering state of
RTCIceTransport and/or RTCPeerConnection.
Let jsepSetOfTransceivers be a shallow copy of
connection's set of transceivers.
In parallel, start the process to apply
description as described in [JSEP],
with these additional restrictions:
Use jsepSetOfTransceivers as the source of
truth with regard to what "RtpTransceivers" exist, and
their [[JsepMid]] internal slot as their "mid
property".
If remote is true, validate
back-to-back offers as if answers were applied in
between, by running the check for subsequent offers as if
it were in stable state.
If applying description leads to modifying a
transceiver transceiver, and
transceiver.[[Sender]].[[SendEncodings]]
is non-empty, and not equal to the encodings that would
result from processing description, the
process of applying description fails. This
specification does not allow remotely initiated RID
renegotiation.
If the process to apply description fails for
any reason, then the user agent MUST queue a task that
runs the following steps:
If connection.[[IsClosed]] is
true, then abort these steps.
If 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 applied successfully, the
user agent MUST queue a task that runs the following
steps:
If connection.[[IsClosed]] is
true, then abort these steps.
If remote is true and
description is of type
"offer", then if any
addTrack() methods succeeded
during the process to apply description,
abort these steps and start the process over as if
they had succeeded prior, to include the extra
transceiver(s) in the process.
If 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.[[SctpTransport]] to
null.
Let trackEventInits,
muteTracks, addList,
removeList and errorList be
empty lists.
If description is of type
"answer" or "pranswer",
then run the following steps:
If description negotiates the DTLS
role of the SCTP transport, then for each
RTCDataChannel, channel, with a
nullid, run the
following step:
Give channel a new ID generated
according to [RTCWEB-DATA-PROTOCOL]. If no
available ID could be generated, set
channel.[[ReadyState]] to
"closed", and add
channnel to errorList.
If description is not of type
"rollback", then run the following
steps:
If remote is false, then
run the following steps for each media
description in description:
Set
transceiver.[[Receiver]].[[ReceiveCodecs]]
to the codecs that description
negotiates for receiving and which the user
agent is currently prepared to receive.
Note
If the direction is
"sendonly" or
"inactive",
the receiver is not prepared to receive
anything, and the list will be empty.
If description is of type
"answer" or
"pranswer", then run the
following steps:
Otherwise, (if remote is
true) run the following steps for
each media description in
description:
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.
Let supportedEncodings be the
maximum number of encodings that the
implementation can support. If the length of
sendEncodings is greater than
supportedEncodings, truncate
sendEncodings so that its length is
supportedEncodings.
If sendEncodings is non-empty, set
each encoding's
scaleResolutionDownBy
to 2^(length of sendEncodings -
encoding index - 1).
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.
If direction is
"sendrecv" or
"recvonly",
let msids be a list of the MSIDs
that the media description indicates
transceiver.[[Receiver]].[[ReceiverTrack]]
is to be associated with. Otherwise, let
msids be an empty list.
Process remote tracks with
transceiver, direction,
msids, addList,
removeList, and
trackEventInits.
Set
transceiver.[[Receiver]].[[ReceiveCodecs]]
to the codecs that description
negotiates for receiving and which the user
agent is currently prepared to receive.
If description is of type
"answer" or
"pranswer", then run the
following steps:
Set
transceiver.[[Sender]].[[SendCodecs]]
to the codecs that description
negotiates for sending and which the user
agent is currently capable of sending.
For each transceiver in the
connection's set of transceivers
run the following steps:
If transceiver was not associated with a media description
prior to pendingDescription being set,
disassociate it and set both
transceiver.[[JsepMid]]
and transceiver.[[Mid]] to
null.
If transceiver was created when
pendingDescription was set, and a
track has never been attached to it via
addTrack(), then stop the RTCRtpTransceivertransceiver, and remove it from
connection's set of
transceivers.
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:
Parse the url using the generic URI syntax
defined in [RFC3986] and obtain the scheme
name. If the parsing based on the syntax
defined in [RFC3986] fails, throw
a SyntaxError. If the scheme name is
not implemented by the browser throw
a NotSupportedError. If scheme name is
turn or turns, and parsing the url
using the syntax defined in [RFC7065] fails, throw a SyntaxError. If scheme
name is stun or
stuns, and parsing the
url using the syntax defined in
[RFC7064] fails, throw a
SyntaxError.
Set the ICE Agent's ICE
servers list to validatedServers.
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], except the user
agent MUST treat a stopping
transceiver as stopped for the
purposes of JSEP in this case.
As an offer, the generated SDP will contain the full set of
codec/RTP/RTCP capabilities supported or preferred by the
session (as opposed to an answer, which will include only a
specific negotiated subset to use). In the event
createOffer is called after the session is established,
createOffer will generate an offer that is compatible
with the current session, incorporating any changes that
have been made to the session since the last complete
offer-answer exchange, such as addition or removal of
tracks. If no changes have been made, the offer will
include the capabilities of the current local description
as well as any additional capabilities that could be
negotiated in an updated offer.
The generated SDP will also contain the ICE agent's
usernameFragment,
password and ICE options (as defined
in [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.
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.
Given the information that was obtained from previous
inspection, the current state of connection
and its RTCRtpTransceivers, 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 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.
Note
[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.
An answer can be marked as provisional, as described in
[JSEP], by setting
the type to
"pranswer".
When the method is called, the user agent MUST run the
following steps:
Let connection be the RTCPeerConnection
object on which the method was invoked.
Given the information that was obtained from previous
inspection and the current state of
connection and its RTCRtpTransceivers,
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
RTCRtpTransceiver.[[PreferredCodecs]]
with the following filtering applied (or said not
to be set if [[PreferredCodecs]] is empty):
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 RTCPeerConnectionMUST 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.
If sdp is the empty string, or if it
no longer accurately represents the answerer's system state of
connection, then let p be
the result of creating an answer with
connection, and return the result of
reacting to p with the
following fulfillment steps:
Let answer be the first argument
to these fulfillment steps.
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 an empty string, process candidate as
an end-of-candidates indication for the
corresponding media description and ICE
candidate generation. If both
candidate.sdpMid and
candidate.sdpMLineIndex
are null, then this end-of-candidates
indication applies to all media descriptions.
If candidate could not be
successfully added the user agent MUST queue a
task that runs the following steps:
If
connection.[[IsClosed]]
is true, then abort these
steps.
If candidate is applied
successfully, or if the candidate was administratively prohibited the user agent
MUST queue a task that runs the following
steps:
If
connection.[[IsClosed]]
is true, then abort these
steps.
A candidate is administratively prohibited if
the UA has decided not to allow connection attempts to this
address.
For privacy reasons, there is no indication to the
developer about whether or not an address/port is blocked;
it behaves exactly as if there was no response from the
address.
The UA MUST prohibit connections to addresses on the
[Fetch] block bad port list, and MAY choose to
prohibit connections to other addresses.
If the iceTransportPolicy member of
the RTCConfiguration is
relay, candidates requiring
external resolution, such as mDNS candidates and DNS
candidates, MUST be prohibited.
Note
Due to WebIDL processing,
addIceCandidate(null) is
interpreted as a call with the default dictionary present,
which, in the above algorithm, indicates end-of-candidates
for all media descriptions and ICE candidate generation.
This is by design for legacy reasons.
restartIce
The restartIce method tells the RTCPeerConnection
that ICE should be restarted. Subsequent calls to
createOffer will create descriptions that will restart
ICE, as described in section 9.1.1.1 of [ICE].
When this method is invoked, the user agent MUST run the
following steps:
Let connection be the RTCPeerConnection
on which the method was invoked.
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.[[Stopped]] is
true, abort these sub steps.
Supporting the methods in this section is optional. However, if
these methods are supported it is mandatory to implement according
to what is specified here.
Note
The addStream method that used to exist on
RTCPeerConnection is easy to polyfill as:
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:
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.
4.4.4
Garbage collection
An RTCPeerConnection object MUST not be garbage collected as
long as any event can cause an event handler to be triggered on the
object. When the object's [[IsClosed]] internal slot is
true, no such event handler can be triggered and it is
therefore safe to garbage collect the object.
All 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
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. An
"answer" or "pranswer"
cannot be rolled back.
The RTCSessionDescription()
constructor takes a dictionary argument,
description, whose content is used to initialize
the new RTCSessionDescription object. This constructor
is deprecated; it exists for legacy compatibility reasons
only.
The string representation of the SDP [SDP]; if
type is
"rollback", this member is unused.
4.7
Session Negotiation Model
Many changes to state of an RTCPeerConnection will require
communication with the remote side via the signaling channel, in
order to have the desired effect. The app can be kept informed as to
when it needs to do signaling, by listening to the negotiationneeded event. This event is fired according
to the state of the connection's negotiation-needed flag,
represented by a [[NegotiationNeeded]] internal slot.
4.7.1
Setting Negotiation-Needed
This section is non-normative.
If an operation is performed on an RTCPeerConnection that
requires signaling, the connection will be marked as needing
negotiation. Examples of such operations include adding or stopping
an RTCRtpTransceiver, or adding the first RTCDataChannel.
Internal changes within the implementation can also result in the
connection being marked as needing negotiation.
The negotiation-needed flag is cleared when a session description
of type "answer" is
set successfully, and the supplied description
matches the state of the 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 MUSTupdate the negotiation-needed flag.
To update the negotiation-needed flag for
connection, run the following steps:
The task queueing prevents negotiationneeded from firing
prematurely, in the common situation where multiple
modifications to connection are being made at
once.
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.
4.8
Interfaces for Interactive Connectivity Establishment
4.8.1
RTCIceCandidate Interface
This interface describes an ICE candidate, described in [ICE]
Section 2. Other than candidate,
sdpMid,
sdpMLineIndex, and
usernameFragment, the remaining attributes
are derived from parsing the candidate
member in candidateInitDict, if it is well formed.
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 or a peer
reflexive remote candidate, 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.
Remote candidates may be exposed, for instance via
[[SelectedCandidatePair]].remote.
By default, the user agent MUST leave the
address attribute as null
for any exposed remote candidate. Once a
RTCPeerConnection instance learns on an address by the
web application using
addIceCandidate, the user agent can
expose the address attribute value in any
RTCIceCandidate of the RTCPeerConnection instance
representing a remote candidate with that newly learnt
address.
Note
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].
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:
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
The primary grammar for candidate-attribute is defined in
section 15.1 of [ICE]. In addition, the browser MUST support
the grammar extension for ICE TCP as defined in section 4.5 of
[RFC6544].
The browser MAY support other grammar extensions for candidate-attribute as defined in other RFCs.
4.8.1.2
RTCIceProtocol Enum
The RTCIceProtocol represents the protocol of the ICE
candidate.
An "active" TCP candidate is
one for which the transport will attempt to open an
outbound connection but will not receive incoming
connection requests.
passive
A "passive" TCP candidate is
one for which the transport will receive incoming
connection attempts but not attempt a connection.
so
An "so" candidate is one for
which the transport will attempt to open a connection
simultaneously with its peer.
Note
The user agent will typically only gather
active ICE TCP candidates.
4.8.1.4
RTCIceCandidateType Enum
The RTCIceCandidateType represents the type of the ICE
candidate, as defined in [ICE] section 15.1.
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.
Note
Even where there are multiple media components, only one
event containing a null candidate is fired.
url of type DOMString, readonly, nullable
The url attribute is the STUN or TURN URL that
identifies the STUN or TURN server used to gather this
candidate. If the candidate was not gathered from a STUN or
TURN server, this parameter will be set to
null.
The address attribute is the local IP address used to
communicate with the STUN or TURN server.
On a multihomed system, multiple interfaces may be used to
contact the server, and this attribute allows the
application to figure out on which one the failure
occurred.
If the local IP address value is not already exposed as
part of a local candidate, the address attribute will
be set to null.
port of type unsigned short, readonly, nullable
The port attribute is the port used to communicate with
the STUN or TURN server.
If the address attribute is null, the
port attribute is also set to null.
url of type DOMString, readonly
The url attribute is the STUN or TURN URL that
identifies the STUN or TURN server for which the failure
occurred.
errorCode of type unsigned short, readonly
The errorCode attribute is the numeric STUN error code
returned by the STUN or TURN server [STUN-PARAMETERS].
If no host candidate can reach the server, errorCode
will be set to the value 701 which is outside the STUN
error code range. This error is only fired once per server
URL while in the RTCIceGatheringState of
"gathering".
errorText of type USVString, readonly
The errorText attribute is the STUN reason text
returned by the STUN or TURN server [STUN-PARAMETERS].
If the server could not be reached, errorText will be
set to an implementation-specific value providing details
about the error.
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 an X.509 certificate [X509V3] and
corresponding private key. A handle to information is
provided in the form of the RTCCertificate interface. The
returned RTCCertificate can be used to control the
certificate that is offered in the DTLS sessions established
by RTCPeerConnection.
The keygenAlgorithm argument is used to control
how the private key associated with the certificate is
generated. The keygenAlgorithm argument uses the
WebCrypto [WebCryptoAPI] AlgorithmIdentifier
type.
The following values MUST be supported by a user
agent: { name: "RSASSA-PKCS1-v1_5",
modulusLength: 2048, publicExponent: new Uint8Array([1, 0,
1]), hash: "SHA-256" }, and { name:
"ECDSA", namedCurve:
"P-256"
}.
Note
It is expected that a user agent will have a small or
even fixed set of values that it will accept.
The certificate produced by this process also contains a
signature. The validity of this signature is only relevant
for compatibility reasons. Only the public key and the
resulting certificate fingerprint are used by
RTCPeerConnection, but it is more likely that a
certificate will be accepted if the certificate is well
formed. The browser selects the algorithm used to sign the
certificate; a browser SHOULD select SHA-256 [FIPS-180-4]
if a hash algorithm is needed.
The resulting certificate MUST NOT include information that
can be linked to a user or user agent. Randomized
values for distinguished name and serial number SHOULD be
used.
When the method is called, the user agent MUST run the
following steps:
If the above normalization step fails with an
error, return a promise that is rejected
with error.
If the normalizedKeygenAlgorithm parameter
identifies an algorithm that the user agent cannot
or will not use to generate a certificate for
RTCPeerConnection, return a promise that is rejected with a DOMException of type
NotSupportedError. In particular,
normalizedKeygenAlgorithmMUST be an
asymmetric algorithm that can be used to produce a
signature used to authenticate DTLS connections.
Let p be a new promise.
Run the following steps in parallel:
Perform the generate key operation specified by
normalizedKeygenAlgorithm using
keygenAlgorithm.
Let generatedKeyingMaterial and
generatedKeyCertificate be the private
keying material and certificate generated by the
above step.
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.
4.9.2
RTCCertificate Interface
The RTCCertificate interface represents a certificate used to
authenticate WebRTC communications. In addition to the visible
properties, internal slots contain a handle to the generated
private keying materal ([[KeyingMaterialHandle]]), 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
getFingerprints
Returns the list of certificate fingerprints, one of which
is computed with the digest algorithm used in the
certificate signature.
For the purposes of this API, the [[Certificate]] slot
contains unstructured binary data. No mechanism is provided for
applications to access the [[KeyingMaterialHandle]]
internal slot or the keying material it references. Implementations
MUST support applications storing and retrieving RTCCertificate
objects from persistent storage, in a manner that also preserves
the keying material referenced by [[KeyingMaterialHandle]].
Implementations SHOULD store the sensitive keying material in a
secure module safe from same-process memory attacks. This allows
the private key to be stored and used, but not easily read using a
memory attack.
Initialize value.expires
attribute to contain serialized.[[Expires]].
Set value.[[Certificate]] to a copy of
serialized.[[Certificate]].
Set value.[[Origin]] to a copy of
serialized.[[Origin]].
Set value.[[KeyingMaterialHandle]] to the
private keying material handle resulting from deserializing
serialized.[[KeyingMaterialHandle]].
Note
Supporting structured cloning in this manner allows
RTCCertificate instances to be persisted to stores. It also
allows instances to be passed to other origins using APIs like
postMessage(message, options) [html]. However, the object cannot
be used by any other origin than the one that originally created
it.
5.
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.
Note
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.
Note
The WebRTC Working Group is seeking implementation feedback on the need
and timeline for a more complex handling of this situation. Some
possible designs have been discussed in GitHub issue 1283.
When video is rescaled, for example for certain combinations of width
or height and scaleResolutionDownBy
values, situations when the resulting width or height is not an integer
may occur. In such situations the user agent MUST use the integer part of the
result. 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 MediaStreamTrackSHOULD be
made such that its characteristics (width,
height and frameRate
for video tracks; sampleSize, sampleRate and
channelCount for audio tracks) are to a
reasonable degree retained by the track created on the remote side.
There are situations when this does not apply, there may for example be
resource constraints at either endpoint or in the network or there may
be RTCRtpSender settings applied that instruct the implementation
to act differently.
An RTCPeerConnection object contains a set of 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.
When creating an offer, enough media descriptions will be generated to
cover all transceivers on that end. When this offer is set as the local
description, any disassociated transceivers get associated with media
descriptions in the offer.
When an offer is set as the remote description, any media descriptions
in it not yet associated with a transceiver get associated with a new
or existing transceiver. In this case, only disassociated transceivers
that were created via the addTrack() method may
be associated. Disassociated transceivers created via the
addTransceiver() method, however, won't get
associated even if media descriptions are available in the remote
offer. Instead, new transceivers will be created and associated if
there aren't enough addTrack()-created
transceivers. This sets addTrack()-created and
addTransceiver()-created transceivers apart in a
critical way that is not observable from inspecting their attributes.
When creating an answer, only media media descriptions that were
present in the offer may be listed in the answer. As a consequence, any
transceivers that were not associated when setting the remote offer
remain disassociated after setting the local answer. This can be
remedied by the answerer creating a follow-up offer, initiating another
offer/answer exchange, or in the case of using
addTrack()-created transceivers, making sure that
enough media descriptions are offered in the initial exchange.
5.1
RTCPeerConnection Interface Extensions
The RTP media API extends the RTCPeerConnection interface as
described below.
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.
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:
A track could have contents that are inaccessible to the
application. This can be due to anything that would make
a track CORS
cross-origin. These tracks can be supplied to the
addTrack() method, and have an
RTCRtpSender created for them, but content MUST NOT
be transmitted. Silence (audio), black frames (video) or
equivalently absent content is sent in place of track
content.
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 mute event is fired at the
track.
Let senders be the result of executing the
CollectSenders algorithm.
If sender is not in senders (which
indicates its transceiver was stopped or removed due to
setting a session description of
type
"rollback"), then abort these steps.
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.
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
scaleResolutionDownBy
attribues of sendEncodings are still
undefined, initialize each encoding's
scaleResolutionDownBy to
2^(length of sendEncodings - encoding
index - 1). This results in smaller-to-larger
resolutions where the last encoding has no scaling
applied to it, e.g. 4:2:1 if the length is 3.
If the number of RTCRtpEncodingParameters now
stored in sendEncodings is 1,
then remove any rid member
from the lone entry.
Note
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 will neither send nor receive RTP.
It will generate a zero port in the offer. In answers, its
RTCRtpSender will not offer to send RTP, and its
RTCRtpReceiver will not offer to receive RTP. This is a
terminal state.
5.1.1
Processing Remote MediaStreamTracks
An application can reject incoming media descriptions by setting
the transceiver's direction to either
"inactive" to turn off both
directions temporarily, or to
"sendonly" to reject only the
incoming side. To permanently reject an m-line in a manner that
makes it available for reuse, the application would need to call
RTCRtpTransceiver.stop() and subsequently
initiate negotiation from its end.
To process remote tracks
given an RTCRtpTransceivertransceiver,
direction, msids, addList,
removeList, and trackEventInits, run the
following steps:
To set the associated
remote streams given RTCRtpReceiverreceiver,
msids, addList, and removeList,
run the following steps:
Let connection be the RTCPeerConnection object
associated with receiver.
For each MSID in msids, unless a MediaStream
object has previously been created with that id for this connection, create a
MediaStream object with that id.
Let streams be a list of the MediaStream objects
created for this connection with the 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 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 RTCRtpSenderMUST send black frames
(video) and MUST NOT send (audio). In the case of video, the
RTCRtpSenderSHOULD 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.
Methods
getCapabilities, static
The getCapabilities() method returns the most optimistic
view of the capabilities of the system for sending media of
the given kind. It does not reserve any resources, ports, or
other state but is meant to provide a way to discover the
types of capabilities of the browser including which codecs
may be supported. User agents MUST support kind
values of "audio" and "video". If
the system has no capabilities corresponding to the value of
the kind argument, getCapabilities returns
null.
These capabilities provide generally persistent cross-origin
information on the device and thus increases the
fingerprinting surface of the application. In
privacy-sensitive contexts, browsers can consider mitigations
such as reporting only a common subset of the capabilities.
Note
The codec capabilities returned affect the
setCodecPreferences() algorithm and
what inputs it throws InvalidModificationError on,
and should also be consistent with information revealed by
createOffer() and createAnswer() about codecs
negotiated for sending, to ensure any
privacy mitigations are effective.
setParameters
The setParameters method updates how track is encoded
and transmitted to a remote peer.
When the setParameters method is called, the user agent
MUST run the following steps:
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.[[LastReturnedParameters]].
Note that this also applies to
transactionId.
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.
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.
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.[[IsClosed]]
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.
A unique identifier for the last set of parameters applied.
Ensures that setParameters can only be
called based on a previous getParameters,
and that there are no intervening changes. Read-only
parameter.
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.
Indicates that this encoding is actively being sent.
Setting it to false causes this encoding to no
longer be sent. Setting it to true causes this
encoding to be sent. Since setting the value to
false does not cause the SSRC to be removed,
an RTCP BYE is not sent.
maxBitrate of type unsigned long
When present, indicates the maximum bitrate that can be
used to send this encoding. The user agent is free to
allocate bandwidth between the encodings, as long as the
maxBitrate value is not exceeded. The encoding may also
be further constrained by other limits (such as
per-transport or per-session bandwidth limits) below the
maximum specified here. maxBitrate is computed the same
way as the Transport Independent Application Specific
Maximum (TIAS) bandwidth defined in [RFC3890] Section
6.2.2, which is the maximum bandwidth needed without
counting IP or other transport layers like TCP or UDP. The
unit of maxBitrate is bits per second.
Note
How the bitrate is achieved is media and encoding
dependent. For video, a frame will always be sent as fast
as possible, but frames may be dropped until bitrate is low
enough. Thus, even a bitrate of zero will allow sending one
frame. For audio, it might be necessary to stop playing if
the bitrate does not allow the chosen encoding enough
bandwidth to be sent.
scaleResolutionDownBy of type
double
This member is only present if the sender's kind is "video". The video's
resolution will be scaled down in each dimension by the
given value before sending. For example, if the value is
2.0, the video will be scaled down by a factor of 2 in each
dimension, resulting in sending a video of one quarter the
size. If the value is 1.0, the video will not be affected.
The value must be greater than or equal to 1.0. By default,
scaling is applied by a factor of two to the power of the
layer's number, in order of smaller to higher resolutions,
e.g. 4:2:1. If there is only one layer, the sender will by
default not apply any scaling, (i.e.
scaleResolutionDownBy will be
1.0).
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:
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
[[LastStableStateReceiverTransport]] internal slot
initialized to null.
Let receiver have an
[[AssociatedRemoteMediaStreams]] internal slot,
representing a list of MediaStream objects that the
MediaStreamTrack object of this receiver is associated with,
and initialized to an empty list.
Let receiver have a
[[LastStableStateAssociatedRemoteMediaStreams]]
internal slot and initialize it to an empty list.
Let receiver have a [[ReceiveCodecs]]
internal slot, representing a list of RTCRtpCodecParameters
dictionaries, and initialized to an empty list.
Let receiver have a
[[LastStableStateReceiveCodecs]] internal slot and
initialize it to an empty list.
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 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.
Note
The codec capabilities returned affect the
setCodecPreferences() algorithm and
what inputs it throws InvalidModificationError on,
and should also be consistent with information revealed by
createOffer() and createAnswer() about codecs
negotiated for reception, to ensure any
privacy mitigations are effective.
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.
The RTCRtpContributingSource and
RTCRtpSynchronizationSource dictionaries contain
information about a given contributing source (CSRC) or
synchronization source (SSRC) respectively. When an audio or video
frame from one or more RTP packets is delivered to the
RTCRtpReceiver's MediaStreamTrack, the user agent MUST queue
a task to update the relevant information for the
RTCRtpContributingSource and RTCRtpSynchronizationSource
dictionaries based on the content of those packets. The information
relevant to the RTCRtpSynchronizationSource dictionary
corresponding to the SSRC identifier, is updated each time, and if an
RTP packet contains CSRC identifiers, then the information relevant
to the RTCRtpContributingSource dictionaries corresponding to
those CSRC identifiers is also updated. The user agent MUST process
RTP packets in order of ascending RTP timestamps. The user agent MUST
keep information from RTP packets delivered to the
RTCRtpReceiver's MediaStreamTrack in the previous 10 seconds.
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 implementation does
not need to literally queue a task for every frame, 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 CSRC or SSRC identifier of the contributing or
synchronization source.
audioLevel of type double
Only present for audio receivers. This is a value between
0..1 (linear), where 1.0 represents 0 dBov, 0 represents
silence, and 0.5 represents approximately 6 dBSPL change in
the sound pressure level from 0 dBov.
For CSRCs, this MUST be converted from the level value
defined in [RFC6465] if the RFC 6465 header extension is
present, otherwise this member MUST be absent.
For SSRCs, this MUST be converted from the level value
defined in [RFC6464]. If the RFC 6464 header extension is
not present in the received packets (such as if the other
endpoint is not a user agent or is a legacy endpoint), this
value SHOULD be absent.
Both RFCs define the level as an integral value from 0 to 127
representing the audio level in negative decibels relative to
the loudest signal that the system could possibly encode.
Thus, 0 represents the loudest signal the system could
possibly encode, and 127 represents silence.
To convert these values to the linear 0..1 range, a value of
127 is converted to 0, and all other values are converted
using the equation: 10^(-rfc_level/20).
rtpTimestamp of type unsigned long, required
The last RTP timestamp, as defined in [RFC3550] Section
5.1, of the media played out at timestamp.
A RTCRtpTransceiver may become associated with a new pending
description in JSEP while still being disassociated with the
current description. This may happen in check if negotiation is
needed.
Let transceiver have a [[Sender]] internal
slot, initialized to sender.
Let transceiver have a [[Receiver]]
internal slot, initialized to receiver.
Let transceiver have a [[Stopping]]
internal slot, initialized to false.
Let transceiver have a [[Stopped]]
internal slot, initialized to false.
Let transceiver have a [[Direction]]
internal slot, initialized to direction.
Let transceiver have a [[Receptive]]
internal slot, initialized to false.
Let transceiver have a
[[CurrentDirection]] internal slot, initialized to
null.
Let transceiver have a [[FiredDirection]]
internal slot, initialized to null.
Let transceiver have a [[PreferredCodecs]]
internal slot, initialized to an empty list.
Let transceiver have a [[JsepMid]]
internal slot, initialized to null. This is the
"RtpTransceiver mid property" defined in [JSEP], and is only
modified there.
Let transceiver have a [[Mid]] internal
slot, initialized to null.
The mid attribute is the media stream
"identification-tag" negotiated and present in the local
and remote descriptions. On getting, the attribute MUST
return the value of the [[Mid]] slot.
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.
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, the user agent MUST run the following steps:
Let transceiver be the RTCRtpTransceiver
object on which the getter is invoked.
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, the value is null. If the transceiver
is stopped, the value is
"stopped".
On getting, the user agent MUST run the following steps:
Let transceiver be the RTCRtpTransceiver
object on which the getter is invoked.
A stopping transceiver will cause future calls to
createOffer to generate a zero port in
the media description for the corresponding
transceiver, as defined in [JSEP] (The user agent MUST treat a
stopping transceiver as stopped for the purposes of
JSEP only in this case). However, to avoid problems with
[BUNDLE], a transceiver that is stopping, but not
stopped, will not affect
createAnswer.
A stopped transceiver will cause future calls to
createOffer or
createAnswer to generate a zero port in
the media description for the corresponding
transceiver, as defined in [JSEP].
The transceiver will remain in the stopping state, unless
it becomes stopped by
setRemoteDescription processing a
rejected m-line in a remote offer or answer.
Note
A transceiver that is stopping but not stopped will
always need negotiation. In practice, this means that calling
stop() on a transceiver will cause the transceiver to
become stopped eventually, provided negotiation is
allowed to complete on both ends.
When the stop method is invoked, the user agent MUST run
the following steps:
Let transceiver be the RTCRtpTransceiver
object on which the method is invoked.
Let connection be the RTCPeerConnection
object associated with transceiver.
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 agentMUST 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.
Note
Codecs have their payload types listed under each m= section
in the SDP, defining the mapping between payload types and
codecs. These payload types are referenced by the m=video or
m=audio lines in the order of preference, and codecs that are
not negotiated do not appear in this list as defined in
section 5.2.1 of [JSEP]. A previously negotiated codec
that is subsequently removed disappears from the m=video or
m=audio line, and while its codec payload type is not to be
reused in future offers or answers, its payload type may also
be removed from the mapping of payload types in the SDP.
Due to a recommendation in [SDP], calls to
createAnswerSHOULD 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.
Let transceiver be the RTCRtpTransceiver
object this method was invoked on.
Let codecs be the first argument.
If codecs is an empty list, set
transceiver.[[PreferredCodecs]] to
codecs and abort these steps.
Remove any duplicate values in codecs. Start
at the back of the list such that the priority of the
codecs is maintained; the index of the first occurrence
of a codec within the list is the same before and after
this step.
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.
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 session description. Once the
envelope is determined, layers cannot be removed. They can be
marked as inactive by setting the
active member 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 member
to false, or can be reactivated by setting the
active member to true.
Using setParameters, stream characteristics can be
changed by modifying attributes such as
maxBitrate.
Note
Simulcast is frequently used to send multiple encodings to an SFU,
which will then forward one of the simulcast streams to the end
user. The user agent is therefore expected to allocate bandwidth
between encodings in such a way that all simulcast streams are
usable on their own; for instance, if two simulcast streams have
the same maxBitrate, one would expect
to see a similar bitrate on both streams. If bandwidth does not
permit all simulcast streams to be sent in an usable form, the user
agent is expected to stop sending some of the simulcast streams.
As defined in [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 reception of
multiple RTP encodings using createOffer,
createAnswer or
addTransceiver. However when
setRemoteDescription is called with a
corresponding remote description that is able to send multiple RTP
encodings as defined in [JSEP], and the browser supports
receiving multiple RTP encodings, the RTCRtpReceiver may
receive multiple RTP encodings and the parameters retrieved via the
transceiver's
receiver.getParameters()
will reflect the encodings negotiated.
Note
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.
5.4.1.1
Encoding Parameter Examples
This section is non-normative.
Examples of simulcast scenarios implemented with encoding
parameters:
asyncfunctionplayMusicOnHold() {
try {
// Assume we have an audio transceiver and a music track named musicTrackawait 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);
}
}
asyncfunctionstopOnHoldMusic() {
// Assume we have an audio transceiver and a microphone track named micTrackawait 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:
asyncfunctiononOffHold() {
try {
// Apply the sendrecv offer first, to ensure receiver is ready for ICE candidates.await pc.setRemoteDescription(sendrecvOffer);
// Start sending audioawait audio.sender.replaceTrack(micTrack);
// Set the direction sendrecv (just in time for the answer)
audio.direction = 'sendrecv';
// Call createAnswer and send a sendrecv answerawait doAnswer();
} catch (err) {
// handle signaling error
}
}
5.5
RTCDtlsTransport Interface
The RTCDtlsTransport interface allows an application access to
information about the Datagram Transport Layer Security (DTLS)
transport over which RTP and RTCP packets are sent and received by
RTCRtpSender and RTCRtpReceiver objects, as well other data
such as SCTP packets sent and received by data channels. In
particular, DTLS adds security to an underlying transport, and the
RTCDtlsTransport interface allows access to information about the
underlying transport and the security added. RTCDtlsTransport
objects are constructed as a result of calls to
setLocalDescription() and
setRemoteDescription(). Each
RTCDtlsTransport object represents the DTLS transport layer for
the RTP or RTCP component of a specific
RTCRtpTransceiver, or a group of RTCRtpTransceivers if such a
group has been negotiated via [BUNDLE].
Note
A new DTLS association for an existing RTCRtpTransceiver will be
represented by an existing RTCDtlsTransport object, whose
state will be updated accordingly, as opposed to
being represented by a new object.
An RTCDtlsTransport has a [[DtlsTransportState]]
internal slot initialized to "new" 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.
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.[[RemoteCertificates]] 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.
5.6
RTCIceTransport Interface
The RTCIceTransport interface allows an application access to
information about the ICE transport over which packets are sent and
received. In particular, ICE manages peer-to-peer connections which
involve state which the application may want to access.
RTCIceTransport objects are constructed as a result of calls to
setLocalDescription() and
setRemoteDescription(). The underlying ICE
state is managed by the ICE agent; as such, the state of an
RTCIceTransport changes when the ICE Agent provides
indications to the user agent as described below. Each
RTCIceTransport object represents the ICE transport layer for the
RTP or RTCP component of a specific
RTCRtpTransceiver, or a group of RTCRtpTransceivers if such a
group has been negotiated via [BUNDLE].
Note
An ICE restart for an existing RTCRtpTransceiver will be
represented by an existing RTCIceTransport object, whose
state will be updated accordingly, as opposed to
being represented by a new object.
When the ICE Agent indicates that it began gathering a generation of candidates for an RTCIceTransport, the user
agent MUST queue a task that runs the following steps:
When the ICE Agent is finished gathering a generation of
candidates for an RTCIceTransport, and those candidates have been
surfaced to the application, the user agent MUST queue a task that
runs the following steps:
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 signals that the ICE role has changed due to
an ICE binding request with a role collision per [RFC8445] section
7.3.1.1, the UA will queue a task to set the value of
[[IceRole]] to the new value.
To release early candidates of a connection,
run the following steps:
The RTCIceTransportState of an RTCIceTransport may change
because a candidate pair with a usable connection was found and
selected or it may change without the selected candidate pair
changing. The selected pair and RTCIceTransportState are related
and are handled in the same task.
When the ICE Agent indicates that an RTCIceTransport has
changed either the selected candidate pair, the
RTCIceTransportState or both, the user agent MUST queue a task
that runs the following steps:
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 until ICE is restarted. Since an
ICE restart may cause connectivity to resume, entering the
"failed" state does not cause DTLS
transports, SCTP associations or the data channels that run
over them to close, or tracks to mute.
closed
The RTCIceTransport has shut down and is no longer
responding to STUN requests.
Note
The most common transitions for a successful call will be new ->
checking -> connected -> completed, but under specific
circumstances (only the last checked candidate succeeds, and
gathering and the no-more candidates indication both occur prior to
success), the state can transition directly from
"checking" to
"completed".
An ICE restart causes candidate gathering and connectivity checks to
begin anew, causing a transition to
"connected" if begun in the
"completed" state. If begun in the
transient "disconnected" state, it causes
a transition to "checking", effectively
forgetting that connectivity was previously lost.
The "failed" and
"completed" states require an indication
that there are no additional remote candidates. This can be
indicated by calling addIceCandidate with a
candidate value whose candidate property is set
to an empty string or by
canTrickleIceCandidates being set to
false.
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 Peer-to-peer Data API lets a web application send and receive
generic application data peer-to-peer. The API for sending and
receiving data models the behavior of Web
Sockets.
6.1
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.
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.
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.
6.1.1.3
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.
Note
This attribute's value will be null until the
SCTP transport goes into the
"connected" state.
onstatechange of type EventHandler
The event type of this event handler is statechange.
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.
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.
the underlying DTLS association has transitioned to
"closed" state.
Note that the last transition is logical due to the fact
that an SCTP association requires an established DTLS
connection - [RFC8261] section 6.1 specifies that SCTP
over DTLS is single-homed - and that no way of of
switching to an alternate transport is defined in this
API.
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]], and [[DataChannelId]].
Return channel.
6.2.2
Announcing a data channel as open
When the user agent is to announce an RTCDataChannel as
open, the user agent MUST queue a task to run the following
steps:
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:
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.
Let connection be the RTCPeerConnection object
associated with channel.
If channel.[[ReadyState]] is not
"open", abort these steps and discard
rawData.
Execute the sub step by switching on type and
channel.binaryType:
If type indicates that rawData is a
string:
Let data be a DOMString that represents the result
of decoding rawData as UTF-8.
If type indicates that rawData is
binary and binaryType is "blob":
Let data be a new Blob object containing
rawData as its raw data source.
If type indicates that rawData is
binary and binaryType is "arraybuffer":
Let data be a new ArrayBuffer object
containing rawData as its raw data source.
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.
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 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.
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 Web Socket's binaryType.
Methods
close
Closes the RTCDataChannel. It may be called regardless of
whether the RTCDataChannel object was created by this
peer or the remote peer.
When the close method is called, the user agent MUST run
the following steps:
Let channel be the RTCDataChannel object
which is about to be closed.
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.
Let data be the raw data represented by the
Blob object.
Note
Although the actual retrieval of data from a
Blob object can happen asynchronously, the user agent
will make sure to queue the data on the
channel's underlying data transport in
the same order as the send method is called. The byte
size of data needs to be known synchronously.
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.
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.
Note
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.
An RTCDataChannel object MUST not be garbage collected if its
[[ReadyState]] slot is
"connecting" and at least one event
listener is registered for open
events, message events, error events, closing
events, or close events.
[[ReadyState]] slot is "open" and
at least one event listener is registered for message events, error
events, closing events, or
close events.
[[ReadyState]] slot is "closing"
and at least one event listener is registered for error events, or close
events.
This section describes an interface on RTCRtpSender to send DTMF
(phone keypad) values across an RTCPeerConnection. Details of how
DTMF is sent to the other peer are described in [RTCWEB-AUDIO].
7.1
RTCRtpSender Interface Extensions
The Peer-to-peer DTMF API extends the RTCRtpSender interface as
described below.
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".
7.2
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.
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.
7.3
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.
8.
Statistics Model
8.1
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. 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.
8.2
RTCPeerConnection Interface Extensions
The Statistics API extends the RTCPeerConnection interface as
described below.
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).
Use these to retrieve the various dictionaries descended from
RTCStats that this stats report is composed of. The set of
supported property names [WEBIDL] is defined as the ids of all
the RTCStats-derived dictionaries that have been generated for
this stats report.
8.4
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,
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.
Stats ids MUST NOT be predictable by an application. This
prevents applications from depending on a particular user
agent's way of generating ids, since this prevents an
application from getting stats objects by their id unless
they have already read the id of that specific stats object.
User agents are free to pick any format for the id as long as
it meets the requirements above.
Note
A user agent can turn a predictably generated string into an
unpredictable string using a hash function, as long as it
uses a salt that is unique to the peer connection. This
allows an implementation to have predictable ids internally,
which may make it easier to guarantee that stats objects have
stable ids across getStats() calls.
The set of valid values for RTCStatsType, and the dictionaries
derived from RTCStats that they indicate, are documented in
[WEBRTC-STATS].
The stats 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
RTCPeerConnection, with the fields that are listed when they are
valid for that object in addition to the generic fields defined in
the RTCStats dictionary:
An implementation MAY support generating any other statistic defined
in [WEBRTC-STATS], and MAY generate statistics that are not
documented.
8.7
GetStats Example
Consider the case where the user is experiencing bad sound and the
application wants to determine if the cause of it is packet loss. The
following example code might be used:
asyncfunctiongatherStats(pc) {
try {
const [sender] = pc.getSenders();
const baselineReport = await sender.getStats();
awaitnewPromise(resolve => setTimeout(resolve, aBit)); // wait a bitconst currentReport = await sender.getStats();
// compare the elements from the current report with the baselinefor (const now of currentReport.values()) {
if (now.type != 'outbound-rtp') continue;
// get the corresponding stats from the baseline reportconst base = baselineReport.get(now.id);
if (!base) continue;
const remoteNow = currentReport.get(now.remoteId);
const remoteBase = baselineReport.get(base.remoteId);
const packetsSent = now.packetsSent - base.packetsSent;
const packetsReceived = remoteNow.packetsReceived -
remoteBase.packetsReceived;
const fractionLost = (packetsSent - packetsReceived) / packetsSent;
if (fractionLost > 0.3) {
// if fractionLost is > 0.3, we have probably found the culprit
}
}
} catch (err) {
console.error(err);
}
}
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 Media Capture and
Streams specification. Channels are intended to be encoded together
for transmission as, for instance, an RTP payload type. All of the
channels that a codec needs to encode jointly MUST be in the same
MediaStreamTrack and the codecs SHOULD be able to encode, or
discard, all the channels in the track.
The concepts of an input and output to a given MediaStreamTrack
apply in the case of MediaStreamTrack objects transmitted over
the network as well. A MediaStreamTrack created by an
RTCPeerConnection object (as described previously in this
document) will take as input the data received from a remote peer.
Similarly, a MediaStreamTrack from a local source, for instance a
camera via [GETUSERMEDIA], will have an output that represents
what is transmitted to a remote peer if the object is used with an
RTCPeerConnection object.
The concept of duplicating MediaStream and MediaStreamTrack
objects as described in [GETUSERMEDIA] is also applicable here.
This feature can be used, for instance, in a video-conferencing
scenario to display the local video from the user's camera and
microphone in a local monitor, while only transmitting the audio to
the remote peer (e.g. in response to the user using a "video mute"
feature). Combining different MediaStreamTrack objects into new
MediaStream objects is useful in certain situations.
Note
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.
9.2
MediaStream
9.2.1
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.
Note
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).
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.
9.3.1
MediaTrackSupportedConstraints, MediaTrackCapabilities,
MediaTrackConstraints and MediaTrackSettings
The concept of constraints and constrainable properties, including
MediaTrackConstraints (MediaStreamTrack.getConstraints(), MediaStreamTrack.applyConstraints()), and MediaTrackSettings
(MediaStreamTrack.getSettings()) are
outlined in [GETUSERMEDIA]. However, the constrainable
properties of tracks sourced from a peer connection are different
than those sourced by getUserMedia(); the
constraints and settings applicable to MediaStreamTracks
sourced from a remote source are defined here. The settings
of a remote track represent the latest frame received.
MediaStreamTrack.getCapabilities()MUST always return the empty set and
MediaStreamTrack.applyConstraints()MUST always reject with OverconstrainedError on remote tracks for constraints
defined here.
The following constrainable properties are defined to apply to
video MediaStreamTracks sourced from a remote source:
As a setting, this is the aspect ratio of the latest frame;
this is the width in pixels divided by height in pixels as a
double rounded to the tenth decimal place.
This document does not define any constrainable properties to apply
to audio MediaStreamTracks sourced from a remote source.
10.
Examples and Call Flows
This section is non-normative.
10.1
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/parseconst constraints = {audio: true, video: true};
const configuration = {iceServers: [{urls: 'stun:stun.example.org'}]};
const pc = new RTCPeerConnection(configuration);
// send any ice candidates to the other peer
pc.onicecandidate = ({candidate}) => signaling.send({candidate});
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
try {
await pc.setLocalDescription();
// send the offer to the other peer
signaling.send({description: pc.localDescription});
} catch (err) {
console.error(err);
}
};
pc.ontrack = ({track, streams}) => {
// once media for a remote track arrives, show it in the remote video element
track.onunmute = () => {
// don't set srcObject again if it is already set.if (remoteView.srcObject) return;
remoteView.srcObject = streams[0];
};
};
// call start() to initiatefunctionstart() {
addCameraMic();
}
// add camera and microphone to connectionasyncfunctionaddCameraMic() {
try {
// get a local stream, show it in a self-view and add it to be sentconst stream = await navigator.mediaDevices.getUserMedia(constraints);
for (const track of stream.getTracks()) {
pc.addTrack(track, stream);
}
selfView.srcObject = stream;
} catch (err) {
console.error(err);
}
}
signaling.onmessage = async ({data: {description, candidate}}) => {
try {
if (description) {
await pc.setRemoteDescription(description);
// if we got an offer, we need to reply with an answerif (description.type == 'offer') {
if (!selfView.srcObject) {
// blocks negotiation on permission (not recommended in production code)await addCameraMic();
}
await pc.setLocalDescription();
signaling.send({description: pc.localDescription});
}
} elseif (candidate) {
await pc.addIceCandidate(candidate);
}
} catch (err) {
console.error(err);
}
};
10.2
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(); // handles JSON.stringify/parseconst constraints = {audio: true, video: true};
const configuration = {iceServers: [{urls: 'stun:stun.example.org'}]};
let pc;
let audio;
let video;
let started = false;
// Call warmup() before media is ready, to warm-up ICE, DTLS, and media.asyncfunctionwarmup(isAnswerer) {
pc = new RTCPeerConnection(configuration);
if (!isAnswerer) {
audio = pc.addTransceiver('audio');
video = pc.addTransceiver('video');
}
// send any ice candidates to the other peer
pc.onicecandidate = ({candidate}) => signaling.send({candidate});
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
try {
await pc.setLocalDescription();
// send the offer to the other peer
signaling.send({description: pc.localDescription});
} catch (err) {
console.error(err);
}
};
pc.ontrack = async ({track, transceiver}) => {
try {
// once media for the remote track arrives, show it in the video element
event.track.onunmute = () => {
// don't set srcObject again if it is already set.if (!remoteView.srcObject) {
remoteView.srcObject = new MediaStream();
}
remoteView.srcObject.addTrack(track);
}
if (isAnswerer) {
if (track.kind == 'audio') {
audio = transceiver;
} elseif (track.kind == 'video') {
video = transceiver;
}
if (started) await addCameraMicWarmedUp();
}
} catch (err) {
console.error(err);
}
};
try {
// get a local stream, show it in a self-view and add it to be sent
selfView.srcObject = await navigator.mediaDevices.getUserMedia(constraints);
if (started) await addCameraMicWarmedUp();
} catch (err) {
console.error(err);
}
}
// call start() after warmup() to begin transmitting media from both endsfunctionstart() {
signaling.send({start: true});
signaling.onmessage({data: {start: true}});
}
// add camera and microphone to already warmed-up connectionasyncfunctionaddCameraMicWarmedUp() {
const stream = selfView.srcObject;
if (audio && video && stream) {
awaitPromise.all([
audio.sender.replaceTrack(stream.getAudioTracks()[0]),
video.sender.replaceTrack(stream.getVideoTracks()[0]),
]);
}
}
signaling.onmessage = async ({data: {start, description, candidate}}) => {
if (!pc) warmup(true);
try {
if (start) {
started = true;
await addCameraMicWarmedUp();
} elseif (description) {
await pc.setRemoteDescription(description);
// if we got an offer, we need to reply with an answerif (description.type == 'offer') {
await pc.setLocalDescription();
signaling.send({description: pc.localDescription});
}
} else {
await pc.addIceCandidate(candidate);
}
} catch (err) {
console.error(err);
}
};
10.3
Simulcast Example
A client wants to send multiple RTP encodings (simulcast) to a
server.
const signaling = new SignalingChannel(); // handles JSON.stringify/parseconst constraints = {audio: true, video: true};
const configuration = {'iceServers': [{'urls': 'stun:stun.example.org'}]};
let pc;
// call start() to initiateasyncfunctionstart() {
pc = new RTCPeerConnection(configuration);
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
try {
await pc.setLocalDescription();
// send the offer to the other peer
signaling.send({description: pc.localDescription});
} catch (err) {
console.error(err);
}
};
try {
// get a local stream, show it in a self-view and add it to be sentconst stream = await navigator.mediaDevices.getUserMedia(constraints);
selfView.srcObject = stream;
pc.addTransceiver(stream.getAudioTracks()[0], {direction: 'sendonly'});
pc.addTransceiver(stream.getVideoTracks()[0], {
direction: 'sendonly',
sendEncodings: [
{rid: 'q', scaleResolutionDownBy: 4.0}
{rid: 'h', scaleResolutionDownBy: 2.0},
{rid: 'f'},
]
});
} catch (err) {
console.error(err);
}
}
signaling.onmessage = async ({data: {description, candidate}}) => {
try {
if (description) {
await pc.setRemoteDescription(description);
// if we got an offer, we need to reply with an answerif (description.type == 'offer') {
await pc.setLocalDescription();
signaling.send({description: pc.localDescription});
}
} elseif (candidate) {
await pc.addIceCandidate(candidate);
}
} catch (err) {
console.error(err);
}
};
10.4
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 using an input field for
user input.
const signaling = new SignalingChannel(); // handles JSON.stringify/parseconst configuration = {iceServers: [{urls: 'stun:stun.example.org'}]};
let pc, channel;
// call start() to initiatefunctionstart() {
pc = new RTCPeerConnection(configuration);
// send any ice candidates to the other peer
pc.onicecandidate = ({candidate}) => signaling.send({candidate});
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
try {
await pc.setLocalDescription();
// send the offer to the other peer
signaling.send({description: pc.localDescription});
} catch (err) {
console.error(err);
}
};
// create data channel and setup chat using "negotiated" pattern
channel = pc.createDataChannel('chat', {negotiated: true, id: 0});
channel.onopen = () => input.disabled = false;
channel.onmessage = ({data}) => showChatMessage(data);
input.onkeypress = ({keyCode}) => {
// only send when user presses enterif (keyCode != 13) return;
channel.send(input.value);
}
}
signaling.onmessage = async ({data: {description, candidate}}) => {
if (!pc) start(false);
try {
if (description) {
await pc.setRemoteDescription(description);
// if we got an offer, we need to reply with an answerif (description.type == 'offer') {
await pc.setLocalDescription();
signaling.send({description: pc.localDescription});
}
} elseif (candidate) {
await pc.addIceCandidate(candidate);
}
} catch (err) {
console.error(err);
}
};
10.5
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.
asyncfunctionsendDTMF() {
if (sender.dtmf.canInsertDTMF) {
sender.dtmf.insertDTMF('123');
awaitnewPromise(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 =>newPromise(resolve => setTimeout(resolve, ms));
if (sender.dtmf.canInsertDTMF) {
const duration = 500; // ms
sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '1234', duration);
sender.dtmf.ontonechange = async ({tone}) => {
if (!tone) return;
lightKey(tone); // light up the key when playout startsawait wait(duration);
lightKey(''); // turn off the light after tone duration
};
} else {
console.log('DTMF function not available');
}
It is always safe to append to the tone buffer. This example appends
before any tone playout has started as well as during playout.
if (sender.dtmf.canInsertDTMF) {
sender.dtmf.insertDTMF('123');
// append more tones to the tone buffer before playout has begun
sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '456');
sender.dtmf.ontonechange = ({tone}) => {
// append more tones when playout has begunif (tone != '1') return;
sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '789');
};
} else {
console.log('DTMF function not available');
}
Send a 1-second "1" tone followed by a 2-second "2" tone:
if (sender.dtmf.canInsertDTMF) {
sender.dtmf.ontonechange = ({tone}) => {
if (tone == '1') {
sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '2', 2000);
}
};
sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '1', 1000);
} else {
console.log('DTMF function not available');
}
10.7
Perfect Negotiation Example
Perfect negotiation is a recommended pattern to manage negotiation
transparently, abstracting this asymmetric task away from the rest of
an application. This pattern has advantages over one side always
being the offerer, as it lets applications operate on both peer
connection objects simultaneously without risk of glare (an offer
coming in outside of "stable" state). The rest
of the application may use any and all modification methods and
attributes, without worrying about signaling state races.
It designates different roles to the two peers, with behavior to
resolve signaling collisions between them:
The polite peer uses rollback to avoid collision with
an incoming offer.
The impolite peer ignores an incoming offer when this
would collide with its own.
Together, they manage signaling for the rest of the application in a
manner that doesn't deadlock. The example assumes a
polite boolean variable indicating the designated role:
const signaling = new SignalingChannel(); // handles JSON.stringify/parseconst constraints = {audio: true, video: true};
const configuration = {iceServers: [{urls: 'stun:stun.example.org'}]};
const pc = new RTCPeerConnection(configuration);
// call start() anytime on either end to add camera and microphone to connectionasyncfunctionstart() {
try {
const stream = await navigator.mediaDevices.getUserMedia(constraints);
for (const track of stream.getTracks()) {
pc.addTrack(track, stream);
}
selfView.srcObject = stream;
} catch (err) {
console.error(err);
}
}
pc.ontrack = ({track, streams}) => {
// once media for a remote track arrives, show it in the remote video element
track.onunmute = () => {
// don't set srcObject again if it is already set.if (remoteView.srcObject) return;
remoteView.srcObject = streams[0];
};
};
// - The perfect negotiation logic, separated from the rest of the application ---// keep track of some negotiation state to prevent races and errorslet makingOffer = false;
let ignoreOffer = false;
let isSettingRemoteAnswerPending = false;
// send any ice candidates to the other peer
pc.onicecandidate = ({candidate}) => signaling.send({candidate});
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
try {
makingOffer = true;
await pc.setLocalDescription();
signaling.send({description: pc.localDescription});
} catch (err) {
console.error(err);
} finally {
makingOffer = false;
}
};
signaling.onmessage = async ({data: {description, candidate}}) => {
try {
if (description) {
// An offer may come in while we are busy processing SRD(answer).// In this case, we will be in "stable" by the time the offer is processed// so it is safe to chain it on our Operations Chain now.const readyForOffer =
!makingOffer &&
(pc.signalingState == "stable" || isSettingRemoteAnswerPending);
const offerCollision = description.type == "offer" && !readyForOffer;
ignoreOffer = !polite && offerCollision;
if (ignoreOffer) {
return;
}
isSettingRemoteAnswerPending = description.type == "answer";
await pc.setRemoteDescription(description); // SRD rolls back as needed
isSettingRemoteAnswerPending = false;
if (description.type == "offer") {
await pc.setLocalDescription();
signaling.send({description: pc.localDescription});
}
} elseif (candidate) {
try {
await pc.addIceCandidate(candidate);
} catch (err) {
if (!ignoreOffer) throw err; // Suppress ignored offer's candidates
}
}
} catch (err) {
console.error(err);
}
}
Note that this is timing sensitive, and deliberately uses versions of
setLocalDescription (without arguments) and
setRemoteDescription (with implicit rollback)
to avoid races with other signaling messages being serviced.
The ignoreOffer variable is needed, because the
RTCPeerConnection object on the impolite side is never told about
ignored offers. We must therefore suppress errors from incoming
candidates belonging to such offers.
11.
Error Handling
Some operations throw or fire RTCError. This is an extension of
DOMException that carries additional WebRTC-specific information.
The errorDetail, sdpLineNumber, sctpCauseCode,
receivedAlert and sentAlert members of RTCErrorInit have the same
definitions as the attributes of the same name of RTCError.
The DTLS negotiation has failed or the connection has been
terminated with a fatal error. The message
contains information relating to the nature of error. If a
fatal DTLS alert was received, the receivedAlert
attribute is set to the value of the DTLS alert received. If a
fatal DTLS alert was sent, the sentAlert attribute
is set to the value of the DTLS alert sent.
fingerprint-failure
The RTCDtlsTransport's remote certificate did not match any
of the fingerprints provided in the SDP. If the remote peer
cannot match the local certificate against the provided
fingerprints, this error is not generated. Instead a
"bad_certificate" (42) DTLS alert might be received from the
remote peer, resulting in a
"dtls-failure".
sctp-failure
The SCTP negotiation has failed or the connection has been
terminated with a fatal error. The sctpCauseCode
attribute is set to the SCTP cause code.
sdp-syntax-error
The SDP syntax is not valid. The sdpLineNumber
attribute is set to the line number in the SDP where the syntax
error was detected.
hardware-encoder-not-available
The hardware encoder resources required for the requested
operation are not available.
hardware-encoder-error
The hardware encoder does not support the provided parameters.
11.3
RTCErrorEvent Interface
The RTCErrorEvent interface is defined for cases when an
RTCError is raised as an event:
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].
13.1
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.
13.2
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).
13.3
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.
13.4
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.
Communication certificates may be opaquely shared using
postMessage(message, options) in anticipation of future needs. User
agents are strongly encouraged to isolate the private keying material
these objects hold a handle to, from the processes that have access
to the RTCCertificate objects, to reduce memory attack surface.
13.5
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.
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.
13.6
Setting SDP from remote endpoints
setRemoteDescription guards against malformed
and invalid SDP by throwing exceptions, but makes no attempt to guard
against SDP that might be unexpected by the application. Setting the
remote description can cause significant resources to be allocated
(including image buffers and network ports), media to start flowing
(which may have privacy and bandwidth implications) among other
things. An application that does not guard against malicious SDP
could be at risk of resource deprivation, unintentionally allowing
incoming media or at risk of not having certain events fire like
ontrack if the other endpoint does not
negotiate sending. Applications need to be on guard against
malevolent SDP.
14.
Accessibility Considerations
This section is non-normative.
The WebRTC 1.0 specification exposes an API to control protocols
(defined within the IETF) necessary to establish real-time audio, video
and data exchange.
The Telecommunications Device for the Deaf (TDD/TTY) enables
individuals who are hearing or speech impaired (among others) to
communicate over telephone lines. Real-Time Text, defined in
[RFC4103], utilizes T.140 encapsulated in RTP to enable the
transition from TDD/TTY devices to IP-based communications, including
emergency communication with
Public Safety Access Points (PSAP).
Since Real-Time Text requires the ability to send and receive data in
near real time, it can be best supported via the WebRTC 1.0 data
channel API. As defined by the IETF, the data channel protocol utilizes
the SCTP/DTLS/UDP protocol stack, which supports both reliable and
unreliable data channels. The IETF chose to standardize SCTP/DTLS/UDP
over proposals for an RTP data channel which relied on SRTP key
management and were focused on unreliable communications.
Since the IETF chose a different approach than the RTP data channel as
part of the WebRTC suite of protocols, as of the time of this
publication there is no standardized way for the WebRTC APIs to
directly support Real-Time Text as defined at IETF and implemented in
U.S. (FCC) regulations. The WebRTC working Group will evaluate whether
the developing IETF protocols in this space warrant direct exposure in
the browser APIs and is looking for input from the relevant user
communities on this potential gap.
Within the IETF MMUSIC
Working Group, work is ongoing to enable
Real-time text to be sent over the WebRTC data channel, allowing
gateways to be deployed to translate between the SCTP data channel
protocol and RFC 4103 Real-Time Text. This work, once completed, is
expected to enable a unified and interoperable approach for integrating
real-time text in WebRTC user-agents (including browsers) - through a
gateway or otherwise.
At the time of this publication, gateways that enable effective RTT
support in WebRTC clients can be developed e.g. through a custom WebRTC
data channel. This is deemed sufficient until such time as future
standardized gateways are enabled via IETF protocols such as the SCTP
data channel protocol and RFC 4103 Real-Time Text. This will need to be
defined at IETF in conjunction with related work at W3C groups to
effectively and consistently standardise RTT support internationally.
A.
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.
ITU-T Recommendation X.509 version 3 (1997). "Information Technology - Open Systems Interconnection - The Directory Authentication Framework" ISO/IEC 9594-8:1997.. ITU.
