RTCDTMFToneChangeEvent.tone — Eigenschaft · JavaScript-Referenz

Signatur

RTCDTMFToneChangeEvent.tone

Beschreibung

Die Eigenschaft tone des RTCDTMFToneChangeEvent gibt das DTMF-Zeichen (Dual-Tone Multi-Frequency, also Tonwahl) an, dessen Wiedergabe gerade begonnen hat. Das Ereignis heißt tonechange und wird von einem RTCDTMFSender ausgelöst. Den Sender bekommt man über RTCRtpSender.dtmf.

Mögliche Werte sind die Ziffern 0–9, die Buchstaben A–D, *, # sowie das Komma ,, das für eine Pause von 2 Sekunden steht. Ist die Warteschlange (RTCDTMFSender.toneBuffer) leer, wird ein letztes tonechange-Ereignis mit tone === "" ausgelöst. Daran erkennt man zuverlässig, dass die Wahlfolge komplett gesendet wurde.

Typische Einsatzfälle: Man zeigt in WebRTC-Telefonie-Anwendungen (z. B. bei Anbindung an SIP-Gateways oder Sprachmenüs/IVR) die gerade gesendete Ziffer in der Oberfläche an, protokolliert den Fortschritt oder startet nach dem Ende der Wahlfolge weitere Schritte.

Beispiele

Gesendete Töne mit addEventListener protokollieren

// pc ist eine bestehende RTCPeerConnection mit Audiospur
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [track] = stream.getAudioTracks();
const sender = pc.addTrack(track, stream);

const dtmf = sender.dtmf;
if (!dtmf) {
  console.warn('DTMF wird nicht unterstützt');
} else {
  dtmf.addEventListener('tonechange', (event) => {
    if (event.tone !== '') {
      console.log(`Sende Ton: ${event.tone}`);
    } else {
      console.log('Alle Töne gesendet');
    }
  });

  dtmf.insertDTMF('12#', 100, 70);
}

Sende Ton: 1 Sende Ton: 2 Sende Ton: # Alle Töne gesendet

Wahlfolge in der Oberfläche anzeigen (on-Property)

const display = document.querySelector('#dtmf-display');
const dtmf = pc.getSenders().find((s) => s.track?.kind === 'audio')?.dtmf;

dtmf.ontonechange = ({ tone }) => {
  if (tone === ',') {
    display.textContent += ' (Pause) ';
  } else if (tone) {
    display.textContent += tone;
  } else {
    display.textContent += ' ✓';
    dtmf.ontonechange = null; // Handler entfernen
  }
};

dtmf.insertDTMF('0800,123');

Ende der Wahlfolge als Promise abwarten

const sendDTMF = (dtmf, tones, duration = 100, gap = 70) =>
  new Promise((resolve) => {
    const onChange = (event) => {
      if (event.tone === '') {
        dtmf.removeEventListener('tonechange', onChange);
        resolve();
      }
    };
    dtmf.addEventListener('tonechange', onChange);
    dtmf.insertDTMF(tones, duration, gap);
  });

await sendDTMF(sender.dtmf, '4711#');
console.log('PIN übertragen');

PIN übertragen

// Wichtig · Fallstricke

Leerer String am Ende: Das letzte Ereignis hat tone === "". Wer nur auf Truthiness prüft, muss diesen Fall bewusst behandeln, sonst entgeht einem das Ende der Wahlfolge.
Komma als Pause: "," ist kein hörbarer Ton, sondern eine Pause von 2 Sekunden. Trotzdem wird dafür ein eigenes tonechange-Ereignis ausgelöst.
Kleinbuchstaben: insertDTMF() nimmt auch a–d an, speichert sie aber in Großschreibung. tone liefert dann "A"–"D".
Neuer Aufruf ersetzt die Warteschlange: Ruft man insertDTMF() erneut auf, wird der bisherige toneBuffer verworfen. Töne, die noch nicht gespielt wurden, erzeugen dann kein Ereignis mehr.
Kompatibilität: Alle aktuellen Browser unterstützen die Eigenschaft. RTCRtpSender.dtmf ist allerdings null, wenn der Sender keine Audiospur hat oder der Browser DTMF nicht unterstützt. Deshalb vorher prüfen. Die ältere API RTCPeerConnection.createDTMFSender() ist veraltet.
Die Eigenschaft ist schreibgeschützt. Zuweisungen werden stillschweigend ignoriert (im Strict Mode wird ein TypeError geworfen).

Siehe auch

RTCDTMFToneChangeEvent RTCDTMFSender RTCDTMFSender.insertDTMF() RTCDTMFSender.toneBuffer RTCRtpSender.dtmf PaymentMethodChangeEvent.methodDetails