RTCDTMFSender — Schnittstelle · JavaScript-Referenz

Signatur

interface RTCDTMFSender extends EventTarget

Beschreibung

RTCDTMFSender dient dazu, DTMF-Töne (Dual-Tone Multi-Frequency, also die Töne von Telefontasten) über eine WebRTC-Verbindung zu senden. Das braucht man vor allem, wenn eine WebRTC-Anwendung über ein Gateway mit dem klassischen Telefonnetz oder einer Telefonanlage (IVR-Sprachmenü, Voicemail, Konferenz-PIN) spricht. Dann muss der Nutzer zum Beispiel „Drücken Sie die 1“ beantworten können.

Eine Instanz legt man nicht selbst an. Man liest sie aus der Eigenschaft RTCRtpSender.dtmf eines Audio-Senders. Bei Video-Sendern oder wenn DTMF nicht unterstützt wird, ist diese Eigenschaft null. Die Töne werden nach RFC 4733 als telephone-event-RTP-Pakete übertragen und nicht als hörbares Audiosignal eingemischt.

Die Schnittstelle hat folgende Bestandteile:

insertDTMF(tones, duration, interToneGap): stellt eine Tonfolge in die Warteschlange. Ein neuer Aufruf ersetzt die noch nicht gesendeten Töne.
toneBuffer (nur lesbar): enthält die Töne, die noch nicht gesendet wurden.
canInsertDTMF (nur lesbar): ist true, wenn gerade DTMF gesendet werden kann.
tonechange-Ereignis: wird bei jedem Tonbeginn ausgelöst und mit leerem tone, wenn die Folge fertig ist. Man kann es per addEventListener("tonechange", …) oder über ontonechange abonnieren.

Parameter

Name	Typ	Default	Beschreibung
$tones Pflicht	string		Parameter von `insertDTMF()`: die Tonfolge aus `0–9`, `A–D`, `*`, `#` und `,`. Ein Komma bedeutet 2 Sekunden Pause. Kleinbuchstaben `a–d` werden in Großbuchstaben umgewandelt. Bei ungültigen Zeichen wird ein `InvalidCharacterError` geworfen. Ein leerer String bricht die Warteschlange ab.
$duration	number	100	Dauer jedes Tons in Millisekunden. Erlaubt sind 40 bis 6000, Werte außerhalb werden auf diesen Bereich begrenzt.
$interToneGap	number	70	Pause zwischen zwei Tönen in Millisekunden, mindestens 30.

Rückgabewert

Typ

RTCDTMFSender

Beschreibung

Man erhält die Instanz über RTCRtpSender.dtmf. insertDTMF() selbst liefert undefined.

Beispiele

DTMF-Sender aus dem Audio-Sender holen und Töne senden

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

// ... Angebot/Antwort austauschen, bis die Verbindung steht ...

const dtmf = sender.dtmf;
if (dtmf?.canInsertDTMF) {
  dtmf.insertDTMF('1234#', 120, 80);
  console.log('Warteschlange:', dtmf.toneBuffer);
}

Warteschlange: 1234#

Fortschritt mit addEventListener verfolgen

const dtmf = sender.dtmf;

const onTone = (event) => {
  if (event.tone) {
    console.log(`Sende Ton: ${event.tone}`);
  } else {
    console.log('Tonfolge fertig');
    dtmf.removeEventListener('tonechange', onTone);
  }
};

dtmf.addEventListener('tonechange', onTone);
dtmf.insertDTMF('9,1');

Sende Ton: 9 Sende Ton: , Sende Ton: 1 Tonfolge fertig

Telefon-Tastenfeld mit ontonechange

const dtmf = sender.dtmf;
const anzeige = document.querySelector('#dtmf-anzeige');

dtmf.ontonechange = ({ tone }) => {
  anzeige.textContent = tone ? `Taste ${tone}` : '';
};

document.querySelectorAll('button[data-taste]').forEach((btn) => {
  btn.addEventListener('click', () => {
    if (!dtmf.canInsertDTMF) return;
    // Neue Taste an die noch ausstehenden Töne anhängen, statt sie zu ersetzen
    dtmf.insertDTMF(dtmf.toneBuffer + btn.dataset.taste);
  });
});

// Wichtig · Fallstricke

Ersetzen statt Anhängen: insertDTMF() überschreibt den aktuellen toneBuffer. Wer Töne anhängen will, muss dtmf.toneBuffer + neueTöne übergeben.
Verbindungsstatus: Wenn die Verbindung noch nicht steht, der Track beendet ist oder die Gegenseite telephone-event nicht ausgehandelt hat, ist canInsertDTMF gleich false. Dann wirft insertDTMF() einen InvalidStateError.
sender.dtmf kann null sein, etwa bei Video-Sendern. Deshalb optionales Chaining (?.) verwenden.
Kompatibilität: Der ältere, Chrome-spezifische Weg pc.createDTMFSender(track) ist veraltet. Stattdessen RTCRtpSender.dtmf verwenden. Safari unterstützt die Schnittstelle erst ab Version 13.1.
Die Töne sind lokal nicht hörbar. Wer akustische Rückmeldung will, muss sie selbst erzeugen, z. B. mit der Web Audio API.
Die Werte für duration und interToneGap werden stillschweigend auf den erlaubten Bereich begrenzt, es wird kein Fehler geworfen.

Siehe auch

RTCPeerConnection RTCRtpSender RTCRtpSender.dtmf RTCDTMFSender.insertDTMF() RTCDTMFSender.toneBuffer RTCDTMFToneChangeEvent