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.
Itsassociated test suite has been used to build animplementation report of the API at the time of its initial publication as a Recommendation. That test suite has been updated to integrate proposed and candidates amendments identified since then, and anupdated implementation report focused on the implementation status of these amendments has been used to select features with double implementation as proposed amendments, now fully incorporated in this version of the Recommendation.
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 theIETF 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 wordsMAY,MUST,MUST NOT, andSHOULD in this document are to be interpreted as described inBCP 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: theuser 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 specificationMUST 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
TheEventHandler interface, representing a callback used for event handlers, is defined in [HTML].
The general principles for Javascript APIs apply, including the principle ofrun-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.
AnRTCPeerConnection instance allows an application to establish peer-to-peer communications with anotherRTCPeerConnection 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. usingWebSocket orXMLHttpRequest.
4.2 Configuration
4.2.1RTCConfiguration Dictionary
TheRTCConfiguration defines a set of parameters to configure how the peer-to-peer communication established viaRTCPeerConnection is established or re-established.
iceServers of typesequence<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 limitMUST be at least 32.
Indicates whichrtcp-mux policy to use when gathering ICE candidates.
certificates of typesequence<RTCCertificate>, defaulting to[].
A set of certificates that theRTCPeerConnection uses to authenticate.
Valid values for this parameter are created through calls to thegenerateCertificate() 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. TheRTCPeerConnection 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 eachRTCPeerConnection instance.
This option allows applications to establish key continuity. AnRTCCertificate 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.
As described in[RFC9429] (section 4.1.1.), if theiceTransportPolicy member of theRTCConfiguration is specified, it defines theICE 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.
TheICE 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
TheICE 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 ofRTCIceCandidate.address.
4.2.4RTCBundlePolicy 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.5RTCRtcpMuxPolicy Enum
As described in[RFC9429] (section 4.1.1.), theRTCRtcpMuxPolicy 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 istrue, or the relevantRTCPeerConnection 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 thecurrentLocalDescription 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 wheniceConnectionState transitions to "failed". An application may additionally choose to listen for theiceConnectionState transition to "disconnected" and then use other sources of information (such as usinggetStats 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.
TheRTCAnswerOptions dictionary describe options specific to session description of type "answer" (none in this version of the specification).
Note that if anRTCIceTransport is discarded as a result of signaling (e.g. RTCP mux or bundling), or created as a result of signaling (e.g. adding a newmedia 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 theRTCPeerConnection 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 serverMAY also be used as a STUN server for the purposes of gathering server reflexive candidates.
When theRTCPeerConnection.constructor() is invoked, the user agentMUST run the following steps:
If any of the steps enumerated below fails for a reason not specified here,throw anUnknownError with themessage attribute set to an appropriate description.
Else, generate one or more newRTCCertificate instances with thisRTCPeerConnection instance and store them. ThisMAY happen asynchronously and the value ofcertificates remainsundefined 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.
Letconnection have a[[Configuration]] internal slot, initialized tonull.Set the configuration specified byconfiguration.
Letconnection have an[[IsClosed]] internal slot, initialized tofalse.
Letconnection have a[[NegotiationNeeded]] internal slot, initialized tofalse.
Letconnection have an[[SctpTransport]] internal slot, initialized tonull.
Letconnection have a[[DataChannels]] internal slot, initialized to an emptyordered set.
Letconnection have an[[Operations]] internal slot, representing anoperations chain, initialized to an empty list.
Letconnection have a[[UpdateNegotiationNeededFlagOnEmptyChain]] internal slot, initialized tofalse.
Letconnection have an[[LastCreatedOffer]] internal slot, initialized to"".
Letconnection have an[[LastCreatedAnswer]] internal slot, initialized to"".
Letconnection have an[[EarlyCandidates]] internal slot, initialized to an empty list.
Letconnection have an[[SignalingState]] internal slot, initialized to "stable".
Letconnection have an[[IceConnectionState]] internal slot, initialized to "new".
Letconnection have an[[IceGatheringState]] internal slot, initialized to "new".
Letconnection have an[[ConnectionState]] internal slot, initialized to "new".
Letconnection have a[[PendingLocalDescription]] internal slot, initialized tonull.
Letconnection have a[[CurrentLocalDescription]] internal slot, initialized tonull.
Letconnection have a[[PendingRemoteDescription]] internal slot, initialized tonull.
Letconnection have a[[CurrentRemoteDescription]] internal slot, initialized tonull.
Letconnection have a[[LocalIceCredentialsToReplace]] internal slot, initialized to an empty set.
Returnconnection.
4.4.1.2 Chain an asynchronous operation
AnRTCPeerConnection object has anoperations 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 notsettled, they are added to the chain and executed when all the previous calls have finished executing and their promises havesettled.
UsejsepSetOfTransceivers 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)
Ifremote istrue, 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 applyingdescription leads to modifying a transceivertransceiver, andtransceiver.[[Sender]].[[SendEncodings]] is non-empty, and not equal to the encodings that would result from processingdescription, the process of applyingdescription fails. This specification does not allow remotely initiated RID renegotiation.
If the process to applydescription fails for any reason, then the user agentMUST queue a task that runs the following steps:
Ifconnection.[[IsClosed]] istrue, then abort these steps.
If the content ofdescription is not valid SDP syntax, thenrejectp with anRTCError (witherrorDetail set to "sdp-syntax-error" and thesdpLineNumber attribute set to the line number in the SDP where the syntax error was detected) and abort these steps.
Ifdescription is applied successfully, the user agentMUST queue a task that runs the following steps:
Ifconnection.[[IsClosed]] istrue, then abort these steps.
Ifremote istrue anddescription is of type "offer", then if anyaddTrack() methods onconnection succeeded during the process to applydescription, 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 fromsetParameters methods onRTCRtpSenders associated withconnection are notsettled, abort these steps and start the process over.
Ifdescription 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 ofconnection.[[SctpTransport]] tonull.
LettrackEventInits,muteTracks,addList,removeList anderrorList be empty lists.
Ifdescription is of type "answer" or "pranswer", then run the following steps:
Ifdescription negotiates the DTLS role of the SCTP transport, then for eachRTCDataChannel,channel, with anullid, run the following step:
Givechannel a new ID generated according to [RFC8832]. If no available ID could be generated, setchannel.[[ReadyState]] to "closed", and addchannnel toerrorList.
Ifdescription is not of type "rollback", then run the following steps:
Ifremote isfalse, then run the following steps for eachmedia description indescription:
Candidate Correction 26:Prune createAnswer()'s encodings and SendEncodings in sLD(answer). (PR #2801)
Settransceiver.[[Receiver]].[[ReceiveCodecs]] to the codecs thatdescription negotiates for receiving and which the user agent is currently prepared to receive.
Note
If thedirection is "sendonly" or "inactive", the receiver is not prepared to receive anything, and the list will be empty.
Ifdescription is of type "answer" or "pranswer", then run the following steps:
Ifdescription is missing all of the previously negotiated layers, then remove all dictionaries intransceiver.[[Sender]].[[SendEncodings]] except the first one, and skip the next step.
Ifdescription is missing any of the previously negotiated layers, then remove the dictionaries that correspond to the missing layers fromtransceiver.[[Sender]].[[SendEncodings]].
If thedescription is of type "offer" andthemedia descriptioncontains a request to receive simulcast, use the order of the rid values specified in the simulcast attribute to create anRTCRtpEncodingParameters dictionary for each of the simulcast layers, populating therid member according to the corresponding ridvaluevalue (using only the first value if comma-separated alternatives exist), and letsendEncodingsproposedSendEncodings bethe listthe listcontaining the created dictionaries. Otherwise, letsendEncodingsproposedSendEncodingsbeananempty list.
For each encoding,encoding, inproposedSendEncodings in reverse order, ifencoding'srid matches that of another encoding inproposedSendEncodings, removeencoding fromproposedSendEncodings.
LetsupportedEncodings be the maximum number of encodings that the implementation can support. If the length ofsendEncodingsproposedSendEncodings is greater thansupportedEncodings, truncatesendEncodingsproposedSendEncodings so that its length issupportedEncodings.
IfsendEncodingsproposedSendEncodings is non-empty, set seteach encoding'sscaleResolutionDownBy to2^(length ofsendEncodingsproposedSendEncodings - encoding index - 1).
If a suitable transceiver was found (transceiver is set), andsendEncodingsproposedSendEncodings is non-empty, settransceiver.[[Sender]].[[SendEncodings]]tosendEncodings, and settransceiver.[[Sender]].[[LastReturnedParameters]] tonull.run the following steps:
Ifdescription indicates that simulcast is not supported or desired, ordescription is missing all of the previously negotiated layers, then remove all dictionaries intransceiver.[[Sender]].[[SendEncodings]] except the first one and abort these sub steps.
Ifdescriptionrejectsis missingany of theofferedpreviously negotiatedlayers,thenthenremovethethedictionaries that correspondto rejectedto the missinglayers fromtransceiver.[[Sender]].[[SendEncodings]].
Update the paused status as indicated by [RFC8853] of each simulcast layer by setting theactive member on the corresponding dictionaries intransceiver.[[Sender]].[[SendEncodings]] totrue for unpaused or tofalse for paused.
Ifdirection is "sendrecv" or "recvonly", letmsids be a list of the MSIDs that the media description indicatestransceiver.[[Receiver]].[[ReceiverTrack]] is to be associated with. Otherwise, letmsids be an empty list.
Process remote tracks withtransceiver,direction,msids,addList,removeList, andtrackEventInits.
Settransceiver.[[Receiver]].[[ReceiveCodecs]] to the codecs thatdescription negotiates for receiving and which the user agent is currently prepared to receive.
Ifdescription is of type "answer" or "pranswer", then run the following steps:
Settransceiver.[[Sender]].[[SendCodecs]] to the codecs thatdescription negotiates for sending and which the user agent is currently capable of sending.
If the length ofconfiguration.certificates is different from the length ofoldConfig.certificates, fail.
Letindex be 0.
Whileindex is less than the length ofconfiguration.certificates, run the following steps:
If the ECMAScript object represented by the value ofconfiguration.certificates atindex is not the same as the ECMAScript object represented by the value ofoldConfig.certificates atindex, then fail.
Set theICE Agent'sICE transports setting to the value ofconfiguration.iceTransportPolicy. As defined in[RFC9429] (section 4.1.18.), if the newICE 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.
As defined in[RFC9429] (section 4.1.18.), if a new list of servers replaces theICE Agent's existingICE 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 theICE candidate pool has a nonzero size, any existing pooled candidates will be discarded, and new candidates will be gathered from the new servers.
Parse theurl using the generic URI syntax defined in [RFC3986] and obtain thescheme name. If the parsing based on the syntax defined in [RFC3986] fails,throw aSyntaxError. If thescheme name is not implemented by the browserthrow aNotSupportedError. Ifscheme name isturn orturns, and parsing theurl using the syntax defined in [RFC7065] fails,throw aSyntaxError. Ifscheme name isstun orstuns, and parsing theurl using the syntax defined in [RFC7064] fails,throw aSyntaxError.
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.
TheRTCPeerConnection interface presented in this section is extended by several partial interfaces throughout this specification. Notably, theRTP Media API section, which adds the APIs to send and receiveMediaStreamTrack objects.
It represents the local description that was successfully negotiated the last time theRTCPeerConnection transitioned into the stable state plus any local candidates that have been generated by theICE 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 theICE Agent since the offer or answer was created. If theRTCPeerConnection is in the stable state, the value isnull.
It represents the last remote description that was successfully negotiated the last time theRTCPeerConnection transitioned into the stable state plus any remote candidates that have been supplied viaaddIceCandidate() 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 viaaddIceCandidate() since the offer or answer was created. If theRTCPeerConnection is in the stable state, the value isnull.
canTrickleIceCandidates of typeboolean, readonly, nullable
ThecanTrickleIceCandidates 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 ofsetRemoteDescription, this value isnull.
ThecreateOffer method generates a blob of SDP that contains an RFC 3264 offer with the supported configurations for the session, including descriptions of the localMediaStreamTracks attached to thisRTCPeerConnection, the codec/RTP/RTCP capabilities supported by this implementation, and parameters of theICE agent and the DTLS connection. Theoptions 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 thatsetLocalDescription will succeed when it attempts to acquire those resources. The session descriptionsMUST remain usable bysetLocalDescription without causing an error until at least the end of thefulfillment callback of the returned promise.
Creating the SDPMUST follow the appropriate process for generating an offer described in [RFC9429], except the user agentMUST treat astopping transceiver asstopped 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 eventcreateOffer 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 theICE agent'susernameFragment,password and ICE options (as defined in [RFC5245], Section 14) and may also contain any local candidates that have been gathered by the agent.
Thecertificates value inconfiguration for theRTCPeerConnection provides the certificates configured by the application for theRTCPeerConnection. 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 agentMUST run the following steps:
Letconnection be theRTCPeerConnection object on which the method was invoked.
Thein-parallel steps to create an offer givenconnection and a promisep are as follows:
Ifconnection was not constructed with a set of certificates, and one has not yet been generated, wait for it to be generated.
Inspect theofferer'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 ofconnection and itsRTCRtpTransceivers, generate an SDP offer,sdpString, as described in[RFC9429] (section 5.2.).
As described in [RFC8843] (Section 7), if bundling is used (seeRTCBundlePolicy) an offerer tagged m= section must be selected in order to negotiate a BUNDLE group. The user agentMUST choose the m= section that corresponds to the first non-stopped transceiver in theset 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.
LetfilteredCodecs be the result of applying the following filter ontransceiver.[[PreferredCodecs]]. The filteringMUST NOT change the order of the codec preferences:
Thecodec preferences of amedia description'sassociated transceiver,transceiver, is said to be the value offilteredCodecs if non-empty and said to be unset otherwise.
If the length of the[[SendEncodings]] slot of theRTCRtpSender is larger than 1, then for each encoding given in[[SendEncodings]] of theRTCRtpSender, add ana=rid send line to the corresponding media section, and add ana=simulcast:send line giving the RIDs in the same order as given in theencodings 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.
Letoffer be a newly createdRTCSessionDescriptionInit dictionary with itstype member initialized to the string "offer" and itssdp member initialized tosdpString.
ThecreateAnswer method generates an [SDP] answer with the supported configuration for the session that is compatible with the parameters in the remote configuration. LikecreateOffer, the returned blob of SDP contains descriptions of the localMediaStreamTracks attached to thisRTCPeerConnection, the codec/RTP/RTCP options negotiated for this session, and any candidates that have been gathered by theICE Agent. Theoptions parameter may be supplied to provide additional control over the generated answer.
LikecreateOffer, the returned descriptionSHOULD reflect the current state of the system. The session descriptionsMUST remain usable bysetLocalDescription without causing an error until at least the end of thefulfillment 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 SDPMUST follow the appropriate process for generating an answer described in [RFC9429].
The generated SDP will also contain theICE agent'susernameFragment,password and ICE options (as defined in [RFC5245], Section 14) and may also contain any local candidates that have been gathered by the agent.
Thecertificates value inconfiguration for theRTCPeerConnection provides the certificates configured by the application for theRTCPeerConnection. 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.
Thein-parallel steps to create an answer givenconnection and a promisep are as follows:
Ifconnection was not constructed with a set of certificates, and one has not yet been generated, wait for it to be generated.
Inspect theanswerer'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 ofconnection and itsRTCRtpTransceivers, 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)
Thecodec preferences of an m= section's associated transceiver is said to be the value of theRTCRtpTransceiver.[[PreferredCodecs]] with the following filtering applied (or said not to be set if[[PreferredCodecs]] is empty):
The filteringMUST NOT change the order of the codec preferences.
If the length of the[[SendEncodings]] slot of theRTCRtpSender is larger than 1, then for each encoding given in[[SendEncodings]] of theRTCRtpSender, add ana=rid send line to the corresponding media section, and add ana=simulcast:send line giving the RIDs in the same order as given in theencodings field. No RID restrictions are set.
LetfilteredCodecs be the result of applying the following filter ontransceiver.[[PreferredCodecs]]. The filteringMUST NOT change the order of the codec preferences:
Thecodec preferences of amedia description'sassociated transceiver,transceiver, is said to be the value offilteredCodecs if non-empty and said to be unset otherwise.
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 thea=simulcast attribute contains comma-separated alternatives for RIDs, remove all but the first ones.
If there are any identically named RIDs in thea=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]].
Letanswer be a newly createdRTCSessionDescriptionInit dictionary with itstype member initialized to the string "answer" and itssdp member initialized tosdpString.
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, theRTCPeerConnectionMUST 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 theRTCPeerConnection can fully adopt the pending local description, or rollback to the current description if the remote side rejected the change.
Ifsdp is the empty string, or if it no longer accurately represents theanswerer's system state ofconnection, then letp be the result ofcreating an answer withconnection, and return the result ofreacting top with the following fulfillment steps:
Letanswer be the first argument to these fulfillment steps.
TheaddIceCandidate method provides a remote candidate to theICE Agent. This method can also be used to indicate the end of remote candidates when called with an empty string for thecandidate member. The only members of the argument used by this method arecandidate,sdpMid,sdpMLineIndex, andusernameFragment; the rest are ignored. When the method is invoked, the user agentMUST run the following steps:
Letcandidate be the method's argument.
Letconnection be theRTCPeerConnection object on which the method was invoked.
Ifcandidate.candidate is an empty string, processcandidate as an end-of-candidates indication for the correspondingmedia description and ICE candidategeneration. If bothcandidate.sdpMid andcandidate.sdpMLineIndex arenull, then this end-of-candidates indication applies to allmedia descriptions.
Ifcandidate could not be successfully added the user agentMUST queue a task that runs the following steps:
Ifconnection.[[IsClosed]] istrue, then abort these steps.
A candidate isadministratively 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 UAMUST prohibit connections to addresses on the [Fetch]block bad port list, andMAY choose to prohibit connections to other addresses.
If theiceTransportPolicy member of theRTCConfiguration isrelay, 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
TherestartIce method tells theRTCPeerConnection that ICE should be restarted. Subsequent calls tocreateOffer will create descriptions that will restart ICE, as described in section 9.1.1.1 of [RFC5245].
When this method is invoked, the user agentMUST run the following steps:
Letconnection be theRTCPeerConnection on which the method was invoked.
ThesetConfiguration method updates the configuration of thisRTCPeerConnection object. This includes changing the configuration of theICE 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 thesetConfiguration method is invoked, the user agentMUST run the following steps:
Letconnection be theRTCPeerConnection on which the method was invoked.
Lettransceivers be the result of executing theCollectTransceivers algorithm. For everyRTCRtpTransceivertransceiver intransceivers, run the following steps:
Iftransceiver.[[Stopped]] istrue, 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
TheaddStream method that used to exist onRTCPeerConnection 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 theRTCPeerConnection. Developers are encouraged to use theRTCRtpTransceiver API instead.
WhencreateOffer is called with any of the legacy options specified in this section, run the followings steps instead of the regularcreateOffer 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 typeboolean
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
AnRTCPeerConnection objectMUST 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 istrue, 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.
AnRTCSdpType of "offer" indicates that a descriptionMUST be treated as an [SDP] offer.
pranswer
AnRTCSdpType of "pranswer" indicates that a descriptionMUST 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
AnRTCSdpType of "answer" indicates that a descriptionMUST be treated as an [SDP] final answer, and the offer-answer exchangeMUST 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
AnRTCSdpType of "rollback" indicates that a descriptionMUST 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 benull if there has not yet been a successful offer-answer negotiation. An "answer" or "pranswer" cannot be rolled back.
TheRTCSessionDescription() constructor takes a dictionary argument,description, whose content is used to initialize the newRTCSessionDescription object. This constructor is deprecated; it exists for legacy compatibility reasons only.
The string representation of the SDP [SDP]; iftype is "rollback", this member is unused.
4.7 Session Negotiation Model
Many changes to state of anRTCPeerConnection 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 thenegotiationneeded event. This event is fired according to the state of the connection'snegotiation-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 anRTCPeerConnection that requires signaling, the connection will be marked as needing negotiation. Examples of such operations include adding or stopping anRTCRtpTransceiver, or adding the firstRTCDataChannel.
Internal changes within the implementation can also result in the connection being marked as needing negotiation.
Thenegotiation-needed flag is cleared when a session description of type "answer"is set successfully, and the supplied description matches the state of theRTCRtpTransceivers andRTCDataChannels that currently exist on theRTCPeerConnection. Specifically, this means that all non-stopped transceivers have anassociated 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 agentMUSTupdate the negotiation-needed flag.
Toupdate the negotiation-needed flag forconnection, run the following steps:
The task queueing preventsnegotiationneeded from firing prematurely, in the common situation where multiple modifications toconnection are being made at once.
Iftransceiver isn'tstopped and isn't yetassociated with an m= section indescription, returntrue.
Iftransceiver isn'tstopped and isassociated with an m= section indescription then perform the following checks:
Iftransceiver.[[Direction]] is "sendrecv" or "sendonly", and theassociated m= section indescription either doesn't contain a singlea=msid line, or the number of MSIDs from thea=msid lines in thism= section, or the MSID values themselves, differ from what is intransceiver.sender.[[AssociatedMediaStreamIds]], returntrue.
Ifdescription is of type "answer", and the direction of theassociated m= section in thedescription does not matchtransceiver.[[Direction]] intersected with the offered direction (as described in[RFC9429] (section 5.3.1.)), returntrue.
If all the preceding checks were performed andtrue was not returned, nothing remains to be negotiated; returnfalse.
4.8 Interfaces for Interactive Connectivity Establishment
4.8.1RTCIceCandidate Interface
This interface describes an ICE candidate, described in [RFC5245] Section 2. Other thancandidate,sdpMid,sdpMLineIndex, andusernameFragment, the remaining attributes are derived from parsing thecandidate member incandidateInitDict, if it is well formed.
To maintain backward compatibility, any error on parsing thecandidate attribute is ignored. In such case, thecandidate attribute holds the rawcandidate string given incandidateInitDict, but derivative attributes such asfoundation,priority, etc are set tonull.
Attributes
Most attributes below are defined in section 15.1 of [RFC5245].
candidate of typeDOMString, readonly
This carries thecandidate-attribute as defined in section 15.1 of [RFC5245]. If thisRTCIceCandidate represents an end-of-candidates indication or a peer reflexive remote candidate,candidate is an empty string.
sdpMid of typeDOMString, readonly, nullable
If notnull, this contains themedia stream "identification-tag" defined in [RFC5888] for the media component this candidate is associated with.
sdpMLineIndex of typeunsigned short, readonly, nullable
If notnull, this indicates the index (starting at zero) of themedia description in the SDP this candidate is associated with.
foundation of typeDOMString, readonly, nullable
A unique identifier that allows ICE to correlate candidates that appear on multipleRTCIceTransports.
The assigned network component of the candidate ("rtp" or "rtcp"). This corresponds to thecomponent-id field incandidate-attribute, decoded to the string representation as defined inRTCIceComponent.
priority of typeunsigned long, readonly, nullable
The assigned priority of the candidate.
address of typeDOMString, readonly, nullable
The address of the candidate, allowing for IPv4 addresses, IPv6 addresses, and fully qualified domain names (FQDNs). This corresponds to theconnection-address field incandidate-attribute.
Remote candidates may be exposed, for instance via[[SelectedCandidatePair]].remote. By default, the user agentMUST leave theaddress attribute asnull for any exposed remote candidate. Once aRTCPeerConnection instance learns on an address by the web application usingaddIceCandidate, the user agent can expose theaddress attribute value in anyRTCIceCandidate of theRTCPeerConnection 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 inRTCIceCandidate 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 theICE Agent to report only relay candidates via theiceTransportPolicy member ofRTCConfiguration.
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 typeDOMString, readonly, nullable
For a candidate that is derived from another, such as a relay or reflexive candidate, therelatedAddress is the IP address of the candidate that it is derived from. For host candidates, therelatedAddress isnull. This corresponds to therel-address field incandidate-attribute.
relatedPort of typeunsigned short, readonly, nullable
For a candidate that is derived from another, such as a relay or reflexive candidate, therelatedPort is the port of the candidate that it is derived from. For host candidates, therelatedPort isnull. This corresponds to therel-port field incandidate-attribute.
usernameFragment of typeDOMString, readonly, nullable
This carries theufrag as defined in section 15.4 of [RFC5245].
relayProtocol of typeRTCIceServerTransportProtocol, 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 isnull.
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 isnull.
Methods
toJSON()
To invoke thetoJSON() operation of theRTCIceCandidate interface, run the following steps:
This carries thecandidate-attribute as defined in section 15.1 of [RFC5245]. If this represents an end-of-candidates indication,candidate is an empty string.
sdpMid of typeDOMString, nullable, defaulting tonull
The primary grammar forcandidate-attribute is defined in section 15.1 of [RFC5245]. In addition, the browserMUST support the grammar extension for ICE TCP as defined in section 4.5 of [RFC6544].
The browserMAY support other grammar extensions forcandidate-attribute as defined in other RFCs.
4.8.1.2RTCIceProtocol Enum
TheRTCIceProtocol 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 gatheractive ICE TCP candidates.
TheRTCIceServerTransportProtocol represents the type of the transport protocol used between the client and the server, as defined in [RFC8656] section 3.1.
Theicecandidate event is used for three different types of indications:
A candidate has been gathered. Thecandidate member of the event will be populated normally. It should be signaled to the remote peer and passed intoaddIceCandidate.
AnRTCIceTransport has finished gathering ageneration of candidates, and is providing an end-of-candidates indication as defined by Section 8.2 of [RFC8838]. This is indicated bycandidate.candidate being set to an empty string. Thecandidate object should be signaled to the remote peer and passed intoaddIceCandidate like a typical ICE candidate, in order to provide the end-of-candidates indication to the remote peer.
Thecandidate attribute is theRTCIceCandidate object with the new ICE candidate that caused the event.
This attribute is set tonull when an event is generated to indicate the end of candidate gathering.
Note
Even where there are multiple media components, only one event containing anull candidate is fired.
url of typeDOMString, readonly, nullable
Theurl 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 tonull.
Candidate Correction 23:Mark RTCPeerConnectionIceEvent.url as deprecated (PR #2773)
This attribute is deprecated; it exists for legacy compatibility reasons only. Prefer the candidateurl.
Theaddress 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, theaddress attribute will be set tonull.
port of typeunsigned short, readonly, nullable
Theport attribute is the port used to communicate with the STUN or TURN server.
If theaddress attribute isnull, theport attribute is also set tonull.
url of typeDOMString, readonly
Theurl attribute is the STUN or TURN URL that identifies the STUN or TURN server for which the failure occurred.
errorCode of typeunsigned short, readonly
TheerrorCode 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 theRTCIceGatheringState of "gathering".
errorText of typeUSVString, readonly
TheerrorText 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 thecertificates configuration option when constructing anRTCPeerConnection a new set of certificatesMUST be generated by theuser agent. That setMUST include an ECDSA certificate with a private key on the P-256 curve and a signature with a SHA-256 hash.
ThegenerateCertificate function causes theuser agent to create an X.509 certificate [X509V3] and corresponding private key. A handle to information is provided in the form of theRTCCertificate interface. The returnedRTCCertificate can be used to control the certificate that is offered in the DTLS sessions established byRTCPeerConnection.
ThekeygenAlgorithm argument is used to control how the private key associated with the certificate is generated. ThekeygenAlgorithm argument uses the WebCrypto [WebCryptoAPI]AlgorithmIdentifier type.
The following valuesMUST be supported by auser 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 auser 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 byRTCPeerConnection, 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 browserSHOULD select SHA-256 [FIPS-180-4] if a hash algorithm is needed.
The resulting certificateMUST NOT include information that can be linked to a user oruser agent. Randomized values for distinguished name and serial numberSHOULD be used.
When the method is called, the user agentMUST run the following steps:
If the above normalization step fails with anerror, return a promise that isrejected witherror.
If thenormalizedKeygenAlgorithm parameter identifies an algorithm that theuser agent cannot or will not use to generate a certificate forRTCPeerConnection, return a promise that isrejected with aDOMException of typeNotSupportedError. In particular,normalizedKeygenAlgorithmMUST be an asymmetric algorithm that can be used to produce a signature used to authenticate DTLS connections.
An optionalexpires attributeMAY be added to the definition of the algorithm that is passed togenerateCertificate. If this parameter is present it indicates the maximum time in milliseconds that theRTCCertificate is valid for, measured from the time the certificate is created.
4.9.2RTCCertificate Interface
TheRTCCertificate 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]]) thatRTCPeerConnection uses to authenticate with a peer, and the origin ([[Origin]]) that created the object.
Theexpires 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 anRTCPeerConnection using this certificate fail.
Note that this value might not be reflected in anotAfter 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. ImplementationsMUST support applications storing and retrievingRTCCertificate objects from persistent storage, in a manner that also preserves the keying material referenced by[[KeyingMaterialHandle]]. ImplementationsSHOULD 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.
Initializevalue.expires attribute to containserialized.[[Expires]].
Setvalue.[[Certificate]] to a copy of serialized.[[Certificate]]
Setvalue.[[Origin]] to a copy ofserialized.[[Origin]]
Setvalue.[[KeyingMaterialHandle]] to the private keying material handle resulting from deserializingserialized.[[KeyingMaterialHandle]]
Note
Supporting structured cloning in this manner allowsRTCCertificate instances to be persisted to stores. It also allows instances to be passed to other origins using APIs likepostMessage(message,options) [html]. However, the object cannot be used by any other origin than the one that originally created it.
5. RTP Media API
TheRTP media API lets a web application send and receiveMediaStreamTracks over a peer-to-peer connection. Tracks, when added to anRTCPeerConnection, 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 oneRTCPeerConnection 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 anRTCRtpSender without creating a new track on the receiver side; the correspondingRTCRtpReceiver will only have a single track, potentially representing multiple sources of media stitched together. BothaddTransceiver andreplaceTrack 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 anRTCRtpSender on one side and anRTCRtpReceiver's track on the other side, matching senders and receivers using theRTCRtpTransceiver'smid 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 videoMAY be downscaled. The mediaMUST NOT be upscaled to create fake data that did not occur in the input source, the mediaMUST NOT be cropped except as needed to satisfy constraints on pixel counts, and the aspect ratioMUST 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 inGitHub issue 1283.
Whenever video is rescaled as a result ofscaleResolutionDownBy, situations when the resulting width or height is not an integer may occur. The user agentMUST NOT transmit video larger thanthe integer part of the scaled width and height fromscaleResolutionDownBy, except to respect an encoder's minimum resolution. What to transmit if the integer part of the scaled width or height is zero isimplementation-defined.
The actual encoding and transmission ofMediaStreamTracks is managed through objects calledRTCRtpSenders. Similarly, the reception and decoding ofMediaStreamTracks is managed through objects calledRTCRtpReceivers. EachRTCRtpSender is associated with at most one track, and each track to be received is associated with exactly oneRTCRtpReceiver.
The encoding and transmission of eachMediaStreamTrackSHOULD be made such that its characteristics (width,height andframeRate for video tracks;sampleSize,sampleRate andchannelCount 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 beRTCRtpSender settings applied that instruct the implementation to act differently.
AnRTCPeerConnection object contains aset ofRTCRtpTransceivers, representing the paired senders and receivers with some shared state.This set is initialized to the empty set when theRTCPeerConnection object is created.RTCRtpSenders andRTCRtpReceivers are always created at the same time as anRTCRtpTransceiver, which they will remain attached to for their lifetime.RTCRtpTransceivers are created implicitly when the application attaches aMediaStreamTrack to anRTCPeerConnection via theaddTrack() method, or explicitly when the application uses theaddTransceiver 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 relevantMediaStreamTrack andRTCRtpReceiver are surfaced to the application via thetrack 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 theaddTrack() method may be associated. Disassociated transceivers created via theaddTransceiver() 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 enoughaddTrack()-created transceivers. This setsaddTrack()-created andaddTransceiver()-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 usingaddTrack()-created transceivers, making sure that enough media descriptions are offered in the initial exchange.
5.1 RTCPeerConnection Interface Extensions
The RTP media API extends theRTCPeerConnection interface as described below.
When theaddTrack method is invoked, the user agentMUST run the following steps:
Letconnection be theRTCPeerConnection object on which this method was invoked.
Lettrack be theMediaStreamTrack object indicated by the method's first argument.
Letkind betrack.kind.
Letstreams be a list ofMediaStream 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 tocreateOffer andcreateAnswer to mark the correspondingmedia description assendrecv orsendonly and add the MSID of the sender's streams, as defined in[RFC9429] (section 5.2.2. andsection 5.3.2.).
If anyRTCRtpSender object insenders matches all the following criteria, letsender be that object, ornull otherwise:
A track could have contents that are inaccessible to the application. This can be due to anything that would make a trackCORS cross-origin. These tracks can be supplied to theaddTrack() method, and have anRTCRtpSender created for them, but contentMUST 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 remoteMediaStreams that were initially revealed in thetrack event, and if theMediaStreamTrack is not already muted, amute event is fired at the track.
ValidatesendEncodings by running the following addTransceiver sendEncodings validation steps, where eachRTCRtpEncodingParameters 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 eachrid value insendEncodings conforms to the grammar specified in Section 10 of [RFC8851]. If one of the RIDs does not meet these requirements,throw aTypeError.
If any of the following conditions are met,throw aTypeError:
Any encodingcontains arid 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 promiserejected with a newlycreatedOperationError.
Verify that the value of eachmaxFramerate member insendEncodings that is defined is greater than 0.0. If one of themaxFramerate values does not meet this requirement,throw aRangeError.
LetmaxN be the maximum number of total simultaneous encodings the user agent may support for thiskind, at minimum1.This should be an optimistic number since the codec to be used is not known yet.
If the number of encodings stored insendEncodings exceedsmaxN, then trimsendEncodings from the tail until its length ismaxN.
Ifkind is"video" and none of the encodingscontain ascaleResolutionDownBy member, then for each encoding, add ascaleResolutionDownBy member with the value2^(length ofsendEncodings - 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 insendEncodings is1, then remove anyrid member from the lone entry.
Note
Providing a single, defaultRTCRtpEncodingParameters insendEncodings allows the application to subsequently set encoding parameters usingsetParameters, even when simulcast isn't used.
Create an RTCRtpSender withtrack,kind,streams andsendEncodings and letsender be the result.
IfsendEncodings is set, then subsequent calls tocreateOffer will be configured to send multiple RTP encodings as defined in[RFC9429] (section 5.2.2. andsection 5.2.1.). WhensetRemoteDescription is called with a corresponding remote description that is able to receive multiple RTP encodings as defined in[RFC9429] (section 3.7.), theRTCRtpSender may send multiple RTP encodings and the parameters retrieved via the transceiver'ssender.getParameters() will reflect the encodings negotiated.
When the remoteRTCPeerConnection's track event fires corresponding to theRTCRtpReceiver being added, these are the streams that will be put in the event.
TheRTCRtpTransceiver will neither send nor receive RTP. It will generate a zero port in the offer. In answers, itsRTCRtpSender will not offer to send RTP, and itsRTCRtpReceiver 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 callRTCRtpTransceiver.stop() and subsequently initiate negotiation from its end.
Toprocess remote tracks given anRTCRtpTransceivertransceiver,direction,msids,addList,removeList, andtrackEventInits, run the following steps:
TheRTCRtpSender interface allows an application to control how a givenMediaStreamTrack is encoded and transmitted to a remote peer. WhensetParameters is called on anRTCRtpSender object, the encoding is changed appropriately.
Tocreate an RTCRtpSender with aMediaStreamTrack,track, a string,kind, a list ofMediaStream objects,streams, and optionally a list ofRTCRtpEncodingParameters objects,sendEncodings, run the following steps:
Letsender have an[[AssociatedMediaStreamIds]] internal slot, representing a list of Ids ofMediaStream objects that this sender is to be associated with. The[[AssociatedMediaStreamIds]] slot is used whensender is represented in SDP as described in[RFC9429] (section 5.2.1.).
Letsender have a[[SendEncodings]] internal slot, representing a list ofRTCRtpEncodingParameters dictionaries.
IfsendEncodings is given as input to this algorithm, and is non-empty, set the[[SendEncodings]] slot tosendEncodings. Otherwise, set it to a list containing a single newRTCRtpEncodingParameters dictionary, and ifkind is"video", add ascaleResolutionDownBy member with the value1.0 to that dictionary.
Thetrack attribute is the track that is associated with thisRTCRtpSender object. Iftrack is ended, or if the track's output is disabled, i.e. the track is disabled and/or muted, theRTCRtpSenderMUST send black frames (video) andMUST NOT send (audio). In the case of video, theRTCRtpSenderSHOULD send one black frame per second. Iftrack isnull then theRTCRtpSender does not send. On getting, the attributeMUST return the value of the[[SenderTrack]] slot.
Thetransport attribute is the transport over which media fromtrack is sent in the form of RTP packets. Prior to construction of theRTCDtlsTransport object, thetransport attribute will be null. When bundling is used, multipleRTCRtpSender objects will share onetransport and will all send RTP and RTCP over the same transport.
On getting, the attributeMUST return the value of the[[SenderTransport]] slot.
Methods
getCapabilities, static
The staticRTCRtpSender.getCapabilities() method provides a way to discover the types of capabilities the user agent supports for sending media of the given kind, without reserving any resources, ports, or other state.
When thegetCapabilities method is called, the user agentMUST run the following steps:
Thelist of implemented send codecs, givenkind, is animplementation-defined list ofRTCRtpCodec dictionaries representing the most optimistic view of the codecs the user agent supports for sending media of the givenkind (video or audio).
Thelist of implemented header extensions for sending, givenkind, is animplementation-defined list ofRTCRtpHeaderExtensionCapability dictionaries representing the most optimistic view of the header extensions the user agent supports for sending media of the givenkind (video or audio).
These capabilities provide generally persistent cross-origin information on the device and thus increases the fingerprinting surface of the application. In privacy-sensitive contexts, user agentsMAY consider mitigations such as reporting only a common subset of the capabilities.
Note
The codec capabilities returned affect thesetCodecPreferences() algorithm and what inputs it throwsInvalidModificationError on, and should also be consistent with information revealed bycreateOffer() andcreateAnswer() about codecs negotiated for sending, to ensure any privacy mitigations are effective.
setParameters
ThesetParameters method updates howtrack is encoded and transmitted to a remote peer.
When thesetParameters method is called, the user agentMUST run the following steps:
Any parameter inparameters is marked as aRead-only parameter (such as RID) and has a value that is different from the corresponding parameter value insender.[[LastReturnedParameters]]. Note that this also applies totransactionId.
Candidate Addition 49:Add codec to RTCRtpEncodingParameters (PR #2985)
Anyencoding in encodingscontains a codec not found inchoosableCodecs, using thecodec dictionary match algorithm withignoreLevels set totrue.
Verify that each encoding inencodings has amaxFramerate member whose value is greater than or equal to 0.0. If one of themaxFramerate values does not meet this requirement, return a promiserejected with a newlycreatedRangeError.
Candidate Addition 49:Add codec to RTCRtpEncodingParameters (PR #2985)
If the user agent does not support setting the codec for any encoding or mixing different codec values on the different encodings, return a promiserejected with a newlycreatedOperationError.
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 theRTCRtpSendParameters dictionary are designed to not enable this, so attributes likecname that cannot be changed are read-only. Other things, like bitrate, are controlled using limits such asmaxBitrate, where the user agent needs to ensure it does not exceed the maximum bitrate specified bymaxBitrate, 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 associatedRTCPeerConnection.rtcp.reducedSize is set totrue if reduced-size RTCP has been negotiated for sending, andfalse otherwise.
Ifsending istrue, andwithTrack isnull, have the sender stop sending.
Ifsending istrue, andwithTrack is notnull, determine ifwithTrack can be sent immediately by the sender without violating the sender's already-negotiated envelope, and if it cannot, then:
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 theMediaStreams to be associated with this sender's track.
When thesetStreams method is invoked, the user agentMUST run the following steps:
Letsender be theRTCRtpSender object on which this method was invoked.
Letconnection be theRTCPeerConnection object on which this method was invoked.
A sequence containing the media codecs that anRTCRtpSender 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 incodecs with amimeType attribute indicating retransmission viaaudio/rtx orvideo/rtx, and ansdpFmtpLine attribute (providing the "apt" and "rtx-time" parameters).Read-only parameter.
A unique identifier for the last set of parameters applied. Ensures thatsetParameters can only be called based on a previousgetParameters, and that there are no intervening changes.Read-only parameter.
Indicates that this encoding is actively being sent. Setting it tofalse causes this encoding to no longer be sent. Setting it totrue causes this encoding to be sent. Since setting the value tofalse does not cause the SSRC to be removed, an RTCP BYE is not sent.
Candidate Addition 49:Add codec to RTCRtpEncodingParameters (PR #2985)
codec of typeRTCRtpCodec
Optional value selecting which codec is used for this encoding's RTP stream. If absent, the user agent can choose to use any codec negotiated for sending.
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 themaxBitrate 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 ofmaxBitrate 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.
maxFramerate of typedouble
This member can only be present if the sender'skind is"video". When present, indicates the maximum frame rate that can be used to send this encoding, in frames per second. Theuser agent is free to allocate bandwidth between the encodings, as long as themaxFramerate value is not exceeded.
If changed withsetParameters(), the new frame rate takes effect after the current picture is completed; setting the max frame rate to zero thus has the effect of freezing the video on the next frame.
scaleResolutionDownBy of typedouble
This member is only present if the sender'skind 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 in reverse order by a factor of two, to produce an 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).
TheRTCRtpHeaderExtensionParameters dictionary enables an application to determine whether a header extension is configured for use within anRTCRtpSender orRTCRtpReceiver. For anRTCRtpTransceivertransceiver, an application can determine the "direction" parameter (defined in Section 5 of [RFC5285]) of a header extension as follows without having to parse SDP:
TheRTCRtpCodec dictionary provides information about codec objects.
mimeType of typeDOMString, required
The codec MIME media type/subtype. Valid media types and subtypes are listed in [IANA-RTP-2].
clockRate of typeunsigned long, required
The codec clock rate expressed in Hertz.
channels of typeunsigned short
If present, indicates the maximum number of channels (mono=1, stereo=2).
sdpFmtpLine of typeDOMString
The "format specific parameters" field from thea=fmtp line in the SDP corresponding to the codec, if one exists, as defined by[RFC9429] (section 5.8.).
Supported media codecs as well as entries for RTX, RED and FEC mechanisms. Only combinations that would utilize distinct payload types in a generated SDP offer are to be provided. For example:
Two H.264/AVC codecs, one for each of two supported packetization-mode values.
Two CN codecs with different clock rates.
ThereMUST only be a single entry incodecs for retransmission via RTX, withsdpFmtpLine not present.
Lettrack be a newMediaStreamTrack object [GETUSERMEDIA]. The source oftrack is aremote source provided byreceiver. Note that thetrack.id is generated by theuser agent and does not map to any track IDs on the remote side.
Initializetrack.kind tokind.
Initializetrack.label to the result of concatenating the string"remote " withkind.
Initializetrack.readyState tolive.
Initializetrack.muted totrue. See theMediaStreamTrack section about how themuted attribute reflects if aMediaStreamTrack is receiving media data or not.
Letreceiver have a[[ReceiverTrack]] internal slot initialized totrack.
Letreceiver have a[[ReceiverTransport]] internal slot initialized tonull.
Letreceiver have a[[LastStableStateReceiverTransport]] internal slot initialized tonull.
Letreceiver have an[[AssociatedRemoteMediaStreams]] internal slot, representing a list ofMediaStream objects that theMediaStreamTrack object of this receiver is associated with, and initialized to an empty list.
Letreceiver have a[[LastStableStateAssociatedRemoteMediaStreams]] internal slot and initialize it to an empty list.
Letreceiver have a[[ReceiveCodecs]] internal slot, representing a list ofRTCRtpCodecParameters dictionaries, and initialized to an empty list.
Letreceiver have a[[LastStableStateReceiveCodecs]] internal slot and initialize it to an empty list.
Letreceiver have a[[JitterBufferTarget]] internal slot initialized tonull.
Thetrack attribute is the track that is associated with thisRTCRtpReceiver objectreceiver.
Note thattrack.stop() is final, although clones are not affected. Sincereceiver.track.stop() does not implicitly stopreceiver, Receiver Reports continue to be sent. On getting, the attributeMUST return the value of the[[ReceiverTrack]] slot.
Thetransport attribute is the transport over which media for the receiver'strack is received in the form of RTP packets. Prior to construction of theRTCDtlsTransport object, thetransport attribute will benull. When bundling is used, multipleRTCRtpReceiver objects will share onetransport and will all receive RTP and RTCP over the same transport.
This attribute allows the application to specify a target duration of time in milliseconds of media for theRTCRtpReceiver's jitter buffer to hold. This influences the amount of buffering done by theuser agent, which in turn affects retransmissions and packet loss recovery. Altering the target value allows applications to control the tradeoff between playout delay and the risk of running out of audio or video frames due to network jitter.
Theuser agentMUST have aminimum allowed target and amaximum allowed target reflecting what theuser agent is able or willing to provide based on network conditions and memory constraints, which can change at any time.
Note
This is a target value. The resulting change in delay can be gradually observed over time. The receiver's average jitter buffer delay can be measured as the deltajitterBufferDelay divided by the deltajitterBufferEmittedCount.
An average delay is expected even if DTX is used. For example, if DTX is used and packets start flowing after silence, larger targets can influence theuser agent to buffer these packets rather than playing them out.
On getting, this attributeMUST return the value of the[[JitterBufferTarget]] internal slot.
On setting, theuser agentMUST run the following steps:
Letreceiver be theRTCRtpReceiver object on which the setter is invoked.
Lettarget be the argument to the setter.
Iftarget is negative or larger than 4000 milliseconds, thenthrow aRangeError.
When the underlying system is applying a jitter buffer target, it will continuously make sure that the actual jitter buffer target is clamped within theminimum allowed target andmaximum allowed target.
Note
If theuser agent ends up using a target different from the requested one (e.g. due to network conditions or physical memory constraints), this is not reflected in the[[JitterBufferTarget]] internal slot.
Modifying the jitter buffer target of the underlying systemSHOULD affect the internal audio or video buffering gradually in order not to hurt user experience. Audio samples or video framesSHOULD be accelerated or decelerated before playout, similarly to how it is done for audio/video synchronization or in response to congestion control.
The acceleration or deceleration rate may vary depending on network conditions or the type of audio received (e.g. speech or background noise). ItMAY take several seconds to achieve 1 second of buffering butSHOULD not take more than 30 seconds assuming packets are being received. The speedMAY be different for audio and video.
The staticRTCRtpReceiver.getCapabilities() method provides a way to discover the types of capabilities the user agent supports for receiving media of the given kind, without reserving any resources, ports, or other state.
When thegetCapabilities method is called, the user agentMUST run the following steps:
Thelist of implemented receive codecs, givenkind, is animplementation-defined list ofRTCRtpCodec dictionaries representing the most optimistic view of the codecs the user agent supports for receiving media of the givenkind (video or audio).
Thelist of implemented header extensions for receiving, givenkind, is animplementation-defined list ofRTCRtpHeaderExtensionCapability dictionaries representing an optimistic view of the header extensions the user agent supports for receiving media of the givenkind (video or audio).
These capabilities provide generally persistent cross-origin information on the device and thus increases the fingerprinting surface of the application. In privacy-sensitive contexts, user agentsMAY consider mitigations such as reporting only a common subset of the capabilities.
Note
The codec capabilities returned affect thesetCodecPreferences() algorithm and what inputs it throwsInvalidModificationError on, and should also be consistent with information revealed bycreateOffer() andcreateAnswer() 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 fromgetParameters. But if the remote endpoint only answers with two, the absent codec will no longer be returned bygetParameters as the receiver no longer needs to be prepared to receive it.
rtcp.reducedSize is set totrue if the receiver is currently prepared to receive reduced-size RTCP packets, andfalse otherwise.rtcp.cname is left out.
TheRTCRtpContributingSource andRTCRtpSynchronizationSource 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 theRTCRtpReceiver'sMediaStreamTrack, the user agentMUST queue a task to update the relevant information for theRTCRtpContributingSource andRTCRtpSynchronizationSource dictionaries based on the content of those packets. The information relevant to theRTCRtpSynchronizationSource dictionary corresponding to the SSRC identifier, is updated each time, and if an RTP packet contains CSRC identifiers, then the information relevant to theRTCRtpContributingSource dictionaries corresponding to those CSRC identifiers is also updated. The user agentMUST process RTP packets in order of ascending RTP timestamps. The user agentMUST keep information from RTP packets delivered to theRTCRtpReceiver'sMediaStreamTrack in the previous 10 seconds.
As stated in theconformance 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 returnedRTCRtpSynchronizationSource andRTCRtpContributingSource dictionaries for a particularRTCRtpReceiver contain information from a single point in the RTP stream.
The CSRC or SSRC identifier of the contributing or synchronization source.
audioLevel of typedouble
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, thisMUST be converted from the level value defined in [RFC6465] if the RFC 6465 header extension is present, otherwise this memberMUST be absent.
For SSRCs, thisMUST 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 valueSHOULD 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 typeunsigned long, required
The RTP timestamp, as defined in [RFC3550] Section 5.1, of the media played out attimestamp.
ARTCRtpTransceiver may become associated with a new pending description in RFC9429 while still being disassociated with the current description. This may happen incheck if negotiation is needed.
Lettransceiver have a[[Sender]] internal slot, initialized tosender.
Lettransceiver have a[[Receiver]] internal slot, initialized toreceiver.
Lettransceiver have a[[Stopping]] internal slot, initialized tofalse.
Lettransceiver have a[[Stopped]] internal slot, initialized tofalse.
Lettransceiver have a[[Direction]] internal slot, initialized todirection.
Lettransceiver have a[[Receptive]] internal slot, initialized tofalse.
Lettransceiver have a[[CurrentDirection]] internal slot, initialized tonull.
Lettransceiver have a[[FiredDirection]] internal slot, initialized tonull.
Lettransceiver have a[[PreferredCodecs]] internal slot, initialized to an empty list.
Lettransceiver have a[[JsepMid]] internal slot, initialized tonull. This is the "RtpTransceiver mid property" defined in[RFC9429] (section 5.2.1. andsection 5.3.1.), and is only modified there.
Lettransceiver have a[[Mid]] internal slot, initialized tonull.
Themid attribute is themedia stream "identification-tag" negotiated and present in the local and remote descriptions. On getting, the attributeMUST return the value of the[[Mid]] slot.
Thesender attribute exposes theRTCRtpSender corresponding to the RTP media that may be sent with mid =[[Mid]]. On getting, the attributeMUST return the value of the[[Sender]] slot.
Thereceiver attribute is theRTCRtpReceiver corresponding to the RTP media that may be received with mid =[[Mid]]. On getting the attributeMUST return the value of the[[Receiver]] slot.
As defined in[RFC9429] (section 4.2.5.), thecurrentDirection attribute indicates the current direction negotiated for this transceiver. The value ofcurrentDirection is independent of the value ofRTCRtpEncodingParameters.active since one cannot be deduced from the other. If this transceiver has never been represented in an offer/answer exchange, the value isnull. If the transceiver isstopped, the value is "stopped".
On getting, the user agentMUST run the following steps:
Lettransceiver be theRTCRtpTransceiver object on which the getter is invoked.
Astopping transceiver will cause future calls tocreateOffer to generate a zero port in themedia description for the corresponding transceiver, as defined in[RFC9429] (section 4.2.1.) (The user agentMUST treat astopping transceiver asstopped for the purposes of RFC9429 only in this case). However, to avoid problems with [RFC8843], a transceiver that isstopping, but notstopped, will not affectcreateAnswer.
The transceiver will remain in thestopping state, unless it becomesstopped bysetRemoteDescription processing a rejected m-line in a remote offer or answer.
Note
A transceiver that isstopping but notstopped will always need negotiation. In practice, this means that callingstop() on a transceiver will cause the transceiver to becomestopped eventually, provided negotiation is allowed to complete on both ends.
When thestop method is invoked, the user agentMUST run the following steps:
Lettransceiver be theRTCRtpTransceiver object on which the method is invoked.
Letconnection be theRTCPeerConnection object associated withtransceiver.
Candidate Addition 51:setCodecPreferences supports both send and receive codecs (filtered by direction) (PR #3018)
ThesetCodecPreferences method overrides the default codec preferences used by theuser agent as input to negotiation.WhenWhengenerating a session descriptionusing eitherusing eithercreateOffer orcreateAnswer, theuser agentMUSTuseMUST filtertheindicated codecspreferred codecs ondirection and,if this resultsinthe ordera non-empty list, itMUST use thespecifiedcodecsinthethe order of thecodecsargument, for the mediasectionsectioncorresponding tothisthisRTCRtpTransceiver.
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 listby listing all codecs exceptforsendingthe ones to disable.
Note
If the m= section is used for receiving, the order of the codecs in the SDP (both the offer and the answer) tells the remote endpoint which codec the local endpoint prefers to receive. Even if the m= section is not used for receiving, an answerer that does not have any codec preferences of their own defaults to using the same order for its SDP answer.
Note
AnRTCRtpSender defaults to sending what the remote endpoint indicated that it prefers to receive, but the application can change which codec to send amongst negotiatedcodecs by callingsetParameters and specifying whichcodec to send. AnRTCRtpReceiver is prepared to receive any negotiated codec.
Codec preferences remain in effect for all calls tocreateOffer andcreateAnswer that include thisRTCRtpTransceiver until this method is called again. Settingcodecs to an emptysequence resets codec preferences to anysequence, or one that becomes empty afterdirection filtering, results indefaultvaluecodec preferences.
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 [RFC8829RFC9429]. 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 tocreateAnswerSHOULD use only the common subset of the codec preferences and the codecs that appear in the offer. For example, if codec preferences are "C, B, A", but only codecs "A, B" were offered, the answer should only contain codecs "B, A". However,[RFC8829] (section 5.3.1.) allows adding codecs that were not in the offer, so implementations can behave differently.
Lettransceiver be theRTCRtpTransceiver object this method was invoked on.
Letcodecs be the first argument.
Ifcodecs is an empty list, settransceiver.[[PreferredCodecs]] tocodecs and abort these steps.
Remove any duplicate values incodecs. 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.
Remove anyduplicate values incodecs, ensuring that the first occurrence of each value remains in place.
Ifcodecs only contains entries for RTX, RED, FEC or Comfort Noise or is an empty set, throwInvalidModificationError. This ensures that we always have something to offer, regardless oftransceiver.direction.
Thecodec dictionary match algorithm given twoRTCRtpCodec dictionariesfirst andsecond, and anignoreLevels boolean defaulting tofalse if not specified, is as follows:
If either offirst.sdpFmtpLine andsecond.sdpFmtpLine is not in key-value format, return the result of performing an equals comparison betweenfirst.sdpFmtpLine andsecond.sdpFmtpLine.
LetfirstMediaFormat be a key-value map of the media formats constructed fromfirst.sdpFmtpLine andsecondMediaFormat be a key-value map of the media formats constructed fromsecond.sdpFmtpLine.
Note
Which FMTP parameters make up the media format is codec specific. In some cases a parameter can be omitted and still be inferred, in which case it is also a part of the media format of that codec.
IffirstMediaFormat is not equal tosecondMediaFormat, returnfalse.
Candidate Correction 52:Two codecs are considered the same even if level-id is not (PR #3023)
IfignoreLevels isfalse and the highest complying bitstream levels inferred fromfirst.sdpFmtpLine andsecond.sdpFmtpLine are different, returnfalse.
Note
Even ifignoreLevels istrue, some codecs (such as H.264) include levels in the media format, so that ignoring the level requires codec-specific parsing.
Returntrue.
Note
If set, the offerer's receive 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.
AnRTCRtpSender'ssimulcast envelope is established in the first successful negotiation that involves it sending simulcast instead of unicast, and includes the maximum number of simulcast streams that can be sent, as well as the ordering of itsencodings. Thissimulcast envelope may be narrowed (reducing the number of layers) in subsequent renegotiation, but cannot be reexpanded. Characteristics of individual simulcast streams can be modified using thesetParameters method, but thesimulcast envelope itself cannot be changed by that method.
One way to configure simulcast is with thesendEncodings option toaddTransceiver(). While theaddTrack() method lacks thesendEncodings argument necessary to configure simulcast, senders can be promoted to simulcast when the user agent is the answerer. Upon calling thesetRemoteDescription method with a remote offer to receive simulcast, aproposed envelope is configured on anRTCRtpSender to contain the layers described in the specified session description. As long as this description isn't rolled back, theproposed envelope becomes theRTCRtpSender'ssimulcast envelope when negotiation completes. As above, thissimulcast envelope may be narrowed in subsequent renegotiation, but not reexpanded.
Candidate Correction 12:Mark RTP Pause/Resume as not supported (PR #2755)
WhilesetParameters cannot modify thesimulcastsimulcastenvelope,, it is still possible to control the number of streams that are sent and the characteristics of those streams. UsingsetParameters, simulcast streams can be made inactive by setting theactive member tofalse, or can be reactivated by setting theactive member totrue. [RFC7728] (RTP Pause/Resume) is not supported, nor is signaling of pause/resume via SDP Offer/Answer.UsingsetParameters, stream characteristics can be changed by modifying attributes such asmaxBitrate.
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 samemaxBitrate, 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[RFC9429] (section 3.7.), an offer from a user-agent will only contain a "send" description and no "recv" description on thea=simulcast line. Alternatives and restrictions (described in [RFC8853]) are not supported.
This specification does not define how to configure reception of multiple RTP encodings usingcreateOffer,createAnswer oraddTransceiver. However whensetRemoteDescription is called with a corresponding remote description that is able to send multiple RTP encodings as defined in [RFC9429], and the browser supports receiving multiple RTP encodings, theRTCRtpReceiver may receive multiple RTP encodings and the parameters retrieved via the transceiver'sreceiver.getParameters() will reflect the encodings negotiated.
Note
AnRTCRtpReceiver 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, theRTCRtpReceiver 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. AnRTCRtpReceiver 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:
// Example of 3-layer spatial simulcast with all but the lowest resolution layer disabledvar encodings = [ {rid:'q',active:true,scaleResolutionDownBy:4.0} {rid:'h',active:false,scaleResolutionDownBy:2.0}, {rid:'f',active:false},];
5.4.2 "Hold" functionality
This section is non-normative.
Together, thedirection attribute and thereplaceTrack method enable developers to implement "hold" scenarios.
To send music to a peer and cease rendering received audio (music-on-hold):
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); }}
asyncfunctionhandleSendonlyOffer() {try {// Apply the sendonly offer first,// to ensure the receiver is ready for ICE candidates.await pc.setRemoteDescription(sendonlyOffer);// Stop sending audioawait audio.sender.replaceTrack(null);// Align our direction to avoid further negotiation audio.direction ='recvonly';// Call createAnswer and send a recvonly answerawaitdoAnswer(); }catch (err) {// handle signaling error }}
To stop sending music and send audio captured from a microphone, as well to render received audio:
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 answerawaitdoAnswer(); }catch (err) {// handle signaling error }}
5.5RTCDtlsTransport Interface
TheRTCDtlsTransport 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 byRTCRtpSender andRTCRtpReceiver 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 theRTCDtlsTransport interface allows access to information about the underlying transport and the security added.RTCDtlsTransport objects are constructed as a result of calls tosetLocalDescription() andsetRemoteDescription(). EachRTCDtlsTransport object represents the DTLS transport layer for the RTP or RTCPcomponent of a specificRTCRtpTransceiver, or a group ofRTCRtpTransceivers if such a group has been negotiated via [RFC8843].
Note
A new DTLS association for an existingRTCRtpTransceiver will be represented by an existingRTCDtlsTransport object, whosestate will be updated accordingly, as opposed to being represented by a new object.
AnRTCDtlsTransport 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 agentMUST queue a task that runs the following steps:
Lettransport be theRTCDtlsTransport object to receive the state update and error notification.
If the state oftransport is already "failed", abort these steps.
When the underlying DTLS transport needs to update the state of the correspondingRTCDtlsTransport object for any other reason, the user agentMUST queue a task that runs the following steps:
Lettransport be theRTCDtlsTransport object to receive the state update.
IfnewState isconnected then letnewRemoteCertificates be the certificate chain in use by the remote side, with each certificate encoded in binary Distinguished Encoding Rules (DER) [X690], and settransport.[[RemoteCertificates]] tonewRemoteCertificates.
TheiceTransport attribute is the underlying transport that is used to send and receive packets. The underlying transport may not be shared between multiple activeRTCDtlsTransport objects.
One of the the hash function algorithms defined in the 'Hash function Textual Names' registry [IANA-HASH-FUNCTION].
value of typeDOMString
The value of the certificate fingerprint in lowercase hex string as expressed utilizing the syntax of 'fingerprint' in [RFC4572] Section 5.
5.6RTCIceTransport Interface
TheRTCIceTransport 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 tosetLocalDescription() andsetRemoteDescription(). The underlying ICE state is managed by theICE agent; as such, the state of anRTCIceTransport changes when theICE Agent provides indications to the user agent as described below. EachRTCIceTransport object represents the ICE transport layer for the RTP or RTCPcomponent of a specificRTCRtpTransceiver, or a group ofRTCRtpTransceivers if such a group has been negotiated via [RFC8843].
Note
An ICE restart for an existingRTCRtpTransceiver will be represented by an existingRTCIceTransport object, whosestate will be updated accordingly, as opposed to being represented by a new object.
Candidate Correction 24:Queue two tasks upon finishing ICE gathering, and fire gatheringstatechange & icegatheringstatechange in same task (PR #2894)
When theICE Agent indicates that it began gathering ageneration of candidates for anRTCIceTransporttransport associated with anRTCPeerConnectionconnection, the user agentMUST queue a task that runs the following steps:
When theICE Agent is finished gathering ageneration of candidates for anRTCIceTransporttransport associated with anRTCPeerConnectionconnection, and those candidates have been surfaced to the application, the user agentMUST queue a taskthat runsto runthefollowingfollowingsteps:
When theICE Agent has queued the above task, and no othergenerations of candidates is being gathered, the user agentMUST also queue a second task to run the following steps:
Note
Othergenerations of candidates might still be gathering if an ICE restart was initiated while the ICE agent is still gathering the previousgeneration of candidates.
Ifconnection.[[IsClosed]] istrue, abort these steps.
The null candidate event is fired to ensure legacy compatibility. New code should monitor the gathering state ofRTCIceTransport and/orRTCPeerConnection.
When theICE Agent indicates that a new ICE candidate is available for anRTCIceTransport, either by taking one from theICE candidate pool or gathering it from scratch, the user agentMUST queue a task that runs the following steps:
When theICE 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.
Torelease early candidates of aconnection, run the following steps:
TheRTCIceTransportState of anRTCIceTransport 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 andRTCIceTransportState are related and are handled in the same task.
When theICE Agent indicates that anRTCIceTransport has changed either the selected candidate pair, theRTCIceTransportState or both, the user agentMUST queue a task that runs the steps tochange the selected candidate pair and state:
Iftransport's selected candidate pair was changed, run the following steps:
LetnewCandidatePair be the result ofcreating an RTCIceCandidatePair withlocal andremote, representing the local and remote candidates of the indicated pair if one is selected, andnull otherwise.
Thecomponent attributeMUST return the ICE component of the transport. When RTCP mux is used, a singleRTCIceTransport transports both RTP and RTCP andcomponent is set to "rtp".
TheRTCIceTransport was just created, and has not started gathering candidates yet.
gathering
TheRTCIceTransport is in the process of gathering candidates.
complete
TheRTCIceTransport 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.
TheRTCIceTransport has shut down and is no longer responding to STUN requests.
failed
TheRTCIceTransport has finished gathering, received an indication that there are no more remote candidates, finished checking all candidate pairs, and all pairs have either failed connectivity checks or lost consent, and either zero local candidates were gathered or the PAC timer has expired [RFC8863]. This is a terminal state until ICE is restarted. Since an ICE restart may cause connectivity to resume, entering the "failed" state does not cause DTLS transports, SCTP associations or the data channels that run over them to close, or tracks to mute.
disconnected
TheICE Agent has determined that connectivity is currently lost for thisRTCIceTransport. 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, theRTCIceTransport 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.
new
TheRTCIceTransport is gathering candidates and/or waiting for remote candidates to be supplied, and has not yet started checking.
checking
TheRTCIceTransport has received at least one remote candidate (by means ofaddIceCandidate() or discovered as a peer-reflexive candidate when receiving a STUN binding request) 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.
completed
TheRTCIceTransport 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".
connected
TheRTCIceTransport 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).
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 callingaddIceCandidate with a candidate value whosecandidate property is set to an empty string or bycanTrickleIceCandidates being set tofalse.
The ICE Transport is used for RTP (or RTCP multiplexing), as defined in [RFC5245], Section 4.1.1.1. Protocols multiplexed with RTP (e.g. data channel) share its component ID. This represents thecomponent-id value1 when encoded incandidate-attribute.
rtcp
The ICE Transport is used for RTCP as defined by [RFC5245], Section 4.1.1.1. This represents thecomponent-id value2 when encoded incandidate-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 ofWeb Sockets.
6.1 RTCPeerConnection Interface Extensions
The Peer-to-peer data API extends theRTCPeerConnection 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 attributeMUST return theRTCSctpTransport object stored in the[[SctpTransport]] internal slot.
ondatachannel of typeEventHandler
The event type of this event handler isdatachannel.
Methods
createDataChannel
Creates a newRTCDataChannel object with the given label. TheRTCDataChannelInit dictionary can be used to configure properties of the underlying channel such as data reliability.
When thecreateDataChannel method is invoked, the user agentMUST run the following steps.
Letconnection be theRTCPeerConnection object on which the method is invoked.
This means theid 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 [RFC8832].
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 valueMUST 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 anunsigned short,throw aTypeError.
LetremoteMaxMessageSize be the value of themax-message-size SDP attribute read from the remote description, as described in [RFC8841] (section 6), or 65536 if the attribute is missing.
LetcanSendSize 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 bothremoteMaxMessageSize andcanSendSize are 0, set[[MaxMessageSize]] to the positive Infinity value.
Else, if eitherremoteMaxMessageSize orcanSendSize is 0, set[[MaxMessageSize]] to the larger of the two.
Else, set[[MaxMessageSize]] to the smaller ofremoteMaxMessageSize orcanSendSize.
6.1.1.3 Connected procedure
Once anSCTP transport is connected, meaning the SCTP association of anRTCSctpTransport has been established, the user agentMUSTqueue a task that runs the following steps:
The current state of the SCTP transport. On getting, this attributeMUST return the value of the[[SctpTransportState]] slot.
maxMessageSize of typeunrestricted double, readonly
The maximum size of data that can be passed toRTCDataChannel'ssend() method. The attributeMUST, on getting, return the value of the[[MaxMessageSize]] slot.
maxChannels of typeunsigned short , readonly, nullable
The maximum amount ofRTCDataChannel's that can be used simultaneously. The attributeMUST, on getting, return the value of the[[MaxChannels]] slot.
Note
This attribute's value will benull until the SCTP transport goes into the "connected" state.
onstatechange of typeEventHandler
The event type of this event handler isstatechange.
TheRTCSctpTransport is in the process of negotiating an association. This is the initial state of the [[SctpTransportState]] slot when anRTCSctpTransport 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.
6.2RTCDataChannel
TheRTCDataChannel interface represents a bi-directional data channel between two peers. AnRTCDataChannel is created via a factory method on anRTCPeerConnection object. The messages sent between the browsers are described in [RFC8831] and [RFC8832].
There are two ways to establish a connection withRTCDataChannel. The first way is to simply create anRTCDataChannel at one of the peers with thenegotiatedRTCDataChannelInit dictionary member unset or set to its default value false. This will announce the new channel in-band and trigger anRTCDataChannelEvent with the correspondingRTCDataChannel object at the other peer. The second way is to let the application negotiate theRTCDataChannel. To do this, create anRTCDataChannel object with thenegotiatedRTCDataChannelInit dictionary member set to true, and signal out-of-band (e.g. via a web server) to the other side that itSHOULD create a correspondingRTCDataChannel with thenegotiatedRTCDataChannelInit dictionary member set to true and the sameid. This will connect the two separately createdRTCDataChannel objects. The second way makes it possible to create channels with asymmetric properties and to create channels in a declarative way by specifying matchingids.
EachRTCDataChannel has an associatedunderlying data transport that is used to transport actual data to the other peer. In the case of SCTP data channels utilizing anRTCSctpTransport (which represents the state of the SCTP association), the underlying data transport is the SCTP stream pair. The transport properties of theunderlying data transport, such as in order delivery settings and reliability mode, are configured by the peer as the channel is created. The properties of a channel cannot change after the channel has been created. The actual wire protocol between the peers is specified by the WebRTC DataChannel Protocol specification [RFC8831].
AnRTCDataChannel 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.
When anunderlying data transport is to be announced (the other peer created a channel withnegotiated unset or set to false), the user agent of the peer that did not initiate the creation processMUST queue a task to run the following steps:
Letconfiguration be an information bundle received from the other peer as a part of the process to establish theunderlying data transport described by the WebRTC DataChannel Protocol specification [RFC8832].
Candidate Correction 38:Prevent GC of non-closed RTCDataChannels (PR #2902)
6.2.4 Closing procedure
6.2.4 Closing procedure
AnRTCDataChannel object'sunderlying data transport may be torn down in a non-abrupt manner by running theclosing procedure. When that happens the user agentMUST queue a task to run the following steps:
The above steps do not need to transfer[[BufferedAmount]] as its value will always be equal to0. The reason is anRTCDataChannel can be transferred only if itssend() algorithm was not called prior the transfer.
In some cases, the user agent may beunable to create anRTCDataChannel 'sunderlying data transport. For example, the data channel'sid may be outside the range negotiated by the [RFC8831] implementations in the SCTP handshake. When the user agent determines that anRTCDataChannel'sunderlying data transport cannot be created, the user agentMUST queue a task to run the following steps:
When anRTCDataChannel message has been received via theunderlying data transport with typetype and datarawData, the user agentMUST queue a task to run the following steps:
Letchannel be theRTCDataChannel object for which the user agent has received a message.
Letconnection be theRTCPeerConnection object associated withchannel.
Ifchannel.[[ReadyState]] is not "open", abort these steps and discardrawData.
Execute the sub step by switching ontype andchannel.binaryType:
Iftype indicates thatrawData is astring:
Letdata be aDOMString that represents the result of decodingrawData as UTF-8.
Iftype indicates thatrawData is binary andbinaryType is"blob":
Letdata be a newBlob object containingrawData as its raw data source.
Iftype indicates thatrawData is binary andbinaryType is"arraybuffer":
Letdata be a newArrayBuffer object containingrawData as its raw data source.
Thelabel attribute represents a label that can be used to distinguish thisRTCDataChannel object from otherRTCDataChannel objects. Scripts are allowed to create multipleRTCDataChannel objects with the same label. On getting, the attributeMUST return the value of the[[DataChannelLabel]] slot.
ordered of typeboolean, readonly
Theordered attribute returns true if theRTCDataChannel is ordered, and false if out of order delivery is allowed. On getting, the attributeMUST return the value of the[[Ordered]] slot.
maxPacketLifeTime of typeunsigned short, readonly, nullable
ThemaxPacketLifeTime attribute returns the length of the time window (in milliseconds) during which transmissions and retransmissions may occur in unreliable mode. On getting, the attributeMUST return the value of the[[MaxPacketLifeTime]] slot.
maxRetransmits of typeunsigned short, readonly, nullable
ThemaxRetransmits attribute returns the maximum number of retransmissions that are attempted in unreliable mode. On getting, the attributeMUST return the value of the[[MaxRetransmits]] slot.
Thenegotiated attribute returns true if thisRTCDataChannel was negotiated by the application, or false otherwise. On getting, the attributeMUST return the value of the[[Negotiated]] slot.
id of typeunsigned short, readonly, nullable
Theid attribute returns the ID for thisRTCDataChannel. The value is initially null, which is what will be returned if the ID was not provided at channel creation time, and the DTLS role of the SCTP transport has not yet been negotiated. Otherwise, it will return the ID that was either selected by the script or generated by the user agent according to [RFC8832]. After the ID is set to a non-null value, it will not change. On getting, the attributeMUST return the value of the[[DataChannelId]] slot.
ThebufferedAmount attributeMUST, 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 usingsend(). Even though the data transmission can occurin parallel, the returned valueMUST 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 thesend() method as long as the[[ReadyState]] slot is "open"; however, the slot does not reset to zero once the channel closes. When theunderlying data transport sends data from its queue, the user agentMUST queue a task that reduces[[BufferedAmount]] with the number of bytes that was sent.
The event type of this event handler isRTCErrorEvent.errorDetail contains "sctp-failure",sctpCauseCode contains the SCTP Cause Code value, andmessage contains the SCTP Cause-Specific-Information, possibly with additional text.
Thesend() method is overloaded to handle different data argument types. When any version of the method is called, the user agentMUSTrun the following steps:
Letchannel be theRTCDataChannel object on which data is to be sent.
Letdata be the raw data represented by theBlob object.
Note
Although the actual retrieval ofdata from aBlob object can happen asynchronously, the user agent will make sure to queue the data on thechannel'sunderlying data transport in the same order as the send method is called. The byte size ofdata needs to be known synchronously.
The actual transmission of data occursin parallel. If sending data leads to an SCTP-level error, the application will be notified asynchronously throughonerror.
Increase the value of the[[BufferedAmount]] slot by the byte size ofdata.
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 typeunsigned 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 typeunsigned 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 typeUSVString, defaulting to""
Subprotocol name used for this channel.
negotiated of typeboolean, defaulting tofalse
The default value of false tells the user agent to announce the channel in-band and instruct the other peer to dispatch a correspondingRTCDataChannel object. If set to true, it is up to the application to negotiate the channel and create anRTCDataChannel object with the sameid 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.
This section describes an interface onRTCRtpSender to send DTMF (phone keypad) values across anRTCPeerConnection. Details of how DTMF is sent to the other peer are described in [RFC7874].
7.1 RTCRtpSender Interface Extensions
The Peer-to-peer DTMF API extends theRTCRtpSender interface as described below.
On getting, thedtmf attribute returns the value of the[[Dtmf]] internal slot, which represents aRTCDTMFSender which can be used to send DTMF, ornull if unset. The[[Dtmf]] internal slot is set when the kind of anRTCRtpSender's[[SenderTrack]] is"audio".
7.2RTCDTMFSender
Tocreate an RTCDTMFSender, the user agentMUST run the following steps:
ThetoneBuffer attributeMUST return a list of the tones remaining to be played out. For the syntax, content, and interpretation of this list, seeinsertDTMF.
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 dMUST 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 consideredunrecognized.
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.
TheinterToneGap 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 browserMAY increase theduration andinterToneGap times to cause the times that DTMF start and stop to align with the boundaries of RTP packets but itMUST not increase either of them by more than the duration of a single RTP audio packet.
When theinsertDTMF() method is invoked, the user agentMUST run the following steps:
If the value ofduration is less than 40 ms, setdtmf.[[Duration]] to 40 ms.
If the value ofduration parameter is greater than 6000 ms, setdtmf.[[Duration]] to 6000 ms.
If the value ofinterToneGap is less than 30 ms, setdtmf.[[InterToneGap]] to 30 ms.
If the value ofinterToneGap is greater than 6000 ms, setdtmf.[[InterToneGap]] to 6000 ms.
If [[ToneBuffer]] slot is an empty string, abort these steps.
If a task to run theDTMF playout task steps is scheduled to be run, abort these steps; otherwise queue a task that runs the followingDTMF playout task steps:
Candidate Correction 33:Determine if DTMF can be sent inside queued playout task (PR #2861)
Remove the first character from the[[ToneBuffer]] slot and let that character betone.
Iftone is"," delay sending tones for2000 ms on the associated RTP media stream, and queue a task to be executed in2000 ms from now that runs theDTMF playout task steps.
SinceinsertDTMF replaces the tone buffer, in order to add to the DTMF tones being played, it is necessary to callinsertDTMF with a string containing both the remaining tones (stored in the[[ToneBuffer]] slot) and the new tones appended together. CallinginsertDTMF with an empty tones parameter can be used to cancel all tones queued to play after the currently playing tone.
7.3 canInsertDTMF algorithm
Todetermine if DTMF can be sent for anRTCDTMFSender instancedtmfSender, the user agentMUST run the following steps:
Letsender be theRTCRtpSender associated withdtmfSender.
Thetone attribute contains the character for the tone (including",") that has just begun playout (seeinsertDTMF ). 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.
Thetone attribute contains the character for the tone (including",") that has just begun playout (seeinsertDTMF ). 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 formonitored objects, in the form ofstats objects.
A group of related objects may be referenced by aselector. The selector may, for example, be aMediaStreamTrack. For a track to be a valid selector, itMUST be aMediaStreamTrack that is sent or received by theRTCPeerConnection object on which the stats request was issued. The calling Web application provides the selector to thegetStats() method and the browser emits (in the JavaScript) a set of statistics that are relevant to the selector, according to thestats selection algorithm. Note that that algorithm takes the sender or receiver of a selector.
The statistics returned instats objects are designed in such a way that repeated queries can be linked by theRTCStatsid 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 associatedRTCPeerConnection. This ensures statistics from them are available in the result fromgetStats() even past the associated peer connection beingclosed.
Only a few monitored objects haveshorter 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 theRTCPeerConnection interface as described below.
ThegetStats() method delivers a successful result in the form of anRTCStatsReport object. AnRTCStatsReport object is a map between strings that identify the inspected objects (id attribute inRTCStats instances), and their correspondingRTCStats-derived dictionaries.
AnRTCStatsReport may be composed of severalRTCStats-derived dictionaries, each reporting stats for one underlying object that the implementation thinks is relevant for theselector. One achieves the total for theselector by summing over all the stats of a certain type; for instance, if anRTCRtpSender uses multiple SSRCs to carry its track over the network, theRTCStatsReport may contain oneRTCStats-derived dictionary per SSRC (which can be distinguished by the value of thessrc stats attribute).
Use these to retrieve the various dictionaries descended fromRTCStats that this stats report is composed of. The set of supported property names [WEBIDL] is defined as the ids of all theRTCStats-derived dictionaries that have been generated for this stats report.
8.4RTCStats Dictionary
AnRTCStats dictionary represents thestats object constructed by inspecting a specificmonitored object. TheRTCStats dictionary is a base type that specifies as set of default attributes, such astimestamp andtype. Specific stats are added by extending theRTCStats 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, applicationsMUST 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, ifbytesSent andpacketsSent 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 implementationsMUST return synchronized values for all stats in anRTCStats-derived dictionary.
Thetimestamp, of typeTimestamps are expressed withDOMHighResTimeStamp,associated with this object. The time is relative to the UNIX epoch (Jan 1[HIGHRES-TIME],1970,and are defined asPerformance.timeOriginUTC)+Performance.now()at the time the information is collected.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 anRTCStats-derived dictionary, if applicable.
Thetype attributeMUST be initialized to the name of the most specific type thisRTCStats dictionary represents.
id of typeDOMString
A uniqueid that is associated with the object that was inspected to produce thisRTCStats object. TwoRTCStats objects, extracted from two differentRTCStatsReport objects,MUST have the same id if they were produced by inspecting the same underlying object.
Stats idsMUST 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 forRTCStatsType, 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 implementationMUST support generating statistics of the followingtypes when the corresponding objects exist on aRTCPeerConnection, with the fields that are listed when they are valid for that object in addition to the generic fields defined in theRTCStats dictionary:
An implementationMAY support generating any other statistic defined in [WEBRTC-STATS], andMAY 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 nowof 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); }}
AMediaStreamTrack 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 theMediaStreamTrack object will be described in this section. How the media is transmitted to the peer is described in [RFC8834], [RFC7874], and [RFC8835].
AMediaStreamTrack sent to another peer will appear as one and only oneMediaStreamTrack to the recipient. A peer is defined as a user agent that supports this specification. In addition, the sending side application can indicate whatMediaStream object(s) theMediaStreamTrack is a member of. The correspondingMediaStream object(s) on the receiver side will be created (if not already present) and populated accordingly.
As also described earlier in this document, the objectsRTCRtpSender andRTCRtpReceiver can be used by the application to get more fine grained control over the transmission and reception ofMediaStreamTracks.
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 jointlyMUST be in the sameMediaStreamTrack and the codecsSHOULD be able to encode, or discard, all the channels in the track.
The concepts of an input and output to a givenMediaStreamTrack apply in the case ofMediaStreamTrack objects transmitted over the network as well. AMediaStreamTrack created by anRTCPeerConnection object (as described previously in this document) will take as input the data received from a remote peer. Similarly, aMediaStreamTrack 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 anRTCPeerConnection object.
The concept of duplicatingMediaStream andMediaStreamTrack 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 differentMediaStreamTrack objects into newMediaStream 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 anRTCPeerConnection. Please refer to the original definitions of the objects in the [GETUSERMEDIA] document for general information on usingMediaStream andMediaStreamTrack.
9.2 MediaStream
9.2.1 id
Theid attribute specified inMediaStream returns an id that is unique to this stream, so that streams can be recognized at the remote end of theRTCPeerConnection API.
When aMediaStream is created to represent a stream obtained from a remote peer, theid attribute is initialized from information provided by the remote source.
Note
Theid of aMediaStream 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 usingRTCPeerConnection 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 proceduresadd a track,remove a track andset a track's muted state are specified in [GETUSERMEDIA].
When aMediaStreamTrack track produced by anRTCRtpReceiverreceiver hasended [GETUSERMEDIA] (such as via a call toreceiver.track.stop), the user agentMAY choose to free resources allocated for the incoming stream, by for instance turning off the decoder ofreceiver.
9.3.1 MediaTrackSupportedConstraints, MediaTrackCapabilities, MediaTrackConstraints and MediaTrackSettings
The concept of constraints and constrainable properties, includingMediaTrackConstraints (MediaStreamTrack.getConstraints(),MediaStreamTrack.applyConstraints()), andMediaTrackSettings (MediaStreamTrack.getSettings()) are outlined in [GETUSERMEDIA]. However, the constrainable properties of tracks sourced from a peer connection are different than those sourced bygetUserMedia(); the constraints and settings applicable toMediaStreamTracks sourced from aremote source are defined here. The settings of a remote track represent the latest frame received.
MediaStreamTrack.getCapabilities()MUST always return the empty set andMediaStreamTrack.applyConstraints()MUST always reject withOverconstrainedError on remote tracks for constraints defined here.
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 audioMediaStreamTracks sourced from aremote 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 =newSignalingChannel();// handles JSON.stringify/parseconst constraints = {audio:true,video:true};const configuration = {iceServers: [{urls:'stun:stun.example.org'}]};const pc =newRTCPeerConnection(configuration);// send any ice candidates to the other peerpc.onicecandidate =({candidate}) => signaling.send({candidate});// let the "negotiationneeded" event trigger offer generationpc.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 trackof 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)awaitaddCameraMic(); }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 =newSignalingChannel();// 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 =newRTCPeerConnection(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 =newMediaStream(); } remoteView.srcObject.addTrack(track); }if (isAnswerer) {if (track.kind =='audio') { audio = transceiver; }elseif (track.kind =='video') { video = transceiver; }if (started)awaitaddCameraMicWarmedUp(); } }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)awaitaddCameraMicWarmedUp(); }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;awaitaddCameraMicWarmedUp(); }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 =newSignalingChannel();// handles JSON.stringify/parseconst constraints = {audio:true,video:true};const configuration = {'iceServers': [{'urls':'stun:stun.example.org'}]};let pc;// call start() to initiateasyncfunctionstart() { pc =newRTCPeerConnection(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 anRTCDataChannel object and perform the offer/answer exchange required to connect the channel to the other peer. TheRTCDataChannel is used in the context of a simple chat application using aninput field for user input.
const signaling =newSignalingChannel();// handles JSON.stringify/parseconst configuration = {iceServers: [{urls:'stun:stun.example.org'}]};let pc, channel;// call start() to initiatefunctionstart() { pc =newRTCPeerConnection(configuration);// send any ice candidates to the other peer pc.onicecandidate =({candidate}) => signaling.send({candidate});// let the "negotiationneeded" event trigger offer generation pc.onnegotiationneeded =async () => {try {await pc.setLocalDescription();// send the offer to the other peer signaling.send({description: pc.localDescription}); }catch (err) {console.error(err); } };// create data channel and setup chat using "negotiated" pattern channel = pc.createDataChannel('chat', {negotiated:true,id:0}); channel.onopen =() => input.disabled =false; channel.onmessage =({data}) =>showChatMessage(data); input.onkeydown =({key}) => {if (key !='Enter')return; channel.send(input.value); }}signaling.onmessage =async ({data: {description, candidate}}) => {if (!pc)start();try {if (description) {await pc.setRemoteDescription(description);// if we got an offer, we need to reply with an 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 usinglightKey(key) while the tone is playing (assuming thatlightKey("") will darken all the keys):
constwait = 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 startsawaitwait(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 apolite boolean variable indicating the designated role:
const signaling =newSignalingChannel();// handles JSON.stringify/parseconst constraints = {audio:true,video:true};const configuration = {iceServers: [{urls:'stun:stun.example.org'}]};const pc =newRTCPeerConnection(configuration);// call start() anytime on either end to add camera and microphone to connectionasyncfunctionstart() {try {const stream =await navigator.mediaDevices.getUserMedia(constraints);for (const trackof 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 peerpc.onicecandidate =({candidate}) => signaling.send({candidate});// let the "negotiationneeded" event trigger offer generationpc.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 ofsetLocalDescription (without arguments) andsetRemoteDescription (with implicit rollback) to avoid races with other signaling messages being serviced.
TheignoreOffer variable is needed, because theRTCPeerConnection 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 fireRTCError. This is an extension ofDOMException that carries additional WebRTC-specific information.
TheerrorDetail,sdpLineNumber,sctpCauseCode,receivedAlert andsentAlert members ofRTCErrorInit have the same definitions as the attributes of the same name ofRTCError.
The DTLS negotiation has failed or the connection has been terminated with a fatal error. Themessage contains information relating to the nature of error. If a fatal DTLS alert was received, thereceivedAlert attribute is set to the value of the DTLS alert received. If a fatal DTLS alert was sent, thesentAlert attribute is set to the value of the DTLS alert sent.
fingerprint-failure
TheRTCDtlsTransport'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. ThesctpCauseCode attribute is set to the SCTP cause code.
sdp-syntax-error
The SDP syntax is not valid. ThesdpLineNumber 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.3RTCErrorEvent Interface
TheRTCErrorEvent interface is defined for cases when anRTCError is raised as an event:
TheRTCDTMFSender object has either just begun playout of a tone (returned as thetone attribute) or just ended the playout of tones in thetoneBuffer (returned as an empty value in thetone 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 [RFC8827].
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 theRTCIceTransportPolicy dictionary, and by using relays (for instance TURN servers) rather than direct connections between participants. One will normally assume that the IP address of TURN servers is not sensitive information. These choices can for instance be made by the application based on whether the user has indicated consent to start a media connection with the other party.
Mitigating the exposure of IP addresses to the application itself requires limiting the IP addresses that can be used, which will impact the ability to communicate on the most direct path between endpoints. Browsers are encouraged to provide appropriate controls for deciding which IP addresses are made available to applications, based on the security posture desired by the user. The choice of which addresses to expose is controlled by local policy (see [RFC8828] for details).
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 usingpostMessage(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 theRTCCertificate 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 theRTCRtpSender.getCapabilities andRTCRtpReceiver.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 duringsession 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 likeontrack 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 theIETF 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 atW3C groups to effectively and consistently standardise RTT support internationally.
setCodecPreferences supports both send and receive codecs (filtered by direction) -section Methods (PR #3018) - Changes to Web Platform Tests:#49421
Candidate Correction 52:
Two codecs are considered the same even if level-id is not -section Methods (PR #3023) - Changes to Web Platform Tests:#49990
B. 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.
Media Capture and Streams. Cullen Jennings; Bernard Aboba; Jan-Ivar Bruaroey; Henrik Boström; youenn fablet; Daniel Burnett; Adam Bergkvist; Anant Narayanan. W3C.21 January 202119 December 2024.W3C Candidate RecommendationCRD. URL:https://www.w3.org/TR/mediacapture-streams/
ITU-T Recommendation X.509 version 3 (1997). "Information Technology - Open Systems Interconnection - The Directory Authentication Framework" ISO/IEC 9594-8:1997.. ITU.
