idnits 2.17.1 draft-ietf-rtcweb-jsep-21.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 3736 has weird spacing: '... mid a1...' == Line 3737 has weird spacing: '... attr candi...' == Line 3743 has weird spacing: '... mid a1...' == Line 3744 has weird spacing: '... attr candi...' == Line 3751 has weird spacing: '... mid a1...' == (11 more instances...) -- The document date (July 3, 2017) is 2483 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-21) exists of draft-ietf-ice-trickle-12 == Outdated reference: A later version (-32) exists of draft-ietf-mmusic-dtls-sdp-26 == Outdated reference: A later version (-17) exists of draft-ietf-mmusic-msid-16 == Outdated reference: A later version (-15) exists of draft-ietf-mmusic-rid-10 == Outdated reference: A later version (-54) exists of draft-ietf-mmusic-sdp-bundle-negotiation-38 == Outdated reference: A later version (-19) exists of draft-ietf-mmusic-sdp-mux-attributes-16 == Outdated reference: A later version (-14) exists of draft-ietf-mmusic-sdp-simulcast-08 == Outdated reference: A later version (-10) exists of draft-ietf-rtcweb-fec-05 == Outdated reference: A later version (-12) exists of draft-ietf-rtcweb-security-08 == Outdated reference: A later version (-20) exists of draft-ietf-rtcweb-security-arch-12 ** Obsolete normative reference: RFC 4566 (Obsoleted by RFC 8866) ** Obsolete normative reference: RFC 5245 (Obsoleted by RFC 8445, RFC 8839) ** Obsolete normative reference: RFC 5285 (Obsoleted by RFC 8285) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) == Outdated reference: A later version (-18) exists of draft-ietf-mmusic-trickle-ice-sip-07 == Outdated reference: A later version (-12) exists of draft-ietf-rtcweb-ip-handling-03 == Outdated reference: A later version (-14) exists of draft-ietf-rtcweb-sdp-06 Summary: 4 errors (**), 0 flaws (~~), 20 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Uberti 3 Internet-Draft Google 4 Intended status: Standards Track C. Jennings 5 Expires: January 4, 2018 Cisco 6 E. Rescorla, Ed. 7 Mozilla 8 July 3, 2017 10 JavaScript Session Establishment Protocol 11 draft-ietf-rtcweb-jsep-21 13 Abstract 15 This document describes the mechanisms for allowing a JavaScript 16 application to control the signaling plane of a multimedia session 17 via the interface specified in the W3C RTCPeerConnection API, and 18 discusses how this relates to existing signaling protocols. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on January 4, 2018. 37 Copyright Notice 39 Copyright (c) 2017 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 55 1.1. General Design of JSEP . . . . . . . . . . . . . . . . . 4 56 1.2. Other Approaches Considered . . . . . . . . . . . . . . . 6 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 58 3. Semantics and Syntax . . . . . . . . . . . . . . . . . . . . 7 59 3.1. Signaling Model . . . . . . . . . . . . . . . . . . . . . 7 60 3.2. Session Descriptions and State Machine . . . . . . . . . 7 61 3.3. Session Description Format . . . . . . . . . . . . . . . 11 62 3.4. Session Description Control . . . . . . . . . . . . . . . 11 63 3.4.1. RtpTransceivers . . . . . . . . . . . . . . . . . . . 11 64 3.4.2. RtpSenders . . . . . . . . . . . . . . . . . . . . . 12 65 3.4.3. RtpReceivers . . . . . . . . . . . . . . . . . . . . 12 66 3.5. ICE . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 67 3.5.1. ICE Gathering Overview . . . . . . . . . . . . . . . 12 68 3.5.2. ICE Candidate Trickling . . . . . . . . . . . . . . . 13 69 3.5.2.1. ICE Candidate Format . . . . . . . . . . . . . . 13 70 3.5.3. ICE Candidate Policy . . . . . . . . . . . . . . . . 14 71 3.5.4. ICE Candidate Pool . . . . . . . . . . . . . . . . . 15 72 3.6. Video Size Negotiation . . . . . . . . . . . . . . . . . 16 73 3.6.1. Creating an imageattr Attribute . . . . . . . . . . . 16 74 3.6.2. Interpreting an imageattr Attribute . . . . . . . . . 17 75 3.7. Simulcast . . . . . . . . . . . . . . . . . . . . . . . . 18 76 3.8. Interactions With Forking . . . . . . . . . . . . . . . . 19 77 3.8.1. Sequential Forking . . . . . . . . . . . . . . . . . 20 78 3.8.2. Parallel Forking . . . . . . . . . . . . . . . . . . 20 79 4. Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 21 80 4.1. PeerConnection . . . . . . . . . . . . . . . . . . . . . 21 81 4.1.1. Constructor . . . . . . . . . . . . . . . . . . . . . 21 82 4.1.2. addTrack . . . . . . . . . . . . . . . . . . . . . . 24 83 4.1.3. removeTrack . . . . . . . . . . . . . . . . . . . . . 24 84 4.1.4. addTransceiver . . . . . . . . . . . . . . . . . . . 24 85 4.1.5. createDataChannel . . . . . . . . . . . . . . . . . . 24 86 4.1.6. createOffer . . . . . . . . . . . . . . . . . . . . . 25 87 4.1.7. createAnswer . . . . . . . . . . . . . . . . . . . . 26 88 4.1.8. SessionDescriptionType . . . . . . . . . . . . . . . 26 89 4.1.8.1. Use of Provisional Answers . . . . . . . . . . . 27 90 4.1.8.2. Rollback . . . . . . . . . . . . . . . . . . . . 28 91 4.1.9. setLocalDescription . . . . . . . . . . . . . . . . . 29 92 4.1.10. setRemoteDescription . . . . . . . . . . . . . . . . 30 93 4.1.11. currentLocalDescription . . . . . . . . . . . . . . . 30 94 4.1.12. pendingLocalDescription . . . . . . . . . . . . . . . 30 95 4.1.13. currentRemoteDescription . . . . . . . . . . . . . . 30 96 4.1.14. pendingRemoteDescription . . . . . . . . . . . . . . 31 97 4.1.15. canTrickleIceCandidates . . . . . . . . . . . . . . . 31 98 4.1.16. setConfiguration . . . . . . . . . . . . . . . . . . 31 99 4.1.17. addIceCandidate . . . . . . . . . . . . . . . . . . . 32 100 4.2. RtpTransceiver . . . . . . . . . . . . . . . . . . . . . 33 101 4.2.1. stop . . . . . . . . . . . . . . . . . . . . . . . . 33 102 4.2.2. stopped . . . . . . . . . . . . . . . . . . . . . . . 33 103 4.2.3. setDirection . . . . . . . . . . . . . . . . . . . . 33 104 4.2.4. direction . . . . . . . . . . . . . . . . . . . . . . 34 105 4.2.5. currentDirection . . . . . . . . . . . . . . . . . . 34 106 4.2.6. setCodecPreferences . . . . . . . . . . . . . . . . . 34 107 5. SDP Interaction Procedures . . . . . . . . . . . . . . . . . 35 108 5.1. Requirements Overview . . . . . . . . . . . . . . . . . . 35 109 5.1.1. Usage Requirements . . . . . . . . . . . . . . . . . 35 110 5.1.2. Profile Names and Interoperability . . . . . . . . . 35 111 5.2. Constructing an Offer . . . . . . . . . . . . . . . . . . 36 112 5.2.1. Initial Offers . . . . . . . . . . . . . . . . . . . 37 113 5.2.2. Subsequent Offers . . . . . . . . . . . . . . . . . . 43 114 5.2.3. Options Handling . . . . . . . . . . . . . . . . . . 47 115 5.2.3.1. IceRestart . . . . . . . . . . . . . . . . . . . 47 116 5.2.3.2. VoiceActivityDetection . . . . . . . . . . . . . 47 117 5.3. Generating an Answer . . . . . . . . . . . . . . . . . . 48 118 5.3.1. Initial Answers . . . . . . . . . . . . . . . . . . . 48 119 5.3.2. Subsequent Answers . . . . . . . . . . . . . . . . . 55 120 5.3.3. Options Handling . . . . . . . . . . . . . . . . . . 56 121 5.3.3.1. VoiceActivityDetection . . . . . . . . . . . . . 56 122 5.4. Modifying an Offer or Answer . . . . . . . . . . . . . . 56 123 5.5. Processing a Local Description . . . . . . . . . . . . . 57 124 5.6. Processing a Remote Description . . . . . . . . . . . . . 58 125 5.7. Parsing a Session Description . . . . . . . . . . . . . . 58 126 5.7.1. Session-Level Parsing . . . . . . . . . . . . . . . . 59 127 5.7.2. Media Section Parsing . . . . . . . . . . . . . . . . 60 128 5.7.3. Semantics Verification . . . . . . . . . . . . . . . 63 129 5.8. Applying a Local Description . . . . . . . . . . . . . . 64 130 5.9. Applying a Remote Description . . . . . . . . . . . . . . 66 131 5.10. Applying an Answer . . . . . . . . . . . . . . . . . . . 69 132 6. Processing RTP/RTCP . . . . . . . . . . . . . . . . . . . . . 72 133 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 72 134 7.1. Simple Example . . . . . . . . . . . . . . . . . . . . . 73 135 7.2. Detailed Example . . . . . . . . . . . . . . . . . . . . 77 136 7.3. Early Transport Warmup Example . . . . . . . . . . . . . 87 137 8. Security Considerations . . . . . . . . . . . . . . . . . . . 94 138 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 95 139 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 95 140 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 95 141 11.1. Normative References . . . . . . . . . . . . . . . . . . 95 142 11.2. Informative References . . . . . . . . . . . . . . . . . 100 143 Appendix A. Appendix A . . . . . . . . . . . . . . . . . . . . . 102 144 Appendix B. Change log . . . . . . . . . . . . . . . . . . . . . 103 145 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 112 147 1. Introduction 149 This document describes how the W3C WEBRTC RTCPeerConnection 150 interface [W3C.webrtc] is used to control the setup, management and 151 teardown of a multimedia session. 153 1.1. General Design of JSEP 155 The thinking behind WebRTC call setup has been to fully specify and 156 control the media plane, but to leave the signaling plane up to the 157 application as much as possible. The rationale is that different 158 applications may prefer to use different protocols, such as the 159 existing SIP call signaling protocol, or something custom to the 160 particular application, perhaps for a novel use case. In this 161 approach, the key information that needs to be exchanged is the 162 multimedia session description, which specifies the necessary 163 transport and media configuration information necessary to establish 164 the media plane. 166 With these considerations in mind, this document describes the 167 JavaScript Session Establishment Protocol (JSEP) that allows for full 168 control of the signaling state machine from JavaScript. As described 169 above, JSEP assumes a model in which a JavaScript application 170 executes inside a runtime containing WebRTC APIs (the "JSEP 171 implementation"). The JSEP implementation is almost entirely 172 divorced from the core signaling flow, which is instead handled by 173 the JavaScript making use of two interfaces: (1) passing in local and 174 remote session descriptions and (2) interacting with the ICE state 175 machine. The combination of the JSEP implementation and the 176 JavaScript application is referred to throughout this document as a 177 "JSEP endpoint". 179 In this document, the use of JSEP is described as if it always occurs 180 between two JSEP endpoints. Note though in many cases it will 181 actually be between a JSEP endpoint and some kind of server, such as 182 a gateway or MCU. This distinction is invisible to the JSEP 183 endpoint; it just follows the instructions it is given via the API. 185 JSEP's handling of session descriptions is simple and 186 straightforward. Whenever an offer/answer exchange is needed, the 187 initiating side creates an offer by calling a createOffer() API. The 188 application then uses that offer to set up its local config via the 189 setLocalDescription() API. The offer is finally sent off to the 190 remote side over its preferred signaling mechanism (e.g., 191 WebSockets); upon receipt of that offer, the remote party installs it 192 using the setRemoteDescription() API. 194 To complete the offer/answer exchange, the remote party uses the 195 createAnswer() API to generate an appropriate answer, applies it 196 using the setLocalDescription() API, and sends the answer back to the 197 initiator over the signaling channel. When the initiator gets that 198 answer, it installs it using the setRemoteDescription() API, and 199 initial setup is complete. This process can be repeated for 200 additional offer/answer exchanges. 202 Regarding ICE [RFC5245], JSEP decouples the ICE state machine from 203 the overall signaling state machine, as the ICE state machine must 204 remain in the JSEP implementation, because only the implementation 205 has the necessary knowledge of candidates and other transport 206 information. Performing this separation provides additional 207 flexibility in protocols that decouple session descriptions from 208 transport. For instance, in traditional SIP, each offer or answer is 209 self-contained, including both the session descriptions and the 210 transport information. However, [I-D.ietf-mmusic-trickle-ice-sip] 211 allows SIP to be used with trickle ICE [I-D.ietf-ice-trickle], in 212 which the session description can be sent immediately and the 213 transport information can be sent when available. Sending transport 214 information separately can allow for faster ICE and DTLS startup, 215 since ICE checks can start as soon as any transport information is 216 available rather than waiting for all of it. JSEP's decoupling of 217 the ICE and signaling state machines allows it to accommodate either 218 model. 220 Through its abstraction of signaling, the JSEP approach does require 221 the application to be aware of the signaling process. While the 222 application does not need to understand the contents of session 223 descriptions to set up a call, the application must call the right 224 APIs at the right times, convert the session descriptions and ICE 225 information into the defined messages of its chosen signaling 226 protocol, and perform the reverse conversion on the messages it 227 receives from the other side. 229 One way to mitigate this is to provide a JavaScript library that 230 hides this complexity from the developer; said library would 231 implement a given signaling protocol along with its state machine and 232 serialization code, presenting a higher level call-oriented interface 233 to the application developer. For example, libraries exist to adapt 234 the JSEP API into an API suitable for a SIP or XMPP. Thus, JSEP 235 provides greater control for the experienced developer without 236 forcing any additional complexity on the novice developer. 238 1.2. Other Approaches Considered 240 One approach that was considered instead of JSEP was to include a 241 lightweight signaling protocol. Instead of providing session 242 descriptions to the API, the API would produce and consume messages 243 from this protocol. While providing a more high-level API, this put 244 more control of signaling within the JSEP implementation, forcing it 245 to have to understand and handle concepts like signaling glare (see 246 [RFC3264], Section 4). 248 A second approach that was considered but not chosen was to decouple 249 the management of the media control objects from session 250 descriptions, instead offering APIs that would control each component 251 directly. This was rejected based on a feeling that requiring 252 exposure of this level of complexity to the application programmer 253 would not be beneficial; it would result in an API where even a 254 simple example would require a significant amount of code to 255 orchestrate all the needed interactions, as well as creating a large 256 API surface that needed to be agreed upon and documented. In 257 addition, these API points could be called in any order, resulting in 258 a more complex set of interactions with the media subsystem than the 259 JSEP approach, which specifies how session descriptions are to be 260 evaluated and applied. 262 One variation on JSEP that was considered was to keep the basic 263 session description-oriented API, but to move the mechanism for 264 generating offers and answers out of the JSEP implementation. 265 Instead of providing createOffer/createAnswer methods within the 266 implementation, this approach would instead expose a getCapabilities 267 API which would provide the application with the information it 268 needed in order to generate its own session descriptions. This 269 increases the amount of work that the application needs to do; it 270 needs to know how to generate session descriptions from capabilities, 271 and especially how to generate the correct answer from an arbitrary 272 offer and the supported capabilities. While this could certainly be 273 addressed by using a library like the one mentioned above, it 274 basically forces the use of said library even for a simple example. 275 Providing createOffer/createAnswer avoids this problem. 277 2. Terminology 279 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 280 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 281 document are to be interpreted as described in [RFC2119]. 283 3. Semantics and Syntax 285 3.1. Signaling Model 287 JSEP does not specify a particular signaling model or state machine, 288 other than the generic need to exchange session descriptions in the 289 fashion described by [RFC3264] (offer/answer) in order for both sides 290 of the session to know how to conduct the session. JSEP provides 291 mechanisms to create offers and answers, as well as to apply them to 292 a session. However, the JSEP implementation is totally decoupled 293 from the actual mechanism by which these offers and answers are 294 communicated to the remote side, including addressing, 295 retransmission, forking, and glare handling. These issues are left 296 entirely up to the application; the application has complete control 297 over which offers and answers get handed to the implementation, and 298 when. 300 +-----------+ +-----------+ 301 | Web App |<--- App-Specific Signaling -->| Web App | 302 +-----------+ +-----------+ 303 ^ ^ 304 | SDP | SDP 305 V V 306 +-----------+ +-----------+ 307 | JSEP |<----------- Media ------------>| JSEP | 308 | Impl. | | Impl. | 309 +-----------+ +-----------+ 311 Figure 1: JSEP Signaling Model 313 3.2. Session Descriptions and State Machine 315 In order to establish the media plane, the JSEP implementation needs 316 specific parameters to indicate what to transmit to the remote side, 317 as well as how to handle the media that is received. These 318 parameters are determined by the exchange of session descriptions in 319 offers and answers, and there are certain details to this process 320 that must be handled in the JSEP APIs. 322 Whether a session description applies to the local side or the remote 323 side affects the meaning of that description. For example, the list 324 of codecs sent to a remote party indicates what the local side is 325 willing to receive, which, when intersected with the set of codecs 326 the remote side supports, specifies what the remote side should send. 327 However, not all parameters follow this rule; for example, the 328 fingerprints [RFC8122] sent to a remote party are calculated based on 329 the local certificate(s) offered; the remote party MUST either accept 330 these parameters or reject them altogether, with no option to choose 331 different values. 333 In addition, various RFCs put different conditions on the format of 334 offers versus answers. For example, an offer may propose an 335 arbitrary number of m= sections (i.e., media descriptions as 336 described in [RFC4566], Section 5.14), but an answer must contain the 337 exact same number as the offer. 339 Lastly, while the exact media parameters are only known only after an 340 offer and an answer have been exchanged, the offerer may receive ICE 341 checks, and possibly media (e.g., in the case of a re-offer after a 342 connection has been established) before it receives an answer. To 343 properly process incoming media in this case, the offerer's media 344 handler must be aware of the details of the offer before the answer 345 arrives. 347 Therefore, in order to handle session descriptions properly, the JSEP 348 implementation needs: 350 1. To know if a session description pertains to the local or remote 351 side. 353 2. To know if a session description is an offer or an answer. 355 3. To allow the offer to be specified independently of the answer. 357 JSEP addresses this by adding both setLocalDescription and 358 setRemoteDescription methods and having session description objects 359 contain a type field indicating the type of session description being 360 supplied. This satisfies the requirements listed above for both the 361 offerer, who first calls setLocalDescription(sdp [offer]) and then 362 later setRemoteDescription(sdp [answer]), as well as for the 363 answerer, who first calls setRemoteDescription(sdp [offer]) and then 364 later setLocalDescription(sdp [answer]). 366 JSEP also allows for an answer to be treated as provisional by the 367 application. Provisional answers provide a way for an answerer to 368 communicate initial session parameters back to the offerer, in order 369 to allow the session to begin, while allowing a final answer to be 370 specified later. This concept of a final answer is important to the 371 offer/answer model; when such an answer is received, any extra 372 resources allocated by the caller can be released, now that the exact 373 session configuration is known. These "resources" can include things 374 like extra ICE components, TURN candidates, or video decoders. 375 Provisional answers, on the other hand, do no such deallocation; as a 376 result, multiple dissimilar provisional answers, with their own codec 377 choices, transport parameters, etc., can be received and applied 378 during call setup. Note that the final answer itself may be 379 different than any received provisional answers. 381 In [RFC3264], the constraint at the signaling level is that only one 382 offer can be outstanding for a given session, but at the media stack 383 level, a new offer can be generated at any point. For example, when 384 using SIP for signaling, if one offer is sent, then cancelled using a 385 SIP CANCEL, another offer can be generated even though no answer was 386 received for the first offer. To support this, the JSEP media layer 387 can provide an offer via the createOffer() method whenever the 388 JavaScript application needs one for the signaling. The answerer can 389 send back zero or more provisional answers, and finally end the 390 offer-answer exchange by sending a final answer. The state machine 391 for this is as follows: 393 setRemote(OFFER) setLocal(PRANSWER) 394 /-----\ /-----\ 395 | | | | 396 v | v | 397 +---------------+ | +---------------+ | 398 | |----/ | |----/ 399 | have- | setLocal(PRANSWER) | have- | 400 | remote-offer |------------------- >| local-pranswer| 401 | | | | 402 | | | | 403 +---------------+ +---------------+ 404 ^ | | 405 | | setLocal(ANSWER) | 406 setRemote(OFFER) | | 407 | V setLocal(ANSWER) | 408 +---------------+ | 409 | | | 410 | |<---------------------------+ 411 | stable | 412 | |<---------------------------+ 413 | | | 414 +---------------+ setRemote(ANSWER) | 415 ^ | | 416 | | setLocal(OFFER) | 417 setRemote(ANSWER) | | 418 | V | 419 +---------------+ +---------------+ 420 | | | | 421 | have- | setRemote(PRANSWER) |have- | 422 | local-offer |------------------- >|remote-pranswer| 423 | | | | 424 | |----\ | |----\ 425 +---------------+ | +---------------+ | 426 ^ | ^ | 427 | | | | 428 \-----/ \-----/ 429 setLocal(OFFER) setRemote(PRANSWER) 431 Figure 2: JSEP State Machine 433 Aside from these state transitions there is no other difference 434 between the handling of provisional ("pranswer") and final ("answer") 435 answers. 437 3.3. Session Description Format 439 JSEP's session descriptions use SDP syntax for their internal 440 representation. While this format is not optimal for manipulation 441 from JavaScript, it is widely accepted, and frequently updated with 442 new features; any alternate encoding of session descriptions would 443 have to keep pace with the changes to SDP, at least until the time 444 that this new encoding eclipsed SDP in popularity. 446 However, to provide for future flexibility, the SDP syntax is 447 encapsulated within a SessionDescription object, which can be 448 constructed from SDP, and be serialized out to SDP. If future 449 specifications agree on a JSON format for session descriptions, we 450 could easily enable this object to generate and consume that JSON. 452 As detailed below, most applications should be able to treat the 453 SessionDescriptions produced and consumed by these various API calls 454 as opaque blobs; that is, the application will not need to read or 455 change them. 457 3.4. Session Description Control 459 In order to give the application control over various common session 460 parameters, JSEP provides control surfaces which tell the JSEP 461 implementation how to generate session descriptions. This avoids the 462 need for JavaScript to modify session descriptions in most cases. 464 Changes to these objects result in changes to the session 465 descriptions generated by subsequent createOffer/Answer calls. 467 3.4.1. RtpTransceivers 469 RtpTransceivers allow the application to control the RTP media 470 associated with one m= section. Each RtpTransceiver has an RtpSender 471 and an RtpReceiver, which an application can use to control the 472 sending and receiving of RTP media. The application may also modify 473 the RtpTransceiver directly, for instance, by stopping it. 475 RtpTransceivers generally have a 1:1 mapping with m= sections, 476 although there may be more RtpTransceivers than m= sections when 477 RtpTransceivers are created but not yet associated with a m= section, 478 or if RtpTransceivers have been stopped and disassociated from m= 479 sections. An RtpTransceiver is said to be associated with an m= 480 section if its mid property is non-null; otherwise it is said to be 481 disassociated. The associated m= section is determined using a 482 mapping between transceivers and m= section indices, formed when 483 creating an offer or applying a remote offer. 485 An RtpTransceiver is never associated with more than one m= section, 486 and once a session description is applied, a m= section is always 487 associated with exactly one RtpTransceiver. However, in certain 488 cases where a m= section has been rejected, as discussed in 489 Section 5.2.2 below, that m= section will be "recycled" and 490 associated with a new RtpTransceiver with a new mid value. 492 RtpTransceivers can be created explicitly by the application or 493 implicitly by calling setRemoteDescription with an offer that adds 494 new m= sections. 496 3.4.2. RtpSenders 498 RtpSenders allow the application to control how RTP media is sent. 499 An RtpSender is conceptually responsible for the outgoing RTP 500 stream(s) described by an m= section. This includes encoding the 501 attached MediaStreamTrack, sending RTP media packets, and generating/ 502 processing RTCP for the outgoing RTP streams(s). 504 3.4.3. RtpReceivers 506 RtpReceivers allow the application to inspect how RTP media is 507 received. An RtpReceiver is conceptually responsible for the 508 incoming RTP stream(s) described by an m= section. This includes 509 processing received RTP media packets, decoding the incoming 510 stream(s) to produce a remote MediaStreamTrack, and generating/ 511 processing RTCP for the incoming RTP stream(s). 513 3.5. ICE 515 3.5.1. ICE Gathering Overview 517 JSEP gathers ICE candidates as needed by the application. Collection 518 of ICE candidates is referred to as a gathering phase, and this is 519 triggered either by the addition of a new or recycled m= section to 520 the local session description, or new ICE credentials in the 521 description, indicating an ICE restart. Use of new ICE credentials 522 can be triggered explicitly by the application, or implicitly by the 523 JSEP implementation in response to changes in the ICE configuration. 525 When the ICE configuration changes in a way that requires a new 526 gathering phase, a 'needs-ice-restart' bit is set. When this bit is 527 set, calls to the createOffer API will generate new ICE credentials. 528 This bit is cleared by a call to the setLocalDescription API with new 529 ICE credentials from either an offer or an answer, i.e., from either 530 a local- or remote-initiated ICE restart. 532 When a new gathering phase starts, the ICE agent will notify the 533 application that gathering is occurring through an event. Then, when 534 each new ICE candidate becomes available, the ICE agent will supply 535 it to the application via an additional event; these candidates will 536 also automatically be added to the current and/or pending local 537 session description. Finally, when all candidates have been 538 gathered, an event will be dispatched to signal that the gathering 539 process is complete. 541 Note that gathering phases only gather the candidates needed by 542 new/recycled/restarting m= sections; other m= sections continue to 543 use their existing candidates. Also, if an m= section is bundled 544 (either by a successful bundle negotiation or by being marked as 545 bundle-only), then candidates will be gathered and exchanged for that 546 m= section if and only if its MID is a BUNDLE-tag, as described in 547 [I-D.ietf-mmusic-sdp-bundle-negotiation]. 549 3.5.2. ICE Candidate Trickling 551 Candidate trickling is a technique through which a caller may 552 incrementally provide candidates to the callee after the initial 553 offer has been dispatched; the semantics of "Trickle ICE" are defined 554 in [I-D.ietf-ice-trickle]. This process allows the callee to begin 555 acting upon the call and setting up the ICE (and perhaps DTLS) 556 connections immediately, without having to wait for the caller to 557 gather all possible candidates. This results in faster media setup 558 in cases where gathering is not performed prior to initiating the 559 call. 561 JSEP supports optional candidate trickling by providing APIs, as 562 described above, that provide control and feedback on the ICE 563 candidate gathering process. Applications that support candidate 564 trickling can send the initial offer immediately and send individual 565 candidates when they get the notified of a new candidate; 566 applications that do not support this feature can simply wait for the 567 indication that gathering is complete, and then create and send their 568 offer, with all the candidates, at this time. 570 Upon receipt of trickled candidates, the receiving application will 571 supply them to its ICE agent. This triggers the ICE agent to start 572 using the new remote candidates for connectivity checks. 574 3.5.2.1. ICE Candidate Format 576 In JSEP, ICE candidates are abstracted by an IceCandidate object, and 577 as with session descriptions, SDP syntax is used for the internal 578 representation. 580 The candidate details are specified in an IceCandidate field, using 581 the same SDP syntax as the "candidate-attribute" field defined in 582 [RFC5245], Section 15.1. Note that this field does not contain an 583 "a=" prefix, as indicated in the following example: 585 candidate:1 1 UDP 1694498815 192.0.2.33 10000 typ host 587 The IceCandidate object contains a field to indicate which ICE ufrag 588 it is associated with, as defined in [RFC5245], Section 15.4. This 589 value is used to determine which session description (and thereby 590 which gathering phase) this IceCandidate belongs to, which helps 591 resolve ambiguities during ICE restarts. If this field is absent in 592 a received IceCandidate (perhaps when communicating with a non-JSEP 593 endpoint), the most recently received session description is assumed. 595 The IceCandidate object also contains fields to indicate which m= 596 section it is associated with, which can be identified in one of two 597 ways, either by a m= section index, or a MID. The m= section index 598 is a zero-based index, with index N referring to the N+1th m= section 599 in the session description referenced by this IceCandidate. The MID 600 is a "media stream identification" value, as defined in [RFC5888], 601 Section 4, which provides a more robust way to identify the m= 602 section in the session description, using the MID of the associated 603 RtpTransceiver object (which may have been locally generated by the 604 answerer when interacting with a non-JSEP endpoint that does not 605 support the MID attribute, as discussed in Section 5.9 below). If 606 the MID field is present in a received IceCandidate, it MUST be used 607 for identification; otherwise, the m= section index is used instead. 609 When creating an IceCandidate object, JSEP implementations MUST 610 populate all of these fields. 612 3.5.3. ICE Candidate Policy 614 Typically, when gathering ICE candidates, the JSEP implementation 615 will gather all possible forms of initial candidates - host, server 616 reflexive, and relay. However, in certain cases, applications may 617 want to have more specific control over the gathering process, due to 618 privacy or related concerns. For example, one may want to only use 619 relay candidates, to leak as little location information as possible 620 (keeping in mind that this choice comes with corresponding 621 operational costs). To accomplish this, JSEP allows the application 622 to restrict which ICE candidates are used in a session. Note that 623 this filtering is applied on top of any restrictions the 624 implementation chooses to enforce regarding which IP addresses are 625 permitted for the application, as discussed in 626 [I-D.ietf-rtcweb-ip-handling]. 628 There may also be cases where the application wants to change which 629 types of candidates are used while the session is active. A prime 630 example is where a callee may initially want to use only relay 631 candidates, to avoid leaking location information to an arbitrary 632 caller, but then change to use all candidates (for lower operational 633 cost) once the user has indicated they want to take the call. For 634 this scenario, the JSEP implementation MUST allow the candidate 635 policy to be changed in mid-session, subject to the aforementioned 636 interactions with local policy. 638 To administer the ICE candidate policy, the JSEP implementation will 639 determine the current setting at the start of each gathering phase. 640 Then, during the gathering phase, the implementation MUST NOT expose 641 candidates disallowed by the current policy to the application, use 642 them as the source of connectivity checks, or indirectly expose them 643 via other fields, such as the raddr/rport attributes for other ICE 644 candidates. Later, if a different policy is specified by the 645 application, the application can apply it by kicking off a new 646 gathering phase via an ICE restart. 648 3.5.4. ICE Candidate Pool 650 JSEP applications typically inform the JSEP implementation to begin 651 ICE gathering via the information supplied to setLocalDescription, as 652 the local description indicates the number of ICE components which 653 will be needed and for which candidates must be gathered. However, 654 to accelerate cases where the application knows the number of ICE 655 components to use ahead of time, it may ask the implementation to 656 gather a pool of potential ICE candidates to help ensure rapid media 657 setup. 659 When setLocalDescription is eventually called, and the JSEP 660 implementation goes to gather the needed ICE candidates, it SHOULD 661 start by checking if any candidates are available in the pool. If 662 there are candidates in the pool, they SHOULD be handed to the 663 application immediately via the ICE candidate event. If the pool 664 becomes depleted, either because a larger-than-expected number of ICE 665 components is used, or because the pool has not had enough time to 666 gather candidates, the remaining candidates are gathered as usual. 667 This only occurs for the first offer/answer exchange, after which the 668 candidate pool is emptied and no longer used. 670 One example of where this concept is useful is an application that 671 expects an incoming call at some point in the future, and wants to 672 minimize the time it takes to establish connectivity, to avoid 673 clipping of initial media. By pre-gathering candidates into the 674 pool, it can exchange and start sending connectivity checks from 675 these candidates almost immediately upon receipt of a call. Note 676 though that by holding on to these pre-gathered candidates, which 677 will be kept alive as long as they may be needed, the application 678 will consume resources on the STUN/TURN servers it is using. 680 3.6. Video Size Negotiation 682 Video size negotiation is the process through which a receiver can 683 use the "a=imageattr" SDP attribute [RFC6236] to indicate what video 684 frame sizes it is capable of receiving. A receiver may have hard 685 limits on what its video decoder can process, or it may have some 686 maximum set by policy. By specifying these limits in an 687 "a=imageattr" attribute, JSEP endpoints can attempt to ensure that 688 the remote sender transmits video at an acceptable resolution. 689 However, when communicating with a non-JSEP endpoint that does not 690 understand this attribute, any signaled limits may be exceeded, and 691 the JSEP implementation MUST handle this gracefully, e.g., by 692 discarding the video. 694 Note that certain codecs support transmission of samples with aspect 695 ratios other than 1.0 (i.e., non-square pixels). JSEP 696 implementations will not transmit non-square pixels, but SHOULD 697 receive and render such video with the correct aspect ratio. 698 However, sample aspect ratio has no impact on the size negotiation 699 described below; all dimensions are measured in pixels, whether 700 square or not. 702 3.6.1. Creating an imageattr Attribute 704 The receiver will first intersect any known local limits (e.g., 705 hardware decoder capababilities, local policy) to determine the 706 absolute minimum and maximum sizes it can receive. If there are no 707 known local limits, the "a=imageattr" attribute SHOULD be omitted. 708 If these local limits preclude receiving any video, i.e., the 709 degenerate case of no permitted resolutions, the "a=imageattr" 710 attribute MUST be omitted, and the m= section MUST be marked as 711 sendonly/inactive, as appropriate. 713 Otherwise, an "a=imageattr" attribute is created with "recv" 714 direction, and the resulting resolution space formed from the 715 aforementioned intersection is used to specify its minimum and 716 maximum x= and y= values. 718 The rules here express a single set of preferences, and therefore, 719 the "a=imageattr" q= value is not important. It SHOULD be set to 720 1.0. 722 The "a=imageattr" field is payload type specific. When all video 723 codecs supported have the same capabilities, use of a single 724 attribute, with the wildcard payload type (*), is RECOMMENDED. 725 However, when the supported video codecs have different limitations, 726 specific "a=imageattr" attributes MUST be inserted for each payload 727 type. 729 As an example, consider a system with a multiformat video decoder, 730 which is capable of decoding any resolution from 48x48 to 720p, In 731 this case, the implementation would generate this attribute: 733 a=imageattr:* recv [x=[48:1280],y=[48:720],q=1.0] 735 This declaration indicates that the receiver is capable of decoding 736 any image resolution from 48x48 up to 1280x720 pixels. 738 3.6.2. Interpreting an imageattr Attribute 740 [RFC6236] defines "a=imageattr" to be an advisory field. This means 741 that it does not absolutely constrain the video formats that the 742 sender can use, but gives an indication of the preferred values. 744 This specification prescribes more specific behavior. When a 745 MediaStreamTrack, which is producing video of a certain resolution 746 (the "track resolution"), is attached to a RtpSender, which is 747 encoding the track video at the same or lower resolution(s) (the 748 "encoder resolutions"), and a remote description is applied that 749 references the sender and contains valid "a=imageattr recv" 750 attributes, it MUST follow the rules below to ensure the sender does 751 not transmit a resolution that would exceed the size criteria 752 specified in the attributes. These rules MUST be followed as long as 753 the attributes remain present in the remote description, including 754 cases in which the track changes its resolution, or is replaced with 755 a different track. 757 Depending on how the RtpSender is configured, it may be producing a 758 single encoding at a certain resolution, or, if simulcast Section 3.7 759 has been negotiated, multiple encodings, each at their own specific 760 resolution. In addition, depending on the configuration, each 761 encoding may have the flexibility to reduce resolution when needed, 762 or may be locked to a specific output resolution. 764 For each encoding being produced by the RtpSender, the following 765 rules are applied to determine what should be transmitted: 767 o First, the most suitable "a=imageattr recv" attribute is selected. 768 This is performed by taking the attribute with the highest "q=" 769 value from the set of attributes that reference the media format 770 that has been selected for the specified encoding. If multiple 771 attributes have the same "q=" value, the one that appears first in 772 the m= section is used. Note that while JSEP endpoints will 773 include at most one "a=imageattr recv" attribute per media format, 774 JSEP endpoints may receive session descriptions from non-JSEP 775 endpoints with m= sections that contain multiple such attributes. 777 o If there is an applicable "a=imageattr recv" attribute for the 778 encoding, the limits from the attribute are then compared to the 779 encoder resolution. Only the specific limits mentioned below are 780 considered; any other values, such as picture aspect ratio, MUST 781 be ignored. Note that when considering a MediaStreamTrack that is 782 producing rotated video, the unrotated resolution MUST be used for 783 the checks. This is required regardless of whether the receiver 784 supports performing receive-side rotation (e.g., through CVO 785 [TS26.114]), as it significantly simplifies the matching logic. 787 o If the attribute includes a "sar=" (sample aspect ratio) value set 788 to something other than "1.0", indicating the receiver wants to 789 receive non-square pixels, this cannot be satisfied and the sender 790 MUST NOT transmit the encoding. 792 o If the encoder resolution exceeds the maximum size permitted by 793 the attribute, and the encoder is allowed to adjust its 794 resolution, the encoder SHOULD apply downscaling in order to 795 satisfy the limits, although the downscaling MUST NOT change the 796 picture aspect ratio of the encoding. For example, if the encoder 797 resolution is 1280x720, and the attribute specified a maximum of 798 640x480, the expected output resolution would be 640x360. If 799 downscaling cannot be applied, the encoding MUST NOT be 800 transmitted, and an error SHOULD be surfaced to the application. 802 o If the encoder resolution is less than the minimum size permitted 803 by the attribute, the encoding MUST NOT be transmitted, and an 804 error SHOULD be surfaced to the application; the encoder MUST NOT 805 apply upscaling. JSEP implementations SHOULD avoid this situation 806 by allowing receipt of arbitrarily small resolutions, perhaps via 807 fallback to a software decoder. 809 3.7. Simulcast 811 JSEP supports simulcast transmission of a MediaStreamTrack, where 812 multiple encodings of the source media can be transmitted within the 813 context of a single m= section. The current JSEP API is designed to 814 allow applications to send simulcasted media but only to receive a 815 single encoding. This allows for multi-user scenarios where each 816 sending client sends multiple encodings to a server, which then, for 817 each receiving client, chooses the appropriate encoding to forward. 819 Applications request support for simulcast by configuring multiple 820 encodings on an RtpSender, which, upon generation of an offer or 821 answer, are indicated in SDP markings on the corresponding m= 822 section, as described below. Receivers that understand simulcast and 823 are willing to receive it will also include SDP markings to indicate 824 their support, and JSEP endpoints will use these markings to 825 determine whether simulcast is permitted for a given RtpSender. If 826 simulcast support is not negotiated, the RtpSender will only use the 827 first configured encoding. 829 Note that the exact simulcast parameters are up to the sending 830 application. While the aforementioned SDP markings are provided to 831 ensure the remote side can receive and demux multiple simulcast 832 encodings, the specific resolutions and bitrates to be used for each 833 encoding are purely a send-side decision in JSEP. 835 JSEP currently does not provide a mechanism to configure receipt of 836 simulcast. This means that if simulcast is offered by the remote 837 endpoint, the answer generated by a JSEP endpoint will not indicate 838 support for receipt of simulcast, and as such the remote endpoint 839 will only send a single encoding per m= section. 841 In addition, JSEP does not provide a mechanism to handle an incoming 842 offer requesting simulcast from the JSEP endpoint. This means that 843 established simulcast streams will continue to work through a 844 received re-offer, but setting up initial simulcast by way of a 845 received offer requires out-of-band signaling or SDP inspection. 846 Future versions of this specification may add additional APIs to 847 provide direct control. 849 When using JSEP to transmit multiple encodings from a RtpSender, the 850 techniques from [I-D.ietf-mmusic-sdp-simulcast] and 851 [I-D.ietf-mmusic-rid] are used. Specifically, when multiple 852 encodings have been configured for a RtpSender, the m= section for 853 the RtpSender will include an "a=simulcast" attribute, as defined in 854 [I-D.ietf-mmusic-sdp-simulcast], Section 6.2, with a "send" simulcast 855 stream description that lists each desired encoding, and no "recv" 856 simulcast stream description. The m= section will also include an 857 "a=rid" attribute for each encoding, as specified in 858 [I-D.ietf-mmusic-rid], Section 4; the use of RID identifiers allows 859 the individual encodings to be disambiguated even though they are all 860 part of the same m= section. 862 3.8. Interactions With Forking 864 Some call signaling systems allow various types of forking where an 865 SDP Offer may be provided to more than one device. For example, SIP 866 [RFC3261] defines both a "Parallel Search" and "Sequential Search". 868 Although these are primarily signaling level issues that are outside 869 the scope of JSEP, they do have some impact on the configuration of 870 the media plane that is relevant. When forking happens at the 871 signaling layer, the JavaScript application responsible for the 872 signaling needs to make the decisions about what media should be sent 873 or received at any point of time, as well as which remote endpoint it 874 should communicate with; JSEP is used to make sure the media engine 875 can make the RTP and media perform as required by the application. 876 The basic operations that the applications can have the media engine 877 do are: 879 o Start exchanging media with a given remote peer, but keep all the 880 resources reserved in the offer. 882 o Start exchanging media with a given remote peer, and free any 883 resources in the offer that are not being used. 885 3.8.1. Sequential Forking 887 Sequential forking involves a call being dispatched to multiple 888 remote callees, where each callee can accept the call, but only one 889 active session ever exists at a time; no mixing of received media is 890 performed. 892 JSEP handles sequential forking well, allowing the application to 893 easily control the policy for selecting the desired remote endpoint. 894 When an answer arrives from one of the callees, the application can 895 choose to apply it either as a provisional answer, leaving open the 896 possibility of using a different answer in the future, or apply it as 897 a final answer, ending the setup flow. 899 In a "first-one-wins" situation, the first answer will be applied as 900 a final answer, and the application will reject any subsequent 901 answers. In SIP parlance, this would be ACK + BYE. 903 In a "last-one-wins" situation, all answers would be applied as 904 provisional answers, and any previous call leg will be terminated. 905 At some point, the application will end the setup process, perhaps 906 with a timer; at this point, the application could reapply the 907 pending remote description as a final answer. 909 3.8.2. Parallel Forking 911 Parallel forking involves a call being dispatched to multiple remote 912 callees, where each callee can accept the call, and multiple 913 simultaneous active signaling sessions can be established as a 914 result. If multiple callees send media at the same time, the 915 possibilities for handling this are described in [RFC3960], 916 Section 3.1. Most SIP devices today only support exchanging media 917 with a single device at a time, and do not try to mix multiple early 918 media audio sources, as that could result in a confusing situation. 919 For example, consider having a European ringback tone mixed together 920 with the North American ringback tone - the resulting sound would not 921 be like either tone, and would confuse the user. If the signaling 922 application wishes to only exchange media with one of the remote 923 endpoints at a time, then from a media engine point of view, this is 924 exactly like the sequential forking case. 926 In the parallel forking case where the JavaScript application wishes 927 to simultaneously exchange media with multiple peers, the flow is 928 slightly more complex, but the JavaScript application can follow the 929 strategy that [RFC3960] describes using UPDATE. The UPDATE approach 930 allows the signaling to set up a separate media flow for each peer 931 that it wishes to exchange media with. In JSEP, this offer used in 932 the UPDATE would be formed by simply creating a new PeerConnection 933 and making sure that the same local media streams have been added 934 into this new PeerConnection. Then the new PeerConnection object 935 would produce a SDP offer that could be used by the signaling to 936 perform the UPDATE strategy discussed in [RFC3960]. 938 As a result of sharing the media streams, the application will end up 939 with N parallel PeerConnection sessions, each with a local and remote 940 description and their own local and remote addresses. The media flow 941 from these sessions can be managed using setDirection (see 942 Section 4.2.3), or the application can choose to play out the media 943 from all sessions mixed together. Of course, if the application 944 wants to only keep a single session, it can simply terminate the 945 sessions that it no longer needs. 947 4. Interface 949 This section details the basic operations that must be present to 950 implement JSEP functionality. The actual API exposed in the W3C API 951 may have somewhat different syntax, but should map easily to these 952 concepts. 954 4.1. PeerConnection 956 4.1.1. Constructor 958 The PeerConnection constructor allows the application to specify 959 global parameters for the media session, such as the STUN/TURN 960 servers and credentials to use when gathering candidates, as well as 961 the initial ICE candidate policy and pool size, and also the bundle 962 policy to use. 964 If an ICE candidate policy is specified, it functions as described in 965 Section 3.5.3, causing the JSEP implementation to only surface the 966 permitted candidates (including any implementation-internal 967 filtering) to the application, and only use those candidates for 968 connectivity checks. The set of available policies is as follows: 970 all: All candidates permitted by implementation policy will be 971 gathered and used. 973 relay: All candidates except relay candidates will be filtered out. 974 This obfuscates the location information that might be ascertained 975 by the remote peer from the received candidates. Depending on how 976 the application deploys and chooses relay servers, this could 977 obfuscate location to a metro or possibly even global level. 979 The default ICE candidate policy MUST be set to "all" as this is 980 generally the desired policy, and also typically reduces use of 981 application TURN server resources significantly. 983 If a size is specified for the ICE candidate pool, this indicates the 984 number of ICE components to pre-gather candidates for. Because pre- 985 gathering results in utilizing STUN/TURN server resources for 986 potentially long periods of time, this must only occur upon 987 application request, and therefore the default candidate pool size 988 MUST be zero. 990 The application can specify its preferred policy regarding use of 991 bundle, the multiplexing mechanism defined in 992 [I-D.ietf-mmusic-sdp-bundle-negotiation]. Regardless of policy, the 993 application will always try to negotiate bundle onto a single 994 transport, and will offer a single bundle group across all m= 995 sections; use of this single transport is contingent upon the 996 answerer accepting bundle. However, by specifying a policy from the 997 list below, the application can control exactly how aggressively it 998 will try to bundle media streams together, which affects how it will 999 interoperate with a non-bundle-aware endpoint. When negotiating with 1000 a non-bundle-aware endpoint, only the streams not marked as bundle- 1001 only streams will be established. 1003 The set of available policies is as follows: 1005 balanced: The first m= section of each type (audio, video, or 1006 application) will contain transport parameters, which will allow 1007 an answerer to unbundle that section. The second and any 1008 subsequent m= section of each type will be marked bundle-only. 1009 The result is that if there are N distinct media types, then 1010 candidates will be gathered for for N media streams. This policy 1011 balances desire to multiplex with the need to ensure basic audio 1012 and video can still be negotiated in legacy cases. When acting as 1013 answerer, if there is no bundle group in the offer, the 1014 implementation will reject all but the first m= section of each 1015 type. 1017 max-compat: All m= sections will contain transport parameters; none 1018 will be marked as bundle-only. This policy will allow all streams 1019 to be received by non-bundle-aware endpoints, but require separate 1020 candidates to be gathered for each media stream. 1022 max-bundle: Only the first m= section will contain transport 1023 parameters; all streams other than the first will be marked as 1024 bundle-only. This policy aims to minimize candidate gathering and 1025 maximize multiplexing, at the cost of less compatibility with 1026 legacy endpoints. When acting as answerer, the implementation 1027 will reject any m= sections other than the first m= section, 1028 unless they are in the same bundle group as that m= section. 1030 As it provides the best tradeoff between performance and 1031 compatibility with legacy endpoints, the default bundle policy MUST 1032 be set to "balanced". 1034 The application can specify its preferred policy regarding use of 1035 RTP/RTCP multiplexing [RFC5761] using one of the following policies: 1037 negotiate: The JSEP implementation will gather both RTP and RTCP 1038 candidates but also will offer "a=rtcp-mux", thus allowing for 1039 compatibility with either multiplexing or non-multiplexing 1040 endpoints. 1042 require: The JSEP implementation will only gather RTP candidates and 1043 will insert an "a=rtcp-mux-only" indication into any new m= 1044 sections in offers it generates. This halves the number of 1045 candidates that the offerer needs to gather. Applying a 1046 description with an m= section that does not contain an "a=rtcp- 1047 mux" attribute will cause an error to be returned. 1049 The default multiplexing policy MUST be set to "require". 1050 Implementations MAY choose to reject attempts by the application to 1051 set the multiplexing policy to "negotiate". 1053 4.1.2. addTrack 1055 The addTrack method adds a MediaStreamTrack to the PeerConnection, 1056 using the MediaStream argument to associate the track with other 1057 tracks in the same MediaStream, so that they can be added to the same 1058 "LS" group when creating an offer or answer. addTrack attempts to 1059 minimize the number of transceivers as follows: If the PeerConnection 1060 is in the "have-remote-offer" state, the track will be attached to 1061 the first compatible transceiver that was created by the most recent 1062 call to setRemoteDescription() and does not have a local track. 1063 Otherwise, a new transceiver will be created, as described in 1064 Section 4.1.4. 1066 4.1.3. removeTrack 1068 The removeTrack method removes a MediaStreamTrack from the 1069 PeerConnection, using the RtpSender argument to indicate which sender 1070 should have its track removed. The sender's track is cleared, and 1071 the sender stops sending. Future calls to createOffer will mark the 1072 m= section associated with the sender as recvonly (if 1073 transceiver.currentDirection is sendrecv) or as inactive (if 1074 transceiver.currentDirection is sendonly). 1076 4.1.4. addTransceiver 1078 The addTransceiver method adds a new RtpTransceiver to the 1079 PeerConnection. If a MediaStreamTrack argument is provided, then the 1080 transceiver will be configured with that media type and the track 1081 will be attached to the transceiver. Otherwise, the application MUST 1082 explicitly specify the type; this mode is useful for creating 1083 recvonly transceivers as well as for creating transceivers to which a 1084 track can be attached at some later point. 1086 At the time of creation, the application can also specify a 1087 transceiver direction attribute, a set of MediaStreams which the 1088 transceiver is associated with (allowing LS group assignments), and a 1089 set of encodings for the media (used for simulcast as described in 1090 Section 3.7). 1092 4.1.5. createDataChannel 1094 The createDataChannel method creates a new data channel and attaches 1095 it to the PeerConnection. If no data channel currently exists for 1096 this PeerConnection, then a new offer/answer exchange is required. 1097 All data channels on a given PeerConnection share the same SCTP/DTLS 1098 association and therefore the same m= section, so subsequent creation 1099 of data channels does not have any impact on the JSEP state. 1101 The createDataChannel method also includes a number of arguments 1102 which are used by the PeerConnection (e.g., maxPacketLifetime) but 1103 are not reflected in the SDP and do not affect the JSEP state. 1105 4.1.6. createOffer 1107 The createOffer method generates a blob of SDP that contains a 1108 [RFC3264] offer with the supported configurations for the session, 1109 including descriptions of the media added to this PeerConnection, the 1110 codec/RTP/RTCP options supported by this implementation, and any 1111 candidates that have been gathered by the ICE agent. An options 1112 parameter may be supplied to provide additional control over the 1113 generated offer. This options parameter allows an application to 1114 trigger an ICE restart, for the purpose of reestablishing 1115 connectivity. 1117 In the initial offer, the generated SDP will contain all desired 1118 functionality for the session (functionality that is supported but 1119 not desired by default may be omitted); for each SDP line, the 1120 generation of the SDP will follow the process defined for generating 1121 an initial offer from the document that specifies the given SDP line. 1122 The exact handling of initial offer generation is detailed in 1123 Section 5.2.1 below. 1125 In the event createOffer is called after the session is established, 1126 createOffer will generate an offer to modify the current session 1127 based on any changes that have been made to the session, e.g., adding 1128 or stopping RtpTransceivers, or requesting an ICE restart. For each 1129 existing stream, the generation of each SDP line must follow the 1130 process defined for generating an updated offer from the RFC that 1131 specifies the given SDP line. For each new stream, the generation of 1132 the SDP must follow the process of generating an initial offer, as 1133 mentioned above. If no changes have been made, or for SDP lines that 1134 are unaffected by the requested changes, the offer will only contain 1135 the parameters negotiated by the last offer-answer exchange. The 1136 exact handling of subsequent offer generation is detailed in 1137 Section 5.2.2. below. 1139 Session descriptions generated by createOffer must be immediately 1140 usable by setLocalDescription; if a system has limited resources 1141 (e.g. a finite number of decoders), createOffer should return an 1142 offer that reflects the current state of the system, so that 1143 setLocalDescription will succeed when it attempts to acquire those 1144 resources. 1146 Calling this method may do things such as generating new ICE 1147 credentials, but does not result in candidate gathering, or cause 1148 media to start or stop flowing. Specifically, the offer is not 1149 applied, and does not become the pending local description, until 1150 setLocalDescription is called. 1152 4.1.7. createAnswer 1154 The createAnswer method generates a blob of SDP that contains a 1155 [RFC3264] SDP answer with the supported configuration for the session 1156 that is compatible with the parameters supplied in the most recent 1157 call to setRemoteDescription, which MUST have been called prior to 1158 calling createAnswer. Like createOffer, the returned blob contains 1159 descriptions of the media added to this PeerConnection, the 1160 codec/RTP/RTCP options negotiated for this session, and any 1161 candidates that have been gathered by the ICE agent. An options 1162 parameter may be supplied to provide additional control over the 1163 generated answer. 1165 As an answer, the generated SDP will contain a specific configuration 1166 that specifies how the media plane should be established; for each 1167 SDP line, the generation of the SDP must follow the process defined 1168 for generating an answer from the document that specifies the given 1169 SDP line. The exact handling of answer generation is detailed in 1170 Section 5.3. below. 1172 Session descriptions generated by createAnswer must be immediately 1173 usable by setLocalDescription; like createOffer, the returned 1174 description should reflect the current state of the system. 1176 Calling this method may do things such as generating new ICE 1177 credentials, but does not trigger candidate gathering or cause a 1178 media state change. Specifically, the answer is not applied, and 1179 does not become the pending local description, until 1180 setLocalDescription is called. 1182 4.1.8. SessionDescriptionType 1184 Session description objects (RTCSessionDescription) may be of type 1185 "offer", "pranswer", "answer" or "rollback". These types provide 1186 information as to how the description parameter should be parsed, and 1187 how the media state should be changed. 1189 "offer" indicates that a description should be parsed as an offer; 1190 said description may include many possible media configurations. A 1191 description used as an "offer" may be applied anytime the 1192 PeerConnection is in a stable state, or as an update to a previously 1193 supplied but unanswered "offer". 1195 "pranswer" indicates that a description should be parsed as an 1196 answer, but not a final answer, and so should not result in the 1197 freeing of allocated resources. It may result in the start of media 1198 transmission, if the answer does not specify an inactive media 1199 direction. A description used as a "pranswer" may be applied as a 1200 response to an "offer", or an update to a previously sent "pranswer". 1202 "answer" indicates that a description should be parsed as an answer, 1203 the offer-answer exchange should be considered complete, and any 1204 resources (decoders, candidates) that are no longer needed can be 1205 released. A description used as an "answer" may be applied as a 1206 response to an "offer", or an update to a previously sent "pranswer". 1208 The only difference between a provisional and final answer is that 1209 the final answer results in the freeing of any unused resources that 1210 were allocated as a result of the offer. As such, the application 1211 can use some discretion on whether an answer should be applied as 1212 provisional or final, and can change the type of the session 1213 description as needed. For example, in a serial forking scenario, an 1214 application may receive multiple "final" answers, one from each 1215 remote endpoint. The application could choose to accept the initial 1216 answers as provisional answers, and only apply an answer as final 1217 when it receives one that meets its criteria (e.g. a live user 1218 instead of voicemail). 1220 "rollback" is a special session description type implying that the 1221 state machine should be rolled back to the previous stable state, as 1222 described in Section 4.1.8.2. The contents MUST be empty. 1224 4.1.8.1. Use of Provisional Answers 1226 Most applications will not need to create answers using the 1227 "pranswer" type. While it is good practice to send an immediate 1228 response to an offer, in order to warm up the session transport and 1229 prevent media clipping, the preferred handling for a JSEP application 1230 is to create and send a "sendonly" final answer with a null 1231 MediaStreamTrack immediately after receiving the offer, which will 1232 prevent media from being sent by the caller, and allow media to be 1233 sent immediately upon answer by the callee. Later, when the callee 1234 actually accepts the call, the application can plug in the real 1235 MediaStreamTrack and create a new "sendrecv" offer to update the 1236 previous offer/answer pair and start bidirectional media flow. While 1237 this could also be done with a "sendonly" pranswer, followed by a 1238 "sendrecv" answer, the initial pranswer leaves the offer-answer 1239 exchange open, which means that the caller cannot send an updated 1240 offer during this time. 1242 As an example, consider a typical JSEP application that wants to set 1243 up audio and video as quickly as possible. When the callee receives 1244 an offer with audio and video MediaStreamTracks, it will send an 1245 immediate answer accepting these tracks as sendonly (meaning that the 1246 caller will not send the callee any media yet, and because the callee 1247 has not yet added its own MediaStreamTracks, the callee will not send 1248 any media either). It will then ask the user to accept the call and 1249 acquire the needed local tracks. Upon acceptance by the user, the 1250 application will plug in the tracks it has acquired, which, because 1251 ICE and DTLS handshaking have likely completed by this point, can 1252 start transmitting immediately. The application will also send a new 1253 offer to the remote side indicating call acceptance and moving the 1254 audio and video to be two-way media. A detailed example flow along 1255 these lines is shown in Section 7.3. 1257 Of course, some applications may not be able to perform this double 1258 offer-answer exchange, particularly ones that are attempting to 1259 gateway to legacy signaling protocols. In these cases, pranswer can 1260 still provide the application with a mechanism to warm up the 1261 transport. 1263 4.1.8.2. Rollback 1265 In certain situations it may be desirable to "undo" a change made to 1266 setLocalDescription or setRemoteDescription. Consider a case where a 1267 call is ongoing, and one side wants to change some of the session 1268 parameters; that side generates an updated offer and then calls 1269 setLocalDescription. However, the remote side, either before or 1270 after setRemoteDescription, decides it does not want to accept the 1271 new parameters, and sends a reject message back to the offerer. Now, 1272 the offerer, and possibly the answerer as well, need to return to a 1273 stable state and the previous local/remote description. To support 1274 this, we introduce the concept of "rollback". 1276 A rollback discards any proposed changes to the session, returning 1277 the state machine to the stable state, and setting the pending local 1278 and/or remote description (see Section 4.1.12 and Section 4.1.14) to 1279 null. Any resources or candidates that were allocated by the 1280 abandoned local description are discarded; any media that is received 1281 will be processed according to the previous local and remote 1282 descriptions. Rollback can only be used to cancel proposed changes; 1283 there is no support for rolling back from a stable state to a 1284 previous stable state. Note that this implies that once the answerer 1285 has performed setLocalDescription with his answer, this cannot be 1286 rolled back. 1288 A rollback will disassociate any RtpTransceivers that were associated 1289 with m= sections by the application of the rolled-back session 1290 description (see Section 5.9 and Section 5.8). This means that some 1291 RtpTransceivers that were previously associated will no longer be 1292 associated with any m= section; in such cases, the value of the 1293 RtpTransceiver's mid property MUST be set to null, and the mapping 1294 between the transceiver and its m= section index MUST be discarded. 1295 RtpTransceivers that were created by applying a remote offer that was 1296 subsequently rolled back MUST be stopped and removed from the 1297 PeerConnection. However, a RtpTransceiver MUST NOT be removed if a 1298 track was attached to the RtpTransceiver via the addTrack method. 1299 This is so that an application may call addTrack, then call 1300 setRemoteDescription with an offer, then roll back that offer, then 1301 call createOffer and have a m= section for the added track appear in 1302 the generated offer. 1304 A rollback is performed by supplying a session description of type 1305 "rollback" with empty contents to either setLocalDescription or 1306 setRemoteDescription, depending on which was most recently used (i.e. 1307 if the new offer was supplied to setLocalDescription, the rollback 1308 should be done using setLocalDescription as well). 1310 4.1.9. setLocalDescription 1312 The setLocalDescription method instructs the PeerConnection to apply 1313 the supplied session description as its local configuration. The 1314 type field indicates whether the description should be processed as 1315 an offer, provisional answer, final answer, or rollback; offers and 1316 answers are checked differently, using the various rules that exist 1317 for each SDP line. 1319 This API changes the local media state; among other things, it sets 1320 up local resources for receiving and decoding media. In order to 1321 successfully handle scenarios where the application wants to offer to 1322 change from one media format to a different, incompatible format, the 1323 PeerConnection must be able to simultaneously support use of both the 1324 current and pending local descriptions (e.g., support the codecs that 1325 exist in either description). This dual processing begins when the 1326 PeerConnection enters the "have-local-offer" state, and continues 1327 until setRemoteDescription is called with either a final answer, at 1328 which point the PeerConnection can fully adopt the pending local 1329 description, or a rollback, which results in a revert to the current 1330 local description. 1332 This API indirectly controls the candidate gathering process. When a 1333 local description is supplied, and the number of transports currently 1334 in use does not match the number of transports needed by the local 1335 description, the PeerConnection will create transports as needed and 1336 begin gathering candidates for each transport, using ones from the 1337 candidate pool if available. 1339 If setRemoteDescription was previously called with an offer, and 1340 setLocalDescription is called with an answer (provisional or final), 1341 and the media directions are compatible, and media is available to 1342 send, this will result in the starting of media transmission. 1344 4.1.10. setRemoteDescription 1346 The setRemoteDescription method instructs the PeerConnection to apply 1347 the supplied session description as the desired remote configuration. 1348 As in setLocalDescription, the type field of the description 1349 indicates how it should be processed. 1351 This API changes the local media state; among other things, it sets 1352 up local resources for sending and encoding media. 1354 If setLocalDescription was previously called with an offer, and 1355 setRemoteDescription is called with an answer (provisional or final), 1356 and the media directions are compatible, and media is available to 1357 send, this will result in the starting of media transmission. 1359 4.1.11. currentLocalDescription 1361 The currentLocalDescription method returns the current negotiated 1362 local description - i.e., the local description from the last 1363 successful offer/answer exchange - in addition to any local 1364 candidates that have been generated by the ICE agent since the local 1365 description was set. 1367 A null object will be returned if an offer/answer exchange has not 1368 yet been completed. 1370 4.1.12. pendingLocalDescription 1372 The pendingLocalDescription method returns a copy of the local 1373 description currently in negotiation - i.e., a local offer set 1374 without any corresponding remote answer - in addition to any local 1375 candidates that have been generated by the ICE agent since the local 1376 description was set. 1378 A null object will be returned if the state of the PeerConnection is 1379 "stable" or "have-remote-offer". 1381 4.1.13. currentRemoteDescription 1383 The currentRemoteDescription method returns a copy of the current 1384 negotiated remote description - i.e., the remote description from the 1385 last successful offer/answer exchange - in addition to any remote 1386 candidates that have been supplied via processIceMessage since the 1387 remote description was set. 1389 A null object will be returned if an offer/answer exchange has not 1390 yet been completed. 1392 4.1.14. pendingRemoteDescription 1394 The pendingRemoteDescription method returns a copy of the remote 1395 description currently in negotiation - i.e., a remote offer set 1396 without any corresponding local answer - in addition to any remote 1397 candidates that have been supplied via processIceMessage since the 1398 remote description was set. 1400 A null object will be returned if the state of the PeerConnection is 1401 "stable" or "have-local-offer". 1403 4.1.15. canTrickleIceCandidates 1405 The canTrickleIceCandidates property indicates whether the remote 1406 side supports receiving trickled candidates. There are three 1407 potential values: 1409 null: No SDP has been received from the other side, so it is not 1410 known if it can handle trickle. This is the initial value before 1411 setRemoteDescription() is called. 1413 true: SDP has been received from the other side indicating that it 1414 can support trickle. 1416 false: SDP has been received from the other side indicating that it 1417 cannot support trickle. 1419 As described in Section 3.5.2, JSEP implementations always provide 1420 candidates to the application individually, consistent with what is 1421 needed for Trickle ICE. However, applications can use the 1422 canTrickleIceCandidates property to determine whether their peer can 1423 actually do Trickle ICE, i.e., whether it is safe to send an initial 1424 offer or answer followed later by candidates as they are gathered. 1425 As "true" is the only value that definitively indicates remote 1426 Trickle ICE support, an application which compares 1427 canTrickleIceCandidates against "true" will by default attempt Half 1428 Trickle on initial offers and Full Trickle on subsequent interactions 1429 with a Trickle ICE-compatible agent. 1431 4.1.16. setConfiguration 1433 The setConfiguration method allows the global configuration of the 1434 PeerConnection, which was initially set by constructor parameters, to 1435 be changed during the session. The effects of this method call 1436 depend on when it is invoked, and differ depending on which specific 1437 parameters are changed: 1439 o Any changes to the STUN/TURN servers to use affect the next 1440 gathering phase. If an ICE gathering phase has already started or 1441 completed, the 'needs-ice-restart' bit mentioned in Section 3.5.1 1442 will be set. This will cause the next call to createOffer to 1443 generate new ICE credentials, for the purpose of forcing an ICE 1444 restart and kicking off a new gathering phase, in which the new 1445 servers will be used. If the ICE candidate pool has a nonzero 1446 size, and a local description has not yet been applied, any 1447 existing candidates will be discarded, and new candidates will be 1448 gathered from the new servers. 1450 o Any change to the ICE candidate policy affects the next gathering 1451 phase. If an ICE gathering phase has already started or 1452 completed, the 'needs-ice-restart' bit will be set. Either way, 1453 changes to the policy have no effect on the candidate pool, 1454 because pooled candidates are not surfaced to the application 1455 until a gathering phase occurs, and so any necessary filtering can 1456 still be done on any pooled candidates. 1458 o The ICE candidate pool size MUST NOT be changed after applying a 1459 local description. If a local description has not yet been 1460 applied, any changes to the ICE candidate pool size take effect 1461 immediately; if increased, additional candidates are pre-gathered; 1462 if decreased, the now-superfluous candidates are discarded. 1464 o The bundle and RTCP-multiplexing policies MUST NOT be changed 1465 after the construction of the PeerConnection. 1467 This call may result in a change to the state of the ICE Agent. 1469 4.1.17. addIceCandidate 1471 The addIceCandidate method provides a remote candidate to the ICE 1472 agent, which, if parsed successfully, will be added to the current 1473 and/or pending remote description according to the rules defined for 1474 Trickle ICE. The pair of MID and ufrag is used to determine the m= 1475 section and ICE candidate generation to which the candidate belongs. 1476 If the MID is not present, the m= section index is used to look up 1477 the locally generated MID (see Section 5.9), which is used in place 1478 of a supplied MID. If these values or the candidate string are 1479 invalid, an error is generated. 1481 The purpose of the ufrag is to resolve ambiguities when trickle ICE 1482 is in progress during an ICE restart. If the ufrag is absent, the 1483 candidate MUST be assumed to belong to the most recently applied 1484 remote description. Connectivity checks will be sent to the new 1485 candidate. 1487 This method can also be used to provide an end-of-candidates 1488 indication to the ICE agent, as defined in [I-D.ietf-ice-trickle]). 1489 The MID and ufrag are used as described above to determine the m= 1490 section and ICE generation for which candidate gathering is complete. 1491 If the ufrag is not present, then the end-of-candidates indication 1492 MUST be assumed to apply to the relevant m= section in the most 1493 recently applied remote description. If neither the MID nor the m= 1494 index is present, then the indication MUST be assumed to apply to all 1495 m= sections in the most recently applied remote description. 1497 This call will result in a change to the state of the ICE Agent, and 1498 may result in a change to media state if it results in connectivity 1499 being established. 1501 4.2. RtpTransceiver 1503 4.2.1. stop 1505 The stop method stops an RtpTransceiver. This will cause future 1506 calls to createOffer to generate a zero port for the associated m= 1507 section. See below for more details. 1509 4.2.2. stopped 1511 The stopped property indicates whether the transceiver has been 1512 stopped, either by a call to stopTransceiver or by applying an answer 1513 that rejects the associated m= section. In either of these cases, it 1514 is set to "true", and otherwise will be set to "false". 1516 A stopped RtpTransceiver does not send any outgoing RTP or RTCP or 1517 process any incoming RTP or RTCP. It cannot be restarted. 1519 4.2.3. setDirection 1521 The setDirection method sets the direction of a transceiver, which 1522 affects the direction property of the associated m= section on future 1523 calls to createOffer and createAnswer. 1525 When creating offers, the transceiver direction is directly reflected 1526 in the output, even for re-offers. When creating answers, the 1527 transceiver direction is intersected with the offered direction, as 1528 explained in Section 5.3 below. 1530 Note that while setDirection sets the direction property of the 1531 transceiver immediately (Section 4.2.4), this property does not 1532 immediately affect whether the transceiver's RtpSender will send or 1533 its RtpReceiver will receive. The direction in effect is represented 1534 by the currentDirection property, which is only updated when an 1535 answer is applied. 1537 4.2.4. direction 1539 The direction property indicates the last value passed into 1540 setDirection. If setDirection has never been called, it is set to 1541 the direction the transceiver was initialized with. 1543 4.2.5. currentDirection 1545 The currentDirection property indicates the last negotiated direction 1546 for the transceiver's associated m= section. More specifically, it 1547 indicates the [RFC3264] directional attribute of the associated m= 1548 section in the last applied answer, with "send" and "recv" directions 1549 reversed if it was a remote answer. For example, if the directional 1550 attribute for the associated m= section in a remote answer is 1551 "recvonly", currentDirection is set to "sendonly". 1553 If an answer that references this transceiver has not yet been 1554 applied, or if the transceiver is stopped, currentDirection is set to 1555 null. 1557 4.2.6. setCodecPreferences 1559 The setCodecPreferences method sets the codec preferences of a 1560 transceiver, which in turn affect the presence and order of codecs of 1561 the associated m= section on future calls to createOffer and 1562 createAnswer. Note that setCodecPreferences does not directly affect 1563 which codec the implementation decides to send. It only affects 1564 which codecs the implementation indicates that it prefers to receive, 1565 via the offer or answer. Even when a codec is excluded by 1566 setCodecPreferences, it still may be used to send until the next 1567 offer/answer exchange discards it. 1569 The codec preferences of an RtpTransceiver can cause codecs to be 1570 excluded by subsequent calls to createOffer and createAnswer, in 1571 which case the corresponding media formats in the associated m= 1572 section will be excluded. The codec preferences cannot add media 1573 formats that would otherwise not be present. 1575 The codec preferences of an RtpTransceiver can also determine the 1576 order of codecs in subsequent calls to createOffer and createAnswer, 1577 in which case the order of the media formats in the associated m= 1578 section will follow the specified preferences. 1580 5. SDP Interaction Procedures 1582 This section describes the specific procedures to be followed when 1583 creating and parsing SDP objects. 1585 5.1. Requirements Overview 1587 JSEP implementations must comply with the specifications listed below 1588 that govern the creation and processing of offers and answers. 1590 5.1.1. Usage Requirements 1592 All session descriptions handled by JSEP implementations, both local 1593 and remote, MUST indicate support for the following specifications. 1594 If any of these are absent, this omission MUST be treated as an 1595 error. 1597 o ICE, as specified in [RFC5245], MUST be used. Note that the 1598 remote endpoint may use a Lite implementation; implementations 1599 MUST properly handle remote endpoints which do ICE-Lite. 1601 o DTLS [RFC6347] or DTLS-SRTP [RFC5763], MUST be used, as 1602 appropriate for the media type, as specified in 1603 [I-D.ietf-rtcweb-security-arch] 1605 The SDES SRTP keying mechanism from [RFC4568] MUST NOT be used, as 1606 discussed in [I-D.ietf-rtcweb-security-arch]. 1608 5.1.2. Profile Names and Interoperability 1610 For media m= sections, JSEP implementations MUST support the 1611 "UDP/TLS/RTP/SAVPF" profile specified in [RFC7850], and MUST indicate 1612 this profile for each media m= line they produce in an offer. For 1613 data m= sections, implementations MUST support the "UDP/DTLS/SCTP" 1614 profile and MUST indicate this profile for each data m= line they 1615 produce in an offer. Because ICE can select either UDP [RFC5245] or 1616 TCP [RFC6544] transport depending on network conditions, this 1617 advertisement is consistent with ICE eventually selecting either 1618 either UDP or TCP. 1620 Unfortunately, in an attempt at compatibility, some endpoints 1621 generate other profile strings even when they mean to support one of 1622 these profiles. For instance, an endpoint might generate "RTP/AVP" 1623 but supply "a=fingerprint" and "a=rtcp-fb" attributes, indicating its 1624 willingness to support "UDP/TLS/RTP/SAVPF" or "TCP/TLS/RTP/SAVPF". 1625 In order to simplify compatibility with such endpoints, JSEP 1626 implementations MUST follow the following rules when processing the 1627 media m= sections in a received offer: 1629 o Any profile in the offer matching one of the following MUST be 1630 accepted: 1632 * "RTP/AVP" (Defined in [RFC4566], Section 8.2.2) 1634 * "RTP/AVPF" (Defined in [RFC4585], Section 9) 1636 * "RTP/SAVP" (Defined in [RFC3711], Section 12) 1638 * "RTP/SAVPF" (Defined in [RFC5124], Section 6) 1640 * "TCP/DTLS/RTP/SAVP" (Defined in [RFC7850], Section 3.4) 1642 * "TCP/DTLS/RTP/SAVPF" (Defined in [RFC7850], Section 3.5) 1644 * "UDP/TLS/RTP/SAVP" (Defined in [RFC5764], Section 9) 1646 * "UDP/TLS/RTP/SAVPF" (Defined in [RFC5764], Section 9) 1648 o The profile in any "m=" line in any generated answer MUST exactly 1649 match the profile provided in the offer. 1651 o Because DTLS-SRTP is REQUIRED, the choice of SAVP or AVP has no 1652 effect; support for DTLS-SRTP is determined by the presence of one 1653 or more "a=fingerprint" attribute. Note that lack of an 1654 "a=fingerprint" attribute will lead to negotiation failure. 1656 o The use of AVPF or AVP simply controls the timing rules used for 1657 RTCP feedback. If AVPF is provided, or an "a=rtcp-fb" attribute 1658 is present, assume AVPF timing, i.e., a default value of "trr- 1659 int=0". Otherwise, assume that AVPF is being used in an AVP 1660 compatible mode and use a value of "trr-int=4000". 1662 o For data m= sections, implementations MUST support receiving the 1663 "UDP/DTLS/SCTP", "TCP/DTLS/SCTP", or "DTLS/SCTP" (for backwards 1664 compatibility) profiles. 1666 Note that re-offers by JSEP implementations MUST use the correct 1667 profile strings even if the initial offer/answer exchange used an 1668 (incorrect) older profile string. 1670 5.2. Constructing an Offer 1672 When createOffer is called, a new SDP description must be created 1673 that includes the functionality specified in 1674 [I-D.ietf-rtcweb-rtp-usage]. The exact details of this process are 1675 explained below. 1677 5.2.1. Initial Offers 1679 When createOffer is called for the first time, the result is known as 1680 the initial offer. 1682 The first step in generating an initial offer is to generate session- 1683 level attributes, as specified in [RFC4566], Section 5. 1684 Specifically: 1686 o The first SDP line MUST be "v=0", as specified in [RFC4566], 1687 Section 5.1 1689 o The second SDP line MUST be an "o=" line, as specified in 1690 [RFC4566], Section 5.2. The value of the field SHOULD 1691 be "-". [RFC3264] requires that the be representable as 1692 a 64-bit signed integer. It is RECOMMENDED that the be 1693 generated as a 64-bit quantity with the high bit being sent to 1694 zero and the remaining 63 bits being cryptographically random. 1695 The value of the tuple 1696 SHOULD be set to a non-meaningful address, such as IN IP4 0.0.0.0, 1697 to prevent leaking the local address in this field. As mentioned 1698 in [RFC4566], the entire o= line needs to be unique, but selecting 1699 a random number for is sufficient to accomplish this. 1701 o The third SDP line MUST be a "s=" line, as specified in [RFC4566], 1702 Section 5.3; to match the "o=" line, a single dash SHOULD be used 1703 as the session name, e.g. "s=-". Note that this differs from the 1704 advice in [RFC4566] which proposes a single space, but as both 1705 "o=" and "s=" are meaningless in JSEP, having the same meaningless 1706 value seems clearer. 1708 o Session Information ("i="), URI ("u="), Email Address ("e="), 1709 Phone Number ("p="), Repeat Times ("r="), and Time Zones ("z=") 1710 lines are not useful in this context and SHOULD NOT be included. 1712 o Encryption Keys ("k=") lines do not provide sufficient security 1713 and MUST NOT be included. 1715 o A "t=" line MUST be added, as specified in [RFC4566], Section 5.9; 1716 both and SHOULD be set to zero, e.g. "t=0 1717 0". 1719 o An "a=ice-options" line with the "trickle" option MUST be added, 1720 as specified in [I-D.ietf-ice-trickle], Section 4. 1722 o If WebRTC identity is being used, an "a=identity" line as 1723 described in [I-D.ietf-rtcweb-security-arch], Section 5. 1725 The next step is to generate m= sections, as specified in [RFC4566], 1726 Section 5.14. An m= section is generated for each RtpTransceiver 1727 that has been added to the PeerConnection, excluding any stopped 1728 RtpTransceivers. This is done in the order the RtpTransceivers were 1729 added to the PeerConnection. 1731 For each m= section generated for an RtpTransceiver, establish a 1732 mapping between the transceiver and the index of the generated m= 1733 section. 1735 Each m= section, provided it is not marked as bundle-only, MUST 1736 generate a unique set of ICE credentials and gather its own unique 1737 set of ICE candidates. Bundle-only m= sections MUST NOT contain any 1738 ICE credentials and MUST NOT gather any candidates. 1740 For DTLS, all m= sections MUST use all the certificate(s) that have 1741 been specified for the PeerConnection; as a result, they MUST all 1742 have the same [RFC8122] fingerprint value(s), or these value(s) MUST 1743 be session-level attributes. 1745 Each m= section should be generated as specified in [RFC4566], 1746 Section 5.14. For the m= line itself, the following rules MUST be 1747 followed: 1749 o If the m= section is marked as bundle-only, then the port value 1750 MUST be set to 0. Otherwise, the port value is set to the port of 1751 the default ICE candidate for this m= section, but given that no 1752 candidates are available yet, the "dummy" port value of 9 1753 (Discard) MUST be used, as indicated in [I-D.ietf-ice-trickle], 1754 Section 5.1. 1756 o To properly indicate use of DTLS, the field MUST be set to 1757 "UDP/TLS/RTP/SAVPF", as specified in [RFC5764], Section 8. 1759 o If codec preferences have been set for the associated transceiver, 1760 media formats MUST be generated in the corresponding order, and 1761 MUST exclude any codecs not present in the codec preferences. 1763 o Unless excluded by the above restrictions, the media formats MUST 1764 include the mandatory audio/video codecs as specified in 1765 [RFC7874], Section 3, and [RFC7742], Section 5. 1767 The m= line MUST be followed immediately by a "c=" line, as specified 1768 in [RFC4566], Section 5.7. Again, as no candidates are available 1769 yet, the "c=" line must contain the "dummy" value "IN IP4 0.0.0.0", 1770 as defined in [I-D.ietf-ice-trickle], Section 5.1. 1772 [I-D.ietf-mmusic-sdp-mux-attributes] groups SDP attributes into 1773 different categories. To avoid unnecessary duplication when 1774 bundling, attributes of category IDENTICAL or TRANSPORT MUST NOT be 1775 repeated in bundled m= sections, repeating the guidance from 1776 [I-D.ietf-mmusic-sdp-bundle-negotiation], Section 8.1. This includes 1777 m= sections for which bundling has been negotiated and is still 1778 desired, as well as m= sections marked as bundle-only. 1780 The following attributes, which are of a category other than 1781 IDENTICAL or TRANSPORT, MUST be included in each m= section: 1783 o An "a=mid" line, as specified in [RFC5888], Section 4. All MID 1784 values MUST be generated in a fashion that does not leak user 1785 information, e.g., randomly or using a per-PeerConnection counter, 1786 and SHOULD be 3 bytes or less, to allow them to efficiently fit 1787 into the RTP header extension defined in 1788 [I-D.ietf-mmusic-sdp-bundle-negotiation], Section 14. Note that 1789 this does not set the RtpTransceiver mid property, as that only 1790 occurs when the description is applied. The generated MID value 1791 can be considered a "proposed" MID at this point. 1793 o A direction attribute which is the same as that of the associated 1794 transceiver. 1796 o For each media format on the m= line, "a=rtpmap" and "a=fmtp" 1797 lines, as specified in [RFC4566], Section 6, and [RFC3264], 1798 Section 5.1. 1800 o For each primary codec where RTP retransmission should be used, a 1801 corresponding "a=rtpmap" line indicating "rtx" with the clock rate 1802 of the primary codec and an "a=fmtp" line that references the 1803 payload type of the primary codec, as specified in [RFC4588], 1804 Section 8.1. 1806 o For each supported FEC mechanism, "a=rtpmap" and "a=fmtp" lines, 1807 as specified in [RFC4566], Section 6. The FEC mechanisms that 1808 MUST be supported are specified in [I-D.ietf-rtcweb-fec], 1809 Section 6, and specific usage for each media type is outlined in 1810 Sections 4 and 5. 1812 o If this m= section is for media with configurable durations of 1813 media per packet, e.g., audio, an "a=maxptime" line, indicating 1814 the maximum amount of media, specified in milliseconds, that can 1815 be encapsulated in each packet, as specified in [RFC4566], 1816 Section 6. This value is set to the smallest of the maximum 1817 duration values across all the codecs included in the m= section. 1819 o If this m= section is for video media, and there are known 1820 limitations on the size of images which can be decoded, an 1821 "a=imageattr" line, as specified in Section 3.6. 1823 o For each supported RTP header extension, an "a=extmap" line, as 1824 specified in [RFC5285], Section 5. The list of header extensions 1825 that SHOULD/MUST be supported is specified in 1826 [I-D.ietf-rtcweb-rtp-usage], Section 5.2. Any header extensions 1827 that require encryption MUST be specified as indicated in 1828 [RFC6904], Section 4. 1830 o For each supported RTCP feedback mechanism, an "a=rtcp-fb" line, 1831 as specified in [RFC4585], Section 4.2. The list of RTCP feedback 1832 mechanisms that SHOULD/MUST be supported is specified in 1833 [I-D.ietf-rtcweb-rtp-usage], Section 5.1. 1835 o If the RtpTransceiver has a sendrecv or sendonly direction: 1837 * For each MediaStream that was associated with the transceiver 1838 when it was created via addTrack or addTransceiver, an "a=msid" 1839 line, as specified in [I-D.ietf-mmusic-msid], Section 2. If a 1840 MediaStreamTrack is attached to the transceiver's RtpSender, 1841 the "a=msid" lines MUST use that track's ID. If no 1842 MediaStreamTrack is attached, a valid ID MUST be generated, in 1843 the same way that the implementation generates IDs for local 1844 tracks. 1846 * If no MediaStream is associated with the transceiver, a single 1847 "a=msid" line with the special value "-" in place of the 1848 MediaStream ID, as specified in [I-D.ietf-mmusic-msid], 1849 Section 3. The track ID MUST be selected as described above. 1851 o If the RtpTransceiver has a sendrecv or sendonly direction, and 1852 the application has specified RID values or has specified more 1853 than one encoding in the RtpSenders's parameters, an "a=rid" line 1854 for each encoding specified. The "a=rid" line is specified in 1855 [I-D.ietf-mmusic-rid], and its direction MUST be "send". If the 1856 application has chosen a RID value, it MUST be used as the rid- 1857 identifier; otherwise a RID value MUST be generated by the 1858 implementation. RID values MUST be generated in a fashion that 1859 does not leak user information, e.g., randomly or using a per- 1860 PeerConnection counter, and SHOULD be 3 bytes or less, to allow 1861 them to efficiently fit into the RTP header extension defined in 1862 [I-D.ietf-avtext-rid], Section 3. If no encodings have been 1863 specified, or only one encoding is specified but without a RID 1864 value, then no "a=rid" lines are generated. 1866 o If the RtpTransceiver has a sendrecv or sendonly direction and 1867 more than one "a=rid" line has been generated, an "a=simulcast" 1868 line, with direction "send", as defined in 1869 [I-D.ietf-mmusic-sdp-simulcast], Section 6.2. The list of RIDs 1870 MUST include all of the RID identifiers used in the "a=rid" lines 1871 for this m= section. 1873 o If the bundle policy for this PeerConnection is set to "max- 1874 bundle", and this is not the first m= section, or the bundle 1875 policy is set to "balanced", and this is not the first m= section 1876 for this media type, an "a=bundle-only" line. 1878 The following attributes, which are of category IDENTICAL or 1879 TRANSPORT, MUST appear only in "m=" sections which either have a 1880 unique address or which are associated with the bundle-tag. (In 1881 initial offers, this means those "m=" sections which do not contain 1882 an "a=bundle-only" attribute.) 1884 o "a=ice-ufrag" and "a=ice-pwd" lines, as specified in [RFC5245], 1885 Section 15.4. 1887 o For each desired digest algorithm, one or more "a=fingerprint" 1888 lines for each of the endpoint's certificates, as specified in 1889 [RFC8122], Section 5. 1891 o An "a=setup" line, as specified in [RFC4145], Section 4, and 1892 clarified for use in DTLS-SRTP scenarios in [RFC5763], Section 5. 1893 The role value in the offer MUST be "actpass". 1895 o An "a=tls-id" line, as specified in [I-D.ietf-mmusic-dtls-sdp], 1896 Section 5.2. 1898 o An "a=rtcp" line, as specified in [RFC3605], Section 2.1, 1899 containing the dummy value "9 IN IP4 0.0.0.0", because no 1900 candidates have yet been gathered. 1902 o An "a=rtcp-mux" line, as specified in [RFC5761], Section 5.1.3. 1904 o If the RTP/RTCP multiplexing policy is "require", an "a=rtcp-mux- 1905 only" line, as specified in [I-D.ietf-mmusic-mux-exclusive], 1906 Section 4. 1908 o An "a=rtcp-rsize" line, as specified in [RFC5506], Section 5. 1910 Lastly, if a data channel has been created, a m= section MUST be 1911 generated for data. The field MUST be set to "application" 1912 and the field MUST be set to "UDP/DTLS/SCTP" 1914 [I-D.ietf-mmusic-sctp-sdp]. The "fmt" value MUST be set to "webrtc- 1915 datachannel" as specified in [I-D.ietf-mmusic-sctp-sdp], Section 4.1. 1917 Within the data m= section, an "a=mid" line MUST be generated and 1918 included as described above, along with an "a=sctp-port" line 1919 referencing the SCTP port number, as defined in 1920 [I-D.ietf-mmusic-sctp-sdp], Section 5.1, and, if appropriate, an 1921 "a=max-message-size" line, as defined in [I-D.ietf-mmusic-sctp-sdp], 1922 Section 6.1. 1924 As discussed above, the following attributes of category IDENTICAL or 1925 TRANSPORT are included only if the data m= section either has a 1926 unique address or is associated with the bundle-tag (e.g., if it is 1927 the only m= section): 1929 o "a=ice-ufrag" 1931 o "a=ice-pwd" 1933 o "a=fingerprint" 1935 o "a=setup" 1937 o "a=tls-id" 1939 Once all m= sections have been generated, a session-level "a=group" 1940 attribute MUST be added as specified in [RFC5888]. This attribute 1941 MUST have semantics "BUNDLE", and MUST include the mid identifiers of 1942 each m= section. The effect of this is that the JSEP implementation 1943 offers all m= sections as one bundle group. However, whether the m= 1944 sections are bundle-only or not depends on the bundle policy. 1946 The next step is to generate session-level lip sync groups as defined 1947 in [RFC5888], Section 7. For each MediaStream referenced by more 1948 than one RtpTransceiver (by passing those MediaStreams as arguments 1949 to the addTrack and addTransceiver methods), a group of type "LS" 1950 MUST be added that contains the mid values for each RtpTransceiver. 1952 Attributes which SDP permits to either be at the session level or the 1953 media level SHOULD generally be at the media level even if they are 1954 identical. This assists development and debugging by making it 1955 easier to understand individual media sections, especially if one of 1956 a set of initially identical attributes is subsequently changed. 1957 However, implementations MAY choose to aggregate attributes at the 1958 session level and JSEP implementations MUST be prepared to receive 1959 attributes in either location. 1961 Attributes other than the ones specified above MAY be included, 1962 except for the following attributes which are specifically 1963 incompatible with the requirements of [I-D.ietf-rtcweb-rtp-usage], 1964 and MUST NOT be included: 1966 o "a=crypto" 1968 o "a=key-mgmt" 1970 o "a=ice-lite" 1972 Note that when bundle is used, any additional attributes that are 1973 added MUST follow the advice in [I-D.ietf-mmusic-sdp-mux-attributes] 1974 on how those attributes interact with bundle. 1976 Note that these requirements are in some cases stricter than those of 1977 SDP. Implementations MUST be prepared to accept compliant SDP even 1978 if it would not conform to the requirements for generating SDP in 1979 this specification. 1981 5.2.2. Subsequent Offers 1983 When createOffer is called a second (or later) time, or is called 1984 after a local description has already been installed, the processing 1985 is somewhat different than for an initial offer. 1987 If the previous offer was not applied using setLocalDescription, 1988 meaning the PeerConnection is still in the "stable" state, the steps 1989 for generating an initial offer should be followed, subject to the 1990 following restriction: 1992 o The fields of the "o=" line MUST stay the same except for the 1993 field, which MUST increment by one on each call 1994 to createOffer if the offer might differ from the output of the 1995 previous call to createOffer; implementations MAY opt to increment 1996 on every call. The value of the generated 1997 is independent of the of the 1998 current local description; in particular, in the case where the 1999 current version is N, an offer is created and applied with version 2000 N+1, and then that offer is rolled back so that the current 2001 version is again N, the next generated offer will still have 2002 version N+2. 2004 Note that if the application creates an offer by reading 2005 currentLocalDescription instead of calling createOffer, the returned 2006 SDP may be different than when setLocalDescription was originally 2007 called, due to the addition of gathered ICE candidates, but the 2008 will not have changed. There are no known 2009 scenarios in which this causes problems, but if this is a concern, 2010 the solution is simply to use createOffer to ensure a unique 2011 . 2013 If the previous offer was applied using setLocalDescription, but a 2014 corresponding answer from the remote side has not yet been applied, 2015 meaning the PeerConnection is still in the "have-local-offer" state, 2016 an offer is generated by following the steps in the "stable" state 2017 above, along with these exceptions: 2019 o The "s=" and "t=" lines MUST stay the same. 2021 o If any RtpTransceiver has been added, and there exists an m= 2022 section with a zero port in the current local description or the 2023 current remote description, that m= section MUST be recycled by 2024 generating an m= section for the added RtpTransceiver as if the m= 2025 section were being added to the session description (including a 2026 new MID value), and placing it at the same index as the m= section 2027 with a zero port. 2029 o If an RtpTransceiver is stopped and is not associated with an m= 2030 section, an m= section MUST NOT be generated for it. This 2031 prevents adding back RtpTransceivers whose m= sections were 2032 recycled and used for a new RtpTransceiver in a previous offer/ 2033 answer exchange, as described above. 2035 o If an RtpTransceiver has been stopped and is associated with an m= 2036 section, and the m= section is not being recycled as described 2037 above, an m= section MUST be generated for it with the port set to 2038 zero and all "a=msid" lines removed. 2040 o For RtpTransceivers that are not stopped, the "a=msid" line(s) 2041 MUST stay the same if they are present in the current description, 2042 regardless of changes to the transceiver's direction or track. If 2043 no "a=msid" line is present in the current description, "a=msid" 2044 line(s) MUST be generated according to the same rules as for an 2045 initial offer. 2047 o Each "m=" and c=" line MUST be filled in with the port, protocol, 2048 and address of the default candidate for the m= section, as 2049 described in [RFC5245], Section 4.3. If ICE checking has already 2050 completed for one or more candidate pairs and a candidate pair is 2051 in active use, then that pair MUST be used, even if ICE has not 2052 yet completed. Note that this differs from the guidance in 2053 [RFC5245], Section 9.1.2.2, which only refers to offers created 2054 when ICE has completed. In each case, if no RTP candidates have 2055 yet been gathered, dummy values MUST be used, as described above. 2057 o Each "a=mid" line MUST stay the same. 2059 o Each "a=ice-ufrag" and "a=ice-pwd" line MUST stay the same, unless 2060 the ICE configuration has changed (either changes to the supported 2061 STUN/TURN servers, or the ICE candidate policy), or the 2062 "IceRestart" option ( Section 5.2.3.1 was specified. If the m= 2063 section is bundled into another m= section, it still MUST NOT 2064 contain any ICE credentials. 2066 o If the m= section is not bundled into another m= section, its 2067 "a=rtcp" attribute line MUST be filled in with the port and 2068 address of the default RTCP candidate, as indicated in [RFC5761], 2069 Section 5.1.3. If no RTCP candidates have yet been gathered, 2070 dummy values MUST be used, as described in the initial offer 2071 section above. 2073 o If the m= section is not bundled into another m= section, for each 2074 candidate that has been gathered during the most recent gathering 2075 phase (see Section 3.5.1), an "a=candidate" line MUST be added, as 2076 defined in [RFC5245], Section 4.3., paragraph 3. If candidate 2077 gathering for the section has completed, an "a=end-of-candidates" 2078 attribute MUST be added, as described in [I-D.ietf-ice-trickle], 2079 Section 9.3. If the m= section is bundled into another m= 2080 section, both "a=candidate" and "a=end-of-candidates" MUST be 2081 omitted. 2083 o For RtpTransceivers that are still present, the "a=rid" lines MUST 2084 stay the same. 2086 o For RtpTransceivers that are still present, any "a=simulcast" line 2087 MUST stay the same. 2089 If the previous offer was applied using setLocalDescription, and a 2090 corresponding answer from the remote side has been applied using 2091 setRemoteDescription, meaning the PeerConnection is in the "have- 2092 remote-pranswer" or "stable" states, an offer is generated based on 2093 the negotiated session descriptions by following the steps mentioned 2094 for the "have-local-offer" state above. 2096 In addition, for each existing, non-recycled, non-rejected m= section 2097 in the new offer, the following adjustments are made based on the 2098 contents of the corresponding m= section in the current local or 2099 remote description, as appropriate: 2101 o The m= line and corresponding "a=rtpmap" and "a=fmtp" lines MUST 2102 only include media formats which have not been excluded by the 2103 codec preferences of the associated transceiver, and MUST include 2104 all currently available formats. Media formats that were 2105 previously offered but are no longer available (e.g., a shared 2106 hardware codec) MAY be excluded. 2108 o Unless codec preferences have been set for the associated 2109 transceiver, the media formats on the m= line MUST be generated in 2110 the same order as in the most recent answer. Any media formats 2111 that were not present in the most recent answer MUST be added 2112 after all existing formats. 2114 o The RTP header extensions MUST only include those that are present 2115 in the most recent answer. 2117 o The RTCP feedback mechanisms MUST only include those that are 2118 present in the most recent answer, except for the case of format- 2119 specific mechanisms that are referencing a newly-added media 2120 format. 2122 o The "a=rtcp" line MUST NOT be added if the most recent answer 2123 included an "a=rtcp-mux" line. 2125 o The "a=rtcp-mux" line MUST be the same as that in the most recent 2126 answer. 2128 o The "a=rtcp-mux-only" line MUST NOT be added. 2130 o The "a=rtcp-rsize" line MUST NOT be added unless present in the 2131 most recent answer. 2133 o An "a=bundle-only" line MUST NOT be added, as indicated in 2134 [I-D.ietf-mmusic-sdp-bundle-negotiation], Section 6. Instead, 2135 JSEP implementations MUST simply omit parameters in the IDENTICAL 2136 and TRANSPORT categories for bundled m= sections, as described in 2137 [I-D.ietf-mmusic-sdp-bundle-negotiation], Section 8.1. 2139 o Note that if media m= sections are bundled into a data m= section, 2140 then certain TRANSPORT and IDENTICAL attributes may appear in the 2141 data m= section even if they would otherwise only be appropriate 2142 for a media m= section (e.g., "a=rtcp-mux"). This cannot happen 2143 in initial offers because in the initial offer JSEP 2144 implementations always list media m= sections (if any) before the 2145 data m= section (if any), and at least one of those media m= 2146 sections will not have the "a=bundle-only" attribute. Therefore, 2147 in initial offers, any "a=bundle-only" m= sections will be bundled 2148 into a preceding non-bundle-only media m= section. 2150 The "a=group:BUNDLE" attribute MUST include the MID identifiers 2151 specified in the bundle group in the most recent answer, minus any m= 2152 sections that have been marked as rejected, plus any newly added or 2153 re-enabled m= sections. In other words, the bundle attribute must 2154 contain all m= sections that were previously bundled, as long as they 2155 are still alive, as well as any new m= sections. 2157 "a=group:LS" attributes are generated in the same way as for initial 2158 offers, with the additional stipulation that any lip sync groups that 2159 were present in the most recent answer MUST continue to exist and 2160 MUST contain any previously existing MID identifiers, as long as the 2161 identified m= sections still exist and are not rejected, and the 2162 group still contains at least two MID identifiers. This ensures that 2163 any synchronized "recvonly" m= sections continue to be synchronized 2164 in the new offer. 2166 5.2.3. Options Handling 2168 The createOffer method takes as a parameter an RTCOfferOptions 2169 object. Special processing is performed when generating a SDP 2170 description if the following options are present. 2172 5.2.3.1. IceRestart 2174 If the "IceRestart" option is specified, with a value of "true", the 2175 offer MUST indicate an ICE restart by generating new ICE ufrag and 2176 pwd attributes, as specified in [RFC5245], Section 9.1.1.1. If this 2177 option is specified on an initial offer, it has no effect (since a 2178 new ICE ufrag and pwd are already generated). Similarly, if the ICE 2179 configuration has changed, this option has no effect, since new ufrag 2180 and pwd attributes will be generated automatically. This option is 2181 primarily useful for reestablishing connectivity in cases where 2182 failures are detected by the application. 2184 5.2.3.2. VoiceActivityDetection 2186 Silence suppression, also known as discontinuous transmission 2187 ("DTX"), can reduce the bandwidth used for audio by switching to a 2188 special encoding when voice activity is not detected, at the cost of 2189 some fidelity. 2191 If the "VoiceActivityDetection" option is specified, with a value of 2192 "true", the offer MUST indicate support for silence suppression in 2193 the audio it receives by including comfort noise ("CN") codecs for 2194 each offered audio codec, as specified in [RFC3389], Section 5.1, 2195 except for codecs that have their own internal silence suppression 2196 support. For codecs that have their own internal silence suppression 2197 support, the appropriate fmtp parameters for that codec MUST be 2198 specified to indicate that silence suppression for received audio is 2199 desired. For example, when using the Opus codec [RFC6716], the 2200 "usedtx=1" parameter, specified in [RFC7587], would be used in the 2201 offer. 2203 If the "VoiceActivityDetection" option is specified, with a value of 2204 "false", the JSEP implementation MUST NOT emit "CN" codecs. For 2205 codecs that have their own internal silence suppression support, the 2206 appropriate fmtp parameters for that codec MUST be specified to 2207 indicate that silence suppression for received audio is not desired. 2208 For example, when using the Opus codec, the "usedtx=0" parameter 2209 would be specified in the offer. In addition, the implementation 2210 MUST NOT use silence suppression for media it generates, regardless 2211 of whether the "CN" codecs or related fmtp parameters appear in the 2212 peer's description. The impact of these rules is that silence 2213 suppression in JSEP depends on mutual agreement of both sides, which 2214 ensures consistent handling regardless of which codec is used. 2216 The "VoiceActivityDetection" option does not have any impact on the 2217 setting of the "vad" value in the signaling of the client to mixer 2218 audio level header extension described in [RFC6464], Section 4. 2220 5.3. Generating an Answer 2222 When createAnswer is called, a new SDP description must be created 2223 that is compatible with the supplied remote description as well as 2224 the requirements specified in [I-D.ietf-rtcweb-rtp-usage]. The exact 2225 details of this process are explained below. 2227 5.3.1. Initial Answers 2229 When createAnswer is called for the first time after a remote 2230 description has been provided, the result is known as the initial 2231 answer. If no remote description has been installed, an answer 2232 cannot be generated, and an error MUST be returned. 2234 Note that the remote description SDP may not have been created by a 2235 JSEP endpoint and may not conform to all the requirements listed in 2236 Section 5.2. For many cases, this is not a problem. However, if any 2237 mandatory SDP attributes are missing, or functionality listed as 2238 mandatory-to-use above is not present, this MUST be treated as an 2239 error, and MUST cause the affected m= sections to be marked as 2240 rejected. 2242 The first step in generating an initial answer is to generate 2243 session-level attributes. The process here is identical to that 2244 indicated in the initial offers section above, except that the 2245 "a=ice-options" line, with the "trickle" option as specified in 2246 [I-D.ietf-ice-trickle], Section 4, is only included if such an option 2247 was present in the offer. 2249 The next step is to generate session-level lip sync groups, as 2250 defined in [RFC5888], Section 7. For each group of type "LS" present 2251 in the offer, select the local RtpTransceivers that are referenced by 2252 the MID values in the specified group, and determine which of them 2253 either reference a common local MediaStream (specified in the calls 2254 to addTrack/addTransceiver used to create them), or have no 2255 MediaStream to reference because they were not created by addTrack/ 2256 addTransceiver. If at least two such RtpTransceivers exist, a group 2257 of type "LS" with the mid values of these RtpTransceivers MUST be 2258 added. Otherwise the offered "LS" group MUST be ignored and no 2259 corresponding group generated in the answer. 2261 As a simple example, consider the following offer of a single audio 2262 and single video track contained in the same MediaStream. SDP lines 2263 not relevant to this example have been removed for clarity. As 2264 explained in Section 5.2, a group of type "LS" has been added that 2265 references each track's RtpTransceiver. 2267 a=group:LS a1 v1 2268 m=audio 10000 UDP/TLS/RTP/SAVPF 0 2269 a=mid:a1 2270 a=msid:ms1 mst1a 2271 m=video 10001 UDP/TLS/RTP/SAVPF 96 2272 a=mid:v1 2273 a=msid:ms1 mst1v 2275 If the answerer uses a single MediaStream when it adds its tracks, 2276 both of its transceivers will reference this stream, and so the 2277 subsequent answer will contain a "LS" group identical to that in the 2278 offer, as shown below: 2280 a=group:LS a1 v1 2281 m=audio 20000 UDP/TLS/RTP/SAVPF 0 2282 a=mid:a1 2283 a=msid:ms2 mst2a 2284 m=video 20001 UDP/TLS/RTP/SAVPF 96 2285 a=mid:v1 2286 a=msid:ms2 mst2v 2288 However, if the answerer groups its tracks into separate 2289 MediaStreams, its transceivers will reference different streams, and 2290 so the subsequent answer will not contain a "LS" group. 2292 m=audio 20000 UDP/TLS/RTP/SAVPF 0 2293 a=mid:a1 2294 a=msid:ms2a mst2a 2295 m=video 20001 UDP/TLS/RTP/SAVPF 96 2296 a=mid:v1 2297 a=msid:ms2b mst2v 2299 Finally, if the answerer does not add any tracks, its transceivers 2300 will not reference any MediaStreams, causing the preferences of the 2301 offerer to be maintained, and so the subsequent answer will contain 2302 an identical "LS" group. 2304 a=group:LS a1 v1 2305 m=audio 20000 UDP/TLS/RTP/SAVPF 0 2306 a=mid:a1 2307 a=recvonly 2308 m=video 20001 UDP/TLS/RTP/SAVPF 96 2309 a=mid:v1 2310 a=recvonly 2312 The Section 7.2 example later in this document shows a more involved 2313 case of "LS" group generation. 2315 The next step is to generate m= sections for each m= section that is 2316 present in the remote offer, as specified in [RFC3264], Section 6. 2317 For the purposes of this discussion, any session-level attributes in 2318 the offer that are also valid as media-level attributes are 2319 considered to be present in each m= section. 2321 The next step is to go through each offered m= section. Each offered 2322 m= section will have an associated RtpTransceiver, as described in 2323 Section 5.9. If there are more RtpTransceivers than there are m= 2324 sections, the unmatched RtpTransceivers will need to be associated in 2325 a subsequent offer. 2327 For each offered m= section, if any of the following conditions are 2328 true, the corresponding m= section in the answer MUST be marked as 2329 rejected by setting the port in the m= line to zero, as indicated in 2330 [RFC3264], Section 6, and further processing for this m= section can 2331 be skipped: 2333 o The associated RtpTransceiver has been stopped. 2335 o None of the offered media formats are supported and, if 2336 applicable, allowed by codec preferences. 2338 o The bundle policy is "max-bundle", and this is not the first m= 2339 section or in the same bundle group as the first m= section. 2341 o The bundle policy is "balanced", and this is not the first m= 2342 section for this media type or in the same bundle group as the 2343 first m= section for this media type. 2345 Otherwise, each m= section in the answer should then be generated as 2346 specified in [RFC3264], Section 6.1. For the m= line itself, the 2347 following rules must be followed: 2349 o The port value would normally be set to the port of the default 2350 ICE candidate for this m= section, but given that no candidates 2351 are available yet, the "dummy" port value of 9 (Discard) MUST be 2352 used, as indicated in [I-D.ietf-ice-trickle], Section 5.1. 2354 o The field MUST be set to exactly match the field 2355 for the corresponding m= line in the offer. 2357 o If codec preferences have been set for the associated transceiver, 2358 media formats MUST be generated in the corresponding order, 2359 regardless of what was offered, and MUST exclude any codecs not 2360 present in the codec preferences. 2362 o Otherwise, the media formats on the m= line MUST be generated in 2363 the same order as those offered in the current remote description, 2364 excluding any currently unsupported formats. Any currently 2365 available media formats that are not present in the current remote 2366 description MUST be added after all existing formats. 2368 o In either case, the media formats in the answer MUST include at 2369 least one format that is present in the offer, but MAY include 2370 formats that are locally supported but not present in the offer, 2371 as mentioned in [RFC3264], Section 6.1. If no common format 2372 exists, the m= section is rejected as described above. 2374 The m= line MUST be followed immediately by a "c=" line, as specified 2375 in [RFC4566], Section 5.7. Again, as no candidates are available 2376 yet, the "c=" line must contain the "dummy" value "IN IP4 0.0.0.0", 2377 as defined in [I-D.ietf-ice-trickle], Section 5.1. 2379 If the offer supports bundle, all m= sections to be bundled must use 2380 the same ICE credentials and candidates; all m= sections not being 2381 bundled must use unique ICE credentials and candidates. Each m= 2382 section MUST contain the following attributes (which are of attribute 2383 types other than IDENTICAL and TRANSPORT): 2385 o If and only if present in the offer, an "a=mid" line, as specified 2386 in [RFC5888], Section 9.1. The "mid" value MUST match that 2387 specified in the offer. 2389 o A direction attribute, determined by applying the rules regarding 2390 the offered direction specified in [RFC3264], Section 6.1, and 2391 then intersecting with the direction of the associated 2392 RtpTransceiver. For example, in the case where an m= section is 2393 offered as "sendonly", and the local transceiver is set to 2394 "sendrecv", the result in the answer is a "recvonly" direction. 2396 o For each media format on the m= line, "a=rtpmap" and "a=fmtp" 2397 lines, as specified in [RFC4566], Section 6, and [RFC3264], 2398 Section 6.1. 2400 o If "rtx" is present in the offer, for each primary codec where RTP 2401 retransmission should be used, a corresponding "a=rtpmap" line 2402 indicating "rtx" with the clock rate of the primary codec and an 2403 "a=fmtp" line that references the payload type of the primary 2404 codec, as specified in [RFC4588], Section 8.1. 2406 o For each supported FEC mechanism, "a=rtpmap" and "a=fmtp" lines, 2407 as specified in [RFC4566], Section 6. The FEC mechanisms that 2408 MUST be supported are specified in [I-D.ietf-rtcweb-fec], 2409 Section 6, and specific usage for each media type is outlined in 2410 Sections 4 and 5. 2412 o If this m= section is for media with configurable durations of 2413 media per packet, e.g., audio, an "a=maxptime" line, as described 2414 in Section 5.2. 2416 o If this m= section is for video media, and there are known 2417 limitations on the size of images which can be decoded, an 2418 "a=imageattr" line, as specified in Section 3.6. 2420 o For each supported RTP header extension that is present in the 2421 offer, an "a=extmap" line, as specified in [RFC5285], Section 5. 2422 The list of header extensions that SHOULD/MUST be supported is 2423 specified in [I-D.ietf-rtcweb-rtp-usage], Section 5.2. Any header 2424 extensions that require encryption MUST be specified as indicated 2425 in [RFC6904], Section 4. 2427 o For each supported RTCP feedback mechanism that is present in the 2428 offer, an "a=rtcp-fb" line, as specified in [RFC4585], 2429 Section 4.2. The list of RTCP feedback mechanisms that SHOULD/ 2430 MUST be supported is specified in [I-D.ietf-rtcweb-rtp-usage], 2431 Section 5.1. 2433 o If the RtpTransceiver has a sendrecv or sendonly direction: 2435 * For each MediaStream that was associated with the transceiver 2436 when it was created via addTrack or addTransceiver, an "a=msid" 2437 line, as specified in [I-D.ietf-mmusic-msid], Section 2. If a 2438 MediaStreamTrack is attached to the transceiver's RtpSender, 2439 the "a=msid" lines MUST use that track's ID. If no 2440 MediaStreamTrack is attached, a valid ID MUST be generated, in 2441 the same way that the implementation generates IDs for local 2442 tracks. 2444 * If no MediaStream is associated with the transceiver, a single 2445 "a=msid" line with the special value "-" in place of the 2446 MediaStream ID, as specified in [I-D.ietf-mmusic-msid], 2447 Section 3. The track ID MUST be selected as described above. 2449 Each m= section which is not bundled into another m= section, MUST 2450 contain the following attributes (which are of category IDENTICAL or 2451 TRANSPORT): 2453 o "a=ice-ufrag" and "a=ice-pwd" lines, as specified in [RFC5245], 2454 Section 15.4. 2456 o For each desired digest algorithm, one or more "a=fingerprint" 2457 lines for each of the endpoint's certificates, as specified in 2458 [RFC8122], Section 5. 2460 o An "a=setup" line, as specified in [RFC4145], Section 4, and 2461 clarified for use in DTLS-SRTP scenarios in [RFC5763], Section 5. 2462 The role value in the answer MUST be "active" or "passive". When 2463 the offer contains the "actpass" value, as will always be the case 2464 with JSEP endpoints, the answerer SHOULD use the "active" role. 2465 Offers from non-JSEP endpoints MAY send other values for 2466 "a=setup", in which case the answer MUST use a value consistent 2467 with the value in the offer. 2469 o An "a=tls-id" line, as specified in [I-D.ietf-mmusic-dtls-sdp], 2470 Section 5.3. 2472 o If present in the offer, an "a=rtcp-mux" line, as specified in 2473 [RFC5761], Section 5.1.3. Otherwise, an "a=rtcp" line, as 2474 specified in [RFC3605], Section 2.1, containing the dummy value "9 2475 IN IP4 0.0.0.0" (because no candidates have yet been gathered). 2477 o If present in the offer, an "a=rtcp-rsize" line, as specified in 2478 [RFC5506], Section 5. 2480 If a data channel m= section has been offered, a m= section MUST also 2481 be generated for data. The field MUST be set to 2482 "application" and the and fields MUST be set to exactly 2483 match the fields in the offer. 2485 Within the data m= section, an "a=mid" line MUST be generated and 2486 included as described above, along with an "a=sctp-port" line 2487 referencing the SCTP port number, as defined in 2488 [I-D.ietf-mmusic-sctp-sdp], Section 5.1, and, if appropriate, an 2489 "a=max-message-size" line, as defined in [I-D.ietf-mmusic-sctp-sdp], 2490 Section 6.1. 2492 As discussed above, the following attributes of category IDENTICAL or 2493 TRANSPORT are included only if the data m= section is not bundled 2494 into another m= section: 2496 o "a=ice-ufrag" 2498 o "a=ice-pwd" 2500 o "a=fingerprint" 2502 o "a=setup" 2504 o "a=tls-id" 2506 Note that if media m= sections are bundled into a data m= section, 2507 then certain TRANSPORT and IDENTICAL attributes may also appear in 2508 the data m= section even if they would otherwise only be appropriate 2509 for a media m= section (e.g., "a=rtcp-mux"). 2511 If "a=group" attributes with semantics of "BUNDLE" are offered, 2512 corresponding session-level "a=group" attributes MUST be added as 2513 specified in [RFC5888]. These attributes MUST have semantics 2514 "BUNDLE", and MUST include the all mid identifiers from the offered 2515 bundle groups that have not been rejected. Note that regardless of 2516 the presence of "a=bundle-only" in the offer, no m= sections in the 2517 answer should have an "a=bundle-only" line. 2519 Attributes that are common between all m= sections MAY be moved to 2520 session-level, if explicitly defined to be valid at session-level. 2522 The attributes prohibited in the creation of offers are also 2523 prohibited in the creation of answers. 2525 5.3.2. Subsequent Answers 2527 When createAnswer is called a second (or later) time, or is called 2528 after a local description has already been installed, the processing 2529 is somewhat different than for an initial answer. 2531 If the previous answer was not applied using setLocalDescription, 2532 meaning the PeerConnection is still in the "have-remote-offer" state, 2533 the steps for generating an initial answer should be followed, 2534 subject to the following restriction: 2536 o The fields of the "o=" line MUST stay the same except for the 2537 field, which MUST increment if the session 2538 description changes in any way from the previously generated 2539 answer. 2541 If any session description was previously supplied to 2542 setLocalDescription, an answer is generated by following the steps in 2543 the "have-remote-offer" state above, along with these exceptions: 2545 o The "s=" and "t=" lines MUST stay the same. 2547 o Each "m=" and c=" line MUST be filled in with the port and address 2548 of the default candidate for the m= section, as described in 2549 [RFC5245], Section 4.3. Note, however, that the m= line protocol 2550 need not match the default candidate, because this protocol value 2551 must instead match what was supplied in the offer, as described 2552 above. 2554 o Each "a=ice-ufrag" and "a=ice-pwd" line MUST stay the same, unless 2555 the m= section is restarting, in which case new ICE credentials 2556 must be created as specified in [RFC5245], Section 9.2.1.1. If 2557 the m= section is bundled into another m= section, it still MUST 2558 NOT contain any ICE credentials. 2560 o Each "a=setup" line MUST use an "active" or "passive" role value 2561 consistent with the existing DTLS association, if the association 2562 is being continued by the offerer. 2564 o RTCP multiplexing must be used, and an "a=rtcp-mux" line inserted 2565 if and only if the m= section previously used RTCP multiplexing. 2567 o If the m= section is not bundled into another m= section and RTCP 2568 multiplexing is not active, an "a=rtcp" attribute line MUST be 2569 filled in with the port and address of the default RTCP candidate. 2570 If no RTCP candidates have yet been gathered, dummy values MUST be 2571 used, as described in the initial answer section above. 2573 o If the m= section is not bundled into another m= section, for each 2574 candidate that has been gathered during the most recent gathering 2575 phase (see Section 3.5.1), an "a=candidate" line MUST be added, as 2576 defined in [RFC5245], Section 4.3., paragraph 3. If candidate 2577 gathering for the section has completed, an "a=end-of-candidates" 2578 attribute MUST be added, as described in [I-D.ietf-ice-trickle], 2579 Section 9.3. If the m= section is bundled into another m= 2580 section, both "a=candidate" and "a=end-of-candidates" MUST be 2581 omitted. 2583 o For RtpTransceivers that are not stopped, the "a=msid" line(s) 2584 MUST stay the same, regardless of changes to the transceiver's 2585 direction or track. If no "a=msid" line is present in the current 2586 description, "a=msid" line(s) MUST be generated according to the 2587 same rules as for an initial answer. 2589 5.3.3. Options Handling 2591 The createAnswer method takes as a parameter an RTCAnswerOptions 2592 object. The set of parameters for RTCAnswerOptions is different than 2593 those supported in RTCOfferOptions; the IceRestart option is 2594 unnecessary, as ICE credentials will automatically be changed for all 2595 m= sections where the offerer chose to perform ICE restart. 2597 The following options are supported in RTCAnswerOptions. 2599 5.3.3.1. VoiceActivityDetection 2601 Silence suppression in the answer is handled as described in 2602 Section 5.2.3.2, with one exception: if support for silence 2603 suppression was not indicated in the offer, the 2604 VoiceActivityDetection parameter has no effect, and the answer should 2605 be generated as if VoiceActivityDetection was set to false. This is 2606 done on a per-codec basis (e.g., if the offerer somehow offered 2607 support for CN but set "usedtx=0" for Opus, setting 2608 VoiceActivityDetection to true would result in an answer with CN 2609 codecs and "usedtx=0"). The impact of this rule is that an answerer 2610 will not try to use silence suppression with any endpoint that does 2611 not offer it, making silence suppression support bilateral even with 2612 non-JSEP endpoints. 2614 5.4. Modifying an Offer or Answer 2616 The SDP returned from createOffer or createAnswer MUST NOT be changed 2617 before passing it to setLocalDescription. If precise control over 2618 the SDP is needed, the aforementioned createOffer/createAnswer 2619 options or RtpTransceiver APIs MUST be used. 2621 Note that the application MAY modify the SDP to reduce the 2622 capabilities in the offer it sends to the far side (post- 2623 setLocalDescription) or the offer that it installs from the far side 2624 (pre-setRemoteDescription), as long as it remains a valid SDP offer 2625 and specifies a subset of what was in the original offer. This is 2626 safe because the answer is not permitted to expand capabilities, and 2627 therefore will just respond to what is present in the offer. 2629 The application SHOULD NOT modify the SDP in the answer it transmits, 2630 as the answer contains the negotiated capabilities, and this can 2631 cause the two sides to have different ideas about what exactly was 2632 negotiated. 2634 As always, the application is solely responsible for what it sends to 2635 the other party, and all incoming SDP will be processed by the JSEP 2636 implementation to the extent of its capabilities. It is an error to 2637 assume that all SDP is well-formed; however, one should be able to 2638 assume that any implementation of this specification will be able to 2639 process, as a remote offer or answer, unmodified SDP coming from any 2640 other implementation of this specification. 2642 5.5. Processing a Local Description 2644 When a SessionDescription is supplied to setLocalDescription, the 2645 following steps MUST be performed: 2647 o If the description is of type "rollback", follow the processing 2648 defined in Section 4.1.8.2 and skip the processing described in 2649 the rest of this section. 2651 o Otherwise, the type of the SessionDescription is checked against 2652 the current state of the PeerConnection: 2654 * If the type is "offer", the PeerConnection state MUST be either 2655 "stable" or "have-local-offer". 2657 * If the type is "pranswer" or "answer", the PeerConnection state 2658 MUST be either "have-remote-offer" or "have-local-pranswer". 2660 o If the type is not correct for the current state, processing MUST 2661 stop and an error MUST be returned. 2663 o The SessionDescription is then checked to ensure that its contents 2664 are identical to those generated in the last call to createOffer/ 2665 createAnswer, and thus have not been altered, as discussed in 2666 Section 5.4; otherwise, processing MUST stop and an error MUST be 2667 returned. 2669 o Next, the SessionDescription is parsed into a data structure, as 2670 described in Section 5.7 below. 2672 o Finally, the parsed SessionDescription is applied as described in 2673 Section 5.8 below. 2675 5.6. Processing a Remote Description 2677 When a SessionDescription is supplied to setRemoteDescription, the 2678 following steps MUST be performed: 2680 o If the description is of type "rollback", follow the processing 2681 defined in Section 4.1.8.2 and skip the processing described in 2682 the rest of this section. 2684 o Otherwise, the type of the SessionDescription is checked against 2685 the current state of the PeerConnection: 2687 * If the type is "offer", the PeerConnection state MUST be either 2688 "stable" or "have-remote-offer". 2690 * If the type is "pranswer" or "answer", the PeerConnection state 2691 MUST be either "have-local-offer" or "have-remote-pranswer". 2693 o If the type is not correct for the current state, processing MUST 2694 stop and an error MUST be returned. 2696 o Next, the SessionDescription is parsed into a data structure, as 2697 described in Section 5.7 below. If parsing fails for any reason, 2698 processing MUST stop and an error MUST be returned. 2700 o Finally, the parsed SessionDescription is applied as described in 2701 Section 5.9 below. 2703 5.7. Parsing a Session Description 2705 The SDP contained in the session description object consists of a 2706 sequence of text lines, each containing a key-value expression, as 2707 described in [RFC4566], Section 5. The SDP is read, line-by-line, 2708 and converted to a data structure that contains the deserialized 2709 information. However, SDP allows many types of lines, not all of 2710 which are relevant to JSEP applications. For each line, the 2711 implementation will first ensure it is syntactically correct 2712 according to its defining ABNF, check that it conforms to [RFC4566] 2713 and [RFC3264] semantics, and then either parse and store or discard 2714 the provided value, as described below. 2716 If any line is not well-formed, or cannot be parsed as described, the 2717 parser MUST stop with an error and reject the session description, 2718 even if the value is to be discarded. This ensures that 2719 implementations do not accidentally misinterpret ambiguous SDP. 2721 5.7.1. Session-Level Parsing 2723 First, the session-level lines are checked and parsed. These lines 2724 MUST occur in a specific order, and with a specific syntax, as 2725 defined in [RFC4566], Section 5. Note that while the specific line 2726 types (e.g. "v=", "c=") MUST occur in the defined order, lines of the 2727 same type (typically "a=") can occur in any order. 2729 The following non-attribute lines are not meaningful in the JSEP 2730 context and MAY be discarded once they have been checked. 2732 The "c=" line MUST be checked for syntax but its value is only 2733 used for ICE mismatch detection, as defined in [RFC5245], 2734 Section 6.1. Note that JSEP implementations should never 2735 encounter this condition because ICE is required for WebRTC. 2737 The "i=", "u=", "e=", "p=", "t=", "r=", "z=", and "k=" lines are 2738 not used by this specification; they MUST be checked for syntax 2739 but their values are not used. 2741 The remaining non-attribute lines are processed as follows: 2743 The "v=" line MUST have a version of 0, as specified in [RFC4566], 2744 Section 5.1. 2746 The "o=" line MUST be parsed as specified in [RFC4566], 2747 Section 5.2. 2749 The "b=" line, if present, MUST be parsed as specified in 2750 [RFC4566], Section 5.8, and the bwtype and bandwidth values 2751 stored. 2753 Finally, the attribute lines are processed. Specific processing MUST 2754 be applied for the following session-level attribute ("a=") lines: 2756 o Any "a=group" lines are parsed as specified in [RFC5888], 2757 Section 5, and the group's semantics and mids are stored. 2759 o If present, a single "a=ice-lite" line is parsed as specified in 2760 [RFC5245], Section 15.3, and a value indicating the presence of 2761 ice-lite is stored. 2763 o If present, a single "a=ice-ufrag" line is parsed as specified in 2764 [RFC5245], Section 15.4, and the ufrag value is stored. 2766 o If present, a single "a=ice-pwd" line is parsed as specified in 2767 [RFC5245], Section 15.4, and the password value is stored. 2769 o If present, a single "a=ice-options" line is parsed as specified 2770 in [RFC5245], Section 15.5, and the set of specified options is 2771 stored. 2773 o Any "a=fingerprint" lines are parsed as specified in [RFC8122], 2774 Section 5, and the set of fingerprint and algorithm values is 2775 stored. 2777 o If present, a single "a=setup" line is parsed as specified in 2778 [RFC4145], Section 4, and the setup value is stored. 2780 o If present, a single "a=tls-id" line is parsed as specified in 2781 [I-D.ietf-mmusic-dtls-sdp] Section 5, and the tls-id value is 2782 stored. 2784 o Any "a=identity" lines are parsed and the identity values stored 2785 for subsequent verification, as specified 2786 [I-D.ietf-rtcweb-security-arch], Section 5. 2788 o Any "a=extmap" lines are parsed as specified in [RFC5285], 2789 Section 5, and their values are stored. 2791 Other attributes that are not relevant to JSEP may also be present, 2792 and implementations SHOULD process any that they recognize. As 2793 required by [RFC4566], Section 5.13, unknown attribute lines MUST be 2794 ignored. 2796 Once all the session-level lines have been parsed, processing 2797 continues with the lines in m= sections. 2799 5.7.2. Media Section Parsing 2801 Like the session-level lines, the media section lines MUST occur in 2802 the specific order and with the specific syntax defined in [RFC4566], 2803 Section 5. 2805 The "m=" line itself MUST be parsed as described in [RFC4566], 2806 Section 5.14, and the media, port, proto, and fmt values stored. 2808 Following the "m=" line, specific processing MUST be applied for the 2809 following non-attribute lines: 2811 o As with the "c=" line at the session level, the "c=" line MUST be 2812 parsed according to [RFC4566], Section 5.7, but its value is not 2813 used. 2815 o The "b=" line, if present, MUST be parsed as specified in 2816 [RFC4566], Section 5.8, and the bwtype and bandwidth values 2817 stored. 2819 Specific processing MUST also be applied for the following attribute 2820 lines: 2822 o If present, a single "a=ice-ufrag" line is parsed as specified in 2823 [RFC5245], Section 15.4, and the ufrag value is stored. 2825 o If present, a single "a=ice-pwd" line is parsed as specified in 2826 [RFC5245], Section 15.4, and the password value is stored. 2828 o If present, a single "a=ice-options" line is parsed as specified 2829 in [RFC5245], Section 15.5, and the set of specified options is 2830 stored. 2832 o Any "a=candidate" attributes MUST be parsed as specified in 2833 [RFC5245], Section 15.1, and their values stored. 2835 o Any "a=remote-candidates" attributes MUST be parsed as specified 2836 in [RFC5245], Section 15.2, but their values are ignored. 2838 o If present, a single "a=end-of-candidates" attribute MUST be 2839 parsed as specified in [I-D.ietf-ice-trickle], Section 8.2, and 2840 its presence or absence flagged and stored. 2842 o Any "a=fingerprint" lines are parsed as specified in [RFC8122], 2843 Section 5, and the set of fingerprint and algorithm values is 2844 stored. 2846 If the "m=" proto value indicates use of RTP, as described in 2847 Section 5.1.2 above, the following attribute lines MUST be processed: 2849 o The "m=" fmt value MUST be parsed as specified in [RFC4566], 2850 Section 5.14, and the individual values stored. 2852 o Any "a=rtpmap" or "a=fmtp" lines MUST be parsed as specified in 2853 [RFC4566], Section 6, and their values stored. 2855 o If present, a single "a=ptime" line MUST be parsed as described in 2856 [RFC4566], Section 6, and its value stored. 2858 o If present, a single "a=maxptime" line MUST be parsed as described 2859 in [RFC4566], Section 6, and its value stored. 2861 o If present, a single direction attribute line (e.g. "a=sendrecv") 2862 MUST be parsed as described in [RFC4566], Section 6, and its value 2863 stored. 2865 o Any "a=ssrc" attributes MUST be parsed as specified in [RFC5576], 2866 Section 4.1, and their values stored. 2868 o Any "a=extmap" attributes MUST be parsed as specified in 2869 [RFC5285], Section 5, and their values stored. 2871 o Any "a=rtcp-fb" attributes MUST be parsed as specified in 2872 [RFC4585], Section 4.2., and their values stored. 2874 o If present, a single "a=rtcp-mux" attribute MUST be parsed as 2875 specified in [RFC5761], Section 5.1.3, and its presence or absence 2876 flagged and stored. 2878 o If present, a single "a=rtcp-mux-only" attribute MUST be parsed as 2879 specified in [I-D.ietf-mmusic-mux-exclusive], Section 3, and its 2880 presence or absence flagged and stored. 2882 o If present, a single "a=rtcp-rsize" attribute MUST be parsed as 2883 specified in [RFC5506], Section 5, and its presence or absence 2884 flagged and stored. 2886 o If present, a single "a=rtcp" attribute MUST be parsed as 2887 specified in [RFC3605], Section 2.1, but its value is ignored, as 2888 this information is superfluous when using ICE. 2890 o If present, "a=msid" attributes MUST be parsed as specified in 2891 [I-D.ietf-mmusic-msid], Section 3.2, and their values stored. 2893 o Any "a=imageattr" attributes MUST be parsed as specified in 2894 [RFC6236], Section 3, and their values stored. 2896 o Any "a=rid" lines MUST be parsed as specified in 2897 [I-D.ietf-mmusic-rid], Section 10, and their values stored. 2899 o If present, a single "a=simulcast" line MUST be parsed as 2900 specified in [I-D.ietf-mmusic-sdp-simulcast], and its values 2901 stored. 2903 Otherwise, if the "m=" proto value indicates use of SCTP, the 2904 following attribute lines MUST be processed: 2906 o The "m=" fmt value MUST be parsed as specified in 2907 [I-D.ietf-mmusic-sctp-sdp], Section 4.3, and the application 2908 protocol value stored. 2910 o An "a=sctp-port" attribute MUST be present, and it MUST be parsed 2911 as specified in [I-D.ietf-mmusic-sctp-sdp], Section 5.2, and the 2912 value stored. 2914 o If present, a single "a=max-message-size" attribute MUST be parsed 2915 as specified in [I-D.ietf-mmusic-sctp-sdp], Section 6, and the 2916 value stored. Otherwise, use the specified default. 2918 Other attributes that are not relevant to JSEP may also be present, 2919 and implementations SHOULD process any that they recognize. As 2920 required by [RFC4566], Section 5.13, unknown attribute lines MUST be 2921 ignored. 2923 5.7.3. Semantics Verification 2925 Assuming parsing completes successfully, the parsed description is 2926 then evaluated to ensure internal consistency as well as proper 2927 support for mandatory features. Specifically, the following checks 2928 are performed: 2930 o For each m= section, valid values for each of the mandatory-to-use 2931 features enumerated in Section 5.1.1 MUST be present. These 2932 values MAY either be present at the media level, or inherited from 2933 the session level. 2935 * ICE ufrag and password values, which MUST comply with the size 2936 limits specified in [RFC5245], Section 15.4. 2938 * tls-id value, which MUST be set according to 2939 [I-D.ietf-mmusic-dtls-sdp], Section 5. If this is a re-offer 2940 and the tls-id value is different from that presently in use, 2941 the DTLS connection is not being continued and the remote 2942 description MUST be part of an ICE restart, together with new 2943 ufrag and password values. If this is an answer, the tls-id 2944 value, if present, MUST be the same as in the offer. 2946 * DTLS setup value, which MUST be set according to the rules 2947 specified in [RFC5763], Section 5 and MUST be consistent with 2948 the selected role of the current DTLS connection, if one exists 2949 and is being continued. 2951 * DTLS fingerprint values, where at least one fingerprint MUST be 2952 present. 2954 o All RID values referenced in an "a=simulcast" line MUST exist as 2955 "a=rid" lines. 2957 o Each m= section is also checked to ensure prohibited features are 2958 not used. 2960 o If the RTP/RTCP multiplexing policy is "require", each m= section 2961 MUST contain an "a=rtcp-mux" attribute. If an m= section contains 2962 an "a=rtcp-mux-only" attribute then that section MUST also contain 2963 an "a=rtcp-mux" attribute. 2965 o If this m= section was present in the previous answer then the 2966 state of RTP/RTCP multiplexing MUST match what was previously 2967 negotiated. 2969 If this session description is of type "pranswer" or "answer", the 2970 following additional checks are applied: 2972 o The session description must follow the rules defined in 2973 [RFC3264], Section 6, including the requirement that the number of 2974 m= sections MUST exactly match the number of m= sections in the 2975 associated offer. 2977 o For each m= section, the media type and protocol values MUST 2978 exactly match the media type and protocol values in the 2979 corresponding m= section in the associated offer. 2981 If any of the preceding checks failed, processing MUST stop and an 2982 error MUST be returned. 2984 5.8. Applying a Local Description 2986 The following steps are performed at the media engine level to apply 2987 a local description. If an error is returned, the session MUST be 2988 restored to the state it was in before performing these steps. 2990 Next, m= sections are processed. For each m= section, the following 2991 steps MUST be performed; if any parameters are out of bounds, or 2992 cannot be applied, processing MUST stop and an error MUST be 2993 returned. 2995 o If this m= section is new, begin gathering candidates for it, as 2996 defined in [RFC5245], Section 4.1.1, unless it is definitively 2997 being bundled (either this is an offer and the m= section is 2998 marked bundle-only, or it is an answer and the m= section is 2999 bundled into into another m= section.) 3001 o Or, if the ICE ufrag and password values have changed, trigger the 3002 ICE agent to start an ICE restart, and begin gathering new 3003 candidates for the m= section as described in [RFC5245], 3004 Section 9.1.1.1. If this description is an answer, also start 3005 checks on that media section as defined in [RFC5245], 3006 Section 9.3.1.1. 3008 o If the m= section proto value indicates use of RTP: 3010 * If there is no RtpTransceiver associated with this m= section, 3011 find one and associate it with this m= section according to the 3012 following steps. Note that this situation will only occur when 3013 applying an offer. 3015 + Find the RtpTransceiver that corresponds to this m= section, 3016 using the mapping between transceivers and m= section 3017 indices established when creating the offer. 3019 + Set the value of this RtpTransceiver's mid property to the 3020 MID of the m= section. 3022 * If RTCP mux is indicated, prepare to demux RTP and RTCP from 3023 the RTP ICE component, as specified in [RFC5761], 3024 Section 5.1.3. 3026 * For each specified RTP header extension, establish a mapping 3027 between the extension ID and URI, as described in [RFC5285], 3028 Section 6. 3030 * If the MID header extension is supported, prepare to demux RTP 3031 streams intended for this m= section based on the MID header 3032 extension, as described in 3033 [I-D.ietf-mmusic-sdp-bundle-negotiation], Section 15. 3035 * For each specified media format, establish a mapping between 3036 the payload type and the actual media format, as described in 3037 [RFC3264], Section 6.1. In addition, prepare to demux RTP 3038 streams intended for this m= section based on the media formats 3039 supported by this m= section, as described in 3040 [I-D.ietf-mmusic-sdp-bundle-negotiation], Section 10.2. 3042 * For each specified "rtx" media format, establish a mapping 3043 between the RTX payload type and its associated primary payload 3044 type, as described in [RFC4588], Sections 8.6 and 8.7. 3046 * If the directional attribute is of type "sendrecv" or 3047 "recvonly", enable receipt and decoding of media. 3049 Finally, if this description is of type "pranswer" or "answer", 3050 follow the processing defined in Section 5.10 below. 3052 5.9. Applying a Remote Description 3054 The following steps are performed to apply a remote description. If 3055 an error is returned, the session MUST be restored to the state it 3056 was in before performing these steps. 3058 If the answer contains any "a=ice-options" attributes where "trickle" 3059 is listed as an attribute, update the PeerConnection canTrickle 3060 property to be true. Otherwise, set this property to false. 3062 The following steps MUST be performed for attributes at the session 3063 level; if any parameters are out of bounds, or cannot be applied, 3064 processing MUST stop and an error MUST be returned. 3066 o For any specified "CT" bandwidth value, set this as the limit for 3067 the maximum total bitrate for all m= sections, as specified in 3068 [RFC4566], Section 5.8. Within this overall limit, the 3069 implementation can dynamically decide how to best allocate the 3070 available bandwidth between m= sections, respecting any specific 3071 limits that have been specified for individual m= sections. 3073 o For any specified "RR" or "RS" bandwidth values, handle as 3074 specified in [RFC3556], Section 2. 3076 o Any "AS" bandwidth value MUST be ignored, as the meaning of this 3077 construct at the session level is not well defined. 3079 For each m= section, the following steps MUST be performed; if any 3080 parameters are out of bounds, or cannot be applied, processing MUST 3081 stop and an error MUST be returned. 3083 o If the ICE ufrag or password changed from the previous remote 3084 description: [RFC5245]. 3086 * If the description is of type "offer", note that an ICE restart 3087 is needed, as described in [RFC5245], Section 9.1.1.1 . 3089 * If the description is of type "answer" or "pranswer", then 3090 check to see if the current local description is an ICE 3091 restart, and if not, generate an error. It the PeerConnection 3092 state is "have-remote-pranswer", and the ICE ufrag or password 3093 changed from the previous provisional answer, then signal the 3094 ICE agent to discard any previous ICE check list state for the 3095 m= section. Finally, signal the ICE agent to begin checks as 3096 described in [RFC5245], Section 9.3.1.1. 3098 o If the current local description indicates an ICE restart, and 3099 either the ICE ufrag or password has not changed from the previous 3100 remote description, as prescribed by [RFC5245], Section 9.2.1.1, 3101 generate an error. 3103 o Configure the ICE components associated with this media section to 3104 use the supplied ICE remote ufrag and password for their 3105 connectivity checks. 3107 o Pair any supplied ICE candidates with any gathered local 3108 candidates, as described in [RFC5245], Section 5.7, and start 3109 connectivity checks with the appropriate credentials. 3111 o If an "a=end-of-candidates" attribute is present, process the end- 3112 of-candidates indication as described in [I-D.ietf-ice-trickle], 3113 Section 11. 3115 o If the m= section proto value indicates use of RTP: 3117 * If the m= section is being recycled (see Section 5.2.2), 3118 dissociate the currently associated RtpTransceiver by setting 3119 its mid property to null, and discard the mapping between the 3120 transceiver and its m= section index. 3122 * If the m= section is not associated with any RtpTransceiver 3123 (possibly because it was dissociated in the previous step), 3124 either find an RtpTransceiver or create one according to the 3125 following steps: 3127 + If the m= section is sendrecv or recvonly, and there are 3128 RtpTransceivers of the same type that were added to the 3129 PeerConnection by addTrack and are not associated with any 3130 m= section and are not stopped, find the first (according to 3131 the canonical order described in Section 5.2.1) such 3132 RtpTransceiver. 3134 + If no RtpTransceiver was found in the previous step, create 3135 one with a recvonly direction. 3137 + Associate the found or created RtpTransceiver with the m= 3138 section by setting the value of the RtpTransceiver's mid 3139 property to the MID of the m= section, and establish a 3140 mapping between the transceiver and the index of the m= 3141 section. If the m= section does not include a MID (i.e., 3142 the remote endpoint does not support the MID extension), 3143 generate a value for the RtpTransceiver mid property, 3144 following the guidance for "a=mid" mentioned in 3145 Section 5.2.1. 3147 * For each specified media format that is also supported by the 3148 local implementation, establish a mapping between the specified 3149 payload type and the media format, as described in [RFC3264], 3150 Section 6.1. Specifically, this means that the implementation 3151 records the payload type to be used in outgoing RTP packets 3152 when sending each specified media format, as well as the 3153 relative preference for each format that is indicated in their 3154 ordering. If any indicated media format is not supported by 3155 the local implementation, it MUST be ignored. 3157 * For each specified "rtx" media format, establish a mapping 3158 between the RTX payload type and its associated primary payload 3159 type, as described in [RFC4588], Section 4. If any referenced 3160 primary payload types are not present, this MUST result in an 3161 error. Note that RTX payload types may refer to primary 3162 payload types which are not supported by the local media 3163 implementation, in which case, the RTX payload type MUST also 3164 be ignored. 3166 * For each specified fmtp parameter that is supported by the 3167 local implementation, enable them on the associated media 3168 formats. 3170 * For each specified SSRC that is signaled in the m= section, 3171 prepare to demux RTP streams intended for this m= section using 3172 that SSRC, as described in 3173 [I-D.ietf-mmusic-sdp-bundle-negotiation], Section 10.2. 3175 * For each specified RTP header extension that is also supported 3176 by the local implementation, establish a mapping between the 3177 extension ID and URI, as described in [RFC5285], Section 5. 3178 Specifically, this means that the implementation records the 3179 extension ID to be used in outgoing RTP packets when sending 3180 each specified header extension. If any indicated RTP header 3181 extension is not supported by the local implementation, it MUST 3182 be ignored. 3184 * For each specified RTCP feedback mechanism that is supported by 3185 the local implementation, enable them on the associated media 3186 formats. 3188 * For any specified "TIAS" bandwidth value, set this value as a 3189 constraint on the maximum RTP bitrate to be used when sending 3190 media, as specified in [RFC3890]. If a "TIAS" value is not 3191 present, but an "AS" value is specified, generate a "TIAS" 3192 value using this formula: 3194 TIAS = AS * 1000 * 0.95 - (50 * 40 * 8) 3195 The 50 is based on 50 packets per second, the 40 is based on an 3196 estimate of total header size, the 1000 changes the unit from 3197 kbps to bps (as required by TIAS), and the 0.95 is to allocate 3198 5% to RTCP. "TIAS" is used in preference to "AS" because it 3199 provides more accurate control of bandwidth. 3201 * For any "RR" or "RS" bandwidth values, handle as specified in 3202 [RFC3556], Section 2. 3204 * Any specified "CT" bandwidth value MUST be ignored, as the 3205 meaning of this construct at the media level is not well 3206 defined. 3208 * If the m= section is of type audio: 3210 + For each specified "CN" media format, configure silence 3211 suppression for all supported media formats with the same 3212 clockrate, as described in [RFC3389], Section 5, except for 3213 formats that have their own internal silence suppression 3214 mechanisms. Silence suppression for such formats (e.g., 3215 Opus) is controlled via fmtp parameters, as discussed in 3216 Section 5.2.3.2. 3218 + For each specified "telephone-event" media format, enable 3219 DTMF transmission for all supported media formats with the 3220 same clockrate, as described in [RFC4733], Section 2.5.1.2. 3221 If the application attempts to transmit DTMF when using a 3222 media format that does not have a corresponding telephone- 3223 event format, this MUST result in an error. 3225 + For any specified "ptime" value, configure the available 3226 media formats to use the specified packet size when sending. 3227 If the specified size is not supported for a media format, 3228 use the next closest value instead. 3230 Finally, if this description is of type "pranswer" or "answer", 3231 follow the processing defined in Section 5.10 below. 3233 5.10. Applying an Answer 3235 In addition to the steps mentioned above for processing a local or 3236 remote description, the following steps are performed when processing 3237 a description of type "pranswer" or "answer". 3239 For each m= section, the following steps MUST be performed: 3241 o If the m= section has been rejected (i.e. port is set to zero in 3242 the answer), stop any reception or transmission of media for this 3243 section, and, unless a non-rejected m= section is bundled with 3244 this m= section, discard any associated ICE components, as 3245 described in [RFC5245], Section 9.2.1.3. 3247 o If the remote DTLS fingerprint has been changed or the tls-id has 3248 changed, tear down the DTLS connection. This includes the case 3249 when the PeerConnection state is "have-remote-pranswer". If a 3250 DTLS connection needs to be torn down but the answer does not 3251 indicate an ICE restart or, in the case of "have-remote-pranswer", 3252 new ICE credentials, an error MUST be generated. If an ICE 3253 restart is performed without a change in tls-id or fingerprint, 3254 then the same DTLS connection is continued over the new ICE 3255 channel. 3257 o If no valid DTLS connection exists, prepare to start a DTLS 3258 connection, using the specified roles and fingerprints, on any 3259 underlying ICE components, once they are active. 3261 o If the m= section proto value indicates use of RTP: 3263 * If the m= section references RTCP feedback mechanisms that were 3264 not present in the corresponding m= section in the offer, this 3265 indicates a negotiation problem and MUST result in an error. 3266 However, new media formats and new RTP header extension values 3267 are permitted in the answer, as described in [RFC3264], 3268 Section 7, and [RFC5285], Section 6. 3270 * If the m= section has RTCP mux enabled, discard the RTCP ICE 3271 component, if one exists, and begin or continue muxing RTCP 3272 over the RTP ICE component, as specified in [RFC5761], 3273 Section 5.1.3. Otherwise, prepare to transmit RTCP over the 3274 RTCP ICE component; if no RTCP ICE component exists, because 3275 RTCP mux was previously enabled, this MUST result in an error. 3277 * If the m= section has reduced-size RTCP enabled, configure the 3278 RTCP transmission for this m= section to use reduced-size RTCP, 3279 as specified in [RFC5506]. 3281 * If the directional attribute in the answer indicates that the 3282 JSEP implementation should be sending media ("sendonly" for 3283 local answers, "recvonly" for remote answers, or "sendrecv" for 3284 either type of answer), choose the media format to send as the 3285 most preferred media format from the remote description that is 3286 also locally supported, as discussed in [RFC3264], Sections 6.1 3287 and 7, and start transmitting RTP media using that format once 3288 the underlying transport layers have been established. If an 3289 SSRC has not already been chosen for this outgoing RTP stream, 3290 choose a random one. If media is already being transmitted, 3291 the same SSRC SHOULD be used unless the clockrate of the new 3292 codec is different, in which case a new SSRC MUST be chosen, as 3293 specified in [RFC7160], Section 3.1. 3295 * The payload type mapping from the remote description is used to 3296 determine payload types for the outgoing RTP streams, including 3297 the payload type for the send media format chosen above. Any 3298 RTP header extensions that were negotiated should be included 3299 in the outgoing RTP streams, using the extension mapping from 3300 the remote description; if the RID header extension has been 3301 negotiated, and RID values are specified, include the RID 3302 header extension in the outgoing RTP streams, as indicated in 3303 [I-D.ietf-mmusic-rid], Section 4. 3305 * If the m= section is of type audio, and silence suppression was 3306 configured for the send media format as a result of processing 3307 the remote description, and is also enabled for that format in 3308 the local description, use silence suppression for outgoing 3309 media, in accordance with the guidance in Section 5.2.3.2. If 3310 these conditions are not met, silence suppression MUST NOT be 3311 used for outgoing media. 3313 * If simulcast has been negotiated, send the number of Source RTP 3314 Streams as specified in [I-D.ietf-mmusic-sdp-simulcast], 3315 Section 6.2.2. 3317 * If the send media format chosen above has a corresponding "rtx" 3318 media format, or a FEC mechanism has been negotiated, establish 3319 a Redundancy RTP Stream with a random SSRC for each Source RTP 3320 Stream, and start or continue transmitting RTX/FEC packets as 3321 needed. 3323 * If the send media format chosen above has a corresponding "red" 3324 media format of the same clockrate, allow redundant encoding 3325 using the specified format for resiliency purposes, as 3326 discussed in [I-D.ietf-rtcweb-fec], Section 3.2. Note that 3327 unlike RTX or FEC media formats, the "red" format is 3328 transmitted on the Source RTP Stream, not the Redundancy RTP 3329 Stream. 3331 * Enable the RTCP feedback mechanisms referenced in the media 3332 section for all Source RTP Streams using the specified media 3333 formats. Specifically, begin or continue sending the requested 3334 feedback types and reacting to received feedback, as specified 3335 in [RFC4585], Section 4.2. When sending RTCP feedback, follow 3336 the rules and recommendations from [RFC8108] Section 5.4.1, to 3337 select which SSRC to use. 3339 * If the directional attribute in the answer indicates that the 3340 JSEP implementation should not be sending media ("recvonly" for 3341 local answers, "sendonly" for remote answers, or "inactive" for 3342 either type of answer) stop transmitting all RTP media, but 3343 continue sending RTCP, as described in [RFC3264], Section 5.1. 3345 o If the m= section proto value indicates use of SCTP: 3347 * If an SCTP association exists, and the remote SCTP port has 3348 changed, discard the existing SCTP association. This includes 3349 the case when the PeerConnection state is "have-remote- 3350 pranswer". 3352 * If no valid SCTP association exists, prepare to initiate a SCTP 3353 association over the associated ICE component and DTLS 3354 connection, using the local SCTP port value from the local 3355 description, and the remote SCTP port value from the remote 3356 description, as described in [I-D.ietf-mmusic-sctp-sdp], 3357 Section 10.2. 3359 If the answer contains valid bundle groups, discard any ICE 3360 components for the m= sections that will be bundled onto the primary 3361 ICE components in each bundle, and begin muxing these m= sections 3362 accordingly, as described in 3363 [I-D.ietf-mmusic-sdp-bundle-negotiation], Section 8.2. 3365 If the description is of type "answer", and there are still remaining 3366 candidates in the ICE candidate pool, discard them. 3368 6. Processing RTP/RTCP 3370 When bundling, associating incoming RTP/RTCP with the proper m= 3371 section is defined in [I-D.ietf-mmusic-sdp-bundle-negotiation], 3372 Section 10.2. When not bundling, the proper m= section is clear from 3373 the ICE component over which the RTP/RTCP is received. 3375 Once the proper m= section(s) are known, RTP/RTCP is delivered to the 3376 RtpTransceiver(s) associated with the m= section(s) and further 3377 processing of the RTP/RTCP is done at the RtpTransceiver level. This 3378 includes using RID [I-D.ietf-mmusic-rid] to distinguish between 3379 multiple Encoded Streams, as well as determine which Source RTP 3380 stream should be repaired by a given Redundancy RTP stream. 3382 7. Examples 3384 Note that this example section shows several SDP fragments. To 3385 format in 72 columns, some of the lines in SDP have been split into 3386 multiple lines, where leading whitespace indicates that a line is a 3387 continuation of the previous line. In addition, some blank lines 3388 have been added to improve readability but are not valid in SDP. 3390 More examples of SDP for WebRTC call flows, including examples with 3391 IPv6 addresses, can be found in [I-D.ietf-rtcweb-sdp]. 3393 7.1. Simple Example 3395 This section shows a very simple example that sets up a minimal audio 3396 / video call between two JSEP endpoints without using trickle ICE. 3397 The example in the following section provides a more detailed example 3398 of what could happen in a JSEP session. 3400 The code flow below shows Alice's endpoint initiating the session to 3401 Bob's endpoint. The messages from the JavaScript application in 3402 Alice's browser to the JavaScript in Bob's browser, abbreviated as 3403 AliceJS and BobJS respectively, are assumed to flow over some 3404 signaling protocol via a web server. The JavaScript on both Alice's 3405 side and Bob's side waits for all candidates before sending the offer 3406 or answer, so the offers and answers are complete; trickle ICE is not 3407 used. The user agents (JSEP implementations) in Alice and Bob's 3408 browsers, abbreviated as AliceUA and BobUA respectively, are using 3409 the default bundle policy of "balanced", and the default RTCP mux 3410 policy of "require". 3412 // set up local media state 3413 AliceJS->AliceUA: create new PeerConnection 3414 AliceJS->AliceUA: addTrack with two tracks: audio and video 3415 AliceJS->AliceUA: createOffer to get offer 3416 AliceJS->AliceUA: setLocalDescription with offer 3417 AliceUA->AliceJS: multiple onicecandidate events with candidates 3419 // wait for ICE gathering to complete 3420 AliceUA->AliceJS: onicecandidate event with null candidate 3421 AliceJS->AliceUA: get |offer-A1| from pendingLocalDescription 3423 // |offer-A1| is sent over signaling protocol to Bob 3424 AliceJS->WebServer: signaling with |offer-A1| 3425 WebServer->BobJS: signaling with |offer-A1| 3427 // |offer-A1| arrives at Bob 3428 BobJS->BobUA: create a PeerConnection 3429 BobJS->BobUA: setRemoteDescription with |offer-A1| 3430 BobUA->BobJS: ontrack events for audio and video tracks 3432 // Bob accepts call 3433 BobJS->BobUA: addTrack with local tracks 3434 BobJS->BobUA: createAnswer 3435 BobJS->BobUA: setLocalDescription with answer 3436 BobUA->BobJS: multiple onicecandidate events with candidates 3438 // wait for ICE gathering to complete 3439 BobUA->BobJS: onicecandidate event with null candidate 3440 BobJS->BobUA: get |answer-A1| from currentLocalDescription 3442 // |answer-A1| is sent over signaling protocol to Alice 3443 BobJS->WebServer: signaling with |answer-A1| 3444 WebServer->AliceJS: signaling with |answer-A1| 3446 // |answer-A1| arrives at Alice 3447 AliceJS->AliceUA: setRemoteDescription with |answer-A1| 3448 AliceUA->AliceJS: ontrack events for audio and video tracks 3450 // media flows 3451 BobUA->AliceUA: media sent from Bob to Alice 3452 AliceUA->BobUA: media sent from Alice to Bob 3454 The SDP for |offer-A1| looks like: 3456 v=0 3457 o=- 4962303333179871722 1 IN IP4 0.0.0.0 3458 s=- 3459 t=0 0 3460 a=ice-options:trickle 3461 a=group:BUNDLE a1 v1 3462 a=group:LS a1 v1 3464 m=audio 10100 UDP/TLS/RTP/SAVPF 96 0 8 97 98 3465 c=IN IP4 203.0.113.100 3466 a=mid:a1 3467 a=sendrecv 3468 a=rtpmap:96 opus/48000/2 3469 a=rtpmap:0 PCMU/8000 3470 a=rtpmap:8 PCMA/8000 3471 a=rtpmap:97 telephone-event/8000 3472 a=rtpmap:98 telephone-event/48000 3473 a=fmtp:97 0-15 3474 a=fmtp:98 0-15 3475 a=maxptime:120 3476 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 3477 a=extmap:2 urn:ietf:params:rtp-hdrext:ssrc-audio-level 3478 a=msid:47017fee-b6c1-4162-929c-a25110252400 3479 f83006c5-a0ff-4e0a-9ed9-d3e6747be7d9 3480 a=ice-ufrag:ETEn 3481 a=ice-pwd:OtSK0WpNtpUjkY4+86js7ZQl 3482 a=fingerprint:sha-256 3483 19:E2:1C:3B:4B:9F:81:E6:B8:5C:F4:A5:A8:D8:73:04: 3484 BB:05:2F:70:9F:04:A9:0E:05:E9:26:33:E8:70:88:A2 3485 a=setup:actpass 3486 a=tls-id:1 3487 a=rtcp:10101 IN IP4 203.0.113.100 3488 a=rtcp-mux 3489 a=rtcp-rsize 3490 a=candidate:1 1 udp 2113929471 203.0.113.100 10100 typ host 3491 a=candidate:1 2 udp 2113929470 203.0.113.100 10101 typ host 3492 a=end-of-candidates 3494 m=video 10102 UDP/TLS/RTP/SAVPF 100 101 102 103 3495 c=IN IP4 203.0.113.100 3496 a=mid:v1 3497 a=sendrecv 3498 a=rtpmap:100 VP8/90000 3499 a=rtpmap:101 H264/90000 3500 a=fmtp:101 packetization-mode=1;profile-level-id=42e01f 3501 a=rtpmap:102 rtx/90000 3502 a=fmtp:102 apt=100 3503 =rtpmap:103 rtx/90000 3504 a=fmtp:103 apt=101 3505 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 3506 a=extmap:3 urn:ietf:params:rtp-hdrext:sdes:rtp-stream-id 3507 a=rtcp-fb:100 ccm fir 3508 a=rtcp-fb:100 nack 3509 a=rtcp-fb:100 nack pli 3510 a=msid:47017fee-b6c1-4162-929c-a25110252400 3511 f30bdb4a-5db8-49b5-bcdc-e0c9a23172e0 3512 a=ice-ufrag:BGKk 3513 a=ice-pwd:mqyWsAjvtKwTGnvhPztQ9mIf 3514 a=fingerprint:sha-256 3515 19:E2:1C:3B:4B:9F:81:E6:B8:5C:F4:A5:A8:D8:73:04: 3516 BB:05:2F:70:9F:04:A9:0E:05:E9:26:33:E8:70:88:A2 3517 a=setup:actpass 3518 a=tls-id:1 3519 a=rtcp:10103 IN IP4 203.0.113.100 3520 a=rtcp-mux 3521 a=rtcp-rsize 3522 a=candidate:1 1 udp 2113929471 203.0.113.100 10102 typ host 3523 a=candidate:1 2 udp 2113929470 203.0.113.100 10103 typ host 3524 a=end-of-candidates 3526 The SDP for |answer-A1| looks like: 3528 v=0 3529 o=- 6729291447651054566 1 IN IP4 0.0.0.0 3530 s=- 3531 t=0 0 3532 a=ice-options:trickle 3533 a=group:BUNDLE a1 v1 3534 a=group:LS a1 v1 3536 m=audio 10200 UDP/TLS/RTP/SAVPF 96 0 8 97 98 3537 c=IN IP4 203.0.113.200 3538 a=mid:a1 3539 a=sendrecv 3540 a=rtpmap:96 opus/48000/2 3541 a=rtpmap:0 PCMU/8000 3542 a=rtpmap:8 PCMA/8000 3543 a=rtpmap:97 telephone-event/8000 3544 a=rtpmap:98 telephone-event/48000 3545 a=fmtp:97 0-15 3546 a=fmtp:98 0-15 3547 a=maxptime:120 3548 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 3549 a=extmap:2 urn:ietf:params:rtp-hdrext:ssrc-audio-level 3550 a=msid:61317484-2ed4-49d7-9eb7-1414322a7aae 3551 5a7b57b8-f043-4bd1-a45d-09d4dfa31226 3553 a=ice-ufrag:6sFv 3554 a=ice-pwd:cOTZKZNVlO9RSGsEGM63JXT2 3555 a=fingerprint:sha-256 3556 6B:8B:F0:65:5F:78:E2:51:3B:AC:6F:F3:3F:46:1B:35: 3557 DC:B8:5F:64:1A:24:C2:43:F0:A1:58:D0:A1:2C:19:08 3558 a=setup:active 3559 a=tls-id:1 3560 a=rtcp-mux 3561 a=rtcp-rsize 3562 a=candidate:1 1 udp 2113929471 203.0.113.200 10200 typ host 3563 a=end-of-candidates 3565 m=video 10200 UDP/TLS/RTP/SAVPF 100 101 102 103 3566 c=IN IP4 203.0.113.200 3567 a=mid:v1 3568 a=sendrecv 3569 a=rtpmap:100 VP8/90000 3570 a=rtpmap:101 H264/90000 3571 a=fmtp:101 packetization-mode=1;profile-level-id=42e01f 3572 a=rtpmap:102 rtx/90000 3573 a=fmtp:102 apt=100 3574 =rtpmap:103 rtx/90000 3575 a=fmtp:103 apt=101 3576 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 3577 a=extmap:3 urn:ietf:params:rtp-hdrext:sdes:rtp-stream-id 3578 a=rtcp-fb:100 ccm fir 3579 a=rtcp-fb:100 nack 3580 a=rtcp-fb:100 nack pli 3581 a=msid:61317484-2ed4-49d7-9eb7-1414322a7aae 3582 4ea4d4a1-2fda-4511-a9cc-1b32c2e59552 3584 7.2. Detailed Example 3586 This section shows a more involved example of a session between two 3587 JSEP endpoints. Trickle ICE is used in full trickle mode, with a 3588 bundle policy of "max-bundle", an RTCP mux policy of "require", and a 3589 single TURN server. Initially, both Alice and Bob establish an audio 3590 channel and a data channel. Later, Bob adds two video flows, one for 3591 his video feed, and one for screensharing, both supporting FEC, and 3592 with the video feed configured for simulcast. Alice accepts these 3593 video flows, but does not add video flows of her own, so they are 3594 handled as recvonly. Alice also specifies a maximum video decoder 3595 resolution. 3597 // set up local media state 3598 AliceJS->AliceUA: create new PeerConnection 3599 AliceJS->AliceUA: addTrack with an audio track 3600 AliceJS->AliceUA: createDataChannel to get data channel 3601 AliceJS->AliceUA: createOffer to get |offer-B1| 3602 AliceJS->AliceUA: setLocalDescription with |offer-B1| 3604 // |offer-B1| is sent over signaling protocol to Bob 3605 AliceJS->WebServer: signaling with |offer-B1| 3606 WebServer->BobJS: signaling with |offer-B1| 3608 // |offer-B1| arrives at Bob 3609 BobJS->BobUA: create a PeerConnection 3610 BobJS->BobUA: setRemoteDescription with |offer-B1| 3611 BobUA->BobJS: ontrack with audio track from Alice 3613 // candidates are sent to Bob 3614 AliceUA->AliceJS: onicecandidate (host) |offer-B1-candidate-1| 3615 AliceJS->WebServer: signaling with |offer-B1-candidate-1| 3616 AliceUA->AliceJS: onicecandidate (srflx) |offer-B1-candidate-2| 3617 AliceJS->WebServer: signaling with |offer-B1-candidate-2| 3618 AliceUA->AliceJS: onicecandidate (relay) |offer-B1-candidate-3| 3619 AliceJS->WebServer: signaling with |offer-B1-candidate-3| 3621 WebServer->BobJS: signaling with |offer-B1-candidate-1| 3622 BobJS->BobUA: addIceCandidate with |offer-B1-candidate-1| 3623 WebServer->BobJS: signaling with |offer-B1-candidate-2| 3624 BobJS->BobUA: addIceCandidate with |offer-B1-candidate-2| 3625 WebServer->BobJS: signaling with |offer-B1-candidate-3| 3626 BobJS->BobUA: addIceCandidate with |offer-B1-candidate-3| 3628 // Bob accepts call 3629 BobJS->BobUA: addTrack with local audio 3630 BobJS->BobUA: createDataChannel to get data channel 3631 BobJS->BobUA: createAnswer to get |answer-B1| 3632 BobJS->BobUA: setLocalDescription with |answer-B1| 3634 // |answer-B1| is sent to Alice 3635 BobJS->WebServer: signaling with |answer-B1| 3636 WebServer->AliceJS: signaling with |answer-B1| 3637 AliceJS->AliceUA: setRemoteDescription with |answer-B1| 3638 AliceUA->AliceJS: ontrack event with audio track from Bob 3640 // candidates are sent to Alice 3641 BobUA->BobJS: onicecandidate (host) |answer-B1-candidate-1| 3642 BobJS->WebServer: signaling with |answer-B1-candidate-1| 3643 BobUA->BobJS: onicecandidate (srflx) |answer-B1-candidate-2| 3644 BobJS->WebServer: signaling with |answer-B1-candidate-2| 3645 BobUA->BobJS: onicecandidate (relay) |answer-B1-candidate-3| 3646 BobJS->WebServer: signaling with |answer-B1-candidate-3| 3647 WebServer->AliceJS: signaling with |answer-B1-candidate-1| 3648 AliceJS->AliceUA: addIceCandidate with |answer-B1-candidate-1| 3649 WebServer->AliceJS: signaling with |answer-B1-candidate-2| 3650 AliceJS->AliceUA: addIceCandidate with |answer-B1-candidate-2| 3651 WebServer->AliceJS: signaling with |answer-B1-candidate-3| 3652 AliceJS->AliceUA: addIceCandidate with |answer-B1-candidate-3| 3654 // data channel opens 3655 BobUA->BobJS: ondatachannel event 3656 AliceUA->AliceJS: ondatachannel event 3657 BobUA->BobJS: onopen 3658 AliceUA->AliceJS: onopen 3660 // media is flowing between endpoints 3661 BobUA->AliceUA: audio+data sent from Bob to Alice 3662 AliceUA->BobUA: audio+data sent from Alice to Bob 3664 // some time later Bob adds two video streams 3665 // note, no candidates exchanged, because of bundle 3666 BobJS->BobUA: addTrack with first video stream 3667 BobJS->BobUA: addTrack with second video stream 3668 BobJS->BobUA: createOffer to get |offer-B2| 3669 BobJS->BobUA: setLocalDescription with |offer-B2| 3671 // |offer-B2| is sent to Alice 3672 BobJS->WebServer: signaling with |offer-B2| 3673 WebServer->AliceJS: signaling with |offer-B2| 3674 AliceJS->AliceUA: setRemoteDescription with |offer-B2| 3675 AliceUA->AliceJS: ontrack event with first video track 3676 AliceUA->AliceJS: ontrack event with second video track 3677 AliceJS->AliceUA: createAnswer to get |answer-B2| 3678 AliceJS->AliceUA: setLocalDescription with |answer-B2| 3680 // |answer-B2| is sent over signaling protocol to Bob 3681 AliceJS->WebServer: signaling with |answer-B2| 3682 WebServer->BobJS: signaling with |answer-B2| 3683 BobJS->BobUA: setRemoteDescription with |answer-B2| 3685 // media is flowing between endpoints 3686 BobUA->AliceUA: audio+video+data sent from Bob to Alice 3687 AliceUA->BobUA: audio+video+data sent from Alice to Bob 3689 The SDP for |offer-B1| looks like: 3691 v=0 3692 o=- 4962303333179871723 1 IN IP4 0.0.0.0 3693 s=- 3694 t=0 0 3695 a=ice-options:trickle 3696 a=group:BUNDLE a1 d1 3698 m=audio 9 UDP/TLS/RTP/SAVPF 96 0 8 97 98 3699 c=IN IP4 0.0.0.0 3700 a=mid:a1 3701 a=sendrecv 3702 a=rtpmap:96 opus/48000/2 3703 a=rtpmap:0 PCMU/8000 3704 a=rtpmap:8 PCMA/8000 3705 a=rtpmap:97 telephone-event/8000 3706 a=rtpmap:98 telephone-event/48000 3707 a=fmtp:97 0-15 3708 a=fmtp:98 0-15 3709 a=maxptime:120 3710 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 3711 a=extmap:2 urn:ietf:params:rtp-hdrext:ssrc-audio-level 3712 a=msid:57017fee-b6c1-4162-929c-a25110252400 3713 e83006c5-a0ff-4e0a-9ed9-d3e6747be7d9 3714 a=ice-ufrag:ATEn 3715 a=ice-pwd:AtSK0WpNtpUjkY4+86js7ZQl 3716 a=fingerprint:sha-256 3717 29:E2:1C:3B:4B:9F:81:E6:B8:5C:F4:A5:A8:D8:73:04: 3718 BB:05:2F:70:9F:04:A9:0E:05:E9:26:33:E8:70:88:A2 3719 a=setup:actpass 3720 a=tls-id:1 3721 a=rtcp-mux 3722 a=rtcp-mux-only 3723 a=rtcp-rsize 3725 m=application 0 UDP/DTLS/SCTP webrtc-datachannel 3726 c=IN IP4 0.0.0.0 3727 a=mid:d1 3728 a=sctp-port:5000 3729 a=max-message-size:65536 3730 a=bundle-only 3732 |offer-B1-candidate-1| looks like: 3734 ufrag ATEn 3735 index 0 3736 mid a1 3737 attr candidate:1 1 udp 2113929471 203.0.113.100 10100 typ host 3739 |offer-B1-candidate-2| looks like: 3741 ufrag ATEn 3742 index 0 3743 mid a1 3744 attr candidate:1 1 udp 1845494015 198.51.100.100 11100 typ srflx 3745 raddr 203.0.113.100 rport 10100 3747 |offer-B1-candidate-3| looks like: 3749 ufrag ATEn 3750 index 0 3751 mid a1 3752 attr candidate:1 1 udp 255 192.0.2.100 12100 typ relay 3753 raddr 198.51.100.100 rport 11100 3755 The SDP for |answer-B1| looks like: 3757 v=0 3758 o=- 7729291447651054566 1 IN IP4 0.0.0.0 3759 s=- 3760 t=0 0 3761 a=ice-options:trickle 3762 a=group:BUNDLE a1 d1 3764 m=audio 9 UDP/TLS/RTP/SAVPF 96 0 8 97 98 3765 c=IN IP4 0.0.0.0 3766 a=mid:a1 3767 a=sendrecv 3768 a=rtpmap:96 opus/48000/2 3769 a=rtpmap:0 PCMU/8000 3770 a=rtpmap:8 PCMA/8000 3771 a=rtpmap:97 telephone-event/8000 3772 a=rtpmap:98 telephone-event/48000 3773 a=fmtp:97 0-15 3774 a=fmtp:98 0-15 3775 a=maxptime:120 3776 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 3777 a=extmap:2 urn:ietf:params:rtp-hdrext:ssrc-audio-level 3778 a=msid:71317484-2ed4-49d7-9eb7-1414322a7aae 3779 6a7b57b8-f043-4bd1-a45d-09d4dfa31226 3780 a=ice-ufrag:7sFv 3781 a=ice-pwd:dOTZKZNVlO9RSGsEGM63JXT2 3782 a=fingerprint:sha-256 3783 7B:8B:F0:65:5F:78:E2:51:3B:AC:6F:F3:3F:46:1B:35: 3784 DC:B8:5F:64:1A:24:C2:43:F0:A1:58:D0:A1:2C:19:08 3785 a=setup:active 3786 a=tls-id:1 3787 a=rtcp-mux 3788 a=rtcp-mux-only 3789 a=rtcp-rsize 3791 m=application 9 UDP/DTLS/SCTP webrtc-datachannel 3792 c=IN IP4 0.0.0.0 3793 a=mid:d1 3794 a=sctp-port:5000 3795 a=max-message-size:65536 3797 |answer-B1-candidate-1| looks like: 3799 ufrag 7sFv 3800 index 0 3801 mid a1 3802 attr candidate:1 1 udp 2113929471 203.0.113.200 10200 typ host 3804 |answer-B1-candidate-2| looks like: 3806 ufrag 7sFv 3807 index 0 3808 mid a1 3809 attr candidate:1 1 udp 1845494015 198.51.100.200 11200 typ srflx 3810 raddr 203.0.113.200 rport 10200 3812 |answer-B1-candidate-3| looks like: 3814 ufrag 7sFv 3815 index 0 3816 mid a1 3817 attr candidate:1 1 udp 255 192.0.2.200 12200 typ relay 3818 raddr 198.51.100.200 rport 11200 3820 The SDP for |offer-B2| is shown below. In addition to the new m= 3821 sections for video, both of which are offering FEC, and one of which 3822 is offering simulcast, note the increment of the version number in 3823 the o= line, changes to the c= line, indicating the local candidate 3824 that was selected, and the inclusion of gathered candidates as 3825 a=candidate lines. 3827 v=0 3828 o=- 7729291447651054566 2 IN IP4 0.0.0.0 3829 s=- 3830 t=0 0 3831 a=ice-options:trickle 3832 a=group:BUNDLE a1 d1 v1 v2 3833 a=group:LS a1 v1 3835 m=audio 12200 UDP/TLS/RTP/SAVPF 96 0 8 97 98 3836 c=IN IP4 192.0.2.200 3837 a=mid:a1 3838 a=sendrecv 3839 a=rtpmap:96 opus/48000/2 3840 a=rtpmap:0 PCMU/8000 3841 a=rtpmap:8 PCMA/8000 3842 a=rtpmap:97 telephone-event/8000 3843 a=rtpmap:98 telephone-event/48000 3844 a=fmtp:97 0-15 3845 a=fmtp:98 0-15 3846 a=maxptime:120 3847 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 3848 a=extmap:2 urn:ietf:params:rtp-hdrext:ssrc-audio-level 3849 a=msid:71317484-2ed4-49d7-9eb7-1414322a7aae 3850 6a7b57b8-f043-4bd1-a45d-09d4dfa31226 3851 a=ice-ufrag:7sFv 3852 a=ice-pwd:dOTZKZNVlO9RSGsEGM63JXT2 3853 a=fingerprint:sha-256 3854 7B:8B:F0:65:5F:78:E2:51:3B:AC:6F:F3:3F:46:1B:35: 3855 DC:B8:5F:64:1A:24:C2:43:F0:A1:58:D0:A1:2C:19:08 3856 a=setup:actpass 3857 a=tls-id:1 3858 a=rtcp-mux 3859 a=rtcp-mux-only 3860 a=rtcp-rsize 3861 a=candidate:1 1 udp 2113929471 203.0.113.200 10200 typ host 3862 a=candidate:1 1 udp 1845494015 198.51.100.200 11200 typ srflx 3863 raddr 203.0.113.200 rport 10200 3864 a=candidate:1 1 udp 255 192.0.2.200 12200 typ relay 3865 raddr 198.51.100.200 rport 11200 3866 a=end-of-candidates 3868 m=application 12200 UDP/DTLS/SCTP webrtc-datachannel 3869 c=IN IP4 192.0.2.200 3870 a=mid:d1 3871 a=sctp-port:5000 3872 a=max-message-size:65536 3874 m=video 12200 UDP/TLS/RTP/SAVPF 100 101 102 103 104 3875 c=IN IP4 192.0.2.200 3876 a=mid:v1 3877 a=sendrecv 3878 a=rtpmap:100 VP8/90000 3879 a=rtpmap:101 H264/90000 3880 a=fmtp:101 packetization-mode=1;profile-level-id=42e01f 3881 a=rtpmap:102 rtx/90000 3882 a=fmtp:102 apt=100 3883 =rtpmap:103 rtx/90000 3884 a=fmtp:103 apt=101 3885 a=rtpmap:104 flexfec/90000 3886 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 3887 a=extmap:3 urn:ietf:params:rtp-hdrext:sdes:rtp-stream-id 3888 a=rtcp-fb:100 ccm fir 3889 a=rtcp-fb:100 nack 3890 a=rtcp-fb:100 nack pli 3891 a=msid:71317484-2ed4-49d7-9eb7-1414322a7aae 3892 5ea4d4a1-2fda-4511-a9cc-1b32c2e59552 3893 a=rid:1 send 3894 a=rid:2 send 3895 a=rid:3 send 3896 a=simulcast:send 1;2;3 3898 m=video 12200 UDP/TLS/RTP/SAVPF 100 101 102 103 104 3899 c=IN IP4 192.0.2.200 3900 a=mid:v2 3901 a=sendrecv 3902 a=rtpmap:100 VP8/90000 3903 a=rtpmap:101 H264/90000 3904 a=fmtp:101 packetization-mode=1;profile-level-id=42e01f 3905 a=rtpmap:102 rtx/90000 3906 a=fmtp:102 apt=100 3907 =rtpmap:103 rtx/90000 3908 a=fmtp:103 apt=101 3909 a=rtpmap:104 flexfec/90000 3910 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 3911 a=extmap:3 urn:ietf:params:rtp-hdrext:sdes:rtp-stream-id 3912 a=rtcp-fb:100 ccm fir 3913 a=rtcp-fb:100 nack 3914 a=rtcp-fb:100 nack pli 3915 a=msid:81317484-2ed4-49d7-9eb7-1414322a7aae 3916 6ea4d4a1-2fda-4511-a9cc-1b32c2e59552 3918 The SDP for |answer-B2| is shown below. In addition to the 3919 acceptance of the video m= sections, the use of a=recvonly to 3920 indicate one-way video, and the use of a=imageattr to limit the 3921 received resolution, note the use of setup:passive to maintain the 3922 existing DTLS roles. 3924 v=0 3925 o=- 4962303333179871723 2 IN IP4 0.0.0.0 3926 s=- 3927 t=0 0 3928 a=ice-options:trickle 3929 a=group:BUNDLE a1 d1 v1 v2 3930 a=group:LS a1 v1 3932 m=audio 12100 UDP/TLS/RTP/SAVPF 96 0 8 97 98 3933 c=IN IP4 192.0.2.100 3934 a=mid:a1 3935 a=sendrecv 3936 a=rtpmap:96 opus/48000/2 3937 a=rtpmap:0 PCMU/8000 3938 a=rtpmap:8 PCMA/8000 3939 a=rtpmap:97 telephone-event/8000 3940 a=rtpmap:98 telephone-event/48000 3941 a=fmtp:97 0-15 3942 a=fmtp:98 0-15 3943 a=maxptime:120 3944 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 3945 a=extmap:2 urn:ietf:params:rtp-hdrext:ssrc-audio-level 3946 a=msid:57017fee-b6c1-4162-929c-a25110252400 3947 e83006c5-a0ff-4e0a-9ed9-d3e6747be7d9 3948 a=ice-ufrag:ATEn 3949 a=ice-pwd:AtSK0WpNtpUjkY4+86js7ZQl 3950 a=fingerprint:sha-256 3951 29:E2:1C:3B:4B:9F:81:E6:B8:5C:F4:A5:A8:D8:73:04: 3952 BB:05:2F:70:9F:04:A9:0E:05:E9:26:33:E8:70:88:A2 3953 a=setup:passive 3954 a=tls-id:1 3955 a=rtcp-mux 3956 a=rtcp-mux-only 3957 a=rtcp-rsize 3958 a=candidate:1 1 udp 2113929471 203.0.113.100 10100 typ host 3959 a=candidate:1 1 udp 1845494015 198.51.100.100 11100 typ srflx 3960 raddr 203.0.113.100 rport 10100 3961 a=candidate:1 1 udp 255 192.0.2.100 12100 typ relay 3962 raddr 198.51.100.100 rport 11100 3963 a=end-of-candidates 3965 m=application 12100 UDP/DTLS/SCTP webrtc-datachannel 3966 c=IN IP4 192.0.2.100 3967 a=mid:d1 3968 a=sctp-port:5000 3969 a=max-message-size:65536 3971 m=video 12100 UDP/TLS/RTP/SAVPF 100 101 102 103 3972 c=IN IP4 192.0.2.100 3973 a=mid:v1 3974 a=recvonly 3975 a=rtpmap:100 VP8/90000 3976 a=rtpmap:101 H264/90000 3977 a=fmtp:101 packetization-mode=1;profile-level-id=42e01f 3978 a=rtpmap:102 rtx/90000 3979 a=fmtp:102 apt=100 3980 =rtpmap:103 rtx/90000 3981 a=fmtp:103 apt=101 3982 a=imageattr:100 recv [x=[48:1920],y=[48:1080],q=1.0] 3983 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 3984 a=extmap:3 urn:ietf:params:rtp-hdrext:sdes:rtp-stream-id 3985 a=rtcp-fb:100 ccm fir 3986 a=rtcp-fb:100 nack 3987 a=rtcp-fb:100 nack pli 3989 m=video 12100 UDP/TLS/RTP/SAVPF 100 101 102 103 3990 c=IN IP4 192.0.2.100 3991 a=mid:v2 3992 a=recvonly 3993 a=rtpmap:100 VP8/90000 3994 a=rtpmap:101 H264/90000 3995 a=fmtp:101 packetization-mode=1;profile-level-id=42e01f 3996 a=rtpmap:102 rtx/90000 3997 a=fmtp:102 apt=100 3998 =rtpmap:103 rtx/90000 3999 a=fmtp:103 apt=101 4000 a=imageattr:100 recv [x=[48:1920],y=[48:1080],q=1.0] 4001 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 4002 a=extmap:3 urn:ietf:params:rtp-hdrext:sdes:rtp-stream-id 4003 a=rtcp-fb:100 ccm fir 4004 a=rtcp-fb:100 nack 4005 a=rtcp-fb:100 nack pli 4007 7.3. Early Transport Warmup Example 4009 This example demonstrates the early warmup technique described in 4010 Section 4.1.8.1. Here, Alice's endpoint sends an offer to Bob's 4011 endpoint to start an audio/video call. Bob immediately responds with 4012 an answer that accepts the audio/video m= sections, but marks them as 4013 sendonly (from his perspective), meaning that Alice will not yet send 4014 media. This allows the JSEP implementation to start negotiating ICE 4015 and DTLS immediately. Bob's endpoint then prompts him to answer the 4016 call, and when he does, his endpoint sends a second offer which 4017 enables the audio and video m= sections, and thereby bidirectional 4018 media transmission. The advantage of such a flow is that as soon as 4019 the first answer is received, the implementation can proceed with ICE 4020 and DTLS negotiation and establish the session transport. If the 4021 transport setup completes before the second offer is sent, then media 4022 can be transmitted immediately by the callee immediately upon 4023 answering the call, minimizing perceived post-dial-delay. The second 4024 offer/answer exchange can also change the preferred codecs or other 4025 session parameters. 4027 This example also makes use of the "relay" ICE candidate policy 4028 described in Section 3.5.3 to minimize the ICE gathering and checking 4029 needed. 4031 // set up local media state 4032 AliceJS->AliceUA: create new PeerConnection with "relay" ICE policy 4033 AliceJS->AliceUA: addTrack with two tracks: audio and video 4034 AliceJS->AliceUA: createOffer to get |offer-C1| 4035 AliceJS->AliceUA: setLocalDescription with |offer-C1| 4037 // |offer-C1| is sent over signaling protocol to Bob 4038 AliceJS->WebServer: signaling with |offer-C1| 4039 WebServer->BobJS: signaling with |offer-C1| 4041 // |offer-C1| arrives at Bob 4042 BobJS->BobUA: create new PeerConnection with "relay" ICE policy 4043 BobJS->BobUA: setRemoteDescription with |offer-C1| 4044 BobUA->BobJS: ontrack events for audio and video 4046 // a relay candidate is sent to Bob 4047 AliceUA->AliceJS: onicecandidate (relay) |offer-C1-candidate-1| 4048 AliceJS->WebServer: signaling with |offer-C1-candidate-1| 4050 WebServer->BobJS: signaling with |offer-C1-candidate-1| 4051 BobJS->BobUA: addIceCandidate with |offer-C1-candidate-1| 4053 // Bob prepares an early answer to warmup the transport 4054 BobJS->BobUA: addTransceiver with null audio and video tracks 4055 BobJS->BobUA: transceiver.setDirection(sendonly) for both 4056 BobJS->BobUA: createAnswer 4057 BobJS->BobUA: setLocalDescription with answer 4059 // |answer-C1| is sent over signaling protocol to Alice 4060 BobJS->WebServer: signaling with |answer-C1| 4061 WebServer->AliceJS: signaling with |answer-C1| 4063 // |answer-C1| (sendonly) arrives at Alice 4064 AliceJS->AliceUA: setRemoteDescription with |answer-C1| 4065 AliceUA->AliceJS: ontrack events for audio and video 4067 // a relay candidate is sent to Alice 4068 BobUA->BobJS: onicecandidate (relay) |answer-B1-candidate-1| 4069 BobJS->WebServer: signaling with |answer-B1-candidate-1| 4071 WebServer->AliceJS: signaling with |answer-B1-candidate-1| 4072 AliceJS->AliceUA: addIceCandidate with |answer-B1-candidate-1| 4074 // ICE and DTLS establish while call is ringing 4076 // Bob accepts call, starts media, and sends new offer 4077 BobJS->BobUA: transceiver.setTrack with audio and video tracks 4078 BobUA->AliceUA: media sent from Bob to Alice 4079 BobJS->BobUA: transceiver.setDirection(sendrecv) for both 4080 transceivers 4081 BobJS->BobUA: createOffer 4082 BobJS->BobUA: setLocalDescription with offer 4084 // |offer-C2| is sent over signaling protocol to Alice 4085 BobJS->WebServer: signaling with |offer-C2| 4086 WebServer->AliceJS: signaling with |offer-C2| 4088 // |offer-C2| (sendrecv) arrives at Alice 4089 AliceJS->AliceUA: setRemoteDescription with |offer-C2| 4090 AliceJS->AliceUA: createAnswer 4091 AliceJS->AliceUA: setLocalDescription with |answer-C2| 4092 AliceUA->BobUA: media sent from Alice to Bob 4094 // |answer-C2| is sent over signaling protocol to Bob 4095 AliceJS->WebServer: signaling with |answer-C2| 4096 WebServer->BobJS: signaling with |answer-C2| 4097 BobJS->BobUA: setRemoteDescription with |answer-C2| 4099 The SDP for |offer-C1| looks like: 4101 v=0 4102 o=- 1070771854436052752 1 IN IP4 0.0.0.0 4103 s=- 4104 t=0 0 4105 a=ice-options:trickle 4106 a=group:BUNDLE a1 v1 4107 a=group:LS a1 v1 4109 m=audio 9 UDP/TLS/RTP/SAVPF 96 0 8 97 98 4110 c=IN IP4 0.0.0.0 4111 a=mid:a1 4112 a=sendrecv 4113 a=rtpmap:96 opus/48000/2 4114 a=rtpmap:0 PCMU/8000 4115 a=rtpmap:8 PCMA/8000 4116 a=rtpmap:97 telephone-event/8000 4117 a=rtpmap:98 telephone-event/48000 4118 a=fmtp:97 0-15 4119 a=fmtp:98 0-15 4120 a=maxptime:120 4121 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 4122 a=extmap:2 urn:ietf:params:rtp-hdrext:ssrc-audio-level 4123 a=msid:bbce3ba6-abfc-ac63-d00a-e15b286f8fce 4124 e80098db-7159-3c06-229a-00df2a9b3dbc 4126 a=ice-ufrag:4ZcD 4127 a=ice-pwd:ZaaG6OG7tCn4J/lehAGz+HHD 4128 a=fingerprint:sha-256 4129 C4:68:F8:77:6A:44:F1:98:6D:7C:9F:47:EB:E3:34:A4: 4130 0A:AA:2D:49:08:28:70:2E:1F:AE:18:7D:4E:3E:66:BF 4131 a=setup:actpass 4132 a=tls-id:1 4133 a=rtcp-mux 4134 a=rtcp-mux-only 4135 a=rtcp-rsize 4137 m=video 0 UDP/TLS/RTP/SAVPF 100 101 102 103 4138 c=IN IP4 0.0.0.0 4139 a=mid:v1 4140 a=sendrecv 4141 a=rtpmap:100 VP8/90000 4142 a=rtpmap:101 H264/90000 4143 a=fmtp:101 packetization-mode=1;profile-level-id=42e01f 4144 a=rtpmap:102 rtx/90000 4145 a=fmtp:102 apt=100 4146 =rtpmap:103 rtx/90000 4147 a=fmtp:103 apt=101 4148 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 4149 a=extmap:3 urn:ietf:params:rtp-hdrext:sdes:rtp-stream-id 4150 a=rtcp-fb:100 ccm fir 4151 a=rtcp-fb:100 nack 4152 a=rtcp-fb:100 nack pli 4153 a=msid:bbce3ba6-abfc-ac63-d00a-e15b286f8fce 4154 ac701365-eb06-42df-cc93-7f22bc308789 4155 a=bundle-only 4157 |offer-C1-candidate-1| looks like: 4159 ufrag 4ZcD 4160 index 0 4161 mid a1 4162 attr candidate:1 1 udp 255 192.0.2.100 12100 typ relay 4163 raddr 0.0.0.0 rport 0 4165 The SDP for |answer-C1| looks like: 4167 v=0 4168 o=- 6386516489780559513 1 IN IP4 0.0.0.0 4169 s=- 4170 t=0 0 4171 a=ice-options:trickle 4172 a=group:BUNDLE a1 v1 4173 a=group:LS a1 v1 4175 m=audio 9 UDP/TLS/RTP/SAVPF 96 0 8 97 98 4176 c=IN IP4 0.0.0.0 4177 a=mid:a1 4178 a=sendonly 4179 a=rtpmap:96 opus/48000/2 4180 a=rtpmap:0 PCMU/8000 4181 a=rtpmap:8 PCMA/8000 4182 a=rtpmap:97 telephone-event/8000 4183 a=rtpmap:98 telephone-event/48000 4184 a=fmtp:97 0-15 4185 a=fmtp:98 0-15 4186 a=maxptime:120 4187 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 4188 a=extmap:2 urn:ietf:params:rtp-hdrext:ssrc-audio-level 4189 a=msid:751f239e-4ae0-c549-aa3d-890de772998b 4190 04b5a445-82cc-c9e8-9ffe-c24d0ef4b0ff 4191 a=ice-ufrag:TpaA 4192 a=ice-pwd:t2Ouhc67y8JcCaYZxUUTgKw/ 4193 a=fingerprint:sha-256 4194 A2:F3:A5:6D:4C:8C:1E:B2:62:10:4A:F6:70:61:C4:FC: 4195 3C:E0:01:D6:F3:24:80:74:DA:7C:3E:50:18:7B:CE:4D 4196 a=setup:active 4197 a=tls-id:1 4198 a=rtcp-mux 4199 a=rtcp-mux-only 4200 a=rtcp-rsize 4202 m=video 9 UDP/TLS/RTP/SAVPF 100 101 102 103 4203 c=IN IP4 0.0.0.0 4204 a=mid:v1 4205 a=sendonly 4206 a=rtpmap:100 VP8/90000 4207 a=rtpmap:101 H264/90000 4208 a=fmtp:101 packetization-mode=1;profile-level-id=42e01f 4209 a=rtpmap:102 rtx/90000 4210 a=fmtp:102 apt=100 4211 =rtpmap:103 rtx/90000 4212 a=fmtp:103 apt=101 4213 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 4214 a=extmap:3 urn:ietf:params:rtp-hdrext:sdes:rtp-stream-id 4215 a=rtcp-fb:100 ccm fir 4216 a=rtcp-fb:100 nack 4217 a=rtcp-fb:100 nack pli 4218 a=msid:751f239e-4ae0-c549-aa3d-890de772998b 4219 39292672-c102-d075-f580-5826f31ca958 4221 |answer-C1-candidate-1| looks like: 4223 ufrag TpaA 4224 index 0 4225 mid a1 4226 attr candidate:1 1 udp 255 192.0.2.200 12200 typ relay 4227 raddr 0.0.0.0 rport 0 4229 The SDP for |offer-C2| looks like: 4231 v=0 4232 o=- 6386516489780559513 2 IN IP4 0.0.0.0 4233 s=- 4234 t=0 0 4235 a=ice-options:trickle 4236 a=group:BUNDLE a1 v1 4237 a=group:LS a1 v1 4239 m=audio 12200 UDP/TLS/RTP/SAVPF 96 0 8 97 98 4240 c=IN IP4 192.0.2.200 4241 a=mid:a1 4242 a=sendrecv 4243 a=rtpmap:96 opus/48000/2 4244 a=rtpmap:0 PCMU/8000 4245 a=rtpmap:8 PCMA/8000 4246 a=rtpmap:97 telephone-event/8000 4247 a=rtpmap:98 telephone-event/48000 4248 a=fmtp:97 0-15 4249 a=fmtp:98 0-15 4250 a=maxptime:120 4251 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 4252 a=extmap:2 urn:ietf:params:rtp-hdrext:ssrc-audio-level 4253 a=msid:751f239e-4ae0-c549-aa3d-890de772998b 4254 04b5a445-82cc-c9e8-9ffe-c24d0ef4b0ff 4255 a=ice-ufrag:TpaA 4256 a=ice-pwd:t2Ouhc67y8JcCaYZxUUTgKw/ 4257 a=fingerprint:sha-256 4258 A2:F3:A5:6D:4C:8C:1E:B2:62:10:4A:F6:70:61:C4:FC: 4259 3C:E0:01:D6:F3:24:80:74:DA:7C:3E:50:18:7B:CE:4D 4260 a=setup:actpass 4261 a=tls-id:1 4262 a=rtcp-mux 4263 a=rtcp-mux-only 4264 a=rtcp-rsize 4265 a=candidate:1 1 udp 255 192.0.2.200 12200 typ relay 4266 raddr 0.0.0.0 rport 0 4267 a=end-of-candidates 4269 m=video 12200 UDP/TLS/RTP/SAVPF 100 101 102 103 4270 c=IN IP4 192.0.2.200 4271 a=mid:v1 4272 a=sendrecv 4273 a=rtpmap:100 VP8/90000 4274 a=rtpmap:101 H264/90000 4275 a=fmtp:101 packetization-mode=1;profile-level-id=42e01f 4276 a=rtpmap:102 rtx/90000 4277 a=fmtp:102 apt=100 4278 =rtpmap:103 rtx/90000 4279 a=fmtp:103 apt=101 4280 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 4281 a=extmap:3 urn:ietf:params:rtp-hdrext:sdes:rtp-stream-id 4282 a=rtcp-fb:100 ccm fir 4283 a=rtcp-fb:100 nack 4284 a=rtcp-fb:100 nack pli 4285 a=msid:751f239e-4ae0-c549-aa3d-890de772998b 4286 39292672-c102-d075-f580-5826f31ca958 4288 The SDP for |answer-C2| looks like: 4290 v=0 4291 o=- 1070771854436052752 2 IN IP4 0.0.0.0 4292 s=- 4293 t=0 0 4294 a=ice-options:trickle 4295 a=group:BUNDLE a1 v1 4296 a=group:LS a1 v1 4298 m=audio 12100 UDP/TLS/RTP/SAVPF 96 0 8 97 98 4299 c=IN IP4 192.0.2.100 4300 a=mid:a1 4301 a=sendrecv 4302 a=rtpmap:96 opus/48000/2 4303 a=rtpmap:0 PCMU/8000 4304 a=rtpmap:8 PCMA/8000 4305 a=rtpmap:97 telephone-event/8000 4306 a=rtpmap:98 telephone-event/48000 4307 a=fmtp:97 0-15 4308 a=fmtp:98 0-15 4309 a=maxptime:120 4310 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 4311 a=extmap:2 urn:ietf:params:rtp-hdrext:ssrc-audio-level 4312 a=msid:bbce3ba6-abfc-ac63-d00a-e15b286f8fce 4313 e80098db-7159-3c06-229a-00df2a9b3dbc 4314 a=ice-ufrag:4ZcD 4315 a=ice-pwd:ZaaG6OG7tCn4J/lehAGz+HHD 4316 a=fingerprint:sha-256 4317 C4:68:F8:77:6A:44:F1:98:6D:7C:9F:47:EB:E3:34:A4: 4318 0A:AA:2D:49:08:28:70:2E:1F:AE:18:7D:4E:3E:66:BF 4319 a=setup:passive 4320 a=tls-id:1 4321 a=rtcp-mux 4322 a=rtcp-mux-only 4323 a=rtcp-rsize 4324 a=candidate:1 1 udp 255 192.0.2.100 12100 typ relay 4325 raddr 0.0.0.0 rport 0 4326 a=end-of-candidates 4328 m=video 12100 UDP/TLS/RTP/SAVPF 100 101 102 103 4329 c=IN IP4 192.0.2.100 4330 a=mid:v1 4331 a=sendrecv 4332 a=rtpmap:100 VP8/90000 4333 a=rtpmap:101 H264/90000 4334 a=fmtp:101 packetization-mode=1;profile-level-id=42e01f 4335 a=rtpmap:102 rtx/90000 4336 a=fmtp:102 apt=100 4337 =rtpmap:103 rtx/90000 4338 a=fmtp:103 apt=101 4339 a=extmap:1 urn:ietf:params:rtp-hdrext:sdes:mid 4340 a=extmap:3 urn:ietf:params:rtp-hdrext:sdes:rtp-stream-id 4341 a=rtcp-fb:100 ccm fir 4342 a=rtcp-fb:100 nack 4343 a=rtcp-fb:100 nack pli 4344 a=msid:bbce3ba6-abfc-ac63-d00a-e15b286f8fce 4345 ac701365-eb06-42df-cc93-7f22bc308789 4347 8. Security Considerations 4349 The IETF has published separate documents 4350 [I-D.ietf-rtcweb-security-arch] [I-D.ietf-rtcweb-security] describing 4351 the security architecture for WebRTC as a whole. The remainder of 4352 this section describes security considerations for this document. 4354 While formally the JSEP interface is an API, it is better to think of 4355 it is an Internet protocol, with the JS being untrustworthy from the 4356 perspective of the endpoint. Thus, the threat model of [RFC3552] 4357 applies. In particular, JS can call the API in any order and with 4358 any inputs, including malicious ones. This is particularly relevant 4359 when we consider the SDP which is passed to setLocalDescription(). 4360 While correct API usage requires that the application pass in SDP 4361 which was derived from createOffer() or createAnswer(), there is no 4362 guarantee that applications do so. The JSEP implementation MUST be 4363 prepared for the JS to pass in bogus data instead. 4365 Conversely, the application programmer MUST recognize that the JS 4366 does not have complete control of endpoint behavior. One case that 4367 bears particular mention is that editing ICE candidates out of the 4368 SDP or suppressing trickled candidates does not have the expected 4369 behavior: implementations will still perform checks from those 4370 candidates even if they are not sent to the other side. Thus, for 4371 instance, it is not possible to prevent the remote peer from learning 4372 your public IP address by removing server reflexive candidates. 4373 Applications which wish to conceal their public IP address should 4374 instead configure the ICE agent to use only relay candidates. 4376 9. IANA Considerations 4378 This document requires no actions from IANA. 4380 10. Acknowledgements 4382 Harald Alvestrand, Taylor Brandstetter, Suhas Nandakumar, and Peter 4383 Thatcher provided significant text for this draft. Bernard Aboba, 4384 Adam Bergkvist, Dan Burnett, Ben Campbell, Alissa Cooper, Richard 4385 Ejzak, Stefan Hakansson, Ted Hardie, Christer Holmberg Andrew Hutton, 4386 Randell Jesup, Matthew Kaufman, Anant Narayanan, Adam Roach, Neil 4387 Stratford, Martin Thomson, Sean Turner, and Magnus Westerlund all 4388 provided valuable feedback on this proposal. 4390 11. References 4392 11.1. Normative References 4394 [I-D.ietf-avtext-rid] 4395 Roach, A., Nandakumar, S., and P. Thatcher, "RTP Stream 4396 Identifier Source Description (SDES)", draft-ietf-avtext- 4397 rid-09 (work in progress), October 2016. 4399 [I-D.ietf-ice-trickle] 4400 Ivov, E., Rescorla, E., Uberti, J., and P. Saint-Andre, 4401 "Trickle ICE: Incremental Provisioning of Candidates for 4402 the Interactive Connectivity Establishment (ICE) 4403 Protocol", draft-ietf-ice-trickle-12 (work in progress), 4404 June 2017. 4406 [I-D.ietf-mmusic-dtls-sdp] 4407 Holmberg, C. and R. Shpount, "Using the SDP Offer/Answer 4408 Mechanism for DTLS", draft-ietf-mmusic-dtls-sdp-26 (work 4409 in progress), June 2017. 4411 [I-D.ietf-mmusic-msid] 4412 Alvestrand, H., "WebRTC MediaStream Identification in the 4413 Session Description Protocol", draft-ietf-mmusic-msid-16 4414 (work in progress), February 2017. 4416 [I-D.ietf-mmusic-mux-exclusive] 4417 Holmberg, C., "Indicating Exclusive Support of RTP/RTCP 4418 Multiplexing using SDP", draft-ietf-mmusic-mux- 4419 exclusive-12 (work in progress), May 2017. 4421 [I-D.ietf-mmusic-rid] 4422 Thatcher, P., Zanaty, M., Nandakumar, S., Burman, B., 4423 Roach, A., and B. Campen, "RTP Payload Format 4424 Restrictions", draft-ietf-mmusic-rid-10 (work in 4425 progress), March 2017. 4427 [I-D.ietf-mmusic-sctp-sdp] 4428 Holmberg, C., Shpount, R., Loreto, S., and G. Camarillo, 4429 "Session Description Protocol (SDP) Offer/Answer 4430 Procedures For Stream Control Transmission Protocol (SCTP) 4431 over Datagram Transport Layer Security (DTLS) Transport.", 4432 draft-ietf-mmusic-sctp-sdp-26 (work in progress), April 4433 2017. 4435 [I-D.ietf-mmusic-sdp-bundle-negotiation] 4436 Holmberg, C., Alvestrand, H., and C. Jennings, 4437 "Negotiating Media Multiplexing Using the Session 4438 Description Protocol (SDP)", draft-ietf-mmusic-sdp-bundle- 4439 negotiation-38 (work in progress), April 2017. 4441 [I-D.ietf-mmusic-sdp-mux-attributes] 4442 Nandakumar, S., "A Framework for SDP Attributes when 4443 Multiplexing", draft-ietf-mmusic-sdp-mux-attributes-16 4444 (work in progress), December 2016. 4446 [I-D.ietf-mmusic-sdp-simulcast] 4447 Burman, B., Westerlund, M., Nandakumar, S., and M. Zanaty, 4448 "Using Simulcast in SDP and RTP Sessions", draft-ietf- 4449 mmusic-sdp-simulcast-08 (work in progress), March 2017. 4451 [I-D.ietf-rtcweb-fec] 4452 Uberti, J., "WebRTC Forward Error Correction 4453 Requirements", draft-ietf-rtcweb-fec-05 (work in 4454 progress), May 2017. 4456 [I-D.ietf-rtcweb-rtp-usage] 4457 Perkins, C., Westerlund, M., and J. Ott, "Web Real-Time 4458 Communication (WebRTC): Media Transport and Use of RTP", 4459 draft-ietf-rtcweb-rtp-usage-26 (work in progress), March 4460 2016. 4462 [I-D.ietf-rtcweb-security] 4463 Rescorla, E., "Security Considerations for WebRTC", draft- 4464 ietf-rtcweb-security-08 (work in progress), February 2015. 4466 [I-D.ietf-rtcweb-security-arch] 4467 Rescorla, E., "WebRTC Security Architecture", draft-ietf- 4468 rtcweb-security-arch-12 (work in progress), June 2016. 4470 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4471 Requirement Levels", BCP 14, RFC 2119, 4472 DOI 10.17487/RFC2119, March 1997, 4473 . 4475 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 4476 A., Peterson, J., Sparks, R., Handley, M., and E. 4477 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 4478 DOI 10.17487/RFC3261, June 2002, 4479 . 4481 [RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model 4482 with Session Description Protocol (SDP)", RFC 3264, 4483 DOI 10.17487/RFC3264, June 2002, 4484 . 4486 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 4487 Text on Security Considerations", BCP 72, RFC 3552, 4488 DOI 10.17487/RFC3552, July 2003, 4489 . 4491 [RFC3605] Huitema, C., "Real Time Control Protocol (RTCP) attribute 4492 in Session Description Protocol (SDP)", RFC 3605, 4493 DOI 10.17487/RFC3605, October 2003, 4494 . 4496 [RFC3711] Baugher, M., McGrew, D., Naslund, M., Carrara, E., and K. 4497 Norrman, "The Secure Real-time Transport Protocol (SRTP)", 4498 RFC 3711, DOI 10.17487/RFC3711, March 2004, 4499 . 4501 [RFC3890] Westerlund, M., "A Transport Independent Bandwidth 4502 Modifier for the Session Description Protocol (SDP)", 4503 RFC 3890, DOI 10.17487/RFC3890, September 2004, 4504 . 4506 [RFC4145] Yon, D. and G. Camarillo, "TCP-Based Media Transport in 4507 the Session Description Protocol (SDP)", RFC 4145, 4508 DOI 10.17487/RFC4145, September 2005, 4509 . 4511 [RFC4566] Handley, M., Jacobson, V., and C. Perkins, "SDP: Session 4512 Description Protocol", RFC 4566, DOI 10.17487/RFC4566, 4513 July 2006, . 4515 [RFC4585] Ott, J., Wenger, S., Sato, N., Burmeister, C., and J. Rey, 4516 "Extended RTP Profile for Real-time Transport Control 4517 Protocol (RTCP)-Based Feedback (RTP/AVPF)", RFC 4585, 4518 DOI 10.17487/RFC4585, July 2006, 4519 . 4521 [RFC5124] Ott, J. and E. Carrara, "Extended Secure RTP Profile for 4522 Real-time Transport Control Protocol (RTCP)-Based Feedback 4523 (RTP/SAVPF)", RFC 5124, DOI 10.17487/RFC5124, February 4524 2008, . 4526 [RFC5245] Rosenberg, J., "Interactive Connectivity Establishment 4527 (ICE): A Protocol for Network Address Translator (NAT) 4528 Traversal for Offer/Answer Protocols", RFC 5245, 4529 DOI 10.17487/RFC5245, April 2010, 4530 . 4532 [RFC5285] Singer, D. and H. Desineni, "A General Mechanism for RTP 4533 Header Extensions", RFC 5285, DOI 10.17487/RFC5285, July 4534 2008, . 4536 [RFC5761] Perkins, C. and M. Westerlund, "Multiplexing RTP Data and 4537 Control Packets on a Single Port", RFC 5761, 4538 DOI 10.17487/RFC5761, April 2010, 4539 . 4541 [RFC5888] Camarillo, G. and H. Schulzrinne, "The Session Description 4542 Protocol (SDP) Grouping Framework", RFC 5888, 4543 DOI 10.17487/RFC5888, June 2010, 4544 . 4546 [RFC6236] Johansson, I. and K. Jung, "Negotiation of Generic Image 4547 Attributes in the Session Description Protocol (SDP)", 4548 RFC 6236, DOI 10.17487/RFC6236, May 2011, 4549 . 4551 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4552 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 4553 January 2012, . 4555 [RFC6716] Valin, JM., Vos, K., and T. Terriberry, "Definition of the 4556 Opus Audio Codec", RFC 6716, DOI 10.17487/RFC6716, 4557 September 2012, . 4559 [RFC6904] Lennox, J., "Encryption of Header Extensions in the Secure 4560 Real-time Transport Protocol (SRTP)", RFC 6904, 4561 DOI 10.17487/RFC6904, April 2013, 4562 . 4564 [RFC7160] Petit-Huguenin, M. and G. Zorn, Ed., "Support for Multiple 4565 Clock Rates in an RTP Session", RFC 7160, 4566 DOI 10.17487/RFC7160, April 2014, 4567 . 4569 [RFC7587] Spittka, J., Vos, K., and JM. Valin, "RTP Payload Format 4570 for the Opus Speech and Audio Codec", RFC 7587, 4571 DOI 10.17487/RFC7587, June 2015, 4572 . 4574 [RFC7742] Roach, A., "WebRTC Video Processing and Codec 4575 Requirements", RFC 7742, DOI 10.17487/RFC7742, March 2016, 4576 . 4578 [RFC7850] Nandakumar, S., "Registering Values of the SDP 'proto' 4579 Field for Transporting RTP Media over TCP under Various 4580 RTP Profiles", RFC 7850, DOI 10.17487/RFC7850, April 2016, 4581 . 4583 [RFC7874] Valin, JM. and C. Bran, "WebRTC Audio Codec and Processing 4584 Requirements", RFC 7874, DOI 10.17487/RFC7874, May 2016, 4585 . 4587 [RFC8108] Lennox, J., Westerlund, M., Wu, Q., and C. Perkins, 4588 "Sending Multiple RTP Streams in a Single RTP Session", 4589 RFC 8108, DOI 10.17487/RFC8108, March 2017, 4590 . 4592 [RFC8122] Lennox, J. and C. Holmberg, "Connection-Oriented Media 4593 Transport over the Transport Layer Security (TLS) Protocol 4594 in the Session Description Protocol (SDP)", RFC 8122, 4595 DOI 10.17487/RFC8122, March 2017, 4596 . 4598 11.2. Informative References 4600 [I-D.ietf-mmusic-trickle-ice-sip] 4601 Ivov, E., Stach, T., Marocco, E., and C. Holmberg, "A 4602 Session Initiation Protocol (SIP) usage for Trickle ICE", 4603 draft-ietf-mmusic-trickle-ice-sip-07 (work in progress), 4604 March 2017. 4606 [I-D.ietf-rtcweb-ip-handling] 4607 Uberti, J. and G. Shieh, "WebRTC IP Address Handling 4608 Requirements", draft-ietf-rtcweb-ip-handling-03 (work in 4609 progress), January 2017. 4611 [I-D.ietf-rtcweb-sdp] 4612 Nandakumar, S. and C. Jennings, "Annotated Example SDP for 4613 WebRTC", draft-ietf-rtcweb-sdp-06 (work in progress), 4614 April 2017. 4616 [RFC3389] Zopf, R., "Real-time Transport Protocol (RTP) Payload for 4617 Comfort Noise (CN)", RFC 3389, DOI 10.17487/RFC3389, 4618 September 2002, . 4620 [RFC3556] Casner, S., "Session Description Protocol (SDP) Bandwidth 4621 Modifiers for RTP Control Protocol (RTCP) Bandwidth", 4622 RFC 3556, DOI 10.17487/RFC3556, July 2003, 4623 . 4625 [RFC3960] Camarillo, G. and H. Schulzrinne, "Early Media and Ringing 4626 Tone Generation in the Session Initiation Protocol (SIP)", 4627 RFC 3960, DOI 10.17487/RFC3960, December 2004, 4628 . 4630 [RFC4568] Andreasen, F., Baugher, M., and D. Wing, "Session 4631 Description Protocol (SDP) Security Descriptions for Media 4632 Streams", RFC 4568, DOI 10.17487/RFC4568, July 2006, 4633 . 4635 [RFC4588] Rey, J., Leon, D., Miyazaki, A., Varsa, V., and R. 4636 Hakenberg, "RTP Retransmission Payload Format", RFC 4588, 4637 DOI 10.17487/RFC4588, July 2006, 4638 . 4640 [RFC4733] Schulzrinne, H. and T. Taylor, "RTP Payload for DTMF 4641 Digits, Telephony Tones, and Telephony Signals", RFC 4733, 4642 DOI 10.17487/RFC4733, December 2006, 4643 . 4645 [RFC5506] Johansson, I. and M. Westerlund, "Support for Reduced-Size 4646 Real-Time Transport Control Protocol (RTCP): Opportunities 4647 and Consequences", RFC 5506, DOI 10.17487/RFC5506, April 4648 2009, . 4650 [RFC5576] Lennox, J., Ott, J., and T. Schierl, "Source-Specific 4651 Media Attributes in the Session Description Protocol 4652 (SDP)", RFC 5576, DOI 10.17487/RFC5576, June 2009, 4653 . 4655 [RFC5763] Fischl, J., Tschofenig, H., and E. Rescorla, "Framework 4656 for Establishing a Secure Real-time Transport Protocol 4657 (SRTP) Security Context Using Datagram Transport Layer 4658 Security (DTLS)", RFC 5763, DOI 10.17487/RFC5763, May 4659 2010, . 4661 [RFC5764] McGrew, D. and E. Rescorla, "Datagram Transport Layer 4662 Security (DTLS) Extension to Establish Keys for the Secure 4663 Real-time Transport Protocol (SRTP)", RFC 5764, 4664 DOI 10.17487/RFC5764, May 2010, 4665 . 4667 [RFC6464] Lennox, J., Ed., Ivov, E., and E. Marocco, "A Real-time 4668 Transport Protocol (RTP) Header Extension for Client-to- 4669 Mixer Audio Level Indication", RFC 6464, 4670 DOI 10.17487/RFC6464, December 2011, 4671 . 4673 [RFC6544] Rosenberg, J., Keranen, A., Lowekamp, B., and A. Roach, 4674 "TCP Candidates with Interactive Connectivity 4675 Establishment (ICE)", RFC 6544, DOI 10.17487/RFC6544, 4676 March 2012, . 4678 [TS26.114] 4679 3GPP TS 26.114 V12.8.0, "3rd Generation Partnership 4680 Project; Technical Specification Group Services and System 4681 Aspects; IP Multimedia Subsystem (IMS); Multimedia 4682 Telephony; Media handling and interaction (Release 12)", 4683 December 2014, . 4685 [W3C.webrtc] 4686 Bergkvist, A., Burnett, D., Jennings, C., Narayanan, A., 4687 Aboba, B., and T. Brandstetter, "WebRTC 1.0: Real-time 4688 Communication Between Browsers", World Wide Web Consortium 4689 WD WD-webrtc-20170515, May 2017, 4690 . 4692 Appendix A. Appendix A 4694 For the syntax validation performed in Section 5.7, the following 4695 list of ABNF definitions is used: 4697 +------------------------+------------------------------------------+ 4698 | Attribute | Reference | 4699 +------------------------+------------------------------------------+ 4700 | ptime | [RFC4566] Section 9 | 4701 | maxptime | [RFC4566] Section 9 | 4702 | rtpmap | [RFC4566] Section 9 | 4703 | recvonly | [RFC4566] Section 9 | 4704 | sendrecv | [RFC4566] Section 9 | 4705 | sendonly | [RFC4566] Section 9 | 4706 | inactive | [RFC4566] Section 9 | 4707 | framerate | [RFC4566] Section 9 | 4708 | fmtp | [RFC4566] Section 9 | 4709 | quality | [RFC4566] Section 9 | 4710 | rtcp | [RFC3605] Section 2.1 | 4711 | setup | [RFC4145] Sections 3, 4, and 5 | 4712 | connection | [RFC4145] Sections 3, 4, and 5 | 4713 | fingerprint | [RFC8122] Section 5 | 4714 | rtcp-fb | [RFC4585] Section 4.2 | 4715 | candidate | [RFC5245] Section 15.1 | 4716 | remote-candidates | [RFC5245] Section 15.2 | 4717 | ice-lite | [RFC5245] Section 15.3 | 4718 | ice-ufrag | [RFC5245] Section 15.4 | 4719 | ice-pwd | [RFC5245] Section 15.4 | 4720 | ice-options | [RFC5245] Section 15.5 | 4721 | extmap | [RFC5285] Section 7 | 4722 | mid | [RFC5888] Sections 4 and 5 | 4723 | group | [RFC5888] Sections 4 and 5 | 4724 | imageattr | [RFC6236] Section 3.1 | 4725 | extmap (encrypt | [RFC6904] Section 4 | 4726 | option) | | 4727 | msid | [I-D.ietf-mmusic-msid] Section 2 | 4728 | rid | [I-D.ietf-mmusic-rid] Section 10 | 4729 | simulcast | [I-D.ietf-mmusic-sdp-simulcast] Section | 4730 | | 6.1 | 4731 | tls-id | [I-D.ietf-mmusic-dtls-sdp] Section 4 | 4732 +------------------------+------------------------------------------+ 4734 Table 1: SDP ABNF References 4736 Appendix B. Change log 4738 Note: This section will be removed by RFC Editor before publication. 4740 Changes in draft-21: 4742 o Change dtls-id to tls-id to match MMUSIC draft. 4744 o Replace regular expression for proto field with a list and clarify 4745 that the answer must exactly match the offer. 4747 o Remove text about how to error check on setLocal because local 4748 descriptions cannot be changed. 4750 o Rework silence suppression support to always require that both 4751 sides agree to silence suppression or none is used. 4753 o Remove instructions to parse "a=ssrc-group". 4755 o Allow the addition of new codecs in answers and in subsequent 4756 offers. 4758 o Clarify imageattr processing. Replace use of [x=0,y=0] with 4759 direction indicators. 4761 o Document when early media can occur. 4763 o Fix ICE default port handling when bundle-only is used. 4765 o Forbid duplicating IDENTICAL/TRANSPORT attributes when you are 4766 bundling. 4768 o Clarify the number of components to gather when bundle is 4769 involved. 4771 o Explicitly state that PTs and SSRCs are to be used for demuxing. 4773 o Update guidance on "a=setup" line. This should now match the 4774 MMUSIC draft. 4776 o Update guidance on certificate/digest matching to conform to 4777 RFC8122. 4779 o Update examples. 4781 Changes in draft-20: 4783 o Remove Appendix-B. 4785 Changes in draft-19: 4787 o Examples are now machine-generated for correctness, and use IETF- 4788 approved example IP addresses. 4790 o Add early transport warmup example, and add missing attributes to 4791 existing examples. 4793 o Only send "a=rtcp-mux-only" and "a=bundle-only" on new m= 4794 sections. 4796 o Update references. 4798 o Add coverage of a=identity. 4800 o Explain the lipsync group algorithm more thoroughly. 4802 o Remove unnecessary list of MTI specs. 4804 o Allow codecs which weren't offered to appear in answers and which 4805 weren't selected to appear in subsequent offers. 4807 o Codec preferences now are applied on both initial and subsequent 4808 offers and answers. 4810 o Clarify a=msid handling for recvonly m= sections. 4812 o Clarify behavior of attributes for bundle-only data channels. 4814 o Allow media attributes to appear in data m= sections when all the 4815 media m= sections are bundle-only. 4817 o Use consistent terminology for JSEP implementations. 4819 o Describe how to handle failed API calls. 4821 o Some cleanup on routing rules. 4823 Changes in draft-18: 4825 o Update demux algorithm and move it to an appendix in preparation 4826 for merging it into BUNDLE. 4828 o Clarify why we can't handle an incoming offer to send simulcast. 4830 o Expand IceCandidate object text. 4832 o Further document use of ICE candidate pool. 4834 o Document removeTrack. 4836 o Update requirements to only accept the last generated offer/answer 4837 as an argument to setLocalDescription. 4839 o Allow round pixels. 4841 o Fix code around default timing when AVPF is not specified. 4843 o Clean up terminology around m= line and m=section. 4845 o Provide a more realistic example for minimum decoder capabilities. 4847 o Document behavior when rtcp-mux policy is require but rtcp-mux 4848 attribute not provided. 4850 o Expanded discussion of RtpSender and RtpReceiver. 4852 o Add RtpTransceiver.currentDirection and document setDirection. 4854 o Require imageattr x=0, y=0 to indicate that there are no valid 4855 resolutions. 4857 o Require a privacy-preserving MID/RID construction. 4859 o Require support for RFC 3556 bandwidth modifiers. 4861 o Update maxptime description. 4863 o Note that endpoints may encounter extra codecs in answers and 4864 subsequent offers from non-JSEP peers. 4866 o Update references. 4868 Changes in draft-17: 4870 o Split createOffer and createAnswer sections to clearly indicate 4871 attributes which always appear and which only appear when not 4872 bundled into another m= section. 4874 o Add descriptions of RtpTransceiver methods. 4876 o Describe how to process RTCP feedback attributes. 4878 o Clarify transceiver directions and their interaction with 3264. 4880 o Describe setCodecPreferences. 4882 o Update RTP demux algorithm. Include RTCP. 4884 o Update requirements for when a=rtcp is included, limiting to cases 4885 where it is needed for backward compatibility. 4887 o Clarify SAR handling. 4889 o Updated addTrack matching algorithm. 4891 o Remove a=ssrc requirements. 4893 o Handle a=setup in reoffers. 4895 o Discuss how RTX/FEC should be handled. 4897 o Discuss how telephone-event should be handled. 4899 o Discuss how CN/DTX should be handled. 4901 o Add missing references to ABNF table. 4903 Changes in draft-16: 4905 o Update addIceCandidate to indicate ICE generation and allow per-m= 4906 section end-of-candidates. 4908 o Update fingerprint handling to use draft-ietf-mmusic-4572-update. 4910 o Update text around SDP processing of RTP header extensions and 4911 payload formats. 4913 o Add sections on simulcast, addTransceiver, and createDataChannel. 4915 o Clarify text to ensure that the session ID is a positive 63 bit 4916 integer. 4918 o Clarify SDP processing for direction indication. 4920 o Describe SDP processing for rtcp-mux-only. 4922 o Specify how SDP session version in o= line. 4924 o Require that when doing an re-offer, the capabilities of the new 4925 session are mostly required to be a subset of the previously 4926 negotiated session. 4928 o Clarified ICE restart interaction with bundle-only. 4930 o Remove support for changing SDP before calling 4931 setLocalDescription. 4933 o Specify algorithm for demuxing RTP based on MID, PT, and SSRC. 4935 o Clarify rules for rejecting m= lines when bundle policy is 4936 balanced or max-bundle. 4938 Changes in draft-15: 4940 o Clarify text around codecs offered in subsequent transactions to 4941 refer to what's been negotiated. 4943 o Rewrite LS handling text to indicate edge cases and that we're 4944 living with them. 4946 o Require that answerer reject m= lines when there are no codecs in 4947 common. 4949 o Enforce max-bundle on offer processing. 4951 o Fix TIAS formula to handle bits vs. kilobits. 4953 o Describe addTrack algorithm. 4955 o Clean up references. 4957 Changes in draft-14: 4959 o Added discussion of RtpTransceivers + RtpSenders + RtpReceivers, 4960 and how they interact with createOffer/createAnswer. 4962 o Removed obsolete OfferToReceiveX options. 4964 o Explained how addIceCandidate can be used for end-of-candidates. 4966 Changes in draft-13: 4968 o Clarified which SDP lines can be ignored. 4970 o Clarified how to handle various received attributes. 4972 o Revised how attributes should be generated for bundled m= lines. 4974 o Remove unused references. 4976 o Remove text advocating use of unilateral PTs. 4978 o Trigger an ICE restart even if the ICE candidate policy is being 4979 made more strict. 4981 o Remove the 'public' ICE candidate policy. 4983 o Move open issues into GitHub issues. 4985 o Split local/remote description accessors into current/pending. 4987 o Clarify a=imageattr handling. 4989 o Add more detail on VoiceActivityDetection handling. 4991 o Reference draft-shieh-rtcweb-ip-handling. 4993 o Make it clear when an ICE restart should occur. 4995 o Resolve changes needed in references. 4997 o Remove MSID semantics. 4999 o ice-options are now at session level. 5001 o Default RTCP mux policy is now 'require'. 5003 Changes in draft-12: 5005 o Filled in sections on applying local and remote descriptions. 5007 o Discussed downscaling and upscaling to fulfill imageattr 5008 requirements. 5010 o Updated what SDP can be modified by the application. 5012 o Updated to latest datachannel SDP. 5014 o Allowed multiple fingerprint lines. 5016 o Switched back to IPv4 for dummy candidates. 5018 o Added additional clarity on ICE default candidates. 5020 Changes in draft-11: 5022 o Clarified handling of RTP CNAMEs. 5024 o Updated what SDP lines should be processed or ignored. 5026 o Specified how a=imageattr should be used. 5028 Changes in draft-10: 5030 o Described video size negotiation with imageattr. 5032 o Clarified rejection of sections that do not have mux-only. 5034 o Add handling of LS groups 5035 Changes in draft-09: 5037 o Don't return null for {local,remote}Description after close(). 5039 o Changed TCP/TLS to UDP/DTLS in RTP profile names. 5041 o Separate out bundle and mux policy. 5043 o Added specific references to FEC mechanisms. 5045 o Added canTrickle mechanism. 5047 o Added section on subsequent answers and, answer options. 5049 o Added text defining set{Local,Remote}Description behavior. 5051 Changes in draft-08: 5053 o Added new example section and removed old examples in appendix. 5055 o Fixed field handling. 5057 o Added text describing a=rtcp attribute. 5059 o Reworked handling of OfferToReceiveAudio and OfferToReceiveVideo 5060 per discussion at IETF 90. 5062 o Reworked trickle ICE handling and its impact on m= and c= lines 5063 per discussion at interim. 5065 o Added max-bundle-and-rtcp-mux policy. 5067 o Added description of maxptime handling. 5069 o Updated ICE candidate pool default to 0. 5071 o Resolved open issues around AppID/receiver-ID. 5073 o Reworked and expanded how changes to the ICE configuration are 5074 handled. 5076 o Some reference updates. 5078 o Editorial clarification. 5080 Changes in draft-07: 5082 o Expanded discussion of VAD and Opus DTX. 5084 o Added a security considerations section. 5086 o Rewrote the section on modifying SDP to require implementations to 5087 clearly indicate whether any given modification is allowed. 5089 o Clarified impact of IceRestart on CreateOffer in local-offer 5090 state. 5092 o Guidance on whether attributes should be defined at the media 5093 level or the session level. 5095 o Renamed "default" bundle policy to "balanced". 5097 o Removed default ICE candidate pool size and clarify how it works. 5099 o Defined a canonical order for assignment of MSTs to m= lines. 5101 o Removed discussion of rehydration. 5103 o Added Eric Rescorla as a draft editor. 5105 o Cleaned up references. 5107 o Editorial cleanup 5109 Changes in draft-06: 5111 o Reworked handling of m= line recycling. 5113 o Added handling of BUNDLE and bundle-only. 5115 o Clarified handling of rollback. 5117 o Added text describing the ICE Candidate Pool and its behavior. 5119 o Allowed OfferToReceiveX to create multiple recvonly m= sections. 5121 Changes in draft-05: 5123 o Fixed several issues identified in the createOffer/Answer sections 5124 during document review. 5126 o Updated references. 5128 Changes in draft-04: 5130 o Filled in sections on createOffer and createAnswer. 5132 o Added SDP examples. 5134 o Fixed references. 5136 Changes in draft-03: 5138 o Added text describing relationship to W3C specification 5140 Changes in draft-02: 5142 o Converted from nroff 5144 o Removed comparisons to old approaches abandoned by the working 5145 group 5147 o Removed stuff that has moved to W3C specification 5149 o Align SDP handling with W3C draft 5151 o Clarified section on forking. 5153 Changes in draft-01: 5155 o Added diagrams for architecture and state machine. 5157 o Added sections on forking and rehydration. 5159 o Clarified meaning of "pranswer" and "answer". 5161 o Reworked how ICE restarts and media directions are controlled. 5163 o Added list of parameters that can be changed in a description. 5165 o Updated suggested API and examples to match latest thinking. 5167 o Suggested API and examples have been moved to an appendix. 5169 Changes in draft -00: 5171 o Migrated from draft-uberti-rtcweb-jsep-02. 5173 Authors' Addresses 5174 Justin Uberti 5175 Google 5176 747 6th St S 5177 Kirkland, WA 98033 5178 USA 5180 Email: justin@uberti.name 5182 Cullen Jennings 5183 Cisco 5184 400 3rd Avenue SW 5185 Calgary, AB T2P 4H2 5186 Canada 5188 Email: fluffy@iii.ca 5190 Eric Rescorla (editor) 5191 Mozilla 5192 331 Evelyn Ave 5193 Mountain View, CA 94041 5194 USA 5196 Email: ekr@rtfm.com