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-2015 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 http://www.w3.org/TR/.
This document is neither complete nor stable, and as such is not yet suitable for commercial implementation. However, early experimentation is encouraged. The API is based on preliminary work done in the WHATWG. The Web Real-Time Communications Working Group expects this specification to evolve significantly based on:
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 September 2015 W3C Process Document.
RTCRtpParameters
MembersRTCRtpEncodingParameters
MembersRTCRtxParameters
MembersRTCFecParameters
MembersRTCRtcpParameters
MembersRTCRtpHeaderExtensionParameters
MembersRTCRtpCodecParameters
MembersRTCRtpCapabilities
MembersRTCRtpCodecCapability
MembersRTCRtpHeaderExtensionCapability
MembersThis 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 with the exception of the
interface which is used by the
user agent but not implemented by the user agent.RTCIdentityProvider
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.
The EventHandler
interface represents a callback used for event handlers as defined in
[HTML5].
The concepts queue a task and fires a simple event are defined in [HTML5].
The terms event, event handlers and event handler event types are defined in [HTML5].
The terms MediaStream, MediaStreamTrack, Constraints, and Consumer are defined in [GETUSERMEDIA].
An
allows two users to
communicate directly, browser to browser. 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].
dictionary RTCConfiguration {
sequence<RTCIceServer
> iceServers;
RTCIceTransportPolicy
iceTransportPolicy = "all";
RTCBundlePolicy
bundlePolicy = "balanced";
DOMString peerIdentity;
sequence<RTCCertificate
> certificates;
unsigned short iceCandidatePoolSize = 0;
};
RTCConfiguration
MembersbundlePolicy
of type RTCBundlePolicy
, , defaulting to "balanced"
Indicates which BundlePolicy to use.
certificates
of type sequence<RTCCertificate
>, A set of certificates that
the RTCPeerConnection
uses to authenticate.
Valid values for this parameter are created through calls to
the generateCertificate
function.
Although any given DTLS connection will use only one certificate,
this attribute allows the caller to provide multiple certificates
that support different algorithms. The final certificate will be
selected based on the DTLS handshake, which establishes which
certificates are allowed. The RTCPeerConnection
implementation selects which of the certificates is used for a given
connection; how certificates are selected is outside the scope of
this specification.
If this value is absent, then a set of certificates are generated
for each RTCPeerConnection
instance.
This option allows applications to establish key continuity.
An RTCCertificate
can be persisted in [INDEXEDDB] and
reused. Persistence and reuse also avoids the cost of key
generation.
The value for this configuration option cannot change after its value is initially selected. Attempts to change this value MUST be rejected.
iceCandidatePoolSize
of type unsigned short, , defaulting to 0
Size of the prefetched ICE pool as defined in [RTCWEB-JSEP] Section 3.4.4 and 4.1.1.
iceServers
of type sequence<RTCIceServer
>, An array containing URIs of servers available to be used by ICE, such as STUN and TURN server.
iceTransportPolicy
of type RTCIceTransportPolicy
, , defaulting to "all"
Indicates which candidates the ICE engine is allowed to use.
peerIdentity
of type DOMString, Sets 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.
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. |
Should we have a "none" type, for cases where no authentication is needed? (e.g. STUN)
dictionary RTCIceServer {
required (DOMString or sequence<DOMString>) urls;
DOMString username;
DOMString credential;
RTCIceCredentialType
credentialType = "password";
};
RTCIceServer
Memberscredential
of type DOMString, If 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
urls
of type (DOMString or sequence<DOMString>), requiredSTUN or TURN URI(s) as defined in [RFC7064] and [RFC7065] or other URI types.
username
of type DOMString, If this
object represents a
TURN server, then this attribute specifies the username to use with
that TURN server.RTCIceServer
In network topologies with multiple layers of NATs, it is desirable to have a STUN server between every layer of NATs in addition to the TURN servers to minimize the peer to peer network latency.
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" }
]
enum RTCIceTransportPolicy {
"none",
"relay",
"all"
};
Enumeration description | |
---|---|
none | The ICE engine MUST not send or receive any packets at this point. |
relay | The ICE engine 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 engine may use any type of candidates when this value is specified. |
enum RTCBundlePolicy {
"balanced",
"max-compat",
"max-bundle"
};
Enumeration description | |
---|---|
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. |
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 system 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
{
long offerToReceiveVideo;
long offerToReceiveAudio;
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
offerToReceiveAudio
of type long, In some cases, an RTCPeerConnection
may wish to
receive audio but not send any audio. The
RTCPeerConnection
needs to know if it should signal to
the remote side whether it wishes to receive audio. This option
allows an application to indicate its preferences for the number of
audio streams to receive when creating an offer.
offerToReceiveVideo
of type long, In some cases, an RTCPeerConnection
may wish to
receive video but not send any video. The
RTCPeerConnection
needs to know if it should signal to
the remote side whether it wishes to receive video or not. This
option allows an application to indicate its preferences for the
number of video streams to receive when creating an offer.
dictionary RTCAnswerOptions : RTCOfferAnswerOptions
{
};
The general operation of the RTCPeerConnection is described in [RTCWEB-JSEP].
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 an associated
ICE agent [ICE],
RTCPeerConnection signaling state, ICE gathering state, and ICE
connection state. These are initialized when the object is created.RTCPeerConnection
When the RTCPeerConnection()
constructor
is invoked, the user agent MUST run the following steps:
Let connection be a newly created
object.RTCPeerConnection
Set the configuration specified by the constructor's first argument.
Create an ICE Agent as defined in [ICE] and let
connection's RTCPeerConnection
ICE Agent be
that ICE Agent. The ICE Agent will
proceed with gathering as soon as the ICE transports setting is not set to
none
. At this point the ICE Agent does not know how
many ICE components it needs (and hence the number of candidates to
gather), but it can make a reasonable assumption such as 2. As the
RTCPeerConnection
object gets more information, the
ICE Agent can adjust the number of components.
Set connection's RTCPeerConnection
signalingState to stable
.
Set connection's RTCPeerConnection
ice connection state to new
.
Set connection's RTCPeerConnection
ice gathering state to new
.
Set connection's
pendingLocalDescription
,
currentLocalDescription
,
pendingRemoteDescription
and currentRemoteDescription
to null.
Initialize an internal variable to represent a queue of
operations
with an empty set.
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 InvalidParameter
exception and abort these steps; otherwise, store the certificates.
If no certificates
value was specified, one or more
new RTCCertificate
instances are generated for use with
this RTCPeerConnection
instance.
Return connection.
Once the RTCPeerConnection object has been initialized, for every
call to createOffer
, setLocalDescription
,
createAnswer
, setRemoteDescription
,
and addIceCandidate
;
execute the following steps:
Let p be a new promise.
Append an object representing the current call being handled
(i.e. function name and corresponding arguments) to the
operations
array.
If the length of the operations
array is exactly 1,
execute the object from the front of the queue.
Upon fulfillment or rejection of the promise returned by the function, fulfill or reject p with the corresponding value or reason. Upon fulfillment or rejection of p, execute the following steps:
Remove the corresponding object from
the operations
array.
If the array is non-empty, execute the first object queued.
Return p.
The general idea is to have only one among createOffer
,
setLocalDescription
, createAnswer
and
setRemoteDescription
and addIceCandidate
executing at any given
time. If subsequent calls are made while the returned promise
of a previous call is still unsettled, they are added to a
queue and executed when all the previous calls are executed
and their promises are settled.
Additionally, during the lifetime of the RTCPeerConnection object, the following procedures are followed when an ICE event occurs:
If the RTCPeerConnection
ice gathering state is new
and the ICE transports setting is not set to
none
, the user agent MUST queue a task to start
gathering ICE addresses and set the ice gathering state
to gathering
.
If the ICE Agent has found one or more candidate pairs for each
MediaStreamTrack
that forms a valid connection, the ICE connection
state is changed to "connected".
When the ICE Agent finishes checking all candidate pairs, if at
least one connection has been found for each MediaStreamTrack
, the
RTCPeerConnection
ice connection state is changed to "completed"; otherwise
"failed".
The section above shouldn't need to reference MediaStreamTracks when discussing the ICE connection state; one problem with this is that it doesn't handle the data channel situation properly. Rewrite this to refer to m-lines or ICE "media streams" or some such (here and in the later ICE connection state discussions.)
When the ICE Agent needs to notify the script about the candidate gathering progress, the user agent MUST queue a task to run the following steps:
Let connection be the
object associated with this
ICE Agent.RTCPeerConnection
If connection's RTCPeerConnection
signalingState is closed
, abort these steps.
If the intent of the ICE Agent is to notify the script that:
A new candidate is available.
Add the candidate to connection's
and create a
localDescription
instance to represent the
candidate. Let newCandidate be that object.RTCIceCandidate
The gathering process is done.
Set connection's ice gathering
state to completed
and let
newCandidate be null.
Fire a icecandidate event named icecandidate
with
newCandidate at connection.
The task source for the tasks listed in this section is the networking task source.
To prevent network sniffing from allowing a fourth party to establish a connection to a peer using the information sent out-of-band to the other peer and thus spoofing the client, the configuration information SHOULD always be transmitted using an encrypted connection.
The
interface presented this
section is not complete. The interface is extended by several partial
interfaces throughout this specification. Notably, the RTP Media section, that
adds the APIs to send and receive RTCPeerConnection
objects.MediaStreamTrack
[ Constructor (optional RTCConfiguration
configuration)]
interface RTCPeerConnection : EventTarget {
Promise<RTCSessionDescription
> createOffer (optional RTCOfferOptions
options);
Promise<RTCSessionDescription
> 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 (RTCIceCandidate
candidate);
readonly attribute RTCSignalingState
signalingState;
readonly attribute RTCIceGatheringState
iceGatheringState;
readonly attribute RTCIceConnectionState
iceConnectionState;
readonly attribute RTCPeerConnectionState
connectionState;
readonly attribute boolean? canTrickleIceCandidates;
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;
};
RTCPeerConnection
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
configuration |
| ✘ | ✔ |
canTrickleIceCandidates
of type boolean, readonly , nullableThis 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 Section 4.1.9 of [RTCWEB-JSEP]. Prior to
the completion
of setRemoteDescription
,
this value is null
.
connectionState
of type RTCPeerConnectionState
, readonly The connectionState
attribute MUST return the aggregate of the states of
the DtlsTransport
s
and IceTransport
s of
the RTCPeerConnection
.
currentLocalDescription
of type RTCSessionDescription
, readonly , nullableThe currentLocalDescription
attribute represents the local
that was successfully negotiated the last time the PeerConnection transitioned into
the stable state plus any local candidates that have been generated by the ICE
Agent since the offer or answer was created. This attribute is updated by RTCSessionDescription
setLocalDescription()
.
The currentLocalDescription
attribute MUST return the last value that previous algorithms in this
specification set it to plus any local candidates that have been
generated by the ICE Agent since the offer or answer was created.
currentRemoteDescription
of type RTCSessionDescription
, readonly , nullableThe currentRemoteDescription
attribute represents the last remote
that was successfully
negotiated the last time the PeerConnection transitioned into the
stable state plus any remote candidates that have been supplied via
RTCSessionDescription
addIceCandidate()
since the offer or answer was created. This attribute is updated by
setRemoteDescription()
.
The currentRemoteDescription
attribute MUST return the value that previous algorithms in this
specification set it to plus any remote candidates that have been
supplied via addIceCandidate()
since the offer or answer was created.
iceConnectionState
of type RTCIceConnectionState
, readonly The iceConnectionState
attribute MUST return the state of the RTCPeerConnection
ICE
Agent ICE state.
iceGatheringState
of type RTCIceGatheringState
, readonly The iceGatheringState
attribute MUST return the gathering state of the RTCPeerConnection
ICE
Agent.
localDescription
of type RTCSessionDescription
, readonly , nullableThe localDescription
attribute MUST return pendingLocalDescription
if it is not null and otherwise it MUST return currentLocalDescription
.
onconnectionstatechange
of type EventHandler, connectionstatechange
,
MUST be fired by all objects implementing the
RTCPeerConnection
interface. It is
called any time the RTCPeerConnection
.connectionState
changes.
onicecandidate
of type EventHandler, icecandidate
, MUST be supported by
all objects implementing the RTCPeerConnection
interface.onicecandidateerror
of type EventHandler, icecandidateerror
, MUST be supported by
all objects implementing the RTCPeerConnection
interface.oniceconnectionstatechange
of type EventHandler, iceconnectionstatechange
,
MUST be fired by all objects implementing the
RTCPeerConnection
interface. It is called any
time the RTCPeerConnection
ice connection state changes.
onicegatheringstatechange
of type EventHandler, icegatheringstatechange
,
MUST be fired by all objects implementing the
RTCPeerConnection
interface. It is called any
time
the RTCPeerConnection
ice gathering state changes.
onnegotiationneeded
of type EventHandler, negotiationneeded
, MUST be supported
by all objects implementing the RTCPeerConnection
interface.onsignalingstatechange
of type EventHandler, signalingstatechange
, MUST
be supported by all objects implementing the
RTCPeerConnection
interface. It is called any
time the
RTCPeerConnection
signaling state changes, i.e., from a call to
setLocalDescription
, a call to
setRemoteDescription
, or code. It does not fire for the
initial state change into new
.pendingLocalDescription
of type RTCSessionDescription
, readonly , nullableThe pendingLocalDescription
attribute represents a local
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
PeerConnection is in the stable state, the value is null.
This attribute is updated by RTCSessionDescription
setLocalDescription()
.
The pendingLocalDescription
attribute MUST return the last value that previous algorithms in this
specification set it to plus any local candidates that have been
generated by the ICE Agent since the offer or answer was created.
pendingRemoteDescription
of type RTCSessionDescription
, readonly , nullableThe pendingRemoteDescription
attribute represents a remote
that is in the process of
being negotiated plus any remote candidates that have been supplied
via RTCSessionDescription
addIceCandidate()
since the offer or answer was created. If the
PeerConnection is in the stable state, the value is null.
This attribute is updated by setLocalDescription()
.
The pendingRemoteDescription
attribute MUST return the value that previous algorithms in this
specification set it to plus any remote candidates that have been
supplied via addIceCandidate()
since the offer or answer was created.
remoteDescription
of type RTCSessionDescription
, readonly , nullableThe remoteDescription
attribute MUST return pendingRemoteDescription
if it is not null and otherwise it MUST return currentRemoteDescription
.
signalingState
of type RTCSignalingState
, readonly The signalingState
attribute MUST return the RTCPeerConnection
object's RTCPeerConnection
signaling state.
addIceCandidate
The addIceCandidate()
method provides a remote candidate to the ICE Agent. In addition to
being added to the remote description, connectivity checks will be
sent to the new candidates as long as the ICE Transports setting is not set to
none
. This call will result in a change to the
connection state of the ICE Agent, and may result in a change to
media state if it results in different connectivity being
established.
Let p be a new promise.
If this
object's
signaling
state is RTCPeerConnection
closed
, the user agent MUST reject
p with InvalidStateError
, and
jump to the step labeled Return.
If the candidate could not be successfully applied, reject
p with a DOMError
object whose
name
attribute has the value TBD
and jump to the step
labeled Return.
TODO: define names for DOMError ( InvalidCandidate and InvalidMidIndex)
If the candidate is successfully applied, resolve p with undefined.
Return: Return p.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
candidate |
| ✘ | ✘ |
Promise<void>
close
When the RTCPeerConnection close()
method is invoked, the
user agent MUST run the following steps:
RTCPeerConnection
object's
RTCPeerConnection
signalingState
is
closed
, abort these steps.Destroy the RTCPeerConnection
ICE Agent, abruptly ending any active ICE processing and
any active streaming, and releasing any relevant resources
(e.g. TURN permissions).
Set the object's RTCPeerConnection
signalingState to closed
.
void
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 MediaStreams 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 get the ICE user name fragment and password.
An answer can be marked as provisional, as described in
[RTCWEB-JSEP], by setting the type
to
"pranswer"
.
If the RTCPeerConnection
is configured to generate
Identity assertions by calling setIdentityProvider, then the
session description SHALL contain an appropriate assertion. If the
identity provider is unable to produce an identity assertion, the
call to createAnswer
MUST be rejected with a
DOMError
that has a name of IdpError.
If this RTCPeerConnection
object is closed before
the SDP generation process completes, the USER agent MUST suppress
the result and not resolve or reject the returned promise.
If the SDP generation process completed successfully, the user
agent MUST resolve the returned promise with a
newly created
object,
representing the generated answer.RTCSessionDescription
If the SDP generation process failed for any reason, the user
agent MUST reject the returned promise with a DOMError
object of type TBD.
TODO: define type of error for SDP generation
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
options |
| ✘ | ✔ |
Promise<RTCSessionDescription
>
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 MediaStream
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 streams. 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 get the ICE user name 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 setIdentityProvider, then the
session description SHALL contain an appropriate assertion. If the
identity provider is unable to produce an identity assertion, the
call to createOffer
MUST be rejected with a
DOMError
that has a name of IdpError.
If this RTCPeerConnection
object is closed before
the SDP generation process completes, the USER agent MUST suppress
the result and not resolve or reject the returned promise.
If the SDP generation process completed successfully, the user
agent MUST resolve the returned promise with a
newly created
object,
representing the generated offer.RTCSessionDescription
If the SDP generation process failed for any other reason, the
user agent MUST reject the returned promise with an
DOMError
object of type TBD as its argument.
To Do: Discuss privacy aspects of this from a fingerprinting point of view - it's probably around as bad as access to a canvas :-)
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
options |
| ✘ | ✔ |
Promise<RTCSessionDescription
>
getConfiguration
Returns a
object
representing the current configuration of this
RTCConfiguration
object.RTCPeerConnection
When this method is call, the user agent MUST construct new
object to be returned, and
initialize it using the ICE Agent's ICE transports setting and ICE servers list.RTCConfiguration
The returned configuration MUST include
a certificates
attribute containing the candidate set
of certificates used for connecting to peers. This attribute
contains the certificates chosen by the application, or the
certificates generated by the user agent for use with this
RTCPeerConnection
instance.
RTCConfiguration
setConfiguration
The setConfiguration method updates the ICE Agent process of gathering local candidates and pinging remote candidates.
This call may result in a change to the state of the ICE Agent, and may result in a change to media state if it results in connectivity being established.
When the setConfiguration()
method is invoked, the user agent MUST set the configuration specified by the
methods argument.
To set a configuration, run the following steps:
RTCConfiguration
dictionary to be processed.Let the value of configuration's iceTransportPolicy member be the ICE Agent's ICE transports setting.
Let the value of configuration's bundlePolicy member be the User Agent's bundle policy.
Let the value of configuration's iceCandidatePoolSize member be the User Agent's prefetched ICE candidate pool size as defined in [RTCWEB-JSEP] Section 4.1.10.
Let validatedServers be an empty list.
If configuration's iceServers dictionary member is present, then run the following steps for each element:
Let server be the current list element.
If the server.urls dictionary member an empty
list, then throw an
InvalidAccessError
and abort these steps.
If server.urls is a single string, let server.urls be a list consisting of just that string.
For each url in server.urls, parse the url and
obtain scheme name. If the parsing fails or if
scheme name is not implemented by the browser,
throw a SyntaxError
and abort these steps.
If scheme name is "turn" and either of the
dictionary members server.username or
server.credential are omitted, then throw an
InvalidAccessError
and abort these steps.
Appendserver to validatedServers.
Let validatedServers be the ICE Agent's ICE servers list.
If a new list of servers replaces the ICE Agent's existing
ICE servers list, no action will taken until the
's ice gathering
state transitions to RTCPeerConnection
gathering
. If a script
wants this to happen immediately, it should do an ICE
restart.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
configuration |
| ✘ | ✘ |
void
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
To Do: specify what parts of the SDP can be changed between the createOffer and setLocalDescription
The following list describes the processing model for setting a new
.RTCSessionDescriptionInit
When the method is invoked, the user agent MUST run the following steps:
Let p be a new promise.
If this
object's
signaling
state is RTCPeerConnection
closed
, the user agent MUST reject
p with InvalidStateError
, and
jump to the step labeled Return.
If a local description contains a different set of ICE
credentials, then the ICE Agent MUST trigger an ICE restart.
When ICE restarts, the gathering state will be changed back to
"gathering", if it was not already gathering. If the RTCPeerConnection
ice connection state was "completed", it will be changed
back to "connected".
The user agent MUST start the process to apply the
argument.RTCSessionDescriptionInit
Return: Return p.
If the process to apply the
argument fails for
any reason, then user agent MUST queue a task runs the
following steps:RTCSessionDescriptionInit
Let connection be the
object on with this
method was invoked.RTCPeerConnection
If connection's signaling state
is closed
, then abort these steps.
If the reason for the failure is:
The content of the
argument is
invalid or the RTCSessionDescriptionInit
type
is
wrong for the current signaling
state of connection.
Let reason be
InvalidSessionDescriptionError
.
The
is a
valid description but cannot be applied at the media
layer.RTCSessionDescriptionInit
TODO - next few points are probably wrong. Make sure to check this in setRemote too.
This can happen, e.g., if there are insufficient resources to apply the SDP. The user agent MUST then rollback as necessary if the new description was partially applied when the failure occurred.
If rollback was not necessary or was completed
successfully, let reason be
IncompatibleSessionDescriptionError
. If
rollback was not possible, let reason be
InternalError
and set
connection's signaling
state to closed
.
Reject p with reason.
If the
argument is
applied successfully, then user agent MUST queue a task (setLocalDescription() resolve task)
that runs the following steps:RTCSessionDescriptionInit
Let connection be the
object on with this
method was invoked.RTCPeerConnection
If connection's signaling state
is closed
, then abort these steps.
If the local description was set, and the supplied description matches the state of all tracks and data channels, as defined below, clear the negotiation-needed flag.
Set the connection's description attributes by executing one of the following.
NOTE: The principles of pending and current SDP were agreed by the WG but the details the this step has not yet been fully reviewed. TODO - review this.
If
the local description was set, and the
argument has a
type of "offer", and it has a version that is later than the
currentLocalDescription, then the pendingLocalDescription will be set to
the argument and the state will transition to
have-local-offer. RTCSessionDescriptionInit
If the local description was set, and the
argument has a
type of "answer", then this completes an offer answer
negotiation and currentLocalDescription is set to the argument,
currentRemoteDescription is set to the value of pendingRemoteDescription,
then pendingRemoteDescription and pendingLocalDescription are set to null,
and the state will transitions to stable. RTCSessionDescriptionInit
If
the remote description was set, and the
argument has a
type of "offer", and it has a version that is later than the
currentRemoteDescription, then the pendingRemoteDescription will be set to
the argument and the state will transition to
have-remote-offer. RTCSessionDescriptionInit
If the remote description was set, and the
argument has a
type of "answer", then this completes an offer answer
negotiation and currentRemoteDescription is set to the argument,
currentLocalDescription is set to the value of pendingLocalDescription,
then pendingRemoteDescription and pendingLocalDescription are set to null,
and the state will transitions to stable. RTCSessionDescriptionInit
If the local description was set, and the
argument has a
type of "rollback", then this is a rollback and the
pendingLocalDescription is set to null and the state will
transition to stable. RTCSessionDescriptionInit
If the remote description was set, and the
argument has a
type of "rollback", then this is a rollback and the
pendingRemoteDescription is set to null and the state will
transition to stable. RTCSessionDescriptionInit
If the local description was set, and the
argument has a
type of "pranswer", then pendingLocalDescription will be set to the
argument and the state will transitions to
have-local-pranswer unless the state was stable,
have-local-offer, or have-remote-pranswer in which case an
InvalidStateError error will be generated. RTCSessionDescriptionInit
If the remote description was set, and the
argument has a
type of "pranswer", then pendingRemoteDescription will be set to
the argument and the state will transitions to
have-remote-pranswer unless the state was stable,
have-remote-offer, or have-local-pranswer in which case an
InvalidStateError error will be generated. RTCSessionDescriptionInit
If the local description was set,
connection's ice gathering
state is new
, and the local description
contains media, then set connection's ice gathering
state to gathering
.
If the local description was set with content that
caused an ICE restart, then set connection's
ice
gathering state to gathering
.
Set connection's signalingState accordingly.
If connection's signalingState
changed, fire a simple event named signalingstatechange
at connection.
If connection's signalingState is
now stable
, and the negotiation-needed flag is
set, fire a simple event named negotiationneeded
at connection.
Resolve p with undefined.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
description |
| ✘ | ✘ |
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 follow the processing model of setLocalDescription()
.
In addition, a remote description is processed to determine and
verify the identity of the peer.
If the
argument is
applied successfully, the user agent MUST dispatch a receiver for all new
media descriptions [RTCWEB-JSEP] before queuing the setLocalDescription() resolve task.RTCSessionDescriptionInit
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
peerIdentity
),
then this also establishes a target
peer identity.
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
IncompatibleSessionDescriptionError
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 |
| ✘ | ✘ |
Promise<void>
RTCPeerConnection
for legacy purposes.partial interface RTCPeerConnection {
void createOffer (RTCSessionDescriptionCallback
successCallback, RTCPeerConnectionErrorCallback
failureCallback, optional RTCOfferOptions
options);
void setLocalDescription (RTCSessionDescriptionInit
description, VoidFunction successCallback, RTCPeerConnectionErrorCallback
failureCallback);
void createAnswer (RTCSessionDescriptionCallback
successCallback, RTCPeerConnectionErrorCallback
failureCallback);
void setRemoteDescription (RTCSessionDescriptionInit
description, VoidFunction successCallback, RTCPeerConnectionErrorCallback
failureCallback);
void addIceCandidate (RTCIceCandidate
candidate, VoidFunction successCallback, RTCPeerConnectionErrorCallback
failureCallback);
void getStats (MediaStreamTrack
? selector, RTCStatsCallback
successCallback, RTCPeerConnectionErrorCallback
failureCallback);
};
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.
Invoke RTCPeerConnection.addIceCandiddate() 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.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
candidate |
| ✘ | ✘ | |
successCallback | VoidFunction | ✘ | ✘ | |
failureCallback |
| ✘ | ✘ |
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.
Invoke RTCPeerConnection.createAnswer() with no arguments, and let p be the resulting promise.
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.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
successCallback |
| ✘ | ✘ | |
failureCallback |
| ✘ | ✘ |
void
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.
Invoke RTCPeerConnection.createOffer() with options as the sole argument, and let p be the resulting promise.
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.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
successCallback |
| ✘ | ✘ | |
failureCallback |
| ✘ | ✘ | |
options |
| ✘ | ✔ |
void
getStats
When the getStats
method is called, the
user agent MUST run the following steps:
Let selector 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.
Invoke RTCPeerConnection.getStats() with selector as the sole argument, and let p be the resulting promise.
Upon fulfillment of p with value report, invoke successCallback with report as the argument.
Upon rejection of p with reason r, invoke failureCallback with r as the argument.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
selector |
| ✔ | ✘ | |
successCallback |
| ✘ | ✘ | |
failureCallback |
| ✘ | ✘ |
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.
Invoke RTCPeerConnection.setLocalDescription() 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.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
description |
| ✘ | ✘ | |
successCallback | VoidFunction | ✘ | ✘ | |
failureCallback |
| ✘ | ✘ |
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.
Invoke RTCPeerConnection.setLocalDescription() 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.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
description |
| ✘ | ✘ | |
successCallback | VoidFunction | ✘ | ✘ | |
failureCallback |
| ✘ | ✘ |
void
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 RTCPeerConnection
RTCPeerConnection
signalingState is closed
, 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
are considered to have a strong
reference to the RTCPeerConnection
object.RTCPeerConnection
enum RTCSignalingState {
"stable",
"have-local-offer",
"have-remote-offer",
"have-local-pranswer",
"have-remote-pranswer",
"closed"
};
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. |
closed | The connection is closed. |
The non-normative peer state transitions are:
An example set of transitions might be:
Caller transition:
stable
have-local-offer
have-remote-pranswer
stable
closed
Callee transition:
stable
have-remote-offer
have-local-pranswer
stable
closed
enum RTCIceGatheringState {
"new",
"gathering",
"complete"
};
Enumeration description | |
---|---|
new | The object was just created, and no networking has occurred yet. |
gathering | The ICE engine is in the process of gathering candidates for this RTCPeerConnection. |
complete | The ICE engine has completed gathering. Events such as adding a new interface or a new TURN server will cause the state to go back to gathering. |
enum RTCPeerConnectionState {
"new",
"connecting",
"connected",
"disconnected",
"failed"
};
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. |
enum RTCIceConnectionState {
"new",
"checking",
"connected",
"completed",
"failed",
"disconnected",
"closed"
};
Enumeration description | |
---|---|
new | The ICE Agent is gathering addresses and/or waiting for remote candidates to be supplied. |
checking | The ICE Agent has received remote candidates on at least one component, and is checking candidate pairs but has not yet found a connection. In addition to checking, it may also still be gathering. |
connected | The ICE Agent has found a usable connection for all components but is still checking other candidate pairs to see if there is a better connection. It may also still be gathering. |
completed | The ICE Agent has finished gathering and checking and found a connection for all components. Details on how the completed state in ICE is reached are covered in [ICE]. |
failed | The ICE Agent is finished checking all candidate pairs and failed to find a connection for at least one component. Connections may have been found for some components. |
disconnected | Liveness checks have failed for one or more components. This is
more aggressive than failed , and may trigger
intermittently (and resolve itself without action) on a flaky
network. |
closed | The ICE Agent has shut down and is no longer responding to STUN requests. |
States take either the value of any component or all components, as outlined below:
checking
occurs if ANY component has received a
candidate and can start checkingconnected
occurs if ALL components have established
a working connectioncompleted
occurs if ALL components have finalized
the running of their ICE processesfailed
occurs if ANY component has given up trying
to connectdisconnected
occurs if ANY component has failed
liveness checksclosed
occurs only if
RTCPeerConnection.close()
has been called.If a component is discarded as a result of signaling (e.g. RTCP mux
or BUNDLE), the state may advance directly from checking
to completed
.
Some example transitions might be:
new
new
, remote candidates received):
checking
checking
, found usable connection):
connected
checking
, gave up): failed
connected
, finished all checks):
completed
completed
, lost connectivity):
disconnected
new
closed
The non-normative ICE state transitions are:
callback RTCPeerConnectionErrorCallback = void (DOMError error);
RTCPeerConnectionErrorCallback
Parameterserror
of type DOMErrorAll 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
interface RTCSdpError : DOMError {
readonly attribute long sdpLineNumber;
};
sdpLineNumber
of type long, readonly RTCSessionDescriptionInit
at which the error was encountered.Ask the DOM team to extend their list with the following errors. The error names and their descriptions are directly copied from the old RTCErrorName enum and might need some adjustment before being added to the public list of errors.
The RTCSdpType enum describes the type of an
or
RTCSessionDescriptionInit
instance.RTCSessionDescription
enum RTCSdpType {
"offer",
"pranswer",
"answer",
"rollback"
};
Enumeration description | |
---|---|
offer |
An RTCSdpType of "offer" indicates that a description MUST be treated as an [SDP] offer. |
pranswer |
An RTCSdpType of "pranswer" indicates that a description MUST be treated as an [SDP] answer, but not a final answer. A description used as an SDP "pranswer" may be applied as a response to a SDP offer, or an update to a previously sent SDP "pranswer". |
answer |
An RTCSdpType of "answer" indicates that a description MUST be treated as an [SDP] final answer, and the offer-answer exchange MUST be considered complete. A description used as an SDP answer may be applied as a response to an SDP offer or as an update to a previously sent SDP "pranswer". |
rollback |
An RTCSdpType of "rollback" indicates that a description MUST be treated as an canceling the current SDP negotiation and moving back to the SDP [SDP] offer and answer back to what it was in the previous stable state. Note the local or remote SDP descriptions in the previous stable state could be null if there has not yet been a successful offer-answer negotiation. |
The RTCSessionDescription
class is used by
to expose local and remote session
descriptions. Attributes on this interface are mutable for legacy
reasons.RTCPeerConnection
dictionary RTCSessionDescriptionInit {
required RTCSdpType
type;
DOMString? sdp = null;
};
[ Constructor (RTCSessionDescriptionInit
descriptionInitDict)]
interface RTCSessionDescription {
attribute RTCSdpType
type;
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 |
| ✘ | ✘ |
sdp
of type DOMString, , nullablenull
value.type
of type RTCSdpType
, Instances of this interface are serialized as a map with entries for each of the serializable attributes.
RTCSessionDescriptionInit
Memberssdp
of type DOMString, , nullable, defaulting to null
type
of type RTCSdpType
, requiredcallback RTCSessionDescriptionCallback = void (RTCSessionDescription
sdp);
RTCSessionDescriptionCallback
Parameterssdp
of type RTCSessionDescription
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 negotiationneeded event.RTCPeerConnection
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 a track, or adding the first
data channel.RTCPeerConnection
Internal changes within the implementation can also result in the
connection being marked as needing negotiation. For example, if a
enters the ended state because
its source device became unavailable.
MediaStreamTrack
The negotiation-needed state is cleared when
setLocalDescription
is
called (either for an offer or answer), and the supplied description
matches the state of the tracks/datachannels that currenly exist on the
. Specifically, this means that
all live tracks have an associated section in the local description
with their MSID, all ended tracks have been removed from the local
description, and, if any data channels have been created, a data
section exists in the local description.RTCPeerConnection
Note that setLocalDescription(answer)
will clear the
negotiation-needed state only if the offer had a corresponding section for
all the tracks/datachannels on the answerer side. Otherwise, a new offer by
the answerer is still needed, and so the state is not cleared.
When the
connection
is marked as negotiation-needed, and it was not already marked as such:RTCPeerConnection
setLocalDescription
or
setRemoteDescription
processing, as described above.This describes an ICE candidate. Though not explicitly required, values for candidate and either sdpMid or sdpMLineIndex MUST be provided.
[Constructor(RTCIceCandidate copy)]
dictionary RTCIceCandidate {
required DOMString candidate;
DOMString sdpMid;
unsigned short sdpMLineIndex;
};
RTCIceCandidate
Memberscandidate
of type DOMString, requiredcandidate-attribute
as defined in
section 15.1 of [ICE].sdpMLineIndex
of type unsigned short, sdpMid
of type DOMString, The constructor on
exists
for legacy compatibility reasons only.RTCIceCandidate
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
sdpMid
and sdpMLineIndex
.
If the
is of type RTCIceCandidate
srflx
or type relay
, the url
parameter MUST be
filled in.
dictionary RTCPeerConnectionIceEventInit : EventInit {
RTCIceCandidate
candidate;
DOMString url;
};
[ Constructor (DOMString type, RTCPeerConnectionIceEventInit
eventInitDict)]
interface RTCPeerConnectionIceEvent : Event {
readonly attribute RTCIceCandidate
? candidate;
readonly attribute DOMString? url;
};
RTCPeerConnectionIceEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type | DOMString | ✘ | ✘ | |
eventInitDict |
| ✘ | ✘ |
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 sections, 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
.
RTCPeerConnectionIceEventInit
Memberscandidate
of type RTCIceCandidate
, url
of type DOMString, The icecandidateerror
event of the RTCPeerConnection uses
the
interface.RTCPeerConnectionIceErrorEvent
dictionary RTCPeerConnectionIceErrorEventInit : EventInit {
DOMString hostCandidate;
DOMString url;
DOMString status;
DOMString statusText;
};
[ 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 |
| ✘ | ✘ |
errorCode
of type unsigned short, readonly The errorCode
attribute is the numeric STUN
error code returned by the STUN or TURN server.
If the server could not be reached, errorCode
will
be set to a TBD value in the 7XX range, as this does not conflict
with the STUN error code range.
errorText
of type USVString, readonly The errorText
attribute is the STUN reason text
returned by the STUN or TURN server.
If the server could not be reached, errorText
will
be set to an implementation-specific value providing details about
the error.
hostCandidate
of type DOMString, readonly The hostCandidate
attribute is the local IP address and
port used to communicate with the STUN or TURN server.
On a multihomed system, multiple interfaces may be used to contact the server, and this attribute allows the application to figure out on which one the failure occurred.
If use of multiple interfaces has been prohibited for privacy reasons, this attribute will be set to 0.0.0.0:0 or [::]:0, as appropriate.
url
of type DOMString, readonly The url
attribute is the STUN or TURN URL that
identifies the STUN or TURN server for which the
failure occurred.
RTCPeerConnectionIceErrorEventInit
MembershostCandidate
of type DOMString, status
of type DOMString, statusText
of type DOMString, url
of type DOMString, Many applications have multiple media flows of the same
data type and often some of the flows are more important than
others. WebRTC uses the priority and Quality of Service (QoS) framework
described in [RTCWEB-TRANSPORT] and [TSVWG-RTCWEB-QOS]
to provide priority and DSCP marketing 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 RTCRtpEncodingParamters.priority
to the follwing values.
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 the priority of the things that are.
The certificates that RTCPeerConnection
instances use to
authenticate with peers use the RTCCertificate
interface. These objects can be explicitly generated by applications
using RTCPeerConnection.generateCertificate
and provided in
the RTCConfiguration
when constructing a
new RTCPeerConnection
instance.
The explicit certificate management functions provided here are
optional. If an application does not provide
the certificates
configuration option when constructing
an RTCPeerConnection
a new set of certificates MUST be
generated by the user agent. That set MUST include an ECDSA
certificate with a private key on the P-256 curve and a signature with a
SHA-256 hash.
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 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-3] 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 DOMError
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]) }
, 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
>
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 Date expires;
};
expires
of type Date, readonly The expires attribute indicates the date and time
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.
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 RTCRtpSender
s. Similarly, the reception and decoding of
MediaStreamTrack
s is managed through objects called RTCRtpReceiver
s.
Each track to be sent is associated with exactly one RTCRtpSender
, and
each track to be received is associated with exactly one RTCRtpReceiver
.
RTCRtpSender
s are created when the application attaches a
MediaStreamTrack
to a PeerConnection
, via the
addTrack
method. RTCRtpReceiver
s, on the other
hand, are created when remote signaling indicates new tracks are available,
and each new MediaStreamTrack
and its associated RTCRtpReceiver
are surfaced to the application via the ontrack
event.
A
object contains a
set of RTCPeerConnection
RTCRtpSender
s, representing tracks to
be sent, and a set of RTCRtpReceiver
s,
representing tracks that are to be received on this
object. Both of these sets are
initialized to empty sets when the
RTCPeerConnection
object is created.RTCPeerConnection
The RTP media API extends the
interface as described below.RTCPeerConnection
partial interface RTCPeerConnection {
readonly attribute RTCSctpTransport
? sctp;
sequence<RTCRtpSender
> getSenders ();
sequence<RTCRtpReceiver
> getReceivers ();
RTCRtpSender
addTrack (MediaStreamTrack
track, MediaStream... streams);
void removeTrack (RTCRtpSender
sender);
attribute EventHandler ontrack;
};
ontrack
of type EventHandler, This event handler, of event handler event type track
, MUST be fired
by all objects implementing the
interface. RTCPeerConnection
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.
addTrack
Adds a new track to the RTCPeerConnection, and indicate that it is contained in the specified MediaStreams.
When the addTrack()
method is invoked, the user agent MUST
run the following steps:
Let connection be the
object on which the
RTCPeerConnection
, track, is to be
added.MediaStreamTrack
If connection's RTCPeerConnection
signalingState is closed
, throw an
InvalidStateError
exception and abort these
steps.
If an RTCRtpSender
for track already exists in
connection's set of senders,
throw an InvalidParameter
exception and abort these
steps.
Create a new RTCRtpSender
for track, add it to
connection's set of senders,
and return it to the caller.
A track could have contents that are inaccessible to the
application. This can be due to being marked with a
peerIdentity option or anything that would make a
track
CORS cross-origin. These tracks can be supplied to the
addTrack method, and have an RTCRtpSender
created for them, but content
MUST NOT be transmitted, unless they are also marked with
peerIdentity and they meet the
requirements for sending (see
isolated 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.
Mark connection as needing negotiation.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
track |
| ✘ | ✘ | |
streams | MediaStream | ✘ | ✘ |
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 a new sequence that represents a snapshot of all
the
objects in this
RTCRtpReceiver
object's set of receivers. The conversion from
the receivers set to the sequence, to be returned, is user agent
defined and the order does not have to be stable between calls.RTCPeerConnection
sequence<RTCRtpReceiver
>
getSenders
Returns a sequence of
objects
representing the RTP senders that are currently attached to this
RTCRtpSender
object.RTCPeerConnection
The getSenders()
method MUST return a new sequence that represents a snapshot of all
the RTCRtpSenders
objects in this
object's set of senders. The conversion from the
senders set to the sequence, to be returned, is user agent defined
and the order does not have to be stable between calls.RTCPeerConnection
sequence<RTCRtpSender
>
removeTrack
Removes sender, and its associated MediaStreamTrack
, from the
.RTCPeerConnection
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 connection be the
object on which the
RTCPeerConnection
, sender, is to be
removed.RTCRtpSender
If connection's RTCPeerConnection
signalingState is closed
, throw an
InvalidStateError
exception.
If sender is not in connection's set of senders, then abort these steps.
Remove sender from connection's set of senders.
Mark connection as needing negotiation.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
sender |
| ✘ | ✘ |
void
Rejection of incoming
objects
can be done by the application, after receiving the track, by stopping
it.MediaStreamTrack
To dispatch a receiver for an incoming media description [RTCWEB-JSEP], the user agent MUST queue a task that runs the following steps:
Let connection be the
expecting this media.RTCPeerConnection
If the connection's RTCPeerConnection
signalingState is closed
, abort these
steps.
Let streams be a list of
MediaStream
objects that the sender indicated the
sent
being a part of. The
information needed to collect these objects is part of the media
description.MediaStreamTrack
Run the following steps to create a track representing the incoming media description:
Create a
object
track to represent the media description.MediaStreamTrack
Initialize track's kind
attribute to "audio
" or "video
"
depending on the media type of the media description.
Initialize track's id
attribute to the media description track id.
Initialize track's label
attribute to "remote audio
" or "remote
video
" depending on the media type of the media
media description.
Initialize track's readyState
attribute to live
.
Initialize track's muted
attribute to true
. See the MediaStreamTrack section about how
the muted
attribute reflects if a
is receiving media data
or not.MediaStreamTrack
If streams is an empty list, create a new
MediaStream
object and add it to streams.
Add track to all MediaStream
objects in streams.
Create a new
object
receiver for track, and add it
to connection's set of receivers.RTCRtpReceiver
Fire an event named
track
with
receiver, track, and streams
at the connection object.
When an
finds that a track
from the remote peer has been removed, the user agent MUST follow these
steps:RTCPeerConnection
Let connection be the
associated with the track
being removed.RTCPeerConnection
Let track be the
object that represents the track being removed, if any. If
there isn't one, then abort these steps.MediaStreamTrack
By definition, track is now ended.
A task is thus queued to update track and fire an event.
Queue a task to run the following substeps:
If the connection's RTCPeerConnection
signalingState is closed
, abort these
steps.
Remove the RTCRtpReceiver
associated with track from
connection's set of receivers.
Since the beginning of this specification, remote MediaStreamTracks have been created by the setRemoteDescription call, one track for each non-rejected m-line in the remote description. This meant that at the caller, MediaStreamTracks were not created until the answer was received, and any media received prior to a remote description (AKA "early media") would be discarded. If any form of remote description is provided (either an answer or a pranswer), this issue does not occur.
If we want to allow early media to be played out, minor changes are necessary. Fundamentally, we would need to change when tracks are created for the offerer; this would have to happen either as a result of setLocalDescription, or when media packets are received. This ensures that these objects can be created and connected to media elements for playout.
However, there are three consequences to this potential change:
For now, we simply make note of this issue, until it can be considered fully by the WG.
The RTCRtpSender
interface allows an application to control how a given
MediaStreamTrack
is encoded and transmitted to a remote RTCRtpReceiver
.
When methods are called on an RTCRtpSender
, such as RTCRtpSender.setParameters
,
the encoding is changed appropriately.
dictionary RTCRtpParameters {
sequence<RTCRtpEncodingParameters
> encodings;
sequence<RTCRtpHeaderExtensionParameters
> headerExtensions;
RTCRtcpParameters
rtcp;
sequence<RTCRtpCodecParameters
> codecs;
};
RTCRtpParameters
Memberscodecs
of type sequence<RTCRtpCodecParameters
>, An array containing codecs the codecs that
an RTCRtpSender
will choose from in
order to send media.
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.
dictionary RTCRtpEncodingParameters {
unsigned long ssrc;
RTCRtxParameters
rtx;
RTCFecParameters
fec;
boolean active;
RTCPriorityType
priority;
unsigned long maxBitrate;
RTCDegradationPreference degradationPreference = "balanced";
};
RTCRtpEncodingParameters
Membersactive
of type boolean, Indicates that this encoding is actively being sent. Setting it to false causes this encoding to no longer be sent. Setting it to true causes this encoding to be sent.
degradationPreference
of type RTCDegradationPreference, , defaulting to "balanced"
When bandwidth is constrained and
the RtpSender
must choose between
degrading resolution or degrading
framerate, degradationPreference
indicates what should be prefered.
fec
of type RTCFecParameters
, The parameters used for FEC, or unset if FEC is not being used.
maxBitrate
of type unsigned long, Indicates the maximum bitrate that can be used to send this encoding. The encoding may also be further constrained by other bandwidth limits (such as per-transport or per-session limits) below the maximum specified here.
TODO: Find or create a definition for bitrate (how much header overhead is included, for example). Should be aligned with RTCOutboundRTPStreamStats.targetBitrate in webrtc-stats.
priority
of type RTCPriorityType
, Indicates the priority of this encoding. It is specified in [RTCWEB-TRANSPORT], Section 4.
rtx
of type RTCRtxParameters
, The parameters used for RTX, or unset if RTX is not being used.
ssrc
of type unsigned long, The SSRC of the RTP source stream of this encoding (non-RTX, non-FEC RTP stream). Read-only parameter.
enum RTCQualityPreference {
"maintain-framerate",
"maintain-resolution",
"balanced"
};
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 RTCRtxParameters {
unsigned long ssrc;
};
RTCRtxParameters
Membersssrc
of type unsigned long, The SSRC of the RTP stream for RTX. Read-only parameter.
dictionary RTCFecParameters {
unsigned long ssrc;
};
RTCFecParameters
Membersssrc
of type unsigned long, The SSRC of the RTP stream for FEC. Read-only parameter.
dictionary RTCRtcpParameters {
DOMString cname;
boolean reducedSize;
};
RTCRtcpParameters
Memberscname
of type DOMString, The Canonical Name (CNAME) used by RTCP (e.g. in SDES messages). Read-only parameter.
reducedSize
of type boolean, Whether 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
Membersencrypted
of type boolean, Whether the header extension is encryted or not. Read-only parameter.
id
of type unsigned short, The value put in the RTP packet to identify the header extension. Read-only parameter.
uri
of type DOMString, The URI of the RTP header extension, as defined in [RFC5285]. Read-only parameter.
dictionary RTCRtpCodecParameters {
unsigned short payloadType;
DOMString mimeType;
unsigned long clockRate;
unsigned short channels = 1;
DOMString sdpFmtpLine;
};
RTCRtpCodecParameters
Memberschannels
of type unsigned short, , defaulting to 1
The number of channels (mono=1, stereo=2).
clockRate
of type unsigned long, The codec clock rate expressed in Hertz.
mimeType
of type DOMString, The codec MIME type. Valid types are listed in [IANA-RTP-2].
payloadType
of type unsigned short, The RTP payload type. This value can be set in the RTCRtpParameters.encodings[0].payloadType to control which codec should be used to send a given encoding.
sdpFmtpLine
of type DOMString, The a=fmtp line in the SDP corresponding to the codec, as defined by [RTCWEB-JSEP].
dictionary RTCRtpCapabilities {
sequence<RTCRtpCodecCapability
> codecs;
sequence<RTCRtpHeaderExtensionCapability
> headerExtensions;
};
RTCRtpCapabilities
Memberscodecs
of type sequence<RTCRtpCodecCapability
>, Supported codecs.
headerExtensions
of type sequence<RTCRtpHeaderExtensionCapability
>, Supported RTP header extensions.
dictionary RTCRtpCodecCapability {
DOMString mimeType;
};
RTCRtpCodecCapability
MembersmimeType
of type DOMString, The codec MIME type. Valid types are listed in [IANA-RTP-2].
dictionary RTCRtpHeaderExtensionCapability {
DOMString uri;
};
RTCRtpHeaderExtensionCapability
Membersuri
of type DOMString, The URI of the RTP header extension, as defined in [RFC5285].
interface RTCRtpSender {
readonly attribute MediaStreamTrack
track;
readonly attribute RTCDtlsTransport
transport;
readonly attribute RTCDtlsTransport
? rtcpTransport;
readonly attribute DOMString mid;
static RTCRtpCapabilities
getCapabilities (DOMString kind);
void setParameters (RTCRtpParameters
parameters);
RTCRtpParameters
getParameters ();
Promise<void> replaceTrack (MediaStreamTrack
withTrack);
};
mid
of type DOMString, readonly RTCRtpSender.mid
attribute is the value of the a=mid SDP attribute that is immutably
associated, via setLocalDescription
,
with this RTCRtpSender
object.
rtcpTransport
of type RTCDtlsTransport
, readonly , nullableThe RTCRtpSender.rtcpTransport
attribute is the transport over which RTCP is sent and
received. When BUNDLE is used,
many
objects will share
one RTCRtpSender
RTCRtpSender.rtcpTransport
and will all
send and receive RTCP over the same transport. When RTCP
mux is used, RTCRtpSender.rtcpTransport
will
be null, and both RTP and RTCP traffic will flow
over RTCRtpSender.transport
.
track
of type MediaStreamTrack
, readonly The RTCRtpSender.track
attribute is the track that is associated with this
object.RTCRtpSender
transport
of type RTCDtlsTransport
, readonly The RTCRtpSender.transport
attribute is the transport over which media from
RTCRtpSender.track
is sent in the form of RTP
packets. When BUNDLE is used,
many
objects will share
one RTCRtpSender
RTCRtpSender.transport
and will all send
RTP over the same transport. When RTCP mux is
used, RTCRtpSender.rtcpTransport
will be
null, and both RTP and RTCP traffic will flow
over RTCRtpSender.transport
.
getCapabilities
, staticThe RTCRtpSender.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.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
kind | DOMString | ✘ | ✘ |
RTCRtpCapabilities
getParameters
The RTCRtpSender.getParameters
method returns the RtpSender's current parameters for how RTCRtpSender.track
is encoded and transmitted to a remote RTCRtpReceiver
.
It may used with RTCRtpSender.setParameters
to change the parameters in the follwing way:
var params = sender.getParameters(); // ... make changes to RtpParameters params.encodings[0].active = false; sender.setParameters(params)
RTCRtpParameters
replaceTrack
Attempts to replace the track being sent with another track provided, without renegotiation.
When the
replaceTrack()
method is invoked, the user agent
MUST run the following steps:
Let p be a new promise.
Let withTrack be the argument to this method.
If withTrack's kind
attribute differs
from the kind
of this sender's
track
,
then reject p with TypeError
,
return p and abort these steps.
Run the following steps in parallel:
Determine if negotiation is needed to transmit
withTrack in place of the sender's existing track.
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 InvalidModificationError
, return
p and abort these steps.
Have the sender switch seamlessly to transmitting withTrack in place of what it is sending, without negotiating. To avoid track identifiers changing on the remote receiving end, the sender MUST retain the original track identifier and stream associations and use these in subsequent negotiations.
track
attribute to withTrack, and resolve p
with 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 |
| ✘ | ✘ |
Promise<void>
setParameters
The RTCRtpSender.setParameters
method updates how RTCRtpSender.track
is encoded and transmitted to a remote RTCRtpReceiver
.
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 getParameters()
, the User
Agent MUST throw a ReadOnlyError
exception and abort
this operation without updating the current parameters.
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 must be called again to re-apply codec preferences.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
parameters |
| ✘ | ✘ |
void
The RTCRtpReceiver
interface allows an
application to control the receipt of a
MediaStreamTrack
. When attributes on an
RTCRtpReceiver
are modified, a negotiation is
triggered to signal the changes regarding what the application
wants to receive to the other side.
interface RTCRtpReceiver {
readonly attribute MediaStreamTrack
track;
readonly attribute RTCDtlsTransport
transport;
readonly attribute RTCDtlsTransport
? rtcpTransport;
readonly attribute DOMString mid;
static RTCRtpCapabilities
getCapabilities (DOMString kind);
sequence<RTCRtpContributingSource
> getContributingSources ();
};
mid
of type DOMString, readonly RTCRtpReceiver.mid
attribute is the value of the a=mid SDP attribute that is
immutably associated, via setRemoteDescription
,
with this RTCRtpReceiver
object. In the
case where no a=mid attribute is present in the remote
description, a random value will be generated. rtcpTransport
of type RTCDtlsTransport
, readonly , nullableThe RTCRtpReceiver.rtcpTransport
attribute is the transport over which RTCP is sent and
received. When BUNDLE is used, many
objects will share one
RTCRtpReceiver
RTCRtpReceiver.rtcpTransport
and will all
send and receive RTCP over the same transport. When RTCP
mux is used, RTCRtpReceiver.rtcpTransport
will be null, and both RTP and RTCP traffic will flow over
RTCRtpReceiver.transport
.
track
of type MediaStreamTrack
, readonly The RTCRtpReceiver.track
attribute is the track that is immutably associated with this
object.RTCRtpReceiver
transport
of type RTCDtlsTransport
, readonly The RTCRtpReceiver.transport
attribute is the transport over which media for
RTCRtpReceiver.track
is received in the form
of RTP packets. When BUNDLE is used, many
objects will share one
RTCRtpReceiver
RTCRtpReceiver.transport
and will all receive
RTP over the same transport. When RTCP mux is used,
RTCRtpReceiver.rtcpTransport
will be null,
and both RTP and RTCP traffic will flow over
RTCRtpReceiver.transport
.
getCapabilities
, staticThe RTCRtpReceiver.getCapabilities
method returns the most optimist view on 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.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
kind | DOMString | ✘ | ✘ |
RTCRtpCapabilities
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;
};
audioLevel
of type byte, readonly , nullableThe audio level contained in the last RTP packet received from the 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 decibels relative to the loudest signal that they system could possibly encode.
source
of type unsigned long, readonly The CSRC or SSRC value of the contributing source.
timestamp
of type DOMHighResTimeStamp, readonly The 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.
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.
interface RTCDtlsTransport {
readonly attribute RTCIceTransport
transport;
readonly attribute RTCDtlsTransportState
state;
sequence<ArrayBuffer> getRemoteCertificates ();
attribute EventHandler onstatechange;
};
onstatechange
of type EventHandler, statechange
,
MUST be fired any time the RTCDtlsTransport
state changes.
state
of type RTCDtlsTransportState
, readonly The state
attribute MUST return the state of the transport.
transport
of type RTCIceTransport
, readonly The RTCDtlsTransport.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
getRemoteCertificates
An array containing the remote certificates in use by the remote side.
sequence<ArrayBuffer>
enum 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
interface allows an
application access to information about the ICE transport over
packets are sent and received. In particular, ICE manages
peer-to-peer connections which involve state which the
application may want to access.RTCIceTransport
interface RTCIceTransport {
readonly attribute RTCIceRole
role;
readonly attribute RTCIceComponent
component;
readonly attribute RTCIceConnectionState
state;
readonly attribute RTCIceGatheringState
gatheringState;
sequence<RTCIceCandidate
> getLocalCandidates ();
sequence<RTCIceCandidate
> getRemoteCandidates ();
RTCIceCandidatePair
? getSelectedCandidatePair ();
RTCIceParameters
? getLocalParameters ();
RTCIceParameters
? getRemoteParameters ();
attribute EventHandler onstatechange;
attribute EventHandler ongatheringstatechange;
attribute EventHandler onselectedcandidatepairchange;
};
component
of type RTCIceComponent
, readonly The component
attribute MUST return the ICE component of the transport.
gatheringState
of type RTCIceGatheringState
, readonly The gathering
state
attribute MUST return the gathering
state of the transport.
ongatheringstatechange
of type EventHandler, gatheringstatechange
,
MUST be fired any time the
RTCIceTransport
gathering
state changes.
onselectedcandidatepairchange
of type EventHandler, selectedcandidatepairchange
,
MUST be fired any time
the RTCIceTransport
's selected
candidate pair changes.
onstatechange
of type EventHandler, statechange
,
MUST be fired any time the RTCIceTransport
state changes.
role
of type RTCIceRole
, readonly The role
attribute
MUST return the ICE role of the transport.
state
of type RTCIceConnectionState
, readonly The state
attribute MUST return the state of the transport.
getLocalCandidates
An array containing the local ICE candiates gathered
for this
and sent in
RTCIceTransport
onicecandidate
sequence<RTCIceCandidate
>
getLocalParameters
Returns the local ICE parameters received by
this
via RTCIceTransport
setLocalDescription()
,
or null
if the parameters have not yet been
received.
RTCIceParameters
, nullablegetRemoteCandidates
An array containing the remote ICE candiates received by
this
via RTCIceTransport
addIceCandidate()
sequence<RTCIceCandidate
>
getRemoteParameters
Returns the remote ICE parameters received by
this
via RTCIceTransport
setRemoteDescription()
null
if the parameters have not yet been
received.
RTCIceParameters
, nullablegetSelectedCandidatePair
Returns the selected candidate pair on which packets are sent, or NULL if there is no such pair.
RTCIceCandidatePair
, nullabledictionary 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.
enum RTCIceRole {
"controlling",
"controlled"
};
Enumeration description | |
---|---|
controlling | A controlling agent as defined by [RFC7065], Section 3. |
controlled | A controlled agent as defined by [RFC7065], Section 3. |
enum RTCIceComponent {
"RTP",
"RTCP"
};
Enumeration description | |
---|---|
RTP | Defined by [ICE], Section 4.1.1.1 as "1". |
RTCP | Defined by [ICE], Section 4.1.1.1 as "2". |
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;
};
maxMessageSize
of type unsigned long, readonly The maximum size of data that can be passed
to
's RTCDataChannel
send()
method.
transport
of type RTCDtlsTransport
, readonly The transport over which all SCTP packets for data channels will be sent and received.
The track
event uses the
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
receiver
attribute
set to receiver,
track
attribute
set to track,
streams
attribute
set to streams, MUST be created and dispatched at the
given target.
dictionary RTCTrackEventInit : EventInit {
RTCRtpReceiver
receiver;
MediaStreamTrack
track;
MediaStream[] streams;
};
[ Constructor (DOMString type, RTCTrackEventInit
eventInitDict)]
interface RTCTrackEvent : Event {
readonly attribute RTCRtpReceiver
receiver;
readonly attribute MediaStreamTrack
track;
readonly attribute MediaStream[] streams;
};
RTCTrackEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type | DOMString | ✘ | ✘ | |
eventInitDict |
| ✘ | ✘ |
receiver
of type RTCRtpReceiver
, readonly The receiver
attribute
represents the
object associated with
the event.RTCRtpReceiver
streams
of type array of MediaStream, readonly The streams
attribute returns an array of MediaStream
objects
representing the MediaStream
s that this event's
track
is a part of.
track
of type MediaStreamTrack
, readonly The RTCTrackEvent.track
attribute
represents the
object that is
associated with the MediaStreamTrack
identified by
RTCRtpReceiver
receiver
.
RTCTrackEventInit
Membersreceiver
of type RTCRtpReceiver
, TODO
streams
of type array of MediaStream, TODO
track
of type MediaStreamTrack
, TODO
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 {
RTCDataChannel
createDataChannel ([TreatNullAs=EmptyString] DOMString label, optional RTCDataChannelInit
dataChannelDict);
attribute EventHandler ondatachannel;
};
ondatachannel
of type EventHandler, datachannel
, MUST be supported by all
objects implementing the RTCPeerConnection
interface.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.
If the
object's
RTCPeerConnection
RTCPeerConnection
signalingState is closed
, throw an
InvalidStateError
exception and abort these
steps.
Let channel be a newly created
object.RTCDataChannel
Initialize channel's label
attribute to the value
of the first argument.
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).
If both the maxPacketLifeTime
and maxRetransmits
attributes are set (not null), then throw a
SyntaxError
exception and abort these steps.
If an attribute, either maxPacketLifeTime
or maxRetransmits
, has
been set to indicate unreliable mode, and that value exceeds the
maximum value supported by the user agent, the value MUST be set
to the user agents maximum value.
If id
attribute
is uninitialized (not set via the dictionary), initialize it to a
value generated by the user agent, according to the WebRTC
DataChannel Protocol specification, and skip to the next step.
Otherwise, if the value of the id
attribute is taken by an
existing
, throw a
RTCDataChannel
ResourceInUse
exception and abort these steps.
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 RTCDataChannel created on this connection, mark the connection as needing negotiation.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
label | DOMString | ✘ | ✘ | |
dataChannelDict |
| ✘ | ✔ |
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
id
. This will
connect the two separately created
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
ids
.
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
maxRetransmits
) or
set a time during which transmissions (including retransmissions) are
allowed ( maxPacketLifeTime
). These properties can not be used simultaneously and an attempt to do
so will result in an error. Not setting any of these properties results
in a reliable channel.
A
, created with RTCDataChannel
createDataChannel()
or
dispatched via a
, 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
RTCPeerConnection
RTCPeerConnection
signalingState is closed
, abort these steps.
Let channel be the
object to be announced.RTCDataChannel
Set channel's readyState
attribute to
open
.
Fire a simple event named open
at channel.
When an underlying data transport is to be announced (the other
peer created a channel with negotiated
unset or set
to false), the user agent of the peer that did not initiate the creation
process MUST queue a task to run the following steps:
If the associated
object's
RTCPeerConnection
RTCPeerConnection
signalingState is closed
, 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
,
negotiated
and
id
attributes to their
corresponding values in configuration.
Set channel's readyState
attribute to
connecting
.
Fire a datachannel event named datachannel
with channel
at the
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
close()
method,
queue a task that sets the object's readyState
attribute to
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 readyState
attribute to
closed
.
If the transport was closed with an error, fire an NetworkError event at channel.
Fire a simple event named close
at
channel.
dictionary RTCDataChannelInit {
boolean ordered = true;
unsigned short maxPacketLifeTime;
unsigned short maxRetransmits;
DOMString protocol = "";
boolean negotiated = false;
unsigned short id;
};
interface RTCDataChannel : EventTarget {
readonly attribute DOMString label;
readonly attribute boolean ordered;
readonly attribute unsigned short? maxPacketLifeTime;
readonly attribute unsigned short? maxRetransmits;
readonly attribute DOMString protocol;
readonly attribute boolean negotiated;
readonly attribute unsigned short id;
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 (DOMString data);
void send (Blob data);
void send (ArrayBuffer data);
void send (ArrayBufferView data);
};
binaryType
of type DOMString, The 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
binaryType
attribute MUST be initialized to the string "blob
".
This attribute controls how binary data is exposed to scripts. See the [WEBSOCKETS-API] for more information.
bufferedAmount
of type unsigned long, readonly The bufferedAmount
attribute MUST return the number of bytes of application data (UTF-8
text and binary data) that have been queued using send()
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).
bufferedAmountLowThreshold
of type unsigned long, The
bufferedAmountLowThreshold
attribute sets the
threshold at which the bufferedAmount
is
considered to be low. When the bufferedAmount
decreases from above this threshold to equal or below it, the
bufferedamountlow
event fires. The
bufferedAmountLowThreshold
is
initially zero on each new
, but
the application may change its value at any time.RTCDataChannel
id
of type unsigned short, readonly The RTCDataChannel.id
attribute
returns the id for this
. The id
was either assigned by the user agent at channel creation time or
selected by the script. The attribute MUST return the value to which
it was set when the RTCDataChannel
was
created.RTCDataChannel
label
of type DOMString, readonly The RTCDataChannel.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
maxPacketLifeTime
of type unsigned short, readonly , nullableThe RTCDataChannel.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 RTCDataChannel.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
negotiated
of type boolean, readonly The RTCDataChannel.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
onbufferedamountlow
of type EventHandler, bufferedamountlow
,
MUST be supported by all objects implementing the
RTCDataChannel
interface.onclose
of type EventHandler, close
, MUST be supported by all
objects implementing the RTCDataChannel
interface.onerror
of type EventHandler, error
, MUST be supported by all
objects implementing the RTCDataChannel
interface.onmessage
of type EventHandler, message
, MUST be supported by
all objects implementing the RTCDataChannel
interface.onopen
of type EventHandler, open
, MUST be supported by all
objects implementing the RTCDataChannel
interface.ordered
of type boolean, readonly The RTCDataChannel.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
protocol
of type DOMString, readonly The RTCDataChannel.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
readyState
of type RTCDataChannelState
, readonly The RTCDataChannel.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).
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 RTCDataChannel
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 readyState
is
closing
or closed
, then abort these
steps.
Set channel's readyState
attribute to
closing
.
If the closing procedure
has not started yet, start it.
void
send
Run the steps described by the send()
algorithm with argument
type string
object.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | DOMString | ✘ | ✘ |
void
send
Run the steps described by the send()
algorithm with argument
type Blob
object.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | Blob | ✘ | ✘ |
void
send
Run the steps described by the send()
algorithm with argument
type ArrayBuffer
object.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | ArrayBuffer | ✘ | ✘ |
void
send
Run the steps described by the send()
algorithm with argument
type ArrayBufferView
object.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | ArrayBufferView | ✘ | ✘ |
void
RTCDataChannelInit
Membersid
of type unsigned short, Overrides the default selection of id for this channel.
maxPacketLifeTime
of type unsigned short, Limits the time during which the channel will transmit or retransmit data if not acknowledged. This value may be clamped if it exceeds the maximum value supported by the user agent.
maxRetransmits
of type unsigned short, Limits the number of times a channel will retransmit data if not successfully delivered. This value may be clamped if it exceeds the maximum value supported by the user agent..
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
id
at the other
peer.
ordered
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.
protocol
of type DOMString, , defaulting to ""
Subprotocol name used for this channel.
The send()
method is
overloaded to handle different data argument types. When any version of
the method is called, the user agent MUST run the following steps:
Let channel be the
object on which data is to be sent.RTCDataChannel
If channel's readyState
attribute
is connecting
, throw an InvalidStateError
exception and abort these steps.
Execute the sub step that corresponds to the type of the methods argument:
string
object:
Let data be the result of converting the argument
object to a sequence of Unicode characters and increase the
bufferedAmount
attribute by the number of bytes needed to express
data as UTF-8.
Blob
object:
Let data be the raw data represented by the
Blob
object and increase the bufferedAmount
attribute by the size of data, in bytes.
ArrayBuffer
object:
Let data be the data stored in the buffer described
by the ArrayBuffer
object and increase the
bufferedAmount
attribute by the length of the 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
bufferedAmount
attribute by the length of the 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"
};
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 datachannel
event
uses the
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
channel
attribute set to
channel, MUST be created and dispatched at the given
target.
dictionary RTCDataChannelEventInit : EventInit {
RTCDataChannel
channel;
};
[ Constructor (DOMString type, RTCDataChannelEventInit
eventInitDict)]
interface RTCDataChannelEvent : Event {
readonly attribute RTCDataChannel
channel;
};
RTCDataChannelEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type | DOMString | ✘ | ✘ | |
eventInitDict |
| ✘ | ✘ |
channel
of type RTCDataChannel
, readonly The channel
attribute
represents the
object associated
with the event.RTCDataChannel
RTCDataChannelEventInit
Memberschannel
of type RTCDataChannel
, TODO
A
object MUST not be garbage
collected if itsRTCDataChannel
readyState
is connecting
and at least one event listener is
registered for open
events, message
events,
error
events, or close
events.
readyState
is open
and at least one event listener is registered
for message
events, error
events, or
close
events.
readyState
is 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 RTCPeerConnection {
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.
[NoInterfaceObject]
interface RTCDTMFSender {
void insertDTMF (DOMString tones, optional long duration = 100, optional long interToneGap = 70);
attribute EventHandler ontonechange;
readonly attribute DOMString toneBuffer;
readonly attribute long duration;
readonly attribute long interToneGap;
};
duration
of type long, readonly The duration
attribute
MUST return the current tone duration value. This value will be the
value last set via the
method, or
the default value of 100 ms if insertDTMF()
was
called without specifying the duration.insertDTMF()
interToneGap
of type long, readonly The interToneGap
attribute MUST return the current value of the between-tone gap. This
value will be the value last set via the
method, or the default value of 70
ms if insertDTMF()
was called without specifying
the interToneGap.insertDTMF()
ontonechange
of type EventHandler, This event handler uses the
interface to return the
character for each tone as it is played out. See
RTCDTMFToneChangeEvent
for details.RTCDTMFToneChangeEvent
toneBuffer
of type DOMString, readonly The toneBuffer
attribute MUST return a list of the tones remaining to be played out.
For the syntax, content, and interpretation of this list, see
insertDTMF
.
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 are equivalent to A to D. The character ',' indicates a delay of 2 seconds before processing the next character in the tones parameter. All 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. It MUST be 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.
How are invalid values handled?
When the
method is invoked, the
user agent MUST run the following steps:insertDTMF()
toneBuffer
attribute to
the value of the first argument, the duration
attribute to the
value of the second argument, and the interToneGap
attribute
to the value of the third argument.toneBuffer
contains any
unrecognized characters, throw an
InvalidCharacterError
exception and abort these steps.
toneBuffer
is an empty
string, return.duration
attribute is less
than 40, set it to 40. If, on the other hand, the value is greater
than 6000, set it to 6000.interToneGap
attribute
is less than 30, set it to 30.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 insertDTMF()
with an empty
tones parameter can be used to cancel all tones queued to play after
the currently playing tone.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
tones | DOMString | ✘ | ✘ | |
duration | long = 100 | ✘ | ✔ | |
interToneGap | long = 70 | ✘ | ✔ |
void
The tonechange
event uses the
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
tone
attribute set to
tone, MUST be created and dispatched at the given target.
dictionary RTCDTMFToneChangeEventInit : EventInit {
DOMString tone;
};
[ Constructor (DOMString type, RTCDTMFToneChangeEventInit
eventInitDict)]
interface RTCDTMFToneChangeEvent : Event {
readonly attribute DOMString tone;
};
RTCDTMFToneChangeEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type | DOMString | ✘ | ✘ | |
eventInitDict |
| ✘ | ✘ |
tone
of type DOMString, readonly The tone
attribute contains the character for the tone that has just begun
playout (see
). If the value is the
empty string, it indicates that the previous tone has completed
playback.insertDTMF()
RTCDTMFToneChangeEventInit
Memberstone
of type DOMString, TODO
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 member of a
MediaStream
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 it
believes is relevant to the selector.
The statistics returned are designed in such a way that repeated
queries can be linked by the
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.RTCStats
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 methods first argument.
If selectorArg is neither null
nor a
valid selector,
return a promise rejected with a TypeError
.
Let p be a new promise.
Run the following steps in parallel:
Start gathering the stats indicated by selectorArg.
If selectorArg is null, stats MUST be gathered
for the whole
object.RTCPeerConnection
When the relevant stats have been gathered, resolve
p with a new
object, representing the gathered stats.RTCStatsReport
Return p.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
selector |
| ✔ | ✔ |
Promise<RTCStatsReport
>
callback RTCStatsCallback = void (RTCStatsReport
report);
RTCStatsCallback
Parametersreport
of type RTCStatsReport
A
representing the gathered
stats.RTCStatsReport
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 (RTCStats.id), and their corresponding
RTCStatsReport
-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 a RTCStats
MediaStreamTrack
is carried
by multiple SSRCs 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] 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 timestamp and type. Specific stats are added by extending the
RTCStats
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 {
DOMHiResTimeStamp timestamp;
RTCStatsType
type;
DOMString id;
};
RTCStats
Membersid
of type DOMString, A 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
timestamp
of type DOMHiResTimeStamp, The timestamp
,
of type DOMHiResTimeStamp
[HIGHRES-TIME],
associated with this object. The time is relative to the UNIX epoch
(Jan 1, 1970, UTC).
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
enum RTCStatsType {
"inbound-rtp",
"outbound-rtp"
};
Enumeration description | |
---|---|
inbound-rtp | Inbound RTP. |
outbound-rtp | Outbund RTP. |
dictionary RTCRTPStreamStats : RTCStats
{
DOMString ssrc;
DOMString remoteId;
};
RTCRTPStreamStats
MembersremoteId
of type DOMString, The remoteId
can be used to look up the corresponding
object that represents stats reported by
the other peer.RTCStats
ssrc
of type DOMString, ...
dictionary RTCInboundRTPStreamStats : RTCRTPStreamStats
{
unsigned long packetsReceived;
unsigned long bytesReceived;
};
RTCInboundRTPStreamStats
MembersbytesReceived
of type unsigned long, ...
packetsReceived
of type unsigned long, ...
dictionary RTCOutboundRTPStreamStats : RTCRTPStreamStats
{
unsigned long packetsSent;
unsigned long bytesSent;
};
RTCOutboundRTPStreamStats
MembersbytesSent
of type unsigned long, ...
packetsSent
of type unsigned long, ...
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
WorkerGlobalScope
[WEBWORKERS].
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
A global property can only be set by the user agent or the IdP proxy itself. Therefore, the IdP proxy can be assured that requests it receives originate from the user agent. This ensures that an arbitrary origin is unable to instantiate an IdP proxy and impersonate this API in order obtain identity assertions.
interface RTCIdentityProviderGlobalScope : WorkerGlobalScope {
readonly attribute RTCIdentityProviderRegistrar
rtcIdentityProvider;
};
rtcIdentityProvider
of type RTCIdentityProviderRegistrar
, readonly RTCIdentityProvider
instance with the browser.
An IdP proxy implements the
callback interface, which is 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
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.RTCIdentityProviderRegistrar
interface RTCIdentityProviderRegistrar {
void register (RTCIdentityProvider
idp);
};
register
This method is invoked by the IdP when its script is first
executed. This registers an instance of
with the user agent.RTCIdentityProvider
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
idp |
| ✘ | ✘ |
void
The RTCIdentityProvider
interface is exposed by identity
providers and is called by RTCPeerConnection
to acquire or
validate identity assertions.
callback interface RTCIdentityProvider {
Promise<RTCIdentityAssertionResult
> generateAssertion (DOMString contents, DOMString origin, optional DOMString usernameHint);
Promise<RTCIdentityValidationResult
> validateAssertion (DOMString assertion, DOMString origin);
};
generateAssertion
A user agent invokes this method on the IdP to request the generation of an identity assertion.
The contents parameter includes the information that the user agent wants covered by the identity assertion. A successful validation of the provided assertion MUST produce this string.
The origin parameter identifies the origin of the
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
RTCPeerConnection
and therefore can be trusted to
be correct.
The IdP selects the identity to assert. The optional
usernameHint parameter is the same value that was passed to
setIdentityProvider
.
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
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
contents | DOMString | ✘ | ✘ | |
origin | DOMString | ✘ | ✘ | |
usernameHint | DOMString | ✘ | ✔ |
Promise<RTCIdentityAssertionResult
>
validateAssertion
A user agent invokes this method on the IdP to request the validation of an identity assertion.
The assertion parameter includes the assertion that was
recovered from an a=identity
in the session description;
that is, the value that was part of the
provided by the IdP
that generated the assertion.RTCIdentityAssertionResult
The origin parameter identifies the origin of the
that triggered this request. An
IdP can use this information as input to policy decisions about
use.RTCPeerConnection
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
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
assertion | DOMString | ✘ | ✘ | |
origin | DOMString | ✘ | ✘ |
Promise<RTCIdentityValidationResult
>
dictionary RTCIdentityAssertionResult {
required RTCIdentityProviderDetails
idp;
required DOMString assertion;
};
RTCIdentityAssertionResult
Membersassertion
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.
idp
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
.
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
Memberscontents
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.
identity
of type DOMString, requiredThe validated identity of the peer.
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 generateAssertion
method on the
instance
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 returns a Promise to the RTCPeerConnection
.
If the user has been authenticated by the IdP, and the IdP is willing
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.
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.
This process can fail. The IdP proxy MAY reject the promise, or the process of loading and registering the IdP could fail. If assertion generation fails, then the promise for the corresponding function call is rejected.
The browser SHOULD limit the time that it will allow for this process. This includes both the loading of the IdP proxy and the identity assertion generation. Failure to do so potentially causes the corresponding operation to take an indefinite amount of time. This timer can be cancelled when the IdP produces a response. The timer running to completion can be treated as equivalent to an error from the IdP.
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 generateAssertion
will cause the error to propagate to the application. Login errors are
indicated by rejecting the promise with an object that has a
name
attribute set to "IdpLoginError".
If the rejection object also contains a loginUrl
attribute, this value will be passed to the application in
the idpLoginUrl
attribute. This URL might link to page
where a user can enter their (IdP) username and password, or otherwise
provide any information the IdP needs to authorize a assertion
request.
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 setRemoteDescription
is invoked on
. 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 validateAssertion
method on the
instance
registered by the IdP.RTCIdentityProvider
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.
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 contents and
validates that it contains a fingerprint value for every
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.
If a peer offers a certificate that doesn't match
an a=fingerprint
line in the negotiated session
description, the user agent MUST NOT permit communication with
that peer.
The RTCPeerConnection
validates that the domain
portion of the identity matches the domain of the IdP as described in
[RTCWEB-SECURITY-ARCH].
The RTCPeerConnection
resolves the peerIdentity
attribute with a new instance of RTCIdentityAssertion
that includes the IdP domain and peer identity.
The browser MAY display identity information to a user in browser UI. Any user identity information that is displayed in this fashion MUST use a mechanism that cannot be spoofed by content.
This process can fail at any step above. If identity validation fails,
the peerIdentity
promise is
rejected with a DOMError
that has a name of
IdpError
.
If identity validation fails and there is
a target peer identity for the
RTCPeerConnection
, the promise returned by
setRemoteDescription
MUST be rejected.
If identity validation fails and there is no a target peer identity, the value of the
peerIdentity
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.
The browser SHOULD limit the time that it will allow for identity validation. This includes both the loading of the IdP proxy and the identity assertion validation. Failure to do so potentially causes the operation to take an indefinite amount of time. This timer can be cancelled when the IdP produces a response. The timer running to completion is treated as equivalent to an error from the IdP.
The Identity API extends the
interface as described below.RTCPeerConnection
partial interface RTCPeerConnection {
void setIdentityProvider (DOMString provider, optional DOMString protocol, optional DOMString usernameHint);
Promise<DOMString> getIdentityAssertion ();
readonly attribute Promise<RTCIdentityAssertion
> peerIdentity;
readonly attribute DOMString? idpLoginUrl;
};
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.
peerIdentity
of type Promise<RTCIdentityAssertion
>, readonly A 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 there a target peer identity has been established. If this promise successfully resolves, the value will not change.
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 setIdentityProvider()
method was called,
then an identity will be automatically requested when an offer or
answer is created.
When getIdentityAssertion
is invoked, queue a task to
run the following steps:
If the connection's RTCPeerConnection
signalingState is closed
, abort these steps.
Request an identity assertion from the IdP.
Resolve the promise with the base64 and JSON encoded assertion.
Promise<DOMString>
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 connection's RTCPeerConnection
signalingState is closed
, throw an
InvalidStateError
exception and abort these
steps.
Set the current identity provider values to the triplet
(provider
, protocol
,
usernameHint
).
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 | ✘ | ✘ | |
protocol | DOMString | ✘ | ✔ | |
usernameHint | DOMString | ✘ | ✔ |
void
[Constructor(DOMString idp, DOMString name)]
interface RTCIdentityAssertion {
attribute DOMString idp;
attribute DOMString name;
};
idp
of type DOMString, The domain name of the identity provider that validated this identity.
name
of type DOMString, An 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 and protocol.
pc.setIdentityProvider("example.com", "default", "alice@example.com");
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 stream 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 RTCPeerConnection
API.
When a MediaStream
is
created to represent a stream obtained from a remote peer, the
id
attribute is initialized from information provided by the remote
source.
The id of a MediaStream
object is
unique to the source of the stream, but that does not mean it is not
possible to end up with duplicates. For example, 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 new media track may be associated with an existing
MediaStream
. For example, if a remote peer adds a
new
object to a
MediaStreamTrack
, and indicates that the
RTCPeerConnection
is a member of a MediaStreamTrack
MediaStream
that has already been created locally
by the
, this is observed on the local
user agent. If this happens for the reason exemplified, or for any
other reason than the RTCPeerConnection
addTrack()
method being invoked locally on a MediaStream
or
tracks being added as the stream is created (i.e. the stream is
initialized with tracks),
the user agent MUST run the following steps:
Let stream be the target
MediaStream
object.
Let track be the
object representing the media component about to be added.MediaStreamTrack
Add track to stream's track set.
Fire a track event named addtrack
with the newly created
object
at stream.MediaStreamTrack
An existing media track may also be disassociated from a
MediaStream
. If this happens for any other reason
than the removeTrack()
method being invoked locally on a MediaStream
or
the stream being destroyed, the user agent MUST run the following
steps:
Let stream be the target
MediaStream
object.
Let track be the
object representing the media component about to be removed.MediaStreamTrack
Remove track from stream's track set.
Fire a track event named removetrack
with track at stream.
The event source for the onended
event in the networked
case is the
object.RTCPeerConnection
A MediaStreamTrack
object's reference to its
MediaStream
in the non-local media source case (an RTP
source, as is the case for a MediaStream
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 an
's RTP source is
temporarily unable to receive media due to a loss of connection or if a
mute signal has been received, it MUST update the muted state of the corresponding
RTCPeerConnection
with the value MediaStreamTrack
true
.
When media data is available again, the muted state MUST be updated with the value
false
.
The mute signal mentioned in the previous paragraph is yet to be defined.
The procedure update a track's muted state is specified in [GETUSERMEDIA].
When a track comes
from a remote peer and the remote peer has permanently stopped sending
data the ended
event MUST be fired on the track, as
specified in [GETUSERMEDIA].
How do you know when it has stopped? This seems like an SDP question, not a media-level question. (Suggestion: when the track is ended, either through port 0, or removing the a=msid attrib)
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;
};
MediaStreamConstraints
MemberspeerIdentity
of type DOMString, If 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, readonly A 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 EventHandler, This 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) { if (evt.candidate) 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 }, function (stream) { selfView.srcObject = stream; if (stream.getAudioTracks().length > 0) pc.addTrack(stream.getAudioTracks()[0], stream); if (stream.getVideoTracks().length > 0) pc.addTrack(stream.getVideoTracks()[0], stream); }, 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 () { signalingChannel.send(JSON.stringify({ "desc": pc.localDescription })); }) .catch(logError); } else pc.setRemoteDescription(desc).catch(logError); } else pc.addIceCandidate(message.candidate).catch(logError); }; function logError(error) { log(error.name + ": " + error.message); }
This example shows the more complete functionality.
TODO
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) { if (evt.candidate) 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 () { signalingChannel.send(JSON.stringify({ "desc": pc.localDescription })); }) .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.isertDTMF("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 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 bufferedAmount
decreases from above its
bufferedAmountLowThreshold to less
than or equal to its
bufferedAmountLowThreshold .
|
error |
Event |
Issue TODO |
close |
Event |
The object's underlying data
transport has bee closed.
|
The following events fire on
objects:RTCPeerConnection
Event name | Interface | Fired when... |
---|---|---|
connecting |
Event |
Issue TODO |
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 RTCPeerConnection
signalingState has changed. This state change is the result of
either setLocalDescription()
or setRemoteDescription()
being invoked.
|
iceconnectionstatechange |
Event |
The RTCPeerConnection
ice connection state has changed.
|
icegatheringstatechange |
Event |
The RTCPeerConnection
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. |
The following events fire on
objects:RTCDTMFSender
Event name | Interface | Fired when... |
---|---|---|
tonechange |
Event |
The object has either just
begun playout of a tone (returned as the
attribute) or just ended playout of a tone (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.
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.
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
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.
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
RTCIceTransportPolicy
, 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.
Mitigating the exposure of IP addresses to the application 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 working group is actively discussing what additional text regarding exposure of IP addresses is appropriate for this section.
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.
This section will be removed before publication.
The editors wish to thank the Working Group chairs and Team Contact, Harald Alvestrand, Stefan Håkansson and Dominique Hazaël-Massieux, for their support. Substantial text in this specification was provided by many people including Martin Thomson, Harald Alvestrand, Justin Uberti, Eric Rescorla, Peter Thatcher, Jan-Ivar Bruaroey and Peter Saint-Andre.
The RTCRtpSender and RTCRtpReceiver objects were initially described in the W3C ORTC CG, and have been adapted for use in this specification.