A givenRTCPeerConnection can have multiple media tracks sent or received on it. When you wish to transmit DTMF signals, you first need to decide which track to send them on, since DTMF is sent as a series of out-of-band payloads on theRTCRtpSender responsible for transmitting that track's data to the other peer.

Once the track is selected, you can obtain from itsRTCRtpSender theRTCDTMFSender object you'll use for sending DTMF. From there, you can callRTCDTMFSender.insertDTMF() to enqueue DTMF signals to be sent on the track to the other peer. TheRTCRtpSender will then send the tones to the other peer as packets alongside the track's audio data.

Each time a tone is sent, theRTCPeerConnection receives atonechange event with atone property specifying which tone finished playing, which is an opportunity to update interface elements, for example. When the tone buffer is empty, indicating that all the tones have been sent, atonechange event with itstone property set to "" (an empty string) is delivered to the connection object.

If you'd like to know more about how this works, readRFC 3550: RTP: A Transport Protocol for Real-Time Applications andRFC 4733: RTP Payload for DTMF Digits, Telephony Tones, and Telephony Signals. The details of how DTMF payloads are handled on RTP are beyond the scope of this article. Instead, we'll focus on how to use DTMF within the context of anRTCPeerConnection by studying how an example works.

This simple example constructs twoRTCPeerConnections, establishes a connection between them, then waits for the user to click a "Dial" button. When the button is clicked, a DTMF string is sent over the connection usingRTCDTMFSender.insertDTMF(). Once the tones finish transmitting, the connection is closed.

The HTML for this example is very basic; there are only three elements of importance:

• An<audio> element to play the audio received by theRTCPeerConnection being "called."
• A<button> element to trigger creating and connecting the twoRTCPeerConnection objects, then sending the DTMF tones.
• A<div> to receive and display log text to show status information.

<p>  This example demonstrates the use of DTMF in WebRTC. Note that this example is  "cheating" by generating both peers in one code stream, rather than having  each be a truly separate entity.</p><audio autoplay controls></audio><br /><button name="dial">Dial</button><div></div>

Let's take a look at the JavaScript code next. Keep in mind that the process of establishing the connection is somewhat contrived here; you normally don't build both ends of the connection in the same document.

Global variables

First, we establish global variables.

let dialString = "12024561111";let callerPC = null;let receiverPC = null;let dtmfSender = null;let hasAddTrack = false;let mediaConstraints = {  audio: true,  video: false,};let dialButton = null;let logElement = null;

These are, in order:

dialString

The DTMF string the caller will send when the "Dial" button is clicked.

callerPC andreceiverPC

TheRTCPeerConnection objects representing the caller and the receiver, respectively. These will be initialized when the call starts up, in ourconnectAndDial() function, as shown inStarting the connection process below.

dtmfSender

TheRTCDTMFSender object for the connection. This will be obtained while setting up the connection, in thegotStream() function shown inAdding the audio to the connection.

hasAddTrack

Because some browsers have not yet implementedRTCPeerConnection.addTrack(), therefore requiring the use of the obsoleteaddStream() method, we use this Boolean to determine whether or not the user agent supportsaddTrack(); if it doesn't, we'll fall back toaddStream(). This gets figured out inconnectAndDial(), as shown inStarting the connection process.

mediaConstraints

An object specifying the constraints to use when starting the connection. We want an audio-only connection, sovideo isfalse, whileaudio istrue.

dialButton andlogElement

These variables will be used to store references to the dial button and the<div> into which logging information will be written. They'll get set up when the page is first loaded. SeeInitialization below.

Initialization

When the page loads, we do some basic setup: we fetch references to the dial button and the log output box elements, and we useaddEventListener() to add an event listener to the dial button so that clicking it calls theconnectAndDial() function to begin the connection process.

window.addEventListener("load", () => {  logElement = document.querySelector(".log");  dialButton = document.querySelector("#dial");  dialButton.addEventListener("click", connectAndDial, false);});

Starting the connection process

When the dial button is clicked,connectAndDial() is called. This starts building the WebRTC connection in preparation for sending the DTMF codes.

