RTCDTMFSender.canInsertDTMF — Eigenschaft · JavaScript-Referenz

Signatur

RTCDTMFSender.canInsertDTMF

Beschreibung

Die Eigenschaft canInsertDTMF des Interfaces RTCDTMFSender gibt true zurück, wenn der zugehörige Sender DTMF-Töne (Tastentöne wie bei der Telefonwahl, z. B. für Sprachmenüs oder IVR-Systeme) in den Audiostrom einfügen kann. Ist das nicht möglich, liefert sie false.

Ob DTMF möglich ist, hängt von mehreren Bedingungen ab:

Der zugehörige RTCRtpTransceiver muss eine Senderichtung haben (currentDirection ist "sendrecv" oder "sendonly").
Die Verbindung muss ausgehandelt sein, und die Gegenstelle muss den Payload-Typ telephone-event (RFC 4733) in ihrer SDP unterstützen.
Der Transceiver darf nicht gestoppt sein.

Prüfe canInsertDTMF vor dem Aufruf von insertDTMF(). Ist der Wert false, wirft insertDTMF() eine InvalidStateError-DOMException. Den RTCDTMFSender bekommst du über RTCRtpSender.dtmf eines Audio-Senders.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn gerade DTMF-Töne gesendet werden können, sonst false.

Beispiele

Vor dem Senden prüfen, ob DTMF möglich ist

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

// ... Angebot/Antwort aushandeln (Signalisierung) ...

const dtmf = sender.dtmf;
if (dtmf?.canInsertDTMF) {
  dtmf.insertDTMF('1234#', 100, 70);
  console.log('DTMF gesendet');
} else {
  console.log('DTMF wird derzeit nicht unterstützt');
}

DTMF gesendet

Wähltastatur erst nach erfolgreicher Aushandlung freischalten

const keypad = document.querySelector('#keypad');
keypad.disabled = true;

const updateKeypad = (sender) => {
  keypad.disabled = !(sender.dtmf && sender.dtmf.canInsertDTMF);
};

pc.addEventListener('connectionstatechange', () => {
  if (pc.connectionState === 'connected') {
    const audioSender = pc.getSenders().find((s) => s.track?.kind === 'audio');
    if (audioSender) updateKeypad(audioSender);
  }
});

Sichere Hilfsfunktion mit Fehlerbehandlung

const sendTones = (sender, tones) => {
  const dtmf = sender?.dtmf;
  if (!dtmf) {
    console.warn('Kein DTMF-Sender (kein Audio-Track?)');
    return false;
  }
  if (!dtmf.canInsertDTMF) {
    console.warn('DTMF momentan nicht möglich');
    return false;
  }
  try {
    dtmf.insertDTMF(tones);
    return true;
  } catch (err) {
    console.error(err.name, err.message);
    return false;
  }
};

sendTones(pc.getSenders()[0], '*9');

// Wichtig · Fallstricke

Zeitpunkt: Vor Abschluss der SDP-Aushandlung (z. B. direkt nach addTrack()) ist der Wert meist false. Prüfe ihn erst, wenn die Verbindung steht.
Nur Audio: RTCRtpSender.dtmf ist bei Video-Sendern null. Greifst du ohne Prüfung auf canInsertDTMF zu, gibt es einen TypeError. Optionale Verkettung (?.) verwenden.
Der Wert kann sich während der Sitzung ändern, etwa bei einer Neuaushandlung oder wenn der Transceiver gestoppt oder seine Richtung auf "recvonly" gesetzt wird.
Kompatibilität: Chrome und Edge unterstützen die Eigenschaft erst seit Version 108. Ältere Browser kennen RTCDTMFSender zwar, aber nicht canInsertDTMF. Dort ist der Wert undefined, und ein Aufruf von insertDTMF() in try/catch ist die Ausweichlösung.
DTMF funktioniert nur, wenn die Gegenstelle telephone-event aushandelt. Viele reine Browser-zu-Browser-Szenarien brauchen DTMF gar nicht. Wichtig ist es vor allem bei SIP- und Telefonie-Gateways.

Siehe auch

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