7.2 RTCDTMFSender

To create an RTCDTMFSender, the user agent MUST run the following steps:

  1. Let dtmf be a newly created RTCDTMFSender object.

  2. Let dtmf have a [[Duration]] internal slot.

  3. Let dtmf have a [[InterToneGap]] internal slot.

  4. Let dtmf have a [[ToneBuffer]] internal slot.

  1. WebIDL[Exposed=Window]
  2. interface RTCDTMFSender : EventTarget {
  3.   undefined insertDTMF(DOMString tones, optional unsigned long duration = 100, optional unsigned long interToneGap = 70);
  4.   attribute EventHandler ontonechange;
  5.   readonly attribute boolean canInsertDTMF;
  6.   readonly attribute DOMString toneBuffer;
  7. };

Attributes

ontonechange of type EventHandler

The event type of this event handler is tonechange.

canInsertDTMF of type boolean, readonly

Whether the RTCDTMFSender dtmfSender is capable of sending DTMF. On getting, the user agent MUST return the result of running determine if DTMF can be sent for dtmfSender.

toneBuffer of type DOMString, readonly

The toneBuffer attribute MUST return a list of the tones remaining to be played out. For the syntax, content, and interpretation of this list, see insertDTMF.

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 MUST be normalized to uppercase on entry and are equivalent to A to D. As noted in [RTCWEB-AUDIO] Section 3, support for the characters 0 through 9, A through D, #, and * are required. The character ‘,’ MUST be supported, and indicates a delay of 2 seconds before processing the next character in the tones parameter. All other characters (and only those 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 in ms. The user agent clamps it to at least 30 ms and at most 6000 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() method is invoked, the user agent MUST run the following steps:

  1. Let sender be the RTCRtpSender used to send DTMF.

  2. Let transceiver be the RTCRtpTransceiver object associated with sender.

  3. Let dtmf be the RTCDTMFSender associated with sender.

  4. If determine if DTMF can be sent for dtmf returns false, throw an InvalidStateError.
  5. Let tones be the method’s first argument.
  6. Let duration be the method’s second argument.
  7. Let interToneGap be the method’s third argument.
  8. If tones contains any unrecognized characters, throw an InvalidCharacterError.
  9. Set the object’s [[ToneBuffer]] slot to tones.
  10. Set dtmf.[[Duration]] to the value of duration.
  11. Set dtmf.[[InterToneGap]] to the value of interToneGap.
  12. If the value of duration is less than 40 ms, set dtmf.[[Duration]] to 40 ms.
  13. If the value of duration parameter is greater than 6000 ms, set dtmf.[[Duration]] to 6000 ms.
  14. If the value of interToneGap is less than 30 ms, set dtmf.[[InterToneGap]] to 30 ms.
  15. If the value of interToneGap is greater than 6000 ms, set dtmf.[[InterToneGap]] to 6000 ms.
  16. If [[ToneBuffer]] slot is an empty string, abort these steps.
  17. If a Playout task is scheduled to be run, abort these steps; otherwise queue a task that runs the following steps (Playout task):
    1. If transceiver.[[CurrentDirection]] is neither “sendrecv“ nor “sendonly“, abort these steps.
    2. If the [[ToneBuffer]] slot contains the empty string, fire an event named tonechange using the RTCDTMFToneChangeEvent interface with the tone attribute set to an empty string at the RTCDTMFSender object and abort these steps.
    3. Remove the first character from the [[ToneBuffer]] slot and let that character be tone.
    4. If tone is "," delay sending tones for 2000 ms on the associated RTP media stream, and queue a task to be executed in 2000 ms from now that runs the steps labelled Playout task.
    5. If tone is not "," start playout of tone for [[Duration]] ms on the associated RTP media stream, using the appropriate codec, then queue a task to be executed in [[Duration]] + [[InterToneGap]] ms from now that runs the steps labelled Playout task.
    6. Fire an event named tonechange using the RTCDTMFToneChangeEvent interface with the tone attribute set to tone at the RTCDTMFSender object.

Since insertDTMF replaces the tone buffer, in order to add to the DTMF tones being played, it is necessary to call insertDTMF with a string containing both the remaining tones (stored in the [[ToneBuffer]] slot) and the new tones appended together. Calling insertDTMF with an empty tones parameter can be used to cancel all tones queued to play after the currently playing tone.