function connectAndDial() {  callerPC = new RTCPeerConnection();  hasAddTrack = callerPC.addTrack !== undefined;  callerPC.onicecandidate = handleCallerIceEvent;  callerPC.onnegotiationneeded = handleCallerNegotiationNeeded;  callerPC.oniceconnectionstatechange = handleCallerIceConnectionStateChange;  callerPC.onsignalingstatechange = handleCallerSignalingStateChangeEvent;  callerPC.onicegatheringstatechange = handleCallerGatheringStateChangeEvent;  receiverPC = new RTCPeerConnection();  receiverPC.onicecandidate = handleReceiverIceEvent;  if (hasAddTrack) {    receiverPC.ontrack = handleReceiverTrackEvent;  } else {    receiverPC.onaddstream = handleReceiverAddStreamEvent;  }  navigator.mediaDevices    .getUserMedia(mediaConstraints)    .then(gotStream)    .catch((err) => log(err.message));}

After creating theRTCPeerConnection for the caller (callerPC), we look to see if it has anaddTrack() method. If it does, we sethasAddTrack totrue; otherwise, we set it tofalse. This variable will let the example operate even on browsers not yet implementing the neweraddTrack() method; we'll do so by falling back to the olderaddStream() method.

Next, the event handlers for the caller are established. We'll cover these in detail later.

Then a secondRTCPeerConnection, this one representing the receiving end of the call, is created and stored inreceiverPC; itsonicecandidate event handler is set up too.

IfaddTrack() is supported, we set up the receiver'sontrack event handler; otherwise, we set uponaddstream. Thetrack andaddstream events are sent when media is added to the connection.

Finally, we callgetUserMedia() to obtain access to the caller's microphone. If successful, the functiongotStream() is called, otherwise we log the error because calling has failed.

Adding the audio to the connection

As mentioned above, when the audio input from the microphone is obtained,gotStream() is called. Its job is to build the stream being sent to the receiver, so the actual process of starting to transmit can begin. It also gets access to theRTCDTMFSender we'll use to issue DTMF on the connection.

function gotStream(stream) {  log("Got access to the microphone.");  let audioTracks = stream.getAudioTracks();  if (hasAddTrack) {    if (audioTracks.length > 0) {      audioTracks.forEach((track) => callerPC.addTrack(track, stream));    }  } else {    log(      "Your browser doesn't support RTCPeerConnection.addTrack(). Falling " +        "back to the <strong>deprecated</strong> addStream() method…",    );    callerPC.addStream(stream);  }  if (callerPC.getSenders) {    dtmfSender = callerPC.getSenders()[0].dtmf;  } else {    log(      "Your browser doesn't support RTCPeerConnection.getSenders(), so " +        "falling back to use <strong>deprecated</strong> createDTMFSender() " +        "instead.",    );    dtmfSender = callerPC.createDTMFSender(audioTracks[0]);  }  dtmfSender.ontonechange = handleToneChangeEvent;}

After settingaudioTracks to be a list of the audio tracks on the stream from the user's microphone, it's time to add the media to the caller'sRTCPeerConnection. IfaddTrack() is available on theRTCPeerConnection, we add each of the stream's audio tracks, one by one, to the connection usingRTCPeerConnection.addTrack(). Otherwise we callRTCPeerConnection.addStream() to add the stream to the call as a single unit.

