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 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:
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]].
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and terminology.
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 RTCPeerConnection
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
XMLHttpRequest
[[XMLHttpRequest]].
An array containing URIs of servers available to be used by ICE, such as STUN and TURN server.
Indicates which candidates the ICE engine is allowed to use.
Indicates which BundlePolicy to use.
Sets the target peer identity for the RTCPeerConnection. The RTCPeerConnection will establish a connection to a remote peer unless it can be successfully authenticated with the provided name.
STUN or TURN URI(s) as defined in [[!RFC7064]] and [[!RFC7065]] or other URI types.
If this RTCIceServer
object represents a
TURN server, then this attribute specifies the username to use with
that TURN server.
If this RTCIceServer
object represents a
TURN server, then this attribute specifies the credential to use
with that TURN server.
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":
"turn:turn.example.org", "username": "user", "credential": "myPassword"
} ]
These dictionaries describe the options that can be used to control the offer/answer creation process.
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.
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.
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.
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
localDescription
attribute's SDP). Applying the
generated description will restart ICE.
When the value of this dictionary member is false, and the
localDescription
attribute has valid ICE
credentials, the generated description will have the same ICE
credentials as the current value from the
localDescription
attribute.
setIdentityProvider()
call has been made in
JavaScript. As this is the default value, an identity will be
requested if and only if the user has configured an IdP in some
way.The general operation of the RTCPeerConnection is described in [[!RTCWEB-JSEP]].
Calling new RTCPeerConnection(configuration
)
creates an RTCPeerConnection
object.
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 RTCPeerConnection
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.
When the RTCPeerConnection()
constructor
is invoked, the user agent MUST run the following steps:
Validate the RTCConfiguration
argument by
running the steps defined by the updateIce() method.
Let connection be a newly created
RTCPeerConnection
object.
Create an ICE Agent as defined in [[!ICE]] and let
connection's RTCPeerConnection
ICE Agent be
that ICE Agent and provide it the the ICE servers list. 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
.
Initialize an internal variable to represent a queue of
operations
with an empty set.
Return connection.
Once the RTCPeerConnection object has been initialized, for every
call to createOffer
, setLocalDescription
,
createAnswer
and setRemoteDescription
;
execute the following steps:
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 function from the front of the queue
asynchronously.
When the asynchronous operation completes (either successfully
or with an error), remove the corresponding object from the
operations
array. After removal, if the array is
non-empty, execute the first object queued asynchronously and
repeat this step on completion.
The general idea is to have only one among createOffer
,
setLocalDescription
, createAnswer
and
setRemoteDescription
executing at any given time. If
subsequent calls are made while one of them is still executing, they
are added to a queue and processed when the previous operation is fully
completed. It is valid, and expected, for normal error handling
procedures to be applied.
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
RTCPeerConnection
object associated with this
ICE Agent.
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
localDescription
and create a
RTCIceCandidate
object to represent the
candidate. Let newCandidate be that object.
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 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.
If the RTCPeerConnection
is configured to generate
Identity assertions, then the session description SHALL contain an
appropriate assertion.
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 RTCSessionDescription
object,
representing the generated offer.
If the SDP generation process failed for any 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 :-)
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, then the session description SHALL contain an
appropriate assertion.
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 RTCSessionDescription
object,
representing the generated answer.
If the SDP generation process failed for any reason, the user
agent MUST reject the returned promise with a DOMError
object of type TBD.
The setLocalDescription()
method instructs the RTCPeerConnection
to apply
the supplied RTCSessionDescription
as the local
description.
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
RTCPeerConnection
must be able to
simultaneously support use of both the old and new 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 new local
description, or rollback to the old description if the remote side
denied the change.
ISSUE: how to indicate to rollback?
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
RTCSessionDescription
.
When the method is invoked, the user agent MUST run the following steps:
Let p be a new promise.
If this RTCPeerConnection
object's
signaling
state is 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
RTCSessionDescription
argument.
Return: Return p.
If the process to apply the
RTCSessionDescription
argument fails for
any reason, then user agent must queue a task runs the
following steps:
Let connection be the
RTCPeerConnection
object on with this
method was invoked.
If connection's signaling state
is closed
, then abort these steps.
If the reason for the failure is:
The content of the
RTCSessionDescription
argument is
invalid or the type
is
wrong for the current signaling
state of connection.
Let reason be
InvalidSessionDescriptionError
.
The RTCSessionDescription
is a
valid description but cannot be applied at the media
layer.
TODO ISSUE - 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 RTCSessionDescription
argument is
applied successfully, then user agent must queue a task runs
the following steps:
Let connection be the
RTCPeerConnection
object on with this
method was invoked.
If connection's signaling state
is closed
, then abort these steps.
Set connection's description attribute (
localDescription
or
remoteDescription
depending on the
setting operation) to the
RTCSessionDescription
argument.
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.
Resolve p with undefined.
The localDescription
attribute MUST return the last RTCSessionDescription
that was successfully set using setLocalDescription()
,
plus any local candidates that have been generated by the ICE
Agent since then.
A null object will be returned if the local description has not yet been set.
The setRemoteDescription()
method instructs the RTCPeerConnection
to apply
the supplied RTCSessionDescription
as the
remote offer or answer. This API changes the local media state.
When the method is invoked, the user agent must follow the
processing model of
setLocalDescription()
,
with the following additional conditions:
If an a=identity
attribute is present in the
session description, the browser validates the identity
assertion.. Identity validation completes asynchronously
and does not block the completion of
setRemoteDescription
, unless there is 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
InvalidStateError
and abort this
operation.
If the "peerIdentity" configuration is applied to the
RTCPeerConnection
, this establishes a
target peer identity.
Alternatively, if the RTCPeerConnection
has
previously authenticated the identity of the peer (that is,
there is a current value for peerIdentity
), then this also establishes a target peer identity.
If there is a target peer
identity, then setRemoteDescription
rejects
the returned promise, unless the description contains an
identity assertion that matches the
target peer identity. The
RTCPeerConnection
MAY be closed if the
validated peer identity does not match the target peer identity.
The remoteDescription
attribute MUST return the last RTCSessionDescription
that was successfully set using setRemoteDescription()
,
plus any remote candidates that have been supplied via
addIceCandidate()
since then.
A null object will be returned if the remote description has not yet been set.
The signalingState
attribute MUST return the RTCPeerConnection
object's RTCPeerConnection
signaling state.
The updateIce 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 updateIce()
method is invoked, the user MUST run the following steps to process
the RTCConfiguration
dictionary:
If the iceTransportPolicy member is present, let its value be the ICE Agent's ICE transports setting.
If the iceTransportPolicy member was omitted and the ICE Agent's ICE transports setting is unset, set the ICE Agent's ICE transports setting to the iceTransportPolicy dictionary member default value.
If the iceServers dictionary
member is present, but its value is an empty list, then throw
an InvalidAccessError
and abort these steps. If
the list, on the other hand, has elements, each element must be
validated by running the following sub-steps:
Let server be the current list element.
If the server.urls dictionary member is
omitted or an empty list, then throw an
InvalidAccessError
and abort these steps.
If server.urls is a string, let urls be a list consisting of just that string. Otherwise, let urls refer to the server.urls list.
For each url in 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.
After passing the validation, let the iceServers dictionary member 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
RTCPeerConnection
's ice gathering
state transitions to gathering
. If a script
wants this to happen immediately, it should do an ICE
restart.
If the iceServers dictionary
member was omitted, and the ICE Agent's ICE servers list is unset, throw an
InvalidAccessError
and abort these steps.
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 RTCPeerConnection
object's
signaling
state is closed
, the user agent MUST reject
p with InvalidStateError
, and
jump to the step labeled Return.
If the candidate parameter is malformed, reject p
with SyntaxError
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 (TODO
InvalidCandidate and InvalidMidIndex) and jump to the step
labeled Return.
If the candidate is successfully applied, resolve p with undefined.
Return: Return p.
The iceGatheringState
attribute MUST return the gathering state of the RTCPeerConnection
ICE
Agent.
The iceConnectionState
attribute MUST return the state of the RTCPeerConnection
ICE
Agent ICE state.
This 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
.
Returns a RTCConfiguration
object
representing the current configuration of this
RTCPeerConnection
object.
When this method is call, the user agent MUST construct new
RTCConfiguration
object to be returned, and
initialize it using the ICE Agent's ICE transports setting and ICE servers list.
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
.
negotiationneeded
, MUST be supported
by all objects implementing the RTCPeerConnection
interface.icecandidate
, MUST be supported by
all objects implementing the RTCPeerConnection
interface.signalingstatechange
, MUST
be supported by all objects implementing the
RTCPeerConnection
interface. It is called any
time the readyState
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
.iceconnectionstatechange
,
MUST be fired by all objects implementing the
RTCPeerConnection
interface. It is called any
time the RTCPeerConnection
ice connection state changes.
icegatheringstatechange
,
MUST be fired by all objects implementing the
RTCPeerConnection
interface. It is called any
time
the RTCPeerConnection
ice gathering state changes.
RTCPeerConnection
for legacy purposes.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.
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.
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.
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.
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.
An RTCPeerConnection
object MUST not be garbage
collected as long as any event can cause an event handler to be
triggered on the object. When the object's RTCPeerConnection
signalingState is closed
, no such event handler can be
triggered and it is therefore safe to garbage collect the object.
All RTCDTMFSender
,
RTCDataChannel
and
MediaStreamTrack
objects that are connected to a
RTCPeerConnection
are considered to have a strong
reference to the RTCPeerConnection
object.
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
failed
, and may trigger
intermittently (and resolve itself without action) on a flaky
network.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:
All methods that return promises are governed by the standard error handling rules of promises. Methods that do not return promises may throw exceptions to indicate errors.
Legacy-methods may only throw exceptions to indicate invalid state
and other programming errors. For example, when a legacy-method is
called when the RTCPeerConnection
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.
RTCSessionDescription
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
RTCSessionDescription
instance.
An RTCSdpType of "offer" indicates that a description should be treated as an [[!SDP]] offer.
An RTCSdpType of "pranswer" indicates that a description should 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".
An RTCSdpType of "answer" indicates that a description should be treated as an [[!SDP]] final answer, and the offer-answer exchange should 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".
RTCSessionDescription()
constructor takes an optional dictionary argument,
descriptionInitDict, whose content is used to initialize
the new RTCSessionDescription
object. If a
dictionary key is not present in descriptionInitDict, the
corresponding attribute will be initialized to null. If the
constructor is run without the dictionary argument, all attributes
will be initialized to null. This class is a future extensible
carrier for the data contained in it and does not perform any
substantive processing.This class is a future extensible carrier for the data contained in it and does not perform any substantive processing.
RTCIceCandidate()
constructor
takes an optional dictionary argument, candidateInitDict,
whose content is used to initialize the new
RTCIceCandidate
object. If a dictionary key is
not present in candidateInitDict, the corresponding
attribute will be initialized to null. If the constructor is run
without the dictionary argument, all attributes will be initialized
to null.The icecandidate
event of the RTCPeerConnection uses
the RTCPeerConnectionIceEvent
interface.
Firing an
RTCPeerConnectionIceEvent
event named
e with an RTCIceCandidate
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
RTCPeerConnectionIceEvent
interface with the
candidate
attribute set to the new ICE candidate, MUST be
created and dispatched at the given target.
The candidate
attribute is the
RTCIceCandidate
object with the new ICE
candidate that caused the event.
TODO
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 RTCPeerConnection
object contains a
set of RTCRtpSender
s, representing tracks to
be sent, and a set of RTCRtpReceiver
s,
representing tracks that are to be received on this
RTCPeerConnection
object. Both of these sets are
initialized to empty sets when the
RTCPeerConnection
object is created.
The RTP media API extends the
RTCPeerConnection
interface as described below.
Returns a sequence of RTCRtpSender
objects
representing the RTP senders that are currently attached to this
RTCPeerConnection
object.
The getSenders()
method MUST return a new sequence that represents a snapshot of all
the RTCRtpSenders
objects in this
RTCPeerConnection
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 stable between calls.
Returns a sequence of RTCRtpReceiver
objects
representing the RTP receivers that are currently attached to this
RTCPeerConnection
object.
The getReceivers()
method MUST return a new sequence that represents a snapshot of all
the RTCRtpReceiver
objects in this
RTCPeerConnection
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 stable between calls.
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
RTCPeerConnection
object on which the
MediaStreamTrack
, track, is to be
added.
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, though tracks marked with
peerIdentity can be transmitted if 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.
If connection's RTCPeerConnection
signalingState is stable
, then fire an negotiationneeded event at
connection.
Throughout this document, we need to indicate what should happen if a change happens and the state is not stable, most likely to fire the negotiationneeded event when the state eventually returns to stable.
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 MediaStreamTrack
object.
When the removeTrack()
method is invoked, the user agent
MUST run the following steps:
Let connection be the
RTCPeerConnection
object on which the
RTCRtpSender
, sender, is to be
removed.
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.
If connection's RTCPeerConnection
signalingState is stable
, then fire a negotiationneeded event at
connection.
This event handler, of event handler event type track
, MUST be fired
by all objects implementing the RTCPeerConnection
interface.
It is called any time a MediaStreamTrack
is added
by the remote peer; the process for this is indicated below.
Rejection of incoming tracks can be done by the application after receiving the ontrack event, by stopping the track.
The word "components" in this context refers to an RTP media flow and does not have anything to do with how [[ICE]] uses the term "component".
When a user agent has reached the point where a
MediaStreamTrack
can be created to represent an incoming
component, the user agent MUST run the following steps:
Let connection be the
RTCPeerConnection
expecting this media.
Let streams be a list of
MediaStream
objects that the sender indicated the
sent MediaStreamTrack
being a part of. This
information needed to collect these objects is part of the remote
SDP.
Run the following steps to create a track representing the incoming component:
Create a MediaStreamTrack
object
track to represent the component.
Initialize track's kind
attribute to "audio
" or "video
"
depending on the media type of the incoming component.
Initialize track's id
attribute to the component track id.
Initialize track's label
attribute to "remote audio
" or "remote
video
" depending on the media type of the incoming
component.
Initialize track's readyState
attribute to muted
.
If streams is an empty list, create a new
MediaStream
object and add it to streams.
Add track to all MediaStream
objects in streams.
Queue a task to run the following substeps:
If the connection's RTCPeerConnection
signalingState is closed
, abort these
steps.
Create a new RTCRtpReceiver
object
receiver for track, and add it
to connection's set of receivers.
Fire an event named
track
with
receiver, track, and streams
at the connection object.
When an RTCPeerConnection
finds that a track
from the remote peer has been removed, the user agent MUST follow these
steps:
Let connection be the
RTCPeerConnection
associated with the track
being removed.
Let track be the MediaStreamTrack
object that represents the track being removed, if any. If
there isn't one, then abort these steps.
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 peer.
When attributes on an RTCRtpSender
are modified, the encoding is either
changed appropriately, or a negotiation is triggered to signal the new encoding
parameters to the other side.
The RTCRtpSender.track
attribute is the track that is associated with this
RTCRtpSender
object.
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.
The RTCRtpReceiver.track
attribute is the track that is immutably associated with this
RTCRtpReceiver
object.
The track
event uses the
RTCTrackEvent
interface.
Firing an
RTCTrackEvent event named e with an
RTCRtpReceiver
receiver, a
MediaStreamTrack
track and a
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 RTCTrackEvent
interface with the
receiver
attribute
set to receiver,
track
attribute
set to track,
streams
attribute
set to streams, MUST be created and dispatched at the
given target.
The receiver
attribute
represents the RTCRtpReceiver
object associated with
the event.
The RTCTrackEvent.track
attribute
represents the MediaStreamTrack
object that is
associated with the RTCRtpReceiver
identified by
receiver
.
The streams
attribute returns an array of MediaStream
objects
representing the MediaStream
s that this event's
track
is a part of.
TODO
TODO
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
RTCPeerConnection
interface as described below.
Creates a new RTCDataChannel
object with the
given label. The RTCDataChannelInit
dictionary
can be used to configure properties of the underlying channel such as
data reliability.
When the createDataChannel()
method is invoked, the user agent MUST run the following steps.
If the RTCPeerConnection
object's
RTCPeerConnection
signalingState is closed
, throw an
InvalidStateError
exception and abort these
steps.
Let channel be a newly created
RTCDataChannel
object.
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 RTCDataChannel
, throw a
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.
datachannel
, MUST be supported by all
objects implementing the RTCPeerConnection
interface.The RTCDataChannel
interface represents a
bi-directional data channel between two peers. A
RTCDataChannel
is created via a factory method on an
RTCPeerConnection
object. The messages sent between
the browsers are described in [[!RTCWEB-DATA]] and
[[!RTCWEB-DATA-PROTOCOL]].
There are two ways to establish a connection with
RTCDataChannel
. The first way is to simply create a
RTCDataChannel
at one of the peers with the
negotiated
RTCDataChannelInit
dictionary member unset or set to
its default value false. This will announce the new channel in-band and
trigger a RTCDataChannelEvent
with the corresponding
RTCDataChannel
object at the other peer. The second
way is to let the application negotiate the
RTCDataChannel
. To do this, create a
RTCDataChannel
object with the negotiated
RTCDataChannelInit
dictionary member set to true, and
signal out-of-band (e.g. via a web server) to the other side that it
should create a corresponding RTCDataChannel
with the
negotiated
RTCDataChannelInit
dictionary member set to true and
the same id
. This will
connect the two separately created RTCDataChannel
objects. The second way makes it possible to create channels with
asymmetric properties and to create channels in a declarative way by
specifying matching ids
.
Each RTCDataChannel
has an associated
underlying data transport that is used to transport actual
data to the other peer. 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 (TODO: reference needed).
A RTCDataChannel
can be configured to operate in
different reliability modes. A reliable channel ensures that the data is
delivered at the other peer through retransmissions. An unreliable
channel is configured to either limit the number of retransmissions (
maxRetransmits
) or
set a time during which transmissions (including retransmissions) are
allowed ( maxPacketLifeTime
). These properties can not be used simultaneously and an attempt to do
so will result in an error. Not setting any of these properties results
in a reliable channel.
A RTCDataChannel
, created with createDataChannel()
or
dispatched via a RTCDataChannelEvent
, MUST initially
be in the connecting
state. When the
RTCDataChannel
object's underlying data
transport is ready, the user agent MUST announce the 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 RTCPeerConnection
object's
RTCPeerConnection
signalingState is closed
, abort these steps.
Let channel be the RTCDataChannel
object to be announced.
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 RTCPeerConnection
object's
RTCPeerConnection
signalingState is closed
, abort these steps.
Let channel be a newly created
RTCDataChannel
object.
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.
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 RTCPeerConnection
object.
An RTCDataChannel
object's underlying data
transport may be torn down in a non-abrupt manner by running the
closing procedure. When
that happens the user agent MUST, unless the procedure was initiated by
the close()
method,
queue a task that sets the object's readyState
attribute to
closing
. This will eventually render the data transport closed.
When a RTCDataChannel
object's underlying data
transport has been closed, the
user agent MUST queue a task to run the following steps:
Let channel be the RTCDataChannel
object whose transport
was closed.
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.
The RTCDataChannel.label
attribute represents a label that can be used to distinguish this
RTCDataChannel
object from other
RTCDataChannel
objects. Scripts are allowed to
create multiple RTCDataChannel
objects with the
same label. The attribute MUST return the value to which it was set
when the RTCDataChannel
object was created.
The RTCDataChannel.ordered
attribute returns true if the RTCDataChannel
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.
The 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 RTCDataChannel
was created.
The 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 RTCDataChannel
was created.
The RTCDataChannel.protocol
attribute returns the name of the sub-protocol used with this
RTCDataChannel
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.
The RTCDataChannel.negotiated
attribute returns true if this RTCDataChannel
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.
The RTCDataChannel.id
attribute
returns the id for this RTCDataChannel
. 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.
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).
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).
open
, MUST be supported by all
objects implementing the RTCDataChannel
interface.error
, MUST be supported by all
objects implementing the RTCDataChannel
interface.close
, MUST be supported by all
objects implementing the RTCDataChannel
interface.Closes the RTCDataChannel
. It may be called
regardless of whether the RTCDataChannel
object
was created by this peer or the remote peer.
When the RTCDataChannel
close()
method is called, the user agent MUST run the
following steps:
Let channel be the
RTCDataChannel
object which is about to be
closed.
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.
message
, MUST be supported by
all objects implementing the RTCDataChannel
interface.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 RTCDataChannel
object is created, the
binaryType
attribute MUST be initialized to the string "blob
".
This attribute controls how binary data is exposed to scripts. See the [[WEBSOCKETS-API]] for more information.
Run the steps described by the send()
algorithm with argument
type string
object.
Run the steps described by the send()
algorithm with argument
type Blob
object.
Run the steps described by the send()
algorithm with argument
type ArrayBuffer
object.
Run the steps described by the send()
algorithm with argument
type ArrayBufferView
object.
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.
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.
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..
Subprotocol name used for this channel.
The default value of false tells the user agent to announce the
channel in-band and instruct the other peer to dispatch a
corresponding RTCDataChannel
object. If set to
true, it is up to the application to negotiate the channel and create
a RTCDataChannel
object with the same
id
at the other
peer.
Overrides the default selection of id 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 RTCDataChannel
object on which data is to be sent.
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.
The user agent is attempting to establish the underlying data
transport. This is the initial state of a
RTCDataChannel
object created with createDataChannel()
.
The underlying data transport is established and
communication is possible. This is the initial state of a
RTCDataChannel
object dispatched as a part of a
RTCDataChannelEvent
.
The procedure
to close
down the underlying data transport has started.
The underlying data transport has been closed
or could not be
established.
The datachannel
event
uses the RTCDataChannelEvent
interface.
Firing a datachannel event named
e with a RTCDataChannel
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
RTCDataChannelEvent
interface with the channel
attribute set to
channel, MUST be created and dispatched at the given
target.
The channel
attribute
represents the RTCDataChannel
object associated
with the event.
TODO
A RTCDataChannel
object MUST not be garbage
collected if its
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.
In order to send DTMF (phone keypad) values across an
RTCPeerConnection
, the user agent needs to know which
MediaStreamTrack
on which
RTCPeerConnection
will carry the DTMF. This section
describes an interface on RTCPeerConnection
to
associate DTMF capability with a MediaStreamTrack
for
that RTCPeerConnection
. Details of how DTMF is sent to
the other peer are described in [[!RTCWEB-AUDIO]].
The Peer-to-peer DTMF API extends the
RTCPeerConnection
interface as described below.
The createDTMFSender() method creates an RTCDTMFSender
that references the given MediaStreamTrack
. An RTCRtpSender
for track
MUST already exist in theRTCPeerConnection
object's set of senders; if not, throw an
InvalidParameter
exception and abort these steps.
An RTCDTMFSender
is created by calling the
createDTMFSender()
method on an
RTCPeerConnection
. This constructs an object that
exposes the functions required to send DTMF on the given
MediaStreamTrack
.
The canInsertDTMF
attribute MUST indicate if the RTCDTMFSender
is
capable of sending DTMF.
An RTCDTMFSender
object's 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.
ISSUE: How are invalid values handled?
When the insertDTMF()
method is invoked, the
user agent MUST run the following steps:
MediaStreamTrack
is not
connected to the associated RTCPeerConnection
,
return.canInsertDTMF
attribute is false, return.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.
The track
attribute MUST return the
MediaStreamTrack
given as argument to the
createDTMFSender()
method.
This event handler uses the
RTCDTMFToneChangeEvent
interface to return the
character for each tone as it is played out. See
RTCDTMFToneChangeEvent
for details.
The toneBuffer
attribute MUST return a list of the tones remaining to be played out.
For the syntax, content, and interpretation of this list, see
insertDTMF
.
The duration
attribute
MUST return the current tone duration value. This value will be the
value last set via the insertDTMF()
method, or
the default value of 100 ms if insertDTMF()
was
called without specifying the duration.
The interToneGap
attribute MUST return the current value of the between-tone gap. This
value will be the value last set via the
insertDTMF()
method, or the default value of 70
ms if insertDTMF()
was called without specifying
the interToneGap.
The tonechange
event uses the
RTCDTMFToneChangeEvent
interface.
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 RTCDTMFToneChangeEvent
interface with the tone
attribute set to
tone, MUST be created and dispatched at the given target.
The tone
attribute contains the character for the tone that has just begun
playout (see insertDTMF()
). If the value is the
empty string, it indicates that the previous tone has completed
playback.
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
RTCPeerConnection
object on which the stats request
was issued. The calling Web application provides the selector to the
getStats()
method
and the browser emits (in the JavaScript) a set of statistics that it
believes is relevant to the selector.
The statistics returned are designed in such a way that repeated
queries can be linked by the RTCStats
id dictionary member. Thus, a Web application can
make measurements over a given time period by requesting measurements at
the beginning and end of that period.
The Statistics API extends the RTCPeerConnection
interface as described below.
Gathers stats for the given selector and reports the result asynchronously.
When the getStats()
method is
invoked, the user agent MUST queue a task to run the following
steps:
If the RTCPeerConnection
object's RTCPeerConnection
signalingState is closed
, throw an
InvalidStateError
exception.
Return, but continue the following steps in the background.
Let selectorArg be the methods first argument.
If selectorArg is an invalid selector, the user agent MUST queue a task to invoke the failure callback (the method's third argument).
Start gathering the stats indicated by selectorArg.
In case selectorArg is null, stats MUST be gathered
for the whole RTCPeerConnection
object.
When the relevant stats have been gathered, queue a task to
invoke the success callback (the method's second argument) with a
new RTCStatsReport
object, representing the
gathered stats, as its argument.
A RTCStatsReport
representing the gathered
stats.
The getStats()
method delivers a successful result in the form of a
RTCStatsReport
object. A
RTCStatsReport
object represents a map between
strings, identifying the inspected objects (RTCStats.id), and their corresponding
RTCStats
objects.
An RTCStatsReport
may be composed of several
RTCStats
objects, 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 MediaStreamTrack
is carried
by multiple SSRCs over the network, the
RTCStatsReport
may contain one RTCStats
object per SSRC (which can be distinguished by the value of the "ssrc"
stats attribute).
Getter to retrieve the RTCStats
objects that
this stats report is composed of.
The set of supported property names [[!WEBIDL]] is defined as the
ids of all the RTCStats
objects that has been
generated for this stats report. The order of the property names is
left to the user agent.
An RTCStats
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.
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 a
RTCStats
object.
The timestamp
,
of type DOMHiResTimeStamp
[[!HIGHRES-TIME]],
associated with this object. The time is relative to the UNIX epoch
(Jan 1, 1970, UTC).
The type of this object.
The type
attribute
MUST be initialized to the name of the most specific type this
RTCStats
dictionary represents.
A unique id
that is
associated with the object that was inspected to produce this
RTCStats
object. Two RTCStats
objects, extracted from two different
RTCStatsReport
objects, MUST have the same id if
they were produced by inspecting the same underlying object. User
agents are free to pick any format for the id as long as it meets the
requirements above.
...
The remoteId
can be used to look up the corresponding
RTCStats
object that represents stats reported by
the other peer.
...
...
...
...
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, function (report) { baselineReport = report; }, logError); // ... wait a bit setTimeout(function () { pc.getStats(selector, function (report) { currentReport = report; processStats(); }, logError); }, aBit); function processStats() { // compare the elements from the current report with the baseline for (var i in currentReport) { var now = currentReport[i]; if (now.type != "outbund-rtp") continue; // get the corresponding stats from the baseline report base = baselineReport[now.id]; if (base) { remoteNow = currentReport[now.remoteId]; remoteBase = baselineReport[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; } } } function logError(error) { log(error.name + ": " + error.message); }
WebRTC offers and answers (and hence the channels established by
RTCPeerConnection
objects) can be authenticated by
using a web-based Identity Provider (IdP). The idea is that the entity
sending the offer/answer acts as the Authenticating Party (AP) and
obtains an identity assertion from the IdP which it attaches to the
offer/answer. The consumer of the offer/answer (i.e., the
RTCPeerConnection
on which
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, which is deterministic from the IdP's identity, and the generic protocol for requesting and verifying 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. The generic protocol details are described in [[!RTCWEB-SECURITY-ARCH]]. This document specifies the procedures required to instantiate the IdP proxy, request identity assertions, and consume the results.
In order to communicate with the IdP, the browser instantiates an isolated interpreted context, effectively an invisible IFRAME. The initial contents of the context are loaded from a URI derived from the IdP's domain name, as described in [[!RTCWEB-SECURITY-ARCH]].
For purposes of generating assertions, the IdP shall be chosen as follows:
setIdentityProvider()
method has been called,
the IdP provided shall be used.setIdentityProvider()
method has not been
called, then the browser can 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.
The browser creates an IdP proxy by loading an isolated, invisible
IFRAME with HTML content from the IdP URI. The URI for the IdP is a
well-known URI formed from the domain
and protocol
fields, as specified in [[!RTCWEB-SECURITY-ARCH]].
When an IdP proxy is requiured, the browser performs the following steps:
sandbox
attribute is set to
"allow-forms allow-scripts allow-same-origin" to limit the
capabilities available to the IdP. The browser MUST prevent the IdP
proxy from navigating the browsing context to a different location.
The browser MUST prevent the IdP proxy from interacting with the user
(this includes, in particular, popup windows and user dialogs).MessageChannel
[[!webmessaging]] within the context of
the IdP proxy and assigns one port from the channel to a variable
named rtcwebIdentityPort on the window. This
message channel forms the basis of communication between the browser
and the IdP proxy. Since it is an essential security property of the
web sandbox that a page is unable to insert objects into content from
another origin, this ensures that the IdP proxy can trust that
messages originating from window.rtcwebIdentityPort are
from RTCPeerConnection
and not some other page. This
protection ensures that pages from other origins are unable to
instantiate IdP proxies and obtain identity assertions.RTCPeerConnection
that it is ready by sending a "READY"
message to the message channel port [[!RTCWEB-SECURITY-ARCH]]. Once
this message is received by the RTCPeerConnection
, the
IdP is considered ready to receive requests to generate or verify
identity assertions.[TODO: This is not sufficient unless we expect the IdP to protect this information. Otherwise, the a=identity information can be copied from a session with "good" properties to any other session with the same fingerprint information. Since we want to reuse credentials, that would be bad.] The identity mechanism MUST provide an indication to the remote side of whether it requires the stream contents to be protected. Implementations MUST have an user interface that indicates the different cases and identity for these.
The identity assertion request process involves the following steps:
RTCPeerConnection
instantiates an IdP proxy as
described in Identity
Provider Selection section and waits for the IdP to signal that it
is ready.
RTCPeerConnection
sends a "SIGN" message to the IdP
proxy. This message includes the material
the RTCPeerConnection
desires to be bound to the user's
identity.RTCPeerConnection
over the message channel.RTCPeerConnection
MAY store the identity assertion
for use with future offers or answers.createOffer()
or createAnswer()
, then the
assertion is inserted in the offer/answer SDP.The format and contents of the messages that are exchanged are described in detail in [[!RTCWEB-SECURITY-ARCH]].
The IdP proxy can return an "ERROR" response. If an error is
encountered, the browser MUST generate an idpassertionerror
event. No
"a=identity" attribute is added to SDP as a result.
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 could respond to a request to generate an identity assertion with a "LOGINNEEDED" error. This indicates that the site does not have the necessary information available to it (such as cookies) to authorize the creation of an identity assertion.
The "LOGINNEEDED" response includes a URL for a page where the
authorization process can be completed. This URL is exposed to the
application through the loginUrl
attribute of the idpassertionerror event. This URL might
be to a page where a user is able to 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; the resulting page then provides the user with an opportunity to provide 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 be 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 RTCPeerConnection
. The process runs
asynchronously, meaning that validation of an identity assertion does not
block the completion of setRemoteDescription
.
The identity assertion request process involves the following steps:
RTCPeerConnection
instantiates an IdP proxy as
described in Identity
Provider Selection section and waits for the IdP to signal that it
is ready.
RTCPeerConnection
sends a "VERIFY" message to the
IdP proxy. This message includes the assertion from the offer/answer
which is to be verified.RTCPeerConnection
over the message channel.RTCPeerConnection
validates that the fingerprint
provided by the IdP in the validation response matches the certificate
fingerprint that is, or will be, used for communications. This is
either by:
RTCPeerConnection
validates that the domain
portion of the identity matches the domain of the IdP as described in
[[!RTCWEB-SECURITY-ARCH]].RTCPeerConnection
stores the assertion in the
peerIdentity
attribute and raises a simple event named peeridentity at itself. The assertion information to be
displayed MUST contain the domain name of the IdP as provided in the
assertion.
The IdP might fail to validate the identity assertion by providing an "ERROR" response to the validation request. Validation can also fail due to the additional checks performed by the browser. In both cases, the process terminates and no identity information is exposed to the application or the user.
The browser MUST raise an idpvalidationerror
event if
validation of an identity assertion fails for any reason.
If the "peerIdentity" constraint is applied to the
RTCPeerConnection
, any error MUST cause setRemoteDescription
to fail.
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 validation. Failure to do so potentially causes the corresponding operation to take an indefinite amount of time. This timer can be cancelled when the IdP produces a response. The timer running to completion can be treated as equivalent to an error from the IdP.
The format and contents of the messages that are exchanged are described in detail in [[!RTCWEB-SECURITY-ARCH]].
The Identity API extends the RTCPeerConnection
interface as described below.
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 will 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
,
username
).
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 the need to generate SDP with
either createOffer
or createAnswer
.
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.
Contains the peer identity assertion information if an identity assertion was provided and verified. Once this value is set to a non-null value, it cannot change.
identityresult
, MUST be fired by
all objects implementing the RTCPeerConnection
interface. This event is fired when an identity assertion is
successfully generated. Note: this event is fired when an identity
assertion is generated during the creation of an offer or answer.peeridentity
MUST be fired when a peer
identity from a peer is successfully validated.idpassertionerror
MUST be fired
when an IdP encounters an error in generating an identity
assertion.idvalidationperror
MUST be fired
when an IdP encounters an error in validating an identity
assertion.A domain name representing the identity provider.
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 RTCIdentiytEvent
is raised when an IdP
produces an identity assertion.
A string containing the encoded identity assertion (the information that would be added to the "a=identity" line in SDP [[!RTCWEB-SECURITY-ARCH]]).
The RTCIdentityErrorEvent
is raised when an
IdP fails to successfully produce an identity assertion.
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.onpeeridentity = function(e) { console.log("IdP= " + e.target.peerIdentity.idp + " identity=" + e.target.peerIdentity.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]].
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
MediaStreamTrack
created by an
RTCPeerConnection
object (as described previously in this
document) will take as input the data received from a remote peer.
Similarly, a MediaStreamTrack
from a local source, for instance a
camera via [[!GETUSERMEDIA]], will have an output that represents what is
transmitted to a remote peer if the object is used with an
RTCPeerConnection
object.
The concept of duplicating MediaStream
and
MediaStreamTrack
objects as described in [[!GETUSERMEDIA]] is
also applicable here. This feature can be used, for instance, in a
video-conferencing scenario to display the
local video from the user's camera and microphone in a local
monitor, while only transmitting the audio to the remote peer (e.g. in
response to the user using a "video mute" feature). Combining
different MediaStreamTrack
objects into new MediaStream
objects is useful in certain situations.
In this document, we only specify aspects of the
following objects that are relevant when used along with an
RTCPeerConnection
. Please refer to the original
definitions of the objects in the [[!GETUSERMEDIA]] document for general
information on using MediaStream
and
MediaStreamTrack
.
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
RTCPeerConnection
and then sent back to the
original user agent in the same manner, in which case the original user
agent will have multiple streams with the same id (the
locally-generated one and the one received from the remote peer).
A new media track may be associated with an existing
MediaStream
. For example, if a remote peer adds a
new MediaStreamTrack
object to a
RTCPeerConnection
, and indicates that the
MediaStreamTrack
is a member of a
MediaStream
that has already been created locally
by the RTCPeerConnection
, this is observed on the local
user agent. If this happens for the reason exemplified, or for any
other reason than the 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 MediaStreamTrack
object representing the media component about to be added.
Add track to stream's track set.
Fire a track event named addtrack
with the newly created MediaStreamTrack
object
at stream.
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 MediaStreamTrack
object representing the media component about to be removed.
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 RTCPeerConnection
object.
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
RTCPeerConnection
) is always strong.
A MediaStreamTrack
, received from the
ontrack
event on an
RTCPeerConnection
, MUST have its
muted
attribute [[!GETUSERMEDIA]] set to
true
until media data arrives from the RTP source.
In addition, a MediaStreamTrack
has its
muted
attribute set to true
on the
remote peer if the local user agent makes inactive the corresponding
MediaStreamTrack
that is being sent.
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]].
ISSUE: 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.
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 RTCPeerConnection
instance, subject to the
restrictions in isolated streams and 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.
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.
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 RTCPeerConnection
.
However, the content of an isolated track MUST NOT be transmitted
unless all of the following constraints are met:
A MediaStreamTrack
from a stream acquired using the
peerIdentity option can be transmitted if the
RTCPeerConnection
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 name
attribute of the peerIdentity
attribute of the RTCPeerConnection
instance
MUST match the value of the 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 RTCPeerConnection
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
.
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
RTCPeerConnection
records are not reduced in
capability. New statistics that might compromise isolation MUST be
avoided, or explicitly suppressed for isolated streams.
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.
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": [{ "url": "stun: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({ "sdp": 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.sdp) { var desc = new RTCSessionDescription(message.sdp); // 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({ "sdp": pc.localDescription })); }) .catch(logError); } else pc.setRemoteDescription(desc).catch(logError); } else pc.addIceCandidate(new RTCIceCandidate(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
RTCDataChannel
object and perform the offer/answer
exchange required to connect the channel to the other peer. The
RTCDataChannel
is used in the context of a simple
chat application and listeners are attached to monitor when the channel
is ready, messages are received and when the channel is closed.
This example uses the negotiationneeded
event to initiate the offer/answer dialog. The exact behavior
surrounding the negotiationneeded
event is not specified
in detail at the moment. This example can hopefully help to drive that
discussion. An assumption made in this example is that the event only
triggers when a new negotiation should be started. This means that an
action (such as addTrack()) that normally would have fired the
negotiationneeded
event will not do so during an ongoing
offer/answer dialog.
var signalingChannel = new SignalingChannel(); var configuration = { "iceServers": [{ "url": "stun: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({ "sdp": 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.sdp) { var desc = new RTCSessionDescription(message.sdp); // 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({ "sdp": pc.localDescription })); }) .catch(logError); } else pc.setRemoteDescription(desc).catch(logError); } else pc.addIceCandidate(new RTCIceCandidate(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 pc is a connected RTCPeerConnection, and track is an audio track on that connection.
Sending the DTMF signal "1234" with 500 ms duration per tone:
var sender = pc.createDTMFSender(track); if (sender.canInsertDTMF) { var duration = 500; sender.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):
var sender = pc.createDTMFSender(track); sender.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.insertDTMF("1234");
Send a 1-second "1" tone followed by a 2-second "2" tone:
var sender = pc.createDTMFSender(track); sender.ontonechange = function (e) { if (e.tone == "1") sender.insertDTMF("2", 2000); }; sender.insertDTMF("1", 1000);
It is always safe to append to the tone buffer. This example appends before any tone playout has started as well as during playout.
var sender = pc.createDTMFSender(track); sender.insertDTMF("123"); // append more tones to the tone buffer before playout has begun sender.insertDTMF(sender.toneBuffer + "456"); sender.ontonechange = function (e) { if (e.tone == "1") // append more tones when playout has begun sender.insertDTMF(sender.toneBuffer + "789"); };
Send the DTMF signal "123" and abort after sending "2".
var sender = pc.createDTMFSender(track); sender.ontonechange = function (e) { if (e.tone == "2") // empty the buffer to not play any tone after "2" sender.insertDTMF(""); }; sender.insertDTMF("123");
The following events fire on RTCDataChannel
objects:
Event name | Interface | Fired when... |
---|---|---|
open |
Event |
The RTCDataChannel object's underlying data
transport has been established (or re-established).
|
MessageEvent |
Event |
A message was successfully received. TODO: Ref where MessageEvent is defined? |
error |
Event |
TODO. |
close |
Event |
The RTCDataChannel object's underlying data
transport has bee closed.
|
The following events fire on RTCPeerConnection
objects:
Event name | Interface | Fired when... |
---|---|---|
connecting |
Event |
TODO |
track |
RTCTrackEvent |
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 at some point in the near future. |
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 |
RTCPeerConnectionIceEvent |
A new RTCIceCandidate is made available to
the script. |
datachannel |
RTCDataChannelEvent |
A new RTCDataChannel 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. |
identityresult |
RTCIdentityEvent |
A new RTCIdentityEvent is dispatched to the
script when an identity assertion is successfully generated by an
IdP. |
peeridentity |
Event |
A new Event is dispatched to the script when
an identity assertion provided by a peer is successfully
validated. |
idpassertionerror |
RTCIdentityErrorEvent |
A new RTCIdentityErrorEvent is dispatched to
the script when an IdP encounters an error while generating an
identity assertion. |
idpvalidationerror |
RTCIdentityErrorEvent |
A new RTCIdentityErrorEvent is dispatched to
the script when an IdP encounters an error while validating an
identity assertion. |
The following events fire on RTCDTMFSender
objects:
Event name | Interface | Fired when... |
---|---|---|
tonechange |
Event |
The RTCDTMFSender object has either just
begun playout of a tone (returned as the tone
attribute) or just ended playout of a tone (returned as an empty
value in the tone attribute). |
TBD
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, and Eric Rescorla.