Issue 215: RTCDtmfSender Sync

The latest WebRTC 1.0 API specification (see http://w3c.github.io/webrtc-pc/archives/20150611/webrtc.html#rtcdtmfsender) provides a revised Peer-to-peer DTMF API in Section 7 which extends the RTCRtpSender interface. This issue was filed to track differences between the WebRTC 1.0 RTCDTMFSender and the ORTC API RTCDtmfSender (yes, there is a difference in capitalization).  In addition to spelling, another minor difference is the default duration (100 ms in WebRTC 1.0, 70 ms in ORTC API)<https://github.com/aboba>.


Looking over the text, the major difference between WebRTC 1.0 and ORTC API is that WebRTC 1.0 contains the following text describing insertDTMF in Section 7.2.2:

"7.2.2 Methods

insertDTMF
An RTCDTMFSender object's insertDTMF() method is used to send DTMF tones.

The tones parameter is treated as a series of characters. The characters 0 through 9, A through D, #, and * generate the associated DTMF tones. The characters a to d are equivalent to A to D. The character ',' indicates a delay of 2 seconds before processing the next character in the tones parameter. All other characters must be considered unrecognized.

The duration parameter indicates the duration in ms to use for each character passed in the tones parameters. The duration cannot be more than 6000 ms or less than 40 ms. The default duration is 100 ms for each tone.

The interToneGap parameter indicates the gap between tones. It must be at least 30 ms. The default value is 70 ms.

The browser may increase the duration and interToneGap times to cause the times that DTMF start and stop to align with the boundaries of RTP packets but it must not increase either of them by more than the duration of a single RTP audio packet.

ISSUE
How are invalid values handled?

When the insertDTMF() method is invoked, the user agent must run the following steps:

Set the object's toneBuffer attribute to the value of the first argument, the duration attribute to the value of the second argument, and the interToneGap attribute to the value of the third argument.
If toneBuffer contains any unrecognized characters, throw an InvalidCharacterError exception and abort these steps.
If toneBuffer is an empty string, return.
If the value of the duration attribute is less than 40, set it to 40. If, on the other hand, the value is greater than 6000, set it to 6000.
If the value of the interToneGap attribute is less than 30, set it to 30.
If a Playout task is scheduled to be run; abort these steps; otherwise queue a task that runs the following steps (Playout task):
If toneBuffer is an empty string, fire an event named tonechange with an empty string at the RTCDTMFSender object and abort these steps.
Remove the first character from toneBuffer and let that character be tone.
Start playout of tone for duration ms on the associated RTP media stream, using the appropriate codec.
Queue a task to be executed in duration + interToneGap ms from now that runs the steps labelled Playout task.
Fire an event named tonechange with a string consisting of tone at the RTCDTMFSender object.


Proposal is to not change the spelling for now (since the WebRTC object spelling is inconsistent), but to change the default duration and sync up on text as follows:


Section 10.3.2 Methods



insertDTMF

The insertDTMF() method is used to send DTMF tones. Since DTMF tones cannot be sent without configuring the DTMF codec, if insertDTMF() is called prior to sender.send(parameters), or if sender.send(parameters) was called but parameters did not include the DTMF codec, throw an InvalidStateError exception.

The tones parameter is treated as a series of characters. The characters 0 through 9, A through D, #, and * generate the associated DTMF tones. The characters a to d are equivalent to A to D. The character ',' indicates a delay of 2 seconds before processing the next character in the tones parameter. All other characters must be considered unrecognized.

The duration parameter indicates the duration in ms to use for each character passed in the tones parameters. The duration cannot be more than 6000 ms or less than 40 ms. The default duration is 100 ms for each tone.

The interToneGap parameter indicates the gap between tones. It must be at least 30 ms. The default value is 70 ms.

The browser may increase the duration and interToneGap times to cause the times that DTMF start and stop to align with the boundaries of RTP packets but it must not increase either of them by more than the duration of a single RTP audio packet.

When the insertDTMF()<http://ortc.org/wp-content/uploads/2015/06/ortc.html#dom-RTCDTMFSender-insertDTMF> method is invoked, the user agent must run the following steps:

  1.  Set the object's toneBuffer<http://ortc.org/wp-content/uploads/2015/06/ortc.html#dom-RTCDTMFSender-tonebuffer> attribute to the value of the first argument, the duration<http://ortc.org/wp-content/uploads/2015/06/ortc.html#dom-RTCDTMFSender-duration>attribute to the value of the second argument, and the interToneGap<http://ortc.org/wp-content/uploads/2015/06/ortc.html#dom-RTCDTMFSender-intertonegap> attribute to the value of the third argument.
  2.  If toneBuffer<http://ortc.org/wp-content/uploads/2015/06/ortc.html#dom-RTCDTMFSender-tonebuffer> contains any unrecognized<http://ortc.org/wp-content/uploads/2015/06/ortc.html#dtmf-unrecognized> characters, throw an InvalidCharacterErrorexception and abort these steps.
  3.  If toneBuffer<http://ortc.org/wp-content/uploads/2015/06/ortc.html#dom-RTCDTMFSender-tonebuffer> is an empty string, return.
  4.  If the value of the duration<http://ortc.org/wp-content/uploads/2015/06/ortc.html#dom-RTCDTMFSender-duration> attribute is less than 40, set it to 40. If, on the other hand, the value is greater than 6000, set it to 6000.
  5.  If the value of the interToneGap<http://ortc.org/wp-content/uploads/2015/06/ortc.html#dom-RTCDTMFSender-intertonegap> attribute is less than 30, set it to 30.
  6.  If a Playout task is scheduled to be run; abort these steps; otherwise queue a task that runs the following steps (Playout task):
     *   If toneBuffer<http://ortc.org/wp-content/uploads/2015/06/ortc.html#dom-RTCDTMFSender-tonebuffer> is an empty string, fire an event named tonechange<http://ortc.org/wp-content/uploads/2015/06/ortc.html#event-RTCDTMFSender-tonechange> with an empty string at the RTCDtmfSender<http://ortc.org/wp-content/uploads/2015/06/ortc.html#idl-def-RTCDTMFSender> object and abort these steps.
     *   Remove the first character from toneBuffer<http://ortc.org/wp-content/uploads/2015/06/ortc.html#dom-RTCDTMFSender-tonebuffer> and let that character be tone.
     *   Start playout of tone for duration<http://ortc.org/wp-content/uploads/2015/06/ortc.html#dom-RTCDTMFSender-duration> ms on the associated RTP media stream, using the appropriate codec.
     *   Queue a task to be executed in duration<http://ortc.org/wp-content/uploads/2015/06/ortc.html#dom-RTCDTMFSender-duration> + interToneGap<http://ortc.org/wp-content/uploads/2015/06/ortc.html#dom-RTCDTMFSender-intertonegap> ms from now that runs the steps labelled Playout task.
     *   Fire an event named tonechange<http://ortc.org/wp-content/uploads/2015/06/ortc.html#event-RTCDTMFSender-tonechange> with a string consisting of tone at theRTCDtmfSender<http://ortc.org/wp-content/uploads/2015/06/ortc.html#idl-def-RTCDTMFSender> object.

Calling insertDTMF()<http://ortc.org/wp-content/uploads/2015/06/ortc.html#dom-RTCDTMFSender-insertDTMF> with an empty tones parameter can be used to cancel all tones queued to play after the currently playing tone.

Parameter       Type    Nullable        Optional        Description
tones   DOMString       ✘       ✘
duration        long    ✘       ✔
interToneGap    long    ✘       ✔
Return type: void
[@aboba]<https://github.com/aboba>