MediaTrackSupportedConstraints.suppressLocalAudioPlayback — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSupportedConstraints.suppressLocalAudioPlayback

Beschreibung

Die Eigenschaft suppressLocalAudioPlayback gehört zu dem Wörterbuch (Dictionary), das navigator.mediaDevices.getSupportedConstraints() zurückgibt. Ist sie true, kennt der Browser die gleichnamige Einschränkung. Mit ihr lässt sich festlegen, dass das Audio eines aufgenommenen Tabs nicht mehr lokal über die Lautsprecher abgespielt wird, solange die Aufnahme läuft.

Typisch ist das bei Videokonferenzen und Streaming-Anwendungen, die mit getDisplayMedia() einen Browser-Tab samt Ton teilen. Ohne die Unterdrückung hört der Nutzer den Ton doppelt oder es entsteht ein Echo. Wird die Einschränkung auf true gesetzt, leitet der Browser das Tab-Audio nur noch in den aufgenommenen MediaStreamTrack weiter.

Die Eigenschaft sagt nur, ob der Browser die Einschränkung kennt. Ob sie tatsächlich angewendet wurde, erfahren Sie über MediaStreamTrack.getSettings(). Fehlt die Eigenschaft im Rückgabeobjekt, wird die Einschränkung nicht unterstützt. Sie steht dann nicht auf false, sondern ist schlicht undefined.

Rückgabewert

Typ

boolean | undefined

Beschreibung

true, wenn die Einschränkung suppressLocalAudioPlayback unterstützt wird. Wird sie nicht unterstützt, fehlt die Eigenschaft meist ganz (undefined).

Beispiele

Unterstützung prüfen

const supported = navigator.mediaDevices.getSupportedConstraints();

if (supported.suppressLocalAudioPlayback) {
  console.log('Lokale Audiowiedergabe kann unterdrückt werden.');
} else {
  console.log('suppressLocalAudioPlayback wird nicht unterstützt.');
}

Lokale Audiowiedergabe kann unterdrückt werden.

Tab mit Ton teilen, ohne dass er lokal doppelt zu hören ist

const shareTab = async () => {
  const supported = navigator.mediaDevices.getSupportedConstraints();

  const audio = supported.suppressLocalAudioPlayback
    ? { suppressLocalAudioPlayback: true }
    : true;

  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: true,
    audio
  });

  const [audioTrack] = stream.getAudioTracks();
  if (audioTrack) {
    console.log('Einstellung:', audioTrack.getSettings().suppressLocalAudioPlayback);
  }
  return stream;
};

// Muss durch eine Nutzeraktion ausgelöst werden
document.querySelector('#share').addEventListener('click', shareTab);

Einstellung: true

Einschränkung nachträglich per applyConstraints() ändern

const toggleLocalPlayback = async (track, suppress) => {
  if (!navigator.mediaDevices.getSupportedConstraints().suppressLocalAudioPlayback) {
    console.warn('Nicht unterstützt');
    return;
  }
  await track.applyConstraints({ suppressLocalAudioPlayback: suppress });
  console.log('Jetzt:', track.getSettings().suppressLocalAudioPlayback);
};

// Beispiel: toggleLocalPlayback(audioTrack, false);

Jetzt: false

// Wichtig · Fallstricke

Browser-Kompatibilität: Derzeit nur in Chromium-basierten Browsern (Chrome, Edge, Opera) verfügbar, ab Version 109. Firefox und Safari unterstützen die Einschränkung nicht. Prüfen Sie die Unterstützung deshalb immer vorher.
Die Einschränkung wirkt nur bei Audio, das mit getDisplayMedia() aufgenommen wird, meist beim Teilen eines Tabs. Bei getUserMedia() und Mikrofonen hat sie keine Wirkung.
Der Nutzer entscheidet im Freigabe-Dialog, ob überhaupt Audio geteilt wird. Liefert getAudioTracks() ein leeres Array, gibt es keinen Track, auf den die Einschränkung wirken kann.
Wenn die Eigenschaft true ist, heißt das nicht, dass die Einschränkung auch angewendet wurde. Kontrollieren Sie das mit track.getSettings().
getDisplayMedia() funktioniert nur in sicheren Kontexten (HTTPS) und muss durch eine Nutzeraktion ausgelöst werden.

Siehe auch

MediaTrackConstraints.suppressLocalAudioPlayback MediaTrackSettings.suppressLocalAudioPlayback MediaTrackSupportedConstraints.restrictOwnAudio MediaTrackSupportedConstraints.aspectRatio MediaTrackSupportedConstraints.displaySurface