RTCDTMFToneChangeEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface RTCDTMFToneChangeEvent extends Event

Beschreibung

RTCDTMFToneChangeEvent ist das Ereignisobjekt des tonechange-Events, das ein RTCDTMFSender auslöst. DTMF (Dual-Tone Multi-Frequency) sind die bekannten Tastentöne von Telefonen. In WebRTC-Anwendungen braucht man sie vor allem, wenn man mit klassischen Telefonsystemen arbeitet, etwa um in einem Sprachmenü („Drücken Sie die 1 …“) über ein SIP-Gateway zu navigieren.

Nach dem Aufruf von RTCDTMFSender.insertDTMF() spielt der Browser die Töne nacheinander ab. Bei jedem neuen Ton wird ein tonechange-Event ausgelöst. Die Eigenschaft tone enthält dann das gerade gespielte Zeichen (0–9, A–D, *, # oder , für eine Pause von 2 Sekunden). Sind alle Töne abgespielt, folgt ein letztes Event, bei dem tone ein leerer String ist. Daran erkennt man, dass die Tonfolge fertig ist.

Typische Anwendungsfälle sind eine visuelle Rückmeldung in einer Wähltastatur, das Protokollieren gesendeter Töne und das Anstoßen weiterer Aktionen, sobald eine Wahlsequenz beendet ist. Neben den geerbten Eigenschaften von Event bietet das Interface nur die schreibgeschützte Eigenschaft tone.

Man kann den Handler mit sender.dtmf.addEventListener("tonechange", handler) registrieren oder über die Eigenschaft sender.dtmf.ontonechange. Eigene Instanzen lassen sich mit new RTCDTMFToneChangeEvent(type, options) erzeugen, zum Beispiel für Tests.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Events, in der Praxis immer `"tonechange"`. Gilt nur für den Konstruktor.
$options	{ tone?: string, bubbles?: boolean, cancelable?: boolean, composed?: boolean }	{}	Optionales Objekt für den Konstruktor. `tone` gibt das Tonzeichen an (Standard: `""`). Dazu kommen die üblichen `EventInit`-Optionen.
$tone (Eigenschaft)	string	""	Schreibgeschützt. Das Zeichen des Tons, der gerade zu spielen begonnen hat. Ein leerer String bedeutet, dass die Tonfolge vollständig abgespielt ist.

Beispiele

Tastentöne senden und mit addEventListener verfolgen

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

const dtmf = sender.dtmf; // RTCDTMFSender oder null

const onToneChange = (event) => {
  if (event.tone === '') {
    console.log('Wahlsequenz beendet');
    dtmf.removeEventListener('tonechange', onToneChange);
  } else {
    console.log(`Spiele Ton: ${event.tone}`);
  }
};

dtmf.addEventListener('tonechange', onToneChange);

// Erst senden, wenn die Verbindung steht
if (dtmf.canInsertDTMF) {
  dtmf.insertDTMF('12#', 100, 70);
}

Spiele Ton: 1 Spiele Ton: 2 Spiele Ton: # Wahlsequenz beendet

Wähltastatur über die Eigenschaft ontonechange hervorheben

const highlightKey = (tone) => {
  document.querySelectorAll('.dial-key').forEach((el) => {
    el.classList.toggle('active', el.dataset.tone === tone);
  });
};

const setupDialpad = (sender) => {
  const dtmf = sender.dtmf;
  if (!dtmf) {
    console.warn('DTMF wird für diesen Sender nicht unterstützt');
    return;
  }
  dtmf.ontonechange = ({ tone }) => {
    highlightKey(tone); // Bei '' wird keine Taste mehr hervorgehoben
    document.querySelector('#status').textContent =
      tone ? `Sende ${tone} …` : 'Bereit';
  };
};

Event manuell erzeugen, z. B. für Unit-Tests

const event = new RTCDTMFToneChangeEvent('tonechange', { tone: '5' });
console.log(event.type, event.tone);

const endEvent = new RTCDTMFToneChangeEvent('tonechange');
console.log(JSON.stringify(endEvent.tone));

tonechange 5 ""

// Wichtig · Fallstricke

Ende der Tonfolge: Das letzte Event hat tone === "". Prüfen Sie auf den leeren String und nicht einfach mit if (!event.tone), wenn Sie das Ende von anderen Fällen unterscheiden müssen. Auch eine Pause (",") löst ein eigenes Event aus.
sender.dtmf kann null sein, etwa bei Video-Tracks oder wenn der Browser DTMF nicht unterstützt. Vor der Nutzung sollten Sie außerdem canInsertDTMF prüfen. Solange die Verbindung nicht aufgebaut ist, kommen keine Events.
Ein neuer Aufruf von insertDTMF() ersetzt die noch ausstehende Tonfolge. Die Events beziehen sich dann auf die neue Folge.
Die Töne werden nach RFC 4733 als RTP-Telefonie-Events gesendet, also nicht als hörbares Audio. Die Gegenstelle, z. B. ein SIP-Gateway, muss telephone-event aushandeln.
Kompatibilität: Chrome/Edge und Firefox unterstützen das Interface seit Langem, Safari seit Version 13.1. Frühere Implementierungen verwendeten RTCPeerConnection.createDTMFSender(). Dieser Weg ist veraltet, verwenden Sie RTCRtpSender.dtmf.

Siehe auch

RTCDTMFSender RTCDTMFSender.insertDTMF() RTCRtpSender.dtmf RTCPeerConnection Event PaymentMethodChangeEvent