13 | This document defines a set of ECMAScript APIs in WebIDL to extend the WebRTC 1.0 API. 14 |
15 |The API is based on preliminary work done in the W3C WEBRTC Working Group.
18 |22 | This document contains proposed extensions to the [[WEBRTC]] specification. 23 | Some of these extensions were originally included within the [[WEBRTC]] specification, 24 | but needed to be removed due to lack of implementation experience. Others were not 25 | sufficiently mature to be incorporated into that specification when they were developed, 26 | but were too small to warrant creation of a separate document. 27 |
28 |29 | This document contains some sections extending one specific interface or dictionary in 30 | the base specification; in this case the extension is only described in an individual 31 | section. Where an extension affects multiple interfaces or dictionaries, a subsection 32 | in the "Overviews" section describes the extension as a whole, while normative text 33 | is provided in sections relating to the individual interfaces. 34 |
35 |36 | As extensions mature and gain implementation experience, they may move from this document 37 | to the base specification if WG consensus emerges to do so. 38 |
39 |This specification defines conformance criteria that apply to a single 42 | product: the user agent that implements the interfaces that it 43 | contains.
44 |Conformance requirements phrased as algorithms or specific steps may be 45 | implemented in any manner, so long as the end result is equivalent. (In 46 | particular, the algorithms defined in this specification are intended to be 47 | easy to follow, and not intended to be performant.)
48 |Implementations that use ECMAScript to implement the APIs defined in 49 | this specification MUST implement them in a manner consistent with the 50 | ECMAScript Bindings defined in the Web IDL specification [[WEBIDL]], as 51 | this specification uses that specification and terminology.
52 |56 | The following terms are defined in 57 | Absolute Capture Timestamp RTP header extension 58 | [[RTP-EXT-CAPTURE-TIME]]: 59 |
60 |66 | The process of forming a candidate pair is defined in 67 | [[RFC8445]] Section 6.1.2.2. 68 |
69 |70 | The process of nominating a candidate pair is defined in 71 | [[RFC8445]] Section 8.1.1. 72 |
73 |74 | The process of freeing a candidate is defined in [[RFC8445]] Section 8.3. 75 |
76 | 77 |78 | 80 | The following terms are defined in mediacapture-extensions 81 | video timestamp concepts 82 |
83 |94 | The {{RTCPeerConnection}} interface is defined in [[WEBRTC]]. This document 95 | extends that interface by using Content-Security-Policy for ICE candidate 96 | filtering. 97 |
98 |Append the following paragraph to the 102 | administratively prohibited 103 | algorithm:
104 | 105 |If 106 | should RTC connections be blocked for global? with the 107 | [=relevant global object=] of the {{RTCPeerConnection}} object in question 108 | returns `"Blocked"`, then all candidates MUST be 110 | administratively prohibited.
111 |116 | RTP header extension control is an extension to {{RTCRtpTransceiver}} that allows 117 | to set and query the RTP header extensions supported and negotiated in SDP. 118 |
119 | The RTP header extension mechanism is defined in [[RFC8285]], with 120 | the SDP negotiation mechanism defined in section 5. It goes into some 121 | detail on the meaning of "direction" with regard to RTP header 122 | extensions, and gives a detailed procedure for negotiating RTP header 123 | extension IDs. 124 |
125 |126 | This API extension gives the means to control the use and direction of 127 | RTP header extensions as documented in [[RFC8285]]. It does not 128 | influence the ID negotiation mechanism, except for being able to 129 | control the number of extensions offered. 130 |
131 |136 | The {{RTCRtpTransceiver}} 137 | interface is defined in [[WEBRTC]]. This document extends that interface 138 | by adding an additional method and attribute in order to control negotiation of 139 | RTP header extensions. 140 |
141 |
142 | partial dictionary RTCRtpHeaderExtensionCapability {
143 | required RTCRtpTransceiverDirection direction;
144 | };
145 |
146 | partial interface RTCRtpTransceiver {
147 | sequence<RTCRtpHeaderExtensionCapability> getHeaderExtensionsToNegotiate();
148 | undefined setHeaderExtensionsToNegotiate(
149 | sequence<RTCRtpHeaderExtensionCapability> extensions);
150 | sequence<RTCRtpHeaderExtensionCapability> getNegotiatedHeaderExtensions();
151 | };
152 |
153 | 154 | Let 155 | {{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}} 156 | and 157 | {{RTCRtpTransceiver/[[NegotiatedHeaderExtensions]]}} 158 | be internal slots of the {{RTCRtpTransceiver}}, initialized as follows: 159 |
160 |Set {{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}} to the 163 | platform-specific list of implemented RTP header extensions. The 164 | {{RTCRtpHeaderExtensionCapability/direction}} attribute for all 165 | extensions that are mandatory to use MUST be initialized to an 166 | appropriate value other than {{RTCRtpTransceiverDirection/"stopped"}}. 167 | The {{RTCRtpHeaderExtensionCapability/direction}} attribute for 168 | extensions that will not be offered by default in an initial offer MUST 169 | be initialized to {{RTCRtpTransceiverDirection/"stopped"}}.
170 |The list of header extensions that MUST/SHOULD be 171 | supported is listed in [[RTCWEB-RTP]], section 5.2. The "mid" extension 172 | is mandatory to use when BUNDLE is in use, per [[BUNDLE]] section 173 | 9.1.
174 |Set {{RTCRtpTransceiver/[[NegotiatedHeaderExtensions]]}} to an empty 177 | list.
178 |184 | Make the following modifications to the 185 | set a session description 186 | algorithm: 187 |
188 |In the step for processing a description of type 191 | {{RTCSdpType/"answer"}} that runs for both local and remote 192 | descriptions, insert the following steps:
193 |For each media description and corresponding 196 | transceiver, let negotiatedExtensions be the 197 | value of 198 | transceiver.{{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}}.
199 |For each extension in 202 | negotiatedExtensions, run the following steps:
203 |Let answeredDirection be the direction attribute 206 | of the "a=extmap" line in the answer's 207 | media description that correspond to this 208 | extension if one exists, otherwise set 209 | answeredDirection to 210 | {{RTCRtpTransceiverDirection/"stopped"}}.
211 |If description is a remote description, reverse 214 | answeredDirection to represent the peer's point of 215 | view.
216 |Set 219 | extension.{{RTCRtpHeaderExtensionCapability/direction}} 220 | to answeredDirection.
221 |Set 226 | transceiver.{{RTCRtpTransceiver/[[NegotiatedHeaderExtensions]]}} 227 | to negotiatedExtensions.
228 |233 | In the algorithms for generating initial offers in [[RTCWEB-JSEP]] section 5.2.1, 234 | replace "for each supported RTP header extension, an "a=extmap" line, as specified in 235 | [[RFC5285]], section 5" " with "For each RTP header extension "e" 236 | listed in {{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}} where {{RTCRtpHeaderExtensionCapability/direction}} is not {{RTCRtpTransceiverDirection/"stopped"}}, an "a=extmap" 237 | line, as specified in [[RFC5285]], section 5, with direction taken from "e"'s {{RTCRtpHeaderExtensionCapability/direction}} 238 | attribute." 239 |
240 |241 | In the algorithm for generating subsequent offers in [[RTCWEB-JSEP]] section 5.2.2, replace "The 242 | RTP header extensions MUST only include those that are present in the most recent answer" 243 | with "For each RTP header extension listed in {{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}}, 244 | and where {{RTCRtpHeaderExtensionCapability/direction}} is not {{RTCRtpTransceiverDirection/"stopped"}}, generate 245 | an appropriate "a=extmap" line with "direction" set according to the rules of [[RFC5285]] 246 | section 6, considering the {{RTCRtpHeaderExtensionCapability/direction}} in {{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}} to indicate the 247 | answerer's desired usage". 248 |
249 |250 | In the algorithm for generating initial answers in [[RTCWEB-JSEP]] section 5.3.1, replace "For 251 | each supported RTP header extension that is present in the offer" with "For each 252 | supported RTP header extension that is present in the offer and is also present in 253 | {{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}} with a {{RTCRtpHeaderExtensionCapability/direction}} different from {{RTCRtpTransceiverDirection/"stopped"}}, 254 | set the appropriate direction based on {{RTCRtpHeaderExtensionCapability/direction}} that does not exceed the direction in the offer". 255 |
256 |257 | Since JSEP does not know about WebRTC internal slots, merging this change requires 258 | more work on a JSEP revision. 259 |
260 |Execute the following steps:
267 |Let transceiver be the {{RTCRtpTransceiver}} that 270 | this method was invoked on.
271 |Return 274 | transceiver.{{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}}.
275 |Execute the following steps:
283 |Let transceiver be the {{RTCRtpTransceiver}} that 286 | this method was invoked on.
287 |Let extensions be the first argument of this 290 | method.
291 |If the size of extensions does not match the size of 294 | transceiver.{{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}} 295 | [=exception/throw=] an {{InvalidModificationError}}. 296 |
297 |For each index i of extensions, run the 300 | following steps:
301 |Let extension be the i-th element of 304 | extensions.
305 |If 308 | extension.{{RTCRtpHeaderExtensionCapability/uri}} 309 | is not equal to the {{RTCRtpHeaderExtensionCapability/uri}} of 310 | the i-th element of 311 | transceiver.{{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}}, 312 | [=exception/throw=] an {{InvalidModificationError}}.
313 |If 316 | extension.{{RTCRtpHeaderExtensionCapability/direction}} 317 | is not {{RTCRtpTransceiverDirection/"sendrecv"}} and 318 | {{RTCRtpHeaderExtensionParameters/uri}} indicates a 319 | mandatory-to-use attribute that is required to be both sent 320 | and received, [=exception/throw=] an 321 | {{InvalidModificationError}}.
322 |If 325 | extension.{{RTCRtpHeaderExtensionCapability/direction}} 326 | is {{RTCRtpTransceiverDirection/"stopped"}} and 327 | {{RTCRtpHeaderExtensionCapability/uri}} indicates a 328 | mandatory-to-implement extension, [=exception/throw=] an 329 | {{InvalidModificationError}}.
330 |If necessary, restrict 333 | extension.{{RTCRtpHeaderExtensionCapability/direction}} 334 | as to not exceed the user agent's capabilities for this 335 | extension.
336 |Set 341 | transceiver.{{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}} 342 | to extensions.
343 |Execute the following steps:
351 |Let transceiver be the {{RTCRtpTransceiver}} that 354 | this method was invoked on.
355 |Return 358 | transceiver.{{RTCRtpTransceiver/[[NegotiatedHeaderExtensions]]}}.
359 |370 | The {{RTCRtpEncodingParameters}} dictionary is defined in 371 | [[WEBRTC]]. This document extends that dictionary with 372 | additional members to control audio packetization. 373 |
374 |partial dictionary RTCRtpEncodingParameters {
375 | RTCResolutionRestriction scaleResolutionDownTo;
376 | unsigned long ptime;
377 | boolean adaptivePtime = false;
378 | };
379 | The maximum dimensions at which to restrict this encoding.
387 |When {{scaleResolutionDownTo}} is specified, the 388 | {{RTCRtpEncodingParameters/scaleResolutionDownBy}} value MUST be 389 | ignored. Instead, frames are sent according to the specified 390 | resolution restrictions: frames MUST NOT be upscaled.
391 |When configuring parameters, the following validation MUST be 392 | performed if {{scaleResolutionDownTo}} is specified on any encoding or 393 | else {{RTCPeerConnection/addTransceiver()}} [= exception/throws =] a 394 | newly [= exception/created =] {{OperationError}} and 395 | {{RTCRtpSender/setParameters()}} [= reject|rejects =] with a newly 396 | [= exception/created =] {{InvalidModificationError}}:
397 |{{scaleResolutionDownTo}} is specified on all 400 | {{RTCRtpEncodingParameters/active}} encodings.
401 |For each {{scaleResolutionDownTo}} value, both dimensions have 404 | a value greater than 0.
405 |The preferred duration of media represented by a packet in milliseconds.
413 |415 | {{RTCRtpEncodingParameters/ptime}} was moved from [[WEBRTC]] to 416 | this specification due to lack of support from implementers. It is 417 | therefore marked as a feature at risk. 418 |
419 |false.
424 | Indicates whether this encoding MAY dynamically change
427 | the frame length. If the value is true, the
428 | user agent MAY use any valid frame length for any of its
429 | frames, and MAY change this at any time. Valid values are
430 | multiples of 10ms. If the maxptime attribute
431 | (defined in [[RFC4566]] Section 6) is specified, that maximum
432 | applies. If the value is false, the user agent
433 | MUST use a fixed frame length.
If {{adaptivePtime}} is set to true,
435 | {{ptime}} MUST NOT be set; otherwise,
436 | {{InvalidModificationError}} MUST be [=exception/throw|thrown=].
Using a longer frame length reduces the 438 | bandwidth consumption due to overhead, but does so at the cost 439 | of increased latency. Changing the frame length dynamically 440 | allows the user agent to adapt its bandwidth allocation strategy 441 | based on the current network conditions.
442 |dictionary RTCResolutionRestriction {
451 | unsigned long maxWidth;
452 | unsigned long maxHeight;
453 | };
454 | The maximum width that frames will be encoded with. The 462 | restrictions are orientation agnostic, see note below. When scaling is 463 | applied, both dimensions of the frame MUST be downscaled using the 464 | same factor.
465 |The maximum height that frames will be encoded with. The 471 | restrictions are orientation agnostic, see note below. When scaling is 472 | applied, both dimensions of the frame MUST be downscaled using the 473 | same factor.
474 |475 | The restrictions being orientation agnostic means that they will 476 | automatically be adjusted to the orientation of the frame being 477 | restricted (portrait mode or landscape mode) by swapping width and 478 | height if necessary. This means that it does not matter if 1280x720 or 479 | 720x1280 is specified, both always result in the exact same scaling 480 | factor regardless of the orientation of the frame. 481 |
482 |491 | The {{RTCRtpSender}}'s {{RTCRtpSender/setParameters()}} method is defined in 492 | [[WEBRTC]]. This document extends the optional second argument to request 493 | generation of a key frame by the encoder. 494 |
495 |partial dictionary RTCSetParameterOptions {
496 | sequence<RTCEncodingOptions> encodingOptions = [];
497 | };
498 |
499 | dictionary RTCEncodingOptions {
500 | boolean keyFrame = false;
501 | };
502 | 505 | The {{RTCSetParameterOptions}} are extended by a sequence of {{RTCEncodingOptions}}, one for each encoding. 506 |
507 |[].
510 | 513 | A sequence containing encoding options for each RTP encoding. 514 |
515 |521 | {{RTCEncodingOptions}} is the WebRTC equivalent of {{VideoEncoderEncodeOptions}} in [[WebCodecs]]. 522 |
523 |false.
526 | 529 | When set to true, request that RTCRtpSender's encoder generates a keyframe for the encoding. 530 | The semantic of this boolean is similar to the RTCP FIR message described in [RFC5104], section 3.5.1. 531 |
532 |538 | In the steps to call the {{RTCRtpSender/setParameters()}} method, 539 | let parameters be the method's first argument and let 540 | setParameterOptions be the method's second argument. 541 |
542 |Append the following steps after the steps to validate the parameters:
543 |If the [=RTCRtpTransceiver/transceiver kind=] of the associated kind is `"audio"`, set 546 | setParameterOptions.encodingOptions to the empty list.
547 |If setParameterOptions.encodingOptions is not empty and
550 | setParameterOptions.encodingOptions.length is
551 | different from parameters.encodings.length,
552 | return a promise [= rejected =] with a newly [= exception/created =] {{InvalidModificationError}}.
In the steps to configure the media stack to use parameters, append the following step:
556 |For each setParameterOptions.encodingOptions indexed by i,
559 | if setParameterOptions.encodingOptions[i].keyFrame is set to true,
560 | request that the encoder associated with parameters.encodings[i] generates a key frame.
564 | {{RTCRtpSender/setParameters()}} does not wait for a key frame to be produced by the encoder. 565 |
566 |573 | The {{RTCIceTransport}} interface is defined in [[WEBRTC]]. This document extends that interface to allow an 574 | application to observe and affect certain actions that an ICE agent [[RFC5245]] performs. 575 |
576 |577 | The [= ICE agent =] performs connectivity checks to identify valid candidate pairs on which it is possible to send 578 | and receive media and data. In order to conclude ICE processing, the [= ICE agent =] {{nominates}} a valid candidate 579 | pair as the selected candidate pair. Prior to nomination, any valid candidate pair may be used to send and receive data. 580 | Once 581 | a candidate pair is nominated successfully, only the selected candidate pair will be used to send and receive data. 582 | Changing 583 | the selected candidate pair after a successful nomination requires an ICE restart. 584 |
585 |586 | When the [= ICE agent =] has [= formed =] a candidate pair, the [= user agent =] MUST [= queue a task =] to add a candidate pair: 588 |
589 |592 | Let |connection:RTCPeerConnection| be the {{RTCPeerConnection}} object associated with this [= ICE agent =]. 593 |
594 |
597 | If connection.{{RTCPeerConnection/[[IsClosed]]}} is
598 | true, abort these steps.
599 |
603 | Let |candidatePair:RTCIceCandidatePair| be the result of [= creating an RTCIceCandidatePair =] with 604 | |local:RTCIceCandidate| and |remote:RTCIceCandidate|, representing the local and remote candidates of the [= formed =] 605 | pair respectively. 606 |
607 |610 | Let |transport:RTCIceTransport| be the {{RTCIceTransport}} object associated with |candidatePair|. 611 |
612 |615 | [=Assert=]: |transport|.{{RTCIceTransport/[[CandidatePairs]]}} does not [= list/contain =] |candidatePair|. 616 |
617 |620 | [= list/Append =] |candidatePair| to |transport|.{{RTCIceTransport/[[CandidatePairs]]}}. 621 |
622 |625 | [= Fire an event =] named 626 | {{RTCIceTransport/icecandidatepairadd}} at |transport|, using {{RTCIceCandidatePairEvent}}, 627 | with the {{RTCIceCandidatePairEvent/candidatePair}} attribute 628 | initialized to |candidatePair|. 629 |
630 |633 | When the [= ICE agent =] has picked a candidate pair to {{nominate}} as the selected candidate pair, the [= user 634 | agent =] 635 | MUST [= queue a task =] to nominate a 636 | candidate pair: 637 |
638 |641 | Let |connection:RTCPeerConnection| be the {{RTCPeerConnection}} object associated with this [= ICE agent =]. 642 |
643 |
646 | If connection.{{RTCPeerConnection/[[IsClosed]]}} is
647 | true, abort these steps.
648 |
652 | Let |transport:RTCIceTransport| be the {{RTCIceTransport}} object associated with this candidate pair. 653 |
654 |657 | Let |candidatePair:RTCIceCandidatePair| be the candidate pair which is being {{nominated}}. 658 |
659 |
662 | Set |transport|.{{RTCIceTransport/[[ProposalPending]]}} to true.
663 |
667 | Let |accepted:boolean| be the result of [= fire an event | firing an event =] named
668 | {{RTCIceTransport/icecandidatepairnominate}} at |transport|, using {{RTCIceCandidatePairEvent}}, with the
669 | {{Event/cancelable}} attribute initialized to true, and the {{RTCIceCandidatePairEvent/candidatePair}} attribute
670 | initialized to |candidatePair|.
671 |
675 | Set |transport|.{{RTCIceTransport/[[ProposalPending]]}} to false.
676 |
680 | If |accepted| is false, abort these steps and instruct the [= ICE agent =] to continue to perform connectivity checks.
681 |
685 | Otherwise, instruct the [= ICE agent =] to {{nominate}} the candidate pair indicated by |candidatePair|. 686 |
687 |690 | The [= ICE agent =] will continue to send data using |candidatePair| until instructed to use another candidate pair with {{RTCIceTransport/selectCandidatePair}}. 691 |
692 |707 | When the [= ICE agent =] has decided to remove a candidate pair, the [= user agent =] MUST [= queue a task =] to remove a candidate pair: 709 |
710 |713 | Let |connection:RTCPeerConnection| be the {{RTCPeerConnection}} object associated with this [= ICE agent =]. 714 |
715 |
718 | If connection.{{RTCPeerConnection/[[IsClosed]]}} is
719 | true, abort these steps.
720 |
724 | Let |candidatePair:RTCIceCandidatePair| be the candidate pair which is being removed. 725 |
726 |729 | Let |transport:RTCIceTransport| be the {{RTCIceTransport}} object associated with |candidatePair|. 730 |
731 |
734 | Let |cancelable:boolean| be true if the candidate pair is being removed in order to [= free =] an unused
735 | candidate, and
736 | false otherwise.
737 |
741 | Set |transport|.{{RTCIceTransport/[[ProposalPending]]}} to true.
742 |
746 | Let |accepted:boolean| be the result of [= fire an event | firing an event =] named 747 | {{RTCIceTransport/icecandidatepairremove}} at |transport|, using {{RTCIceCandidatePairEvent}}, with the 748 | {{Event/cancelable}} attribute initialized to cancelable, and the {{RTCIceCandidatePairEvent/candidatePair}} attribute 749 | initialized to |candidatePair|. 750 |
751 |
754 | Set |transport|.{{RTCIceTransport/[[ProposalPending]]}} to false.
755 |
759 | If |accepted| is false, instruct the [= ICE agent =] to not remove the candidate pair indicated by
760 | |candidatePair|, and instead continue to send and respond to ICE connectivity checks on the candidate pair as
761 | before.
762 |
766 | Otherwise (if |accepted| is true), run the following steps:
767 |
771 | [= list/Remove =] |candidatePair| from |transport|.{{RTCIceTransport/[[CandidatePairs]]}}. 772 |
773 |776 | Instruct the [= ICE agent =] to remove the candidate pair indicated by |candidatePair|. 777 |
778 |783 | The {{RTCIceTransport}} object is extended by adding the following internal slots: 784 |
785 |false.
791 |
794 | partial interface RTCIceTransport {
795 | attribute EventHandler onicecandidatepairadd;
796 | attribute EventHandler onicecandidatepairremove;
797 | attribute EventHandler onicecandidatepairnominate;
798 | Promise<undefined> selectCandidatePair(RTCIceCandidatePair candidatePair);
799 | Promise<undefined> removeCandidatePair(RTCIceCandidatePair candidatePair);
800 | };
801 | 809 | The event type of this event handler is {{icecandidatepairadd}}, and is fired as part of 810 | the [= add a candidate pair =] algorithm. 811 |
812 |818 | The event type of this event handler is {{icecandidatepairremove}}, and is fired as part of 819 | the [= remove a candidate pair =] algorithm. 820 |
821 |827 | The event type of this event handler is {{icecandidatepairnominate}}, and is fired as part 828 | of the [= nominate a candidate pair =] algorithm. 829 |
830 |841 | The {{selectCandidatePair}} method attempts to select a different candidate pair to send data 842 | over. If successful, data will be sent on the provided candidate pair. 843 | It is meant to be called after the application defers the {{nomination}} of a candidate pair 844 | by cancelling the {{RTCIceTransport/icecandidatepairnominate}} event. 845 |
846 |
847 | When this method is invoked, the [= user agent =] MUST run the following steps: 848 |
849 |852 | Let |connection:RTCPeerConnection| be the {{RTCPeerConnection}} object associated with [=this=]. 853 |
854 |
857 | If connection.{{RTCPeerConnection/[[IsClosed]]}} is
858 | true, [= exception/throw =] an {{InvalidStateError}}.
859 |
863 | If [=this=].{{RTCIceTransport/[[ProposalPending]]}} is true, [= exception/throw =] an {{InvalidStateError}}.
864 |
868 | If [=this=].{{RTCIceTransport/[[IceTransportState]]}} is either of 869 | {{RTCIceTransportState/"new"}}, {{RTCIceTransportState/"failed"}} or {{RTCIceTransportState/"closed"}}, [= 870 | exception/throw =] 871 | an {{InvalidStateError}}. 872 |
873 |876 | Let |candidatePair:RTCIceCandidatePair| be the method's first argument. 877 |
878 |881 | If [=this=].{{RTCIceTransport/[[CandidatePairs]]}} does not [= list/contain =] |candidatePair|, [= exception/throw =] a {{NotFoundError}}. 882 |
883 |886 | Let |p:Promise| be a new promise. 887 |
888 |891 | In parallel, instruct the [= ICE agent =] to use |candidatePair| to send data. 892 |
893 |896 | When the [= ICE agent =] has completed selecting |candidatePair|, [= queue a task =] to run the following steps: 897 |
898 |901 | Run the [=RTCIceTransport/change the selected candidate pair and state=] steps to update [=this=].{{RTCIceTransport/[[SelectedCandidatePair]]}} and [=this=].{{RTCIceTransport/[[IceTransportState]]}} as necessary and fire any associated events. 902 |
903 |906 | Resolve p. 907 |
908 |915 | Return p. 916 |
917 |920 | After changing the selected candidate pair, the controlling [= ICE agent =] may attempt to [= nominate the candidate 921 | pair =] as 922 | well to conclude ICE processing. The application may cancel the nomination to allow further changes to the selected 923 | candidate pair. 924 |
925 |931 | The {{removeCandidatePair}} method removes the provided candidate pair. The [= ICE agent =] will stop sending and 932 | responding to ICE connectivity checks on the removed candidate pair, and it can no longer be used to send data for this 933 | transport. This method is meant to be called when the application wants to allow the [= ICE agent =] to [= free =] 934 | candidates that it no longer needs. 935 |
936 |937 | When this method is invoked, the [= user agent =] MUST run the following steps: 938 |
939 |942 | Let |connection:RTCPeerConnection| be the {{RTCPeerConnection}} object associated with [= this =]. 943 |
944 |
947 | If connection.{{RTCPeerConnection/[[IsClosed]]}} is
948 | true, [= exception/throw =] an
949 | {{InvalidStateError}}.
950 |
954 | If [= this =].{{RTCIceTransport/[[ProposalPending]]}} is true, [= exception/throw =] an
955 | {{InvalidStateError}}.
956 |
960 | If [= this =].{{RTCIceTransport/[[IceTransportState]]}} is either of {{RTCIceTransportState/"new"}}, {{RTCIceTransportState/"failed"}} or {{RTCIceTransportState/"closed"}}, [= exception/throw =] an {{InvalidStateError}}. 961 |
962 |965 | Let |candidatePair:RTCIceCandidatePair| be the method's first argument. 966 |
967 |970 | If [=this=].{{RTCIceTransport/[[CandidatePairs]]}} does not [= list/contain =] |candidatePair|, [= exception/throw =] a {{NotFoundError}}. 971 |
972 |975 | [= list/Remove =] |candidatePair| from 976 | [=this=].{{RTCIceTransport/[[CandidatePairs]]}}. 977 |
978 |981 | Let |p:Promise| be a new promise. 982 |
983 |986 | In parallel, instruct the [= ICE agent =] to remove the candidate pair indicated by candidatePair. 987 |
988 |991 | When the [= ICE agent =] has completed the removal, [= queue a task =] to run the following steps: 992 |
993 |
996 | [= Fire an event =] named {{RTCIceTransport/icecandidatepairremove}} at |transport|, using {{RTCIceCandidatePairEvent}}, with the {{Event/cancelable}} attribute initialized to false, and the {{RTCIceCandidatePairEvent/candidatePair}} attribute initialized to |candidatePair|.
997 |
1001 | Resolve p. 1002 |
1003 |1010 | Return p. 1011 |
1012 |1022 | The {{RTCIceTransport/icecandidatepairadd}}, {{RTCIceTransport/icecandidatepairnominate}} and 1023 | {{RTCIceTransport/icecandidatepairremove}} events use the 1024 | {{RTCIceCandidatePairEvent}} interface. 1025 |
1026 |[Exposed=Window]
1028 | interface RTCIceCandidatePairEvent : Event {
1029 | constructor(DOMString type, RTCIceCandidatePairEventInit eventInitDict);
1030 | readonly attribute RTCIceCandidatePair candidatePair;
1031 | };
1032 | 1047 | The {{candidatePair}} attribute represents the candidate pair associated with the event. 1048 |
1049 |
1055 | dictionary RTCIceCandidatePairEventInit : EventInit {
1056 | required RTCIceCandidatePair candidatePair;
1057 | };
1058 | 1067 | The candidate pair announced by the event. 1068 |
1069 |1077 | In the steps to [=RTCIceTransport/change the selected candidate pair and state=], if the selected candidate pair was changed, modify the first step to the following: 1078 |
1079 |null otherwise.
1082 | 1085 | The candidate match algorithm given two {{RTCIceCandidate}} |first:RTCIceCandidate| and 1086 | |second:RTCIceCandidate| is as follows: 1087 |
1088 |
1091 | If |first|.{{RTCIceCandidate/candidate}} is not [= string/identical to =] |second|.{{RTCIceCandidate/candidate}}, return false.
1092 |
1096 | If either (but not both) of |first|.{{RTCIceCandidate/sdpMid}} and |second|.{{RTCIceCandidate/sdpMid}} is
1097 | null, return false.
1098 |
1102 | If neither of |first|.{{RTCIceCandidate/sdpMid}} and |second|.{{RTCIceCandidate/sdpMid}} is null, and |first|.{{RTCIceCandidate/sdpMid}} is not [= string/identical to =]
1103 | |second|.{{RTCIceCandidate/sdpMid}}, return false.
1104 |
1108 | If either (but not both) of |first|.{{RTCIceCandidate/sdpMLineIndex}} and |second|.{{RTCIceCandidate/sdpMLineIndex}} is
1109 | null, return false.
1110 |
1114 | If neither of |first|.{{RTCIceCandidate/sdpMLineIndex}} and |second|.{{RTCIceCandidate/sdpMLineIndex}} is null and |first|.{{RTCIceCandidate/sdpMLineIndex}} is not equal to
1115 | |second|.{{RTCIceCandidate/sdpMLineIndex}}, return false.
1116 |
1120 | If either (but not both) of |first|.{{RTCIceCandidate/usernameFragment}} and |second|.{{RTCIceCandidate/usernameFragment}} is
1121 | null, return false.
1122 |
1126 | If neither of |first|.{{RTCIceCandidate/usernameFragment}} and |second|.{{RTCIceCandidate/usernameFragment}} is null and |first|.{{RTCIceCandidate/usernameFragment}} is not [= string/identical to =]
1127 | |second|.{{RTCIceCandidate/usernameFragment}}, return false.
1128 |
1132 | Return true.
1133 |
1143 | The {{RTCRtpContributingSource}} dictionary is defined in [[WEBRTC]]. This 1144 | document extends that dictionary by adding two additional members. 1145 |
1146 |1147 | In this section, the capture system refers to the system where 1148 | media is sourced from and the sender system refers to the 1149 | system that is sending RTP and RTCP packets to the 1150 | receiver system where {{RTCRtpContributingSource}} data is 1151 | populated. 1152 |
1153 |1154 | In a direct connection, the capture system is the same as the 1155 | sender system. But when one or more RTCP-terminating intermediate 1156 | systems (e.g. mixers) are involved this is not the case. In such cases, 1157 | media is sourced from the capture system, may be relayed through a 1158 | number of intermediate systems and is then finally sent from the 1159 | sender system to the receiver system. The 1160 | sender system-receiver system path only represents the 1161 | "last hop". 1162 |
1163 |1164 | Despite {{RTCRemoteInboundRtpStreamStats.roundTripTime}} 1165 | measurements only accounting for the "last hop", one-way delay from the 1166 | [=capture system=]'s time of capture to the [=receiver system=]'s 1167 | time of playout can be estimated if the 1168 | [=Absolute Capture Timestamp RTP header extension=] is used all hops of 1169 | the way, where each RTCP-terminating intermediate system appropriately 1170 | updates the [=estimated capture clock offset=]. 1171 |
1172 |partial dictionary RTCRtpContributingSource {
1173 | DOMHighResTimeStamp captureTimestamp;
1174 | DOMHighResTimeStamp senderCaptureTimeOffset;
1175 | };
1176 | 1182 | The {{captureTimestamp}} is the timestamp that, the most recent frame 1183 | (from an RTP packet originating from this source) delivered to the 1184 | {{RTCRtpReceiver}}'s {{MediaStreamTrack}}, was originally captured. 1185 | Its reference clock is the capture system's NTP clock (same 1186 | clock used to generate NTP timestamps for RTCP sender reports on that 1187 | system). 1188 |
1189 |1190 | On populating this member, the user agent MUST run the following 1191 | steps: 1192 |
1193 |If the relevant RTP packet contains the 1196 | Absolute Capture Timestamp RTP header extension, return the 1197 | value of the absolute capture timestamp field and abort 1198 | these steps.
1199 |Otherwise, if the relevant RTP packet does not contain the 1202 | Absolute Capture Timestamp RTP header extension but a 1203 | previous RTP packet did, return the result of calculating the 1204 | absolute capture timestamp according to 1205 | timestamp interpolation and abort these steps.
1206 |undefined.
1209 | 1212 | If multiple receiving tracks are sourced from the same 1213 | capture system, two {{captureTimestamp}}s can be used to 1214 | accurately measure audio-video synchronization since both timestamps 1215 | are based on the same system's clock. 1216 |
1217 |1221 | The {{senderCaptureTimeOffset}} is the sender system's 1222 | estimate of the offset between its own NTP clock and the 1223 | capture system's NTP clock, for the same frame that the 1224 | {{captureTimestamp}} was originated from. 1225 |
1226 |1227 | On populating this member, the user agent MUST run the following 1228 | steps: 1229 |
1230 |If the relevant RTP packet contains the 1233 | Absolute Capture Timestamp RTP header extension and the 1234 | estimated capture clock offset field is present, return the 1235 | value of the estimated capture clock offset field and abort 1236 | these steps.
1237 |Otherwise, if the relevant RTP packet does not contain the 1240 | Absolute Capture Timestamp RTP header extension's 1241 | estimated capture clock offset field, but a 1242 | previous RTP packet did, return the most recent value that was 1243 | present and abort these steps.
1244 |undefined.
1247 | 1250 | The time of capture can estimatedly be expressed in the 1251 | sender system's clock as follows: 1252 | senderCaptureTimestamp = {{captureTimestamp}} + 1253 | {{senderCaptureTimeOffset}}. 1254 |
1255 |1256 | The offset between the sender system's clock and the 1257 | receiver system's clock can be estimated as follows: 1258 | senderReceiverTimeOffset = 1259 | {{RTCRemoteOutboundRtpStreamStats}}.timestamp}} - 1260 | ({{RTCRemoteOutboundRtpStreamStats.remoteTimestamp}} + 1261 | {{RTCRemoteInboundRtpStreamStats.roundTripTime}} / 2). 1262 |
1263 |1264 | The time of capture can estimatedly be expressed in the 1265 | receiver system's clock as follows: 1266 | receiverCaptureTimestamp = senderCaptureTimestamp + 1267 | senderReceiverTimeOffset. 1268 |
1269 |1270 | The one-way delay between the capture system's time of capture 1271 | and the receiver system's time of playout can be estimated as 1272 | follows: 1273 | {{RTCRtpContributingSource.timestamp}} - 1274 | receiverCaptureTimestamp. 1275 |
1276 |This section extends {{RTCDataChannel}} by exposing it to any type of {{Worker}} (not just DedicatedWorker).
The WebIDL changes are the following: 1291 |
1292 | [Exposed=(Window,Worker), Transferable]
1293 | partial interface RTCDataChannel {
1294 | };
1295 | 1305 | RTP header extension encryption policy affects whether RTP header extension 1306 | encryption is negotiated if the remote endpoint does not support [[RFC9335]]. 1307 | If the remote endpoint supports [[RFC9335]], all media streams are sent 1308 | utilizing [[RFC9335]]. 1309 |
1310 |enum RTCRtpHeaderEncryptionPolicy {
1312 | "negotiate",
1313 | "require"
1314 | };
1315 | | Enumeration description (non-normative) | 1320 ||
|---|---|
| negotiate | 1323 |
1324 | 1325 | Negotiate RTP header extension encryption as defined in [[RFC9335]]. 1326 | If encryption cannot be negotiated, RTP header extensions are sent in 1327 | the clear. 1328 | 1329 | |
1330 |
| require | 1333 |
1334 |
1335 | Require RTP header extension encryption. In [[WEBRTC]] Section 4.4.1.5, add the
1336 | following check after Step 4.4.4:
1337 | If remote is |
1343 |
1353 | {{RTCRtpTransceiver/rtpHeaderEncryptionNegotiated}} defines whether 1354 | the transceiver is sending enrypted RTP header extensions as defined in 1355 | [[RFC9335]]. 1356 |
1357 |
1358 | partial interface RTCRtpTransceiver {
1359 | readonly attribute boolean rtpHeaderEncryptionNegotiated;
1360 | };
1361 |
1373 | The {{rtpHeaderEncryptionNegotiated}} attribute indicates whether [[RFC9335]] has been
1374 | negotiated. On getting, the attribute MUST
1375 | return the value of the {{RTCRtpTransceiver/[[RtpHeaderEncryptionNegotiated]]}} slot.
1376 | In [[WEBRTC]] Section 5.4, add the following step to "create an {{RTCRtpTransceiver}}":
1377 | Let transceiver have a [[\RtpHeaderEncryptionNegotiated]]
1378 | internal slot, initialized to false.
1379 |
1389 | {{RTCConfiguration/rtpHeaderEncryptionPolicy}} defines the 1390 | policy for negotiation of RTP header encryption using 1391 | [[RFC9335]]. 1392 |
1393 |partial dictionary RTCConfiguration {
1394 | RTCRtpHeaderEncryptionPolicy rtpHeaderEncryptionPolicy = "negotiate";
1395 | };
1396 | 1408 |
1409 |1411 | {{RTCConfiguration/rtpHeaderEncryptionPolicy}} is marked 1412 | as a feature at risk, since there is no clear commitment 1413 | from implementers. 1414 |
1415 |1424 | While hardware acceleration of video encoding and decoding is generally desirable, it has proven to be 1425 | operationally challenging to achieve in the environment of a browser with no detailed information about 1426 | the underlying hardware. In some cases, falling back to software encoding yields better results. 1427 |
1428 |
1429 | The methods specified in this section should be used sparingly and not for extended amounts of time. 1430 |
1431 |1432 | In privacy-sensitive contexts, browsers may disable hardware acceleration by default to 1433 | reduce the fingerprinting surface. 1434 |
1435 |
1440 | The {{RTCRtpReceiver}} interface is defined in [[WEBRTC]]. This document extends this interface
1441 | by adding a static method and internal slot
1442 | {{RTCRtpReceiver/[[HardwareDisabled]]}} initialized to false.
1443 |
partial interface RTCRtpReceiver {
1445 | static undefined disableHardwareDecoding();
1446 | };
1447 | When the {{RTCRtpReceiver}}'s disableHardwareDecoding method is called, the user agent MUST run the following steps:
1448 |When the RTCPeerConnection.constructor() has been invoked abort these steps.
Set the RTCRtpReceiver's {{RTCRtpReceiver/[[HardwareDisabled]]}} slot to true.
1462 | The {{RTCRtpSender}} interface is defined in [[WEBRTC]]. This document extends this interface
1463 | by adding a static method and internal slot
1464 | {{RTCRtpSender/[[HardwareDisabled]]}} initialized to false.
1465 |
partial interface RTCRtpSender {
1467 | static undefined disableHardwareEncoding();
1468 | };
1469 | When the {{RTCRtpSender}}'s disableHardwareEncoding method is called, the user agent MUST run the following steps:
1470 |When the RTCPeerConnection.constructor() has been invoked abort these steps.
Set the RTCRtpSender's {{RTCRtpSender/[[HardwareDisabled]]}} slot to true.
1482 | In the set a session description algorithm, add a step
1483 | right after the step that sets transceiver.[[\Receiver]].[[\ReceiveCodecs]],
1484 | saying "If the RTCRtpReceiver's {{RTCRtpReceiver/[[HardwareDisabled]]}} slot is true,
1485 | remove any codec from transceiver.[[\Receiver]].[[\ReceiveCodecs]] for which the underlying decoder
1486 | is hardware-accelerated".
1487 |
1489 | In the set a session description algorithm, add a step
1490 | right after the step that sets transceiver.[[\Sender]].[[\SendCodecs]],
1491 | saying "If the RTCRtpSender's {{RTCRtpSender/[[HardwareDisabled]]}} slot is true,
1492 | remove any codec from transceiver.[[\Sender]].[[\SendCodecs]] for which the underlying encoder
1493 | is hardware-accelerated".
1494 |
1500 | The following events fire on {{RTCIceTransport}} objects:
1501 || Event name | 1505 |Interface | 1506 |Fired when... | 1507 |
|---|---|---|
| icecandidatepairadd | 1512 |{{RTCIceCandidatePairEvent}} | 1513 |1514 | The [= ICE agent =] has formed a candidate pair and is making it available to the script. 1515 | | 1516 |
| icecandidatepairremove | 1519 |{{RTCIceCandidatePairEvent}} | 1520 |
1521 | The [= ICE agent =] has picked a candidate pair to remove, and unless the operation is canceled by invoking the preventDefault() method on the event, it will be removed.
1522 | |
1523 |
| icecandidatepairnominate | 1526 |{{RTCIceCandidatePairEvent}} | 1527 |
1528 | The [= ICE agent =] has picked a valid candidate pair to {{nominate}}, and unless the operation is canceled by
1529 | invoking the preventDefault() method on the event, it will be {{nominated}}.
1530 | |
1531 |
1540 | For a frame produced in a {{RTCRtpReceiver}} track, it is possible for the user agent to compute a 1541 | remote capture timestamp. It is a best-effort estimate of the capture 1542 | time of the frame translated to the receiver clock, and can use methods like using RTCP SR 1543 | as specified in [[?RFC3550]] Section 6.4.1, or by other alternative means if use by RTCP SR 1544 | isn't feasible. 1545 | The capture time of an incoming frame is available if its constituent RTP packets contain the 1546 | [=Absolute Capture Timestamp RTP header extension=]. 1547 |
1548 |1549 | Each frame's [=capture timestamp=] MUST be set to the [=remote capture timestamp=], if the information 1550 | required to compute it is available. 1551 |
1552 |1554 | For a video frame produced in a {{RTCRtpReceiver}} track, the frame's [=RTP timestamp=] MUST be set 1555 | from the RTP timestamp of constituent packets of the corresponding received encoded frame. 1556 |
1557 |1559 | For a frame produced in a {{RTCRtpReceiver}} track, the [=receive timestamp=] MUST be set 1560 | as the time the corresponding encoded frame was received by the platform, i.e. the time at which the 1561 | last packet belonging to this frame was received over the network. 1562 |
1563 |1569 | This section is non-normative; it specifies no new behaviour. 1570 | The overall security considerations of the general set 1571 | of APIs and protocols used in WebRTC are described in 1572 | [[?RFC8827]]. 1573 |
1574 |1579 | The extensions defined in this document do not provide 1580 | additional impact on the local network beyond what is described in 1581 | [[WEBRTC]] Section 13.3. 1582 |
1583 |1589 | This document defines extensions for encryption of RTP Header Extensions which 1590 | improve the confidentiality of communications by encrypting header extension 1591 | IDs, as well as CSRCs. 1592 |
1593 |1600 | This section is non-normative; it specifies no new behaviour. 1601 |
1602 |1607 | The extensions defined in this document do not reveal additional 1608 | information on IP addresses beyond that already described in 1609 | [[WEBRTC]] Section 13.2. 1610 |
1611 |1617 | The extensions defined in this document do not provide additional 1618 | persistent information beyond that which is discussed in [[WEBRTC]] 1619 | Section 13.5. 1620 |
1621 |1628 | The WebRTC 1.0 specification exposes an API to control protocols 1629 | (defined within the IETF) necessary to establish real-time audio, video 1630 | and data exchange. Real-Time Text, defined in [[RFC4103]], is supported 1631 | via the data channel API as described in [[WEBRTC]] Section 14. The 1632 | extensions defined in this document do not affect support for Real-Time 1633 | Text. 1634 |
1635 |1639 | The editors wish to thank the Working Group chairs and Team Contact, 1640 | Dominique Hazaël-Massieux, for their support. Substantial text in this 1641 | specification was provided by many people including 1642 | Harald Alvestrand, Justin Uberti and Peter Thatcher. 1643 |
1644 |1645 | The {{RTCRtpSender}} and {{RTCRtpReceiver}} objects were initially 1646 | described in the W3C ORTC 1647 | CG, and have been adapted for use in this specification. 1648 |
1649 |4 | This section documents features that were moved from [[WEBRTC]] to this extension 5 | specification due to lack of support from implementers. 6 |
7 |12 | The {{RTCPeerConnection}} 13 | interface is defined in [[WEBRTC]]. This document extends that interface 14 | by adding an additional static method. 15 |
16 |partial interface RTCPeerConnection {
17 | static sequence<RTCIceServer> getDefaultIceServers();
18 | };
19 | Returns a list of ICE servers that are configured into the 26 | browser. A browser might be configured to use local or private 27 | STUN or TURN servers. This method allows an application to learn 28 | about these servers and optionally use them.
29 |This list is likely to be persistent and 30 | is the same across origins. It thus increases the 31 | fingerprinting surface of the browser. In privacy-sensitive 32 | contexts, browsers can consider mitigations such as only 33 | providing this data to whitelisted origins (or not providing it 34 | at all.)
35 |Since the use of this information is left to 36 | the discretion of application developers, configuring a user 37 | agent with these defaults does not per se increase a user's 38 | ability to limit the exposure of their IP addresses.
39 |If set, the configured default ICE servers exposed by 40 | {{RTCPeerConnection/getDefaultIceServers}} on 41 | {{RTCPeerConnection}} instances provides persistent 42 | information across time and origins which increases the fingerprinting 43 | surface of a given browser.
44 |46 | {{RTCPeerConnection/getDefaultIceServers()}} was moved from [[WEBRTC]] to 47 | this specification due to lack of support from implementers and concerns 48 | discussed in webrtc-pc#2023. 49 |
50 |The following enum values are added to the 60 | {{RTCIceCredentialType}} 61 | enum defined in [[WEBRTC]].
62 |// This is a partial enum, but this is not yet expressable in WebIDL.
65 | enum RTCIceCredentialType {
66 | "oauth"
67 | };
68 | | Enumeration description | 73 ||
|---|---|
| oauth | 76 |An OAuth 2.0 based authentication method, as described 77 | in [[RFC7635]]. 78 | 79 |For OAuth Authentication, the ICE Agent requires three
80 | pieces of credential information. The credential is composed of
81 | a
86 | This specification does not define how an application (acting
87 | as the [=OAuth Client=]) obtains the
88 |
97 | The application, acting as the OAuth Client, is responsible for
98 | refreshing the credential information and updating the ICE
99 | Agent with fresh new credentials before the
100 | The length of the HMAC key 104 | ({{RTCOAuthCredential.macKey}}) MAY be any integer 105 | number of bytes greater than 20 (160 bits). 106 |According to [[RFC7635]] Section 4.1, the 107 | HMAC key MUST be a symmetric key, as asymmetric keys would 108 | result in large access tokens which may not fit in a single 109 | STUN message. 110 |Currently the STUN/TURN protocols use only SHA-1 and SHA-2 111 | family hash algorithms for Message Integrity Protection, as 112 | defined in [[RFC5389]] Section 15.4, and [[STUN-BIS]] 113 | Section 14.6. 114 |When setting a 116 | configuration and evaluating urls, also run the following step: 117 |
129 |
135 | 130 | The {{RTCIceCredentialType/"oauth"}} value of {{RTCIceCredentialType}} 131 | was moved from [[WEBRTC]] to this specification due to lack of support 132 | from implementers. It is therefore marked as a feature at risk. 133 | 134 | |
136 |
The {{RTCOAuthCredential}} dictionary is used to describe
146 | the OAuth auth credential information which is used by the STUN/TURN
147 | client (inside the ICE Agent) to authenticate against a STUN/TURN
148 | server, as described in [[RFC7635]]. Note that the kid
149 | parameter is not located in this dictionary, but in
150 | {{RTCIceServer.username}} member.
153 | The {{RTCOAuthCredential}} dictionary was moved from [[WEBRTC]] to 154 | this specification due to lack of support from implementers. It is 155 | therefore marked as a feature at risk. 156 |
157 |dictionary RTCOAuthCredential {
161 | required DOMString macKey;
162 | required DOMString accessToken;
163 | };
164 | The "mac_key", as described in [[RFC7635]], Section 6.2, in 173 | a base64-url encoded format. It is used in STUN message 174 | integrity hash calculation (as the password is used in password 175 | based authentication). Note that the OAuth response "key" 176 | parameter is a JSON Web Key (JWK) or a JWK encrypted with a JWE 177 | format. Also note that this is the only OAuth parameter whose 178 | value is not used directly, but must be extracted from the "k" 179 | parameter value from the JWK, which contains the needed 180 | base64-encoded "mac_key".
181 |The "access_token", as described in [[RFC7635]], Section 186 | 6.2, in a base64-encoded format. This is an encrypted 187 | self-contained token that is opaque to the application. 188 | Authenticated encryption is used for message encryption and 189 | integrity protection. The access token contains a non-encrypted 190 | nonce value, which is used by the Authorization Server for unique 191 | mac_key generation. The second part of the token is protected 192 | by Authenticated Encryption. It contains the mac_key, a 193 | timestamp and a lifetime. The timestamp combined with lifetime 194 | provides expiry information; this information describes the 195 | time window during which the token credential is valid and 196 | accepted by the TURN server. 197 |
198 |An example of an RTCOAuthCredential dictionary is:
203 |
204 | {
205 | macKey: 'WmtzanB3ZW9peFhtdm42NzUzNG0=',
206 | accessToken: 'AAwg3kPHWPfvk9bDFL936wYvkoctMADzQ5VhNDgeMR3+ZlZ35byg972fW8QjpEl7bx91YLBPFsIhsxloWcXPhA=='
207 | }
208 | 214 | The {{RTCIceServer}} 215 | dictionary is defined in [[WEBRTC]]. This document extends that 216 | dictionary by adding the {{RTCIceServer/credential}} attribute, and adds a 217 | paragraph to how to interpret the existing {{RTCIceServer/username}} 218 | attribute. 219 |
220 |partial dictionary RTCIceServer {
222 | // This attribute is not new in this extension spec, but how to interpret it
223 | // in the case of credentialType being "oauth" is described here.
224 | DOMString username;
225 | (DOMString or RTCOAuthCredential) credential;
226 | };
227 | How to interpret the {{username}} when this 233 | {{RTCIceServer}} object represents a TURN server, and 234 | {{RTCIceServer/credentialType}} is {{RTCIceCredentialType/"password"}} is specified 235 | in {{RTCIceServer}} of [[WEBRTC]].
236 |If this {{RTCIceServer}} object represents a
237 | TURN server, and {{RTCIceServer/credentialType}} is
238 | {{RTCIceCredentialType/"oauth"}}, then this attribute specifies the Key ID
239 | (kid) of the shared symmetric key, which is shared
240 | between the TURN server and the Authorization Server, as described
241 | in [[RFC7635]]. It is an ephemeral and unique key identifier.
242 | The kid allows the TURN server to select the
243 | appropriate keying material for decryption of the Access-Token,
244 | so the key identified by this kid is used in the
245 | Authenticated Encryption of the "access_token". The
246 | kid value is equal with the OAuth response "kid"
247 | parameter, as defined in [[RFC7515]] Section 4.1.4.
If this {{RTCIceServer}} object represents a 254 | TURN server, then this attribute specifies the credential to 255 | use with that TURN server.
256 |If {{RTCIceServer/credentialType}} is {{RTCIceCredentialType/"password"}}, 257 | {{credential}} is a DOMString, and represents a 258 | long-term authentication password, as described in 259 | [[RFC5389]], Section 10.2.
260 |If {{RTCIceServer/credentialType}} is {{RTCIceCredentialType/"oauth"}}, 261 | {{credential}} is an {{RTCOAuthCredential}}, which 262 | contains the OAuth access token and MAC key.
263 |If this {{RTCIceServer}} object represents a
264 | TURN server, and {{RTCIceServer/credentialType}} is
265 | {{RTCIceCredentialType/"oauth"}}, then this attribute specifies the Key ID
266 | (kid) of the shared symmetric key, which is shared
267 | between the TURN server and the Authorization Server, as described
268 | in [[RFC7635]]. It is an ephemeral and unique key identifier.
269 | The kid allows the TURN server to select the
270 | appropriate keying material for decryption of the Access-Token,
271 | so the key identified by this kid is used in the
272 | Authenticated Encryption of the "access_token". The
273 | kid value is equal with the OAuth response "kid"
274 | parameter, as defined in [[RFC7515]] Section 4.1.4.
277 | The {{RTCIceServer/credential}} attribute was moved from [[WEBRTC]] to 278 | this specification due to lack of support from implementers. It is 279 | therefore marked as a feature at risk. 280 |
281 |An example array of {{RTCIceServer}} objects is:
285 |
286 | {
287 | urls: 'turns:turn2.example.net',
288 | username: '22BIjxU93h/IgwEb',
289 | credential: {
290 | macKey: 'WmtzanB3ZW9peFhtdm42NzUzNG0=',
291 | accessToken: 'AAwg3kPHWPfvk9bDFL936wYvkoctMADzQ5VhNDgeMR3+ZlZ35byg972fW8QjpEl7bx91YLBPFsIhsxloWcXPhA=='
292 | },
293 | credentialType: 'oauth'
294 | }
295 | This document extends {{RTCRtpSynchronizationSource}} with a {{RTCRtpSynchronizationSource/voiceActivityFlag}} member (initially defined in the WebRTC 1.0 specification but later dropped due to lack of implementation).
301 |
302 | partial dictionary RTCRtpSynchronizationSource {
303 | boolean voiceActivityFlag;
304 | };
305 | 313 | Only present for audio receivers. Whether the last RTP 314 | packet, delivered from this source, contains voice activity 315 | (true) or not (false). If the RFC 6464 extension header was 316 | not present, or if the peer has signaled that it is not using 317 | the V bit by setting the "vad" extension attribute to "off", 318 | as described in [[!RFC6464]], Section 4, 319 | {{voiceActivityFlag}} will be absent. 320 |
321 |323 | {{RTCRtpSynchronizationSource/voiceActivityFlag}} was moved from [[WEBRTC]] to 324 | this specification due to lack of support from implementers. It is therefore 325 | marked as a feature at risk. 326 |
327 |