RTCPeerConnection.createDTMFSender() — Methode · JavaScript-Referenz

Signatur

RTCPeerConnection.prototype.createDTMFSender(track)

Beschreibung

Mit createDTMFSender() erhält man zu einem Audio-Track, der über eine RTCPeerConnection gesendet wird, ein RTCDTMFSender-Objekt. Über dieses Objekt lassen sich DTMF-Töne (Dual-Tone Multi-Frequency) senden, also die Tastentöne eines Telefons (0–9, *, #, A–D). Gebraucht wird das vor allem, wenn eine WebRTC-Anwendung mit einem klassischen Telefonnetz spricht, etwa mit Sprachmenüs (IVR) oder Konferenzsystemen, die PIN-Eingaben erwarten. Die Töne werden nach RFC 4733 als eigene RTP-Ereignisse übertragen und nicht in den Ton gemischt.

Die Methode stammt aus einer frühen Fassung der WebRTC-Spezifikation und wurde entfernt. Der standardisierte Weg ist die Eigenschaft RTCRtpSender.dtmf. Den passenden RTCRtpSender bekommt man von addTrack() zurück oder über getSenders(). Neuer Code sollte nur diesen Weg nutzen. createDTMFSender() ist höchstens als Rückfalllösung für sehr alte Chromium-Browser sinnvoll.

Der übergebene Track muss ein Audio-Track sein und bereits zur Verbindung gehören. Getönt werden kann erst, wenn die Verbindung steht und die Gegenseite das Payload telephone-event ausgehandelt hat. Ob das Senden möglich ist, zeigt RTCDTMFSender.canInsertDTMF.

Parameter

Name	Typ	Default	Beschreibung
$track Pflicht	MediaStreamTrack		Ein Audio-Track (`kind === "audio"`), der bereits über diese `RTCPeerConnection` gesendet wird. Über ihn werden die DTMF-Töne übertragen.

Rückgabewert

Typ

RTCDTMFSender

Beschreibung

Ein neues RTCDTMFSender-Objekt, das zum angegebenen Track gehört. Mit insertDTMF() reiht es Töne in eine Warteschlange ein und meldet über das Ereignis tonechange, welcher Ton gerade gespielt wird.

Beispiele

Veraltete Nutzung in alten Chromium-Versionen

const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [audioTrack] = stream.getAudioTracks();
pc.addTrack(audioTrack, stream);

// ... Angebot und Antwort austauschen (Signalisierung) ...

if (typeof pc.createDTMFSender === 'function') {
  const dtmf = pc.createDTMFSender(audioTrack);
  dtmf.ontonechange = (e) => console.log('Ton:', e.tone || '(fertig)');
  dtmf.insertDTMF('1234#', 100, 70);
}

Ton: 1 Ton: 2 Ton: 3 Ton: 4 Ton: # Ton: (fertig)

Standardweg mit Rückfall: DTMF-Sender ermitteln

const getDtmfSender = (pc, track) => {
  const sender = pc.getSenders().find((s) => s.track === track);
  if (sender?.dtmf) return sender.dtmf;          // Standard: RTCRtpSender.dtmf
  if (typeof pc.createDTMFSender === 'function') {
    return pc.createDTMFSender(track);           // Alt: nur altes Chromium
  }
  return null;
};

const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [track] = stream.getAudioTracks();
pc.addTrack(track, stream);

const dtmf = getDtmfSender(pc, track);
console.log(dtmf ? 'DTMF verfügbar' : 'DTMF nicht unterstützt');

DTMF verfügbar

Konferenz-PIN senden, sobald die Verbindung steht

const sendPin = (pc, dtmf, pin) => {
  const trySend = () => {
    if (pc.connectionState === 'connected' && dtmf.canInsertDTMF) {
      dtmf.insertDTMF(`${pin}#`, 120, 80);
      console.log('PIN gesendet, Warteschlange:', dtmf.toneBuffer);
      pc.removeEventListener('connectionstatechange', trySend);
    }
  };
  pc.addEventListener('connectionstatechange', trySend);
  trySend();
};

// dtmf z. B. aus getDtmfSender() des vorherigen Beispiels
// sendPin(pc, dtmf, '4711');

PIN gesendet, Warteschlange: 4711#

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: Die Methode wurde aus der WebRTC-Spezifikation gestrichen. Firefox und Safari haben sie nie angeboten, in aktuellen Chromium-Versionen fehlt sie oder gilt als veraltet. Verwenden Sie stattdessen RTCRtpSender.dtmf, das in allen modernen Browsern verfügbar ist.
Ist track kein Audio-Track oder gehört er nicht zur Verbindung, wird ein Fehler geworfen (in Chromium meist SyntaxError oder InvalidAccessError). Bauen Sie deshalb eine Funktionsprüfung und einen try/catch-Block ein.
Die Töne kommen nur an, wenn beide Seiten das Payload telephone-event ausgehandelt haben. Andernfalls ist canInsertDTMF gleich false.
Für insertDTMF() gilt: Die Tondauer muss zwischen 40 und 6000 ms liegen, die Pause zwischen den Tönen mindestens 30 ms. Ein Komma im Tonstring bedeutet 2 Sekunden Pause. Ein neuer Aufruf ersetzt die noch nicht gespielten Töne in der Warteschlange.

Siehe auch

RTCDTMFSender RTCDTMFSender.insertDTMF() RTCRtpSender.dtmf RTCPeerConnection.addTrack() RTCPeerConnection.getSenders() RTCPeerConnection.removeStream()