Initial Author of this Specification was Ian Hickson, Google Inc., with the following copyright statement:
© Copyright 2004-2011 Apple Computer, Inc., Mozilla Foundation, and Opera Software ASA. You are granted a license to use, reproduce and create derivative works of this document.
All subsequent changes since 26 July 2011 done by the W3C WebRTC Working Group are under the following Copyright:
© 2011-2016 W3C® (MIT, ERCIM, Keio, Beihang). Document use rules apply.
For the entire publication on the W3C site the liability and trademark rules apply.
This document defines a set of ECMAScript APIs in WebIDL to allow media to be sent to and received from another browser or device implementing the appropriate set of real-time protocols. This specification is being developed in conjunction with a protocol specification developed by the IETF RTCWEB group and an API specification to get access to local media devices developed by the Media Capture Task Force.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
The Editors and active contributors of WebRTC 1.0 intend to publish a Candidate Recommendation soon. Consequently, this is a Request for Comments by the WebRTC Working Group to seek wide review of this document.
The API is based on preliminary work done in the WHATWG.
This document was published by the Web Real-Time Communications Working Group as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-webrtc@w3.org (subscribe, archives). All comments are welcome.
Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 March 2017 W3C Process Document.
This section is non-normative.
There are a number of facets to video-conferencing in HTML covered by this specification:
This document defines the APIs used for these features. This specification is being developed in conjunction with a protocol specification developed by the IETF RTCWEB group and an API specification to get access to local media devices [GETUSERMEDIA] developed by the Media Capture Task Force. An overview of the system can be found in [ RTCWEB-OVERVIEW] and [RTCWEB-SECURITY].
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, SHALL, and SHOULD are to be interpreted as described in [RFC2119].
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL-1], as this specification uses that specification and terminology.
The EventHandler
interface, representing a callback used for event handlers, and the
ErrorEvent
interface are defined in [HTML5].
The concepts queue a task, fire a simple event and networking task source are defined in [HTML5].
The terms event, event handlers and event handler event types are defined in [HTML5].
The terms MediaStream, MediaStreamTrack
, and
MediaStreamConstraints
are defined in [GETUSERMEDIA].
The term Blob is defined in [FILEAPI].
The term media description is defined in [RFC4566].
The term generation is defined in [TRICKLE-ICE] Section 2.
When referring to exceptions, the terms throw and create are defined in [WEBIDL-1].
An
instance allows to establish peer to peer communications. Communications are coordinated via a signaling channel which is provided by unspecified means, but generally by a script in the page via the server, e.g. using
RTCPeerConnection
XMLHttpRequest
[XMLHttpRequest] or Web Sockets [
WEBSOCKETS-API].
The RTCConfiguration
defines a set of parameters to configure how the peer to peer communication established via
is established or re-established.
RTCPeerConnection
dictionary RTCConfiguration
{
sequence<RTCIceServer
> iceServers
;
RTCIceTransportPolicy
iceTransportPolicy
= "all";
RTCBundlePolicy
bundlePolicy
= "balanced";
RTCRtcpMuxPolicy
rtcpMuxPolicy
= "require";
DOMString peerIdentity
;
sequence<RTCCertificate
> certificates
;
[EnforceRange]
octet iceCandidatePoolSize
= 0;
};
RTCConfiguration
MembersiceServers
of type sequence<RTCIceServer
>An array of objects describing servers available to be used by ICE, such as STUN and TURN servers.
iceTransportPolicy
of type
RTCIceTransportPolicy
,
defaulting to "all"
Indicates which candidates the ICE Agent is allowed to use.
bundlePolicy
of type RTCBundlePolicy
, defaulting to
"balanced"
Indicates which media-bundling policy to use when gathering ICE candidates.
rtcpMuxPolicy
of type RTCRtcpMuxPolicy
, defaulting to
"require"
Indicates which rtcp-mux policy to use when gathering ICE candidates.
peerIdentity
of type DOMStringSets the target peer identity for the
RTCPeerConnection
. The RTCPeerConnection
will not establish a connection to a remote peer unless it can be successfully authenticated with the provided name.
certificates
of type sequence<RTCCertificate
>A set of certificates that the
uses to authenticate.RTCPeerConnection
Valid values for this parameter are created through calls to the
function.
generateCertificate
Although any given DTLS connection will use only one certificate, this attribute allows the caller to provide multiple certificates that support different algorithms. The final certificate will be selected based on the DTLS handshake, which establishes which certificates are allowed. The
RTCPeerConnection
implementation selects which of the certificates is used for a given connection; how certificates are selected is outside the scope of this specification.
If this value is absent, then a default set of certificates is generated for each
instance.
RTCPeerConnection
This option allows applications to establish key continuity. An RTCCertificate
can be persisted in [
INDEXEDDB] and reused. Persistence and reuse also avoids the cost of key generation.
The value for this configuration option cannot change after its value is initially selected.
iceCandidatePoolSize
of type
unsigned short,
defaulting to 0
Size of the prefetched ICE pool as defined in [JSEP] (section 3.5.4. and section 4.1.1.).
RTCIceCredentialType
Enum
enum RTCIceCredentialType
{
"password",
"token"
};
Enumeration description | |
---|---|
password |
The credential is a long-term authentication password, as described in [RFC5389], Section 10.2. |
token |
The credential is an access token, as described in [ TRAM-TURN-THIRD-PARTY-AUTHZ], Section 6.2. |
RTCIceServer
Dictionary
The RTCIceServer
dictionary is used to describe the STUN and TURN servers that can be used by the ICE Agent to establish a connection with a peer.
dictionary RTCIceServer
{
required (DOMString or sequence<DOMString>) urls
;
DOMString username
;
DOMString credential
;
RTCIceCredentialType
credentialType
= "password";
};
RTCIceServer
Membersurls
of type (DOMString or
sequence<DOMString>), requiredSTUN or TURN URI(s) as defined in [RFC7064] and [ RFC7065] or other URI types.
username
of type DOMStringIf this
object represents a TURN server, then this attribute specifies the username to use with that TURN server.RTCIceServer
credential
of type DOMStringIf this
object represents a TURN server, then this attribute specifies the credential to use with that TURN server.RTCIceServer
credentialType
of type RTCIceCredentialType
, defaulting to
"password"
If this
object represents a TURN server, then this attribute specifies how
credential should be used when that TURN server requests authorization.RTCIceServer
An example array of RTCIceServer objects is:
[
{ "urls": "stun:stun1.example.net" },
{ "urls": ["turns:turn.example.org", "turn:turn.example.net"],
"username": "user",
"credential": "myPassword",
"credentialType": "password" }
]
RTCIceTransportPolicy
Enum
As noted in [JSEP] (section 4.1.1.), if the
iceTransportPolicy
member of the RTCConfiguration
is specified, it defines the
ICE candidate policy
[JSEP] (section 3.5.3.) the browser uses to surface the permitted candidates to the application; only these candidates will be used for connectivity checks.
enum RTCIceTransportPolicy
{
"relay",
"all"
};
Enumeration description | |
---|---|
relay |
The ICE Agent MUST only use media relay candidates such as candidates passing through a TURN server. This can be used to reduce leakage of IP addresses in certain use cases. |
all |
The ICE Agent MAY use any type of candidates when this value is specified. This will not include addresses that have been filtered by the browser. |
RTCBundlePolicy
Enum
As described in [JSEP] (section 4.1.1.), bundle policy affects which media tracks are negotiated if the remote endpoint is not bundle-aware, and what ICE candidates are gathered. If the remote endpoint is bundle-aware, all media tracks and data channels are bundled onto the same transport.
enum RTCBundlePolicy
{
"balanced",
"max-compat",
"max-bundle"
};
Enumeration description (non-normative) | |
---|---|
balanced |
Gather ICE candidates for each media type in use (audio, video, and data). If the remote endpoint is not bundle-aware, negotiate only one audio and video track on separate transports. |
max-compat |
Gather ICE candidates for each track. If the remote endpoint is not bundle-aware, negotiate all media tracks on separate transports. |
max-bundle |
Gather ICE candidates for only one track. If the remote endpoint is not bundle-aware, negotiate only one media track. |
RTCRtcpMuxPolicy
Enum
As described in [JSEP] (section 4.1.1.), the RtcpMuxPolicy affects what ICE candidates are gathered to support non-multiplexed RTCP.
enum RTCRtcpMuxPolicy
{
// At risk due to lack of implementers' interest.
"negotiate",
"require"
};
Enumeration description (non-normative) | |
---|---|
negotiate |
Gather ICE candidates for both RTP and RTCP candidates. If the remote-endpoint is capable of multiplexing RTCP, multiplex RTCP on the RTP candidates. If it is not, use both the RTP and RTCP candidates separately. |
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. |
The value negotiate
is marked as a feature at risk, since there is no clear commitment from implementers for the behavior associated with this.
These dictionaries describe the options that can be used to control the offer/answer creation process.
dictionary RTCOfferAnswerOptions
{
boolean voiceActivityDetection
= true;
};
RTCOfferAnswerOptions
MembersvoiceActivityDetection
of type
boolean, defaulting to
true
Many codecs and systems are capable of detecting "silence" and changing their behavior in this case by doing things such as not transmitting any media. In many cases, such as when dealing with emergency calling or sounds other than spoken voice, it is desirable to be able to turn off this behavior. This option allows the application to provide information about whether it wishes this type of processing enabled or disabled.
dictionary RTCOfferOptions
: RTCOfferAnswerOptions
{
boolean iceRestart
= false;
};
RTCOfferOptions
MembersiceRestart
of type boolean, defaulting to
false
When the value of this dictionary member is true, the generated description will have ICE credentials that are different from the current credentials (as visible in the
attribute's SDP). Applying the generated description will restart ICE.localDescription
When the value of this dictionary member is false, and the
attribute has valid ICE credentials, the generated description will have the same ICE credentials as the current value from the
localDescription
attribute.localDescription
The RTCAnswerOptions
dictionary describe options specific to session description of type answer
(none in this version of the specification).
dictionary RTCAnswerOptions
: RTCOfferAnswerOptions
{
};
The [JSEP] specification, as a whole, describes the details of how the
operates. References to specific subsections of [JSEP] are provided as appropriate.RTCPeerConnection
Calling new
creates an RTCPeerConnection
(configuration )
object.RTCPeerConnection
The configuration has the information to find and access the servers used by ICE. There may be multiple servers of each type and any TURN server also acts as a STUN server.
An
object has a signaling
state, a connection state, an ICE gathering
state, and an ICE connection state. These are initialized when the object is created.RTCPeerConnection
The ICE protocol implementation of an
is represented by an ICE
agent [ICE]. Certain RTCPeerConnection
methods involve interactions with the ICE Agent, namely
RTCPeerConnection
, addIceCandidate
,
setConfiguration
,
setLocalDescription
and setRemoteDescription
. These interactions are described in the relevant sections in this document and in [JSEP]. The ICE Agent also provides indications to the user agent when the state of its internal representation of an close
changes, as described in 5.6 RTCIceTransport Interface.RTCIceTransport
When the RTCPeerConnection()
constructor is invoked, the user agent MUST run the following steps:
Let connection be a newly created
object.RTCPeerConnection
Initialize connection's ICE Agent.
Set the configuration specified by the constructor's first argument.
Let connection have an [[isClosed]] internal slot, initialized to false
.
Let connection have a [[needNegotiation]] internal slot, initialized to false
.
Let connection have an [[sctpTransport]] internal slot, initialized to null
.
Let connection have an [[operations]] internal slot, representing an operations queue, initialized to an empty list.
Set connection's signaling state to
stable
.
Set connection's ICE connection state to
new
.
Set connection's ICE gathering state to
new
.
Set connection's connection state to
new
.
Set connection's
,
pendingLocalDescription
,
currentLocalDescription
and
pendingRemoteDescription
to null.
currentRemoteDescription
If the certificates
value in the
RTCConfiguration
structure is non-empty, check that the expires
on each value is in the future. If a certificate has expired, throw an
InvalidAccessError
; otherwise, store the certificates. If no certificates
value was specified, one or more new RTCCertificate
instances are generated for use with this RTCPeerConnection
instance.
Store the configuration, including the certificates, in a [[ configuration]] internal slot.
Return connection.
An
object has an
operations queue, [[operations]], which ensures that only one asynchronous operation in the queue is executed concurrently. If subsequent calls are made while the returned promise of a previous call is still not settled, they are added to the queue and executed when all the previous calls have finished executing and their promises have settled.RTCPeerConnection
To enqueue an operation, run the following steps:
Let connection be the current
object.RTCPeerConnection
If connection's [[isClosed]] slot is
true
, return a promise rejected with a newly
created
InvalidStateError
.
Let operation be the operation to be enqueued.
Let p be a new promise.
Append operation to [[operations]].
If the length of [[operations]] is exactly 1, execute operation.
Upon fulfillment or rejection of the promise returned by the operation, run the following steps:
If connection's [[isClosed]] slot is
true
, abort these steps.
If the promise returned by operation was fulfilled with a value, fulfill p with that value.
If the promise returned by operation was rejected with a value, reject p with that value.
Upon fulfillment or rejection of p, execute the following steps:
If connection's [[isClosed]] slot is
true
, abort these steps.
Remove the first element of [[operations]].
If [[operations]] is non-empty, execute the operation represented by the first element of [[ operations]].
Return p.
An
object has an aggregated
connection state. Whenever the state of an
RTCPeerConnection
or
RTCDtlsTransport
changes or when the [[
isClosed]] slot turns RTCIceTransport
true
, the user agent MUST
update the connection state by queueing a task that runs the following steps:
Let connection be this
object.RTCPeerConnection
Let newState be the value of deriving a new state value as described by the
enum.RTCPeerConnectionState
If connection's connection state is equal to newState, abort these steps.
Let connection's connection state be newState.
Fire a simple event named
at
connection.connectionstatechange
To update the ICE gathering
state of an
instance
connection, the user agent MUST queue a task that runs the following steps:RTCPeerConnection
If connection's [[isClosed]] slot is
true
, abort these steps.
Let newState be the value of deriving a new state value as described by the
enum.
RTCIceGatheringState
If connection's ICE gathering state is equal to newState, abort these steps.
Set connection's ice gathering state to newState.
Fire a simple event named
at
connection.icegatheringstatechange
If newState is completed
, fire an event named
with icecandidate
null
at
connection.
To update the ICE
connection state of an
instance connection, the user agent MUST queue a task that runs the following steps:RTCPeerConnection
If connection's [[isClosed]] slot is
true
, abort these steps.
Let newState be the value of deriving a new state value as described by the
enum.
RTCIceConnectionState
If connection's ICE connection state is equal to newState, abort these steps.
Set connection's ice connection state to newState.
Fire a simple event named
at
connection.iceconnectionstatechange
To set an RTCSessionDescription
description on an
object connection, enqueue the following steps:RTCPeerConnection
Let p be a new promise.
In parallel, start the process to apply description as described in [JSEP] (section 5.5. and section 5.6.).
If the process to apply description fails for any reason, then user agent MUST queue a task runs the following steps:
If connection's [[isClosed]] slot is
true
, then abort these steps.
If elements of the SDP were modified, then reject
p with a newly
created
InvalidModificationError
and abort these steps.
If the description's
is invalid for the current signaling state of connection, then reject p with a newly
created
type
InvalidStateError
and abort these steps.
If the content of description is not valid SDP syntax, then reject p with an
RTCError
(with errorDetail
set to "sdpSyntaxError" and the sdpLineNumber attribute set to the line number in the SDP where the syntax error was detected) and abort these steps.
If the content of description is invalid, then reject p with a newly
created
InvalidAccessError
and abort these steps.
For all other errors, for example if
description cannot be applied at the media layer, reject p with a newly
created
OperationError
.
If description is applied successfully, the user agent MUST queue a task that runs the following steps:
If connection's [[isClosed]] slot is
true
, then abort these steps.
If description is set as a local description, then run one of the following steps:
If description is of type "offer", set
connection.
to description and signaling state to
pendingLocalDescription
have-local-offer
.
If description is of type "answer", then this completes an offer answer negotiation. Set
connection's
to description and currentLocalDescription
to the value of currentRemoteDescription
. Set both pendingRemoteDescription
and pendingRemoteDescription
to null. Finally set connection's
signaling state to pendingLocalDescription
stable
If description is of type "rollback", then this is a rollback. Set
connection.
to null and signaling state to
pendingLocalDescription
stable
.
If description is of type "pranswer", then set connection.
to description and signaling state to
pendingLocalDescription
have-local-pranswer
.
Otherwise, if description is set as a remote description, then run one of the following steps:
If description is of type "offer", set
connection.
attribute to description and signaling
state to pendingRemoteDescription
have-remote-offer
.
If description is of type "answer", then this completes an offer answer negotiation. Set
connection's
to description and currentRemoteDescription
to the value of currentLocalDescription
. Set both pendingLocalDescription
and pendingRemoteDescription
to null. Finally set connection's
signaling state to pendingLocalDescription
stable
If description is of type "rollback", then this is a rollback. Set
connection.
to null and signaling state to
pendingRemoteDescription
stable
.
If description is of type "pranswer", then set connection.
to description and signaling state to
pendingRemoteDescription
have-remote-pranswer
.
If connection's signaling state changed above, fire a simple event named
at
connection.signalingstatechange
If description is of type "answer", and it initiates the closure of an existing SCTP association, as defined in [SCTP-SDP], Sections 10.3 and 10.4, set the value of connection's [[
sctpTransport
]] internal slot to
null
.
If description is of type "answer" or "pranswer", then run the following steps:
If description initiates the establishment of a new SCTP association, as defined in [
SCTP-SDP], Sections 10.3 and 10.4, set the value of
connection's [[
sctpTransport
]] internal slot to a newly created
.RTCSctpTransport
If description negotiates the DTLS role of the SCTP transport, and there is an
with an unassigned
RTCDataChannel
, then generate an id according to [
RTCWEB-DATA-PROTOCOL]. If no available id could be generated, then run the following steps:id
Let channel be the
object for which an id could not be generated.RTCDataChannel
Set channel's
attribute to
readyState
closed
.
Fire an event named
with a
error
ResourceInUse
exception at
channel.
Fire a simple event named
at
channel.close
If description is set as a local description, then run the following steps for each media description in description that is not yet associated with an
object:RTCRtpTransceiver
Let transceiver be the
used to create the media description.RTCRtpTransceiver
Set transceiver's
value to the mid of the corresponding media description.mid
If description is set as a remote description, then run the following steps for each media description in description:
As described by [JSEP] (section 5.9.), attempt to find an existing
object, transceiver, to represent the media description.
RTCRtpTransceiver
If no suitable transceiver is found (transceiver is unset), run the following steps:
Create an RTCRtpSender, sender, from the media description.
Create an RTCRtpReceiver, receiver, from the media description.
Create an RTCRtpTransceiver with sender and receiver, and let transceiver be the result.
Set transceiver's
value to the mid of the corresponding media description. If the media description has no mid, generate a random value as described in [JSEP] (section 5.9.).mid
If the direction of the media description is
sendrecv
or sendonly
, and
transceiver.receiver.track
has not yet been fired in a
event, process the remote track for the media description, given transceiver.track
If the media description is rejected, and transceiver is not already stopped, stop the RTCRtpTransceiver transceiver.
If description is of type "rollback", then run the following steps:
If the
value of an
mid
was set to a non-null value by the
RTCRtpTransceiver
that is being rolled back, set the RTCSessionDescription
value of that transceiver to null, as described by [JSEP] (section 4.1.7.2.).mid
If an
was created by applying the
RTCRtpTransceiver
that is being rolled back, and a track has not been attached to it via RTCSessionDescription
addTrack
, remove that transceiver from connection's set of transceivers, as described by [JSEP] (section 4.1.7.2.).
Restore the value of connection's [[
sctpTransport
]] internal slot to its value at the last stable
signaling state.
If connection's signaling state is now
stable
, update the negotiation-needed
flag. If connection's [[
needNegotiation]] slot was true
both before and after this update, queue a task to check
connection's [[needNegotiation]] slot and, if still true
, fire a simple event named
negotiationneeded
at connection.
Resolve p with undefined.
Return p.
The task source for the tasks listed in this section is the networking task source.
The
interface presented in this section is extended by several partial interfaces throughout this specification. Notably, the RTP Media API section, which adds the APIs to send and receive RTCPeerConnection
objects.MediaStreamTrack
[Constructor(optional RTCConfiguration
configuration)]
interface RTCPeerConnection
: EventTarget {
Promise<RTCSessionDescriptionInit
> createOffer
(optional RTCOfferOptions
options);
Promise<RTCSessionDescriptionInit
> createAnswer
(optional RTCAnswerOptions
options);
Promise<void> setLocalDescription(RTCSessionDescriptionInit
description);
readonly attribute RTCSessionDescription
? localDescription
;
readonly attribute RTCSessionDescription
? currentLocalDescription
;
readonly attribute RTCSessionDescription
? pendingLocalDescription
;
Promise<void> setRemoteDescription
(RTCSessionDescriptionInit
description);
readonly attribute RTCSessionDescription
? remoteDescription
;
readonly attribute RTCSessionDescription
? currentRemoteDescription
;
readonly attribute RTCSessionDescription
? pendingRemoteDescription
;
Promise<void> addIceCandidate((RTCIceCandidateInit
or RTCIceCandidate
) candidate);
readonly attribute RTCSignalingState
signalingState
;
readonly attribute RTCIceGatheringState
iceGatheringState
;
readonly attribute RTCIceConnectionState
iceConnectionState
;
readonly attribute RTCPeerConnectionState
connectionState
;
readonly attribute boolean? canTrickleIceCandidates
;
static readonly attribute FrozenArray<RTCIceServer
> defaultIceServers
;
RTCConfiguration
getConfiguration
();
void setConfiguration
(RTCConfiguration
configuration);
void close
();
attribute EventHandler onnegotiationneeded
;
attribute EventHandler onicecandidate
;
attribute EventHandler onicecandidateerror
;
attribute EventHandler onsignalingstatechange
;
attribute EventHandler oniceconnectionstatechange
;
attribute EventHandler onicegatheringstatechange
;
attribute EventHandler onconnectionstatechange
;
attribute EventHandler onfingerprintfailure
;
};
RTCPeerConnection
RTCPeerConnection
constructor algorithm
.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
configuration | RTCConfiguration |
✘ | ✔ |
localDescription
of type RTCSessionDescription
, readonly ,
nullableThe localDescription
attribute MUST return
if it is not null and otherwise it MUST return pendingLocalDescription
.currentLocalDescription
currentLocalDescription
of type RTCSessionDescription
, readonly ,
nullableThe
attribute represents the local
currentLocalDescription
that was successfully negotiated the last time the RTCSessionDescription
RTCPeerConnection
transitioned into the stable state plus any local candidates that have been generated by the ICE Agent since the offer or answer was created.
The currentLocalDescription
attribute MUST return the last value that algorithms in this specification set it to, complete with any local candidates that have been generated by the ICE Agent since the offer or answer was created. Prior to being set, it returns null. Note that the value of
currentLocalDescription.sdp
need not match the value of localDescription.sdp
.
pendingLocalDescription
of type RTCSessionDescription
, readonly ,
nullableThe
attribute represents a local
pendingLocalDescription
that is in the process of being negotiated plus any local candidates that have been generated by the ICE Agent since the offer or answer was created. If the RTCSessionDescription
RTCPeerConnection
is in the stable state, the value is null. This attribute is updated by
.setLocalDescription
The pendingLocalDescription
attribute MUST return the last value that algorithms in this specification set it to, complete with any local candidates that have been generated by the ICE Agent since the offer or answer was created. Prior to being set, it returns null.
remoteDescription
of type RTCSessionDescription
, readonly ,
nullableThe remoteDescription
attribute MUST return
if it is not null and otherwise it MUST return pendingRemoteDescription
.currentRemoteDescription
currentRemoteDescription
of type RTCSessionDescription
, readonly ,
nullableThe
attribute represents the last remote
currentRemoteDescription
that was successfully negotiated the last time the RTCSessionDescription
RTCPeerConnection
transitioned into the stable state plus any remote candidates that have been supplied via
since the offer or answer was created.addIceCandidate()
The currentRemoteDescription
attribute MUST return the value that algorithms in this specification set it to, complete with any remote candidates that have been supplied via
since the offer or answer was created. Prior to being set, it returns null. Note that the value of addIceCandidate()
currentRemoteDescription.sdp
need not match the value of
remoteDescription.sdp
.
pendingRemoteDescription
of type RTCSessionDescription
, readonly ,
nullableThe
attribute represents a remote
pendingRemoteDescription
that is in the process of being negotiated, complete with any remote candidates that have been supplied via RTCSessionDescription
since the offer or answer was created. If the
addIceCandidate()
RTCPeerConnection
is in the stable state, the value is null. This attribute is updated by
.setLocalDescription
The pendingRemoteDescription
attribute MUST return the value that algorithms in this specification set it to, completed with any remote candidates that have been supplied via
since the offer or answer was created. Prior to being set, it returns null.
addIceCandidate()
signalingState
of type RTCSignalingState
, readonlyThe signalingState
attribute MUST return the
object's
signaling state.RTCPeerConnection
iceGatheringState
of type RTCIceGatheringState
, readonlyThe iceGatheringState
attribute MUST return the ICE gathering state of the
RTCPeerConnection
instance.
iceConnectionState
of type RTCIceConnectionState
, readonlyThe iceConnectionState
attribute MUST return the ICE connection state of the
RTCPeerConnection
instance.
connectionState
of type RTCPeerConnectionState
, readonlyThe connectionState
attribute MUST return the connection state of the
instance.RTCPeerConnection
canTrickleIceCandidates
of type boolean, readonly , nullableThe canTrickleIceCandidates
attribute indicates whether the remote peer is able to accept trickled ICE candidates [TRICKLE-ICE]. The value is determined based on whether a remote description indicates support for trickle ICE, as defined in [JSEP] (section 4.1.14.). Prior to the completion of
, this value is setRemoteDescription
null
.
defaultIceServers
of type
FrozenArray<RTCIceServer
>,
static readonlyThe defaultIceServers
attribute provides a list of ICE servers that are configured into the browser. A browser might be configured to use local or private STUN or TURN servers. This method allows an application to learn about these servers and optionally use them.
This list is likely to be persisent and is the same across origins. It thus increases the fingerprinting surface of the browser. In privacy-sensitive contexts, browsers can consider mitigations such as only providing this data to "trusted" origins (or not providing it at all.)
onnegotiationneeded
of type
EventHandlernegotiationneeded
.onicecandidate
of type EventHandlericecandidate
.onicecandidateerror
of type
EventHandlericecandidateerror
.onsignalingstatechange
of type
EventHandlersignalingstatechange
.oniceconnectionstatechange
of type
EventHandlericeconnectionstatechange
onicegatheringstatechange
of type
EventHandlericegatheringstatechange
.onconnectionstatechange
of type
EventHandlerconnectionstatechange
.onfingerprintfailure
of type
EventHandlerfingerprintfailure
.createOffer
The createOffer method generates a blob of SDP that contains an RFC 3264 offer with the supported configurations for the session, including descriptions of the local
MediaStreamTrack
s attached to this
RTCPeerConnection
, the codec/RTP/RTCP options supported by this implementation, and any candidates that have been gathered by the ICE Agent. The options
parameter may be supplied to provide additional control over the offer generated.
As an offer, the generated SDP will contain the full set of capabilities supported by the session (as opposed to an answer, which will include only a specific negotiated subset to use); for each SDP line, the generation of the SDP MUST follow the appropriate process for generating an offer. In the event
createOffer
is called after the session is established, createOffer
will generate an offer that is compatible with the current session, incorporating any changes that have been made to the session since the last complete offer-answer exchange, such as addition or removal of tracks. If no changes have been made, the offer will include the capabilities of the current local description as well as any additional capabilities that could be negotiated in an updated offer.
Session descriptions generated by createOffer
MUST be immediately usable by setLocalDescription
without causing an error as long as
setLocalDescription
is called reasonably soon. If a system has limited resources (e.g. a finite number of decoders), createOffer
needs to return an offer that reflects the current state of the system, so that
setLocalDescription
will succeed when it attempts to acquire those resources. The session descriptions MUST remain usable by setLocalDescription
without causing an error until at least the end of the fulfillment callback of the returned promise. Calling this method is needed to generate the ICE username fragment and password.
The value for certificates
in the
for the
RTCConfiguration
RTCPeerConnection
is used to produce a set of certificate fingerprints. These certificate fingerprints are used in the construction of SDP and as input to requests for identity assertions.
If the RTCPeerConnection
is configured to generate Identity assertions by calling
, then the session description
SHALL contain an appropriate assertion.setIdentityProvider
The SDP generation process exposes a subset of the media capabilities of the underlying system, which provides generally persistent cross-origin information on the device. It thus increases the fingerprinting surface of the application. In privacy-sensitive contexts, browsers can consider mitigations such as generating SDP matching only a common subset of the capabilities.
When the method is called, the user agent MUST run the following steps:
Let connection be the
object on which the method was invoked.RTCPeerConnection
If connection's [[isClosed]] slot is
true
, return a promise rejected with a newly
created
InvalidStateError
.
If connection is configured with an identity provider, and an identity assertion has not yet been generated using said identity provider, then begin the identity assertion request process if it has not already begun.
Return the result of enqueuing the following steps:
Let p be a new promise.
In parallel, begin the steps to create an offer, given p.
Return p.
The steps to create an offer given a promise p are as follows:
If the need for an identity assertion was identified when createOffer
was invoked, wait for
the
identity assertion request process to complete.
If the identity provider was unable to produce an identity assertion, reject p with a newly
created
NotReadableError
and abort these steps.
If connection was not constructed with a set of certificates, and one has not yet been generated, wait for it to be generated.
Inspect the system state to determine the currently available resources as necessary for generating the offer, as described in [JSEP] (section 4.1.5.).
If this inspection failed for any reason, reject
p with a newly
created
OperationError
and abort these steps.
Queue a task that runs the final steps to create an offer, given p.
The final steps to create an offer given a promise p are as follows:
If connection's [[isClosed]] slot is
true
, then abort these steps.
If connection was modified in such a way that additional inspection of the system state is necessary, then in parallel begin the steps to create an offer again, given p, and abort these steps.
createOffer
was called when only an audio
RTCRtpTransceiver
was added to
connection, but while performing the steps
to create an offer in parallel, a video
RTCRtpTransceiver
was added, requiring additional inspection of video system resources.
Given the information that was obtained from previous inspection and the current state of connection and its
s, generate an SDP offer, sdpString, as described in
[JSEP] (section 5.2.).RTCRtpTransceiver
Let offer be a newly created
dictionary with its RTCSessionDescriptionInit
type
member initialized to the string
"offer"
and its sdp
member initialized to sdpString.
Resolve p with offer.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
options | RTCOfferOptions |
✘ | ✔ |
Promise<RTCSessionDescriptionInit>
createAnswer
The createAnswer
method generates an [SDP] answer with the supported configuration for the session that is compatible with the parameters in the remote configuration. Like createOffer
, the returned blob contains descriptions of the local MediaStreamTrack
s attached to this RTCPeerConnection
, the codec/RTP/RTCP options negotiated for this session, and any candidates that have been gathered by the ICE Agent. The
options
parameter may be supplied to provide additional control over the generated answer.
As an answer, the generated SDP will contain a specific configuration that, along with the corresponding offer, specifies how the media plane should be established. The generation of the SDP MUST follow the appropriate process for generating an answer.
Session descriptions generated by createAnswer MUST be immediately usable by setLocalDescription
without causing an error as long as setLocalDescription
is called reasonably soon. Like createOffer
, the returned description SHOULD reflect the current state of the system. The session descriptions MUST remain usable by
setLocalDescription
without causing an error until at least the end of the fulfillment callback of the returned promise. Calling this method is needed to generate the ICE username fragment and password.
An answer can be marked as provisional, as described in
[JSEP] (section 4.1.7.1.), by setting the
to
type
pranswer
.
If the RTCPeerConnection
is configured to generate Identity assertions by calling
, then the session description SHALL contain an appropriate assertion.setIdentityProvider
When the method is called, the user agent MUST run the following steps:
Let connection be the
object on which the method was invoked.RTCPeerConnection
If connection's [[isClosed]] slot is
true
, return a promise rejected with a newly
created
InvalidStateError
.
If connection is configured with an identity provider, and an identity assertion has not yet been generated using said identity provider, then begin the identity assertion request process if it has not already begun.
Return the result of enqueuing the following steps:
If connection's
is
remoteDescription
null
return a promise rejected with a newly
created
InvalidStateError
.
Let p be a new promise.
In parallel, begin the steps to create an answer, given p.
Return p.
The steps to create an answer given a promise p are as follows:
If the need for an identity assertion was identified when createAnswer
was invoked, wait for
the
identity assertion request process to complete.
If the identity provider was unable to produce an identity assertion, reject p with a newly
created
NotReadableError
and abort these steps.
If connection was not constructed with a set of certificates, and one has not yet been generated, wait for it to be generated.
Inspect the system state to determine the currently available resources as necessary for generating the answer, as described in [JSEP] (section 4.1.6.).
If this inspection failed for any reason, reject
p with a newly
created
OperationError
and abort these steps.
Queue a task that runs the final steps to create an answer, given p.
The final steps to create an answer given a promise p are as follows:
If connection's [[isClosed]] slot is
true
, then abort these steps.
If connection was modified in such a way that additional inspection of the system state is necessary, then in parallel begin the steps to create an answer again, given p, and abort these steps.
createAnswer
was called when an
RTCRtpTransceiver
's direction was "recvonly", but while performing the steps to create
an answer in parallel, the direction was changed to "sendrecv", requiring additional inspection of video encoding resources.
Given the information that was obtained from previous inspection and the current state of connection and its
s, generate an SDP answer, sdpString, as described in
[JSEP] (section 5.3.).
RTCRtpTransceiver
Let answer be a newly created
dictionary with its RTCSessionDescriptionInit
type
member initialized to the string
"answer"
and its sdp
member initialized to sdpString.
Resolve p with answer.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
options | RTCAnswerOptions |
✘ | ✔ |
Promise<RTCSessionDescriptionInit>
setLocalDescription
The setLocalDescription()
method instructs the
to apply the supplied
RTCPeerConnection
as the local description.
RTCSessionDescriptionInit
This API changes the local media state. In order to successfully handle scenarios where the application wants to offer to change from one media format to a different, incompatible format, the
MUST be able to simultaneously support use of both the current and pending local descriptions (e.g. support codecs that exist in both descriptions) until a final answer is received, at which point the RTCPeerConnection
can fully adopt the pending local description, or rollback to the current description if the remote side rejected the change.RTCPeerConnection
As noted in [JSEP] (section 5.4.) the SDP returned from createOffer
or
createAnswer
MUST NOT be changed before passing it to setLocalDescription
. As a result, when the method is invoked, the user agent MUST run the following steps:
setLocalDescription
.createOffer
.createAnswer
.description.sdp
is
null
and description.type
is answer
or pranswer
, set description.sdp
to
lastAnswer.description.sdp
is
null
and description.type
is offer
, set description.sdp
to lastOffer.description.type
is
offer
and description.sdp
does not match lastOffer, reject the promise with a newly
created
InvalidModificationError
and abort these steps.
description.type
is
answer
or pranswer
and
description.sdp
does not match lastAnswer, reject the promise with a newly
created
InvalidModificationError
and abort these steps.Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
description |
RTCSessionDescriptionInit |
✘ | ✘ |
Promise<void>
setRemoteDescription
The setRemoteDescription
method instructs the
to apply the supplied
RTCPeerConnection
as the remote offer or answer. This API changes the local media state.RTCSessionDescriptionInit
When the method is invoked, the user agent MUST return the result of setting the RTCSessionDescription indicated by the method's first argument.
In addition, a remote description is processed to determine and verify the identity of the peer.
If an a=identity
attribute is present in the session description, the browser validates the identity
assertion..
If the "peerIdentity" configuration is applied to the
, this establishes a
target peer identity of the provided value. Alternatively, if the
RTCPeerConnection
has previously authenticated the identity of the peer (that is, there is a current value for RTCPeerConnection
), then this also establishes a target peer identity.peerIdentity
The target peer identity cannot be changed once set. Once set, if a different value is provided, the user agent MUST reject the returned promise with a newly
created
InvalidModificationError
and abort this operation. The
MUST be closed if the validated peer identity does not match the target peer
identity.RTCPeerConnection
If there is no target peer identity, then
setRemoteDescription
does not await the completion of identity validation.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
description |
RTCSessionDescriptionInit |
✘ | ✘ |
Promise<void>
addIceCandidate
The addIceCandidate()
method provides a remote candidate to the ICE Agent. This method can also be used to indicate the end of remote candidates when called with an empty string for
. The only members of the argument used by this method are candidate
, candidate
, sdpMid
, and
sdpMLineIndex
; the rest are ignored. When the method is invoked, the user agent MUST run the following steps:ufrag
Let candidate be the method's argument.
Let connection be the
object on which the method was invoked.RTCPeerConnection
If candidate is not null
and both sdpMid and sdpMLineIndex are
null
, return a promise rejected with a newly
created
TypeError
.
Return the result of enqueuing the following steps:
If
is
remoteDescription
null
return a promise rejected with a newly
created
InvalidStateError
.
Let p be a new promise.
If candidate.sdpMid is not null, run the following steps:
If candidate.sdpMid is not equal to the mid of any media description in
, reject p with a newly
created remoteDescription
OperationError
and abort these steps.
Else, if candidate.sdpMLineIndex is not null, run the following steps:
If candidate.sdpMLineIndex is equal to or larger than the number of media descriptions in
, reject p with a newly
created remoteDescription
OperationError
and abort these steps.
If candidate.ufrag
is neither
undefined
nor null
, and is not equal to any ufrag present in the corresponding
media description of an applied remote description, reject p with a newly
created
OperationError
and abort these steps.
In parallel, add the ICE candidate
candidate as described in [JSEP] (section 4.1.16.). Use
candidate.ufrag
to identify the ICE generation; if the ufrag is null, process the
candidate for the most recent ICE
generation. If
candidate.candidate
is an empty string, process candidate as an end-of-candidates indication for the corresponding
media description and ICE candidate
generation.
If candidate could not be successfully added the user agent MUST queue a task that runs the following steps:
If connection's [[
isClosed]] slot is true
, then abort these steps.
Reject p with a
DOMException
object whose
name
attribute has the value
OperationError
and abort these steps.
If candidate is applied successfully, the user agent MUST queue a task that runs the following steps:
If connection's [[
isClosed]] slot is true
, then abort these steps.
Let remoteDescription be
connection's
if not null, otherwise connection's
pendingRemoteDescription
.currentRemoteDescription
Add candidate to remoteDescription.
Resolve p with
undefined
.
Return p.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
candidate | (RTCIceCandidateInit or
RTCIceCandidate) |
✔ | ✘ |
Promise<void>
getConfiguration
Returns a
object representing the current configuration of this
RTCConfiguration
object.RTCPeerConnection
When this method is called, the user agent MUST return the
object stored in the [[
RTCConfiguration
configuration
]] internal slot.
RTCConfiguration
setConfiguration
The setConfiguration
method updates the configuration of this
object. This includes changing the configuration of the ICE
Agent. As noted in [JSEP] (section 3.5.1.), when the ICE configuration changes in a way that requires a new gathering phase, an ICE restart is required.RTCPeerConnection
When the setConfiguration
method is invoked, the user agent MUST run the following steps:
Let connection be the
on which the method was invoked.RTCPeerConnection
If connection's [[isClosed]] slot is
true
, throw an
InvalidStateError
.
To set a configuration, run the following steps:
RTCConfiguration
dictionary to be processed.
RTCPeerConnection
object.configuration.peerIdentity
is set and its value differs from the target peer
identity, throw an InvalidModificationError
.
configuration.certificates
is set and the set of certificates differs from the ones used when connection was constructed, throw an
InvalidModificationError
.configuration.bundlePolicy
is set and its value differs from the connection's bundle policy,
throw an InvalidModificationError
.configuration.rtcpMuxPolicy
is set and its value differs from the connection's rtcpMux policy, throw an InvalidModificationError
.configuration.iceCandidatePoolSize
is set and its value differs from the connection's previously set iceCandidatePoolSize
, and setLocalDescription
has already been called, throw an
InvalidModificationError
.Set the ICE Agent's ICE transports setting to the value of configuration.
. As defined in [JSEP] (section 4.1.15.), if the new ICE transports setting changes the existing setting, no action will be taken until the next gathering phase. If a script wants this to happen immediately, it should do an ICE restart.iceTransportPolicy
Set the ICE Agent's prefetched ICE candidate
pool size as defined in [JSEP] (section 3.5.4. and section 4.1.1.) to the value of configuration.
. If the new ICE candidate pool size changes the existing setting, this may result in immediate gathering of new pooled candidates, or discarding of existing pooled candidates, as defined in [JSEP] (section 4.1.15.).iceCandidatePoolSize
Let validatedServers be an empty list.
If configuration.
is defined, then run the following steps for each element:iceServers
Let server be the current list element.
If server.urls
is a string, let server.urls
be a list consisting of just that string.
For each url in
server.urls
parse
url and obtain scheme name. If the scheme name is not implemented by the browser, or if parsing based on the syntax defined in [
RFC7064] and [RFC7065] fails, throw a
SyntaxError
.
If scheme name is turn
or
turns
, and either of
server.username
or
server.credential
are omitted, then throw an InvalidAccessError
.
Append server to validatedServers.
Let validatedServers be the ICE Agent's ICE servers list.
As defined in [JSEP] (section 4.1.15.), if a new list of servers replaces the ICE Agent's existing ICE servers list, no action will be taken until the next gathering phase. If a script wants this to happen immediately, it should do an ICE restart. However, if the ICE candidate pool has a nonzero size, any existing pooled candidates will be discarded, and new candidates will be gathered from the new servers.
Store the configuration in the [[
configuration
]] internal slot.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
configuration | RTCConfiguration |
✘ | ✘ |
void
close
When the close
method is invoked, the user agent MUST run the following steps:
Let connection be the
object on which the method was invoked.RTCPeerConnection
If connection's [[isClosed]] slot is
true
, abort these steps.
Destroy connection's ICE Agent, abruptly ending any active ICE processing and any active streaming, and releasing any relevant resources (e.g. TURN permissions).
Set the
of each of
connection's state
s to RTCIceTransport
.closed
Let senders be the result of executing the
CollectSenders
algorithm. For every
sender in
senders, set
RTCRtpSender
sender.transport.state
and
sender.transport.transport.state
to "closed". If sender.rtcpTransport
is set, set
sender.rtcpTransport.state
and
sender.rtcpTransport.transport.state
to "closed".
Let receivers be the result of executing the
CollectReceivers
algorithm. For every
receiver in
receivers, set
RTCRtpReceiver
receiver.transport.state
and
receiver.transport.transport.state
to "closed". If
receiver.rtcpTransport
is set, set
receiver.rtcpTransport.state
and
receiver.rtcpTransport.transport.state
to "closed".
Let transceivers be the result of executing the
CollectTransceivers
algorithm. For every
transceiver in
transceivers, run the following steps:RTCRtpTransceiver
If transceiver.stopped
is
true
, abort these steps.
Let sender be transceiver.sender
.
Let receiver be transceiver.receiver
.
Stop sending media with sender.
Send an RTCP BYE for each SSRC in
sender.getParameters().encodings[i].ssrc
,
sender.getParameters().encodings[i].fec.ssrc
and
sender.getParameters().encodings[i].rtx.ssrc
where i goes from 0 to
sender.getParameters().encodings.length-1
.
Stop receiving media with receiver.
Set receiver.track.readyState
to ended
.
Set transceiver.stopped
to true
.
Set connection's [[isClosed]] slot to
true
.
void
RTCPeerConnection
for legacy purposes.
partial interface RTCPeerConnection
{
Promise<void> createOffer
(RTCSessionDescriptionCallback
successCallback,
RTCPeerConnectionErrorCallback
failureCallback,
optional RTCOfferOptions
options);
Promise<void> setLocalDescription
(RTCSessionDescriptionInit
description,
VoidFunction successCallback,
RTCPeerConnectionErrorCallback
failureCallback);
Promise<void> createAnswer
(RTCSessionDescriptionCallback
successCallback,
RTCPeerConnectionErrorCallback
failureCallback);
Promise<void> setRemoteDescription
(RTCSessionDescriptionInit
description,
VoidFunction successCallback,
RTCPeerConnectionErrorCallback
failureCallback);
Promise<void> addIceCandidate
((RTCIceCandidateInit
or RTCIceCandidate
) candidate,
VoidFunction successCallback,
RTCPeerConnectionErrorCallback
failureCallback);
};
createOffer
When the createOffer
method is called, the user agent MUST run the following steps:
Let successCallback be the method's first argument.
Let failureCallback be the callback indicated by the method's second argument.
Let options be the callback indicated by the method's third argument.
Run the steps specified by
's createOffer() method with
options as the sole argument, and let
p be the resulting promise.RTCPeerConnection
Upon fulfillment of p with value offer, invoke successCallback with offer as the argument.
Upon rejection of p with reason r, invoke failureCallback with r as the argument.
Return a promise resolved with
undefined
.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
successCallback |
RTCSessionDescriptionCallback |
✘ | ✘ | |
failureCallback |
RTCPeerConnectionErrorCallback |
✘ | ✘ | |
options | RTCOfferOptions |
✘ | ✔ |
Promise<void>
setLocalDescription
When the setLocalDescription
method is called, the user agent MUST run the following steps:
Let description be the method's first argument.
Let successCallback be the callback indicated by the method's second argument.
Let failureCallback be the callback indicated by the method's third argument.
Run the steps specified by
's RTCPeerConnection
setLocalDescription
method with
description as the sole argument, and let
p be the resulting promise.
Upon fulfillment of p, invoke
successCallback with undefined
as the argument.
Upon rejection of p with reason r, invoke failureCallback with r as the argument.
Return a promise resolved with
undefined
.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
description |
RTCSessionDescriptionInit |
✘ | ✘ | |
successCallback | VoidFunction |
✘ | ✘ | |
failureCallback |
RTCPeerConnectionErrorCallback |
✘ | ✘ |
Promise<void>
createAnswer
When the createAnswer
method is called, the user agent MUST run the following steps:
Let successCallback be the method's first argument.
Let failureCallback be the callback indicated by the method's second argument.
Run the steps specified by
's createAnswer() method with no arguments, and let p be the resulting promise.
RTCPeerConnection
Upon fulfillment of p with value answer, invoke successCallback with answer as the argument.
Upon rejection of p with reason r, invoke failureCallback with r as the argument.
Return a promise resolved with
undefined
.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
successCallback |
RTCSessionDescriptionCallback |
✘ | ✘ | |
failureCallback |
RTCPeerConnectionErrorCallback |
✘ | ✘ |
Promise<void>
setRemoteDescription
When the setRemoteDescription
method is called, the user agent MUST run the following steps:
Let description be the method's first argument.
Let successCallback be the callback indicated by the method's second argument.
Let failureCallback be the callback indicated by the method's third argument.
Run the steps specified by
's RTCPeerConnection
setRemoteDescription
method with
description as the sole argument, and let
p be the resulting promise.
Upon fulfillment of p, invoke
successCallback with undefined
as the argument.
Upon rejection of p with reason r, invoke failureCallback with r as the argument.
Return a promise resolved with
undefined
.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
description |
RTCSessionDescriptionInit |
✘ | ✘ | |
successCallback | VoidFunction |
✘ | ✘ | |
failureCallback |
RTCPeerConnectionErrorCallback |
✘ | ✘ |
Promise<void>
addIceCandidate
When the addIceCandidate
method is called, the user agent MUST run the following steps:
Let candidate be the method's first argument.
Let successCallback be the callback indicated by the method's second argument.
Let failureCallback be the callback indicated by the method's third argument.
Run the steps specified by
's RTCPeerConnection
addIceCandidate()
method with
candidate as the sole argument, and let
p be the resulting promise.
Upon fulfillment of p, invoke
successCallback with undefined
as the argument.
Upon rejection of p with reason r, invoke failureCallback with r as the argument.
Return a promise resolved with
undefined
.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
candidate | (RTCIceCandidateInit or
RTCIceCandidate) |
✘ | ✘ | |
successCallback | VoidFunction |
✘ | ✘ | |
failureCallback |
RTCPeerConnectionErrorCallback |
✘ | ✘ |
Promise<void>
partial dictionary RTCOfferOptions
{
boolean offerToReceiveAudio
;
boolean offerToReceiveVideo
;
};
offerToReceiveAudio
of type booleanWhen this is given a non-false value, no outgoing track of type "audio" is attached to the PeerConnection, and the existing localDescription (if any) doesn't contain any sendrecv or recv audio media sections, createOffer() will behave as if addTransceiver("audio") had been called once prior to the createOffer() call.
In all other situations, it will be disregarded.
offerToReceiveVideo
of type booleanWhen this is given a non-false value, and no outgoing track of type "video" is attached to the PeerConnection, and the existing localDescription (if any) doesn't contain any sendecv or recv video media sections, createOffer() will behave as if addTransceiver("video") had been called prior to the createOffer() call.
In all other situations, it will be disregarded.
An
object MUST not be garbage collected as long as any event can cause an event handler to be triggered on the object. When the object's [[isClosed]] internal slot is RTCPeerConnection
true
, no such event handler can be triggered and it is therefore safe to garbage collect the object.
All
and
RTCDataChannel
objects that are connected to a
MediaStreamTrack
have a strong reference to the
RTCPeerConnection
object.RTCPeerConnection
RTCSignalingState
Enum
enum RTCSignalingState
{
"stable",
"have-local-offer",
"have-remote-offer",
"have-local-pranswer",
"have-remote-pranswer"
};
Enumeration description | |
---|---|
stable |
There is no offeranswer exchange in progress. This is also the initial state in which case the local and remote descriptions are empty. |
have-local-offer |
A local description, of type "offer", has been successfully applied. |
have-remote-offer |
A remote description, of type "offer", has been successfully applied. |
have-local-pranswer |
A remote description of type "offer" has been successfully applied and a local description of type "pranswer" has been successfully applied. |
have-remote-pranswer |
A local description of type "offer" has been successfully applied and a remote description of type "pranswer" has been successfully applied. |
An example set of transitions might be:
stable
have-local-offer
have-remote-pranswer
stable
stable
have-remote-offer
have-local-pranswer
stable
RTCIceGatheringState
Enum
enum RTCIceGatheringState
{
"new",
"gathering",
"complete"
};
Enumeration description | |
---|---|
new |
Any of the s are in the
new gathering state and none of the transports are in the gathering state, or there are no transports.
|
gathering |
Any of the s are in the
gathering state. |
complete |
At least one exists, and all s are in the
completed gathering state. |
RTCPeerConnectionState
Enum
enum RTCPeerConnectionState
{
"new",
"connecting",
"connected",
"disconnected",
"failed",
"closed"
};
Enumeration description | |
---|---|
new |
Any of the s or
s are in the
new state and none of the transports are in the
connecting , checking ,
failed or disconnected state, or all transports are in the closed state. |
connecting |
Any of the s or
s are in the
connecting or checking state and none of them is in the failed state. |
connected |
All s and
s are in the
connected , completed or
closed state and at least of them is in the
connected or completed state. |
disconnected |
Any of the s or
s are in the
disconnected state and none of them are in the
failed or connecting or
checking state. |
failed |
Any of the s or
s are in a
failed state. |
closed |
The object's [[
isClosed]] slot is true .
|
RTCIceConnectionState
Enum
enum RTCIceConnectionState
{
"new",
"checking",
"connected",
"completed",
"failed",
"disconnected",
"closed"
};
Enumeration description | |
---|---|
new |
Any of the s are in the
new state and none of them are in the
checking , failed or
disconnected state, or all
s are in the
closed state. |
checking |
Any of the s are in the
checking state and none of them are in the
failed or disconnected state. |
connected |
All s are in the
connected , completed or
closed state and at least one of them is in the
connected state. |
completed |
All s are in the
completed or closed state and at least one of them is in the completed state. |
failed |
Any of the s are in the
failed state. |
disconnected |
Any of the s are in the
disconnected state and none of them are in the
failed state. |
closed |
The object's [[
isClosed]] slot is true .
|
Note that if an
is discarded as a result of signaling (e.g. RTCP mux or bundling), or created as a result of signaling (e.g. adding a new media description), the state may advance directly from one state to another.RTCIceTransport
These callbacks are only used on the legacy APIs.
RTCPeerConnectionErrorCallback
callback RTCPeerConnectionErrorCallback
= void (DOMException error);
RTCPeerConnectionErrorCallback
Parameterserror
of type DOMExceptionRTCSessionDescriptionCallback
callback RTCSessionDescriptionCallback
= void (RTCSessionDescriptionInit
description);
RTCSessionDescriptionCallback
Parametersdescription
of type RTCSessionDescriptionInit
RTCStatsCallback
callback RTCStatsCallback
= void (RTCStatsReport
report);
RTCStatsCallback
Parametersreport
of type RTCStatsReport
A
representing the gathered stats.RTCStatsReport
All methods that return promises are governed by the standard error handling rules of promises. Methods that do not return promises may throw exceptions to indicate errors.
Legacy-methods may only throw exceptions to indicate invalid state and other programming errors. For example, when a legacy-method is called when the
is in an invalid state or a state in which that particular method is not allowed to be executed, it will throw an exception. In all other cases, legacy methods MUST provide an error object to the error callback.RTCPeerConnection
RTCSdpType
The RTCSdpType enum describes the type of an
or
RTCSessionDescriptionInit
instance.RTCSessionDescription
enum RTCSdpType
{
"offer",
"pranswer",
"answer",
"rollback"
};
Enumeration description | |
---|---|
offer |
An |
pranswer |
An |
answer |
An |
rollback |
An |
RTCSessionDescription
Class
The RTCSessionDescription
class is used by
to expose local and remote session descriptions. Attributes on this interface are mutable for legacy reasons.RTCPeerConnection
[Constructor(RTCSessionDescriptionInit
descriptionInitDict)]
interface RTCSessionDescription
{
readonly attribute RTCSdpType
type
;
readonly attribute DOMString sdp
;
serializer = {attribute};
};
RTCSessionDescription
RTCSessionDescription()
constructor takes a dictionary argument,
descriptionInitDict, whose content is used to initialize the new RTCSessionDescription
object. This constructor is deprecated; it exists for legacy compatibility reasons only.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
descriptionInitDict |
RTCSessionDescriptionInit |
✘ | ✘ |
type
of type RTCSdpType
, readonlysdp
of type DOMString, readonlySerializer
Instances of this interface are serialized as a map with entries for each of the serializable attributes.
dictionary RTCSessionDescriptionInit
{
required RTCSdpType
type
;
DOMString sdp
= "";
};
RTCSessionDescriptionInit
Memberstype
of type RTCSdpType
, requiredsdp
of type DOMStringtype
is rollback
, this member is unused.
Many changes to state of an
will require communication with the remote side via the signaling channel, in order to have the desired effect. The app can be kept informed as to when it needs to do signaling, by listening to the
RTCPeerConnection
negotiationneeded
event. This event is fired according to the state of the connection's negotiation-needed flag, represented by a [[needNegotiation]] internal slot.
This section is non-normative.
If an operation is performed on an
that requires signaling, the connection will be marked as needing negotiation. Examples of such operations include adding or stopping an
RTCPeerConnection
, or adding the first RTCRtpTransceiver
.
RTCDataChannel
Internal changes within the implementation can also result in the connection being marked as needing negotiation.
Note that the exact procedures for updating the negotiation-needed flag are specified below.
This section is non-normative.
The negotiation-needed flag is cleared when an
of type "answer" is applied, and the supplied description matches the state of the
RTCSessionDescription
s and
RTCRtpTransceiver
s that currently exist on the
RTCDataChannel
. Specifically, this means that all non-
RTCPeerConnection
stopped
transceivers have an associated section in the local description with matching properties, and, if any data channels have been created, a data section exists in the local description.
Note that the exact procedures for updating the negotiation-needed flag are specified below.
The process below occurs where referenced elsewhere in this document. It also may occur as a result of internal changes within the implementation that affect negotiation. If such changes occur, the user agent MUST queue a task to update the negotiation-needed flag.
To update the negotiation-needed flag for connection, run the following steps:
If connection's [[isClosed]] slot is
true
, abort these steps.
If connection's signaling state is not "stable", abort these steps.
The negotiation-needed flag will be updated once the state transitions to "stable", as part of the steps for setting an RTCSessionDescription.
If the result of
checking if negotiation is needed is "false", clear the
negotiation-needed flag by setting connection's [[
needNegotiation]] slot to false
, and abort these steps.
If connection's [[needNegotiation]] slot is already true
, abort these steps.
Set connection's [[needNegotiation]] slot to
true
.
Queue a task to check connection's [[
needNegotiation]] slot and, if still true
, fire a simple event named negotiationneeded
at
connection.
This queueing prevents negotiationneeded
from firing prematurely, in the common situation where multiple modifications to connection are being made at once.
To check if negotiation is needed for connection, perform the following checks:
If any implementation-specific negotiation is required, as described at the start of this section, return "true".
If connection has created any
s, and no m= section has been negotiated yet for data, return "true".RTCDataChannel
For each transceiver t in connection's set of transceivers, perform the following checks:
If t isn't
stopped
and isn't yet associated with an m= section according to [JSEP] (section 3.4.1.), return "true".
If t isn't
stopped
and is associated with an m= section according to [JSEP] (section 3.4.1.), then perform the following checks:
If t's direction
is "sendrecv" or "sendonly", and the associated m= section in
connection's
doesn't contain an "a=msid" line, return "true".currentLocalDescription
If connection's
if of type "offer", and the direction of the associated m= section in neither the offer nor answer matches
t's currentLocalDescription
direction
, return "true".
If connection's
if of type "answer", and the direction of the associated m= section in the answer does not match t's currentLocalDescription
direction
intersected with the offered direction (as described in [JSEP] (section 5.3.1.)), return "true".
If t is
stopped
and is associated with an m= section according to
[JSEP] (section 3.4.1.), but the associated m= section is not yet rejected in
connection's
or
currentLocalDescription
, return "true".currentRemoteDescription
If all the preceding checks were performed and "true" was not returned, nothing remains to be negotiated; return "false".
RTCIceCandidate
Interface
This interface describes an ICE candidate.
[Constructor(RTCIceCandidateInit
candidateInitDict)]
interface RTCIceCandidate
{
readonly attribute DOMString candidate
;
readonly attribute DOMString? sdpMid
;
readonly attribute unsigned short? sdpMLineIndex
;
readonly attribute DOMString? foundation
;
readonly attribute unsigned long? priority
;
readonly attribute DOMString? ip
;
readonly attribute RTCIceProtocol
? protocol
;
readonly attribute unsigned short? port
;
readonly attribute RTCIceCandidateType
? type
;
readonly attribute RTCIceTcpCandidateType
? tcpType
;
readonly attribute DOMString? ufrag
;
serializer = {candidate, sdpMid, sdpMLineIndex, ufrag};
};
RTCIceCandidate
RTCIceCandidate()
constructor takes a dictionary argument, candidateInitDict, whose content is used to initialize the new RTCIceCandidate
object. When run, if both the sdpMid
and
sdpMLineIndex
dictionary members are
null
, throw a TypeError
.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
candidateInitDict | RTCIceCandidateInit |
✘ | ✘ |
candidate
of type DOMString, readonlycandidate-attribute
as defined in section 15.1 of [ICE]. If this RTCIceCandidate
represents an end-of-candidates indication,
candidate
is an empty string.sdpMid
of type DOMString, readonly , nullablenull
, this contains the identifier of the "media stream identification" as defined in [RFC5888] for the media component this candidate is associated with.sdpMLineIndex
of type unsigned short, readonly ,
nullablenull
, this indicates the index (starting at zero) of the media description in the SDP this candidate is associated with.
foundation
of type DOMString, readonly, nullableRTCIceTransport
s.priority
of type unsigned long, readonly, nullableip
of type DOMString, readonly, nullableThe IP address of the candidate.
The IP addresses exposed in candidates gathered via ICE and made visibile to the application in
RTCIceCandidate
instances can reveal more information about the device and the user (e.g. location, local network topology) than the user might have expected in a non-WebRTC enabled browser.
These IP addresses are always exposed to the application, and potentially exposed to the communicating party, and can be exposed without any specific user consent (e.g. for peer connections used with data channels, or to receive media only).
These IP addresses can also be used as temporary or persistent cross-origin states, and thus contribute to the fingerprinting surface of the device.
Applications can avoid exposing IP addresses to the communicating party, either temporarily or permanently, by forcing the ICE Agent to report only relay candidates via the iceTransportPolicy
member of
.RTCConfiguration
To limit the IP addresses exposed to the application itself, browsers can offer their users different policies regarding sharing local IP addresses, as defined in [ RTCWEB-IP-HANDLING].
protocol
of type RTCIceProtocol
, readonly, nullableudp
/tcp
).port
of type unsigned short, readonly, nullabletype
of type RTCIceCandidateType
, readonly, nullabletcpType
of type RTCIceTcpCandidateType
, readonly,
nullableprotocol
is tcp
,
tcpType
represents the type of TCP candidate. Otherwise, tcpType
is null
.relatedAddress
of type DOMString, readonly, nullablerelatedAddress
is the IP address of the candidate that it is derived from. For host candidates, the relatedAddress
is
null
.relatedPort
of type unsigned short, readonly,
nullablerelatedPort
is the port of the candidate that it is derived from. For host candidates, the
relatedPort
is null
.ufrag
of type DOMString, readonlyufrag
as defined in section 15.4 of [ICE].Serializer
Instances of this interface are serialized as a map with entries for the following attributes: candidate, sdpMid, sdpMLineIndex, ufrag.
dictionary RTCIceCandidateInit
{
DOMString candidate
= "";
DOMString? sdpMid
= null;
unsigned short? sdpMLineIndex
= null;
DOMString ufrag
;
};
RTCIceCandidateInit
Memberscandidate
of type DOMString, defaulting to
""
sdpMid
of type DOMString, nullable, defaulting to
null
sdpMLineIndex
of type unsigned short, nullable,
defaulting to null
ufrag
of type DOMStringThe RTCIceProtocol
represents the protocol of the ICE candidate.
enum RTCIceProtocol
{
"udp",
"tcp"
};
Enumeration description | |
---|---|
udp |
A UDP candidate, as described in [ICE]. |
tcp |
A TCP candidate, as described in [RFC6544]. |
The RTCIceTcpCandidateType
represents the type of the ICE TCP candidate, as defined in [RFC6544].
enum RTCIceTcpCandidateType
{
"active",
"passive",
"so"
};
Enumeration description | |
---|---|
active |
An active TCP candidate is one for which the transport will attempt to open an outbound connection but will not receive incoming connection requests. |
passive |
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. |
The RTCIceCandidateType
represents the type of the ICE candidate, as defined in [ICE] section 15.1.
enum RTCIceCandidateType
{
"host",
"srflx",
"prflx",
"relay"
};
Enumeration description | |
---|---|
host |
A host candidate, as defined in Section 4.1.1.1 of [ ICE]. |
srflx |
A server reflexive candidate, as defined in Section 4.1.1.2 of [ICE]. |
prflx |
A peer reflexive candidate, as defined in Section 4.1.1.2 of [ICE]. |
relay |
A relay candidate, as defined in Section 7.1.3.2.1 of [ ICE]. |
The icecandidate
event of the RTCPeerConnection uses the
interface.RTCPeerConnectionIceEvent
Firing an
event named
e with an RTCPeerConnectionIceEvent
candidate means that an event with the name e, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the
RTCIceCandidate
RTCPeerConnectionIceEvent
interface with the
candidate
attribute set to the new ICE candidate, MUST be created and dispatched at the given target.
When firing an
event that contains a RTCPeerConnectionIceEvent
object, it MUST include values for both RTCIceCandidate
and sdpMid
. If the
sdpMLineIndex
is of type RTCIceCandidate
srflx
or type relay
, the url
property of the event
MUST be set to the URL of the ICE server from which the candidate was obtained.
[Constructor(DOMString type, optional RTCPeerConnectionIceEventInit
eventInitDict)]
interface RTCPeerConnectionIceEvent
: Event {
readonly attribute RTCIceCandidate
? candidate
;
readonly attribute DOMString? url
;
};
RTCPeerConnectionIceEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type | DOMString |
✘ | ✘ | |
eventInitDict |
RTCPeerConnectionIceEventInit |
✘ | ✘ |
candidate
of type RTCIceCandidate
, readonly ,
nullableThe candidate
attribute is the
object with the new ICE candidate that caused the event.RTCIceCandidate
This attribute is set to null
when an event is generated to indicate the end of candidate gathering.
Even where there are multiple media components, only one event containing a null
candidate is fired.
url
of type DOMString, readonly , nullableThe url
attribute is the STUN or TURN URL that identifies the STUN or TURN server used to gather this candidate. If the candidate was not gathered from a STUN or TURN server, this parameter will be set to
null
.
dictionary RTCPeerConnectionIceEventInit
: EventInit {
RTCIceCandidate
? candidate
;
DOMString? url
;
};
RTCPeerConnectionIceEventInit
Memberscandidate
of type RTCIceCandidate
, nullableSee the
candidate
attribute of the
RTCPeerConnectionIceEvent
interface.
url
of type DOMStringThe icecandidateerror
event of the RTCPeerConnection uses the
interface.RTCPeerConnectionIceErrorEvent
[Constructor(DOMString type, RTCPeerConnectionIceErrorEventInit
eventInitDict)]
interface RTCPeerConnectionIceErrorEvent
: Event {
readonly attribute DOMString hostCandidate
;
readonly attribute DOMString url
;
readonly attribute unsigned short errorCode
;
readonly attribute USVString errorText
;
};
RTCPeerConnectionIceErrorEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type | DOMString |
✘ | ✘ | |
eventInitDict |
RTCPeerConnectionIceErrorEventInit |
✘ | ✘ |
hostCandidate
of type DOMString, readonlyThe hostCandidate
attribute is the local IP address and port used to communicate with the STUN or TURN server.
On a multihomed system, multiple interfaces may be used to contact the server, and this attribute allows the application to figure out on which one the failure occurred.
If use of multiple interfaces has been prohibited for privacy reasons, this attribute will be set to 0.0.0.0:0 or [::]:0, as appropriate.
url
of type DOMString, readonlyThe url
attribute is the STUN or TURN URL that identifies the STUN or TURN server for which the failure occurred.
errorCode
of type unsigned short, readonlyThe errorCode
attribute is the numeric STUN error code returned by the STUN or TURN server [
STUN-PARAMETERS].
If no host candidate can reach the server,
errorCode
will be set to the value 701 which is outside the STUN error code range. This error is only fired once per server URL while in the
RTCIceGatheringState
of "gathering".
errorText
of type USVString, readonlyThe errorText
attribute is the STUN reason text returned by the STUN or TURN server [STUN-PARAMETERS].
If the server could not be reached, errorText
will be set to an implementation-specific value providing details about the error.
dictionary RTCPeerConnectionIceErrorEventInit
: EventInit {
DOMString hostCandidate
;
DOMString url
;
required unsigned short errorCode
;
USVString statusText
;
};
RTCPeerConnectionIceErrorEventInit
MembershostCandidate
of type DOMStringurl
of type DOMStringerrorCode
of type unsigned short, requiredstatusText
of type USVStringMany applications have multiple media flows of the same data type and often some of the flows are more important than others. WebRTC uses the priority and Quality of Service (QoS) framework described in [
RTCWEB-TRANSPORT] and [TSVWG-RTCWEB-QOS] to provide priority and DSCP marking for packets that will help provide QoS in some networking environments. The priority setting can be used to indicate the relative priority of various flows. The priority API allows the JavaScript applications to tell the browser whether a particular media flow is high, medium, low or of very low importance to the application by setting the
priority
property of
objects to one of the following values.RTCRtpEncodingParameters
RTCPriorityType
Enum
enum RTCPriorityType
{
"very-low",
"low",
"medium",
"high"
};
Enumeration description | |
---|---|
very-low |
See [RTCWEB-TRANSPORT], Section 4. |
low |
See [RTCWEB-TRANSPORT], Section 4. |
medium |
See [RTCWEB-TRANSPORT], Section 4. |
high |
See [RTCWEB-TRANSPORT], Section 4. |
Applications that use this API should be aware that often better overall user experience is obtained by lowering the priority of things that are not as important rather than raising the priority of the things that are.
The certificates that RTCPeerConnection
instances use to authenticate with peers use the
interface. These objects can be explicitly generated by applications using the RTCCertificate
method on the connection and provided in the generateCertificate
when constructing a new RTCConfiguration
RTCPeerConnection
instance.
The explicit certificate management functions provided here are optional. If an application does not provide the
certificates
configuration option when constructing an
RTCPeerConnection
a new set of certificates MUST be generated by the user agent. That set MUST include an ECDSA certificate with a private key on the P-256 curve and a signature with a SHA-256 hash.
partial interface RTCPeerConnection
{
static Promise<RTCCertificate
> generateCertificate
(AlgorithmIdentifier keygenAlgorithm);
};
generateCertificate
, staticThe generateCertificate
function causes the
user agent to create and store an X.509 certificate [
X509V3] and corresponding private key. A handle to information is provided in the form of the
RTCCertificate
interface. The returned
RTCCertificate
can be used to control the certificate that is offered in the DTLS sessions established by
RTCPeerConnection
.
The keygenAlgorithm argument is used to control how the private key associated with the certificate is generated. The
keygenAlgorithm argument uses the WebCrypto [
WebCryptoAPI]
AlgorithmIdentifier
type. The
keygenAlgorithm value MUST be a valid argument to
window.crypto.subtle.generateKey
; that is, the value MUST produce a non-error result when normalized according to the WebCrypto
algorithm normalization process [WebCryptoAPI] with an operation name of generateKey
and a [[supportedAlgorithms]] value specific to production of certificates for
RTCPeerConnection
. If the algorithm normalization process produces an error, the call to
generateCertificate
MUST be rejected with that error.
Signatures produced by the generated key are used to authenticate the DTLS connection. The identified algorithm (as identified by the name
of the normalized
AlgorithmIdentifier
) MUST be an asymmetric algorithm that can be used to produce a signature.
The certificate produced by this process also contains a signature. The validity of this signature is only relevant for compatibility reasons. Only the public key and the resulting certificate fingerprint are used by
RTCPeerConnection
, but it is more likely that a certificate will be accepted if the certificate is well formed. The browser selects the algorithm used to sign the certificate; a browser SHOULD select SHA-256 [FIPS-180-4] if a hash algorithm is needed.
The resulting certificate MUST NOT include information that can be linked to a user or user agent. Randomized values for distinguished name and serial number SHOULD be used.
A user agent MUST reject a call to
generateCertificate()
with a
DOMException
of type NotSupportedError
if the keygenAlgorithm parameter identifies an algorithm that the user agent cannot or will not use to generate a certificate for RTCPeerConnection
.
The following values MUST be supported by a user agent:
{ name: "RSASSA-PKCS1-v1_5",
modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]),
hash: "SHA-256" }
, and { name: "ECDSA",
namedCurve: "P-256"
}
.
It is expected that a user agent will have a small or even fixed set of values that it will accept.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
keygenAlgorithm | AlgorithmIdentifier |
✘ | ✘ |
Promise<RTCCertificate>
RTCCertificateExpiration
is used to set an expiration date on certificates generated by RTCCertificateExpiration
.generateCertificate
dictionary RTCCertificateExpiration
{
[EnforceRange]
DOMTimeStamp expires
;
};
expires
An optional expires
attribute MAY be added to the definition of the algorithm that is passed to
. If this parameter is present it indicates the maximum time that the
generateCertificate
is valid for relative to the current time.RTCCertificate
When
is called with an generateCertificate
object
argument, the user agent attempts to convert the object into a
. If this is unsuccessful, immediately return a promise that is rejected with a newly created
RTCCertificateExpiration
TypeError
and abort processing.
A user agent generates a certificate that has an expiration date set to the current time plus the value of the
expires
attribute. The
attribute of the returned
expires
is set to the expiration time of the certificate. A user agent MAY choose to limit the value of the RTCCertificate
attribute.
expires
The RTCCertificate
interface represents a certificate used to authenticate WebRTC communications. In addition to the visible properties, internal slots contain a handle to the generated private keying materal ([[handle]]) and a certificate ([[certificate]]) that
RTCPeerConnection
uses to authenticate with a peer.
interface RTCCertificate
{
readonly attribute DOMTimeStamp expires
;
readonly attribute FrozenArray<RTCDtlsFingerprint
> fingerprints
;
AlgorithmIdentifier getAlgorithm
();
};
expires
of type DOMTimeStamp, readonlyThe expires attribute indicates the date and time in milliseconds relative to 1970-01-01T00:00:00Z after which the certificate will be considered invalid by the browser. After this time, attempts to construct an
RTCPeerConnection
using this certificate fail.
Note that this value might not be reflected in a
notAfter
parameter in the certificate itself.
fingerprints
of type FrozenArray<RTCDtlsFingerprint
>,
readonlyA list of certificate fingerprints, one of which is computed with the digest algorithm used in the certificate signature.
getAlgorithm
Returns the value of keygenAlgorithm passed in the call to generateCertificate()
.
AlgorithmIdentifier
For the purposes of this API, the [[certificate]] slot contains unstructured binary data.
Note that a RTCCertificate
might not directly hold private keying material, this might be stored in a secure module.
The RTCCertificate
object can be stored and retrieved from persistent storage by an application. When a user agent is required to obtain a structured clone [HTML] of a
RTCCertificate
object, it performs the following steps:
RTCCertificate
object to be cloned.RTCCertificate
object.expires
attribute from
input to output.The RTP media API lets a web application send and receive
MediaStreamTrack
s over a peer-to-peer connection. Tracks, when added to a RTCPeerConnection
, result in signaling; when this signaling is forwarded to a remote peer, it causes corresponding tracks to be created on the remote side.
The actual encoding and transmission of MediaStreamTrack
s is managed through objects called
s. Similarly, the reception and decoding of RTCRtpSender
MediaStreamTrack
s is managed through objects called
s. Each
RTCRtpReceiver
is associated with at most one track, and each track to be received is associated with exactly one RTCRtpSender
.RTCRtpReceiver
The encoding and transmission of each MediaStreamTrack
SHOULD be made such that its characteristics (width, height and frameRate for video tracks; volume, sampleSize, sampleRate and channelCount for audio tracks) are to a reasonable degree retained by the track created on the remote side. There are situations when this does not apply, there may for example be resource constraints at either endpoint or in the network or there may be
settings applied that instruct the implementation to act differently.RTCRtpSender
s are created when the application attaches a RTCRtpSender
MediaStreamTrack
to a
, via the RTCPeerConnection
addTrack
method.
s, on the other hand, are created when remote signaling indicates new tracks are available, and each new
RTCRtpReceiver
MediaStreamTrack
and its associated
are surfaced to the application via the
RTCRtpReceiver
ontrack
event. Both
and
RTCRtpSender
objects are created by the
RTCRtpReceiver
addTransceiver
method.
A
object contains a set of
RTCPeerConnection
s, representing the paired senders and receivers with some shared state. This set is initialized to the empty set when the RTCRtpTransceiver
object is created.
RTCPeerConnection
There are several ways to initiate the sending of a
MediaStreamTrack
over a peer-to-peer connection. One way is to use the addTrack
method on the
. Another way is to use the RTCPeerConnection
replaceTrack
method on an existing
. Yet another way is to create a new RTCRtpSender
via the
RTCRtpSender
addTransceiver
method (with or without a
MediaStreamTrack
argument). While
addTrack
checks if the MediaStreamTrack
given as an argument is already being sent to avoid sending the same MediaStreamTrack
twice, the other ways do not, allowing the same MediaStreamTrack
(possibly using different
with different
RTCRtpParameters
s) to be sent several times simultaneously. Doing this implies that at the receiving end of the peer-to-peer connection there are several
RTCRtpSender
MediaStreamTrack
s with an identical
id
.
The RTP media API extends the
interface as described below.RTCPeerConnection
partial interface RTCPeerConnection
{
sequence<RTCRtpSender
> getSenders
();
sequence<RTCRtpReceiver
> getReceivers
();
sequence<RTCRtpTransceiver
> getTransceivers
();
RTCRtpSender
addTrack
(MediaStreamTrack
track,
MediaStream... streams);
void removeTrack
(RTCRtpSender
sender);
RTCRtpTransceiver
addTransceiver
((MediaStreamTrack
or DOMString) trackOrKind,
optional RTCRtpTransceiverInit
init);
attribute EventHandler ontrack
;
};
ontrack
of type EventHandlerThe event type of this event handler is
.track
getSenders
Returns a sequence of
objects representing the RTP senders that are currently attached to this
RTCRtpSender
object.RTCPeerConnection
The getSenders
method MUST return the result of executing the
CollectSenders
algorithm.
We define the CollectSenders algorithm as follows:
CollectTransceivers
algorithm.RTCRtpSender
objects in
senderset. The conversion from the senders set to the sequence is user agent defined and the order does not have to be stable between calls.sequence<RTCRtpSender>
getReceivers
Returns a sequence of
objects representing the RTP receivers that are currently attached to this RTCRtpReceiver
object.RTCPeerConnection
The getReceivers
method MUST return the result of executing the
CollectReceivers
algorithm.
We define the CollectReceivers algorithm as follows:
CollectTransceivers
algorithm.RTCRtpReceiver
objects in
receiverset. The conversion from the receivers set to the sequence is user agent defined and the order does not have to be stable between calls.sequence<RTCRtpReceiver>
getTransceivers
Returns a sequence of
objects representing the RTP transceivers that are currently attached to this RTCRtpTransceiver
object.RTCPeerConnection
The getTransceivers
method MUST return the result of executing the
CollectTransceivers
algorithm.
We define the CollectTransceivers algorithm as follows:
RTCRtpTransceiver
objects in this
RTCPeerConnection
object's set of
transceivers. The conversion from the transceiver set to the sequence is user agent defined and the order does not have to be stable between calls.
sequence<RTCRtpTransceiver>
addTrack
Adds a new track to the
, and indicates that it is contained in the specified
RTCPeerConnection
MediaStream
s.
When the addTrack
method is invoked, the user agent MUST run the following steps:
Let connection be the
object on which this method was invoked.RTCPeerConnection
Let track be the
object indicated by the method's first argument.MediaStreamTrack
Let streams be a list of
MediaStream
objects constructed from the method's remaining arguments, or an empty list if the method was called with a single argument.
If connection's [[isClosed]] slot is
true
, throw an
InvalidStateError
.
Let senders be the result of executing the
CollectSenders
algorithm. If an
for track already exists in senders, throw an
RTCRtpSender
InvalidAccessError
.
The steps below describe how to determine if an existing sender can be reused. Doing so will cause future calls to
createOffer
and createAnswer
to mark the corresponding media description as
sendrecv
or sendonly
and add the MSID of the track added, as defined in [JSEP] (section 5.2.2. and section 5.3.2.).
If any
object in
senders matches all the following criteria, let
sender be that object, or RTCRtpSender
null
otherwise:
The sender's track is null.
The transceiver kind of the
, associated with the sender, matches track's kind.RTCRtpTransceiver
The sender has never been used to send. More precisely, the
associated with the sender has never had a RTCRtpTransceiver
of currentDirection
sendrecv
or sendonly
.
If sender is not null
, run the following steps to use that sender:
Set sender.track to track.
Set sender's [[associated MediaStreams]] to streams.
Enable sending direction on the
associated with
sender.RTCRtpTransceiver
If sender is null
, run the following steps:
Create an RTCRtpSender with track and streams and let sender be the result.
Create an RTCRtpReceiver with track.kind as kind and let receiver be the result.
Create an RTCRtpTransceiver with sender and receiver and let transceiver be the result.
Add transceiver to connection's set of transceivers
A track could have contents that are inaccessible to the application. This can be due to being marked with a
peerIdentity
option or anything that would make a track
CORS cross-origin. These tracks can be supplied to the
addTrack
method, and have an
created for them, but content MUST NOT be transmitted, unless they are also marked with RTCRtpSender
peerIdentity
and they meet the requirements for sending (see isolated streams and
RTCPeerConnection
).
All other tracks that are not accessible to the application MUST NOT be sent to the peer, with silence (audio), black frames (video) or equivalently absent content being sent in place of track content.
Note that this property can change over time.
Update the negotiation-needed flag for connection.
Return sender.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
track | MediaStreamTrack |
✘ | ✘ | |
streams | MediaStream |
✘ | ✘ |
RTCRtpSender
removeTrack
Stops sending media from sender. The
will still appear in RTCRtpSender
getSenders
. Doing so will cause future calls to createOffer
to mark the
media description for the corresponding transceiver as recvonly
or inactive
, as defined in
[JSEP] (section 5.2.2.).
When the other peer stops sending a track in this manner, an
ended
event is fired at the
object.MediaStreamTrack
When the removeTrack
method is invoked, the user agent MUST run the following steps:
Let sender be the argument to
removeTrack
.
Let connection be the
object on which the method was invoked.RTCPeerConnection
If connection's [[isClosed]] slot is
true
, throw an
InvalidStateError
.
If sender was not created by
connection, throw an
InvalidAccessError
.
Let senders be the result of executing the
CollectSenders
algorithm.
If sender is not in senders (which indicates that it was removed due to setting an RTCSessionDescription of type "rollback"), then abort these steps.
Set sender.track
to null.
Let transceiver be the
object corresponding to sender.RTCRtpTransceiver
If transceiver.currentDirection
is recvonly
or inactive
, then abort these steps.
If transceiver.currentDirection
is sendrecv
set
transceiver.direction
to
recvonly
.
If transceiver.currentDirection
is sendonly
set
transceiver.direction
to
inactive
.
Update the negotiation-needed flag for connection.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
sender | RTCRtpSender |
✘ | ✘ |
void
addTransceiver
Create a new
and add it to the set of transceivers.RTCRtpTransceiver
Adding a transceiver will cause future calls to
createOffer
to add a media description for the corresponding transceiver, as defined in [JSEP] (section 5.2.2.).
The initial value of
is null. Setting a new
mid
may change it to a non-null value, as defined in [JSEP] (section 5.5. and section 5.6.).RTCSessionDescription
When this method is invoked, the user agent MUST run the following steps:
If the dictionary argument is present, and it has a
streams
member, let streams be that list of MediaStream
objects, or an empty list otherwise.
If the dictionary argument is present, and it has a
sendEncodings
member, let
sendEncodings be that list of
objects, or an empty list otherwise.RTCRtpEncodingParameters
If the first argument is a string, let it be kind and run the following steps:
If kind is not a legal
MediaStreamTrack
kind
,
throw a TypeError
.
Let track be null
.
If the first argument is a
, let it be
track and let kind be
track.kind.MediaStreamTrack
Create an RTCRtpSender with track, streams and sendEncodings and let sender be the result.
If sendEncodings is set, then subsequent calls to createOffer
will be configured to send multiple RTP encodings as defined in [JSEP] (section 5.2.2. and section 5.2.1.). When
setRemoteDescription
is called with a corresponding remote description that is able to receive multiple RTP encodings as defined in [JSEP] (section 3.7.), the
may send multiple RTP encodings and the parameters retrieved via the transceiver's
RTCRtpSender
sender.getParameters()
will reflect the encodings negotiated.
RID values passed into init.sendEncodings
must be composed only of case-sensitive alphanumeric characters (a-z, A-Z, 0-9) up to a maximum of 16 characters.
Create an RTCRtpReceiver with kind and let receiver be the result. This specification does not define how to configure createOffer
to receive multiple RTP encodings. However when
setRemoteDescription
is called with a corresponding remote description that is able to send multiple RTP encodings as defined in [JSEP], the
may receive multiple RTP encodings and the parameters retrieved via the transceiver's
RTCRtpReceiver
receiver.getParameters()
will reflect the encodings negotiated.
Create an RTCRtpTransceiver with sender and receiver and let transceiver be the result.
Add transceiver to connection's set of transceivers
Update the negotiation-needed flag for connection.
Return transceiver.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
trackOrKind | (MediaStreamTrack or
DOMString) |
✘ | ✘ | |
init | RTCRtpTransceiverInit |
✘ | ✔ |
RTCRtpTransceiver
dictionary RTCRtpTransceiverInit
{
RTCRtpTransceiverDirection
direction
= "sendrecv";
sequence<MediaStream> streams
;
sequence<RTCRtpEncodingParameters
> sendEncodings
;
};
RTCRtpTransceiverInit
Membersdirection
of type RTCRtpTransceiverDirection
,
defaulting to "sendrecv"
RTCRtpTransceiver
.streams
of type sequence<MediaStream>When the remote PeerConnection's ontrack event fires corresponding to the
being added, these are the streams that will be put in the event.RTCRtpReceiver
sendEncodings
of type sequence<RTCRtpEncodingParameters
>A sequence containing parameters for sending RTP encodings of media.
enum RTCRtpTransceiverDirection
{
"sendrecv",
"sendonly",
"recvonly",
"inactive"
};
RTCRtpTransceiverDirection Enumeration description |
|
---|---|
sendrecv |
The 's
sender will offer to send RTP, and will send RTP if the remote peer accepts and
sender.getParameters().encodings[i].active is "true" for any value of i. The
's
will offer to receive RTP, and will receive RTP if the remote peer accepts. |
sendonly |
The 's
sender will offer to send RTP, and will send RTP if the remote peer accepts and
sender.getParameters().encodings[i].active is "true" for any value of i. The
's
will not offer to receive RTP, and will not receive RTP. |
recvonly |
The 's
will not offer to send RTP, and will not send RTP. The 's
will offer to receive RTP, and will receive RTP if the remote peer accepts. |
inactive |
The 's
will not offer to send RTP, and will not send RTP. The 's
will not offer to receive RTP, and will not receive RTP. |
An application can reject incoming
objects by calling MediaStreamTrack
.RTCRtpTransceiver
.stop()
To process the remote track for an incoming media description [JSEP] (section 5.9.) given
RTCRtpTransceiver
transceiver, the user agent
MUST run the following steps:
Let connection be the
object associated with
transceiver.RTCPeerConnection
Let streams be a list of
MediaStream
objects that the media description indicates the
belongs to.MediaStreamTrack
Add track to all MediaStream
objects in streams.
This will result in an addtrack event being fired at each MediaStream as described in [GETUSERMEDIA].
Fire an event named
with transceiver,
track, and streams at the
connection object.track
The RTCRtpSender
interface allows an application to control how a given MediaStreamTrack
is encoded and transmitted to a remote peer. When setParameters
is called on an
object, the encoding is changed appropriately.RTCRtpSender
When sending media, the sender may need to rescale or resample the media to meet various requirements including the envelope negotiated by SDP. When resizing video, the source video is first centered relative to the desired video then scaled down the minimum amount such that the video fully covers the desired size, then finally cropped to the destination size. The video remains centered while scaling and cropping. For example, if the source video was 1280 by 720, and the max size that could be sent was 640 by 480, the video would be scaled down by 1.5 and 160 columns of pixels on both the right and left sides of the source video would be cropped off. This algorithm is designed to minimize occurrence of images with with letter box or or pillow boxing. The media MUST NOT be upscaled to create fake data that did not occur in the input source.
To create an RTCRtpSender with a
, track, a list of
MediaStreamTrack
MediaStream
objects, streams, and optionally a list of
objects, sendEncodings, run the following steps:RTCRtpEncodingParameters
Let sender be a new
object.RTCRtpSender
Set sender.track to track.
Let sender have an [[associated
MediaStreams]] internal slot, representing a list of
MediaStream
objects that the
object of this sender is associated with.MediaStreamTrack
Set sender's [[associated MediaStreams]] slot to streams.
Let sender have a [[send encodings]] internal slot, representing a list of
objects, initialized to an empty list.RTCRtpEncodingParameters
If sendEncodings is given as input to this algorithm, set the [[send encodings]] slot to sendEncodings.
Return sender.
interface RTCRtpSender
{
readonly attribute MediaStreamTrack
? track
;
readonly attribute RTCDtlsTransport
? transport
;
readonly attribute RTCDtlsTransport
? rtcpTransport
;
static RTCRtpCapabilities
getCapabilities(DOMString kind);
Promise<void> setParameters
(optional RTCRtpParameters
parameters);
RTCRtpParameters
getParameters();
Promise<void> replaceTrack
(MediaStreamTrack
withTrack);
};
track
of type MediaStreamTrack
, readonly ,
nullableThe track
attribute is the track that is associated with this
object. If
RTCRtpSender
track
is ended, or if
track
.muted is set to true
, the RTCRtpSender
sends silence (audio) or a black frame (video). If track
is set to null then the RTCRtpSender
does not send.
transport
of type RTCDtlsTransport
, readonly,
nullableThe transport
attribute is the transport over which media from track
is sent in the form of RTP packets. Prior to construction of the
object, the
RTCDtlsTransport
transport
attribute will be null. When bundling is used, multiple
objects will share one RTCRtpSender
transport
and will all send RTP and RTCP over the same transport.
rtcpTransport
of type RTCDtlsTransport
, readonly ,
nullableThe rtcpTransport
attribute is the transport over which RTCP is sent and received. Prior to construction of the
object, the
RTCDtlsTransport
rtcpTransport
attribute will be null. When RTCP mux is used (or bundling, which mandates RTCP mux),
rtcpTransport
will be null, and both RTP and RTCP traffic will flow over the transport described by
transport
.
getCapabilities
, staticThe getCapabilities()
method returns the most optimist view on the capabilities of the system for sending media of the given kind. It does not reserve any resources, ports, or other state but is meant to provide a way to discover the types of capabilities of the browser including which codecs may be supported.
These capabilities provide generally persistent cross-origin information on the device and thus increases the fingerprinting surface of the application. In privacy-sensitive contexts, browsers can consider mitigations such as reporting only a common subset of the capabilities.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
kind | DOMString |
✘ | ✘ |
RTCRtpCapabilities
setParameters
The setParameters
method updates how
track
is encoded and transmitted to a remote peer.
When the setParameters
method is called, the user agent MUST run the following steps:
RTCRtpSender
object on which
setParameters
is invoked.RTCRtpTransceiver
object associated with sender.sender.getParameters().encodings.length
.transceiver.stopped
is
true
, abort these steps and return a promise rejected with a newly
created
InvalidStateError
.parameters.encodings.length
is different from N, or if any parameter in the parameters argument, marked as a Read-only parameter, has a value that is different from the corresponding parameter value returned from
sender.getParameters()
, abort these steps and return a promise rejected with a newly
created
InvalidModificationError
. Note that this also applies to transactionId.scaleResolutionDownBy
parameter in the
parameters argument has a value less than 1.0, abort these steps and return a promise rejected with a newly
created
RangeError
.RTCRtpSender
's internal
transactionId slot to a previously unused value.
undefined
.If codecs are reordered, the new order indicates the preference for sending, with the first codec being the codec with highest preference. If a codec is removed, that codec will not be used to send. The effect of reordering or removing codecs lasts until the codecs are renegotiated. After the codecs are renegotiated, they are set to the value negotiated, and
setParameters
needs to be called again to re-apply codec preferences.
setParameters
does not cause SDP renegotiation and can only be used to change what the media stack is sending or receiving within the envelope negotiated by Offer/Answer. The attributes in the
dictionary are designed to not enable this, so attributes like
RTCRtpParameters
ssrc
that cannot be changed are read only. Other things, like bitrate, are controlled using limits such as
maxBitrate
, where the user agent needs to ensure it does not exceed the maximum bitrate specified by
maxBitrate
, while at the same time making sure it satisfies constraints on bitrate specified in other places such as the SDP.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
parameters | RTCRtpParameters |
✘ | ✔ |
Promise<void>
getParameters
The getParameters()
method returns the
object's current parameters for how RTCRtpSender
track
is encoded and transmitted to a remote
. It may used with
RTCRtpReceiver
setParameters
to change the parameters in the following way:
var params = sender.getParameters();
// ... make changes to RTCRtpParameters
params.encodings[0].active = false;
sender.setParameters(params)
RTCRtpParameters
replaceTrack
Attempts to replace the track being sent with another track provided (or with a null track), without renegotiation.
To avoid track identifiers changing on the remote receiving end when a track is replaced, the sender MUST retain the original track identifier and stream associations and use these in subsequent negotiations.
When the replaceTrack
method is invoked, the user agent MUST run the following steps:
RTCRtpSender
object on which
replaceTrack
is invoked.Let transceiver be the
object associated with
sender.RTCRtpTransceiver
Let connection be the
object that created
sender.RTCPeerConnection
If connection's [[isClosed]] slot is
true
, return a promise rejected with a newly
created
InvalidStateError
and abort these steps.
If transceiver.stopped
is
true
, return a promise rejected with a newly
created InvalidStateError
.
Let withTrack be the argument to this method.
If withTrack
is non-null and
withTrack.kind
differs from the
transceiver kind of transceiver, return a promise rejected with a newly
created
TypeError
.
If transceiver is not yet associated with a
media description [JSEP] (section 3.4.1.), then set
sender's
attribute to
withTrack, and return a promise resolved with
track
undefined
.
Let p be a new promise.
Run the following steps in parallel:
Determine if negotiation is needed to transmit
withTrack in place of the sender's existing track. Negotiation is not needed if withTrack is null or if the sender's existing track is ended (which appears as though the track was muted). Ignore which MediaStream
the track resides in and the id
attribute of the track in this determination. If negotiation is needed, then reject p with a newly
created
InvalidModificationError
and abort these steps.
If withTrack is null, have the sender stop sending, without negotiating. Otherwise, have the sender switch seamlessly to transmitting withTrack instead of the sender's existing track, without negotiating.
Queue a task that sets sender's
attribute to withTrack, and resolves
p with track
undefined
.
Return p.
Changing dimensions and/or frame rates might not require negotiation. Cases that may require negotiation include:
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
withTrack | MediaStreamTrack |
✔ | ✘ |
Promise<void>
dictionary RTCRtpParameters
{
DOMString transactionId
;
sequence<RTCRtpEncodingParameters
> encodings
;
sequence<RTCRtpHeaderExtensionParameters
> headerExtensions
;
RTCRtcpParameters
rtcp
;
sequence<RTCRtpCodecParameters
> codecs
;
RTCDegradationPreference
degradationPreference
= "balanced";
};
RTCRtpParameters
MemberstransactionId
of type DOMStringAn unique identifier for the last set of parameters applied. Ensures that setParameters can only be called based on a previous getParameters, and that there are no intervening changes.
encodings
of type sequence<RTCRtpEncodingParameters
>A sequence containing parameters for RTP encodings of media.
headerExtensions
of type sequence<RTCRtpHeaderExtensionParameters
>A sequence containing parameters for RTP header extensions.
rtcp
of type RTCRtcpParameters
Parameters used for RTCP.
codecs
of type sequence<RTCRtpCodecParameters
>A sequence containing the media codecs that an
will choose from, as well as entries for RTX, RED and FEC mechanisms. Corresponding to each media codec where retransmission via RTX is enabled, there will be an entry in RTCRtpSender
codecs[]
with a mimeType
attribute indicating retransmission via "audio/rtx" or "video/rtx", and an sdpFmtpLine
attribute (providing the "apt" and "rtx-time" parameters). When using the
setParameters
method, the codecs
sequence from the corresponding call to
getParameters
can be reordered and entries can be removed, but entries cannot be added, and the
RTCRtpCodecParameters
dictionary members cannot be modified.
degradationPreference
of type
RTCDegradationPreference
,
defaulting to "balanced"
When bandwidth is constrained and the
RtpSender
needs to choose between degrading resolution or degrading framerate,
degradationPreference
indicates which is preferred.
dictionary RTCRtpEncodingParameters
{
unsigned long ssrc
;
RTCRtpRtxParameters
rtx
;
RTCRtpFecParameters
fec
;
RTCDtxStatus
dtx
;
boolean active
;
RTCPriorityType
priority
;
unsigned long maxBitrate
;
unsigned long maxFramerate
;
DOMString rid
;
double scaleResolutionDownBy
= 1;
};
RTCRtpEncodingParameters
Membersssrc
of type unsigned longThe SSRC of the RTP source stream of this encoding (non-RTX, non-FEC RTP stream). Read-only parameter.
rtx
of type RTCRtpRtxParameters
The parameters used for RTX, or unset if RTX is not being used.
fec
of type RTCRtpFecParameters
The parameters used for FEC, or unset if FEC is not being used.
dtx
of type RTCDtxStatus
For an
, indicates whether discontinuous transmission will be used. Setting it to
RTCRtpSender
disabled
causes discontinuous transmission to be turned off. Setting it to enabled
causes discontinuous transmission to be turned on if it was negotiated (either via a codec-specific parameter or via negotiation of the CN codec). This attribute is ignored by a video sender.
active
of type booleanFor an
, indicates that this encoding is actively being sent. Setting it to RTCRtpSender
false
causes this encoding to no longer be sent. Setting it to true
causes this encoding to be sent. For an
, a value of RTCRtpReceiver
true
indicates that this encoding is being decoded. A value of false
indicates this encoding is no longer being decoded.
priority
of type RTCPriorityType
Indicates the priority of this encoding. It is specified in [ RTCWEB-TRANSPORT], Section 4.
maxBitrate
of type unsigned longIndicates the maximum bitrate that can be used to send this encoding. The encoding may also be further constrained by other limits (such as maxFramerate or per-transport or per-session bandwidth limits) below the maximum specified here. maxBitrate is the Transport Independent Application Specific Maximum (TIAS) bandwidth defined in [RFC3890] Section 6.2.2, which is the maximum bandwidth needed without counting IP or other transport layers like TCP or UDP.
maxFramerate
of type unsigned longIndicates the maximum framerate that can be used to send this encoding.
rid
of type DOMStringIf set, this RTP encoding will be sent with the RID header extension as defined by [JSEP] (section 5.2.1.). The RID is not modifiable via
setParameters
. It can only be set or modified in
addTransceiver
.
scaleResolutionDownBy
of type
double, defaulting to
1.0
If the sender's kind
is "video", the video's resolution will be scaled down in each dimension by the given value before sending. For example, if the value is 2.0, the video will be scaled down by a factor of 2 in each dimension, resulting in sending a video of one quarter the size. If the value is 1.0, the video will not be affected. The value must be greater than or equal to 1.0.
Usage of the attributes is defined in the table below:
Attribute | Type | Receiver/Sender | Read/Write |
---|---|---|---|
ssrc | unsigned long |
Receiver/Sender | Read-only |
fec |
|
Receiver/Sender | Read-only |
dtx |
|
Sender | Read/Write |
rtx |
|
Receiver/Sender | Read-only |
active | boolean |
Sender | Read/Write |
priority |
|
Sender | Read/Write |
maxBitrate | unsigned long |
Sender | Read/Write |
maxFramerate | unsigned long |
Sender | Read/Write |
scaleResolutionDownBy | double |
Sender | Read/Write |
rid | DOMString |
Receiver/Sender | Read-only |
enum RTCDtxStatus
{
"disabled",
"enabled"
};
RTCDtxStatus Enumeration description |
|
---|---|
disabled |
Discontinuous transmission is disabled. |
enabled |
Discontinuous transmission is enabled if negotiated. |
enum RTCDegradationPreference
{
"maintain-framerate",
"maintain-resolution",
"balanced"
};
RTCDegradationPreference Enumeration description |
|
---|---|
maintain-framerate |
Degrade resolution in order to maintain framerate. |
maintain-resolution |
Degrade framerate in order to maintain resolution. |
balanced |
Degrade a balance of framerate and resolution. |
dictionary RTCRtpRtxParameters
{
unsigned long ssrc
;
};
RTCRtpRtxParameters
Membersssrc
of type unsigned longThe SSRC of the RTP stream for RTX. Read-only parameter.
dictionary RTCRtpFecParameters
{
unsigned long ssrc
;
};
RTCRtpFecParameters
Membersssrc
of type unsigned longThe SSRC of the RTP stream for FEC. Read-only parameter.
dictionary RTCRtcpParameters
{
DOMString cname
;
boolean reducedSize
;
};
RTCRtcpParameters
Memberscname
of type DOMStringThe Canonical Name (CNAME) used by RTCP (e.g. in SDES messages). Read-only parameter.
reducedSize
of type booleanWhether reduced size RTCP [RFC5506] is configured (if true) or compound RTCP as specified in [RFC3550] (if false). Read-only parameter.
dictionary RTCRtpHeaderExtensionParameters
{
DOMString uri
;
unsigned short id
;
boolean encrypted
;
};
RTCRtpHeaderExtensionParameters
Membersuri
of type DOMStringThe URI of the RTP header extension, as defined in [ RFC5285]. Read-only parameter.
id
of type unsigned shortThe value put in the RTP packet to identify the header extension. Read-only parameter.
encrypted
of type booleanWhether the header extension is encryted or not. Read-only parameter.
dictionary RTCRtpCodecParameters
{
unsigned short payloadType
;
DOMString mimeType
;
unsigned long clockRate
;
unsigned short channels
= 1;
DOMString sdpFmtpLine
;
};
RTCRtpCodecParameters
MemberspayloadType
of type unsigned shortThe RTP payload type. This value can be set to control which codec should be used to send a given encoding.
mimeType
of type DOMStringThe codec MIME media type/subtype. Valid media types and subtypes are listed in [IANA-RTP-2].
clockRate
of type unsigned longThe codec clock rate expressed in Hertz.
channels
of type unsigned short, defaulting to
1
The number of channels (mono=1, stereo=2).
sdpFmtpLine
of type DOMStringThe "format specific parameters" field from the "a=fmtp" line in the SDP corresponding to the codec, if one exists, as defined by [JSEP] (section 5.7.). For an
, these parameters come from the remote description, and for an
RTCRtpSender
, they come from the local description.
RTCRtpReceiver
dictionary RTCRtpCapabilities
{
sequence<RTCRtpCodecCapability
> codecs
;
sequence<RTCRtpHeaderExtensionCapability
> headerExtensions
;
};
RTCRtpCapabilities
Memberscodecs
of type sequence<RTCRtpCodecCapability
>Supported media codecs as well as entries for RTX, RED and FEC mechanisms. There will only be a single entry in
codecs[]
for retransmission via RTX.
headerExtensions
of type sequence<RTCRtpHeaderExtensionCapability
>Supported RTP header extensions.
dictionary RTCRtpCodecCapability
{
DOMString mimeType
;
unsigned long clockRate
;
unsigned short channels
= 1;
DOMString sdpFmtpLine
;
};
RTCRtpCodecCapability
MembersThe RTCRtpCodecCapability
dictionary provides information about codec capabilities. Only capability combinations that would utilize distinct payload types in a generated SDP offer are provided. For example:
mimeType
of type DOMStringThe codec MIME media type/subtype. Valid media types and subtypes are listed in [IANA-RTP-2].
clockRate
of type unsigned longThe codec clock rate expressed in Hertz.
channels
of type unsigned short, defaulting to
1
The maximum number of channels (mono=1, stereo=2).
sdpFmtpLine
of type DOMStringThe "format specific parameters" field from the "a=fmtp" line in the SDP corresponding to the codec, if one exists.
dictionary RTCRtpHeaderExtensionCapability
{
DOMString uri
;
};
RTCRtpHeaderExtensionCapability
Membersuri
of type DOMStringThe URI of the RTP header extension, as defined in [ RFC5285].
RTCRtpReceiver
Interface
The RTCRtpReceiver
interface allows an application to inspect the receipt of a MediaStreamTrack
.
To create an RTCRtpReceiver with kind, kind, and optionally an id string, id, run the following steps:
Let receiver be a new
object.RTCRtpReceiver
Let track be a new
object [GETUSERMEDIA]. The source of track is a
remote source provided by receiver.MediaStreamTrack
Initialize track.kind to kind.
If an id string, id, was given as input to this algorithm, initialize track.id to id. (Otherwise the value generated when track was created will be used.)
Initialize track.label to the result of concatenating the string "remote "
with kind.
Initialize track.readyState to live
.
Initialize track.muted to true
. See the
section about how the
MediaStreamTrack
muted
attribute reflects if a
is receiving media data or not.
MediaStreamTrack
Set receiver.track to track.
Return receiver.
interface RTCRtpReceiver
{
readonly attribute MediaStreamTrack
track
;
readonly attribute RTCDtlsTransport
? transport
;
readonly attribute RTCDtlsTransport
? rtcpTransport
;
static RTCRtpCapabilities
getCapabilities(DOMString kind);
RTCRtpParameters
getParameters();
sequence<RTCRtpContributingSource
> getContributingSources
();
};
track
of type MediaStreamTrack
, readonlyThe track
attribute is the track that is associated with this
object receiver. When one of the SSRCs for RTP source media streams received by receiver is removed (either due to reception of a BYE or via timeout), the RTCRtpReceiver
mute
event is fired at
track
. If and when packets are received again, the unmute
event is fired at track
.
Note that track.stop()
is final, although clones are not affected. Since
receiver.track.stop()
does not implicitly stop receiver, Receiver Reports continue to be sent.
transport
of type RTCDtlsTransport
, readonly,
nullableThe transport
attribute is the transport over which media for the receiver's track
is received in the form of RTP packets. Prior to construction of the
object, the
RTCDtlsTransport
transport
attribute will be null. When bundling is used, multiple
objects will share one RTCRtpReceiver
transport
and will all receive RTP and RTCP over the same transport.
rtcpTransport
of type RTCDtlsTransport
, readonly ,
nullableThe rtcpTransport
attribute is the transport over which RTCP is sent and received. Prior to construction of the
object, the RTCDtlsTransport
rtcpTransport
attribute will be null. When RTCP mux is used (or bundling, which mandates RTCP mux),
rtcpTransport
will be null, and both RTP and RTCP traffic will flow over transport
.
getCapabilities
, staticThe getCapabilities()
method returns the most optimistic view of the capabilities of the system for receiving media of the given kind. It does not reserve any resources, ports, or other state but is meant to provide a way to discover the types of capabilities of the browser including which codecs may be supported.
These capabilities provide generally persistent cross-origin information on the device and thus increases the fingerprinting surface of the application. In privacy-sensitive contexts, browsers can consider mitigations such as reporting only a common subset of the capabilities.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
kind | DOMString |
✘ | ✘ |
RTCRtpCapabilities
getParameters
The getParameters()
method returns the RTCRtpReceiver
object's current parameters for how track
is decoded.
RTCRtpParameters
getContributingSources
Returns an
for each unique CSRC or SSRC received by this RTCRtpReceiver in the last 10 seconds.RTCRtpContributingSource
sequence<RTCRtpContributingSource>
The RTCRtpContributingSource
objects contain information about a given contributing source, including the time the most recent time a packet was received from the source. The browser MUST keep information from RTP packets received in the previous 10 seconds. Each time an RTP packet is received, the
objects are updated. If the RTP packet contains CSRCs, then the
RTCRtpContributingSource
objects corresponding to those CSRCs are updated. If the RTP packet contains no CSRCs, then the
RTCRtpContributingSource
object corresponding to the SSRC is updated.RTCRtpContributingSource
interface RTCRtpContributingSource
{
readonly attribute DOMHighResTimeStamp timestamp
;
readonly attribute unsigned long source
;
readonly attribute byte? audioLevel
;
readonly attribute boolean? voiceActivityFlag
;
};
timestamp
of type DOMHighResTimeStamp, readonlyThe timestamp of type DOMHighResTimeStamp [HIGHRES-TIME], indicating the time of reception of the most recent RTP packet containing the source. The timestamp is defined in [ HIGHRES-TIME] and corresponds to a local clock.
source
of type unsigned long, readonlyThe CSRC or SSRC value of the contributing source.
audioLevel
of type byte, readonly , nullableThe audio level contained in the last RTP packet received from this source. If the source was set from an SSRC, this will be the level value defined in [RFC6464]. If an RFC 6464 extension header is not present, the browser will compute the value as if it had come from RFC 6464 and use that. If the source was set from a CSRC, this will be the level value defined in [ RFC6465]. RFC 6464 and 6465 define the level as a integral value from 0 to 127 representing the audio level in negative decibels relative to the loudest signal that they system could possibly encode. Thus, 0 represents the loudest signal the system could possibly encode, and 127 represents silence.
voiceActivityFlag
of type boolean, readonly , nullableWhether the last RTP packet received from this source contains voice activity (true) or not (false). Since the "V" bit is supported in [RFC6464] but not [RFC6465], the voiceActivityFlag attribute will only be set for RTP packets received from peers enabling the client-mixer header extension with the "vad" extension set to "on".
RTCRtpTransceiver
Interface
The
interface represents a combination of an RTCRtpTransceiver
and an
RTCRtpSender
that share a common
RTCRtpReceiver
mid
.
The transceiver kind of an
is defined by the kind of the associated RTCRtpTransceiver
's
RTCRtpReceiver
object.MediaStreamTrack
To create an RTCRtpTransceiver with an
object, receiver, and an
RTCRtpReceiver
object, sender, run the following steps:RTCRtpSender
Let transceiver be a new
object.RTCRtpTransceiver
Set transceiver.sender to sender.
Set transceiver.receiver to receiver.
Set transceiver.stopped to false
.
Return transceiver.
interface RTCRtpTransceiver
{
readonly attribute DOMString? mid
;
[SameObject]
readonly attribute RTCRtpSender
sender
;
[SameObject]
readonly attribute RTCRtpReceiver
receiver
;
readonly attribute boolean stopped
;
readonly attribute RTCRtpTransceiverDirection
direction
;
readonly attribute RTCRtpTransceiverDirection
? currentDirection
;
void setDirection
(RTCRtpTransceiverDirection
direction);
void stop
();
void setCodecPreferences
(sequence<RTCRtpCodecCapability
> codecs);
};
mid
of type DOMString, readonly , nullableThe mid
attribute is the mid
negotatiated and present in the local and remote descriptions as defined in [JSEP] (section 5.2.1. and section 5.3.1.). Before negotiation is complete, the mid
value may be null. After rollbacks, the value may change from a non-null value to null.
sender
of type RTCRtpSender
, readonlyThe sender
attribute is the
corresponding to the RTP media that may be sent with mid = RTCRtpSender
.mid
receiver
of type RTCRtpReceiver
, readonlyThe receiver
attribute is the
corresponding to the RTP media that may be received with mid = RTCRtpReceiver
.mid
stopped
of type boolean, readonlyThe stopped
attribute indicates that the sender of this transceiver will no longer send, and that the receiver will no longer receive. It is true if either stop
has been called or if setting the local or remote description has caused the RTCTransceiver
to be stopped.
direction
of type RTCRtpTransceiverDirection
,
readonlyAs defined in [JSEP] (section 4.2.4.), the
direction attribute indicates the preferred direction of this transceiver, which will be used in calls to
and createOffer
. The value of
direction does not change except due to calls to
createAnswer
.setDirection
currentDirection
of type RTCRtpTransceiverDirection
,
readonly, nullableAs defined in [JSEP] (section 4.2.5), the
currentDirection attribute indicates the current direction negotiated for this transceiver. The value of
currentDirection is independent of the value of
RTCRtpEncodingParameters.
since one cannot be deduced from the other. If this transceiver has never been represented in an offer/answer exchange, or if the transceiver is
active
, currentDirection is null.
stopped
setDirection
The setDirection
method sets the direction of the RTCRtpTransceiver
. Calls to setDirection()
do not take effect immediately. Instead, future calls to createOffer
and createAnswer
mark the corresponding media description as sendrecv
, sendonly
,
recvonly
or inactive
as defined in
[JSEP] (section 5.2.2. and section 5.3.2.). Calling
setDirection()
updates the
negotiation-needed flag for the
RTCRtpTransceiver
's associated
.RTCPeerConnection
When this method is invoked, the user agent MUST run the following steps:
Let transceiver be the
object on which the method is invoked.
RTCRtpTransceiver
Let newDirection be the argument to setDirection
.
If newDirection is equal to
transceiver.direction
, abort these steps.
If newDirection has a value other than sendrecv
, sendonly
,
recvonly
or inactive
,
throw an InvalidModificationError
.
Set transceiver.direction
to newDirection.
Let connection be the
object associated with transceiver.RTCPeerConnection
Update the negotiation-needed flag for connection.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
direction |
RTCRtpTransceiverDirection |
✘ | ✘ |
void
stop
The stop
method irreversibly stops the
. The sender of this transceiver will no longer send, the receiver will no longer receive. Calling
RTCRtpTransceiver
stop()
updates the
negotiation-needed flag for the
RTCRtpTransceiver
's associated
.RTCPeerConnection
Stopping a transceiver will cause future calls to createOffer
to generate a zero port in the media description for the corresponding transceiver, as defined in
[JSEP] (section 4.2.1).
When this method is invoked, to stop the RTCRtpTransceiver transceiver, the user agent MUST run the following steps:
If transceiver.stopped
is
true
, abort these steps.
Let connection be the
object on which the transceiver is to be stopped.RTCPeerConnection
If connection's [[isClosed]] slot is
true
, throw an
InvalidStateError
.
Let sender be transceiver.sender
.
Let receiver be transceiver.receiver
.
Stop sending media with sender.
Send an RTCP BYE for each SSRC in
transceiver.sender.getParameters().encodings[i].ssrc
,
transceiver.sender.getParameters().encodings[i].fec.ssrc
and
transceiver.sender.getParameters().encodings[i].rtx.ssrc
where i goes from 0 to
transceiver.sender.getParameters().encodings.length-1
.
Stop receiving media with receiver.
receiver.track
is now said to be
ended.
Set transceiver.stopped
to true
.
Update the negotiation-needed flag for connection.
When a remote description is applied with a zero port in the media description for the corresponding transceiver, as defined in
[JSEP] (section 4.2.2), the user agent MUST run the above steps as if stop
had been called. In addition, since
transceiver.receiver.track
has ended, the steps described in track ended
MUST be followed.
void
setCodecPreferences
The setCodecPreferences
method overrides the default codec preferences used by the user agent. When generating a session description using either
createOffer
or createAnswer
, the
user agent MUST use the indicated codecs, in the order specified in the codecs argument, for the media section corresponding to this RTCRtpTransceiver
. Note that calls to createAnswer
will use only the common subset of these codecs and the codecs that appear in the offer.
This method allows applications to disable the negotiation of specific codecs. It also allows an application to cause a remote peer to prefer the codec that appears first in the list for sending.
Codec preferences remain in effect for all calls to
createOffer
and createAnswer
that include this RTCRtpTransceiver
until this method is called again. Setting codecs to an empty sequence resets codec preferences to any default value.
The codecs
sequence passed into
setCodecPreferences
can only contain codecs that are returned by RTCRtpSender.getCapabilities(kind)
or
RTCRtpReceiver.getCapabilities(kind)
, where
kind
is the kind of the
RTCRtpTransceiver
on which the method is called. Additionally, the RTCRtpCodecParameters
dictionary members cannot be modified. If codecs
does not fulfill these requirements, the user agent MUST throw an InvalidAccessError.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
codecs |
sequence<RTCRtpCodecCapability> |
✘ | ✘ |
void
Together, the setDirection
and
replaceTrack
methods enable developers to implement "hold" scenarios.
To send music to a peer and cease rendering received audio (music-on-hold):
// Assume we have an audio transceiver and a music track named musicTrack
audio.sender.replaceTrack(musicTrack);
// Mute received audio
audio.receiver.track.enabled = "false";
// Set the direction to send-only (requires negotiation)
audio.setDirection("sendonly");
To respond to a remote peer's "sendonly" offer:
// Stop sending audio
audio.sender.replaceTrack(null);
// Set the direction recvonly (requires negotiation)
audio.setDirection("recvonly");
// Apply the sendonly offer, and then call createAnswer
// and send a recvonly answer
pc.setRemoteDescription(sendonlyOffer).then(doAnswer).catch(onSignalingError);
To stop sending music and send audio captured from a microphone, as well to render received audio:
//assume we have an audio transceiver and a microphone track named micTrack
audio.sender.replaceTrack(micTrack);
// Unmute received audio
audio.receiver.track.enabled = "true";
// // Set the direction to sendrecv (requires negotiation)
audio.setDirection("sendrecv");
To respond to being taken off hold by a remote peer:
// Start sending audio
audio.sender.replaceTrack(micTrack);
// Set the direction sendrecv (requires negotiation)
audio.setDirection("sendrecv");
// Apply the sendrecv offer, and then call createAnswer
// and send a sendrecv answer
pc.setRemoteDescription(sendrecvOffer).then(doAnswer).catch(onSignalingError);
RTCDtlsTransport
Interface
The
interface allows an application access to information about the Datagram Transport Layer Security (DTLS) transport over which RTP and RTCP packets are sent and received by RTCDtlsTransport
and
RTCRtpSender
objects, as well other data such as SCTP packets sent and received by data channels. In particular, DTLS adds security to an underlying transport, and the
RTCRtpReceiver
RTCDtlsTransport
interface allows access to information about the underlying transport and the security added.
objects are constructed as a result of calls to RTCDtlsTransport
setLocalDescription()
and
setRemoteDescription()
.
interface RTCDtlsTransport
{
readonly attribute RTCIceTransport
transport
;
readonly attribute RTCDtlsTransportState
state
;
sequence<ArrayBuffer> getRemoteCertificates
();
attribute EventHandler onstatechange
;
};
transport
of type RTCIceTransport
, readonlyThe transport
attribute is the underlying transport that is used to send and receive packets. The underlying transport may not be shared between multiple active
objects.RTCDtlsTransport
state
of type RTCDtlsTransportState
, readonlyThe state
attribute MUST return the state of the transport.
onstatechange
of type EventHandlerstatechange
, MUST be fired any time the
RTCDtlsTransport
state changes.
getRemoteCertificates
Returns the certificate chain in use by the remote side, with each certificate encoded in binary Distinguished Encoding Rules (DER) [X690]. getRemoteCertificates()
will return an empty list prior to selection of the remote certificate, which will be completed by the time
transitions to "connected".
RTCDtlsTransportState
sequence<ArrayBuffer>
RTCDtlsTransportState
Enumenum RTCDtlsTransportState
{
"new",
"connecting",
"connected",
"closed",
"failed"
};
Enumeration description | |
---|---|
new |
DTLS has not started negotiating yet. |
connecting |
DTLS is in the process of negotiating a secure connection. |
connected |
DTLS has completed negotiation of a secure connection. |
closed |
The transport has been closed. |
failed |
The transport has failed as the result of an error (such as a failure to validate the remote fingerprint). |
The RTCDtlsFingerprint
object includes the hash function algorithm and certificate fingerprint as described in [
RFC4572].
dictionary RTCDtlsFingerprint
{
DOMString algorithm
;
DOMString value
;
};
algorithm
of type DOMStringOne of the the hash function algorithms defined in the 'Hash function Textual Names' registry, initially specified in [ RFC4572] Section 8. As noted in [JSEP] Section 5.2.1, the digest algorithm used for the fingerprint matches that used in the certificate signature.
value
of type DOMStringThe value of the certificate fingerprint in lowercase hex string as expressed utilizing the syntax of 'fingerprint' in [ RFC4572] Section 5.
RTCIceTransport
Interface
The
interface allows an application access to information about the ICE transport over which packets are sent and received. In particular, ICE manages peer-to-peer connections which involve state which the application may want to access.
RTCIceTransport
objects are constructed as a result of calls to RTCIceTransport
setLocalDescription()
and
setRemoteDescription()
. The underlying ICE state is managed by the ICE agent; as such, the state of an
changes when the ICE Agent provides indications to the user agent as described below.RTCIceTransport
When the ICE Agent indicates that it began gathering a
generation of candidates for an
, the user agent MUST queue a task that runs the following steps:RTCIceTransport
Let connection be the
object associated with this
ICE Agent.RTCPeerConnection
If connection's [[isClosed]] slot is
true
, abort these steps.
Let transport be the
for which candidate gathering began.RTCIceTransport
Set transport's
to gatheringState
.gathering
Fire a simple event named
at transport.gatheringstatechange
Update the ICE gathering state of connection.
When the ICE Agent indicates that it finished gathering a
generation of candidates for an
, the user agent MUST queue a task that runs the following steps:RTCIceTransport
Let connection be the
object associated with this
ICE Agent.RTCPeerConnection
If connection's [[isClosed]] slot is
true
, abort these steps.
Let transport be the
for which candidate gathering finished.RTCIceTransport
Create an
instance
newCandidate, with RTCIceCandidate
and
sdpMid
set to the values associated with this
sdpMLineIndex
, with
RTCIceTransport
set to the ufrag of the generation of candidates for which gathering finished, with
ufrag
set to an empty string, and with all other nullable members set to null.candidate
Fire an event named
with
newCandidate at connection.icecandidate
If another generation of candidates is still being gathered, abort these steps.
Set transport's
to gatheringState
.complete
Fire a simple event named
at transport.gatheringstatechange
Update the ICE gathering state of connection.
When the ICE Agent indicates that a new ICE candidate is available for an
, either by taking one from the ICE candidate pool or gathering it from scratch, the user agent MUST queue a task that runs the following steps:RTCIceTransport
Let connection be the
object associated with this
ICE Agent.RTCPeerConnection
If connection's [[isClosed]] slot is
true
, abort these steps.
Let transport be the
for which this candidate is being made available.RTCIceTransport
Add the candidate to connection's
.localDescription
Create an
instance to represent the candidate. Let newCandidate be that object.RTCIceCandidate
Add newCandidate to transport's set of local candidates.
Fire an event named
with
newCandidate at connection.icecandidate
When the ICE Agent indicates that the
for an
RTCIceTransportState
has changed, the user agent MUST queue a task that runs the following steps:RTCIceTransport
Let connection be the
object associated with this
ICE Agent.RTCPeerConnection
If connection's [[isClosed]] slot is
true
, abort these steps.
Let transport be the
whose state is changing.RTCIceTransport
Let newState be the new indicated
.
RTCIceTransportState
Set transport's
to newState.state
Fire a simple event named
at
transport.statechange
Update the ICE connection state of connection.
Update the connection state of connection.
When the ICE Agent indicates that the selected candidate pair for an
has changed, the user agent
MUST queue a task that runs the following steps:RTCIceTransport
Let connection be the
object associated with this
ICE Agent.RTCPeerConnection
If connection's [[isClosed]] slot is
true
, abort these steps.
Let transport be the
whose selected candidate pair is changing.RTCIceTransport
Let newCandidatePair be a newly created
representing the indicated pair if one is selected, and RTCIceCandidatePair
null
otherwise.
Set transport's selected candidate pair to newCandidatePair.
Fire a simple event named
at
transport.selectedcandidatepairchange
interface RTCIceTransport
{
readonly attribute RTCIceRole
role
;
readonly attribute RTCIceComponent
component
;
readonly attribute RTCIceTransportState
state
;
readonly attribute RTCIceGathererState
gatheringState
;
sequence<RTCIceCandidate
> getLocalCandidates
();
sequence<RTCIceCandidate
> getRemoteCandidates
();
RTCIceCandidatePair
? getSelectedCandidatePair
();
RTCIceParameters
? getLocalParameters
();
RTCIceParameters
? getRemoteParameters
();
attribute EventHandler onstatechange
;
attribute EventHandler ongatheringstatechange
;
attribute EventHandler onselectedcandidatepairchange
;
};
role
of type RTCIceRole
, readonlyThe role
attribute MUST return the ICE role of the transport.
component
of type RTCIceComponent
, readonlyThe component
attribute MUST return the ICE component of the transport. When RTP/RTCP mux is used, a single
transports both RTP and RTCP and RTCIceTransport
component
is set to "RTP".
state
of type RTCIceTransportState
, readonlyThe state
attribute MUST return the state of the transport.
gatheringState
of type RTCIceGatheringState
, readonlyThe gathering
state
attribute MUST return the gathering state of the transport.
onstatechange
of type EventHandlerstatechange
, MUST be fired any time the
RTCIceTransport
state changes.
ongatheringstatechange
of type
EventHandlergatheringstatechange
, MUST be fired any time the RTCIceTransport
gathering state changes.
onselectedcandidatepairchange
of type
EventHandlerselectedcandidatepairchange
, MUST be fired any time the RTCIceTransport
's selected candidate pair changes.getLocalCandidates
Returns a sequence describing the local ICE candidates gathered for this
and sent in
RTCIceTransport
onicecandidate
sequence<RTCIceCandidate>
getRemoteCandidates
Returns a sequence describing the remote ICE candidates received by this
via
RTCIceTransport
addIceCandidate()
sequence<RTCIceCandidate>
getSelectedCandidatePair
Returns the selected candidate pair on which packets are sent, or null
if there is no such pair.
RTCIceCandidatePair
, nullable
getLocalParameters
Returns the local ICE parameters received by this
via RTCIceTransport
, or
setLocalDescription
null
if the parameters have not yet been received.
RTCIceParameters
, nullable
getRemoteParameters
Returns the remote ICE parameters received by this
via RTCIceTransport
or
setRemoteDescription
null
if the parameters have not yet been received.
RTCIceParameters
, nullable
dictionary RTCIceParameters
{
DOMString usernameFragment
;
DOMString password
;
};
RTCIceParameters
Membersdictionary RTCIceCandidatePair
{
RTCIceCandidate
local
;
RTCIceCandidate
remote
;
};
RTCIceCandidatePair
Memberslocal
of type RTCIceCandidate
The local ICE candidate.
remote
of type RTCIceCandidate
The remote ICE candidate.
RTCIceGathererState
Enumenum RTCIceGathererState
{
"new",
"gathering",
"complete"
};
Enumeration description | |
---|---|
new |
The was just created, and has not started gathering candidates yet. |
gathering |
The is in the process of gathering candidates. |
complete |
The has completed gathering and the end-of-candidates indication for this transport has been sent. It will not gather candidates again until an ICE restart causes it to restart. |
RTCIceTransportState
Enumenum RTCIceTransportState
{
"new",
"checking",
"connected",
"completed",
"failed",
"disconnected",
"closed"
};
Enumeration description | |
---|---|
new |
The is gathering candidates and/or waiting for remote candidates to be supplied, and has not yet started checking. |
checking |
The has received at least one remote candidate and is checking candidate pairs and has either not yet found a connection or consent checks [RFC7675] have failed on all previously successful candidate pairs. In addition to checking, it may also still be gathering. |
connected |
The has found a usable connection, but is still checking other candidate pairs to see if there is a better connection. It may also still be gathering and/or waiting for additional remote candidates. If consent checks [RFC7675] fail on the connection in use, and there are no other successful candidate pairs available, then the state transitions to "checking" (if there are candidate pairs remaining to be checked) or "disconnected" (if there are no candidate pairs to check, but the peer is still gathering and/or waiting for additional remote candidates). |
completed |
The has finished gathering, received an indication that there are no more remote candidates, finished checking all candidate pairs and found a connection. If consent checks [RFC7675] subsequently fail on all successful candidate pairs, the state transitions to "failed".
|
failed |
The has finished gathering, received an indication that there are no more remote candidates, finished checking all candidate pairs, and all pairs have either failed connectivity checks or have lost consent. |
disconnected |
The ICE Agent has determined that connectivity is currently lost for this . This is more aggressive than failed , and may trigger intermittently (and resolve itself without action) on a flaky network. The way this state is determined is implementation dependent. Examples include:
has finished checking all existing candidates pairs and failed to find a connection (or consent checks [RFC7675] once successful, have now failed), but it is still gathering and/or waiting for additional remote candidates.
|
closed |
The has shut down and is no longer responding to STUN requests. |
The failed
and completed
states require an indication that there are no additional remote candidates. This can be indicated by calling
with a candidate value whose addIceCandidate
candidate
property is set to an empty string or by canTrickleIceCandidates
being set to
false
.
Some example transitions might be:
RTCIceTransport
first created, as a result of
setLocalDescription
or setRemoteDescription
):
new
new
, remote candidates received):
checking
checking
, found usable connection):
connected
checking
, checks fail but gathering still in progress): disconnected
checking
, gave up): failed
disconnected
, new local candidates):
checking
connected
, finished all checks):
completed
completed
, lost connectivity):
disconnected
new
RTCPeerConnection.close()
: closed
RTCIceRole
Enumenum RTCIceRole
{
"controlling",
"controlled"
};
Enumeration description | |
---|---|
controlling |
A controlling agent as defined by [ICE], Section 3. |
controlled |
A controlled agent as defined by [ICE], Section 3. |
RTCIceComponent
Enumenum RTCIceComponent
{
"rtp",
"rtcp"
};
Enumeration description | |
---|---|
rtp |
The ICE Transport is used for RTP (or RTP/RTCP-multiplexing), as defined in [ICE], Section 4.1.1.1. Protocols multiplexed with RTP (e.g. data channel) share its component ID. |
rtcp |
The ICE Transport is used for RTCP as defined by [ICE], Section 4.1.1.1. |
The
event uses the
track
interface.RTCTrackEvent
Firing an
RTCTrackEvent event named e with an
receiver, a
RTCRtpReceiver
track and a
MediaStreamTrack
MediaStream
[] streams, means that an event with the name e, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the
interface with the
RTCTrackEvent
attribute set to
receiver, receiver
attribute set to track, track
attribute set to streams,
MUST be created and dispatched at the given target.streams
[Constructor(DOMString type, RTCTrackEventInit
eventInitDict)]
interface RTCTrackEvent
: Event {
readonly attribute RTCRtpReceiver
receiver
;
readonly attribute MediaStreamTrack
track
;
readonly attribute FrozenArray<MediaStream> streams
;
readonly attribute RTCRtpTransceiver
transceiver
;
};
RTCTrackEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type | DOMString |
✘ | ✘ | |
eventInitDict | RTCTrackEventInit |
✘ | ✘ |
receiver
of type RTCRtpReceiver
, readonlyThe receiver
attribute represents the
object associated with the event.RTCRtpReceiver
track
of type MediaStreamTrack
, readonlyThe track
attribute represents the
object that is associated with the MediaStreamTrack
identified by
RTCRtpReceiver
receiver
.
streams
of type FrozenArray<MediaStream>,
readonlyThe streams
attribute returns an array of MediaStream
objects representing the
MediaStream
s that this event's
track
is a part of.
transceiver
of type RTCRtpTransceiver
, readonlyThe transceiver
attribute represents the
object associated with the event.RTCRtpTransceiver
dictionary RTCTrackEventInit
: EventInit {
required RTCRtpReceiver
receiver
;
required MediaStreamTrack
track
;
sequence<MediaStream> streams
= [];
required RTCRtpTransceiver
transceiver
;
};
RTCTrackEventInit
Membersreceiver
of type RTCRtpReceiver
, requiredThe receiver
attribute represents the
object associated with the event.
RTCRtpReceiver
track
of type MediaStreamTrack
, requiredThe track
attribute represents the
object that is associated with the MediaStreamTrack
identified by
RTCRtpReceiver
receiver
.
streams
of type sequence<MediaStream>,
defaulting to []
The streams
attribute returns an array of
MediaStream
objects representing the
MediaStream
s that this event's
track
is a part of.
transceiver
of type RTCRtpTransceiver
, requiredThe transceiver
attribute represents the
object associated with the event.
RTCRtpTransceiver
The Peer-to-peer Data API lets a web application send and receive generic application data peer-to-peer. The API for sending and receiving data models the behavior of WebSockets [WEBSOCKETS-API].
The Peer-to-peer data API extends the
interface as described below.RTCPeerConnection
partial interface RTCPeerConnection
{
readonly attribute RTCSctpTransport
? sctp
;
RTCDataChannel
createDataChannel
([TreatNullAs=EmptyString] USVString label,
optional RTCDataChannelInit
dataChannelDict);
attribute EventHandler ondatachannel
;
};
sctp
of type RTCSctpTransport
, readonly ,
nullableThe SCTP transport over which SCTP data is sent and received. If SCTP has not been negotiated, the value is null. This attribute MUST return the
object stored in the [[RTCSctpTransport
sctpTransport
]] internal slot.
ondatachannel
of type EventHandlerdatachannel
.createDataChannel
Creates a new
object with the given label. The RTCDataChannel
dictionary can be used to configure properties of the underlying channel such as
data reliability.RTCDataChannelInit
When the createDataChannel
method is invoked, the user agent MUST run the following steps.
Let connection be the
object on which the method is invoked.RTCPeerConnection
If connection's [[isClosed]] slot is
true
, throw an
InvalidStateError
.
Let channel be a newly created
object.RTCDataChannel
Initialize channel's
attribute to the value of the first argument.label
If the second (dictionary) argument is present, set
channel's
, ordered
,
maxPacketLifeTime
,
maxRetransmits
,
protocol
,
negotiated
and
id
attributes to the values of their corresponding dictionary members (if present in the dictionary).priority
negotiated
is false and label
is longer than 65535 bytes long, throw a
TypeError
.
negotiated
is false and
protocol
is longer than 65535 bytes long,
throw a TypeError
.
If both the
and
maxPacketLifeTime
attributes are set (not null), throw a
maxRetransmits
SyntaxError
.
If an attribute, either
or
maxPacketLifeTime
, has been set to indicate unreliable mode, and that value exceeds the maximum value supported by the user agent, the value MUST be set to the user agents maximum value.maxRetransmits
If
is equal to 65535, which is greater than the maximum allowed ID of 65534 but still qualifies as an unsigned short, throw a
id
TypeError
.
If the
attribute is uninitialized (not set via the dictionary), and the DTLS role of the SCTP transport has already been negotiated, then initialize id
to a value generated by the user agent, according to [RTCWEB-DATA-PROTOCOL], and skip to the next step. If no available id could be generated, or if the value of the id
id
member of the dictionary is taken by an existing
,
throw a RTCDataChannel
ResourceInUse
exception.
Return channel and continue the following steps in the background.
Create channel's associated underlying data transport and configure it according to the relevant properties of channel.
If channel was the first
created on
connection, update the negotiation-needed
flag for connection.RTCDataChannel
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
label | USVString |
✘ | ✘ | |
dataChannelDict | RTCDataChannelInit |
✘ | ✔ |
RTCDataChannel
RTCSctpTransport
Interface
The
interface allows an application access to information about the SCTP data channels tied to a particular SCTP association.RTCSctpTransport
interface RTCSctpTransport
{
readonly attribute RTCDtlsTransport
transport
;
readonly attribute unsigned long maxMessageSize
;
};
transport
of type RTCDtlsTransport
, readonlyThe transport over which all SCTP packets for data channels will be sent and received.
maxMessageSize
of type unsigned long, readonlyThe maximum size of data that can be passed to
's RTCDataChannel
method.send()
RTCDataChannel
The
interface represents a bi-directional data channel between two peers. A
RTCDataChannel
is created via a factory method on an
RTCDataChannel
object. The messages sent between the browsers are described in [RTCWEB-DATA] and [
RTCWEB-DATA-PROTOCOL].RTCPeerConnection
There are two ways to establish a connection with
. The first way is to simply create a
RTCDataChannel
at one of the peers with the
RTCDataChannel
negotiated
dictionary member unset or set to its default value false. This will announce the new channel in-band and trigger a RTCDataChannelInit
with the corresponding
RTCDataChannelEvent
object at the other peer. The second way is to let the application negotiate the
RTCDataChannel
. To do this, create a
RTCDataChannel
object with the RTCDataChannel
negotiated
dictionary member set to true, and signal out-of-band (e.g. via a web server) to the other side that it
SHOULD create a corresponding RTCDataChannelInit
with the
RTCDataChannel
negotiated
dictionary member set to true and the same RTCDataChannelInit
. This will connect the two separately created id
objects. The second way makes it possible to create channels with asymmetric properties and to create channels in a declarative way by specifying matching RTCDataChannel
s.id
Each
has an associated
underlying data transport that is used to transport actual data to the other peer. The transport properties of the underlying data transport, such as in order delivery settings and reliability mode, are configured by the peer as the channel is created. The properties of a channel cannot change after the channel has been created. The actual wire protocol between the peers is specified by the WebRTC DataChannel Protocol specification [RTCWEB-DATA].RTCDataChannel
A
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 (
RTCDataChannel
) or set a time during which transmissions (including retransmissions) are allowed ( maxRetransmits
). 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.maxPacketLifeTime
A
, created with RTCDataChannel
or dispatched via a
createDataChannel
, MUST initially be in the
RTCDataChannelEvent
connecting
state. When the
object's underlying data
transport is ready, the user agent MUST announce the
RTCDataChannel
RTCDataChannel
as open.
When the user agent is to announce a RTCDataChannel
as
open, the user agent MUST queue a task to run the following steps:
If the associated
object's [[
isClosed]] slot is RTCPeerConnection
true
, abort these steps.
Let channel be the
object to be announced.RTCDataChannel
Set channel's
attribute to
readyState
open
.
Fire a simple event named
at
channel.open
When an underlying data transport is to be announced (the other peer created a channel with
unset or set to false), the user agent of the peer that did not initiate the creation process MUST queue a task to run the following steps:negotiated
If the associated
object's [[
isClosed]] slot is RTCPeerConnection
true
, abort these steps.
Let channel be a newly created
object.RTCDataChannel
Let configuration be an information bundle received from the other peer as a part of the process to establish the underlying data transport described by the WebRTC DataChannel Protocol specification [RTCWEB-DATA-PROTOCOL].
Initialize channel's
, label
, ordered
, maxPacketLifeTime
, maxRetransmits
, protocol
and negotiated
attributes to their corresponding values in configuration.id
Set channel's
attribute to
readyState
connecting
.
Fire a datachannel event named
with channel at the
datachannel
object.RTCPeerConnection
An
object's underlying data
transport may be torn down in a non-abrupt manner by running the
closing procedure. When that happens the user agent MUST, unless the procedure was initiated by the RTCDataChannel
method, queue a task that sets the object's close
attribute to readyState
closing
. This will eventually render the data transport closed.
When a
object's underlying data
transport has been closed, the user agent MUST queue a task to run the following steps:RTCDataChannel
Let channel be the
object whose transport was closed.
RTCDataChannel
Set channel's
attribute to
readyState
closed
.
If the transport was closed with an error, fire a NetworkError event at channel.
Fire a simple event named
at
channel.close
In some cases, the user agent may be unable to create an
's underlying data transport. For example, the data channel's RTCDataChannel
may be outside the range negotiated by the [
RTCWEB-DATA] implementations in the SCTP handshake. When the user agent determines that an id
's
underlying data transport cannot be created, the user agent MUST queue a task to run the following steps:RTCDataChannel
Let channel be the
object for which the user agent could not create an underlying
data transport.RTCDataChannel
Set channel's
attribute to
readyState
closed
.
Fire a NetworkError event at channel.
Fire a simple event named
at
channel.close
interface RTCDataChannel
: EventTarget {
readonly attribute USVString label
;
readonly attribute boolean ordered
;
readonly attribute unsigned short? maxPacketLifeTime
;
readonly attribute unsigned short? maxRetransmits
;
readonly attribute USVString protocol
;
readonly attribute boolean negotiated
;
readonly attribute unsigned short? id
;
readonly attribute RTCPriorityType
priority
;
readonly attribute RTCDataChannelState
readyState
;
readonly attribute unsigned long bufferedAmount
;
attribute unsigned long bufferedAmountLowThreshold
;
attribute EventHandler onopen
;
attribute EventHandler onbufferedamountlow
;
attribute EventHandler onerror
;
attribute EventHandler onclose
;
void close
();
attribute EventHandler onmessage
;
attribute DOMString binaryType
;
void send
(USVString data);
void send
(Blob data);
void send
(ArrayBuffer data);
void send
(ArrayBufferView data);
};
label
of type USVString, readonlyThe label
attribute represents a label that can be used to distinguish this
object from other
RTCDataChannel
objects. Scripts are allowed to create multiple RTCDataChannel
objects with the same label. The attribute MUST return the value to which it was set when the RTCDataChannel
object was created.
RTCDataChannel
ordered
of type boolean, readonlyThe ordered
attribute returns true if the
is ordered, and false if other of order delivery is allowed. The attribute MUST be initialized to true by default and MUST return the value to which it was set when the
RTCDataChannel
was created.RTCDataChannel
maxPacketLifeTime
of type unsigned short, readonly ,
nullableThe maxPacketLifeTime
attribute returns the length of the time window (in milliseconds) during which transmissions and retransmissions may occur in unreliable mode, or null if unset. The attribute MUST be initialized to null by default and MUST return the value to which it was set when the
was created.
RTCDataChannel
maxRetransmits
of type unsigned short, readonly ,
nullableThe maxRetransmits
attribute returns the maximum number of retransmissions that are attempted in unreliable mode, or null if unset. The attribute
MUST be initialized to null by default and MUST return the value to which it was set when the
was created.RTCDataChannel
protocol
of type USVString, readonlyThe protocol
attribute returns the name of the sub-protocol used with this
if any, or the empty string otherwise. The attribute MUST be initialized to the empty string by default and MUST return the value to which it was set when the
RTCDataChannel
was created.RTCDataChannel
negotiated
of type boolean, readonlyThe negotiated
attribute returns true if this
was negotiated by the application, or false otherwise. The attribute MUST be initialized to false by default and MUST return the value to which it was set when the
RTCDataChannel
was created.RTCDataChannel
id
of type unsigned short, readonly, nullableThe id
attribute returns the id for this
. If the id was not provided at channel creation time, and the DTLS role of the SCTP transport has not yet been negotiated, this attribute will return null. Otherwise, it will return the id that was either selected by the script or generated by the user agent according to [
RTCWEB-DATA-PROTOCOL]. After the id has been set, it will not change.
RTCDataChannel
priority
of type RTCPriorityType
, readonlyThe priority
attribute returns the priority for this
. The priority is assigned by the user agent at channel creation time. The attribute MUST return the value to which it was set when the
RTCDataChannel
was created.RTCDataChannel
readyState
of type RTCDataChannelState
, readonlyThe readyState
attribute represents the state of the RTCDataChannel
object. It MUST return the value to which the user agent last set it (as defined by the processing model algorithms).
bufferedAmount
of type unsigned long, readonlyThe bufferedAmount
attribute MUST return the number of bytes of application data (UTF-8 text and binary data) that have been queued using
but that, as of the last time the event loop started executing a task, had not yet been transmitted to the network. (This thus includes any text sent during the execution of the current task, regardless of whether the user agent is able to transmit text asynchronously with script execution.) This does not include framing overhead incurred by the protocol, or buffering done by the operating system or network hardware. If the channel is closed, this attribute's value will only increase with each call to the
send()
method (the attribute does not reset to zero once the channel closes).send()
bufferedAmountLowThreshold
of type unsigned longThe bufferedAmountLowThreshold
attribute sets the threshold at which the
is considered to be low. When the bufferedAmount
decreases from above this threshold to equal or below it, the bufferedAmount
event fires. The bufferedamountlow
is initially zero on each new bufferedAmountLowThreshold
, but the application may change its value at any time.RTCDataChannel
onopen
of type EventHandleropen
.onbufferedamountlow
of type
EventHandlerbufferedamountlow
.onerror
of type EventHandlererror
.onclose
of type EventHandlerclose
.onmessage
of type EventHandlermessage
.binaryType
of type DOMStringThe binaryType
attribute MUST, on getting, return the value to which it was last set. On setting, the user agent MUST set the IDL attribute to the new value. When a
object is created, the RTCDataChannel
attribute MUST be initialized to the string "binaryType
blob
".
This attribute controls how binary data is exposed to scripts. See the [WEBSOCKETS-API] for more information.
close
Closes the
. It may be called regardless of whether the
RTCDataChannel
object was created by this peer or the remote peer.RTCDataChannel
When the close
method is called, the user agent
MUST run the following steps:
Let channel be the
object which is about to be closed.RTCDataChannel
If channel's
is
readyState
closing
or closed
, then abort these steps.
Set channel's
attribute to
readyState
closing
.
If the closing procedure
has not started yet, start it.
void
send
Run the steps described by the
algorithm with argument type
send()
string
object.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | USVString |
✘ | ✘ |
void
send
Run the steps described by the
algorithm with argument type
send()
Blob
object.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | Blob |
✘ | ✘ |
void
send
Run the steps described by the
algorithm with argument type
send()
ArrayBuffer
object.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | ArrayBuffer |
✘ | ✘ |
void
send
Run the steps described by the
algorithm with argument type
send()
ArrayBufferView
object.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | ArrayBufferView |
✘ | ✘ |
void
dictionary RTCDataChannelInit
{
boolean ordered
= true;
unsigned short maxPacketLifeTime
;
unsigned short maxRetransmits
;
USVString protocol
= "";
boolean negotiated
= false;
[EnforceRange]
unsigned short id
;
RTCPriorityType
priority
= "low";
};
RTCDataChannelInit
Membersordered
of type boolean, defaulting to
true
If set to false, data is allowed to be delivered out of order. The default value of true, guarantees that data will be delivered in order.
maxPacketLifeTime
of type unsigned shortLimits the time (in milliseconds) during which the channel will transmit or retransmit data if not acknowledged. This value may be clamped if it exceeds the maximum value supported by the user agent.
maxRetransmits
of type unsigned shortLimits the number of times a channel will retransmit data if not successfully delivered. This value may be clamped if it exceeds the maximum value supported by the user agent.
protocol
of type USVString, defaulting to
""
Subprotocol name used for this channel.
negotiated
of type boolean, defaulting to
false
The default value of false tells the user agent to announce the channel in-band and instruct the other peer to dispatch a corresponding
object. If set to true, it is up to the application to negotiate the channel and create a RTCDataChannel
object with the same
RTCDataChannel
at the other peer.
id
id
of type unsigned shortOverrides the default selection of id for this channel.
priority
of type RTCPriorityType
, defaulting to
low
Priority of this channel.
The send()
method is overloaded to handle different data argument types. When any version of the method is called, the user agent MUST run the following steps:
Let channel be the
object on which data is to be sent.RTCDataChannel
If channel's
attribute is
readyState
connecting
, throw an
InvalidStateError
.
Execute the sub step that corresponds to the type of the methods argument:
string
object:
Let data be the object and increase the
attribute by the number of bytes needed to express
data as UTF-8.bufferedAmount
Blob
object:
Let data be the raw data represented by the
Blob
object and increase the
attribute by the size of data, in bytes.bufferedAmount
ArrayBuffer
object:
Let data be the data stored in the buffer described by the ArrayBuffer
object and increase the
attribute by the length of the bufferedAmount
ArrayBuffer
in bytes.
ArrayBufferView
object:
Let data be the data stored in the section of the buffer described by the ArrayBuffer
object that the
ArrayBufferView
object references and increase the
attribute by the length of the bufferedAmount
ArrayBufferView
in bytes.
If channel's underlying data transport is not established yet, or if the closing procedure
has started, then abort these steps.
Attempt to send data on channel's
underlying data transport; if the data cannot be sent, e.g. because it would need to be buffered but the buffer is full, the user agent MUST abruptly close
channel's underlying
data transport with an error.
enum RTCDataChannelState
{
"connecting",
"open",
"closing",
"closed"
};
RTCDataChannelState Enumeration description |
|
---|---|
connecting |
The user agent is attempting to establish the underlying
data transport. This is the initial state of a
|
open |
The underlying data transport is established and communication is possible. This is the initial state of a
|
closing |
The |
closed |
The underlying data transport has been
|
The
event uses the
datachannel
interface.RTCDataChannelEvent
Firing a datachannel event named
e with a
channel means that an event with the name e, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the
RTCDataChannel
interface with the
RTCDataChannelEvent
attribute set to channel, MUST be created and dispatched at the given target.
channel
[Constructor(DOMString type, RTCDataChannelEventInit
eventInitDict)]
interface RTCDataChannelEvent
: Event {
readonly attribute RTCDataChannel
channel
;
};
RTCDataChannelEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type | DOMString |
✘ | ✘ | |
eventInitDict |
RTCDataChannelEventInit |
✘ | ✘ |
channel
of type RTCDataChannel
, readonlyThe channel
attribute represents the
object associated with the event.RTCDataChannel
dictionary RTCDataChannelEventInit
: EventInit {
required RTCDataChannel
channel
;
};
RTCDataChannelEventInit
Memberschannel
of type RTCDataChannel
, requiredThe
object to be announced by the event.RTCDataChannel
A
object MUST not be garbage collected if itsRTCDataChannel
is
readyState
connecting
and at least one event listener is registered for open
events, message
events,
error
events, or close
events.
is
readyState
open
and at least one event listener is registered for
message
events, error
events, or
close
events.
is
readyState
closing
and at least one event listener is registered for error
events, or close
events.
underlying data transport is established and data is queued to be transmitted.
This section describes an interface on
to send DTMF (phone keypad) values across an
RTCRtpSender
. Details of how DTMF is sent to the other peer are described in [RTCWEB-AUDIO].RTCPeerConnection
The Peer-to-peer DTMF API extends the
interface as described below.RTCRtpSender
partial interface RTCRtpSender
{
readonly attribute RTCDTMFSender
? dtmf
;
};
dtmf
of type RTCDTMFSender
, readonly , nullableThe dtmf
attribute returns a RTCDTMFSender which can be used to send DTMF. A null value indicates that this RTCRtpSender cannot send DTMF.
RTCDTMFSender
interface RTCDTMFSender
: EventTarget {
void insertDTMF
(DOMString tones,
optional unsigned long duration = 100,
optional unsigned long interToneGap = 70);
attribute EventHandler ontonechange
;
readonly attribute DOMString toneBuffer
;
};
ontonechange
of type EventHandlerThe event type of this event handler is
.tonechange
toneBuffer
of type DOMString, readonlyThe toneBuffer
attribute MUST return a list of the tones remaining to be played out. For the syntax, content, and interpretation of this list, see
.insertDTMF
insertDTMF
An
object's RTCDTMFSender
insertDTMF
method is used to send DTMF tones.
The tones parameter is treated as a series of characters. The characters 0 through 9, A through D, #, and * generate the associated DTMF tones. The characters a to d MUST be normalized to uppercase on entry and are equivalent to A to D. As noted in [ RTCWEB-AUDIO] Section 3, support for the characters 0 through 9, A through D, #, and * are required. The character ',' MUST be supported, and indicates a delay of 2 seconds before processing the next character in the tones parameter. All other characters (and only those other characters) MUST be considered unrecognized.
The duration parameter indicates the duration in ms to use for each character passed in the tones parameters. The duration cannot be more than 6000 ms or less than 40 ms. The default duration is 100 ms for each tone.
The interToneGap parameter indicates the gap between tones in ms. The user agent clamps it to at least 30 ms. The default value is 70 ms.
The browser MAY increase the duration and interToneGap times to cause the times that DTMF start and stop to align with the boundaries of RTP packets but it MUST not increase either of them by more than the duration of a single RTP audio packet.
When the insertDTMF()
method is invoked, the user agent MUST run the following steps:
RTCRtpSender
used to send DTMF.Let transceiver be the
object associated with
sender.RTCRtpTransceiver
transceiver.stopped
is
true
, throw an
InvalidStateError
.transceiver.currentDirection
is recvonly
or inactive
,
throw an InvalidStateError
.InvalidCharacterError
.
toneBuffer
attribute to
tones.duration
parameter is less than 40, set it to 40. If, on the other hand, the value is greater than 6000, set it to 6000.interToneGap
parameter is less than 30, set it to 30.toneBuffer
is an empty string, abort these steps.transceiver.stopped
is
true
, abort these steps.transceiver.currentDirection
is recvonly
or inactive
, abort these steps.toneBuffer
is an empty string, fire an event named tonechange
with an empty string at the RTCDTMFSender
object and abort these steps.toneBuffer
and let that character be tone.duration
ms on the associated RTP media stream, using the appropriate codec.duration
+ interToneGap
ms from now that runs the steps labelled Playout task.tonechange
with a string consisting of tone at the
RTCDTMFSender
object.Calling
with an empty tones parameter can be used to cancel all tones queued to play after the currently playing tone.insertDTMF
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
tones | DOMString |
✘ | ✘ | |
duration | unsigned long = 100 |
✘ | ✔ | |
interToneGap | unsigned long = 70 |
✘ | ✔ |
void
The
event uses the
tonechange
interface.RTCDTMFToneChangeEvent
Firing a tonechange event named
e with a DOMString
tone means that an event with the name e, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the
interface with the RTCDTMFToneChangeEvent
attribute set to
tone, MUST be created and dispatched at the given target.tone
[Constructor(DOMString type, RTCDTMFToneChangeEventInit
eventInitDict)]
interface RTCDTMFToneChangeEvent
: Event {
readonly attribute DOMString tone
;
};
RTCDTMFToneChangeEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type | DOMString |
✘ | ✘ | |
eventInitDict |
RTCDTMFToneChangeEventInit |
✘ | ✘ |
tone
of type DOMString, readonlyThe tone
attribute contains the character for the tone that has just begun playout (see
insertDTMF
). If the value is the empty string, it indicates that the
is an empty string and that the previous tones have completed playback.toneBuffer
dictionary RTCDTMFToneChangeEventInit
: EventInit {
required DOMString tone
;
};
RTCDTMFToneChangeEventInit
Memberstone
of type DOMStringThe tone
attribute contains the character for the tone that has just begun playout (see
insertDTMF
). If the value is the empty string, it indicates that the
is an empty string and that the previous tones have completed playback.toneBuffer
The basic statistics model is that the browser maintains a set of statistics referenced by a selector. The selector may, for example, be a MediaStreamTrack
. For a track to be a valid selector, it MUST be a MediaStreamTrack
that is sent or received by the
object on which the stats request was issued. The calling Web application provides the selector to the RTCPeerConnection
getStats()
method and the browser emits (in the JavaScript) a set of statistics that are relevant to the selector, according to the stats selection algorithm. Note that that algorithm takes the sender or receiver of a selector.
The statistics returned are designed in such a way that repeated queries can be linked by the RTCStats
id
dictionary member. Thus, a Web application can make measurements over a given time period by requesting measurements at the beginning and end of that period.
The Statistics API extends the
interface as described below.RTCPeerConnection
partial interface RTCPeerConnection
{
Promise<RTCStatsReport
> getStats(optional MediaStreamTrack
? selector = null);
};
getStats
Gathers stats for the given selector and reports the result asynchronously.
When the
getStats()
method is invoked, the user agent
MUST run the following steps:
Let selectorArg be the method's first argument.
Let connection be the
object on which the method was invoked.RTCPeerConnection
If selectorArg is neither null
nor a valid MediaStreamTrack
, return a promise rejected with a newly
created
TypeError
.
Let selector be a RTCRtpSender
or
RTCRtpReceiver
on connection which
track
member matches selectorArg. If no such sender or receiver exists, or if more than one sender or receiver fit this criteria, return a promise rejected with a newly
created
InvalidAccessError
.
Let p be a new promise.
Run the following steps in parallel:
Gather the stats indicated by selector according to the stats selection algorithm.
Resolve p with the resulting
object, containing the gathered stats.RTCStatsReport
Return p.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
selector | MediaStreamTrack =
null |
✔ | ✔ |
Promise<RTCStatsReport>
RTCStatsReport
Object
The getStats()
method delivers a successful result in the form of an
object. An
RTCStatsReport
object is a map between strings that identify the inspected objects (RTCStatsReport
attribute in id
RTCStats
instances), and their corresponding
-derived dictionaries.
RTCStats
An
may be composed of several
RTCStatsReport
-derived dictionaries, each reporting stats for one underlying object that the implementation thinks is relevant for the selector. One achieves the total for the selector by summing over all the stats of a certain type; for instance, if an
RTCStats
RTCRtpSender
uses multiple SSRCs to carry its track over the network, the
may contain one
RTCStatsReport
RTCStats
-derived dictionary per SSRC (which can be distinguished by the value of the "ssrc" stats attribute).
interface RTCStatsReport
{
readonly maplike<DOMString, object>;
};
This interface has "entries", "forEach", "get", "has", "keys", "values", @@iterator methods and a "size" getter brought by
readonly maplike
.
Use these to retrieve the various dictionaries descended from
that this stats report is composed of. The set of supported property names [WEBIDL-1] is defined as the ids of all the RTCStats
-derived dictionaries that have been generated for this stats report.RTCStats
An
dictionary represents the stats gathered by inspecting a specific object relevant to a selector. The RTCStats
dictionary is a base type that specifies as set of default attributes, such as RTCStats
timestamp
and type
. Specific stats are added by extending the
dictionary.RTCStats
Note that while stats names are standardized, any given implementation may be using experimental values or values not yet known to the Web application. Thus, applications MUST be prepared to deal with unknown stats.
Statistics need to be synchronized with each other in order to yield reasonable values in computation; for instance, if "bytesSent" and "packetsSent" are both reported, they both need to be reported over the same interval, so that "average packet size" can be computed as "bytes / packets" - if the intervals are different, this will yield errors. Thus implementations MUST return synchronized values for all stats in an
-derived dictionary.RTCStats
dictionary RTCStats
{
DOMHighResTimeStamp timestamp
;
RTCStatsType
type
;
DOMString id
;
};
RTCStats
Memberstimestamp
of type DOMHighResTimeStampThe timestamp
, of type
DOMHighResTimeStamp
[HIGHRES-TIME], associated with this object. The time is relative to the UNIX epoch (Jan 1, 1970, UTC). For statistics that came from a remote source (e.g., from received RTCP packets), timestamp
represents the time at which the information arrived at the local endpoint. The remote timestamp can be found in an additional field in an
-derived dictionary, if applicable.
RTCStats
type
of type RTCStatsType
The type of this object.
The type
attribute MUST be initialized to the name of the most specific type this
dictionary represents.RTCStats
id
of type DOMStringA unique id
that is associated with the object that was inspected to produce this
object. Two
RTCStats
objects, extracted from two different RTCStats
objects, MUST have the same id if they were produced by inspecting the same underlying object. User agents are free to pick any format for the id as long as it meets the requirements above.RTCStatsReport
enum RTCStatsType
{
};
The set of valid values for RTCStatsType
, and the dictionaries derived from RTCStats that they indicate, are documented in [
WEBRTC-STATS].
The stats selection algorithm is as follows:
null
, gather stats for the whole connection, add them to result, return
result, and abort these steps.
RTCRtpSender
, gather stats for and add the following objects to result:
RTCOutboundRTPStreamStats
objects corresponding to
selector.
RTCOutboundRTPStreamStats
objects added.
RTCRtpReceiver
, gather stats for and add the following objects to result:
RTCInboundRTPStreamStats
objects corresponding to selector.
RTCInboundRTPStreamStats
added.
A stats object is said to "correspond to" a selector if its "ssrc" stats attribute matches an ssrc
in one of the encoding parameters of the selector.
The stats listed in [WEBRTC-STATS] are intended to cover a wide range of use cases. Not all of them have to be implemented by every WebRTC implementation.
An implementation MUST support generating statistics of the following types when the corresponding objects exist on a PeerConnection, with the attributes that are listed when they are valid for that object:
An implementation MAY support generating any other statistic defined in [WEBRTC-STATS], and MAY generate statistics that are not documented.
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:
var baselineReport, currentReport;
var selector = pc.getSenders()[0].track;
pc.getStats(selector).then(function (report) {
baselineReport = report;
})
.then(function() {
return new Promise(function(resolve) {
setTimeout(resolve, aBit); // ... wait a bit
});
})
.then(function() {
return pc.getStats(selector);
})
.then(function (report) {
currentReport = report;
processStats();
})
.catch(function (error) {
log(error.toString());
});
function processStats() {
// compare the elements from the current report with the baseline
currentReport.forEach (now => {
if (now.type != "outboundrtp")
return;
// get the corresponding stats from the baseline report
base = baselineReport.get(now.id);
if (base) {
remoteNow = currentReport.get(now.remoteId);
remoteBase = baselineReport.get(base.remoteId);
var packetsSent = now.packetsSent - base.packetsSent;
var packetsReceived = remoteNow.packetsReceived - remoteBase.packetsReceived;
// if fractionLost is > 0.3, we have probably found the culprit
var fractionLost = (packetsSent - packetsReceived) / packetsSent;
}
}
}
WebRTC offers and answers (and hence the channels established by
objects) can be authenticated by using a web-based Identity Provider (IdP). The idea is that the entity sending an offer or answer acts as the Authenticating Party (AP) and obtains an identity assertion from the IdP which it attaches to the session description. The consumer of the session description (i.e., the
RTCPeerConnection
on which
RTCPeerConnection
setRemoteDescription
is called) acts as the Relying Party (RP) and verifies the assertion.
The interaction with the IdP is designed to decouple the browser from any particular identity provider; the browser need only know how to load the IdP's JavaScript, the location of which is determined by the IdP's identity, and the generic interface to generating and validating assertions. The IdP provides whatever logic is necessary to bridge the generic protocol to the IdP's specific requirements. Thus, a single browser can support any number of identity protocols, including being forward compatible with IdPs which did not exist at the time the browser was written.
An IdP is used to generate an identity assertion as follows:
setIdentityProvider()
method has been called, the IdP provided shall be used.setIdentityProvider()
method has not been called, then the user agent MAY use an IdP configured into the browser.
In order to verify assertions, the IdP domain name and protocol are taken from the domain
and protocol
fields of the identity assertion.
In order to communicate with the IdP, the user agent loads the IdP JavaScript from the IdP. The URI for the IdP script is a well-known URI formed from the domain
and protocol
fields, as specified in [RTCWEB-SECURITY-ARCH].
The IdP MAY generate an HTTP redirect to another "https" origin, the browser MUST treat a redirect to any other scheme as a fatal error.
The user agent instantiates an isolated interpreted context, a JavaScript realm that operates in the origin of the loaded JavaScript. Note that a redirect will change the origin of the loaded script.
The realm is populated with a global that implements both the
RTCIdentityProviderGlobalScope
and
WorkerGlobalScope
[WEBWORKERS] interfaces.
The user agent provides an instance of
named
rtcIdentityProvider in the global scope of the realm. This object is used by the IdP to interact with the user agent.RTCIdentityProviderRegistrar
[Global,
Exposed=RTCIdentityProviderGlobalScope]
interface RTCIdentityProviderGlobalScope
: WorkerGlobalScope {
readonly attribute RTCIdentityProviderRegistrar
rtcIdentityProvider
;
};
rtcIdentityProvider
of type
RTCIdentityProviderRegistrar
,
readonlyRTCIdentityProvider
instance with the browser.
An environment that mimics the identity provider realm can be provided by any script. However, only scripts running in the origin of the IdP are able to generate an identical environment. Other origins can load and run the IdP proxy code, but they will be unable to replicate data that is unique to the origin of the IdP.
This means that it is critical that an IdP use data that is restricted to its own origin when generating identity assertions. Otherwise, another origin could load the IdP script and use it to impersonate users.
The data that the IdP script uses could be stored on the client (for example, in IndexedDB) or loaded from servers. Data that is acquired from a server SHOULD require credentials and be protected from cross-origin access.
There is no risk to the integrity of identity assertions if an IdP validates an identity assertion without using origin-private data.
An IdP proxy implements the
methods, which are the means by which the user agent is able to request that an identity assertion be generated or validated.RTCIdentityProvider
Once instantiated, the IdP script is executed. The IdP MUST call the
register()
function on the
RTCIdentityProviderRegistrar
instance during script execution. If an IdP is not registered during this script execution, the user agent cannot use the IdP proxy and MUST fail any future attempt to interact with the IdP.
[Exposed=RTCIdentityProviderGlobalScope]
interface RTCIdentityProviderRegistrar
{
void register
(RTCIdentityProvider
idp);
};
register
This method is invoked by the IdP when its script is first executed. This registers
methods with the user agent.RTCIdentityProvider
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
idp | RTCIdentityProvider |
✘ | ✘ |
void
The callback functions in RTCIdentityProvider
are exposed by identity providers and is called by
RTCPeerConnection
to acquire or validate identity assertions.
dictionary RTCIdentityProvider
{
required GenerateAssertionCallback
generateAssertion
;
required ValidateAssertionCallback
validateAssertion
;
};
RTCIdentityProvider
MembersgenerateAssertion
of type
GenerateAssertionCallback
,
requiredA user agent invokes this method on the IdP to request the generation of an identity assertion.
The IdP provides a promise that resolves to an
to successfully generate an identity assertion. Any other value, or a rejected promise, is treated as an error.RTCIdentityAssertionResult
validateAssertion
of type
ValidateAssertionCallback
,
requiredA user agent invokes this method on the IdP to request the validation of an identity assertion.
The IdP returns a Promise that resolves to an
to successfully validate an identity assertion and to provide the actual identity. Any other value, or a rejected promise, is treated as an error.RTCIdentityValidationResult
callback GenerateAssertionCallback
= Promise<RTCIdentityAssertionResult
> (DOMString contents,
DOMString origin,
RTCIdentityProviderOptions
options);
GenerateAssertionCallback
Parameterscontents
of type DOMStringorigin
of type DOMStringRTCPeerConnection
that triggered this request. An IdP can use this information as input to policy decisions about use. This value is generated by the user
agent based on the origin of the document that created the
RTCPeerConnection
and therefore can be trusted to be correct.
options
of type RTCIdentityProviderOptions
setIdentityProvider
. Though the dictionary is an optional argument to
setIdentityProvider
, default values are used as necessary when passing the value to the identity provider; see the definition of RTCIdentityProviderOptions
for details.callback ValidateAssertionCallback
= Promise<RTCIdentityValidationResult
> (DOMString assertion,
DOMString origin);
ValidateAssertionCallback
Parametersassertion
of type DOMStringa=identity
in the session description; that is, the value that was part of the
RTCIdentityAssertionResult
provided by the IdP that generated the assertion.origin
of type DOMStringRTCPeerConnection
that triggered this request. An IdP can use this information as input to policy decisions about use.dictionary RTCIdentityAssertionResult
{
required RTCIdentityProviderDetails
idp
;
required DOMString assertion
;
};
RTCIdentityAssertionResult
Membersidp
of type RTCIdentityProviderDetails
,
requiredAn IdP provides these details to identify the IdP that validates the identity assertion. This struct contains the same information that is provided to
setIdentityProvider
.
assertion
of type DOMString, requiredAn identity assertion. This is an opaque string that MUST contain all information necessary to assert identity. This value is consumed by the validating IdP.
dictionary RTCIdentityProviderDetails
{
required DOMString domain
;
DOMString protocol
= "default";
};
RTCIdentityProviderDetails
Membersdomain
of type DOMString, requiredThe domain name of the IdP that validated the associated identity assertion.
protocol
of type DOMString, defaulting to
"default"
The protocol parameter used for the IdP.
dictionary RTCIdentityValidationResult
{
required DOMString identity
;
required DOMString contents
;
};
RTCIdentityValidationResult
Membersidentity
of type DOMString, requiredThe validated identity of the peer.
contents
of type DOMString, requiredThe payload of the identity assertion. An IdP that validates an identity assertion MUST return the same string that was provided to the original IdP that generated the assertion.
The user agent uses the contents string to determine if the identity assertion matches the session description.
The identity assertion request process is triggered by a call to
createOffer
, createAnswer
, or
getIdentityAssertion
. When these calls are invoked and an identity provider has been set, the following steps are executed:
The RTCPeerConnection
instantiates an IdP as described in Identity
Provider Selection and Registering an
IdP Proxy. If the IdP cannot be loaded, instantiated, or the IdP proxy is not registered, this process fails.
The RTCPeerConnection
invokes the
method on the
generateAssertion
methods registered by the IdP.
RTCIdentityProvider
The RTCPeerConnection
generates the
contents parameter to this method as described in [
RTCWEB-SECURITY-ARCH]. The value of contents includes the fingerprint of the certificate that was selected or generated during the construction of the RTCPeerConnection
. The
origin parameter contains the origin of the script that calls the RTCPeerConnection
method that triggers this behavior. The usernameHint value is the same value that is provided to setIdentityProvider
, if any such value was provided.
The IdP proxy returns a Promise to the
RTCPeerConnection
. The IdP proxy is expected to generate the identity assertion asynchronously.
If the user has been authenticated by the IdP, and the IdP is able to generate an identity assertion, the IdP resolves the promise with an identity assertion in the form of an
.RTCIdentityAssertionResult
This step depends entirely on the IdP. The methods by which an IdP authenticates users or generates assertions is not specified, though they could involve interacting with the IdP server or other servers.
If the IdP proxy produces an error or returns a promise that does not resolve to a valid
(see 9.5 IdP Error Handling), then identity validation fails.RTCIdentityValidationResult
The RTCPeerConnection
MAY store the identity assertion for use with future offers or answers. If a fresh identity assertion is needed for any reason, applications can create a new
RTCPeerConnection
.
If the identity request was triggered by a
createOffer()
or createAnswer()
, then the assertion is converted to a JSON string, base64-encoded and inserted into an a=identity
attribute in the session description.
If assertion generation fails, then the promise for the corresponding function call is rejected with a newly created OperationError
.
An IdP MAY reject an attempt to generate an identity assertion if it is unable to verify that a user is authenticated. This might be due to the IdP not having the necessary authentication information available to it (such as cookies).
Rejecting the promise returned by
will cause the error to propagate to the application. Login errors are indicated by rejecting the promise with an generateAssertion
RTCError
with errorDetail
set to "IdPNeedLogin".
The URL to login at will be passed to the application in the
idpLoginUrl
attribute of the
RTCPeerConnection
.
An application can load the login URL in an IFRAME or popup window; the resulting page then SHOULD provide the user with an opportunity to enter any information necessary to complete the authorization process.
Once the authorization process is complete, the page loaded in the IFRAME or popup sends a message using postMessage [ webmessaging] to the page that loaded it (through the window.opener attribute for popups, or through window.parent for pages loaded in an IFRAME). The message MUST consist of the DOMString "LOGINDONE". This message informs the application that another attempt at generating an identity assertion is likely to be successful.
Identity assertion validation happens when
is invoked on
setRemoteDescription
. The process runs asynchronously, meaning that validation of an identity assertion might not block the completion of RTCPeerConnection
setRemoteDescription
.
The identity assertion request process involves the following asynchronous steps:
The RTCPeerConnection
awaits any prior identity validation. Only one identity validation can run at a time for an
RTCPeerConnection
. This can happen because the resolution of setRemoteDescription
is not blocked by identity validation unless there is a target peer
identity.
The RTCPeerConnection
loads the identity assertion from the session description and decodes the base64 value, then parses the resulting JSON. The idp parameter of the resulting dictionary contains a domain and an optional
protocol value that identifies the IdP, as described in [
RTCWEB-SECURITY-ARCH].
The RTCPeerConnection
instantiates the identified IdP as described in 9.1.1 Identity Provider
Selection and
9.2 Registering an IdP Proxy. If the IdP cannot be loaded, instantiated or the IdP proxy is not registered, this process fails.
The RTCPeerConnection
invokes the
method registered by the IdP.validateAssertion
The assertion parameter is taken from the decoded identity assertion. The origin parameter contains the origin of the script that calls the RTCPeerConnection
method that triggers this behavior.
The IdP proxy returns a promise and performs the validation process asynchronously.
The IdP proxy verifies the identity assertion using whatever means necessary. Depending on the authentication protocol this could involve interacting with the IdP server.
If the IdP proxy produces an error or returns a promise that does not resolve to a valid
(see 9.5 IdP Error Handling), then identity validation fails.RTCIdentityValidationResult
Once the assertion is successfully verified, the IdP proxy resolves the promise with an
containing the validated identity and the original contents that are the payload of the assertion.RTCIdentityValidationResult
The RTCPeerConnection
decodes the
and validates that it contains a fingerprint value for every contents
a=fingerprint
attribute in the session description. This ensures that the certificate used by the remote peer for communications is covered by the identity assertion.
A user agent is required to fail to communicate with peers that offer a certificate that doesn't match an
a=fingerprint
line in the negotiated session description.
The RTCPeerConnection
validates that the domain portion of the identity matches the domain of the IdP as described in [
RTCWEB-SECURITY-ARCH]. If this check fails then the identity validation fails.
The RTCPeerConnection
resolves the
attribute with a new instance of peerIdentity
RTCIdentityAssertion
that includes the IdP domain and peer identity.
The user agent MAY display identity information to a user in its UI. Any user identity information that is displayed in this fashion MUST use a mechanism that cannot be spoofed by content.
If identity validation fails, the
promise is rejected with a newly created
peerIdentity
OperationError
.
If identity validation fails and there is a target peer
identity for the RTCPeerConnection
, the promise returned by setRemoteDescription
MUST be rejected with the same
DOMException
.
If identity validation fails and there is no a target peer
identity, the value of the
MUST be set to a new, unresolved promise instance. This permits the use of renegotiation (or a subsequent answer, if the session description was a provisional answer) to resolve or reject the identity.peerIdentity
Errors in IdP processing will - in most cases - result in the failure of the procedure that invoked the IdP proxy. This will result in the rejection of the promise returned by
, getIdentityAssertion
, or createOffer
. An IdP proxy error causes a
createAnswer
promise to be rejected if there is a target peer identity; IdP errors in calls to setRemoteDescription
where there is no
target peer identity cause the setRemoteDescription
promise to be rejected instead.
peerIdentity
If an error occurs these promises are rejected with a
RTCError
if an error occurs in interacting with the IdP proxy. The following scenarios result in errors:
A RTCPeerConnection
might be configured with an identity provider, but loading of the IdP URI fails. Any procedure that attempts to invoke such an identity provider and cannot load the URI fails with an RTCError
with errorDetail
set to "IdPLoadFailure" and the httpRequestStatusCode attribute of the error set to the HTTP status code of the response.
If the IdP loads fails due to the TLS certificate used for the HTTPS connection not being trusted, it fails with an
RTCError
with errorDetail
set to "IdpTlsFailure". This typically happens when the IdP uses certificate pinning and an intermediary such as an enterprise firewall has intercepted the TLS connection.
If the script loaded from the identity provider is not valid JavaScript or does not implement the correct interfaces, it causes an IdP failure with an RTCError
with
errorDetail
set to "IdPBadScriptFailure".
An apparently valid identity provider might fail in several ways.
If the IdP token has expired, then the IdP MUST fail with an
RTCError
with errorDetail
set to "IdPTokenExpired".
If the IdP token is not valid, then the IdP MUST fail with an
RTCError
with errorDetail
set to "IdPTokenInvalid".
If an identity provider throws an exception or returns a promise that is ultimately rejected, then the procedure that depends on the IdP
MUST also fail. These types of errors will cause an IdP failure with an
RTCError
with errorDetail
set to "IdPExecutionFailure".
The user agent SHOULD limit the time that it allows for an IdP to 15 seconds. This includes both the loading of the IdP proxy and the identity assertion generation or validation. Failure to do so potentially causes the corresponding operation to take an indefinite amount of time. This timer can be cancelled when the IdP proxy produces a response. Expiration of this timer cases an IdP failure with an
RTCError
with errorDetail
set to "IdPTimeout".
If the identity provider requires the user to login, the operation will fail RTCError
with errorDetail
set to "IdPNeedLogin" and the idpLoginUrl
attribute of the error set to the URL that can be used to login.
Even when the IdP proxy produces a positive result, the procedure that uses this information might still fail. Additional validation of a RTCIdentityValidationResult
value is still necessary. The procedure for validation of identity
assertions describes additional steps that are required to successfully validate the output of the IdP proxy.
Any error generated by the IdP MAY provide additional information in the idpErrorInfo
attribute. The information in this string is defined by the IdP in use.
The Identity API extends the
interface as described below.RTCPeerConnection
partial interface RTCPeerConnection
{
void setIdentityProvider
(DOMString provider,
optional RTCIdentityProviderOptions
options);
Promise<DOMString> getIdentityAssertion
();
readonly attribute Promise<RTCIdentityAssertion
> peerIdentity
;
readonly attribute DOMString? idpLoginUrl
;
readonly attribute DOMString? idpErrorInfo
;
};
peerIdentity
of type Promise<RTCIdentityAssertion
>,
readonlyA promise that resolves with the identity of the peer if the identity is successfully validated.
This promise is rejected if an identity assertion is present in a remote session description and validation of that assertion fails for any reason. If the promise is rejected, a new unresolved value is created, unless a target peer identity has been established. If this promise successfully resolves, the value will not change.
idpLoginUrl
of type DOMString, readonly , nullableThe URL that an application can navigate to so that the user can login to the IdP, as described in 9.3.1 User Login Procedure.
idpErrorInfo
of type DOMString, readonly , nullableAn attribute that the IdP can use to pass additional information back to the applications about the error. The format of this string is defined by the IdP and may be JSON.
setIdentityProvider
Sets the identity provider to be used for a given
RTCPeerConnection
object. Applications need not make this call; if the browser is already configured for an IdP, then that configured IdP might be used to get an assertion.
When the setIdentityProvider
method is invoked, the user agent MUST run the following steps:
If the
object's [[
isClosed]] slot is RTCPeerConnection
true
, throw an
InvalidStateError
.
Set the current identity provider values to the tuple (provider
, options
).
If any identity provider value has changed, discard any stored identity assertion.
Identity provider information is not used until an identity assertion is required, either in response to a call to
getIdentityAssertion
, or a session description is requested with a call to either createOffer
or
createAnswer
.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
provider | DOMString |
✘ | ✘ | |
options |
RTCIdentityProviderOptions |
✘ | ✔ |
void
getIdentityAssertion
Initiates the process of obtaining an identity assertion. Applications need not make this call. It is merely intended to allow them to start the process of obtaining identity assertions before a call is initiated. If an identity is needed, either because the browser has been configured with a default identity provider or because the
method was called, then an identity will be automatically requested when an offer or answer is created.setIdentityProvider
When getIdentityAssertion
is invoked, queue a task to run the following steps:
If the
object's [[
isClosed]] slot is RTCPeerConnection
true
, throw an
InvalidStateError
.
Request an identity assertion from the IdP.
Resolve the promise with the base64 and JSON encoded assertion.
Promise<DOMString>
dictionary RTCIdentityProviderOptions
{
DOMString protocol
= "default";
DOMString usernameHint
;
DOMString peerIdentity
;
};
RTCIdentityProviderOptions
Membersprotocol
of type DOMStringThe name of the protocol that is used by the identity provider. This MUST NOT include '/' (U+002F) or '\' (U+005C) characters. This value defaults to "default" if not provided.
usernameHint
of type DOMStringA hint to the identity provider about the identity of the principal for which it should generate an identity assertion. If absent, the value undefined
is used.
peerIdentity
of type DOMStringThe identity of the peer. For identity providers that bind their assertions to a particular pair of communication peers, this allows them to generate an assertion that includes both local and remote identities. If this value is omitted, but a value is provided for the peerIdentity
member of
, the value from
RTCConfiguration
is used.RTCConfiguration
[Constructor(DOMString idp, DOMString name)]
interface RTCIdentityAssertion
{
attribute DOMString idp
;
attribute DOMString name
;
};
RTCIdentityAssertion
Attributesidp
of type DOMStringThe domain name of the identity provider that validated this identity.
name
of type DOMStringAn RFC5322-conformant [RFC5322] representation of the verified peer identity. This identity will have been verified via the procedures described in [RTCWEB-SECURITY-ARCH].
The identity system is designed so that applications need not take any special action in order for users to generate and verify identity assertions; if a user has configured an IdP into their browser, then the browser will automatically request/generate assertions and the other side will automatically verify them and display the results. However, applications may wish to exercise tighter control over the identity system as shown by the following examples.
This example shows how to configure the identity provider.
pc.setIdentityProvider("example.com");
This example shows how to configure the identity provider with all the options.
pc.setIdentityProvider("example.com", {
protocol: "default",
usernameHint: "alice@example.com",
peerIdentity: "bob@example.net"
});
This example shows how to consume identity assertions inside a Web application.
pc.peerIdentity.then(identity =>
console.log("IdP= " + identity.idp + " identity=" + identity.name));
The MediaStreamTrack
interface, as defined in the [
GETUSERMEDIA] specification, typically represents a stream of data of audio or video. One or more MediaStreamTrack
s can be collected in a MediaStream
(strictly speaking, a
MediaStream
as defined in [GETUSERMEDIA] may contain zero or more MediaStreamTrack
objects).
A MediaStreamTrack
may be extended to represent a media flow that either comes from or is sent to a remote peer (and not just the local camera, for instance). The extensions required to enable this capability on the MediaStreamTrack
object will be described in this section. How the media is transmitted to the peer is described in [
RTCWEB-RTP], [RTCWEB-AUDIO], and [RTCWEB-TRANSPORT].
A MediaStreamTrack
sent to another peer will appear as one and only one MediaStreamTrack
to the recipient. A peer is defined as a user agent that supports this specification. In addition, the sending side application can indicate what MediaStream
object(s) the MediaStreamTrack
is member of. The corresponding MediaStream
object(s) on the receiver side will be created (if not already present) and populated accordingly.
As also described earlier in this document, the objects
RTCRtpSender
and RTCRtpReceiver
can be used by the application to get more fine grained control over the transmission and reception of MediaStreamTrack
s.
Channels are the smallest unit considered in the
MediaStream
specification. Channels are intended to be encoded together for transmission as, for instance, an RTP payload type. All of the channels that a codec needs to encode jointly MUST be in the same MediaStreamTrack
and the codecs SHOULD be able to encode, or discard, all the channels in the track.
The concepts of an input and output to a given
MediaStreamTrack
apply in the case of
MediaStreamTrack
objects transmitted over the network as well. A
created by an
MediaStreamTrack
object (as described previously in this document) will take as input the data received from a remote peer. Similarly, a RTCPeerConnection
MediaStreamTrack
from a local source, for instance a camera via [GETUSERMEDIA], will have an output that represents what is transmitted to a remote peer if the object is used with an
object.RTCPeerConnection
The concept of duplicating MediaStream
and
MediaStreamTrack
objects as described in [GETUSERMEDIA] is also applicable here. This feature can be used, for instance, in a video-conferencing scenario to display the local video from the user's camera and microphone in a local monitor, while only transmitting the audio to the remote peer (e.g. in response to the user using a "video mute" feature). Combining different MediaStreamTrack
objects into new MediaStream
objects is useful in certain situations.
In this document, we only specify aspects of the following objects that are relevant when used along with an
. Please refer to the original definitions of the objects in the [GETUSERMEDIA] document for general information on using RTCPeerConnection
MediaStream
and
MediaStreamTrack
.
The id
attribute specified in MediaStream
returns an id that is unique to this stream, so that streams can be recognized at the remote end of the
API.RTCPeerConnection
When a MediaStream
is created to represent a stream obtained from a remote peer, the id
attribute is initialized from information provided by the remote source.
The id of a MediaStream
object is unique to the source of the stream, but that does not mean it is not possible to end up with duplicates. For example, the tracks of a locally generated stream could be sent from one user agent to a remote peer using
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).RTCPeerConnection
A MediaStreamTrack
object's reference to its
MediaStream
in the non-local media source case (an RTP source, as is the case for MediaStreamTrack
s received over an
) is always strong.RTCPeerConnection
When an
receives data on an RTP source for the first time, it MUST update the muted state of the corresponding RTCPeerConnection
with the value
MediaStreamTrack
false
.
When one of the SSRCs for RTP source media streams received by an
is removed (either due to reception of a BYE or via timeout), it MUST update
the muted state of the corresponding
RTCPeerConnection
with the value
MediaStreamTrack
true
. If and when packets are received again, the muted state MUST be
updated with the value false
.
The procedure update a track's muted state is specified in [ GETUSERMEDIA].
When a remote source is notified that a
, using the source, has
MediaStreamTrack
ended
[GETUSERMEDIA] the user agent MAY choose to free resources allocated for the incoming stream, for instance turn off the decoder.
The basics of MediaTrackSupportedConstraints
,
MediaTrackCapabilites
, MediaTrackConstraints
and MediaTrackSettings
is outlined in [GETUSERMEDIA]. However, the MediaTrackSettings
for a
MediaStreamTrack
sourced by a
will only be populated with members to the extent that data is supplied by means of the remote
RTCPeerConnection
applied via
RTCSessionDescription
setRemoteDescription
and the actual RTP data. This means that certain members, such as facingMode
,
echoCancellation
, latency
,
deviceId
and groupId
, will always be missing.
A MediaStream acquired using getUserMedia()
is, by default, accessible to an application. This means that the application is able to access the contents of tracks, modify their content, and send that media to any peer it chooses.
WebRTC supports calling scenarios where media is sent to a specifically identified peer, without the contents of media streams being accessible to applications. This is enabled by use of the
peerIdentity
parameter to getUserMedia()
.
An application willingly relinquishes access to media by including a
peerIdentity
parameter in the
MediaStreamConstraints
. This attribute is set to a
DOMString
containing the identity of a specific peer.
The MediaStreamConstraints
dictionary is expanded to include the peerIdentity
parameter.
partial dictionary MediaStreamConstraints
{
DOMString peerIdentity
;
};
peerIdentity
of type DOMStringIf set, peerIdentity
isolates media from the application. Media can only be sent to the identified peer.
A user that is prompted to provide consent for access to a camera or microphone can be shown the value of the peerIdentity
parameter, so that they can be informed that the consent is more narrowly restricted.
When the peerIdentity
option is supplied to
getUserMedia()
, all of the MediaStreamTrack
s in the resulting MediaStream
are isolated so that content is not accessible to any application. Isolated
MediaStreamTrack
s can be used for two purposes:
Displayed in an appropriate media tag (e.g., a video or audio element). The browser MUST ensure that content is inaccessible to the application by ensuring that the resulting content is given the same protections as content that is CORS cross-origin, as described in the relevant Security and privacy considerations section of [HTML5].
Used as the argument to addTrack
on an
instance, subject to the restrictions in isolated streams and
RTCPeerConnection.RTCPeerConnection
A MediaStreamTrack
that is added to another
MediaStream
remains isolated. When an isolated
MediaStreamTrack
is added to a MediaStream
with a different peerIdentity, the MediaStream
gets a combination of isolation restrictions. A MediaStream
containing
MediaStreamTrack
instances with mixed isolation properties can be displayed, but cannot be sent using
.RTCPeerConnection
Any peerIdentity
property MUST be retained on cloned copies of MediaStreamTrack
s.
MediaStreamTrack
is expanded to include an
isolated attribute and a corresponding event. This allows an application to quickly and easily determine whether a track is accessible.
partial interface MediaStreamTrack
{
readonly attribute boolean isolated
;
attribute EventHandler onisolationchange
;
};
isolated
of type boolean, readonlyA MediaStreamTrack
is isolated (and the corresponding isolated attribute set to
true) when content is inaccessible to the owning document. This occurs as a result of setting the
peerIdentity option. A track is also isolated if it comes from a cross origin source.
onisolationchange
of type
EventHandlerThis event handler, of type isolationchange
, is fired when the value of the isolated attribute changes.
A MediaStreamTrack
with a peerIdentity option set can be added to any
. However, the content of an isolated track MUST NOT be transmitted unless all of the following constraints are met:RTCPeerConnection
A MediaStreamTrack
from a stream acquired using the
peerIdentity option can be transmitted if the
has successfully validated the identity of the peer AND that identity is the same identity that was used in the
peerIdentity option associated with the track. That is, the RTCPeerConnection
name
attribute of the peerIdentity
attribute of the
instance
MUST match the value of the RTCPeerConnection
peerIdentity
option passed to getUserMedia()
.
Rules for matching identity are described in [ RTCWEB-SECURITY-ARCH].
The peer has indicated that it will respect the isolation properties of streams. That is, a DTLS connection with a promise to respect stream confidentiality, as defined in [RTCWEB-ALPN] has been established.
Failing to meet these conditions means that no media can be sent for the affected MediaStreamTrack
. Video MUST be replaced by black frames, audio MUST be replaced by silence, and equivalently information-free content MUST be provided for other media types.
Remotely sourced MediaStreamTrack
s MUST be isolated if they are received over a DTLS connection that has been negotiated with track isolation. This protects isolated media from the application in the receiving browser. These tracks MUST only be displayed to a user using the appropriate media element (e.g., <video> or <audio>).
Any MediaStreamTrack
that has the
peerIdentity option set causes all tracks sent using the same
to be isolated at the receiving peer. All DTLS connections created for a
RTCPeerConnection
with isolated local streams MUST be negotiated so that media remains isolated at the remote peer. This causes non-isolated media to become isolated at the receiving peer if any isolated tracks are added to the same
RTCPeerConnection
.RTCPeerConnection
Tracks that are not bound to a particular peerIdentity do not cause other streams to be isolated, these tracks simply do not have their content transmitted.
If a stream becomes isolated after initially being accessible, or an isolated stream is added to an active session, then media for that stream is replaced by information-free content (e.g., black frames or silence).
Media isolation ensures that the content of a
MediaStreamTrack
is not accessible to web applications. However, to ensure that media with a peerIdentity option set can be sent to peers, some meta-information about the media will be exposed to applications.
Applications will be able to observe the parameters of the media that affect session negotiation and conversion into RTP. This includes the codecs that might be supported by the track, the bitrate, the number of packets, and the current settings that are set on the
MediaStreamTrack
.
In particular, the statistics that
records are not reduced in capability. New statistics that might compromise isolation MUST be avoided, or explicitly suppressed for isolated streams.RTCPeerConnection
Most of these data are exposed to the network when the media is transmitted. Only the settings for the MediaStreamTrack
present a new source of information. This can includes the frame rate and resolution of video tracks, the bandwidth of audio tracks, and other information about the source, which would not otherwise be revealed to a network observer. Since settings don't change at a high frequency or in response to changes in media content, settings only reveal limited reveal information about the content of a track. However, any setting that might change dynamically in response to the content of an isolated MediaStreamTrack
MUST have changes suppressed.
This section is non-normative.
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.
var signalingChannel = new SignalingChannel();
var configuration = { "iceServers": [{ "urls": "stuns:stun.example.org" }] };
var pc;
// call start() to initiate
function start() {
pc = new RTCPeerConnection(configuration);
// send any ice candidates to the other peer
pc.onicecandidate = function (evt) {
signalingChannel.send(JSON.stringify({ "candidate": evt.candidate }));
};
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = function () {
pc.createOffer().then(function (offer) {
return pc.setLocalDescription(offer);
})
.then(function () {
// send the offer to the other peer
signalingChannel.send(JSON.stringify({ "desc": pc.localDescription }));
})
.catch(logError);
};
// once remote video track arrives, show it in the remote video element
pc.ontrack = function (evt) {
if (evt.track.kind === "video")
remoteView.srcObject = evt.streams[0];
};
// get a local stream, show it in a self-view and add it to be sent
navigator.mediaDevices.getUserMedia({ "audio": true, "video": true })
.then(function (stream) {
selfView.srcObject = stream;
pc.addTrack(stream.getAudioTracks()[0], stream);
pc.addTrack(stream.getVideoTracks()[0], stream);
})
.catch(logError);
}
signalingChannel.onmessage = function (evt) {
if (!pc)
start();
var message = JSON.parse(evt.data);
if (message.desc) {
var desc = message.desc;
// if we get an offer, we need to reply with an answer
if (desc.type == "offer") {
pc.setRemoteDescription(desc).then(function () {
return pc.createAnswer();
})
.then(function (answer) {
return pc.setLocalDescription(answer);
})
.then(function () {
var str = JSON.stringify({ "desc": pc.localDescription });
signalingChannel.send(str);
})
.catch(logError);
} else if (desc.type == "answer") {
pc.setRemoteDescription(desc).catch(logError);
} else {
log("Unsupported SDP type. Your code may differ here.");
}
} else
pc.addIceCandidate(message.candidate).catch(logError);
};
function logError(error) {
log(error.name + ": " + error.message);
}
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.
var signalingChannel = new SignalingChannel();
var configuration = { "iceServers": [{ "urls": "stuns:stun.example.org" }] };
var pc;
var audio = null;
var audioSendTrack = null;
var video = null;
var videoSendTrack = null;
var started = false;
// Call warmup() to warm-up ICE, DTLS, and media, but not send media yet.
function warmup(answerer) {
pc = new RTCPeerConnection(configuration);
if (!answerer) {
audio = pc.addTransceiver("audio");
video = pc.addTransceiver("video");
}
// send any ice candidates to the other peer
pc.onicecandidate = function (evt) {
signalingChannel.send(JSON.stringify({ "candidate": evt.candidate }));
};
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = function () {
pc.createOffer().then(function (offer) {
return pc.setLocalDescription(offer);
})
.then(function () {
// send the offer to the other peer
signalingChannel.send(JSON.stringify({ "desc": pc.localDescription }));
})
.catch(logError);
};
// once remote video track arrives, show it in the remote video element
pc.ontrack = function (evt) {
if (evt.track.kind === "audio") {
if (answerer) {
audio = evt.transceiver;
audio.setDirection("sendrecv");
if (started && audioSendTrack) {
audio.sender.replaceTrack(audioSendTrack);
}
}
} else if (evt.track.kind === "video") {
if (answerer) {
video = evt.transceiver;
video.setDirection("sendrecv");
if (started && videoSendTrack) {
video.sender.replaceTrack(videoSendTrack);
}
}
remoteView.srcObject = evt.streams[0];
}
};
// get a local stream, show it in a self-view and add it to be sent
navigator.mediaDevices.getUserMedia({ "audio": true, "video": true })
.then(function (stream) {
selfView.srcObject = stream;
audioSendTrack = stream.getAudioTracks()[0];
if (started) {
audio.sender.replaceTrack(audioSendTrack);
}
videoSendTrack = stream.getVideoTracks()[0];
if (started) {
video.sender.replaceTrack(videoSendTrack);
}
})
.catch(logError);
}
// Call start() to start sending media.
function start() {
started = true;
signalingChannel.send(JSON.stringify({ "start": true }));
}
signalingChannel.onmessage = function (evt) {
if (!pc)
warmup(true);
var message = JSON.parse(evt.data);
if (message.desc) {
var desc = message.desc;
// if we get an offer, we need to reply with an answer
if (desc.type == "offer") {
pc.setRemoteDescription(desc).then(function () {
return pc.createAnswer();
})
.then(function (answer) {
return pc.setLocalDescription(answer);
})
.then(function () {
var str = JSON.stringify({ "desc": pc.localDescription });
signalingChannel.send(str);
})
.catch(logError);
} else
pc.setRemoteDescription(desc).catch(logError);
} else if (message.start) {
started = true;
if (audio && audioSendTrack) {
audio.sender.replaceTrack(audioSendTrack);
}
if (video && videoSendTrack) {
video.sender.replaceTrack(videoSendTrack);
}
} else
pc.addIceCandidate(message.candidate).catch(logError);
};
function logError(error) {
log(error.name + ": " + error.message);
}
The answerer may wish to send media in parallel with sending the answer, and the offerer may wish to render the media before the answer arrives.
var signalingChannel = new SignalingChannel();
var configuration = { "iceServers": [{ "urls": "stuns:stun.example.org" }] };
var pc;
// call start() to initiate
function start() {
pc = new RTCPeerConnection(configuration);
// send any ice candidates to the other peer
pc.onicecandidate = function (evt) {
signalingChannel.send(JSON.stringify({ "candidate": evt.candidate }));
};
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = function () {
pc.createOffer().then(function (offer) {
return pc.setLocalDescription(offer);
})
.then(function () {
// send the offer to the other peer
signalingChannel.send(JSON.stringify({ "desc": pc.localDescription }));
})
.catch(logError);
};
// get a local stream, show it in a self-view and add it to be sent
navigator.mediaDevices.getUserMedia({ "audio": true, "video": true })
.then(function (stream) {
selfView.srcObject = stream;
var remoteStream = new MediaStream();
var audioSender = pc.addTrack(stream.getAudioTracks()[0], stream);
var videoSender = pc.addTrack(stream.getVideoTracks()[0], stream);
[audioSender, videoSender].forEach(function(sender) {
remoteStream.addTrack(pc.getReceivers.find(function (receiver) {
return receiver.mid == sender.mid;
}).track);
});
// Render the media even before ontrack fires.
remoteView.srcObject = remoteStream;
})
.catch(logError);
}
signalingChannel.onmessage = function (evt) {
if (!pc)
start();
var message = JSON.parse(evt.data);
if (message.desc) {
var desc = message.desc;
// if we get an offer, we need to reply with an answer
if (desc.type == "offer") {
pc.setRemoteDescription(desc).then(function () {
return pc.createAnswer();
})
.then(function (answer) {
return pc.setLocalDescription(answer);
})
.then(function () {
var str = JSON.stringify({ "desc": pc.localDescription });
signalingChannel.send(str);
})
.catch(logError);
} else
pc.setRemoteDescription(desc).catch(logError);
} else
pc.addIceCandidate(message.candidate).catch(logError);
};
function logError(error) {
log(error.name + ": " + error.message);
}
A client wants to send multiple RTP encodings (simulcast) to a server.
var signalingChannel = new SignalingChannel();
var configuration = { "iceServers": [{ "urls": "stuns:stun.example.org" }] };
var pc;
// call start() to initiate
function start() {
pc = new RTCPeerConnection(configuration);
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = function () {
pc.createOffer().then(function (offer) {
return pc.setLocalDescription(offer);
})
.then(function () {
// send the offer to the other peer
signalingChannel.send(JSON.stringify({ "desc": pc.localDescription }));
})
.catch(logError);
};
// get a local stream, show it in a self-view and add it to be sent
navigator.mediaDevices.getUserMedia({ "audio": true, "video": true })
.then(function (stream) {
selfView.srcObject = stream;
pc.addTransceiver(stream.getAudioTracks()[0], {direction: "sendonly"});
pc.addTransceiver(stream.getVideoTracks()[0], {
direction: "sendonly",
sendEncodings: [
{
rid: "f",
},
{
rid: "h",
scaleDownResolutionBy: 2.0
},
{
rid: "q",
scaleDownResolutionBy: 4.0
}
]
});
})
.catch(logError);
}
signalingChannel.onmessage = function (evt) {
var message = JSON.parse(evt.data);
if (message.desc)
pc.setRemoteDescription(message.desc).catch(logError);
else
pc.addIceCandidate(message.candidate).catch(logError);
};
function logError(error) {
log(error.name + ": " + error.message);
}
This example shows how to create a
object and perform the offer/answer exchange required to connect the channel to the other peer. The
RTCDataChannel
is used in the context of a simple chat application and listeners are attached to monitor when the channel is ready, messages are received and when the channel is closed.RTCDataChannel
var signalingChannel = new SignalingChannel();
var configuration = { "iceServers": [{ "urls": "stuns:stun.example.org" }] };
var pc;
var channel;
// call start(true) to initiate
function start(isInitiator) {
pc = new RTCPeerConnection(configuration);
// send any ice candidates to the other peer
pc.onicecandidate = function (evt) {
signalingChannel.send(JSON.stringify({ "candidate": evt.candidate }));
};
// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = function () {
pc.createOffer().then(function (offer) {
return pc.setLocalDescription(offer);
})
.then(function () {
// send the offer to the other peer
signalingChannel.send(JSON.stringify({ "desc": pc.localDescription }));
})
.catch(logError);
};
if (isInitiator) {
// create data channel and setup chat
channel = pc.createDataChannel("chat");
setupChat();
} else {
// setup chat on incoming data channel
pc.ondatachannel = function (evt) {
channel = evt.channel;
setupChat();
};
}
}
signalingChannel.onmessage = function (evt) {
if (!pc)
start(false);
var message = JSON.parse(evt.data);
if (message.desc) {
var desc = message.desc;
// if we get an offer, we need to reply with an answer
if (desc.type == "offer") {
pc.setRemoteDescription(desc).then(function () {
return pc.createAnswer();
})
.then(function (answer) {
return pc.setLocalDescription(answer);
})
.then(function () {
var str = JSON.stringify({ "desc": pc.localDescription });
signalingChannel.send(str);
})
.catch(logError);
} else
pc.setRemoteDescription(desc).catch(logError);
} else
pc.addIceCandidate(message.candidate).catch(logError);
};
function setupChat() {
channel.onopen = function () {
// e.g. enable send button
enableChat(channel);
};
channel.onmessage = function (evt) {
showChatMessage(evt.data);
};
}
function sendChatMessage(msg) {
channel.send(msg);
}
function logError(error) {
log(error.name + ": " + error.message);
}
Editors' Note: This example flow needs to be discussed on the list and is likely wrong in many ways.
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.
Examples assume that sender is an RTCRtpSender.
Sending the DTMF signal "1234" with 500 ms duration per tone:
if (sender.dtmf) {
var duration = 500;
sender.dtmf.insertDTMF("1234", duration);
} else
log("DTMF function not available");
Send the DTMF signal "1234", and light up the active key using
lightKey(key)
while the tone is playing (assuming that
lightKey("")
will darken all the keys):
if (sender.dtmf) {
sender.dtmf.ontonechange = function (e) {
if (!e.tone)
return;
// light up the key when playout starts
lightKey(e.tone);
// turn off the light after tone duration
setTimeout(lightKey, sender.duration, "");
};
sender.dtmf.insertDTMF("1234");
} else
log("DTMF function not available");
Send a 1-second "1" tone followed by a 2-second "2" tone:
if (sender.dtmf) {
sender.dtmf.ontonechange = function (e) {
if (e.tone == "1")
sender.dtmf.insertDTMF("2", 2000);
};
sender.dtmf.insertDTMF("1", 1000);
} else
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) {
sender.dtmf.insertDTMF("123");
// append more tones to the tone buffer before playout has begun
sender.dtmf.insertDTMF(sender.toneBuffer + "456");
sender.dtmf.ontonechange = function (e) {
if (e.tone == "1")
// append more tones when playout has begun
sender.dtmf.insertDTMF(sender.toneBuffer + "789");
};
} else
log("DTMF function not available");
Send the DTMF signal "123" and abort after sending "2".
if (sender.dtmf) {
sender.dtmf.ontonechange = function (e) {
if (e.tone == "2")
// empty the buffer to not play any tone after "2"
sender.dtmf.insertDTMF("");
};
sender.dtmf.insertDTMF("123");
} else
log("DTMF function not available");
This section and its subsections extend the list of Error subclasses defined in [ECMASCRIPT-6.0] following the pattern for NativeError in section 19.5.6 of that specification. Assume the following:
%RTCError%
and
%RTCErrorPrototype%
are available as if they had been included in ([ECMASCRIPT-6.0], Table 7) and all referencing sections, e.g. ([
ECMASCRIPT-6.0], section 8.2.2), thus behave appropriately.The following terms used in this section are defined in [ECMASCRIPT-6.0].
Term/Notation | Section in [ECMASCRIPT-6.0] |
---|---|
Type(X) | 6 |
intrinsic object | 6.1.7.4 |
[[ErrorData]] | 19.5.1 |
internal slot | 6.1.7.2 |
NewTarget | various uses, but no definition |
active function object | 8.3 |
OrdinaryCreateFromConstructor() | 9.1.14 |
ReturnIfAbrupt() | 6.2.2.4 |
Assert | 5.2 |
String | 4.3.17-19, depending on context |
PropertyDescriptor | 6.2.4 |
[[Value]] | 6.1.7.1 |
[[Writable]] | 6.1.7.1 |
[[Enumerable]] | 6.1.7.1 |
[[Configurable]] | 6.1.7.1 |
DefinePropertyOrThrow() | 7.3.7 |
abrupt completion | 6.2.2 |
ToString() | 7.1.12 |
[[Prototype]] | 9.1 |
%Error% | 19.5.1 |
Error | 19.5 |
%ErrorPrototype% | 19.5.3 |
Object.prototype.toString | 19.1.3.6 |
The RTCError Constructor is the %RTCError%
intrinsic object. When RTCError
is called as a function rather than as a constructor, it creates and initializes a new
RTCError
object. A call of the object as a function is equivalent to calling it as a constructor with the same arguments. Thus the function call RTCError(...)
is equivalent to the object creation expression new
RTCError(...)
with the same arguments.
The RTCError
constructor is designed to be subclassable. It may be used as the value of an extends
clause of a class definition. Subclass constructors that intend to inherit the specified RTCError
behaviour must include a super
call to the
RTCError
constructor to create and initialize the subclass instance with an [[ErrorData]] internal slot.
TODO - make a enum for all the error details? Is the enum OK for extending?
When the RTCError
function is called with arguments errorDetail and message the following steps are taken:
"%RTCErrorPrototype%"
, «[[ErrorData]]» ).
errorDetail
", errorDetailDesc).message
", msgDesc).The value of the [[Prototype]] internal slot of the
constructor is the intrinsic object RTCError
%Error%
.
Besides the length
property (whose value is 1), the
constructor has the following properties:RTCError
The initial value of RTCError.prototype
is the RTCError
prototype object. This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
The
prototype object is an ordinary object. It is not an Error instance and does not have an [[ErrorData]] internal slot.RTCError
The value of the [[Prototype]] internal slot of the
prototype object is the intrinsic object
RTCError
%ErrorPrototype%
.
The initial value of the constructor
property of the prototype for the
constructor is the intrinsic object RTCError
%RTCError%
.
The initial value of the errorDetail
property of the prototype for the
constructor is the empty String.RTCError
The initial value of the sdpLineNumber
property of the prototype for the
constructor is 0.RTCError
The initial value of the httpRequestStatusCode
property of the prototype for the
constructor is 0.RTCError
The initial value of the message
property of the prototype for the
constructor is the empty String.RTCError
The initial value of the name
property of the prototype for the RTCError constructor is
"RTCError"
.
instances are ordinary objects that inherit properties from the RTCError
prototype object and have an [[ErrorData]] internal slot whose value is undefined. The only specified use of [[ErrorData]] is by Object.prototype.toString ([
ECMASCRIPT-6.0], section 19.1.3.6) to identify instances of Error or its various subclasses.RTCError
The following interface is defined for cases when an RTCError is raised as an event:
[Exposed=Window,
Constructor(DOMString type, RTCErrorEventInit
eventInitDict)]
interface RTCErrorEvent
: Event {
readonly attribute RTCError
? error
;
};
RTCErrorEvent
Constructs a new
.RTCErrorEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type | DOMString |
✘ | ✘ | |
eventInitDict |
RTCErrorEventInit |
✘ | ✘ |
dictionary RTCErrorEventInit
: EventInit {
RTCError
? error
= null;
};
RTCErrorEventInit
MembersThis section is non-normative.
The following events fire on
objects:RTCDataChannel
Event name | Interface | Fired when... |
---|---|---|
open |
Event |
The object's underlying data
transport has been established (or re-established).
|
message |
MessageEvent [
webmessaging] |
A message was successfully received. |
bufferedamountlow |
Event |
The object's
decreases from above its to less than or equal to its . |
error |
|
Any error occured from the data channel. |
close |
Event |
The object's underlying data
transport has bee closed.
|
The following events fire on
objects:RTCPeerConnection
Event name | Interface | Fired when... |
---|---|---|
track |
|
A new incoming MediaStreamTrack has been created, and an associated RTCRtpReceiver has been added to the set of receivers. |
negotiationneeded |
Event |
The browser wishes to inform the application that session negotiation needs to be done (i.e. a createOffer call followed by setLocalDescription). |
signalingstatechange |
Event |
The signaling state has changed. This state change is the result of either or
being invoked.
|
iceconnectionstatechange |
Event |
The RTCPeerConnection 's ICE connection state has changed.
|
icegatheringstatechange |
Event |
The RTCPeerConnection 's ICE gathering state has changed.
|
icecandidate |
|
A new is made available to the script. |
connectionstatechange |
Event |
The RTCPeerConnection connectionState has changed.
|
icecandidateerror |
|
A failure occured when gathering ICE candidates. |
datachannel |
|
A new is dispatched to the script in response to the other peer creating a channel. |
isolationchange |
Event |
A new Event is dispatched to the script when the isolated attribute on a MediaStreamTrack changes.
|
fingerprintfailure |
Event |
The RTCPeerConnection 's DTLS Certificate did not match any of the fingerprints in the SDP.
|
The following events fire on
objects:RTCDTMFSender
Event name | Interface | Fired when... |
---|---|---|
tonechange |
|
The object has either just begun playout of a tone (returned as the attribute) or just ended the playout of tones in the
(returned as an empty value in the
attribute). |
The following events fire on
objects:RTCIceTransport
Event name | Interface | Fired when... |
---|---|---|
statechange |
Event |
The state changes. |
gatheringstatechange |
Event |
The gathering state changes.
|
selectedcandidatepairchange |
Event |
The 's selected candidate pair changes.
|
The following events fire on
objects:RTCDtlsTransport
Event name | Interface | Fired when... |
---|---|---|
statechange |
Event |
The state changes. |
This section is non-normative.
This section is non-normative; it specifies no new behaviour, but instead summarizes information already present in other parts of the specification. The overall security considerations of the general set of APIs and protocols used in WebRTC are described in [ RTCWEB-SECURITY-ARCH].
This document extends the Web platform with the ability to set up real time, direct communication between browsers and other devices, including other browsers.
This means that data and media can be shared between applications running in different browsers, or between an application running in the same browser and something that is not a browser, something that is an extension to the usual barriers in the Web model against sending data between entities with different origins.
The WebRTC specification provides no user prompts or chrome indicators for communication; it assumes that once the Web page has been allowed to access media, it is free to share that media with other entities as it chooses. Peer-to-peer exchanges of data view WebRTC datachannels can thus occur without any user explicit consent or involvement, similarly as a server-mediated exchange (e.g. via Web Sockets) could occur without user involvement.
The
mechanism loads and executes JavaScript code from a third-party server acting as an identity provider. That code is executed in a separate JavaScript realm and does not affect the protections afforded by the same origin policy.peerIdentity
Even without WebRTC, the Web server providing a Web application will know the public IP address to which the application is delivered. Setting up communications exposes additional information about the browser’s network context to the web application, and may include the set of (possibly private) IP addresses available to the browser for WebRTC use. Some of this information has to be passed to the corresponding party to enable the establishment of a communication session.
Revealing IP addresses can leak location and means of connection; this can be sensitive. Depending on the network environment, it can also increase the fingerprinting surface and create persistent cross-origin state that cannot easily be cleared by the user.
A connection will always reveal the IP addresses proposed for communication to the corresponding party. The application can limit this exposure by choosing not to use certain addresses using the settings exposed by the RTCIceTransportPolicy
dictionary, and by using relays (for instance TURN servers) rather than direct connections between participants. One will normally assume that the IP address of TURN servers is not sensitive information. These choices can for instance be made by the application based on whether the user has indicated consent to start a media connection with the other party.
Mitigating the exposure of IP addresses to the application itself requires limiting the IP addresses that can be used, which will impact the ability to communicate on the most direct path between endpoints. Browsers are encouraged to provide appropriate controls for deciding which IP addresses are made available to applications, based on the security posture desired by the user. The choice of which addresses to expose is controlled by local policy (see [RTCWEB-IP-HANDLING] for details).
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:
These measures are specified in the relevant IETF documents.
The fact that communication is taking place cannot be hidden from adversaries that can observe the network, so this has to be regarded as public information.
A mechanism,
, is provided that gives Javascript the option of requesting media that the same javascript cannot access, but can only be sent to certain other entities.peerIdentity
As described above, the list of IP addresses exposed by the WebRTC API can be used as a persistent cross-origin state.
Beyond IP addresses, the WebRTC API exposes information about the underlying media system via the RTCRtpSender.getCapabilities
and RTCRtpReceiver.getCapabilities
methods, including detailed and ordered information about the codecs that the system is able to produce and consume. A subset of that information is likely to be represented in the SDP session descriptions generated, exposed and transmitted during session
negotiation. That information is in most cases persistent across time and origins, and increases the fingerprint surface of a given device.
If set, the configured default ICE servers exposed by defaultIceServers
on
RTCPeerConnection
instances also provides persistent across time and origins information which increases the fingerprinting surface of a given browser.
When establishing DTLS connections, the WebRTC API can generate certificates that can be persisted by the application (e.g. in IndexedDB). These certificates are not shared across origins, and get cleared when persistent storage is cleared for the origin.
This section will be removed before publication.