--- 1/draft-ietf-rtcweb-jsep-14.txt 2016-07-07 20:16:08.527085119 -0700 +++ 2/draft-ietf-rtcweb-jsep-15.txt 2016-07-07 20:16:08.695089330 -0700 @@ -1,21 +1,21 @@ Network Working Group J. Uberti Internet-Draft Google Intended status: Standards Track C. Jennings -Expires: September 22, 2016 Cisco +Expires: January 8, 2017 Cisco E. Rescorla, Ed. Mozilla - March 21, 2016 + July 7, 2016 Javascript Session Establishment Protocol - draft-ietf-rtcweb-jsep-14 + draft-ietf-rtcweb-jsep-15 Abstract This document describes the mechanisms for allowing a Javascript application to control the signaling plane of a multimedia session via the interface specified in the W3C RTCPeerConnection API, and discusses how this relates to existing signaling protocols. Status of This Memo @@ -25,21 +25,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on September 22, 2016. + This Internet-Draft will expire on January 8, 2017. Copyright Notice Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -64,80 +64,83 @@ 3.4.2. RtpSenders . . . . . . . . . . . . . . . . . . . . . 11 3.4.3. RtpReceivers . . . . . . . . . . . . . . . . . . . . 11 3.5. ICE . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.5.1. ICE Gathering Overview . . . . . . . . . . . . . . . 11 3.5.2. ICE Candidate Trickling . . . . . . . . . . . . . . . 12 3.5.2.1. ICE Candidate Format . . . . . . . . . . . . . . 12 3.5.3. ICE Candidate Policy . . . . . . . . . . . . . . . . 13 3.5.4. ICE Candidate Pool . . . . . . . . . . . . . . . . . 14 3.6. Video Size Negotiation . . . . . . . . . . . . . . . . . 14 3.6.1. Creating an imageattr Attribute . . . . . . . . . . . 14 - 3.6.2. Interpreting an imageattr Attribute . . . . . . . . . 15 + 3.6.2. Interpreting an imageattr Attribute . . . . . . . . . 16 3.7. Interactions With Forking . . . . . . . . . . . . . . . . 17 3.7.1. Sequential Forking . . . . . . . . . . . . . . . . . 17 3.7.2. Parallel Forking . . . . . . . . . . . . . . . . . . 18 - 4. Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 18 + 4. Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.1. Methods . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.1.1. Constructor . . . . . . . . . . . . . . . . . . . . . 19 - 4.1.2. createOffer . . . . . . . . . . . . . . . . . . . . . 21 - 4.1.3. createAnswer . . . . . . . . . . . . . . . . . . . . 22 - 4.1.4. SessionDescriptionType . . . . . . . . . . . . . . . 22 - 4.1.4.1. Use of Provisional Answers . . . . . . . . . . . 23 - 4.1.4.2. Rollback . . . . . . . . . . . . . . . . . . . . 24 - 4.1.5. setLocalDescription . . . . . . . . . . . . . . . . . 25 - 4.1.6. setRemoteDescription . . . . . . . . . . . . . . . . 25 - 4.1.7. currentLocalDescription . . . . . . . . . . . . . . . 26 - 4.1.8. pendingLocalDescription . . . . . . . . . . . . . . . 26 - 4.1.9. currentRemoteDescription . . . . . . . . . . . . . . 26 - 4.1.10. pendingRemoteDescription . . . . . . . . . . . . . . 26 - 4.1.11. canTrickleIceCandidates . . . . . . . . . . . . . . . 27 - 4.1.12. setConfiguration . . . . . . . . . . . . . . . . . . 27 - 4.1.13. addIceCandidate . . . . . . . . . . . . . . . . . . . 28 - 5. SDP Interaction Procedures . . . . . . . . . . . . . . . . . 28 - 5.1. Requirements Overview . . . . . . . . . . . . . . . . . . 28 + 4.1.2. addTrack . . . . . . . . . . . . . . . . . . . . . . 21 + 4.1.3. addTransceiver . . . . . . . . . . . . . . . . . . . 21 + 4.1.4. createDataChannel . . . . . . . . . . . . . . . . . . 21 + 4.1.5. createOffer . . . . . . . . . . . . . . . . . . . . . 21 + 4.1.6. createAnswer . . . . . . . . . . . . . . . . . . . . 22 + 4.1.7. SessionDescriptionType . . . . . . . . . . . . . . . 23 + 4.1.7.1. Use of Provisional Answers . . . . . . . . . . . 24 + 4.1.7.2. Rollback . . . . . . . . . . . . . . . . . . . . 24 + 4.1.8. setLocalDescription . . . . . . . . . . . . . . . . . 25 + 4.1.9. setRemoteDescription . . . . . . . . . . . . . . . . 26 + 4.1.10. currentLocalDescription . . . . . . . . . . . . . . . 26 + 4.1.11. pendingLocalDescription . . . . . . . . . . . . . . . 27 + 4.1.12. currentRemoteDescription . . . . . . . . . . . . . . 27 + 4.1.13. pendingRemoteDescription . . . . . . . . . . . . . . 27 + 4.1.14. canTrickleIceCandidates . . . . . . . . . . . . . . . 27 + 4.1.15. setConfiguration . . . . . . . . . . . . . . . . . . 28 + 4.1.16. addIceCandidate . . . . . . . . . . . . . . . . . . . 29 + 5. SDP Interaction Procedures . . . . . . . . . . . . . . . . . 29 + 5.1. Requirements Overview . . . . . . . . . . . . . . . . . . 29 5.1.1. Implementation Requirements . . . . . . . . . . . . . 29 - 5.1.2. Usage Requirements . . . . . . . . . . . . . . . . . 30 - 5.1.3. Profile Names and Interoperability . . . . . . . . . 30 - 5.2. Constructing an Offer . . . . . . . . . . . . . . . . . . 31 - 5.2.1. Initial Offers . . . . . . . . . . . . . . . . . . . 31 - 5.2.2. Subsequent Offers . . . . . . . . . . . . . . . . . . 37 - 5.2.3. Options Handling . . . . . . . . . . . . . . . . . . 40 - 5.2.3.1. IceRestart . . . . . . . . . . . . . . . . . . . 40 - 5.2.3.2. VoiceActivityDetection . . . . . . . . . . . . . 40 - 5.2.4. Direction Attribute in Offers . . . . . . . . . . . . 41 - 5.3. Generating an Answer . . . . . . . . . . . . . . . . . . 41 + 5.1.2. Usage Requirements . . . . . . . . . . . . . . . . . 31 + 5.1.3. Profile Names and Interoperability . . . . . . . . . 31 + 5.2. Constructing an Offer . . . . . . . . . . . . . . . . . . 32 + 5.2.1. Initial Offers . . . . . . . . . . . . . . . . . . . 32 + 5.2.2. Subsequent Offers . . . . . . . . . . . . . . . . . . 38 + 5.2.3. Options Handling . . . . . . . . . . . . . . . . . . 41 + 5.2.3.1. IceRestart . . . . . . . . . . . . . . . . . . . 41 + 5.2.3.2. VoiceActivityDetection . . . . . . . . . . . . . 41 + 5.2.4. Direction Attribute in Offers . . . . . . . . . . . . 42 + 5.3. Generating an Answer . . . . . . . . . . . . . . . . . . 42 5.3.1. Initial Answers . . . . . . . . . . . . . . . . . . . 42 - 5.3.2. Subsequent Answers . . . . . . . . . . . . . . . . . 46 - 5.3.3. Options Handling . . . . . . . . . . . . . . . . . . 47 - 5.3.3.1. VoiceActivityDetection . . . . . . . . . . . . . 47 - 5.3.4. Direction Attribute in Answers . . . . . . . . . . . 47 - 5.4. Processing a Local Description . . . . . . . . . . . . . 48 - 5.5. Processing a Remote Description . . . . . . . . . . . . . 48 - 5.6. Parsing a Session Description . . . . . . . . . . . . . . 49 - 5.6.1. Session-Level Parsing . . . . . . . . . . . . . . . . 50 - 5.6.2. Media Section Parsing . . . . . . . . . . . . . . . . 52 - 5.6.3. Semantics Verification . . . . . . . . . . . . . . . 54 - 5.7. Applying a Local Description . . . . . . . . . . . . . . 55 - 5.8. Applying a Remote Description . . . . . . . . . . . . . . 57 - 5.9. Applying an Answer . . . . . . . . . . . . . . . . . . . 59 - 6. Configurable SDP Parameters . . . . . . . . . . . . . . . . . 60 - 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 62 - 7.1. Simple Example . . . . . . . . . . . . . . . . . . . . . 62 - 7.2. Normal Examples . . . . . . . . . . . . . . . . . . . . . 66 - 8. Security Considerations . . . . . . . . . . . . . . . . . . . 75 - 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 75 - 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 75 - 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 76 - 11.1. Normative References . . . . . . . . . . . . . . . . . . 76 - 11.2. Informative References . . . . . . . . . . . . . . . . . 78 - Appendix A. Change log . . . . . . . . . . . . . . . . . . . . . 80 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 85 + 5.3.2. Subsequent Answers . . . . . . . . . . . . . . . . . 47 + 5.3.3. Options Handling . . . . . . . . . . . . . . . . . . 48 + 5.3.3.1. VoiceActivityDetection . . . . . . . . . . . . . 48 + 5.3.4. Direction Attribute in Answers . . . . . . . . . . . 48 + 5.4. Processing a Local Description . . . . . . . . . . . . . 49 + 5.5. Processing a Remote Description . . . . . . . . . . . . . 49 + 5.6. Parsing a Session Description . . . . . . . . . . . . . . 50 + 5.6.1. Session-Level Parsing . . . . . . . . . . . . . . . . 51 + 5.6.2. Media Section Parsing . . . . . . . . . . . . . . . . 53 + 5.6.3. Semantics Verification . . . . . . . . . . . . . . . 55 + 5.7. Applying a Local Description . . . . . . . . . . . . . . 56 + 5.8. Applying a Remote Description . . . . . . . . . . . . . . 58 + 5.9. Applying an Answer . . . . . . . . . . . . . . . . . . . 60 + 6. Configurable SDP Parameters . . . . . . . . . . . . . . . . . 62 + 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 63 + 7.1. Simple Example . . . . . . . . . . . . . . . . . . . . . 63 + 7.2. Normal Examples . . . . . . . . . . . . . . . . . . . . . 67 + 8. Security Considerations . . . . . . . . . . . . . . . . . . . 77 + 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 77 + 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 78 + 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 78 + 11.1. Normative References . . . . . . . . . . . . . . . . . . 78 + 11.2. Informative References . . . . . . . . . . . . . . . . . 81 + Appendix A. Change log . . . . . . . . . . . . . . . . . . . . . 82 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 87 1. Introduction This document describes how the W3C WEBRTC RTCPeerConnection interface[W3C.WD-webrtc-20140617] is used to control the setup, management and teardown of a multimedia session. 1.1. General Design of JSEP The thinking behind WebRTC call setup has been to fully specify and @@ -577,21 +580,21 @@ specific control over the gathering process, due to privacy or related concerns. For example, one may want to suppress the use of host candidates, to avoid exposing information about the local network, or go as far as only using relay candidates, to leak as little location information as possible (note that these choices come with corresponding operational costs). To accomplish this, the browser MUST allow the application to restrict which ICE candidates are used in a session. Note that this filtering is applied on top of any restrictions the browser chooses to enforce regarding which IP addresses are permitted for the application, as discussed in - [I-D.shieh-rtcweb-ip-handling]. + [I-D.ietf-rtcweb-ip-handling]. There may also be cases where the application wants to change which types of candidates are used while the session is active. A prime example is where a callee may initially want to use only relay candidates, to avoid leaking location information to an arbitrary caller, but then change to use all candidates (for lower operational cost) once the user has indicated they want to take the call. For this scenario, the browser MUST allow the candidate policy to be changed in mid-session, subject to the aforementioned interactions with local policy. @@ -679,21 +683,21 @@ The "a=imageattr" field is payload type specific. When all video codecs supported have the same capabilities, use of a single attribute, with the wildcard payload type (*), is RECOMMENDED. However, when the supported video codecs have differing capabilities, specific "a=imageattr" attributes MUST be inserted for each payload type. As an example, consider a system with a HD-capable, multiformat video decoder, where the application has constrained the received track to - at most 360p. In this case, the implemention would generate this + at most 360p. In this case, the implementation would generate this attribute: a=imageattr:* recv [x=[16:640],y=[16:360],q=1.0] This declaration indicates that the receiver is capable of decoding any image resolution from 16x16 up to 640x360 pixels. 3.6.2. Interpreting an imageattr Attribute [RFC6236] defines "a=imageattr" to be an advisory field. This means @@ -889,54 +893,79 @@ The set of available policies is as follows: balanced: The first media section of each type (audio, video, or application) will contain transport parameters, which will allow an answerer to unbundle that section. The second and any subsequent media section of each type will be marked bundle-only. The result is that if there are N distinct media types, then candidates will be gathered for for N media streams. This policy balances desire to multiplex with the need to ensure basic audio - and video can still be negotiated in legacy cases. + and video can still be negotiated in legacy cases. When acting as + answerer, if there is no bundle group in the offer, the + implementation will reject all but the first m= section of each + type. max-compat: All media sections will contain transport parameters; none will be marked as bundle-only. This policy will allow all streams to be received by non-bundle-aware endpoints, but require separate candidates to be gathered for each media stream. max-bundle: Only the first media section will contain transport parameters; all streams other than the first will be marked as bundle-only. This policy aims to minimize candidate gathering and maximize multiplexing, at the cost of less compatibility with - legacy endpoints. + legacy endpoints. When acting as answerer, if there if no bundle + group in the offer, the implementation will reject all but the + first m= section. As it provides the best tradeoff between performance and compatibility with legacy endpoints, the default bundle policy MUST be set to "balanced". The application can specify its preferred policy regarding use of RTP/RTCP multiplexing [RFC5761] using one of the following policies: negotiate: The browser will gather both RTP and RTCP candidates but also will offer "a=rtcp-mux", thus allowing for compatibility with either multiplexing or non-multiplexing endpoints. require: The browser will only gather RTP candidates. This halves the number of candidates that the offerer needs to gather. When - acting as answerer, the browser will reject any m= section that - does not provide an "a=rtcp-mux" attribute. + acting as answerer, the implementation will reject any m= section + that does not contain an "a=rtcp-mux" attribute. The default multiplexing policy MUST be set to "require". Implementations MAY choose to reject attempts by the application to set the multiplexing policy to "negotiate". -4.1.2. createOffer +4.1.2. addTrack + + The addTrack method adds a MediaStreamTrack to the PeerConnection, + using the MediaStream argument to associate the track with other + tracks in the same MediaStream, so that they can be added to the same + "LS" group when creating an offer or answer. addTrack attempts to + minimize the number of transceivers as follows: The track will be + attached to the first compatible transceiver (of the same media type) + which has never had a direction of "sendonly" or "sendrecv". If no + such transceiver exists, then one will be constructed as described in + Section 4.1.3. + +4.1.3. addTransceiver + + [TODO] + +4.1.4. createDataChannel + + [TODO] + +4.1.5. createOffer The createOffer method generates a blob of SDP that contains a [RFC3264] offer with the supported configurations for the session, including descriptions of the media added to this PeerConnection, the codec/RTP/RTCP options supported by this implementation, and any candidates that have been gathered by the ICE Agent. An options parameter may be supplied to provide additional control over the generated offer. This options parameter allows an application to trigger an ICE restart, for the purpose of reestablishing connectivity. @@ -969,21 +998,21 @@ offer that reflects the current state of the system, so that setLocalDescription will succeed when it attempts to acquire those resources. Because this method may need to inspect the system state to determine the currently available resources, it may be implemented as an async operation. Calling this method may do things such as generate new ICE credentials, but does not result in candidate gathering, or cause media to start or stop flowing. -4.1.3. createAnswer +4.1.6. createAnswer The createAnswer method generates a blob of SDP that contains a [RFC3264] SDP answer with the supported configuration for the session that is compatible with the parameters supplied in the most recent call to setRemoteDescription, which MUST have been called prior to calling createAnswer. Like createOffer, the returned blob contains descriptions of the media added to this PeerConnection, the codec/RTP/RTCP options negotiated for this session, and any candidates that have been gathered by the ICE Agent. An options parameter may be supplied to provide additional control over the @@ -1000,21 +1029,21 @@ usable by setLocalDescription; like createOffer, the returned description should reflect the current state of the system. Because this method may need to inspect the system state to determine the currently available resources, it may need to be implemented as an async operation. Calling this method may do things such as generate new ICE credentials, but does not trigger candidate gathering or change media state. -4.1.4. SessionDescriptionType +4.1.7. SessionDescriptionType Session description objects (RTCSessionDescription) may be of type "offer", "pranswer", "answer" or "rollback". These types provide information as to how the description parameter should be parsed, and how the media state should be changed. "offer" indicates that a description should be parsed as an offer; said description may include many possible media configurations. A description used as an "offer" may be applied anytime the PeerConnection is in a stable state, or as an update to a previously @@ -1040,23 +1069,23 @@ provisional or final, and can change the type of the session description as needed. For example, in a serial forking scenario, an application may receive multiple "final" answers, one from each remote endpoint. The application could choose to accept the initial answers as provisional answers, and only apply an answer as final when it receives one that meets its criteria (e.g. a live user instead of voicemail). "rollback" is a special session description type implying that the state machine should be rolled back to the previous state, as - described in Section 4.1.4.2. The contents MUST be empty. + described in Section 4.1.7.2. The contents MUST be empty. -4.1.4.1. Use of Provisional Answers +4.1.7.1. Use of Provisional Answers Most web applications will not need to create answers using the "pranswer" type. While it is good practice to send an immediate response to an "offer", in order to warm up the session transport and prevent media clipping, the preferred handling for a web application would be to create and send an "inactive" final answer immediately after receiving the offer. Later, when the called user actually accepts the call, the application can create a new "sendrecv" offer to update the previous offer/answer pair and start the media flow. While this could also be done with an inactive "pranswer", followed @@ -1074,21 +1103,21 @@ two-way media. By the time the human has accepted the call and triggered the new offer, it is likely that the ICE and DTLS handshaking for all the channels will already have finished. Of course, some applications may not be able to perform this double offer-answer exchange, particularly ones that are attempting to gateway to legacy signaling protocols. In these cases, "pranswer" can still provide the application with a mechanism to warm up the transport. -4.1.4.2. Rollback +4.1.7.2. Rollback In certain situations it may be desirable to "undo" a change made to setLocalDescription or setRemoteDescription. Consider a case where a call is ongoing, and one side wants to change some of the session parameters; that side generates an updated offer and then calls setLocalDescription. However, the remote side, either before or after setRemoteDescription, decides it does not want to accept the new parameters, and sends a reject message back to the offerer. Now, the offerer, and possibly the answerer as well, need to return to a stable state and the previous local/remote description. To support @@ -1118,21 +1147,21 @@ then call setRemoteDescription with an offer, then roll back that offer, then call createOffer and have a m= section for the added track appear in the generated offer. A rollback is performed by supplying a session description of type "rollback" with empty contents to either setLocalDescription or setRemoteDescription, depending on which was most recently used (i.e. if the new offer was supplied to setLocalDescription, the rollback should be done using setLocalDescription as well). -4.1.5. setLocalDescription +4.1.8. setLocalDescription The setLocalDescription method instructs the PeerConnection to apply the supplied session description as its local configuration. The type field indicates whether the description should be processed as an offer, provisional answer, or final answer; offers and answers are checked differently, using the various rules that exist for each SDP line. This API changes the local media state; among other things, it sets up local resources for receiving and decoding media. In order to @@ -1149,80 +1178,80 @@ local description is supplied, and the number of transports currently in use does not match the number of transports needed by the local description, the PeerConnection will create transports as needed and begin gathering candidates for them. If setRemoteDescription was previously called with an offer, and setLocalDescription is called with an answer (provisional or final), and the media directions are compatible, and media are available to send, this will result in the starting of media transmission. -4.1.6. setRemoteDescription +4.1.9. setRemoteDescription The setRemoteDescription method instructs the PeerConnection to apply the supplied session description as the desired remote configuration. As in setLocalDescription, the type field of the description indicates how it should be processed. This API changes the local media state; among other things, it sets up local resources for sending and encoding media. If setLocalDescription was previously called with an offer, and setRemoteDescription is called with an answer (provisional or final), and the media directions are compatible, and media are available to send, this will result in the starting of media transmission. -4.1.7. currentLocalDescription +4.1.10. currentLocalDescription The currentLocalDescription method returns a copy of the current negotiated local description - i.e., the local description from the last successful offer/answer exchange - in addition to any local candidates that have been generated by the ICE Agent since the local description was set. A null object will be returned if an offer/answer exchange has not yet been completed. -4.1.8. pendingLocalDescription +4.1.11. pendingLocalDescription The pendingLocalDescription method returns a copy of the local description currently in negotiation - i.e., a local offer set without any corresponding remote answer - in addition to any local candidates that have been generated by the ICE Agent since the local description was set. A null object will be returned if the state of the PeerConnection is "stable" or "have-remote-offer". -4.1.9. currentRemoteDescription +4.1.12. currentRemoteDescription The currentRemoteDescription method returns a copy of the current negotiated remote description - i.e., the remote description from the last successful offer/answer exchange - in addition to any remote candidates that have been supplied via processIceMessage since the remote description was set. A null object will be returned if an offer/answer exchange has not yet been completed. -4.1.10. pendingRemoteDescription +4.1.13. pendingRemoteDescription The pendingRemoteDescription method returns a copy of the remote description currently in negotiation - i.e., a remote offer set without any corresponding local answer - in addition to any remote candidates that have been supplied via processIceMessage since the remote description was set. A null object will be returned if the state of the PeerConnection is "stable" or "have-local-offer". -4.1.11. canTrickleIceCandidates +4.1.14. canTrickleIceCandidates The canTrickleIceCandidates property indicates whether the remote side supports receiving trickled candidates. There are three potential values: null: No SDP has been received from the other side, so it is not known if it can handle trickle. This is the initial value before setRemoteDescription() is called. true: SDP has been received from the other side indicating that it @@ -1236,21 +1265,21 @@ needed for Trickle ICE. However, applications can use the canTrickleIceCandidates property to determine whether their peer can actually do Trickle ICE, i.e., whether it is safe to send an initial offer or answer followed later by candidates as they are gathered. As "true" is the only value that definitively indicates remote Trickle ICE support, an application which compares canTrickleIceCandidates against "true" will by default attempt Half Trickle on initial offers and Full Trickle on subsequent interactions with a Trickle ICE-compatible agent. -4.1.12. setConfiguration +4.1.15. setConfiguration The setConfiguration method allows the global configuration of the PeerConnection, which was initially set by constructor parameters, to be changed during the session. The effects of this method call depend on when it is invoked, and differ depending on which specific parameters are changed: o Any changes to the STUN/TURN servers to use affect the next gathering phase. If an ICE gathering phase has already started or completed, the 'needs-ice-restart' bit mentioned in Section 3.5.1 @@ -1273,26 +1302,28 @@ immediately; if increased, additional candidates are pre-gathered; if decreased, the now-superfluous candidates are discarded. o The bundle and RTCP-multiplexing policies MUST NOT be changed after the construction of the PeerConnection. This call may result in a change to the state of the ICE Agent, and may result in a change to media state if it results in connectivity being established. -4.1.13. addIceCandidate +4.1.16. addIceCandidate The addIceCandidate method provides a remote candidate to the ICE Agent, which, if parsed successfully, will be added to the current and/or pending remote description according to the rules defined for - Trickle ICE. Connectivity checks will be sent to the new candidate. + Trickle ICE. If the MID, m-line index, or candidate string provided + in the ICE candidate is invalid, an error is generated. Connectivity + checks will be sent to the new candidate. This method can also be used to provide an end-of-candidates indication (as defined in [I-D.ietf-ice-trickle]) to the ICE Agent for all media descriptions in the last remote description. This call will result in a change to the state of the ICE Agent, and may result in a change to media state if it results in connectivity being established. 5. SDP Interaction Procedures @@ -1519,22 +1550,22 @@ followed: o The port value is set to the port of the default ICE candidate for this m= section, but given that no candidates have yet been gathered, the "dummy" port value of 9 (Discard) MUST be used, as indicated in [I-D.ietf-ice-trickle], Section 5.1. o To properly indicate use of DTLS, the field MUST be set to "UDP/TLS/RTP/SAVPF", as specified in [RFC5764], Section 8, if the default candidate uses UDP transport, or "TCP/DTLS/RTP/SAVPF", as - specified in[I-D.nandakumar-mmusic-proto-iana-registration] if the - default candidate uses TCP transport. + specified in [I-D.nandakumar-mmusic-proto-iana-registration] if + the default candidate uses TCP transport. The m= line MUST be followed immediately by a "c=" line, as specified in [RFC4566], Section 5.7. Again, as no candidates have yet been gathered, the "c=" line must contain the "dummy" value "IN IP4 0.0.0.0", as defined in [I-D.ietf-ice-trickle], Section 5.1. Each m= section MUST include the following attribute lines: o An "a=mid" line, as specified in [RFC5888], Section 4. When generating mid values, it is RECOMMENDED that the values be 3 @@ -1544,22 +1575,23 @@ o An "a=rtcp" line, as specified in [RFC3605], Section 2.1, containing the dummy value "9 IN IP4 0.0.0.0", because no candidates have yet been gathered. o A direction attribute for the associated RtpTransceiver as described by Section 5.2.4. o For each supported codec, "a=rtpmap" and "a=fmtp" lines, as specified in [RFC4566], Section 6. The audio and video codecs - that MUST be supported are specified in [I-D.ietf-rtcweb-audio] - (see Section 3) and [I-D.ietf-rtcweb-video] (see Section 5). + that MUST be supported are specified in + [I-D.ietf-rtcweb-audio](see Section 3) and + [I-D.ietf-rtcweb-video](see Section 5). o If this m= section is for media with configurable frame sizes, e.g. audio, an "a=maxptime" line, indicating the smallest of the maximum supported frame sizes out of all codecs included above, as specified in [RFC4566], Section 6. o If this m= section is for video media, and there are known limitations on the size of images which can be decoded, an "a=imageattr" line, as specified in Section 3.6. @@ -1830,33 +1863,33 @@ setRemoteDescription, meaning the PeerConnection is in the "remote- pranswer" or "stable" states, an offer is generated based on the negotiated session descriptions by following the steps mentioned for the "local-offer" state above. In addition, for each non-recycled, non-rejected m= section in the new offer, the following adjustments are made based on the contents of the corresponding m= section in the current remote description: o The m= line and corresponding "a=rtpmap" and "a=fmtp" lines MUST - only include codecs present in the remote description. + only include codecs present in the most recent answer. o The RTP header extensions MUST only include those that are present - in the remote description. + in the most recent answer. o The RTCP feedback extensions MUST only include those that are - present in the remote description. + present in the most recent answer. - o The "a=rtcp-mux" line MUST only be added if present in the remote - description. + o The "a=rtcp-mux" line MUST only be added if present in the most + recent answer. - o The "a=rtcp-rsize" line MUST only be added if present in the - remote description. + o The "a=rtcp-rsize" line MUST only be added if present in the most + recent answer. The "a=group:BUNDLE" attribute MUST include the mid identifiers specified in the bundle group in the most recent answer, minus any m= sections that have been marked as rejected, plus any newly added or re-enabled m= sections. In other words, the bundle attribute must contain all m= sections that were previously bundled, as long as they are still alive, as well as any new m= sections. The "LS" groups are generated in the same way as with initial offers. @@ -1948,51 +1981,65 @@ error, and MUST cause the affected m= sections to be marked as rejected. The first step in generating an initial answer is to generate session-level attributes. The process here is identical to that indicated in the Initial Offers section above, except that the "a=ice-options" line, with the "trickle" option as specified in [I-D.ietf-ice-trickle], Section 4, is only included if such an option was present in the offer. - The next step is to generate lip sync groups as defined in [RFC5888], - Section 7. For each MediaStream with more than one referenced - RtpTransceiver, a group of type "LS" MUST be added that contains the - mid values for each RtpTransceiver added with that MediaStream. In - some cases this may result in adding a mid to a given LS group that - was not in that LS group in the associated offer. Although this is - not allowed by [RFC5888], it is allowed when implementing this - specification. [[OPEN ISSUE: This is still under discussion. See: - https://github.com/rtcweb-wg/jsep/issues/162.]] + The next step is to generate session-level lip sync groups as defined + in [RFC5888], Section 7. For each group of type "LS" present in the + offer, determine which of the local RtpTransceivers identified by + that group's mid values reference a common local MediaStream (as + specified in the addTrack and addTransceiver methods). If at least + two such RtpTransceivers exist, a group of type "LS" with the mid + values of these RtpTransceivers MUST be added. Otherwise, this + indicates a difference of opinion between the offerer and answerer + regarding lip sync status, and as such, the offered group MUST be + ignored and no corresponding "LS" group generated. The next step is to generate m= sections for each m= section that is present in the remote offer, as specified in [RFC3264], Section 6. For the purposes of this discussion, any session-level attributes in the offer that are also valid as media-level attributes SHALL be considered to be present in each m= section. The next step is to go through each offered m= section. Each offered m= section will have an associated RtpTransceiver, as described in Section 5.8. If there are more RtpTransceivers than there are m= sections, the unmatched RtpTransceivers will need to be associated in a subsequent offer. - For each offered m= section, if the associated RtpTransceiver has - been stopped, the corresponding m= section in the answer MUST be - marked as rejected by setting the port in the m= line to zero, as - indicated in [RFC3264], Section 6., and further processing for this - m= section can be skipped. + For each offered m= section, if any of the following conditions are + true, the corresponding m= section in the answer MUST be marked as + rejected by setting the port in the m= line to zero, as indicated in + [RFC3264], Section 6., and further processing for this m= section can + be skipped: - Provided that is not the case, each m= section in the answer should - then be generated as specified in [RFC3264], Section 6.1. For the m= - line itself, the following rules must be followed: + o The associated RtpTransceiver has been stopped. + + o No supported codec is present in the offer. + + o The bundle policy is "max-bundle", the m= section is not in a + bundle group, and this is not the first m= section. + + o The bundle policy is "balanced", the m= section is not in a bundle + group, and this is not the first m= section for this media type. + + o The RTP/RTCP multiplexing policy is "require" and the m= section + doesn't contain an "a=rtcp-mux" attribute. + + Otherwise, each m= section in the answer should then be generated as + specified in [RFC3264], Section 6.1. For the m= line itself, the + following rules must be followed: o The port value would normally be set to the port of the default ICE candidate for this m= section, but given that no candidates have yet been gathered, the "dummy" port value of 9 (Discard) MUST be used, as indicated in [I-D.ietf-ice-trickle], Section 5.1. o The field MUST be set to exactly match the field for the corresponding m= line in the offer. The m= line MUST be followed immediately by a "c=" line, as specified @@ -2285,23 +2332,23 @@ described in [RFC4566], Section 5. The SDP is read, line-by-line, and converted to a data structure that contains the deserialized information. However, SDP allows many types of lines, not all of which are relevant to JSEP applications. For each line, the implementation will first ensure it is syntactically correct according its defining ABNF, check that it conforms to [RFC4566] and [RFC3264] semantics, and then either parse and store or discard the provided value, as described below. A partial list of ABNF definitions for SDP attributes can found in: - +---------------------------+------------------------------------+ + +-------------------------+----------------------------------+ | Attribute | Reference | - +---------------------------+------------------------------------+ + +-------------------------+----------------------------------+ | ptime | [RFC4566] Section 9 | | maxptime | [RFC4566] Section 9 | | rtpmap | [RFC4566] Section 9 | | recvonly | [RFC4566] Section 9 | | sendrecv | [RFC4566] Section 9 | | sendonly | [RFC4566] Section 9 | | inactive | [RFC4566] Section 9 | | framerate | [RFC4566] Section 9 | | fmtp | [RFC4566] Section 9 | | quality | [RFC4566] Section 9 | @@ -2310,21 +2357,21 @@ | setup | [RFC4145] Section 3, 4, and 5 | | connection | [RFC4145] Section 3, 4, and 5 | | fingerprint | [RFC4572] Section 5 | | rtcp-fb | [RFC4585] Section 4.2 | | candidate | [RFC5245] Section 15 | | extmap | [RFC5285] Section 7 | | mid | [RFC5888] Section 4 and 5 | | group | [RFC5888] Section 4 and 5 | | imageattr | [RFC6236] Section 3.1 | | extmap (encrypt option) | [RFC6904] Section 4 | - +---------------------------+------------------------------------+ + +-------------------------+----------------------------------+ Table 1: SDP ABNF References [TODO: ensure that every line is listed below.] If the line is not well-formed, or cannot be parsed as described, the parser MUST stop with an error and reject the session description. This ensures that implementations do not accidentally misinterpret ambiguous SDP. @@ -2387,22 +2434,22 @@ o Any "a=fingerprint" lines are parsed as specified in [RFC4572], Section 5, and the set of fingerprint and algorithm values is stored. o If present, a single "a=setup" line is parsed as specified in [RFC4145], Section 4, and the setup value is stored. o Any "a=extmap" lines are parsed as specified in [RFC5285], Section 5, and their values are stored. - o TODO: identity, rtcp-rsize, rtcp-mux, and any other attribs valid - at session level. + o TODO: identity, rtcp-rsize, rtcp-mux, and any other attributes + valid at session level. Once all the session-level lines have been parsed, processing continues with the lines in media sections. 5.6.2. Media Section Parsing Like the session-level lines, the media session lines MUST occur in the specific order and with the specific syntax defined in [RFC4566], Section 5. @@ -2433,21 +2480,21 @@ in [RFC5245], Section 15.5, and the set of specified options is stored. o Any "a=fingerprint" lines are parsed as specified in [RFC4572], Section 5, and the set of fingerprint and algorithm values is stored. o If present, a single "a=setup" line is parsed as specified in [RFC4145], Section 4, and the setup value is stored. - If the "m=" proto value indicates use of RTP, as decribed in the + If the "m=" proto value indicates use of RTP, as described in the Section 5.1.3 section above, the following attribute lines MUST be processed: o The "m=" fmt value MUST be parsed as specified in [RFC4566], Section 5.14, and the individual values stored. o Any "a=rtpmap" or "a=fmtp" lines MUST be parsed as specified in [RFC4566], Section 6, and their values stored. o If present, a single "a=ptime" line MUST be parsed as described in @@ -2606,23 +2653,23 @@ * For each specified RTP header extension, establish a mapping between the extension ID and URI, as described in section 6 of [RFC5285]. If any indicated RTP header extension is unknown, this MUST result in an error. * If the MID header extension is supported, prepare to demux RTP data intended for this media section based on the MID header extension, as described in [I-D.ietf-mmusic-msid], Section 3.2. * For each specified payload type, establish a mapping between - the payload type ID and the actual media format, as descibed in - [RFC3264]. If any indicated payload type is unknown, this MUST - result in an error. + the payload type ID and the actual media format, as described + in [RFC3264]. If any indicated payload type is unknown, this + MUST result in an error. * For each specified "rtx" media format, establish a mapping between the RTX payload type and its associated primary payload type, as described in [RFC4588], Sections 8.6 and 8.7. If any referenced primary payload types are not present, this MUST result in an error. * If the directional attribute is of type "sendrecv" or "recvonly", enable receipt and decoding of media. @@ -2721,25 +2768,26 @@ * For each specified RTCP feedback mechanism that is supported by the local implementation, enable them on the associated payload types. * For any specified "TIAS" bandwidth value, set this value as a constraint on the maximum RTP bitrate to be used when sending media, as specified in [RFC3890]. If a "TIAS" value is not present, but an "AS" value is specified, generate a "TIAS" value using this formula: - TIAS = AS * 0.95 - 50 * 40 * 8 + TIAS = AS * 1000 * 0.95 - 50 * 40 * 8 The 50 is based on 50 packets per second, the 40 is based on an - estimate of total header size, and the 0.95 is to allocate 5% - to RTCP. If more accurate control of bandwidth is needed, + estimate of total header size, the 1000 changes the unit from + kbps to bps (as required by TIAS), and the 0.95 is to allocate + 5% to RTCP. If more accurate control of bandwidth is needed, "TIAS" should be used instead of "AS". * For any "RR" or "RS" bandwidth values, handle as specified in [RFC3556], Section 2. * Any specified "CT" bandwidth value MUST be ignored, as the meaning of this construct at the media level is not well defined. * [TODO: handling of CN, telephone-event, "red"] @@ -2907,21 +2955,21 @@ The flow shows Alice's browser initiating the session to Bob's browser. The messages from Alice's JS to Bob's JS are assumed to flow over some signaling protocol via a web server. The JS on both Alice's side and Bob's side waits for all candidates before sending the offer or answer, so the offers and answers are complete. Trickle ICE is not used. Both Alice and Bob are using the default policy of balanced. // set up local media state AliceJS->AliceUA: create new PeerConnection -AliceJS->AliceUA: addTrack with two tracks: one for audio and one for video +AliceJS->AliceUA: addTrack with two tracks: audio and video AliceJS->AliceUA: createOffer to get offer AliceJS->AliceUA: setLocalDescription with offer AliceUA->AliceJS: multiple onicecandidate events with candidates // wait for ICE gathering to complete AliceUA->AliceJS: onicecandidate event with null candidate AliceJS->AliceUA: get |offer-A1| from pendingLocalDescription // |offer-A1| is sent over signaling protocol to Bob AliceJS->WebServer: signaling with |offer-A1| @@ -3508,48 +3555,64 @@ Significant text incorporated in the draft as well and review was provided by Peter Thatcher, Taylor Brandstetter, Harald Alvestrand and Suhas Nandakumar. Dan Burnett, Neil Stratford, Anant Narayanan, Andrew Hutton, Richard Ejzak, Adam Bergkvist and Matthew Kaufman all provided valuable feedback on this proposal. 11. References 11.1. Normative References + [I-D.ietf-avtext-rid] + Roach, A., Nandakumar, S., and P. Thatcher, "RTP Stream + Identifier (RID) Source Description (SDES)", draft-ietf- + avtext-rid-00 (work in progress), February 2016. + [I-D.ietf-ice-trickle] Ivov, E., Rescorla, E., Uberti, J., and P. Saint-Andre, "Trickle ICE: Incremental Provisioning of Candidates for the Interactive Connectivity Establishment (ICE) Protocol". [I-D.ietf-mmusic-msid] Alvestrand, H., "Cross Session Stream Identification in the Session Description Protocol", draft-ietf-mmusic- msid-01 (work in progress), August 2013. + [I-D.ietf-mmusic-rid] + Thatcher, P., Zanaty, M., Nandakumar, S., Burman, B., + Roach, A., and B. Campen, "RTP Payload Format + Constraints", draft-ietf-mmusic-rid-04 (work in progress), + February 2016. + [I-D.ietf-mmusic-sctp-sdp] Loreto, S. and G. Camarillo, "Stream Control Transmission Protocol (SCTP)-Based Media Transport in the Session Description Protocol (SDP)", draft-ietf-mmusic-sctp-sdp-04 (work in progress), June 2013. [I-D.ietf-mmusic-sdp-bundle-negotiation] Holmberg, C., Alvestrand, H., and C. Jennings, "Multiplexing Negotiation Using Session Description Protocol (SDP) Port Numbers", draft-ietf-mmusic-sdp- bundle-negotiation-04 (work in progress), June 2013. [I-D.ietf-mmusic-sdp-mux-attributes] Nandakumar, S., "A Framework for SDP Attributes when Multiplexing", draft-ietf-mmusic-sdp-mux-attributes-01 (work in progress), February 2014. + [I-D.ietf-mmusic-sdp-simulcast] + Burman, B., Westerlund, M., Nandakumar, S., and M. Zanaty, + "Using Simulcast in SDP and RTP Sessions", draft-ietf- + mmusic-sdp-simulcast-04 (work in progress), February 2016. + [I-D.ietf-rtcweb-audio] Valin, J. and C. Bran, "WebRTC Audio Codec and Processing Requirements", draft-ietf-rtcweb-audio-02 (work in progress), August 2013. [I-D.ietf-rtcweb-fec] Uberti, J., "WebRTC Forward Error Correction Requirements", draft-ietf-rtcweb-fec-00 (work in progress), February 2015. @@ -3638,46 +3701,30 @@ [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer Security Version 1.2", RFC 6347, January 2012. [RFC6904] Lennox, J., "Encryption of Header Extensions in the Secure Real-time Transport Protocol (SRTP)", RFC 6904, April 2013. 11.2. Informative References - [I-D.ietf-avtext-rid] - Roach, A., Nandakumar, S., and P. Thatcher, "RTP Stream - Identifier (RID) Source Description (SDES)", draft-ietf- - avtext-rid-00 (work in progress), February 2016. - - [I-D.ietf-mmusic-rid] - Thatcher, P., Zanaty, M., Nandakumar, S., Burman, B., - Roach, A., and B. Campen, "RTP Payload Format - Constraints", draft-ietf-mmusic-rid-04 (work in progress), - February 2016. - - [I-D.ietf-mmusic-sdp-simulcast] - Burman, B., Westerlund, M., Nandakumar, S., and M. Zanaty, - "Using Simulcast in SDP and RTP Sessions", draft-ietf- - mmusic-sdp-simulcast-04 (work in progress), February 2016. + [I-D.ietf-rtcweb-ip-handling] + Uberti, J. and G. Shieh, "WebRTC IP Address Handling + Recommendations", draft-ietf-rtcweb-ip-handling-01 (work + in progress), March 2016. [I-D.nandakumar-rtcweb-sdp] Nandakumar, S. and C. Jennings, "SDP for the WebRTC", draft-nandakumar-rtcweb-sdp-02 (work in progress), July 2013. - [I-D.shieh-rtcweb-ip-handling] - Shieh, G. and J. Uberti, "WebRTC IP Address Handling - Recommendations", draft-shieh-rtcweb-ip-handling-00 (work - in progress), October 2015. - [RFC3389] Zopf, R., "Real-time Transport Protocol (RTP) Payload for Comfort Noise (CN)", RFC 3389, September 2002. [RFC3556] Casner, S., "Session Description Protocol (SDP) Bandwidth Modifiers for RTP Control Protocol (RTCP) Bandwidth", RFC 3556, July 2003. [RFC3960] Camarillo, G. and H. Schulzrinne, "Early Media and Ringing Tone Generation in the Session Initiation Protocol (SIP)", RFC 3960, December 2004. @@ -3721,36 +3768,55 @@ Bergkvist, A., Burnett, D., Narayanan, A., and C. Jennings, "WebRTC 1.0: Real-time Communication Between Browsers", World Wide Web Consortium WD WD-webrtc- 20140617, June 2014, . Appendix A. Change log Note: This section will be removed by RFC Editor before publication. + Changes in draft-15: + + o Clarify text around codecs offered in subsequent transactions to + refer to what's been negotiated. + + o Rewrite LS handling text to indicate edge cases and that we're + living with them. + + o Require that answerer reject m= lines when there are no codecs in + common. + + o Enforce max-bundle on offer processing. + + o Fix TIAS formula to handle bits vs. kilobits. + + o Describe addTrack algorithm. + + o Clean up references. + Changes in draft-14: o Added discussion of RtpTransceivers + RtpSenders + RtpReceivers, and how they interact with createOffer/createAnswer. o Removed obsolete OfferToReceiveX options. o Explained how addIceCandidate can be used for end-of-candidates. Changes in draft-13: o Clarified which SDP lines can be ignored. o Clarified how to handle various received attributes. - o Revised how atttributes should be generated for bundled m= lines. + o Revised how attributes should be generated for bundled m= lines. o Remove unused references. o Remove text advocating use of unilateral PTs. o Trigger an ICE restart even if the ICE candidate policy is being made more strict. o Remove the 'public' ICE candidate policy.