RTCDtmfSender object

[Some information relates to pre-released product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.]

Allows sending DTMF tones to/from the remote peer, as per [RFC4733].

Operation

An RTCDtmfSender object is constructed from an RTCRtpSender object.

Syntax

[Constructor(RTCRtpSender sender)]
interface RTCDtmfSender {
    readonly    attribute boolean      canInsertDTMF;
    void insertDTMF (DOMString tones, optional long duration, optional long interToneGap);
    readonly    attribute RTCRtpSender sender;
                attribute EventHandler ontonechange;
    readonly    attribute DOMString    toneBuffer;
    readonly    attribute long         duration;
    readonly    attribute long         interToneGap;
};

Members

The RTCDtmfSender object has these types of members:

• Events
• Methods
• Properties

Events

The RTCDtmfSender object has these events.

Event	Description
RTCDTMFToneChangeEvent	Firing an tonechange event uses the RTCDTMFToneChangeEvent interface to create and dispatch DTMF tones to the given target.

 

Methods

The RTCDtmfSender object has these methods.

Method	Description
insertDTMF	Used to send DTMF tones.

 

Properties

The RTCDtmfSender object has these properties.

Property	Access type	Description
canInsertDTMF	Read-only	Whether the RTCDtmfSender is capable of sending DTMF.
duration		Returns the current tone duration value in milliseconds.
interToneGap		Returns the current value of the between-tone gap.
ontonechange		Event handler using the RTCDTMFToneChangeEvent interface to return the character for each tone as it is played out.
sender		The RTCRtpSender instance.
toneBuffer		Returns a list of the tones remaining to be played out.

 

Standards information

• Object RTC (ORTC) API for WebRTC

DTMF Examples

Examples assume that sendObject is an RTCRtpSender object.

Sending the DTMF signal "1234" with 500 ms duration per tone:

var sender = new RTCDtmfSender(sendObject);
if (sender.canInsertDTMF) {
    var duration = 500;
    sender.insertDTMF("1234", duration);
} else {
    trace("DTMF function not available");
}     

Send the DTMF signal "1234", and light up the active key using lightKey(key) while the tone is playing (assuming that lightKey("") will darken all the keys):

var sender = new RTCDtmfSender(sendObject);
sender.ontonechange = function (e) {
    if (!e.tone)
        return;
    // light up the key when playout starts
    lightKey(e.tone);
    // turn off the light after tone duration
    setTimeout(lightKey, sender.duration, "");
};
sender.insertDTMF("1234");

Send a 1-second "1" tone followed by a 2-second "2" tone:

var sender = new RTCDtmfSender(sendObject);
sender.ontonechange = function (e) {
    if (e.tone == "1")
        sender.insertDTMF("2", 2000);
};
sender.insertDTMF("1", 1000);

It is always safe to append to the tone buffer. This example appends before any tone playout has started as well as during playout.

var sender = new RTCDtmfSender(sendObject);
sender.insertDTMF("123");
// append more tones to the tone buffer before playout has begun
sender.insertDTMF(sender.toneBuffer + "456");

sender.ontonechange = function (e) {
    if (e.tone == "1")
        // append more tones when playout has begun
        sender.insertDTMF(sender.toneBuffer + "789");
};

Send the DTMF signal "123" and abort after sending "2".

var sender = new RTCDtmfSender(sendObject);
sender.ontonechange = function (e) {
    if (e.tone == "2")
        // empty the buffer to not play any tone after "2"
        sender.insertDTMF("");
};
sender.insertDTMF("123");

See also

RTCRtpSender