This document defines a set of ECMAScript APIs in WebIDL to allow media
and generic application data to be sent to and received from another
browser or device implementing the appropriate set of real-time
protocols. This specification is being developed in conjunction with a
protocol specification developed by the IETF RTCWEB group and an API
specification to get access to local media devices.
Status of This Document
This section describes the status of this
document at the time of its publication. A list of current W3C
publications and the latest revision of this technical report can be found
in the W3C technical reports index at
https://www.w3.org/TR/.
Its associated
test suite has been used to build an implementation
report of the API at the time of its initial publication as a Recommendation. That test suite has been updated to integrate most of the amendments, and an updated implementation report focused on the implementation status of these amendments has been used to select features with double implementation as proposed amendments.
W3C recommends the wide deployment of this specification as a standard for
the Web.
A W3C Recommendation is a specification that, after extensive
consensus-building, is endorsed by
W3C and its Members, and
has commitments from Working Group members to
royalty-free licensing
for implementations.
Future updates to this Recommendation may incorporate
new features.
Candidate additions are marked in the document.
Candidate corrections are marked in the document.
Proposed additions are marked in the document.
Proposed corrections are marked in the document.
The W3C Membership and other interested parties are invited to review
the proposed additions and send comments through
08 December 2024. Advisory Committee Representatives
should consult their
WBS questionnaires.
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 [RFC8825] and [RFC8826].
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
This section is non-normative.
An RTCPeerConnection instance allows an application to establish
peer-to-peer communications with another RTCPeerConnection
instance in another browser, or to another endpoint implementing the
required protocols. Communications are coordinated by the exchange of
control messages (called a signaling protocol) over a signaling
channel which is provided by unspecified means, but generally by a
script in the page via the server, e.g. using WebSocket or
XMLHttpRequest.
4.2
Configuration
Proposed Correction 1:Set default values of the RTCConfiguration dictionary, aligning it with current implementations (PR #2691)
Proposed Correction 2:Allow an implementation-defined limited to the number of configured ICE Servers (PR #2679)
4.2.1
RTCConfiguration Dictionary
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.
iceServers of type sequence<RTCIceServer>,
defaulting to [].
An array of objects describing servers available to be used
by ICE, such as STUN and TURN servers.
If the number of ICE servers exceeds an
implementation-defined limit, ignore the ICE servers above
the threshold. This implementation defined limit MUST be
at least 32.
rtcpMuxPolicy of type RTCRtcpMuxPolicy, defaulting to
"require".
Indicates which rtcp-mux
policy to use when gathering ICE candidates.
certificates of type sequence<RTCCertificate>,
defaulting to [].
A set of certificates that the RTCPeerConnection uses
to authenticate.
Valid values for this parameter are created through calls
to the generateCertificate()
function.
Although any given DTLS connection will use only one
certificate, this attribute allows the caller to provide
multiple certificates that support different algorithms.
The final certificate will be selected based on the DTLS
handshake, which establishes which certificates are
allowed. The RTCPeerConnection implementation selects
which of the certificates is used for a given connection;
how certificates are selected is outside the scope of this
specification.
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
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
attribute specifies the username to use with 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 [RFC9429] (section 4.1.1.), if
the iceTransportPolicy member of the
RTCConfiguration is specified, it defines the ICE candidate policy [RFC9429] (section 3.5.3.) 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.4
RTCBundlePolicy Enum
As described in [RFC9429] (section 4.1.1.),
bundle policy affects which media tracks are negotiated if the
remote endpoint is not bundle-aware, and what ICE candidates are
gathered. If the remote endpoint is bundle-aware, all media tracks
and data channels are bundled onto the same transport.
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.5
RTCRtcpMuxPolicy Enum
As described in [RFC9429] (section 4.1.1.), the
RTCRtcpMuxPolicy affects what ICE candidates are gathered to
support non-multiplexed RTCP. The only value defined in this spec
is "require".
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.6
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 [RFC5245].
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).
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 [RFC9429] specification, as a whole, describes the details of how
the RTCPeerConnection operates. References to specific
subsections of [RFC9429] 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.
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 [RFC8826], WebRTC utilizes
self-signed rather than Public Key Infrastructure (PKI)
certificates, so that the expiration check is to ensure that
keys are not used indefinitely and additional certificate
checks are unnecessary.
Let connection have a
[[Configuration]]
internal slot, initialized to null.
Set the configuration specified by configuration.
Let connection have an [[IsClosed]]
internal slot, initialized to false.
Let connection have a
[[NegotiationNeeded]] internal slot, initialized
to false.
Let connection have an
[[SctpTransport]] internal slot, initialized to
null.
Let connection have a
[[DataChannels]] internal slot, initialized to
an empty ordered set.
Let connection have an [[Operations]]
internal slot, representing an operations chain,
initialized to an empty list.
Let connection have a
[[UpdateNegotiationNeededFlagOnEmptyChain]]
internal slot, initialized to false.
Let connection have an
[[LastCreatedOffer]] internal slot, initialized
to "".
Let connection have an
[[LastCreatedAnswer]] internal slot, initialized
to "".
Let connection have an
[[EarlyCandidates]] internal slot, initialized to
an empty list.
Let connection have an
[[SignalingState]]
internal slot, initialized to "stable".
Let connection have an
[[IceConnectionState]]
internal slot, initialized to "new".
Let connection have an
[[IceGatheringState]]
internal slot, initialized to "new".
Let connection have an
[[ConnectionState]]
internal slot, initialized to "new".
Let connection have a
[[PendingLocalDescription]] internal slot,
initialized to null.
Let connection have a
[[CurrentLocalDescription]] internal slot,
initialized to null.
Let connection have a
[[PendingRemoteDescription]] internal slot,
initialized to null.
Let connection have a
[[CurrentRemoteDescription]] internal slot,
initialized to null.
Let connection have a
[[LocalIceCredentialsToReplace]] internal slot,
initialized to an empty set.
Return connection.
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.
Use jsepSetOfTransceivers as the source of
truth with regard to what "RtpTransceivers" exist, and
their [[JsepMid]] internal slot as their "mid
property".
Candidate Correction 5:Forbid ICE gathering and connectivity checks on administrative prohibited candidates (PR #2708)
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.
Candidate Correction 37:Don't fail sRD(offer) over rid mismatch, just answer with unicast. (PR #2794)
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 on
connection succeeded
during the process to apply description,
abort these steps and start the process over as if
they had succeeded prior, to include the extra
transceiver(s) in the process.
If any promises from setParameters
methods on RTCRtpSenders associated with
connection are not settled, abort these
steps and start the process over.
If description is of type
"answer", and it initiates the closure
of an existing SCTP association, as defined in
[RFC8841], Sections 10.3 and 10.4, set the value
of connection.[[SctpTransport]] to
null.
Let trackEventInits,
muteTracks, addList,
removeList and errorList be
empty lists.
If description is of type
"answer" or "pranswer",
then run the following steps:
If description 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 [RFC8832]. 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:
Candidate Correction 26:Prune createAnswer()'s encodings and SendEncodings in sLD(answer). (PR #2801)
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:
If description is missing
all of the previously negotiated layers,
then remove all dictionaries in
transceiver.[[Sender]].[[SendEncodings]]
except the first one, and skip the next
step.
If description is missing any of
the previously negotiated layers, then
remove the dictionaries that correspond to
the missing layers from
transceiver.[[Sender]].[[SendEncodings]].
If the description is of type
"offer" and the
media description contains a request
to receive simulcast, use the order of the
rid values specified in the simulcast
attribute to create an
RTCRtpEncodingParameters dictionary for
each of the simulcast layers, populating the
rid member
according to the corresponding rid valuevalue
(using only the first value if
comma-separated alternatives exist), and
let sendEncodingsproposedSendEncodings be the list
the
list containing the created dictionaries.
Otherwise, let sendEncodingsproposedSendEncodings
be an
an empty list.
For each encoding, encoding, in
proposedSendEncodings in reverse
order, if encoding's
rid matches that of
another encoding in
proposedSendEncodings, remove
encoding
from proposedSendEncodings.
Let supportedEncodings be the
maximum number of encodings that the
implementation can support. If the length of
sendEncodingsproposedSendEncodings is greater than
supportedEncodings, truncate
sendEncodingsproposedSendEncodings so that its length is
supportedEncodings.
If sendEncodingsproposedSendEncodings is non-empty, set
set each encoding's
scaleResolutionDownBy
to 2^(length of sendEncodingsproposedSendEncodings -
encoding index - 1).
If a suitable transceiver was found
(transceiver is set), and
sendEncodingsproposedSendEncodings is non-empty, set
transceiver.[[Sender]].[[SendEncodings]]to sendEncodings, and set
transceiver.[[Sender]].[[LastReturnedParameters]]
to null.run the following steps:
If description indicates that
simulcast is not supported or desired, or
description is missing all of
the previously negotiated layers,
then remove all dictionaries in
transceiver.[[Sender]].[[SendEncodings]]
except the first one and abort these sub
steps.
If descriptionrejects is missing any of
the offered previously negotiated layers, then then
remove the
the dictionaries that correspond to rejected
to
the missing layers from
transceiver.[[Sender]].[[SendEncodings]].
Update the paused status as indicated by
[RFC8853] 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 [RFC8829RFC9429] (section 4.1.18.), if the new ICE
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.
For each url in urls, run the [=validate an ICE server URL=] algorithm on url.
Append server to validatedServers.
Set the ICE Agent's ICE
servers list to validatedServersto
iceServers.
As defined in [RFC8829RFC9429] (section 4.1.18.), if a new list of servers
replaces the ICE Agent's existing ICE servers listICE 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
ICE candidate pool has a nonzero size, any existing existing pooled
candidates will be discarded, and new candidates will be
gathered from the new servers.
To validate an ICE server URL url, run the following steps:
Candidate Correction 33:Use the url spec to parse ice server urls (PR #2853)
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.
For "stun" and "stuns" schemes, this validates
[RFC7064] section 3.1.
For "turn" and "turns" schemes, this and the steps below validate
[RFC7065] section 3.1.
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
[RFC8838]. The value is determined based on whether a
remote description indicates support for trickle ICE, as
defined in [RFC9429] (section 4.1.17.).
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 [RFC9429], except the user
agent MUST treat a stopping
transceiver as stopped for the
purposes of RFC9429 in this case.
As an offer, the generated SDP will contain the full set of
codec/RTP/RTCP capabilities supported or preferred by the
session (as opposed to an answer, which will include only a
specific negotiated subset to use). In the event
createOffer is called after the session is established,
createOffer will generate an offer that is compatible
with the current session, incorporating any changes that
have been made to the session since the last complete
offer-answer exchange, such as addition or removal of
tracks. If no changes have been made, the offer will
include the capabilities of the current local description
as well as any additional capabilities that could be
negotiated in an updated offer.
The generated SDP will also contain the ICE agent's
usernameFragment,
password and ICE options (as defined
in [RFC5245], Section 14) and may also contain any local
candidates that have been gathered by the agent.
The certificates value in
configuration for the RTCPeerConnection
provides the certificates configured by the application for
the RTCPeerConnection. These certificates, along with
any default certificates are used to produce a set of
certificate fingerprints. These certificate fingerprints
are used in the construction of SDP.
The process of generating an SDP exposes a subset of the
media capabilities of the underlying system, which provides
generally persistent cross-origin information on the
device. It thus increases the fingerprinting surface of the
application. In privacy-sensitive contexts, browsers can
consider mitigations such as generating SDP matching only a
common subset of the capabilities.
When the method is called, the user agent MUST run the
following steps:
Let connection be the RTCPeerConnection
object on which the method was invoked.
The in-parallel steps to create an offer given
connection and a promise p are as
follows:
If connection was not constructed with a set
of certificates, and one has not yet been generated,
wait for it to be generated.
Inspect the offerer's system state to
determine the currently available resources as
necessary for generating the offer, as described in
[RFC9429] (section 4.1.8.).
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 [RFC9429] (section 5.2.).
As described in [RFC8843] (Section 7), if
bundling is used (see RTCBundlePolicy) an
offerer tagged m= section must be selected in order
to negotiate a BUNDLE group. The user agent MUST
choose the m= section that corresponds to the first
non-stopped transceiver in the set of transceivers as the offerer tagged m= section.
This allows the remote endpoint to predict which
transceiver is the offerer tagged m= section
without having to parse the SDP.
The 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
[RFC8853] section 5.2 specifies that the
order of RIDs in the a=simulcast line suggests a
proposed order of preference. If the browser
decides not to transmit all encodings, one should
expect it to stop sending the last encoding in the
list first.
Let offer be a newly created
RTCSessionDescriptionInit dictionary with its
type member initialized
to the string "offer" and its
sdp member initialized to
sdpString.
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
[RFC9429].
The generated SDP will also contain the ICE agent's
usernameFragment,
password and ICE options (as defined
in [RFC5245], Section 14) and may also contain any local
candidates that have been gathered by the agent.
The certificates value in
configuration for the RTCPeerConnection
provides the certificates configured by the application for
the RTCPeerConnection. These certificates, along with
any default certificates are used to produce a set of
certificate fingerprints. These certificate fingerprints
are used in the construction of SDP.
The in-parallel steps to create an answer given
connection and a promise p are as
follows:
If connection was not constructed with a set
of certificates, and one has not yet been generated,
wait for it to be generated.
Inspect the answerer's system state to
determine the currently available resources as
necessary for generating the answer, as described in
[RFC9429] (section 4.1.9.).
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 [RFC9429] (section 5.3.).
Candidate Correction 26:Prune createAnswer()'s encodings and SendEncodings in sLD(answer). (PR #2801)
The codec preferences of an m= section's
associated transceiver associated transceiver,
transceiver, is said to be the value of
the
RTCRtpTransceivertransceiver.[[PreferredCodecs]]
with the following filtering applied (or said not
to be set if if
transceiver.[[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.
If this is an answer to an offer to receive
simulcast, then for each media section requesting
to receive simulcast, run the following steps:
If the a=simulcast
attribute contains comma-separated alternatives
for RIDs, remove all but the first ones.
If there are any identically named RIDs in the
a=simulcast attribute,
remove all but the first one. No RID
restrictions are set.
Exclude from the media section in the answer any
RID not found in the corresponding transceiver's
[[Sender]].[[SendEncodings]].
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 [RFC5245].
When this method is invoked, the user agent MUST run the
following steps:
Let connection be the RTCPeerConnection
on which the method was invoked.
The setConfiguration method updates the configuration
of this RTCPeerConnection object. This includes
changing the configuration of the ICE Agent. As noted
in [RFC9429] (section 3.5.1.),
when the ICE configuration changes in a way that requires a
new gathering phase, an ICE restart is required.
When the setConfiguration method is invoked, the user
agent MUST run the following steps:
Let connection be the RTCPeerConnection
on which the method was invoked.
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
[RFC9429] (section 5.3.1.)),
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 [RFC5245]
Section 2. Other than candidate,
sdpMid,
sdpMLineIndex, and
usernameFragment, the remaining attributes
are derived from parsing the candidate
member in candidateInitDict, if it is well formed.
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 [RFC5245].
candidate of type DOMString, readonly
This carries the candidate-attribute as defined in
section 15.1 of [RFC5245]. If this RTCIceCandidate
represents an end-of-candidates indication or a peer
reflexive remote candidate, candidate is an empty string.
sdpMid of type DOMString, readonly, nullable
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
[RFC8828].
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 [RFC5245].
relayProtocol of type RTCIceServerTransportProtocol, readonly, nullable
For local candidates of type "relay" this is the
protocol used by the endpoint to communicate with the TURN server. For
all other candidates it is null.
For local candidates of type "srflx" or type
"relay" this is the URL of the ICE server
from which the candidate was obtained. For all other candidates it is
null.
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 [RFC5245]. 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 [RFC5245]. In addition, the browser MUST support
the grammar extension for ICE TCP as defined in section 4.5 of
[RFC6544].
The browser MAY support other grammar extensions for candidate-attribute as defined in other RFCs.
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.
The RTCIceServerTransportProtocol represents the type of the transport
protocol used between the client and the server, as defined in [RFC8656] section 3.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 [RFC8838]. This
is indicated by
candidate.candidate
being set to an empty string. The
candidate object should be
signaled to the remote peer and passed into
addIceCandidate like a typical ICE
candidate, in order to provide the end-of-candidates
indication to the remote peer.
All 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.
Candidate Correction 23:Mark RTCPeerConnectionIceEvent.url as deprecated (PR #2773)
This attribute is deprecated; it exists for legacy compatibility reasons only.
Prefer the candidate url.
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.
Proposed Correction 7:Replace DOMTimeStamp in the definition of the RTCCertificateExpiration.expires and of RTCCertificate.expires, and change its origin to certificate creation time (PR #2686, PR #2700)
An optional expires attribute MAY be added to the
definition of the algorithm that is passed to
generateCertificate. If this parameter is
present it indicates the maximum time in milliseconds that the
RTCCertificate is valid for relative to for, measured from the current timetime the
certificate is created.
Proposed Correction 7:Replace DOMTimeStamp in the definition of the RTCCertificateExpiration.expires and of RTCCertificate.expires, and change its origin to certificate creation time (PR #2686, PR #2700)
4.9.2
RTCCertificate Interface
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
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, alignment restrictions of the encoder, or even CPU overuse
detection or bandwidth estimation.
Following the rules in [RFC9429] (section 3.6.),
the video MAY be downscaled. The
media MUST NOT be upscaled to create fake data that did not occur in
the input source, the media MUST NOT be cropped except as needed to
satisfy constraints on pixel counts, and the aspect ratio MUST NOT be
changed.
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.
Proposed Correction 43:Allow encoder resolution alignment in scaleResolutionDownBy. (PR #2808)
When Whenever video is rescaled, for example for certain combinations of width
or height and rescaled as a result of
scaleResolutionDownBy
values,
situations when the resulting width or height is not an integer
may occur. In such situations the The user agent MUSTMUST NOTuse transmit video larger than
the integer part of the
resultpart
of the scaled width and height from
scaleResolutionDownBy, except to respect an
encoder's minimum resolution. What to transmit if the integer part of of
the scaled width or
or height is zero is implementation-specificimplementation-defined.
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 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 [RFC9429] (section 5.2.2. and section 5.3.2.).
If any RTCRtpSender object in senders
matches all the following criteria, let sender
be that object, or null otherwise:
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 transceiver be the RTCRtpTransceiver
object corresponding to sender.
If transceiver.[[Stopping]] is
true, abort these steps.
Let
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
addTransceiver sendEncodings validation steps,
where each RTCRtpEncodingParameters
dictionary in it is an "encoding":
Candidate Correction 18:TypeError unless all or none of encodings have rids and on duplicate rids (PR #2774, PR #2775)
Verify that each rid value
in sendEncodings conforms to the grammar
specified in Section 10 of [RFC8851]. If one of
the RIDs does not meet these requirements, throw a TypeError.
If any of the following conditions are met,
throw a TypeError:
Any encoding contains a
rid member whose value
does not conform to the grammar requirements specified
in Section 10 of [RFC8851].
Candidate Addition 49:Add codec to RTCRtpEncodingParameters (PR #2985)
If the user agent does not support changing codecs without negotiation or
does not support setting codecs for individual encodings, return a promise
rejected with a newly createdOperationError.
Verify that the value of each
maxFramerate
member in sendEncodings that is defined
is greater than 0.0. If one of the
maxFramerate
values does not meet this requirement, throw a RangeError.
Let maxN be the maximum number of total
simultaneous encodings the user agent may support for
this kind, at minimum 1.This
should be an optimistic number since the codec to be
used is not known yet.
If the number of encodings stored
in sendEncodings exceeds maxN,
then trim sendEncodings from the tail
until its length is maxN.
Proposed Correction 20:Remove RTCRtpEncodingParameters.scaleResolutionDownBy for audio (PR #2772, PR #2799)
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 kind is "video" and none of the
encodings contain a
scaleResolutionDownBy
member, then for each encoding, add a
scaleResolutionDownBy
member with the value
2^(length of sendEncodings - encoding
index - 1). This results in smaller-to-larger
resolutions where the last encoding has no scaling
applied to it, e.g. 4:2:1 if the length is 3.
If the number of encodings now
stored in sendEncodings is 1,
then remove any rid member
from the lone entry.
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 [RFC9429] (section 5.2.2. and section 5.2.1.). When
setRemoteDescription is called with
a corresponding remote description that is able to
receive multiple RTP encodings as defined in
[RFC9429] (section 3.7.), the
RTCRtpSender may send multiple RTP encodings and the
parameters retrieved via the transceiver's
sender.getParameters()
will reflect the encodings negotiated.
When the remote RTCPeerConnection'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:
