MediaTrackConstraints.suppressLocalAudioPlayback — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackConstraints.suppressLocalAudioPlayback

Beschreibung

Die Eigenschaft suppressLocalAudioPlayback des Wörterbuchs MediaTrackConstraints gehört zur Screen Capture API. Sie gibt an, ob der Ton einer aufgenommenen Quelle (in der Praxis fast immer ein Browser-Tab) während der Aufnahme weiter über die lokalen Lautsprecher des Nutzers abgespielt werden soll. Ist der Wert true, wird die lokale Wiedergabe unterdrückt. Der Ton landet dann nur im MediaStreamTrack und nicht mehr zusätzlich in den Lautsprechern.

Typische Einsatzfälle sind Videokonferenzen und Präsentationen: Wer einen Tab mit Video oder Musik teilt, will oft nicht, dass der Ton lokal doppelt oder mit Echo zu hören ist. Das Gleiche gilt für Aufnahme- und Streaming-Anwendungen, bei denen der Ton nur verarbeitet oder weitergeleitet werden soll.

Der Wert ist ein ConstrainBoolean. Du kannst also einfach true oder false angeben oder ein Objekt mit exact (Pflicht) bzw. ideal (Wunsch). Die Einschränkung gehört in das audio-Objekt, das du an navigator.mediaDevices.getDisplayMedia() übergibst. Welcher Wert tatsächlich gilt, liest du über MediaStreamTrack.getSettings() aus.

Ob der Browser die Einschränkung kennt, prüfst du vorher mit navigator.mediaDevices.getSupportedConstraints().suppressLocalAudioPlayback. Standardmäßig ist der Wert false, der Ton wird also lokal weiter abgespielt.

Parameter

Name	Typ	Default	Beschreibung
$(Wert)	boolean	false	Kurzform: `true` unterdrückt die lokale Wiedergabe, `false` behält sie bei. Der Wert gilt als Wunsch (wie `ideal`).
$exact	boolean		Pflichtwert. Kann der Browser ihn nicht erfüllen, schlägt die Anfrage mit `OverconstrainedError` fehl.
$ideal	boolean		Wunschwert. Der Browser versucht, ihn einzuhalten. Klappt das nicht, schlägt die Anfrage trotzdem nicht fehl.

Beispiele

Tab teilen, ohne den Ton lokal abzuspielen

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

  const [audioTrack] = stream.getAudioTracks();
  if (audioTrack) {
    console.log('Lokale Wiedergabe unterdrückt:',
      audioTrack.getSettings().suppressLocalAudioPlayback);
  } else {
    console.log('Der Nutzer hat keinen Ton freigegeben.');
  }
  return stream;
};

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

Lokale Wiedergabe unterdrückt: true

Unterstützung prüfen und sauber zurückfallen

const buildAudioConstraints = () => {
  const supported = navigator.mediaDevices.getSupportedConstraints();
  if (supported.suppressLocalAudioPlayback) {
    return { suppressLocalAudioPlayback: { ideal: true } };
  }
  console.warn('suppressLocalAudioPlayback wird nicht unterstützt.');
  return true; // Ton ohne Zusatzwunsch anfordern
};

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

(In Firefox/Safari:) suppressLocalAudioPlayback wird nicht unterstützt.

Ton für eine Aufnahme mitschneiden, ohne ihn doppelt zu hören

const recordTab = async (durationMs = 5000) => {
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: true,
    audio: { suppressLocalAudioPlayback: true },
    preferCurrentTab: false
  });

  const recorder = new MediaRecorder(stream, { mimeType: 'video/webm' });
  const chunks = [];
  recorder.ondataavailable = (e) => chunks.push(e.data);

  const done = new Promise((resolve) => {
    recorder.onstop = () => resolve(new Blob(chunks, { type: 'video/webm' }));
  });

  recorder.start();
  setTimeout(() => {
    recorder.stop();
    stream.getTracks().forEach((t) => t.stop());
  }, durationMs);

  const blob = await done;
  console.log(`Aufnahme fertig: ${blob.size} Bytes`);
  return blob;
};

Aufnahme fertig: 812345 Bytes

// Wichtig · Fallstricke

Browser-Unterstützung: Bisher nur in Chromium-Browsern auf dem Desktop (ab Version 109). Firefox und Safari ignorieren die Einschränkung. Prüfe die Unterstützung immer mit getSupportedConstraints().
Nur Tab-Ton: Die Einschränkung wirkt praktisch nur, wenn ein Browser-Tab aufgenommen wird. Bei System- oder Fensterton lässt sich die lokale Wiedergabe meist nicht unterdrücken.
Ton ist nicht garantiert: Der Nutzer kann die Tonfreigabe im Auswahldialog abwählen. Dann enthält der Stream keinen Audio-Track, und getAudioTracks() liefert ein leeres Array.
Umschalten während der Aufnahme: Ob applyConstraints() den Wert nachträglich ändern kann, ist je nach Browser-Version unterschiedlich. Lege den Wert am besten direkt bei getDisplayMedia() fest und prüfe ihn anschließend mit getSettings().
exact mit Vorsicht: Mit { exact: true } riskierst du einen OverconstrainedError. ideal oder die einfache Boolean-Form ist robuster.
Sicherheit: getDisplayMedia() funktioniert nur in einem sicheren Kontext (HTTPS) und muss durch eine Nutzeraktion ausgelöst werden. In iframes braucht es zusätzlich die Berechtigungsrichtlinie display-capture.

Siehe auch

MediaTrackConstraints.channelCount MediaTrackConstraints.restrictOwnAudio MediaTrackConstraints.aspectRatio MediaTrackConstraints.displaySurface MediaTrackConstraints.echoCancellation