Next we look to see if theRTCPeerConnection.getSenders() method is implemented. If it is, we call it oncallerPC and get the first entry in the returned list of senders; this is theRTCRtpSender responsible for transmitting data for the first audio track on the call (which is the track we'll send DTMF over). We then obtain theRTCRtpSender'sdtmf property, which is anRTCDTMFSender object that can send DTMF on the connection, from the caller to the receiver.

IfgetSenders() isn't available, we instead callRTCPeerConnection.createDTMFSender() to get theRTCDTMFSender object. Although this method is obsolete, this example supports it as a fallback to let older browsers (and those not yet updated to support the current WebRTC DTMF API) run the example.

Finally, we set the DTMF sender'sontonechange event handler so we get notified each time a DTMF tone finishes playing.

You can find the log function at the bottom of the documentation.

When a tone finishes playing

Each time a DTMF tone finishes playing, atonechange event is delivered tocallerPC. The event listener for these is implemented as thehandleToneChangeEvent() function.

function handleToneChangeEvent(event) {  if (event.tone !== "") {    log(`Tone played: ${event.tone}`);  } else {    log("All tones have played. Disconnecting.");    callerPC.getLocalStreams().forEach((stream) => {      stream.getTracks().forEach((track) => {        track.stop();      });    });    receiverPC.getLocalStreams().forEach((stream) => {      stream.getTracks().forEach((track) => {        track.stop();      });    });    audio.pause();    audio.srcObject = null;    receiverPC.close();    callerPC.close();  }}

Thetonechange event is used both to indicate when an individual tone has played and when all tones have finished playing. The event'stone property is a string indicating which tone just finished playing. If all tones have finished playing,tone is an empty string; when that's the case,RTCDTMFSender.toneBuffer is empty.

In this example, we log to the screen which tone just finished playing. In a more advanced application, you might update the user interface, for example, to indicate which note is currently playing.

On the other hand, if the tone buffer is empty, our example is designed to disconnect the call. This is done by stopping each stream on both the caller and the receiver by iterating over eachRTCPeerConnection's track list (as returned by itsgetTracks() method) and calling each track'sstop() method.

Once both the caller's and the receiver's media tracks are all stopped, we pause the<audio> element and set itssrcObject tonull. This detaches the audio stream from the<audio> element.

Then, finally, eachRTCPeerConnection is closed by calling itsclose() method.

Adding candidates to the caller

When the caller'sRTCPeerConnection ICE layer comes up with a new candidate to propose, it issues anicecandidate event tocallerPC. Theicecandidate event handler's job is to transmit the candidate to the receiver. In our example, we are directly controlling both the caller and the receiver, so we can just directly add the candidate to the receiver by calling itsaddIceCandidate() method. That's handled byhandleCallerIceEvent():

function handleCallerIceEvent(event) {  if (event.candidate) {    log(`Adding candidate to receiver: ${event.candidate.candidate}`);    receiverPC      .addIceCandidate(new RTCIceCandidate(event.candidate))      .catch((err) => log(`Error adding candidate to receiver: ${err}`));  } else {    log("Caller is out of candidates.");  }}

If theicecandidate event has a non-nullcandidate property, we create a newRTCIceCandidate object from theevent.candidate string and "transmit" it to the receiver by callingreceiverPC.addIceCandidate(), providing the newRTCIceCandidate as its input. IfaddIceCandidate() fails, thecatch() clause outputs the error to our log box.

Ifevent.candidate isnull, that indicates that there are no more candidates available, and we log that information.

Dialing once the connection is open

Our design requires that when the connection is established, we immediately send the DTMF string. To accomplish that, we watch for the caller to receive aniceconnectionstatechange event. This event is sent when one of a number of changes occurs to the state of the ICE connection process, including the successful establishment of a connection.

function handleCallerIceConnectionStateChange() {  log(`Caller's connection state changed to ${callerPC.iceConnectionState}`);  if (callerPC.iceConnectionState === "connected") {    log(`Sending DTMF: "${dialString}"`);    dtmfSender.insertDTMF(dialString, 400, 50);  }}

Theiceconnectionstatechange event doesn't actually include within it the new state, so we get the connection process's current state fromcallerPC'sRTCPeerConnection.iceConnectionState property. After logging the new state, we look to see if the state is"connected". If so, we log the fact that we're about to send the DTMF, then we calldtmf.insertDTMF() to send the DTMF on the same track as the audio data method on theRTCDTMFSender object wepreviously stored indtmfSender.

Our call toinsertDTMF() specifies not only the DTMF to send (dialString), but also the length of each tone in milliseconds (400 ms) and the amount of time between tones (50 ms).

Negotiating the connection

When the callingRTCPeerConnection begins to receive media (after the microphone's stream is added to it), anegotiationneeded event is delivered to the caller, letting it know that it's time to start negotiating the connection with the receiver. As previously mentioned, our example is simplified somewhat because we control both the caller and the receiver, sohandleCallerNegotiationNeeded() is able to quickly construct the connection by calling methods for both the caller and receiver, as shown below.

// Offer to receive audio but not videoconst constraints = { audio: true, video: false };async function handleCallerNegotiationNeeded() {  log("Negotiating…");  try {    const stream = await navigator.mediaDevices.getUserMedia(constraints);    for (const track of stream.getTracks()) {      pc.addTrack(track, stream);    }    const offer = await callerPC.createOffer();    log(`Setting caller's local description: ${offer.sdp}`);    await callerPC.setLocalDescription(offer);    log("Setting receiver's remote description to the same as caller's local");    await receiverPC.setRemoteDescription(callerPC.localDescription);    log("Creating answer");    const answer = await receiverPC.createAnswer();    log(`Setting receiver's local description to ${answer.sdp}`);    await receiverPC.setLocalDescription(answer);    log("Setting caller's remote description to match");    await callerPC.setRemoteDescription(receiverPC.localDescription);  } catch (err) {    log(`Error during negotiation: ${err.message}`);  }}

Since the various methods involved in negotiating the connection returnpromises, we can chain them together like this:

1. CallcallerPC.createOffer() to get an offer.
2. Then take that offer and set the caller's local description to match by callingcallerPC.setLocalDescription().
3. Then "transmit" the offer to the receiver by callingreceiverPC.setRemoteDescription(). This configures the receiver so that it knows how the caller is configured.
4. Then the receiver creates an answer by callingreceiverPC.createAnswer().
5. Then the receiver sets its local description to match the newly-created answer by callingreceiverPC.setLocalDescription().
6. Then the answer is "transmitted" to the caller by callingcallerPC.setRemoteDescription(). This lets the caller know what the receiver's configuration is.
7. If at any time an error occurs, thecatch() clause outputs an error message to the log.

Tracking other state changes

We can also watch for changes to the signaling state (by acceptingsignalingstatechange events) and the ICE gathering state (by acceptingicegatheringstatechange events). We aren't using these for anything, so all we do is log them. We could have not set up these event listeners at all.

function handleCallerSignalingStateChangeEvent() {  log(`Caller's signaling state changed to ${callerPC.signalingState}`);}function handleCallerGatheringStateChangeEvent() {  log(`Caller's ICE gathering state changed to ${callerPC.iceGatheringState}`);}

Adding candidates to the receiver

When the receiver'sRTCPeerConnection ICE layer comes up with a new candidate to propose, it issues anicecandidate event toreceiverPC. Theicecandidate event handler's job is to transmit the candidate to the caller. In our example, we are directly controlling both the caller and the receiver, so we can just directly add the candidate to the caller by calling itsaddIceCandidate() method. That's handled byhandleReceiverIceEvent().

This code is analogous to theicecandidate event handler for the caller, seen inAdding candidates to the caller above.

function handleReceiverIceEvent(event) {  if (event.candidate) {    log(`Adding candidate to caller: ${event.candidate.candidate}`);    callerPC      .addIceCandidate(new RTCIceCandidate(event.candidate))      .catch((err) => log(`Error adding candidate to caller: ${err}`));  } else {    log("Receiver is out of candidates.");  }}

If theicecandidate event has a non-nullcandidate property, we create a newRTCIceCandidate object from theevent.candidate string and deliver it to the caller by passing that intocallerPC.addIceCandidate(). IfaddIceCandidate() fails, thecatch() clause outputs the error to our log box.

Ifevent.candidate isnull, that indicates that there are no more candidates available, and we log that information.

Adding media to the receiver

When the receiver begins to receive media, an event is delivered to the receiver'sRTCPeerConnection,receiverPC. As explained inStarting the connection process, the current WebRTC specification uses thetrack event for this. Since some browsers haven't been updated to support this yet, we also need to handle theaddstream event. This is demonstrated in thehandleReceiverTrackEvent() andhandleReceiverAddStreamEvent() methods below.

function handleReceiverTrackEvent(event) {  audio.srcObject = event.streams[0];}function handleReceiverAddStreamEvent(event) {  audio.srcObject = event.stream;}

Thetrack event includes astreams property containing an array of the streams the track is a member of (one track can be part of many streams). We take the first stream and attach it to the<audio> element.

Theaddstream event includes astream property specifying a single stream added to the track. We attach it to the<audio> element.

Logging

A simplelog() function is used throughout the code to append text to a<div> box for displaying status and errors to the user.

function log(msg) {  logElement.innerText += `${msg}\n`;}

You can try this example here. When you click the "Dial" button, you should see a series of logging messages output; then the dialing will begin. If your browser plays the tones audibly as part of its user experience, you should hear them as they're transmitted.

Once transmission of the tones is complete, the connection is closed. You can click "Dial" again to reconnect and send the tones.

• WebRTC API
• Lifetime of a WebRTC session
• Signaling and video calling (a tutorial and example which explains the signaling process in more detail)
• Introduction to WebRTC protocols