RTCRtpSender.dtmf — Eigenschaft · JavaScript-Referenz

Signatur

RTCRtpSender.dtmf

Beschreibung

Die Eigenschaft dtmf eines RTCRtpSender gibt ein RTCDTMFSender-Objekt zurück. Darüber lassen sich DTMF-Töne (Dual-Tone Multi-Frequency, also die Tastentöne eines Telefons) über eine WebRTC-Verbindung senden. Gebraucht wird das vor allem, wenn eine Browser-Anwendung mit klassischer Telefonie spricht, z. B. mit Sprachmenüs („Drücken Sie 1 für …“), Konferenz-PINs oder SIP-Gateways.

Die Töne gehen nicht als hörbares Audio raus, sondern außerhalb des Audiosignals als RTP-Telephone-Events nach RFC 4733. Die Gegenstelle muss dieses Format in der SDP-Aushandlung unterstützen (telephone-event).

Einen Wert ungleich null bekommt man nur bei Sendern, deren Spur vom Typ audio ist. Bei Videospuren ist dtmf null, und bei Sendern ohne DTMF-Unterstützung ebenfalls. Vor der Nutzung sollte man deshalb immer auf null prüfen und über RTCDTMFSender.canInsertDTMF abfragen, ob gerade tatsächlich gesendet werden kann.

Rückgabewert

Typ

RTCDTMFSender | null

Beschreibung

Ein RTCDTMFSender zum Senden von DTMF-Tönen mit insertDTMF(), oder null, wenn der Sender keine Audiospur überträgt oder kein DTMF unterstützt.

Beispiele

DTMF-Sender der Audiospur ermitteln

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

const dtmfSender = sender.dtmf;
console.log(dtmfSender ? 'DTMF verfügbar' : 'Kein DTMF möglich');

DTMF verfügbar

PIN für eine Telefonkonferenz eingeben

const sendDigits = (pc, digits) => {
  const sender = pc.getSenders().find(s => s.track?.kind === 'audio');
  const dtmf = sender?.dtmf;

  if (!dtmf || !dtmf.canInsertDTMF) {
    console.warn('DTMF kann derzeit nicht gesendet werden');
    return;
  }

  // 100 ms Tondauer, 70 ms Pause zwischen den Tönen
  dtmf.insertDTMF(digits, 100, 70);
};

// Nach erfolgreichem Verbindungsaufbau:
sendDigits(pc, '4711#');

Gesendete Töne mit dem tonechange-Event verfolgen

const sender = pc.getSenders().find(s => s.track?.kind === 'audio');
const dtmf = sender?.dtmf;

if (dtmf) {
  dtmf.addEventListener('tonechange', (event) => {
    if (event.tone) {
      console.log(`Sende Ton: ${event.tone}`);
    } else {
      console.log('Alle Töne gesendet');
    }
  });
  dtmf.insertDTMF('123');
  console.log('Warteschlange:', dtmf.toneBuffer);
}

Warteschlange: 123 Sende Ton: 1 Sende Ton: 2 Sende Ton: 3 Alle Töne gesendet

// Wichtig · Fallstricke

Nur Audio: Bei Videospuren ist dtmf immer null. Vorher also immer prüfen, z. B. mit optionaler Verkettung (sender?.dtmf).
Verbindungszustand: insertDTMF() wirft einen InvalidStateError, wenn die Verbindung noch nicht steht oder die Gegenstelle telephone-event nicht ausgehandelt hat. Deshalb vorher canInsertDTMF abfragen.
Erlaubte Zeichen: 0–9, A–D, *, # und , (2 Sekunden Pause). Bei anderen Zeichen wirft insertDTMF() einen InvalidCharacterError.
Überschreiben: Ein neuer Aufruf von insertDTMF() ersetzt die noch nicht gesendeten Töne in toneBuffer, er hängt sie nicht an.
Kompatibilität: In allen modernen Browsern verfügbar, in Safari erst ab 13.1. Das ältere RTCPeerConnection.createDTMFSender() ist veraltet und sollte nicht mehr verwendet werden.

Siehe auch

RTCDTMFSender RTCDTMFSender.insertDTMF() RTCRtpSender RTCPeerConnection.addTrack() RTCPeerConnection.getSenders() RTCErrorEvent.error