This document describes how Dual-Tone Multifrequency events can be sent and received over media streams. This allows browser-based realtime applications to interact with antiquated systems that convey information over audio channels using tones.

Introduction

Dual-Tone Multifrequency (DTMF) events are in widespread use on the Public Switched Telephone Network (PSTN) where they are used to convey user input to signaling and Interactive Voice Response (IVR) systems. Given that old-fashioned telephones typically only have a small number of inputs, this archaic system continues to be used.

In the interests of interoperation with legacy systems, this API describes how an audio track [[!GETUSERMEDIA]] can be decorated with DTMF capabilities.

In order to generate DTMF on an associated audio stream, the stream is decorated as follows. In this example, key press events are used to generate tones.

var dtmfstream;
navigator.getUserMedia({ audio: true }, function(localMediaStream) {
    var audioTrack = localMediaStream.audioTracks[0];
    dtmfStream = new DtmfAudioStreamTrack(audioStreamTrack);
    window.addEventListener('keydown', function(keyDownEvent) {
        dtmfStream.startTone(keyDownEvent.char);
    });
    window.addEventListener('keyup', function(keyDownEvent) {
        dtmfStream.endTone();
    });
});
      

A receiver might wish to display the received tones to a user. In extreme circumstances, they might want to play audio representations of the tones.

var dtmfStream = realtimeMediaStream.track;
dtmfStream.addEventListener('tone', function(dtmfEvent) {
    if (dtmfEvent.state === 'start') {
        dtmfTones[dtmfEvent.tone].enable();
        keyLog += dtmfEvent.tone;
    } else if (dtmfEvent.state === 'end') {
        dtmfTones[dtmfEvent.tone].disable();
    }
});
      

The DtmfAudioStreamTrack Object

The DtmfAudioStreamTrack interface extends MediaStreamTrack to add DTMF-specific attributes and methods.

A DtmfAudioStreamTrack wraps an audio track, passing all MediaStreamTrack methods and parameters straight to the wrapped instance. It cannot be instantiated without a corresponding audio track.

There is no sense in wrapping a DtmfAudioStreamTrack in another instance of a DtmfAudioStreamTrack, an exception is thrown if the constructor is passed an instance of DtmfAudioStreamTrack.

void playTones (DOMString tones, optional unsigned long duration = 100)

Insert a DTMF tone into the stream. The tones parameter includes a string of tones, each tone being represented by a single character. Valid tone characters are: '0' through '9', '*', '#', 'A' through 'D'. Lowercase 'a' through 'd' are converted to uppercase. The ',' can be used to insert a "silent" tone into the sequence. Any other characters are ignored.

The duration parameter specifies the time in milliseconds that each tone is active. This value is clamped to a range between 50ms and 6000ms.

This method causes the browser to generate startTone() and endTone() calls at the appropriate points in time. Calling insertTones() implicitly results in a call to endTone() prior to starting the sequence.

void startTone (DOMString tone)

Used for the manual control of DTMF sending by starting a DTMF tone. The first character of the tone parameter MUST include a single DTMF tone character, including other characters has no effect.

It is not possible to start a tone if another tone is in progress. Calling startTone() implicitly results in a call to endTone() prior to starting the tone.

It is possible to use this method to produce tones that are undetectable by some systems. Applications that wish to have detectable tones should ensure that each tone is active for at least 50ms with a gap of at least 50ms between tones to allow receivers to detect the transition between tones.

void endTone ()

Ends any started DTMF tone or any sequence of tones.

attribute DtmfCallback? ontone

An event handler for tone events. As tones start and end, events are passed to this target. This includes events as they are inserted.

callback DtmfCallback = void (DtmfEvent event);
          

enum DtmfState {
    "start", "continuation", "end"
};