diff --git a/images/2-layer-spatial-temporal.png b/images/2-layer-spatial-temporal.png
new file mode 100644
index 0000000..039d8d7
Binary files /dev/null and b/images/2-layer-spatial-temporal.png differ
diff --git a/images/2-layer-spatialsim-temporal.png b/images/2-layer-spatialsim-temporal.png
new file mode 100644
index 0000000..323dc14
Binary files /dev/null and b/images/2-layer-spatialsim-temporal.png differ
diff --git a/images/3-layer-temporal.png b/images/3-layer-temporal.png
new file mode 100644
index 0000000..48695cb
Binary files /dev/null and b/images/3-layer-temporal.png differ
diff --git a/images/icestates.png b/images/icestates.png
index cc106af..2622107 100644
Binary files a/images/icestates.png and b/images/icestates.png differ
diff --git a/images/ortc-big-picture.png b/images/ortc-big-picture.png
index 54e0037..0409705 100644
Binary files a/images/ortc-big-picture.png and b/images/ortc-big-picture.png differ
diff --git a/ortc.html b/ortc.html
index d5e04c6..b69573e 100644
--- a/ortc.html
+++ b/ortc.html
@@ -17,6 +17,14 @@
"companyURL": "http://www.hookflash.com/" }
],
"authors": [
+ { "name": "Bernard Aboba",
+ "url": "https://plus.google.com/+BernardAboba/about",
+ "company": "Microsoft Corporation",
+ "companyURL": "http://www.microsoft.com/" },
+ { "name": "Justin Uberti",
+ "url": "https://plus.google.com/+JustinUberti/posts",
+ "company": "Google",
+ "companyURL": "https://www.google.com/" },
{ "name": "Inaki Baz Castillo",
"url": "",
"company": "Versatica",
@@ -32,11 +40,7 @@
{ "name": "Roman Shpount",
"url": "",
"company": "TurboBridge",
- "companyURL": "http://turbobridge.com/" },
- { "name": "Erik Lagerway",
- "url": "http://about.me/elagerway",
- "company": "Hookflash",
- "companyURL": "http://www.hookflash.com/" }
+ "companyURL": "http://turbobridge.com/" }
],
"wg": "Object-RTC API Community Group",
"wgURI": "http://www.w3.org/community/ortc/",
@@ -68,6 +72,17 @@
, href: "http://www.iana.org/assignments/sdp-parameters/sdp-parameters.xhtml#sdp-parameters-19"
, publisher: "IANA"
},
+ "OPUS-RTP": {
+ title: "RTP Payload Format for Opus Speech and Audio Codec"
+ , href: "http://tools.ietf.org/html/draft-ietf-payload-rtp-opus"
+ , authors: [
+ "J. Spittka"
+ , "K. Vos"
+ , "JM. Valin"
+ ]
+ , status: "30 June 2014. Internet Draft (work in progress)"
+ , publisher: "IETF"
+ },
"RFC4585": {
title: "Extended RTP Profile for RTCP-Based Feedback (RTP/AVPF)"
, href: "http://tools.ietf.org/html/rfc4585"
@@ -91,6 +106,15 @@
, status: "December 2006. RFC"
, publisher: "IETF"
},
+ "RFC4961": {
+ title: "Symmetric RTP/RTC Control Protocol (RTCP)"
+ , href: "http://tools.ietf.org/html/rfc4961"
+ , authors: [
+ "D. Wing"
+ ]
+ , status: "July 2007. RFC"
+ , publisher: "IETF"
+ },
"RFC5104": {
title: "Codec Control Messages in the RTP Audio-Visual Profile with Feedback (AVPF)"
, href: "http://tools.ietf.org/html/rfc5104"
@@ -153,6 +177,16 @@
, status: "April 2010. RFC"
, publisher: "IETF"
},
+ "RFC5764": {
+ title: "Datagram Transport Layer Security (DTLS) Extension to Establish Keys for the Secure Real-time Transport Protocol (SRTP)"
+ , href: "http://tools.ietf.org/html/rfc5764"
+ , authors: [
+ "D. McGrew"
+ , "E. Rescorla"
+ ]
+ , status: "May 2010. RFC"
+ , publisher: "IETF"
+ },
"RFC6051": {
title: "Rapid Synchronisation of RTP Flows"
, href: "http://tools.ietf.org/html/rfc6051"
@@ -163,6 +197,18 @@
, status: "November 2010. RFC"
, publisher: "IETF"
},
+ "RFC6184": {
+ title: "RTP Payload Format for H.264 Video"
+ , href: "http://tools.ietf.org/html/rfc6184"
+ , authors: [
+ "Y.-K.. Wang"
+ , "R. Even"
+ , "T. Kristensen"
+ , "R. Jesup"
+ ]
+ , status: "May 2011. RFC"
+ , publisher: "IETF"
+ },
"RFC6190": {
title: "RTP Payload Format for Scalable Video Coding"
, href: "http://tools.ietf.org/html/rfc6190"
@@ -263,6 +309,17 @@
, status: "November 2013. RFC"
, publisher: "IETF"
},
+ "BUNDLE": {
+ title: "Negotiating Media Multiplexing Using the Session Description Protocol (SDP)"
+ , href: "http://tools.ietf.org/html/draft-ietf-mmusic-sdp-bundle-negotation"
+ , authors: [
+ "C. Holmberg",
+ "H. Alvestrand",
+ "C. Jennings"
+ ]
+ , status: "23 April 2014. Internet Draft (work in progress)"
+ , publisher: "IETF"
+ },
"APPID": {
title: "The Session Description Protocol (SDP) Application Token Attribute"
, href: "http://tools.ietf.org/html/draft-even-mmusic-application-token"
@@ -296,6 +353,33 @@
, status: "09 April 2014. Internet Draft (work in progress)"
, publisher: "IETF"
},
+ "RTCWEB-SECURITY": {
+ title: "Security Considerations for WebRTC"
+ , href: "http://tools.ietf.org/html/draft-ietf-rtcweb-security"
+ , authors: [
+ "E. Rescorla"
+ ]
+ , status: "4 July 2014. Internet Draft (work in progress)"
+ , publisher: "IETF"
+ },
+ "RTCWEB-SECURITY-ARCH": {
+ title: "WebRTC Security Architecture"
+ , href: "http://tools.ietf.org/html/draft-ietf-rtcweb-security-arch"
+ , authors: [
+ "E. Rescorla"
+ ]
+ , status: "4 July 2014. Internet Draft (work in progress)"
+ , publisher: "IETF"
+ },
+ "RTCWEB-VIDEO": {
+ title: "WebRTC Video Processing and Codec Requirements"
+ , href: "http://tools.ietf.org/html/draft-ietf-rtcweb-video"
+ , authors: [
+ "A.B. Roach"
+ ]
+ , status: "1 July 2014. Internet Draft (work in progress)"
+ , publisher: "IETF"
+ },
"RTP-USAGE": {
title: "Web Real-Time Communication (WebRTC): Media Transport and Use of RTP"
, href: "http://tools.ietf.org/html/draft-ietf-rtcweb-rtp-usage"
@@ -330,7 +414,7 @@
This document defines a set of ECMAScript APIs in WebIDL to allow media to be sent and received
from another browser or device implementing the appropriate set of real-time protocols. However,
-unlike the WebRTC 1.0 API, Object Realtime Communications (ORTC) API does not mandate a media signaling protocol or
+unlike the WebRTC 1.0 API, Object Real-Time Communications (ORTC) API does not mandate a media signaling protocol or
format. As a result, ORTC does not utilize Session Description Protocol (SDP), nor does it mandate support for
the Offer/Answer state machine.
Instead, ORTC focuses on "sender", "receiver" and "transport" objects, which have
@@ -347,7 +431,7 @@
Overview
-Object RealTime Communications (ORTC) provides a powerful API for the development of WebRTC based applications.
+
Object Real-Time Communications (ORTC) provides a powerful API for the development of WebRTC based applications.
ORTC does not mandate a media signaling protocol or format (as the current WebRTC 1.0 does by mandating SDP Offer/Answer).
Instead, ORTC focuses on "sender", "receiver" and "transport" objects, which have
"capabilities" describing what they are capable of doing,
@@ -363,7 +447,9 @@
Overview
(Section 11), and RTCSctpTransport (Section 12).
RTP dictionaries are described in Section 9,
the Statistics API is described in Section 13,
-and an event summary is provided in Section 14.
+the Identity API is described in Section 14,
+an event summary is provided in Section 15,
+and WebRTC 1.0 compatibility issues are discussed in Section 16.
In a Javascript application utilizing the ORTC API,
@@ -395,15 +481,15 @@
Terminology
"http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">event
handler event types are defined in [[!HTML5]].
- The terms MediaStream, MediaStreamTrack
- and Consumer are defined in
+
The terms MediaStream and MediaStreamTrack
+ are defined in
[[!GETUSERMEDIA]].
For Scalable Video Coding (SVC), the terms single-session transmission (SST) and multi-session transmission (MST)
- are defined in [[!RFC6190]]. This specification only supports SST but not MST.
- However, within a single RTP session, this specification allows a codec implementation to indicate
- whether it supports SVC, and if so, whether it is capable of configuring SVC layers to utilize distinct SSRCs, or whether all layers
- must utilize the same SSRC.
+ are defined in [[RFC6190]]. This specification only supports SST but not MST. The term SST-SS refers to
+ an SVC implementation that transmits all layers within a single RTP session, using a single SSRC.
+ The term SST-MS refers
+ to an SVC implementation that transmits all layers within a single RTP session, using a distinct SSRC for each layer.
@@ -416,43 +502,51 @@ The RTCDtlsTransport Object
Interface Definition
-
+
+
+
+
- readonly attribute RTCIceTransport transport
- The associated RTCIceTransport instance.
The associated RTCIceTransport instance.
- readonly attribute RTCDtlsTransportState state
The current state of the DTLS transport.
- void setTransport(RTCIceTransport transport)
- Set the RTCIceTransport.
- RTCDtlsParameters getLocalParameters()
- Obtain the DTLS parameters of the local RTCDtlsTransport.
Obtain the DTLS parameters of the local RTCDtlsTransport.
- RTCDtlsParameters? getRemoteParameters()
- Obtain the current DTLS parameters of the remote RTCDtlsTransport.
Obtain the current DTLS parameters of the remote RTCDtlsTransport.
- sequence<ArrayBuffer> getRemoteCertificates()
Obtain the certificates used by the remote peer.
- void start(RTCDtlsParameters remoteParameters)
- Start DTLS transport negotiation with the parameters of the remote DTLS transport.
Start DTLS transport negotiation with the parameters of the remote DTLS transport;
+ then once the DTLS transport session is established, negotiate a DTLS-SRTP [[!RFC5764]] session to protect media.
+ Since symmetric RTP [[!RFC4961]] is utilized, the DTLS-SRTP session is bidirectional.
+ If remoteParameters is invalid, throw an InvalidParameter exception.
+
- void stop()
- Stops and closes the DTLS transport object.
Stops and closes the DTLS transport object. stop(). is final - calling start() afterwards
+ will throw an InvalidState exception.
- attribute EventHandler? ondtlsstatechange
This event handler, of event handler type dtlsstatechange
@@ -464,7 +558,9 @@
Interface Definition
- attribute EventHandler? onerror
This event handler, of event handler type error,
- MUST be supported by all objects implementing the RTCDtlsTransport interface.
RTCDtlsTransport interface.
+ This event MUST be fired on reception of a DTLS alert.
+
@@ -500,10 +596,10 @@ The RTCDtlsFingerprint Object
enum RTCDtlsRole
-
+ RTCDtlsRole indicates the role of the DTLS transport.
- auto
- The DTLS role is be determined based on the resolved ICE role: the
+
The DTLS role is determined based on the resolved ICE role: the
'Controlled' role acts as the DTLS client,
the 'Controlling' role acts as the DTLS server.
enum RTCDtlsRole
enum RTCDtlsTransportState
- RTCDtlsTransportState provides information about the state of the DTLS transport.
+
RTCDtlsTransportState indicates the state of the DTLS transport.
- new
- DTLS connection object has been created and has not started negotiating yet.
The RTCDtlsTransport object has been created and has not started negotiating yet.
- connecting
DTLS is in the process of negotiating a secure connection.
- connected
- DTLS has completed negotiation of a secure connection (including DTLS/SRTP).
+
DTLS has completed negotiation of a secure connection (including DTLS-SRTP).
- closed
@@ -590,185 +686,99 @@ The RTCIceTransport Object
Overview
An RTCIceTransport instance is associated to a transport object (such as RTCDtlsTransport),
- and provides RTC related methods to it. To do an ICE restart, construct a new RTCIceTransport object
- (or alternatively, a new RTCIceListener object).
+ and provides RTC related methods to it.
+
Interface Definition
-
- - readonly attribute RTCIceListener iceListener
+
+ - readonly attribute RTCIceListener? iceListener
- The RTCIceListener specified in the RTCIceTransport constructor.
- If none was specified, the system will create an RTCIceListener automatically using the RTCIceOptions specified.
+ The iceListener is set to the value of listener passed in the latest call to start().
- readonly attribute RTCIceRole role
- RTCIceRole contains the current role of the ICE transport.
The current role of the ICE transport.
- readonly attribute RTCIceComponent component
- The component-id of the RTCIceTransport, which will always be "RTP" unless RTP and RTCP are not multiplexed and
- the RTCIceTransport object was returned by createAssociatedTransport().
The component-id of the RTCIceTransport.
- readonly attribute RTCIceTransportState state
The current state of the ICE transport.
- readonly attribute RTCIceGatheringState iceGatheringState
- The current state of ICE candidate gathering.
- sequence<RTCIceCandidate> getLocalCandidates()
- Retrieve the sequence of valid candidates associated with the local
- RTCIceTransport.
- This retrieves all candidates currently known, even if an onlocalcandidate
- event hasn't been processed yet.
- sequence<RTCIceCandidate> getRemoteCandidates()
Retrieve the sequence of candidates associated with the remote
RTCIceTransport. Only returns the candidates previously
added using setRemoteCandidates or addRemoteCandidate.
- void gather(RTCIceGatherPolicy gatherPolicy)
- Start gathering RTCIceCandidate objects, based on the gather policy
- (set on the local system, not negotiated).
- RTCIceCandidatePair? getNominatedCandidatePair()
+ Retrieves the nominated candidate pair. If there is no nominated pair yet, NULL is returned.
- void start(RTCIceParameters remoteParameters, optional RTCIceRole role)
- Starts candidate connectivity checks and attempts to connect to the remote
- RTCIceTransport.
- void restart()
- Causes an ICE restart, which resets the ICE gathering state to "gathering".
- void start(RTCIceListener listener, RTCIceParameters remoteParameters, optional RTCIceRole role)
+ The first time start is called candidate connectivity checks are started and the ICE transport attempts to connect to the remote
+ RTCIceTransport.
+ If start is called with invalid parameters,
+ throw an InvalidParameters exception.
+ If start is called again, an ICE restart occurs, all remote candidates are flushed, and addRemoteCandidates or
+ setRemoteCandidates must be called to add the remote candidates back or replace them.
+
- void stop()
- Stops and closes the current object.
- RTCIceParameters getLocalParameters()
- Obtain the ICE parameters of the local RTCIceTransport.
Stops and closes the current object. Also removes the object from the RTCIceTransportController.
- RTCIceParameters? getRemoteParameters()
Obtain the current ICE parameters of the remote RTCIceTransport.
- RTCIceTransport createAssociatedTransport ()
- Create an associated RTCIceTransport for RTCP,
- and implicitly create a newly associated
- RTCIceListener object as well for RTCP, or reusing an existing
- RTCP RTCIceListener if one is already associated with the
- existing RTP RTCIceListener.
+
Create an associated RTCIceTransport for RTCP.
If called more than once for the same
component, throw an InvalidStateError exception. If called when
component is "RTCP",
throw a SyntaxError exception.
- void addRemoteCandidate(RTCIceCandidate remoteCandidate)
+ - void addRemoteCandidate(RTCIceGatherCandidate remoteCandidate)
Add remote candidate associated with remote RTCIceTransport.
- void setRemoteCandidates(sequence<RTCIceCandidate> remoteCandidates)
- Set the sequence of candidates associated with the remote RTCIceTransport.
- attribute EventHandler? onlocalcandidate
- This event handler, of event handler event type icecandidate,
- MUST be supported by all objects implementing the
- RTCIceTransport interface.
- It receives events when a new local ICE candidate is available.
Set the sequence of candidates associated with the remote RTCIceTransport.
- attribute EventHandler? onicestatechange
This event handler, of event handler type icestatechange,
uses the RTCIceTransportStateChangedEvent interface.
It MUST be supported by
all objects implementing the RTCIceTransport interface.
- It is called any time the RTCIceTransportState changes.
+ It is called any time the RTCIceTransportState changes.
- attribute EventHandler? onicegatheringstatechange
- This event handler, of event handler type icegatheringstatechange
- uses the RTCIceGatheringStateChangedEvent interface.
+
- attribute EventHandler? oncandidatepairchange
+ This event handler, of event handler type icecandidatepairchange,
+ uses the RTCIceCandidatePairChangedEvent interface.
It MUST be supported by
all objects implementing the RTCIceTransport interface.
- It is called any time the RTCIceGatheringState changes.
+ It is called any time the nominated RTCIceCandidatePair changes.
- attribute EventHandler? onerror
- This event handler, of event handler type error,
- MUST be supported by all objects implementing the RTCIceTransport interface.
enum RTCIceComponent
-
+ RTCIceComponent contains the component-id of the RTCIceTransport, which will be "RTP" unless RTP and RTCP are not multiplexed and
+ the RTCIceTransport object was returned by createAssociatedTransport().
- RTP
- The RTP component ID, defined (as '1') in [[!RFC5245]] Section 4.1.1.1.
The RTP component ID, defined (as '1') in [[!RFC5245]] Section 4.1.1.1.
+ Protocols multiplexed with RTP (e.g. SCTP data channel) share its component ID.
+
- RTCP
The RTCP component ID, defined (as '2') in [[!RFC5245]] Section 4.1.1.1.
-
- enum RTCIceGatheringState
- The RTCIceGatheringState represents the state of ICE gathering.
-
- - new
- No networking has occurred yet.
- gathering
- The ICE engine is in the process of gathering candidates.
- complete
- The ICE engine has completed gathering and is currently idle.
- Events such as adding a new interface or a new TURN server will cause the state to go back to gathering.
-
-
-
- RTCIceGatheringStateChangedEvent
-
- The icegatheringstatechange event of the RTCIceTransport object uses
- the RTCIceGatheringStateChangedEvent interface.
-
- Firing an
- RTCIceGatheringStateChangedEvent event named
- e with an RTCIceGatheringState
- state 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
- RTCIceGatheringStateChangedEvent interface with the
- state attribute set to the new RTCIceGatheringState,
- MUST be
- created and dispatched at the given target.
-
-
-
- - readonly attribute RTCIceGatheringState state
- -
-
The state attribute is the new
- RTCIceGatheringState
- that caused the event.
-
-
-
-
-
- - RTCIceGatheringState? state
- -
-
The state attribute is the new
- RTCIceGatheringState
- that caused the event.
-
-
-
-
-
The RTCIceParameters Object
@@ -786,7 +796,7 @@ The RTCIceParameters Object
enum RTCIceRole
-
+ RTCIceRole contains the current role of the ICE transport.
- controlling
controlling state
enum RTCIceRole
-
- enum RTCIceGatherPolicy
-
-
- - all
- The ICE engine gathers all types of candidates when this value is specified.
- nohost
- The ICE engine gathers all ICE candidate types except for host candidates.
- relay
- The ICE engine MUST only gather media relay candidates such as candidates passing through a TURN server.
- This can be used to reduce leakage of IP addresses in certain use cases.
-
-
enum RTCIceTransportState
-
+ RTCIceTransportState represents the current state of the ICE transport.
- new
- The ICE Agent is gathering addresses and/or waiting for remote candidates to be supplied.
The ICE Transport is gathering addresses and/or waiting for remote candidates to be supplied.
- checking
- The ICE Agent has received remote candidates on at least one component, and is checking candidate pairs but has not yet found a connection. In addition to checking, it may also still be gathering.
The ICE Transport has received at least one remote candidate, and is checking candidate pairs but has not yet found a connection. In addition to checking, it may also still be gathering.
- connected
- The ICE Agent has found a usable connection for all components but is still checking other candidate pairs to see if there is a better connection. It may also still be gathering.
The ICE Transport has found a usable connection, but is still checking other candidate pairs to see if there is a better connection. It may also still be gathering.
- completed
- The ICE Agent has finished gathering and checking and found a connection for all components.
- Open issue: it is not clear how the non controlling ICE side knows it is in the state.
+ The ICE Transport has finished gathering and checking and found a connection.
+
- disconnected
- Liveness checks have failed for one or more components. This may trigger intermittently (and resolve itself without action).
Liveness checks have failed. This may trigger intermittently (and resolve
+ itself without action).
+
- closed
- The ICE Agent has shut down and is no longer responding to STUN requests.
The ICE Transport has shut down and is no longer responding to STUN requests.
The non-normative ICE state transitions are:
-
+
@@ -881,19 +879,47 @@ RTCIceTransportStateChangedEvent
-
- The RTCIceOptions Object
+
+ RTCIceCandidatePairChangedEvent
-
- The RTCIceOptions object includes information relating to ICE configuration.
-
+ The icecandidatepairchange event of the RTCIceTransport object uses
+ the RTCIceCandidatePairChangedEvent interface.
-
- - sequence<RTCIceServer>? iceServers
- An array containing STUN and TURN servers available to be used by ICE.
+ Firing an
+ RTCIceCandidatePairChangedEvent event named
+ e with an RTCIceCandidatePair
+ pair 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
+ RTCIceCandidatePairChangedEvent interface with the
+ pair attribute set to the nominated RTCIceCandidatePair,
+ MUST be
+ created and dispatched at the given target.
-
+
+
+ - readonly attribute RTCIceCandidatePair pair
+
+ -
+
The pair attribute is the nominated
+ RTCIceCandidatePair
+ that caused the event.
+
+
+
+
+
+ - RTCIceCandidatePair pair
+ -
+
The pair attribute is the nominated
+ RTCIceCandidatePair
+ that caused the event.
+
+
+
+
The RTCIceServer Object
@@ -915,10 +941,10 @@ The RTCIceServer Object
- (DOMString or sequence<DOMString>) urls
STUN or TURN URI(s) as defined in [[!RFC7064]] and [[!RFC7065]]
- DOMString? username
+ - DOMString username
If this RTCIceServer object represents a TURN server, then this attribute specifies
the username to use with that TURN server.
- DOMString? credential
+ - DOMString credential
If the uri element is a TURN URI, then this is the credential to use with that TURN server.
@@ -941,6 +967,9 @@ The RTCIceCandidate Object
};
+
+
+
- DOMString foundation
-
@@ -956,15 +985,15 @@
The RTCIceCandidate Object
The port for the candidate.
- RTCIceCandidateType type
The type of candidate.
- RTCIceTcpCandidateType? tcpType=null
+ - RTCIceTcpCandidateType tcpType
The type of TCP candidate.
- DOMString? relatedAddress=""
+ - DOMString relatedAddress=""
-
For candidates that are derived from others, such as relay or reflexive candidates, the relatedAddress
refers to the host candidate that these are derived from. For host candidates, the relatedAddress
is set to the empty string.
- - unsigned short? relatedPort=null
+ - unsigned short relatedPort
-
For candidates that are derived from others, such as relay or reflexive candidates, the relatedPort
refers to the host candidate that these are derived from. For host candidates, the relatedPort
@@ -992,15 +1021,15 @@
The RTCIceTcpCandidateType
- active
- An active TCP candidate is one for which the agent will
+
An active TCP candidate is one for which the transport will
attempt to open an outbound connection but will not receive incoming
connection requests.
- passive
- A passive TCP candidate is one for which the agent
+
A passive TCP candidate is one for which the transport
will receive incoming connection attempts but not attempt a
connection.
- so
- An so candidate is one for which the agent will attempt
+
An so candidate is one for which the transport will attempt
to open a connection simultaneously with its peer.
@@ -1023,15 +1052,41 @@ The RTCIceCandidateType
+
+ dictionary RTCIceCandidateComplete
+
+
+ The RTCIceCandidateComplete is an empty dictionary signifying that all RTCIceCandidates are gathered.
+
+
+
+
+
+
+
+ dictionary RTCIceCandidatePair
+
+
+ The RTCIceCandidatePair contains the currently selected ICE candidate pair.
+
+
+
+ - RTCIceCandidate local
+ The local ICE candidate.
- RTCIceCandidate remote
+ The remote ICE candidate.
+
+
+
RTCIceTransportEvent
- The icecandidate event of the RTCIceTransport uses
+
The icecandidate event of the RTCIceTransport and RTCIceListener objects uses
the RTCIceTransportEvent interface.
-
Firing an
RTCIceTransportEvent event named
- e with an RTCIceCandidate
+ e with an RTCIceGatherCandidate
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
@@ -1043,21 +1098,21 @@
RTCIceTransportEvent
- - readonly attribute RTCIceCandidate candidate
+ - readonly attribute RTCIceGatherCandidate candidate
-
The candidate attribute is the
- RTCIceCandidate object with the new ICE
+ RTCIceGatherCandidate object with the new ICE
candidate that caused the event.
- If candidate is null,
- there are no additional candidates for now.
+ If candidate is of type RTCIceCandidateComplete,
+ there are no additional candidates.
- - RTCIceCandidate? candidate
+ - RTCIceGatherCandidate candidate
-
The ICE candidate that caused the event.
@@ -1075,22 +1130,26 @@ Examples
// both ICE and DTLS, assuming that RTP and RTCP are multiplexed.
function initiate(mySignaller) {
- var iceOptions = ...;
- var ice = new RTCIceTransport(iceOptions);
+ var gatherOptions = new RTCIceGatherOptions;
+ gatherOptions.gatherPolicy = RTCIceGatherPolicy.all;
+ gatherOptions.iceservers = ... ;
+ var iceListener = new RTCIceListener(gatherOptions);
+ var ice = new RTCIceTransport();
var dtls = new RTCDtlsTransport(ice);
// ... get tracks and RTP objects from other example
mySignaller.mySendInitiate({
- "ice": ice.getLocalParameters(),
+ "ice": iceListener.getLocalParameters(),
"dtls": dtls.getLocalParameters(),
// ... include RTP info from other example
}, function(remote) {
- ice.start(remote.ice, RTCIceRole.controlling);
+ // Start the ICE transport
+ ice.start(iceListener, remote.ice, RTCIceRole.controlling);
dtls.start(remote.dtls);
// ... start RTP senders and receivers from other example
});
- ice.onlocalcandidate = function(candidate) {
+ iceListener.onlocalcandidate = function(candidate) {
mySignaller.mySendLocalCandidate(candidate);
}
@@ -1109,11 +1168,14 @@ Examples
// assuming that RTP and RTCP are multiplexed.
//
function accept(mySignaller, remote) {
- var iceOptions = ...;
- var ice = new RTCIceTransport(iceOptions);
+ var gatherOptions = new RTCIceGatherOptions;
+ gatherOptions.gatherPolicy = RTCIceGatherPolicy.all;
+ gatherOptions.iceservers = ... ;
+ var iceListener = new RTCIceListener(gatherOptions);
+ var ice = new RTCIceTransport();
var dtls = new RTCDtlsTransport(ice);
// ... get tracks and RTP objects from other example
- ice.onlocalcandidate = function(candidate) {
+ iceListener.onlocalcandidate = function(candidate) {
mySignaller.mySendLocalCandidate(candidate);
}
@@ -1122,12 +1184,12 @@ Examples
}
mySignaller.mySendAccept({
- "ice": ice.getLocalParameters(),
+ "ice": iceListener.getLocalParameters(),
"dtls": dtls.getLocalParameters()
// ... include RTP info from other example
});
-
- ice.start(remote.ice, RTCIceRole.controlled);
+ // Start the ICE transport with an implicit gather policy of "all"
+ ice.start(iceListener,remote.ice, RTCIceRole.controlled);
dtls.start(remote.dtls);
// ... start RTP senders and receivers from other example
@@ -1162,24 +1224,26 @@ Interface Definition
- sequence<RTCIceTransport> getTransports()
-
-
Returns the RTCIceTransport objects with component
+
Returns the RTCIceTransport objects with a component
of "RTP".
- - void addTransport(RTCIceTransport transport, int index = null)
+ - void addTransport(RTCIceTransport transport, optional unsigned long index)
-
Adds transport to the RTCIceTransportController
object for the purposes of managing
ICE freezing and sharing bandwidth estimation.
- RTCIceTransport objects will be unfrozen
+ Since addTransport manages ICE freezing, candidate pairs that are not in the
+ frozen state maintain their state when addTransport(transport) is called.
+ RTCIceTransport objects will be unfrozen
according to their index. transport is inserted at index,
or at the end if index is not specified.
- If index is greater than the current number of RTCIceTransports
+ If index is greater than the current number of RTCIceTransports
with a component of "RTP",
- throw a SyntaxError exception.
+ throw an InvalidParameter exception.
If transport has already been added to another
RTCIceTransportController object, or if
- the component is "RTCP", throw an InvalidStateError exception.
-
+ the component is "RTCP", throw an InvalidStateError exception.
+
@@ -1187,79 +1251,196 @@ Interface Definition
Examples
-// This is an example of how to utilize distinct ICE transports for RTP and RTCP.
+// This is an example of how to utilize distinct ICE transports for Audio and Video
+// As well as for RTP and RTCP. If both sides can multiplex audio/video
+// and/or RTP/RTCP then the multiplexing will occur.
+//
// Assume we have an audioTrack and a videoTrack to send.
//
+//create the RTP and RTCP ICE listeners for audio and video
+var gatherOptions = new RTCIceGatherOptions;
+gatherOptions.gatherPolicy = RTCIceGatherPolicy.all;
+gatherOptions.iceservers = ... ;
+var audioRtpIceListener = new RTCIceListener(gatherOptions);
+var audioRtcpIceListener = new RTCIceListener(gatherOptions);
+var videoRtpIceListener = new RTCIceListener(gatherOptions);
+var videoRtcpIceListener = new RTCIceListener(gatherOptions);
//create the RTP and RTCP ICE transports for audio and video
-var audioRtpIceTransport = new RTCIceTransport(...);
+var audioRtpIceTransport = new RTCIceTransport();
var audioRtcpIceTransport = audioRtpIceTransport.createAssociatedTransport();
-var videoRtpIceTransport = new RTCIceTransport(...);
+var videoRtpIceTransport = new RTCIceTransport();
var videoRtcpIceTransport = audioRtpIceTransport.createAssociatedTransport();
-
-//create the DTLS transports
+//
+// Prepare the audio and video ICE transports
+audioRtpIceListener.onlocalcandidate = function (event) {sendLocalCandidate(audioRtpIceTransport, event.candidate,"audio")};
+audioRtcpIceListener.onlocalcandidate = function (event) {sendLocalCandidate(audioRtcpIceTransport, event.candidate,"audio")};
+videoRtpIceListener.onlocalcandidate = function (event) {sendLocalCandidate(videoRtpIceTransport, event.candidate,"video")};
+videoRtcpIceListener.onlocalcandidate = function (event) {sendLocalCandidate(videoRtcpIceTransport, event.candidate,"video")};
+audioRtpIceTransport.onicestatechange = ... ;
+audioRtpIceListener.onerror = errorHandler;
+audioRtcpIceTransport.onicestatechange = ... ;
+audioRtcpIceListener.onerror = errorHandler;
+videoRtpIceTransport.onicestatechange = ... ;
+videoRtpIceListener.onerror = errorHandler;
+videoRctpIceTransport.onicestatechange = ... ;
+videoRctpIceListener.onerror = errorHandler;
+//Prepare the remote candidate handler
+mySignaller.onRemoteCandidate = function(remote) {
+ switch (remote.kind) {
+ case "audio":
+ if (remote.component === RTCIceComponent.RTP){
+ audioRtpIceTransport.addRemoteCandidate(remote.candidate);
+ } else {
+ audioRtcpIceTransport.addRemoteCandidate(remote.candidate);
+ };
+ break;
+ case "video":
+ if (remote.component === RTCIceComponent.RTP){
+ videoRtpIceTransport.addRemoteCandidate(remote.candidate);
+ } else {
+ videoRtcpIceTransport.addRemoteCandidate(remote.candidate);
+ };
+ break;
+ default:
+ log('Invalid media type received');
+ };
+}
+// Create the DTLS transports
var audioRtpDtlsTransport = new RTCDtlsTransport(audioRtpIceTransport);
var audioRtcpDtlsTransport = new RTCDtlsTransport(audioRtcpIceTransport);
var videoRtpDtlsTransport = new RTCDtlsTransport(videoRtpIceTransport);
var videoRtcpDtlsTransport = new RTCDtlsTransport(videoRtcpIceTransport);
-
-// ... start the ICE and DTLS transports
-var controller = new RTCIceTransportController();
-controller.addTransport(audioRtpIceTransport);
-controller.addTransport(videoRtpIceTransport);
+//
+// Create the sender and receiver objects
var audioSender = new RtpSender(audioTrack, audioRtpDtlsTransport, audioRtcpDtlsTransport);
var videoSender = new RtpSender(videoTrack, videoRtpDtlsTransport, videoRtcpDtlsTransport);
var audioReceiver = new RtpReceiver(audioRtpDtlsTransport, audioRtcpDtlsTransport);
var videoReceiver = new RtpReceiver(videoRtpDtlsTransport, videoRtcpDtlsTransport);
+//
+// Retrieve the receiver and sender capabilities
var recvAudioCaps = RTCRtpReceiver.getCapabilities("audio");
-var recvVideoCaps = RTCRtpReceiver.getCapabiltiies("video");
+var recvVideoCaps = RTCRtpReceiver.getCapabilities("video");
var sendAudioCaps = RTCRtpSender.getCapabilities("audio");
var recvVideoCaps = RTCRtpSender.getCapabilities("video");
-
-// At this point, capabilities can be exchanged.
- mySignaller.myOfferTracks({
-// Indicate that the initiator would prefer to multiplex RTP/RTCP.
- "rtcpMux": true,
-// Offer the receiver and sender audio and video capabilities.
- "recvAudioCaps": recvAudioCaps,
- "recvVideoCaps": recvVideoCaps,
- "sendAudioCaps": sendAudioCaps,
- "sendVideoCaps": sendVideoCaps
+//
+// At this point, ICE/DTLS parameters and Send/Receive capabilities can be exchanged.
+mySignaller.myOfferTracks({
+ // Indicate that the initiator would prefer to multiplex both A/V and RTP/RTCP
+ "bundle": true,
+ // Indicate that the initiator is willing to multiplex RTP/RTCP without A/V mux
+ "rtcpMux": true,
+ // Offer the ICE parameters
+ "audioRtpIce": audioRtpIceListener.getLocalParameters(),
+ "audioRtcpIce": audioRtcpIceListener.getLocalParameters(),
+ "videoRtpIce": videoRtpIceListener.getLocalParameters(),
+ "videoRtcpIce": videoRtcpIceListener.getLocalParameters(),
+ // Offer the DTLS parameters
+ "audioRtpDtls": audioRtpDtlsTransport.getLocalParameters(),
+ "audioRtcpDtls": audioRtcpDtlsTransport.getLocalParameters(),
+ "videoRtpDtls": videoRtpDtlsTransport.getLocalParameters(),
+ "videoRtcpDtls": videoRtcpDtlsTransport.getLocalParameters(),
+ // Offer the receiver and sender audio and video capabilities.
+ "recvAudioCaps": recvAudioCaps,
+ "recvVideoCaps": recvVideoCaps,
+ "sendAudioCaps": sendAudioCaps,
+ "sendVideoCaps": sendVideoCaps
}, function(answer) {
-// The responder answers with its RTP/RTCP multiplexing preference and capabilities
-
-// Derive the send and receive parameters, assuming that RTP/RTCP mux will be enabled.
- var audioSendParams = myCapsToSendParams(sendAudioCaps, answer.recvAudioCaps);
- var videoSendParams = myCapsToSendParams(sendVideoCaps, answer.recvVideoCaps);
- var audioRecvParams = myCapsToRecvParams(recvAudioCaps, answer.sendAudioCaps);
- var videoRecvParams = myCapsToRecvParams(recvVideoCaps, answer.sendVideoCaps);
-
-// If the responder wishes to enable RTP/RTCP multiplexing, we will enable it and so
-// we need to remember to stop the unused ICE transports, or else they will go to the
-// failed state when the remote endpoint blows theirs away.
-
-if (answer.rtcpMux) {
- audioRtcpIceTransport.stop();
- audioRtcpDtlsTransport.stop();
- videoRtcpIceTransport.stop();
- videoRtcpDtlsTransport.stop();
-} else {
-
-// If the responder does not want RTP/RTCP multiplexing, we need to set the rtcp.mux parameter to disable it.
- audioSendParams.rtcp.mux = false;
- videoSendParams.rtcp.mux = false;
- audioRecvParams.rtcp.mux = false;
- videoRecvParams.rtcp.mux = false;
-};
-
-// Set the audio and video send and receive parameters.
- audioSender.send(audioSendParams);
- videoSender.send(videoSendParams);
- audioReceiver.receive(audioRecvParams);
- videoReceiver.receive(videoRecvParams);
+ // The responder answers with its preferences, parameters and capabilities
+ //
+ // Derive the send and receive parameters, assuming that RTP/RTCP mux will be enabled.
+ var audioSendParams = myCapsToSendParams(sendAudioCaps, answer.recvAudioCaps);
+ var videoSendParams = myCapsToSendParams(sendVideoCaps, answer.recvVideoCaps);
+ var audioRecvParams = myCapsToRecvParams(recvAudioCaps, answer.sendAudioCaps);
+ var videoRecvParams = myCapsToRecvParams(recvVideoCaps, answer.sendVideoCaps);
+ //
+ // If the responder wishes to enable bundle, we will enable it
+ if (answer.bundle) {
+ // Only start the single ICE and DTLS transport that is needed.
+ // No need for the ICE Transport Controller.
+ audioRtpIceTransport.start(audioRtpIceListener,answer.audioRtpIce, RTCIceRole.controlling);
+ audioRtpDtlsTransport.start(remote.audioRtpDtls);
+ //
+ // Replace the transport on the Sender and Receiver objects
+ //
+ audioSender.setTransport(audioRtpDtlsTransport);
+ videoSender.setTransport(audioRtpDtlsTransport);
+ audioReceiver.setTransport(audioRtpDtlsTransport);
+ videoReceiver.setTransport(audioRtpDtlsTransport);
+ // If BUNDLE was requested, then also assume RTP/RTCP mux
+ answer.rtcpMux = true;
+ } else {
+ if (answer.rtcpMux){
+ // The peer doesn't want BUNDLE, but it does want to multiplex RTP/RTCP
+ // Create the ICE Transport Controller object
+ var controller = new RTCIceTransportController();
+ controller.addTransport(audioRtpIceTransport);
+ controller.addTransport(videoRtpIceTransport);
+ // Start the audio and video ICE transports, with an implicit gather policy of "all"
+ audioRtpIceTransport.start(audioRtpIceListener,answer.audioRtpIce, RTCIceRole.controlling);
+ videoRtpIceTransport.start(videoRtpIceListener,answer.videoRtpIce, RTCIceRole.controlling);
+ // Start the audio and video DTLS transports
+ audioRtpDtlsTransport.onerror = errorHandler;
+ audioRtpDtlsTransport.start(answer.audioRtpDtls);
+ videoRtpDtlsTransport.onerror = errorHandler;
+ videoRtpDtlsTransport.start(answer.videoRtpDtls);
+ // Replace the transport on the Sender and Receiver objects
+ //
+ audioSender.setTransport(audioRtpDtlsTransport);
+ videoSender.setTransport(videoRtpDtlsTransport);
+ audioReceiver.setTransport(audioRtpDtlsTransport);
+ videoReceiver.setTransport(videoRtpDtlsTransport);
+ };
+ // Check if the responder does not want BUNDLE
+ // and does not want RTP/RTCP multiplexing
+ if (!answer.rtcpMux) {
+ // Create the ICE Transport Controller object
+ var controller = new RTCIceTransportController();
+ controller.addTransport(audioRtpIceTransport);
+ controller.addTransport(videoRtpIceTransport);
+ controller.addTransport(audioRtcpIceTransport);
+ controller.addTransport(videoRtcpIceTransport);
+ // Start the ICE transports
+ audioRtpIceTransport.start(audioRtpIceListener,answer.audioRtpIce, RTCIceRole.controlling);
+ audioRtcpIceTransport.start(audioRtcpIceListener,answer.audioRtcpIce, RTCIceRole.controlling);
+ videoRtpIceTransport.start(videoRtpIceListener,answer.videoRtpIce, RTCIceRole.controlling);
+ videoRtcpIceTransport.start(videoRtcpIceListener,answer.videoRtcpIce, RTCIceRole.controlling);
+ // Start the DTLS transports that are needed
+ audioRtpDtlsTransport.start(answer.audioRtpDtls);
+ audioRtcpDtlsTransport.start(answer.audioRtcpDtls);
+ videoRtpDtlsTransport.start(answer.videoRtpDtls);
+ videoRtcpDtlsTransport.start(answer.videoRtcpDtls);
+ // Disable RTP/RTCP multiplexing
+ audioSendParams.rtcp.mux = false;
+ videoSendParams.rtcp.mux = false;
+ audioRecvParams.rtcp.mux = false;
+ videoRecvParams.rtcp.mux = false;
+ };
+ //
+ // Set the audio and video send and receive parameters.
+ audioSender.send(audioSendParams);
+ videoSender.send(videoSendParams);
+ audioReceiver.receive(audioRecvParams);
+ videoReceiver.receive(videoRecvParams);
});
-
// Now we can render/play
// audioReceiver.track and videoReceiver.track.
+
+// Helper functions
+function log(text) {
+ console.log('Time: ' + (performance.now() / 1000).toFixed(3) + ' ' + text);
+}
+
+function errorHandler (error) {
+ log('Error encountered: ' + error.name);
+}
+
+function sendLocalCandidate(transport, candidate, kind){
+ mySignaller.mySendLocalCandidate({
+ "candidate": candidate,
+ "kind": kind,
+ "component": transport.component
+ });
+}
@@ -1283,18 +1464,63 @@ Overview
Interface Definition
-
- - RTCIceOptions getOptions()
- Retrieves the ICE options.
- void setOptions(RTCIceOptions options)
- Sets the ICE options, if they weren't present in the constructor.
+ - RTCIceParameters getLocalParameters()
+ Obtain the ICE parameters of the RTCIceListener.
- sequence<RTCIceCandidate> getLocalCandidates()
+ Retrieve the sequence of valid local candidates associated with the
+ RTCIceListener.
+ This retrieves all local candidates currently known (except for peer reflexive candidates),
+ even if an onlocalcandidate
+ event hasn't been processed yet.
- attribute EventHandler? onerror
+ This event handler, of event handler type error,
+ MUST be supported by all objects
+ implementing the RTCIceListener interface.
+ If TURN credentials are invalid, then this event MUST
+ be fired.
+
- attribute EventHandler? onlocalcandidate
+ This event handler, of event handler event type icecandidate,
+ MUST be supported by all objects implementing the
+ RTCIceListener interface.
+ It receives events when a new local ICE candidate is available.
+
+
+
+
+ dictionary RTCIceGatherOptions
+ RTCIceGatherOptions provides options relating to the gathering of ICE candidates.
+
+
+ - RTCIceGatherPolicy gatherPolicy
+ The ICE gather policy.
- sequence<RTCIceServer> iceservers
+ The ICE servers to be configured.
+
+
+
+ enum RTCIceGatherPolicy
+ RTCIceGatherPolicy denotes the policy relating to the gathering of ICE candidates.
+
+ - all
+ The ICE transport gathers all types of candidates when this value is specified.
- nohost
+ The ICE transport gathers all ICE candidate types except for host candidates.
- relay
+ The ICE transport MUST only gather media relay candidates such as candidates passing through a TURN server.
+ This can be used to reduce leakage of IP addresses in certain use cases.
@@ -1304,34 +1530,34 @@ Example
// Example to demonstrate forking when RTP and RTCP are not multiplexed.
-var iceOptions = ...;
-var iceRtpListener = new RTCIceListener(iceOptions);
-var iceBaseRtpTransport = new RTCIceTransport(iceRtpListener);
-//create the RTCP ICE transport
+var iceGatherOptions = new RTCIceGatherOptions();
+gatherOptions.gatherPolicy = RTCIceGatherPolicy.relay;
+gatherOptions.iceservers = ... ;
+var iceRtpListener = new RTCIceListener(gatherOptions);
+var iceRtcpListener = new RTCIceListener(gatherOptions);
+var iceBaseRtpTransport = new RTCIceTransport();
+//create the RTCP ICE transport, which inherits the iceGatherOptions
var iceBaseRtcpTransport = iceBaseRtpTransport.createAssociatedTransport();
mySendInitiate(
{
- "icertp": iceBaseRtpTransport.getLocalParameters(),
- "icertcp": iceBaseRtcpTransport.getLocalParameters()
+ "icertp": iceRtpListener.getLocalParameters(),
+ "icertcp": iceRtcpListener.getLocalParameters()
},
function(response) {
// We may get N responses
- var iceRtpTransport = new RTCIceTransport(iceRtpListener);
- // Create new ice RTCP transport based on the (implicitly created) iceListener
- var iceRtcpTransport = iceRtpTransport.createAssociatedTransport();
-
-// check to make sure the RTCRtpIceListener objects are set up as expected.
- assert(iceRtpTransport.iceListener == iceBaseRtpTransport.iceListener);
- assert(iceRtcpTransport.iceListener == iceBaseRtcpTransport.iceListener);
-
- iceRtpTransport.start(response.icertp, RTCIceRole.controlling);
- iceRtcpTransport.start(response.icertcp, RTCIceRole.controlling);
+ // Create the ICE Transport Controller object
+ var controller = new RTCIceTransportController();
+ controller.addTransport(iceRtpTransport);
+ controller.addTransport(iceRtcpTransport);
+ // Start the ICE transports (using the "relay" gather policy inherited from the iceListener)
+ iceRtpTransport.start(iceRtpListener,response.icertp, RTCIceRole.controlling);
+ iceRtcpTransport.start(iceRtcpListener,response.icertcp, RTCIceRole.controlling);
// ... setup DTLS, RTP, SCTP, etc.
});
-iceBaseRtpTransport.onlocalcandidate = mySendLocalRtpCandidate;
-iceBaseRtcpTransport.onlocalcandidate = mySendLocalRtcpCandidate;
+iceRtpListener.onlocalcandidate = mySendLocalRtpCandidate;
+iceRtcpListener.onlocalcandidate = mySendLocalRtcpCandidate;
@@ -1361,18 +1587,18 @@ Operation
Interface Definition
-
- - readonly attribute MediaStreamTrack track
+
+ - readonly attribute MediaStreamTrack track
-
-
The associated MediaStreamTrack instance.
+ The associated MediaStreamTrack instance.
- - readonly attribute RTCDtlsTransport transport
+ - readonly attribute RTCDtlsTransport transport
-
The associated RTP RTCDtlsTransport instance.
- - readonly attribute RTCDtlsTransport rtcpTransport
+ - readonly attribute RTCDtlsTransport rtcpTransport
-
The associated RTCP RTCDtlsTransport instance.
@@ -1381,25 +1607,89 @@ Interface Definition
Set the RTP RTCDtlsTransport (and if used) RTCP RTCDtlsTransport.
- void setTrack(MediaStreamTrack track)
- Set the MediaStreamTrack.
Set the MediaStreamTrack.
- static RTCRtpCapabilities getCapabilities(optional DOMString kind)
Obtain the sender capabilities, based on kind. If kind is
- omitted, then all capabilities are returned.
- void send(RTCRtpParameters parameters)
Media to be sent is controlled by parameters.
- The sender starts sending when send()
- is called and stops sending when stop() is called.
send() is called with invalid RTCRtpParameters,
+ throw an InvalidParameters exception.
+ The send() method does not update
+ parameters based on what is currently being sent, so that the value of parameters remains that
+ last passed to the send() method.
+ The RTCRtpSender object starts sending when send()
+ is called for the first time, and changes the sending parameters when send() is called again.
+ The RTCRtpSender object stops sending when stop() is called.
+
- void stop()
- Stops sending the track on the wire. Stop is final like MediaStreamTrack
Stops sending the track on the wire, and sends an RTCP BYE.
+ Stop is final as in MediaStreamTrack.stop()
- attribute EventHandler? onerror
This event handler, of event handler type error,
- MUST be supported by all objects implementing the RTCRtpSender interface.
RTCRtpSender interface.
+ This event MUST be fired if an issue is found
+ with the RTCRtpParameters object passed to
+ send(), that is not immediately detected.
+
+ - attribute EventHandler? onssrcconflict
+ This event handler, of event handler type RTCSsrcConflictEvent,
+ MUST be supported by all objects implementing the RTCRtpSender interface.
+ This event MUST be fired if an SSRC conflict is detected.
+ On an SSRC conflict, the RTCRtpSender automatically sends an RTCP BYE on the conflicted SSRC.
+
+
+ RTCSsrcConflictEvent
+
+ The ssrcconflict event of the RTCRtpSender object uses
+ the RTCSsrcConflictEvent interface.
+
+ Firing an
+ RTCSsrcConflictEvent event named
+ e with an
+ ssrc 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
+ RTCSsrcConflictEvent interface with the
+ ssrc attribute set to the conflicting SSRC
+ MUST be
+ created and dispatched at the given target.
+
+
+
+ - readonly attribute unsigned long ssrc
+ -
+
The ssrc attribute represents the conflicting SSRC
+ that caused the event.
+
+
+
+
+
+ - unsigned long? ssrc
+ -
+
The ssrc attribute represents the conflicting SSRC
+ that caused the event.
+
+
+
+
+
+
+
+
@@ -1425,18 +1715,18 @@ Operation
Interface Definition
-
- - readonly attribute MediaStreamTrack? track
+
+ - readonly attribute MediaStreamTrack? track
-
-
The associated MediaStreamTrack instance.
+ The associated MediaStreamTrack instance.
- - readonly attribute RTCDtlsTransport transport
+ - readonly attribute RTCDtlsTransport transport
-
The associated RTP RTCDtlsTransport instance.
- - readonly attribute RTCDtlsTransport rtcpTransport
+ - readonly attribute RTCDtlsTransport rtcpTransport
-
The associated RTCP RTCDtlsTransport instance.
@@ -1445,19 +1735,36 @@ Interface Definition
Set the RTP RTCDtlsTransport (and if used) RTCP RTCDtlsTransport.
- static RTCRtpCapabilities getCapabilities(optional DOMString kind)
- Obtain the receiver capabilities, based on kind. If kind is omitted, then
+
Obtain the receiver capabilities, based on kind. If kind is omitted or set to "", then
all capabilities are returned.
- void receive(RTCRtpParameters parameters)
- Media to be received is controlled by the receive parameters.
- The receiver starts receiving when the receive() is called and stopped when the stop() is called.
Media to be received is controlled by parameters.
+ If receive() is called with invalid RTCRtpParameters,
+ throw an InvalidParameters exception.
+ The receive() method does not update
+ parameters based on what is currently being received, so that the value of parameters remains that
+ last passed to the receive() method.
+ The RTCRtpReceiver object starts receiving when receive()
+ is called for the first time, and changes the receiving parameters when receive() is called again.
+ The RTCRtpReceiver object stops receiving when stop() is called.
+
+ After receive returns, track is set, and the value of track.kind is determined
+ based on the kind of the codecs provided in parameters.codecs.
+ If parameters.codecs are all of a single kind then track.kind is set to that kind.
+ If parameters.codecs are of mixed kind,
+ throw an InvalidParameters exception.
+
- void stop()
- Stops receiving the track on the wire. Stop is final like MediaStreamTrack
Stops receiving the track on the wire. Stop is final like MediaStreamTrack.
+
- attribute EventHandler? onerror
This event handler, of event handler type error,
- MUST be supported by all objects implementing the RTCRtpReceiver interface.
RTCRtpReceiver interface.
+ This event MUST be fired if an issue is found with the RTCRtpParameters object passed to
+ receive(), that is not immediately detected.
+
@@ -1572,7 +1879,7 @@ Operation
Interface Definition
- - readonly attribute RTCDtlsTransport transport
+ - readonly attribute RTCDtlsTransport transport
-
The RTP RTCDtlsTransport instance.
@@ -1585,26 +1892,27 @@ Interface Definition
RTCRtpUnhandledEvent
- An unhandledrtp event is fired if the RTCRtpListener detects an RTP stream that is not configured to be processed by an
+
An unhandledrtp event is fired if the RTCRtpListener detects an
+ RTP stream that is not configured to be processed by an
existing RTCRtpReceiver object. The amount of buffering to be provided for unhandled
RTP streams is recommended to be strictly limited to protect against denial of service attacks.
- To determine whether an RTP stream is configured to be processed by an existing RTCRtpReceiver object,
- the RTCRtpListener attempts to match the values of an incoming RTP packet's
- Payload Type and SSRC fields as well as the value of its receiverId RTP extension (if present) against the
+
To determine whether an RTP stream is configured to be processed by an existing RTCRtpReceiver object,
+ the RTCRtpListener attempts to match the values of an incoming RTP packet's
+ Payload Type and SSRC fields as well as the value of the muxId (if present in the MID RTP header extension) against the
RTCRtpReceiver.RTCRtpParameters.RTCRtpCodecParameters.payLoadType,
RTCRtpReceiver.RTCRtpParameters.RTCRtpEncodingParameters.ssrc,
- and RTCRtpReceiver.RTCRtpParameters.receiverId attributes of configured RTCRtpReceiver objects.
+ and RTCRtpReceiver.RTCRtpParameters.muxId attributes of configured RTCRtpReceiver objects.
TODO: provide details of matching behavior, along with examples.
- The unhandledrtp event of the RTCRtpListener uses
+
The unhandledrtp event of the RTCRtpListener object uses
the RTCRtpUnhandledEvent interface.
Firing an
- unhandledrtp event named
+ unhandledrtp event named
e with an RTCRtpUnhandled
stream means that an event with the name e,
which does not bubble (except where otherwise stated) and is not
@@ -1650,28 +1958,37 @@
Dictionaries related to Rtp
RTCRtpUnhandled
+ RTCRtpUnhandled provides information on the RTP packet that caused the RTCRtpUnhandled event.
+
+
+
- unsigned long ssrc
-
-
The SSRC in the RTP stream triggering the unhandledrtp event.
+ The SSRC in the RTP stream triggering the unhandledrtp event.
- - unsigned short payloadType
+ - payloadtype payloadType
-
-
The Payload Type value in the RTP stream triggering the unhandledrtp event.
+ The Payload Type value in the RTP stream triggering the unhandledrtp event.
- - DOMString? receiverId
+ - DOMString muxId
-
-
The value of the AppId header extension in the RTP stream triggering the unhandledrtp event, if present.
+ If present, the value of the MID RTP header extension [[!BUNDLE]] in the RTP stream
+ triggering the unhandledrtp event.
dictionary RTCRtpCapabilities
-The RTCRtpCapabilities object expresses the capabilities of RTCRtpSender and RTCRtpReceiver
-objects. Features which are mandatory to implement in [[!RTP-USAGE]], such as RTP/RTCP multiplexing [[!RFC5761]] and
-reduced-size RTCP [[!RFC5506]] are assumed to be available and are therefore not included in RTCRtpCapabilities,
+
+
The RTCRtpCapabilities object expresses the capabilities of RTCRtpSender and
+RTCRtpReceiver objects.
+Features which are mandatory to implement in [[!RTP-USAGE]], such as RTP/RTCP multiplexing [[!RFC5761]]
+and reduced size RTCP [[!RFC5506]] are assumed to be available and are therefore
+not included in RTCRtpCapabilities,
although these features can be set via RTCRtpParameters.
@@ -1681,13 +1998,15 @@ dictionary RTCRtpCapabilities
Supported RTP header extensions.
- sequence<DOMString> fecMechanisms
- Supported FEC mechanisms; valid values include "xor" [[!RFC5109]] and "raptor" [[!RFC6681]].
Supported FEC mechanisms. Currently [[!RTP-USAGE]] makes no recommendations relating to FEC mechanisms.
+
- dictionary RTCRtpFeedback
+ dictionary RTCRtcpFeedback
+ RTCRtcpFeedback provides information on RTCP feedback messages.
- DOMString type
Valid values for type are the "RTCP Feedback" Attribute Values enumerated in [[!IANA-SDP-14]] ("ack", "ccm", "nack", etc.).
dictionary RTCRtpFeedback
dictionary RTCRtpCodecCapability
+ RTCRtpCodecCapability provides information on the capabilities of a codec.
+
+
+
+
- - DOMString name=""
- The MIME media type, if set, empty string otherwise.
- Valid MIME media types are listed in [[!IANA-RTP-2]].
- DOMString name
+ The MIME media type. Valid types are
+ listed in [[!IANA-RTP-2]].
- DOMString kind
The media supported by the codec: "audio", "video" or "" for both.
- unsigned long? clockRate=null
+ - unsigned long clockRate
Codec clock rate expressed in Hertz, null if unset.
- unsigned short preferredPayloadType
+ - payloadtype preferredPayloadType
Added to make it possible for the sender and receiver to pick a
matching payload type when creating sender and receiver parameters.
- unsigned short? numChannels=1
- The number of channels supported (e.g. stereo); one by default.
- For video, this will be null.
- unsigned long numChannels
+ The number of channels supported (e.g. stereo).
+ For video, this will be unset.
- sequence<RTCRtcpFeedback> rtcpFeedback
Transport layer and codec-specific feedback messages for this codec.
- Dictionary parameters
+ Codec-specific parameters that must be signaled to the remote party.
- Dictionary options
Codec-specific parameters available for signaling.
- unsigned short maxTemporalLayers = 0
- Maximum number of temporal layers supported by this codec. A value of 0 indicates no support for temporal scalability.
Maximum number of temporal layer extensions supported by this codec (e.g. a value of 1 indicates support for up to 2 temporal layers). A value of 0 indicates no support for temporal scalability.
- unsigned short maxSpatialLayers = 0
- Maximum number of spatial layers supported by this codec. A value of 0 indicates no support for spatial scalability.
- unsigned short maxQualityLayers = 0
- Maximum number of quality layers supported by this codec. A value of 0 indicates no support for quality scalability.
- boolean? multiStreamSupport=false
- Whether the implementation can send SVC layers utilizing distinct SSRCs. The default is false.
- Only set if the codec supports temporal, spatial or quality scalability.
Maximum number of spatial layer extensions supported by this codec (e.g. a value of 1 indicates support for up to 2 spatial layers). A value of 0 indicates no support for spatial scalability.
- boolean svcMultiStreamSupport
+ Whether the implementation can send SVC layers utilizing distinct SSRCs.
+ Unset for audio codecs. For video codecs, only set if the codec supports scalable video coding with
+ multiple streams.
+
+
+ Codec capability parameters
+
+ The capability parameters for commonly implemented codecs are provided below.
+
+
+ Opus
+ The following capabilities are defined for Opus, as noted in [[!OPUS-RTP]] Section 6.1:
+
+
+
+
+ | Property Name |
+ Values |
+
+ Notes |
+
+
+
+
+ | maxplaybackrate |
+
+
+ unsigned long
+ |
+
+ A hint about the maximum output sampling rate that
+ the receiver is capable of rendering in Hz.
+ |
+
+
+ | stereo |
+
+
+ boolean
+ |
+
+ Specifies whether the decoder prefers receiving stereo (if true) or mono signals (if false).
+ |
+
+
+
+
+
- VP8 formats
+ VP8
- The following properties are defined for VP8, as noted in [[!VP8-RTP]] Section 6.1:
+ The following receiver capabilities are defined for VP8, as noted in [[VP8-RTP]] Section 6.1:
@@ -1748,7 +2119,7 @@ VP8 formats
max-fr |
- long
+ unsigned long
|
This capability indicates the maximum frame rate in frames per second that the decoder is capable of decoding.
@@ -1758,7 +2129,7 @@ VP8 formats
| max-fs |
- long
+ unsigned long long
|
This capability indicates the maximum frame size in macroblocks that the decoder is capable of decoding.
@@ -1766,24 +2137,65 @@ VP8 formats
|
+
+
+
+ H.264
+ The following capabilities are defined for H.264, as noted in [[RFC6184]] Section 8.1, and [[!RTCWEB-VIDEO]].
+
+
+
+
+ | Property Name |
+
+ Values |
+
+ Notes |
+
+
+
+
+ | max-recv-level |
+
+
+ unsigned long
+ |
+
+ Indicates the highest level a receiver supports. |
+
+
+ | packetization-mode |
+
+ sequence<unsigned short> |
+
+A sequence of unsigned shorts, each ranging from 0 to 2, indicating supported packetization-mode values.
+Support for packetization-mode 1 is mandatory in [[!RTCWEB-VIDEO]].
+ |
+
+
+
+
dictionary RTCRtpParameters
+ RTCRtpParameters contains the RTP stack settings.
- - DOMString receiverId=""
- The receiverId assigned to the RTP stream, if any, empty string if unset.
-In an RTCRtpReceiver object, this corresponds to
-recv-appId defined in [[!APPID]]. In an RTCRtpSender object, it corresponds to the appId.
-This is a stable identifier that can be defined and assign to any RTP stream rather than relying on an SSRC.
+
- DOMString muxId=""
+ The muxId assigned to the RTP stream, if any, empty string if unset.
+In an RTCRtpReceiver or RTCRtpSender object, this corresponds to
+MID RTP header extension defined in [[!BUNDLE]].
+This is a stable identifier that permits the track corresponding to an RTP stream to be identified, rather than relying on an SSRC.
An SSRC is randomly generated and can change arbitrarily due to conflicts with other SSRCs, whereas
-the receiverId has a value
+the muxId has a value
whose meaning can be defined in advance between RTP
-sender and receiver, assisting in RTP demultiplexing.
+sender and receiver, assisting in RTP demultiplexing.
+Note that including muxId in RTCRtpParameters rather than in RTCRtpEncodingParameters implies that if it is desired to send simulcast streams with different muxId values for each stream, then multiple
+RTCRtpSender objects are needed.
- sequence<RTCRtpCodecParameters> codecs
- The codecs to send or receive (could include RED, RTX and CN as well).
The codecs to send or receive (could include RED [[RFC2198]], RTX [[!RFC4588]] and CN [[RFC3389]]).
- sequence<RTCRtpHeaderExtensionParameters> headerExtensions
Configured header extensions.
- sequence<RTCRtpEncodingParameters> encodings
@@ -1795,13 +2207,19 @@ dictionary RTCRtpParameters
dictionary RTCRtcpParameters
+ RTCRtcpParameters provides information on RTCP settings.
- unsigned long ssrc
- The SSRC used by RTCP (e.g. in Receiver Reports)t.
- If unset, the SSRC is chosen by the browser.
- Note that the browser may change the SSRC in event of a collision, as described in [[!RFC3550]].
- boolean compound=true
- Whether compound RTCP is configured (if true) or reduced-size RTCP as specified in [[!RFC5506]], if false.
The SSRC to be used in the Receiver Report "SSRC of packet sender" field as defined in [[!RFC3550]] Section 6.4.2.
+ If unset, ssrc is chosen by the browser, and the chosen value is not reflected in RTCRtcpParameters.ssrc.
+ If the browser chooses the ssrc it may change it in event of a collision, as described in [[!RFC3550]].
- DOMString cname
+ The Canonical Name (CNAME) used by RTCP (e.g. in SDES messages). Guidelines for CNAME generation are provided in [[!RTP-USAGE]] Section 4.9.
+ By default, ORTC implementations SHOULD set the CNAME to be the same within all RTCRtcpParameter objects created within the
+ same Javascript sandbox. For backward compatibility with WebRTC 1.0, applications MAY set the CNAME; if unset, the CNAME is chosen by the browser.
- boolean reducedSize=false
+ Whether reduced size RTCP [[!RFC5506]] is configured (if true) or compound RTCP as specified in [[!RFC3550]] (if false).
+ The default is false.
- boolean mux=true
Whether RTP and RTCP are multiplexed, as specified in [[!RFC5761]].
The default is true. If set to false, the
@@ -1815,103 +2233,125 @@
dictionary RTCRtcpParameters
dictionary RTCRtpCodecParameters
+RTCRtpCodecParameters provides information on codec settings.
- - DOMString name=""
- The MIME media type, if set, empty string otherwise.
- Valid MIME media types are listed in [[!IANA-RTP-2]].
- unsigned short payloadType
+ - DOMString name
+ The MIME media type. Valid types are
+ listed in [[!IANA-RTP-2]]. The name MUST always be provided.
+
- payloadtype payloadType
The value that goes in the RTP Payload Type Field [[!RFC3550]]. The payloadType
- must always be provided both within RTCRtpSender and RTCRtpReceiver objects.
- unsigned long? clockRate=null
+ MUST always be provided.
- unsigned long clockRate
Codec clock rate expressed in Hertz, null if unset.
- unsigned short? numChannels=1
- The number of channels supported (e.g. stereo); one by default. For video, this will be null.
- unsigned long numChannels
+ The number of channels supported (e.g. stereo). If unset for audio, use the codec default.
+ For video, this can be left unset.
- sequence<RTCRtcpFeedback> rtcpFeedback
Transport layer and codec-specific feedback messages for this codec.
- Dictionary parameters
Codec-specific parameters available for signaling.
- sequence<DOMString> headerExtensionURIs
- Header extension URIs to configure. If undefined/null, use the ones that
- make sense. Empty set means send no header extensions.
+
+
+ Codec parameters
+
+ The capabilities for commonly implemented codecs described in Section 9.4.2, are also
+ used as codec parameters, with
+ RTCRtpCodecCapability.parameters of the receiver used as
+ RTCRtpCodecParameters.parameters of the sender, and
+ RTCRtpCodecCapability.parameters of the sender used as
+ RTCRtpCodecParameters.parameters of the receiver, with the Property Name
+ and Values unchanged.
+
+
+
dictionary RTCRtpEncodingParameters
- - unsigned long? ssrc=null
- The SSRC for this layering/encoding, null if unset.
- If an SSRC is not present in a receive object, any
- SSRC will match. If an SSRC is not present in a sender object, the browser will choose.
- unsigned short? codecPayloadType=null
+ - unsigned long ssrc
+ The SSRC for this layering/encoding.
+ If ssrc is unset in a RTCRtpEncodingParameters object passed to the RTCRtpReceiver.receive method, the
+ next unhandled SSRC will match, and an RTCRtpUnhandledEvent will not be fired.
+ If ssrc is unset in a RTCRtpEncodingParameters object passed to the RTCRtpSender.send
+ method, the browser will choose, and the chosen value is not reflected in RTCRtpEncodingParameters.ssrc.
+ If the browser chooses the
+ ssrc, it may change it due to a collision without firing an RTCSsrcConflictEvent.
+ If ssrc is set in a RTCRtpEncodingParameters object passed to the RTCRtpSender.send method and an
+ SSRC conflict is detected, then an RTCSsrcConflictEvent is fired (see Section 6.4).
+
- payloadtype codecPayloadType
For per-encoding codec specifications, give the codec Payload Type here.
- If null, the browser will choose.
- RTCRtpFecParameters? fec=null
- Specifies the FEC mechanism if used, null if unset.
- RTCRtpRtxParameters? rtx=null
- Specifies the RTX mechanism if used, null if unset.
- RTCRtpFecParameters fec
+ Specifies the FEC mechanism if set.
- RTCRtpRtxParameters rtx
+ Specifies the RTX [[!RFC4588]] parameters if set.
- double priority=1.0
The higher the value, the more the bits will be given to each as available bandwidth goes up. Default is 1.0.
- This parameter is ignored in scalable video coding.
+ For scalable video coding, this parameter is only relevant for the base layer.
+ This parameter is ignored in an RTCRtpReceiver object.
+ If unset, the default is assumed.
- double? maxBitrate=null
- Ramp up resolution/quality/framerate until this bitrate, null if unset. Summed when using dependent layers.
- This parameter is ignored in scalable video coding, or in an RTCRtpReceiver object.
+
- double maxBitrate
+ Ramp up resolution/quality/framerate until this bitrate, if set. Summed when using dependent layers.
+ This parameter is ignored in scalable video coding, or in an RTCRtpReceiver object.
+ If unset, there is no maximum bitrate.
- double minQuality=0
Never send less than this quality. 1.0 = maximum attainable quality.
- This parameter is ignored in scalable video encoding, or in an RTCRtpReceiver object.
+ For scalable video coding, this parameter is only relevant for the base layer.
+ This parameter is ignored in an RTCRtpReceiver object.
- double framerateBias=0.5
- What to give more bits to, if available, null if unset. 0.0 = strongly favor resolution or 1.0 = strongly favor
- framerate. 0.5 = neither (default). This parameter is ignored in a scalable video encoding,
- or in an RTCRtpReceiver object.
- double resolutionScale=null
- Scale the input resolution, or die trying. 1.0 = full resolution.
- Default is unconstrained (null). For scalable video coding, scale refers to the aggregate scale achieved by this
+
What to give more bits to, if available. 0.0 = strongly favor resolution or 1.0 = strongly favor
+ framerate. 0.5 = neither (default). For scalable video coding, this parameter is only relevant for the base layer.
+ This parameter is ignored in an RTCRtpReceiver object.
+ If unset, the default is assumed.
- double resolutionScale
+ Inverse of the input resolution fraction to be encoded, or die trying. Example: 1.0 = full resolution,
+ 2.0 = one half of the full resolution.
+ For scalable video coding, resolutionScale refers to
+ the inverse aggregate fraction of the input resolution achieved by this
layer when combined with all
dependent layers.
- double framerateScale=null
- Fraction of the input framerate to be encoded. 1.0 = full framerate. Default is unconstrained (null).
- For scalable video coding, framerate refers to the aggregate framerate achieved by this layer
- when combined with all dependent layers.
-
- double qualityScale=null
- Fraction of the input quality to be encoded.
- 1.0 = full quality. Default is unconstrained (null).
- For scalable video coding, quality refers to the aggregate quality achieved by this layer
- when combined with all dependent layers.
+
- double framerateScale
+ Inverse of the input framerate fraction to be encoded. Example: 1.0 = full framerate,
+ 2.0 = one half of the full framerate.
+ For scalable video coding, framerateScale refers to the inverse of the aggregate fraction of input framerate
+ achieved by this layer when combined with all dependent layers.
- boolean active=true
Whether the sender or receiver is active. If false, don't send any media right now.
Disable is different than omitting the encoding; it can keep resources
- available to re-enable more quickly than re-adding. Plus, it still sends RTCP. Default is active.
- DOMString? encodingId
+ available to re-enable more quickly than re-adding. Plus, it still sends RTCP. If unset, the default is assumed.
+ - DOMString encodingId
An identifier for the encoding object. This identifier should be unique within the scope of the
-localized sequence of RTCRtpEncodingParameters for any given RTCRtpParameters object.
-If encodings contained within sequences of other RTCRtpParameters objects are dependent
-upon this encoding identifier, the identifier should be globally unique (unless two or more
-encodings are intentionally referencing the same dependency RTCRtpEncodingParameters such
-as described in [[!RFC5583]] Section 6.5a).
+localized sequence of RTCRtpEncodingParameters for any given RTCRtpParameters object.
- sequence<DOMString> dependencyEncodingIds
- Just the IDs. Within this specification it resolves to encodingIds within the same sequence only.
- In the future if MST were to be supported, then if searching the same sequence did not produce a match, then a global search
+
The encodingIds on which this layer depends.
+ Within this specification encodingIds are permitted only within the same RTCRtpEncodingParameters sequence.
+ In the future if MST were to be supported, then if searching within an
+ RTCRtpEncodingParameters sequence did not produce a match, then a global search
would be carried out.
Examples
-
+
+ Basic Example
//Send a thumbnail along with regular size
-var encodings1 = [{ ssrc: 1, priority: 1.0 }]
+var encodings = [{ ssrc: 1, priority: 1.0 }]
// Control the resolution and framerate with a different track and RtpSender.
-var encodings2 = [{ ssrc: 2,
+var encodings = [{ ssrc: 2,
// Prioritize the thumbnail over the main video.
priority: 10.0 }];
@@ -1938,57 +2378,76 @@ Examples
//Keep the bandwidth low
var encodings = [{ maxBitrate: 100000 }];
-
+
+
+ Temporal Scalability
-Example of 3-layer spatial scalability encoding
+Example of 3-layer temporal scalability encoding
var encodings =[{
+// Base framerate is one quarter of the input framerate
encodingId: "0",
- resolutionScale: 0.25
+ framerateScale: 4.0
}, {
+// Temporal enhancement (half the input framerate when combined with the base layer)
encodingId: "1",
dependencyEncodingIds: ["0"]
- resolutionScale: 0.5
+ framerateScale: 2.0
}, {
+// Another temporal enhancement layer (full input framerate when all layers combined)
encodingId: "2",
dependencyEncodingIds: ["0", "1"]
- resolutionScale: 1.0
+ framerateScale: 1.0
}]
-Example of 3-layer spatial scalability with all but bottom layer disabled
-var encodings1 =[{
+Example of 3-layer temporal scalability with all but the base layer disabled
+var encodings =[{
encodingId: "0",
- resolutionScale: 0.25
+ framerateScale: 4.0
}, {
encodingId: "1",
dependencyEncodingIds: ["0"],
- resolutionScale: 0.5,
+ framerateScale: 2.0,
active: false
}, {
encodingId: "2",
dependencyEncodingIds: ["0", "1"],
- resolutionScale: 1.0,
+ framerateScale: 1.0,
active: false
}];
+
+
+Below is a representation of a 3-layer temporal scalability encoding. In the diagram, I0 is the base layer I-frame,
+and P0 represents base-layer P-frames. P1 represents the first temporal enhancement layer, and P2 represents the
+second temporal enhancement layer.
+
+
+
+
+ Spatial Simulcast
+
Example of 3-layer spatial simulcast
var encodings =[{
+// Simulcast layer at one quarter scale
encodingId: "0",
- resolutionScale: 0.25
+ resolutionScale: 4.0
}, {
+// Simulcast layer at one half scale
encodingId: "1",
- resolutionScale: 0.5
+ resolutionScale: 2.0
}, {
+// Simulcast layer at full scale
encodingId: "2",
resolutionScale: 1.0
}]
-Example of 3-layer spatial simulcast with all but bottom layer disabled
-var encodings1 =[{
+Example of 3-layer spatial simulcast with all but the lowest resolution layer disabled
+var encodings =[{
encodingId: "0",
- resolutionScale: 0.25
+ resolutionScale: 4.0
}, {
encodingId: "1",
- resolutionScale: 0.5,
+ resolutionScale: 2.0,
active: false
}, {
encodingId: "2",
@@ -1998,33 +2457,116 @@ Examples
Example of 2-layer spatial simulcast combined with 2-layer temporal scalability
var encodings =[{
- encodingId: "halfScaleBase",
- resolutionScale: 0.5,
- framerateScale: 0.5
+// Low resolution base layer (half the input framerate, half the input resolution)
+ encodingId: "0",
+ resolutionScale: 2.0,
+ framerateScale: 2.0
}, {
- encodingId: "fullScaleBase",
+// Enhanced resolution Base layer (half the input framerate, full input resolution)
+ encodingId: "E0",
resolutionScale: 1.0,
- framerateScale: 0.5
+ framerateScale: 2.0
}, {
- encodingId: "temporalEnhancemenToHalfScaleBase",
- dependencyEncodingIds: ["halfScaleBase"],
- resolutionScale: 0.5,
+// Temporal enhancement to the low resolution base layer (full input framerate, half resolution)
+ encodingId: "1",
+ dependencyEncodingIds: ["0"],
+ resolutionScale: 2.0,
framerateScale: 1.0
}, {
- encodingId: "temporalEnhancementToFullScaleBase",
- dependencyEncodingIds: ["fullScaleBase"],
+// Temporal enhancement to the enhanced resolution base layer (full input framerate and resolution)
+ encodingId: "E1",
+ dependencyEncodingIds: ["E0"],
resolutionScale: 1.0,
- framerateScale:1.0
+ framerateScale: 1.0
}]
-
+Below is a representation of 2-layer temporal scalability combined with 2-layer spatial simulcast.
+Solid arrows represent temporal prediction.
+In the diagram, I0 is the base-layer I-frame, and P0 represents base-layer P-frames.
+EI0 is an enhanced resolution base-layer I-frame, and EP0 represents P-frames within the enhanced resolution base layer.
+P1 represents the first temporal enhancement layer, and EP1 represents a temporal enhancement to the
+enhanced resolution simulcast base-layer.
+
+
+
+
+ Spatial Scalability
+
+Example of 3-layer spatial scalability encoding
+var encodings =[{
+// Base layer with one quarter input resolution
+ encodingId: "0",
+ resolutionScale: 4.0
+}, {
+// Spatial enhancement layer providing half input resolution when combined with the base layer
+ encodingId: "1",
+ dependencyEncodingIds: ["0"]
+ resolutionScale: 2.0
+}, {
+// Additional spatial enhancement layer providing full input resolution when combined with all layers
+ encodingId: "2",
+ dependencyEncodingIds: ["0", "1"]
+ resolutionScale: 1.0
+}]
+Example of 3-layer spatial scalability with all but the base layer disabled
+var encodings =[{
+ encodingId: "0",
+ resolutionScale: 4.0
+}, {
+ encodingId: "1",
+ dependencyEncodingIds: ["0"],
+ resolutionScale: 2.0,
+ active: false
+}, {
+ encodingId: "2",
+ dependencyEncodingIds: ["0", "1"],
+ resolutionScale: 1.0,
+ active: false
+}];
+
+Example of 2-layer spatial scalability combined with 2-layer temporal scalability
+var encodings =[{
+// Base layer (half input framerate, half resolution)
+ encodingId: "0",
+ resolutionScale: 2.0,
+ framerateScale: 2.0
+}, {
+// Temporal enhancement to the base layer (full input framerate, half resolution)
+ encodingId: "1",
+ dependencyEncodingIds: ["0"],
+ resolutionScale: 2.0,
+ framerateScale: 1.0
+}, {
+// Spatial enhancement to the base layer (half input framerate, full resolution)
+ encodingId: "E0",
+ dependencyEncodingIds: ["0"],
+ resolutionScale: 1.0,
+ framerateScale: 2.0
+}, {
+// Temporal enhancement to the spatial enhancement layer (full input framerate, full resolution)
+ encodingId: "E1",
+ dependencyEncodingIds: ["E0", "1"],
+ resolutionScale: 1.0,
+ framerateScale: 1.0
+}]
+
+Below is a representation of 2-layer temporal scalability combined with 2-layer spatial scalability.
+Solid arrows represent temporal prediction and dashed arrows represent inter-layer prediction.
+In the diagram, I0 is the base-layer I-frame, and EI0 is an intra spatial enhancement.
+P0 represents base-layer P-frames, and P1 represents the first temporal enhancement layer.
+EP0 represents a resolution enhancement to the base-layer P frames, and EP1 represents a resolution enhancement to the
+second temporal layer P-frames.
+
+
+
+
dictionary RTCRtpFecParameters
- - unsigned long? ssrc=null
- The SSRC to use for FEC, null if unset.
- If null in an RTCRtpSender object, the browser will choose.
+
- unsigned long ssrc
+ The SSRC to use for FEC.
+ If unset in an RTCRtpSender object, the browser will choose.
- DOMString mechanism
The Forward Error Correction (FEC) mechanism to use.
dictionary RTCRtpFecParameters
dictionary RTCRtpRtxParameters
- - unsigned long? ssrc=null
- The SSRC to use for RTX, null if unset.
- If null in an RTCRtpSender object, the browser will choose.
+
- unsigned long ssrc
+ The SSRC to use for RTX.
+ If unset in an RTCRtpSender object, the browser will choose.
@@ -2085,17 +2627,18 @@ RTP header extensions
-
- | Transmission Time Offsets |
+
+ | Rapid Synchronization |
- [[!RFC5450]]
+ [[RFC6051]]
|
- This extension indicates when packets are transmitted at a time other than their 'nominal' transmission time.
+ | This extension enables carriage of an NTP-format timestamp, as defined in [[!RFC6051]] Section 3.3.
|
+
| Client-to-Mixer Audio Level |
@@ -2106,22 +2649,23 @@ RTP header extensions
This extension indicates the audio level of the audio sample carried in an RTP packet.
|
-
+
+
| Mixer-to-Client Audio Level |
- [[!RFC6465]]
+ [[RFC6465]]
|
This extension indicates the audio level of individual conference participants.
|
-
- | Application ID |
+
+ | MID |
- [[!APPID]]
+ [[!BUNDLE]]
|
- This extension defines an Application ID which can be used to identify an RTP stream.
+ | This extension defines a track identifier which can be used to identify the track corresponding to an RTP stream.
|
@@ -2137,6 +2681,10 @@ RTP header extensions
The RTCDtmfSender Object
+
+ This section of the ORTC API specification depends on the WebRTC 1.0 DtmfSender API, and needs to be synchronized once it is updated.
+
+
Overview
An RTCDtmfSender instance allows sending DTMF tones to/from the remote peer, as per [[!RFC4733]].
@@ -2391,7 +2939,7 @@ Interface Definition
When an RTCDataChannel object is constructed, 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.
+ See the [[WEBSOCKETS-API]] for more information.
- void close()
Closes the RTCDataChannel.
@@ -2429,13 +2977,13 @@
Interface Definition
- Promise send (DOMString data)
+ - void send (DOMString data)
Run the steps described by the send() algorithm with argument type string object.
- Promise send (Blob data)
+ - void send (Blob data)
Run the steps described by the send() algorithm with argument type Blob object.
- Promise send (ArrayBuffer data)
+ - void send (ArrayBuffer data)
Run the steps described by the send() algorithm with argument type ArrayBuffer object.
- Promise send (ArrayBufferView data)
+ - void send (ArrayBufferView data)
Run the steps described by the send() algorithm with argument type ArrayBufferView object.
Interface Definition
@@ -2475,7 +3023,7 @@ dictionary RTCDataChannelParameters
Not setting any of these properties results in a reliable channel.
- - DOMString? label=""
+ - DOMString label=""
The label attribute represents a label that can be used to distinguish this RTCDataChannel object from other RTCDataChannel objects.
The attribute MUST return the value to which it was set when the RTCDataChannel object was constructed.
For an SCTP data channel, the label is carried in the DATA_CHANNEL_OPEN message defined in
@@ -2487,13 +3035,13 @@
dictionary RTCDataChannelParameters
The attribute MUST return the value to which it was set when the
RTCDataChannel was constructed.
- unsigned short? maxPacketLifetime=null
+ - unsigned short maxPacketLifetime
The maxPacketLifetime
attribute represents the length of the time window (in milliseconds) during which
retransmissions may occur in unreliable mode, or null if unset.
The attribute MUST return the value to which it was set when the
RTCDataChannel was constructed.
- unsigned short? maxRetransmits=null
+ - unsigned short maxRetransmits
The maxRetransmits
attribute returns the maximum number of
retransmissions that are attempted in unreliable mode, or null if unset.
@@ -2501,12 +3049,12 @@
dictionary RTCDataChannelParameters
MUST return the
value to which it was set when the RTCDataChannel was constructed.
- DOMString? protocol=""
+ - DOMString protocol=""
The name of the sub-protocol used with this RTCDataChannel if any,
or the empty string otherwise (in which case the protocol is unspecified).
The attribute MUST return the value to which it was set when the
RTCDataChannel was constucted. Sub-protocols are registered in the
- 'Websocket Subprotocol Name Registry' created in [[!RFC6455]] Section 11.5.
- boolean negotiated=false
The negotiated
attribute returns true if this RTCDataChannel
@@ -2519,7 +3067,7 @@
dictionary RTCDataChannelParameters
If set to false, the remote party will receive an ondatachannel event with
a system constructed RTCDataChannel object.
- unsigned short? id=null
+ - unsigned short id
The id attribute returns the id for this RTCDataChannel, or null if unset.
The id was either assigned by the user agent at channel creation time or was selected by the script.
For SCTP, the id represents a stream identifier, as discussed in [[!DATA]] Section 6.5.
@@ -2577,8 +3125,8 @@
Interface Definition
dictionary RTCSctpCapabilities
- - unsigned short maxMessageSize=null
- Maximum message size or null if unset.
- unsigned short maxMessageSize
+ Maximum message size.
@@ -2673,17 +3221,16 @@ Statistics API
RTCDtlsTransport, RTCIceTransport and
RTCSctpTransport objects.
-
-
+
+ This section of the ORTC API specification depends on the WebRTC 1.0 Statistics API, and needs to be synchronized once it is updated.
+
-
- - void getStats(RTCStatsObject statsObject, RTCStatsCallback
- successCallback, RTCErrorCallback failureCallback)
+
+ - Promise<RTCStatsReport> getStats()
-
Gathers stats for the given object
- and reports the result asynchronously. TODO: Rework this as a Promise.
+ and reports the result asynchronously.
When the
getStats() method is
@@ -2693,7 +3240,7 @@
Statistics API
-
If the object's
- RTCRtpEncodingParameters.active state is false, throw an
+ RTCRtpParameters.RTCRtpEncodingParameters.active state is false, throw an
InvalidStateError exception.
@@ -2708,38 +3255,14 @@ Statistics API
-
-
When the relevant stats have been gathered, queue a task to
- invoke the success callback (the method's second argument) with a
+
When the relevant stats have been gathered, return a
new RTCStatsReport object, representing the
- gathered stats, as its argument.
+ gathered stats.
-
- RTCStatsCallback
-
-
- - RTCStatsReport report
- -
-
A RTCStatsReport representing the gathered
- stats.
-
-
-
-
-
- RTCErrorCallback
-
-
- - DOMError error
- -
-
An error object encapsulating information about what went wrong.
-
-
-
-
RTCStatsReport Object
@@ -2843,10 +3366,6 @@ RTCStats Dictionary
enum RTCStatsType
-
- OPEN ISSUE: Need to synchronize this section with the WebRTC 1.0 Statistics API, once it is updated.
-
-
- inboundrtp
Inbound RTP. Relevant to RTCRtpReceiver objects.
Derived Stats Dictionaries
RTCRtpStreamStats
-
+
- DOMString ssrc
-
@@ -2893,7 +3412,9 @@
RTCRtpStreamStats
- DOMString codecId
- unsigned long firCount
- Count of FIR packets, defined in [[!RFC5104]] Section 4.3.1.
Count of FIR packets, defined in [[!RFC5104]] Section 4.3.1.
+ We are not counting the FIR defined in RFC 2032 Section 5.2.1, which was deprecated in [[RFC4587]].
+
- unsigned long pliCount
Count of PLI packets, defined in [[!RFC4585]] Section 6.3.1.
- unsigned long nackCount
@@ -2905,8 +3426,7 @@ RTCRtpStreamStats
RTCInboundRTPStreamStats
- RTCInboundRTPStreamStats are relevant to RTCRtpReceiver objects.
-
+ RTCInboundRTPStreamStats are relevant to RTCRtpReceiver objects.
- unsigned long packetsReceived
@@ -2925,17 +3445,12 @@ RTCInboundRTPStreamStats
-
Jitter, as calculated in [[!RFC3550]] Section 6.4.1, but given in seconds.
- - double targetBitrate
- -
-
Present bitrate target of this SSRC, in bits per second.
-
RTCOutboundRTPStreamStats
- RTCOutboundRTPStreamStats are relevant to RTCRtpSender objects.
-
+ RTCOutboundRTPStreamStats are relevant to RTCRtpSender objects.
- unsigned long packetsSent
@@ -2946,6 +3461,12 @@ RTCOutboundRTPStreamStats
-
Bytes sent.
+ - double targetBitrate
+ -
+
Presently configured bitrate target of this SSRC, in bits per second.
+ Typically this is a configuration parameter of the codec's encoder.
+
+
- double roundTripTime
-
Estimated round trip time (seconds) based on the RTCP timestamp, as described
@@ -2953,56 +3474,733 @@
RTCOutboundRTPStreamStats
+
+
+ RTCMediaStreamTrackStats
+ RTCMediaStreamTrackStats are relevant to MediaStreamTracks.
+
+ - DOMString trackIdentifier
+ -
+
track.id property
+
+ - boolean remoteSource
+ -
+
+
+ - sequence<DOMString> ssrcIds
+ -
+
SSRCs.
+
+ - unsigned long frameWidth
+ -
+
+
+ - unsigned long frameHeight
+ -
+
+
+ - double framesPerSecond
+ -
+
The nominal FPS value.
+
+ - unsigned long framesSent
+ -
+
+
+ - unsigned long framesReceived
+ -
+
Only makes sense for remoteSource=true.
+
+ - unsigned long framesDecoded
+ -
+
+
+ - unsigned long framesDropped
+ -
+
Same definition as droppedVideoFrames in media-source VideoPlaybackQuality
+
+ - unsigned long framesCorrupted
+ -
+
+
+ - double audioLevel
+ -
+
Values 0..1, linear, with 1.0 = 0dBov as defined in [[!RFC6464]].
+
+ - double echoReturnLoss
+ -
+
As defined in G.168 (2012) Section 3.14, in decibels.
+
+ - double echoReturnLossEnhancement
+ -
+
As above, Section 3.15.
+
+
+
+
+
+ RTCMediaStreamStats
+ RTCMediaStreamStats are relevant to MediaStreams.
+
+
+ - DOMString streamIdentifier
+ -
+
stream.id property
+
+ - sequence<DOMString> trackIds
+ -
+
This is the id of the stats object, not the track.id
+
+
+
+
+
+ RTCDataChannelStats
+ RTCDataChannelStats are relevant to RTCDataChannels.
+
+
+ - DOMString label
+ -
+
+
+ - DOMString protocol
+ -
+
+
+ - long datachannelid
+ -
+
The 'id' attribute of the RTCDataChannel object.
+
+ - RTCDataChannelState state
+ -
+
The state of the RTCDataChannel object.
+
+ - unsigned long long bytesSent
+ -
+
+
+ - unsigned long long bytesReceived
+ -
+
+
+ - unsigned long messagesSent
+ -
+
Number of API 'message' events.
+
+ - unsigned long messagesReceived
+ -
+
+
+
+
+
+
+ RTCTransportStats
+ RTCTransportStats are relevant to RTCDtlsTransport objects.
+
+
+ - unsigned long long bytesSent
+ -
+
+
+ - unsigned long long bytesReceived
+ -
+
+
+ - DOMString rtcpTransportStatsId
+ -
+
If RTP and RTCP are not multiplexed, this is the ID of the transport
+ that gives stats for the RTCP component, and this record has only the RTP component stats.
+
+
+ - boolean activeConnection
+ -
+
+
+ - DOMString selectedCandidatePairId
+ -
+
+
+ - DOMString localCertificateId
+ -
+
+
+ - DOMString remoteCertificateId
+ -
+
+
+
+
+
+
+ enum RTCStatsIceCandidatePairState
+ RTCStatsIceCandidatePairState provides the state of an ICE candidate pair.
+
+ - frozen
+ The candidate pair is frozen.
- waiting
+ The candidate pair is waiting for a connectivity check to go out.
- inprogress
+ A connectivity check is in progress.
- failed
+ The connectivity check has failed.
- succeeded
+ The connectivity check has succeeded.
- cancelled
+ The connectivity check has been cancelled.
+
+
+
+ dictionary RTCIceCandidatePairStats
+ RTCStatsIceCandidatePairStats provides statistics on ICE candidate pairs.
+
+ - DOMString transportId
+ -
+
+
+ - DOMString localCandidateId
+ -
+
+
+ - DOMString remoteCandidateId
+ -
+
+
+ - RTCStatsIceCandidatePairState state
+ -
+
+
+ - unsigned long long priority
+ -
+
+
+ - boolean nominated
+ -
+
+
+ - boolean writable
+ -
+
+
+ - boolean readable
+ -
+
+
+ - unsigned long long bytesSent
+ -
+
+
+ - unsigned long long bytesReceived
+ -
+
+
+ - double roundTripTime
+ -
+
+
+ - double availableOutgoingBitrate
+ -
+
Bits per second, implementation dependent computation.
+
+ - double availableIncomingBitrate
+ -
+
Bits per second, implementation dependent computation.
+
+
+
+
+
+ dictionary RTCCertificateStats
+ RTCCertificateStats provides information on certificates.
+
+ - DOMString fingerprint
+ -
+
As defined in RFC 4572 section 5 - the fingerprint value only
+
+
+ - DOMString fingerprintAlgorithm
+ -
+
For instance 'sha-256'.
+
+ - DOMString base64Certificate
+ -
+
DER-encoded, base-64 representation of the certificate.
+
+ - DOMString issuerCertificateId
+ -
+
+
+
+
+
Example
Consider the case where the user is experiencing bad sound and the application wants to
- determine if the cause of it is packet loss. Assume that receiver is an
- RTCRtpReceiver object. The following example code might be used:
+ determine if the cause of it is packet loss. The following example code might be used:
-var baselineReport, currentReport;
-
-getStats(receiver, function (report) {
- baselineReport = report;
-});
+var mySender = new RTCRtpSender(myTrack);
+var myPreviousReport = null;
// ... wait a bit
setTimeout(function () {
- getStats(receiver, function (report) {
- currentReport = report;
- processStats();
+ mySender.getStats().then(function (report) {
+ processStats(report);
+ myPreviousReport = report;
});
}, aBit);
-function processStats() {
+function processStats(currentReport) {
+ if (myPreviousReport === null) return;
+ // currentReport + myPreviousReport are an RTCStatsReport interface
// compare the elements from the current report with the baseline
- for each (var now in currentReport) {
+ for (var now in currentReport) {
if (now.type != "outbound-rtp")
continue;
-
- // get the corresponding stats from the baseline report
- base = baselineReport[now.id];
-
+ // get the corresponding stats from the previous report
+ base = myPreviousReport[now.id];
+ // base + now will be of RTCRtpStreamStats dictionary type
if (base) {
remoteNow = currentReport[now.remoteId];
- remoteBase = baselineReport[base.remoteId];
-
+ remoteBase = myPreviousReport[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
+ // if fractionLost is > 0.3, we have probably found the culprit
var fractionLost = (packetsSent - packetsReceived) / packetsSent;
}
}
}
-
+
+
+ Identity
+
+
+This section of the ORTC API specification depends on the WebRTC 1.0 Identity API,
+and needs to be synchronized once it is updated.
+
+
+
+ Overview
+
+ An RTCIdentity instance enables authentication of a DTLS transport using a
+ web-based identity provider (IdP).
+The idea is that the initiator acts as the Authenticating Party
+(AP) and obtains an identity assertion from the IdP which is then conveyed in signaling.
+The responder 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, so that 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 Identity Provider API was implemented.
+The generic protocol details are described in [[!RTCWEB-SECURITY-ARCH]].
+This section specifices the procedures required to instantiate the IdP proxy,
+request identity assertions, and consume the results.
+
+
+
+
+
+
+ Identity Provider Selection
+
+ 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:
+
+
+ - If the
getIdentityAssertion() method has been called,
+ the IdP provided shall be used.
+
+ - If the
getIdentityAssertion() 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.
+
+
+
+ Instantiating an IdP Proxy
+
+ 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 required, the browser performs the following
+ steps:
+
+
+ - An invisible, sandboxed IFRAME is created within the browser
+ context. The IFRAME
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).
+
+ - Once the IdP proxy is created, the browser creates a
+
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 RTCIdentity and not some other page. This
+ protection ensures that pages from other origins are unable to
+ instantiate IdP proxies and obtain identity assertions.
+
+ - The IdP proxy completes loading and informs the
+
RTCIdentity object that it is ready by sending a "READY"
+ message to the message channel port [[!RTCWEB-SECURITY-ARCH]]. Once
+ this message is received by the RTCIdentity object, 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 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.
+
+
+
+ Requesting Identity Assertions
+
+ The identity assertion request process involves the following steps:
+
+
+ - The
RTCIdentity instantiates an IdP proxy as
+ described in Identity
+ Provider Selection section and waits
+ for the IdP to signal that it is ready.
+
+ - The IdP sends a "SIGN" message to the IdP proxy. This message
+ includes the material the
+
RTCIdentity object desires to be bound to the user's
+ identity.
+
+ - If the user has been authenticated by the IdP, and the IdP is
+ willing to generate an identity assertion, the IdP generates an identity
+ assertion. This step depends entirely on the IdP. The methods by which
+ an IdP authenticates users or generates assertions is not specified,
+ though this could involve interacting with the IdP server or other
+ servers.
+
+ - The IdP proxy sends a response containing the identity assertion to
+ the
RTCIdentity object over the message channel.
+
+ - The
RTCIdentity object MAY store the identity assertion.
+
+
+
+ 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 getIdentityAssertion Promise MUST
+ be rejected.
+
+ The browser SHOULD limit the time that it will allow for this process.
+ This includes both the loading of
+ the IdP proxy and the
+ identity assertion generation. Failure to do so potentially causes the
+ corresponding operation to take an indefinite amount of time. This timer
+ can be cancelled when the IdP produces a response. The timer running to
+ completion can be treated as equivalent to an error from the IdP.
+
+ NOTE: Where RTP and RTCP are not multiplexed, distinct RTCRtpIceTransport, RTCRtpDtlsTransport
+ and RTCIdentity objects can be constructed for RTP and RTCP.
+ However, while it is possible for getIdentityAssertion()
+ to be called with different values of provider, protocol and username for the RTP and RTCP
+ RTCIdentity objects, application developers desiring backward compatibility with WebRTC 1.0 are strongly
+ discouraged from doing so, since this is likely to result in an error.
+
+
+ User Login Procedure
+
+ 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 RTCIdentityError object.
+ 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.
+
+
+
+
+ Verifying Identity Assertions
+
+ Identity assertion validation happens
+ when setIdentityAssertion()
+ is invoked. The process runs
+ asynchronously.
+
+ The identity assertion validation process involves the following
+ steps:
+
+
+ - The
RTCIdentity instantiates an IdP proxy as
+ described in Identity
+ Provider Selection section and waits
+ for the IdP to signal that it is ready.
+
+ - The IdP sends a "VERIFY" message to the IdP proxy. This message
+ includes the assertion which is to be
+ verified.
+
+ - The IdP proxy verifies the identity assertion (depending on the
+ authentication protocol this could involve interacting with the IDP
+ server).
+
+ - Once the assertion is verified, the IdP proxy sends a response
+ containing the verified assertion results to the
+
RTCIdentity object over the message channel.
+
+ - The
RTCIdentity object 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 done by
+ waiting for the DTLS connection to be established and checking
+ that the certificate fingerprint on the connection matches the one
+ provided by the IdP.
+
+ - The
RTCIdentity validates that the domain portion
+ of the identity matches the domain of the IdP as described in [[!RTCWEB-SECURITY-ARCH]].
+
+ - The
RTCIdentity stores the assertion in the
+ peerIdentity, and returns an RTCIdentityAssertion object
+ when the Promise from setIdentityAssertion() is fulfilled.
+ The assertion
+ information to be displayed MUST contain the domain name of the IdP as
+ provided in the assertion.
+
+ - The browser MAY display identity information to a user in browser
+ UI. Any user identity information that is displayed in this fashion
+ MUST use a mechanism that cannot be spoofed by content.
+
+
+ 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 cause the Promise of setIdentityAssertion() to be rejected if
+ validation of an identity assertion fails for any reason.
+
+ 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]].
+
+ NOTE: Where RTP and RTCP are not multiplexed, it is possible that the assertions for both the RTP and RTCP will be validated,
+ but that the identities will not be equivalent. For applications requiring backward compatibility with WebRTC 1.0,
+ this MUST be considered an error. However, if backward compatibility with WebRTC 1.0 is not required the application MAY consider
+ an alternative, such as ignoring the RTCP identity assertion.
+
+
+
+ RTCIdentity Interface
+ The Identity API is described below.
+
+
+ - readonly attribute RTCIdentityAssertion? peerIdentity
+ -
+
peerIdentity 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.
+
+ - readonly attribute RTCDtlsTransport transport
+ The RTCDtlsTransport to be authenticated.
- Promise<DOMString> getIdentityAssertion (DOMString provider, optional DOMString protocol = "default", optional DOMString username)
+ Sets the identity provider to be used for a given
+ RTCIdentity object, and initiates the process of obtaining an identity assertion.
+
+
+ When getIdentityAssertion() is invoked, the user agent MUST
+ run the following steps:
+
+
+ -
+
If transport.state
+ 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.
+
+ -
+
Request an
+ identity assertion from the IdP.
+
+ -
+
+ If the IdP proxy provides an assertion over the message channel,
+ the Promise is fulfilled, and the assertion is returned (equivalent to onidentityresult in the
+ WebRTC 1.0 API). If the IdP proxy returns an "ERROR" response, the Promise is rejected, and an RTCIdentityError object is returned,
+ (equivalent to onidpassertionerror in the WebRTC 1.0 API).
+
+
+
+ - Promise<RTCIdentityAssertion> setIdentityAssertion (DOMString assertion)
+ Validates the identity assertion. If the Promise is fulfilled,
+ an RTCIdentityAssertion is returned.
+ If the Promise is rejected, an RTCIdentityError object is returned, (equivalent to
+ onidpvalidationerror in the WebRTC 1.0 API).
+
+
+
+
+ dictionary RTCIdentityError
+
+ - DOMString idp
+ -
+
The domain name of the identity provider that is providing the error response.
+
+ - DOMString protocol
+ -
+
The IdP protocol that is in use.
+
+ - DOMString? loginUrl
+ -
+
An IdP that is unable to generate an identity assertion due to a
+ lack of sufficient user authentication information can provide a URL
+ to a page where the user can complete authentication.
+ If the IdP provides this URL, this attribute includes the value provided
+ by the IdP.
+
+
+
+
+
+ dictionary RTCIdentityAssertion
+
+ - DOMString idp
+ -
+
A domain name representing the identity provider.
+
+ - DOMString name
+ -
+
A representation of the verified peer identity conforming to [[RFC5322]].
+ This identity will have been verified via the
+ procedures described in [[!RTCWEB-SECURITY-ARCH]].
+
+
+
+
+
+ Example
+ 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, and consume identity assertions.
+
+
+var iceOptions = ...;
+var ice = new RTCIceTransport(iceOptions);
+var dtls = new RTCDtlsTransport(ice);
+var identity = new RTCIdentity(dtls);
+identity.getIdentityAssertion("example.com", "default", "alice@example.com").then(signalAssertion(assertion)
+ ,function (e) {
+ console.log("Could not obtain an Identity Assertion. idp: ",e.idp,"Protocol: ",e.protocol,"loginUrl: ",e.loginUrl);
+});
+
+function signalAssertion(assertion){
+ mySignalInitiate(
+ { "myAssertion": assertion
+ }, function (response) {
+ identity.setIdentityAssertion(response.myAssertion).then(function (peerAssertion) {
+ console.log("Peer identity assertion validated. idp: ",peerAssertion.idp, "name: ", peerAssertion.name);
+ }, function (e) {
+ console.log("Could not validate peer assertion. idp: ", e.idp, "Protocol: ",e.protocol);
+ });
+ });
+}
+
+