MediaTrackConstraints.restrictOwnAudio — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackConstraints.restrictOwnAudio

Beschreibung

Die Eigenschaft restrictOwnAudio des Wörterbuchs MediaTrackConstraints gilt für Audiospuren, die mit navigator.mediaDevices.getDisplayMedia() aufgenommen werden. Ist sie true, versucht der Browser, den Ton, den die aufnehmende Seite selbst abspielt, aus dem aufgenommenen System- oder Tab-Audio zu entfernen. Die aufgenommene Tonspur enthält dann nur noch den Ton anderer Quellen.

Das ist vor allem bei Videokonferenz- und Streaming-Anwendungen nützlich: Teilt ein Nutzer seinen ganzen Bildschirm samt Systemton, würde sonst auch der Ton der Konferenz selbst (also die Stimmen der anderen Teilnehmer) erneut aufgenommen und zurückgesendet. Das führt zu Echos und Rückkopplungen. Mit restrictOwnAudio: true lässt sich das verhindern.

Als ConstrainBoolean kann der Wert entweder direkt als true/false (bevorzugter Wert) oder als Objekt { exact: … } bzw. { ideal: … } angegeben werden. Welcher Wert tatsächlich gilt, verrät MediaStreamTrack.getSettings().restrictOwnAudio. Ob der Browser die Einschränkung überhaupt kennt, prüfen Sie mit navigator.mediaDevices.getSupportedConstraints().

Verwechseln Sie die Eigenschaft nicht mit suppressLocalAudioPlayback: Diese schaltet die lokale Wiedergabe eines aufgenommenen Tabs stumm, restrictOwnAudio dagegen filtert den eigenen Ton aus der Aufnahme.

Parameter

Name	Typ	Default	Beschreibung
$restrictOwnAudio	boolean \| { exact?: boolean, ideal?: boolean }	false	`true`: Audio des aufnehmenden Dokuments soll aus der Aufnahme entfernt werden. Als einfacher Boolean gilt der Wert als bevorzugt (`ideal`), mit `exact` als zwingend.

Beispiele

Bildschirm mit Systemton teilen, ohne eigenen Ton

const startScreenShare = async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: true,
    audio: {
      restrictOwnAudio: true, // eigenen Konferenzton herausfiltern
      echoCancellation: false
    }
  });

  const [audioTrack] = stream.getAudioTracks();
  console.log('Eigener Ton gefiltert:', audioTrack?.getSettings().restrictOwnAudio);
  return stream;
};

document.querySelector('#share').addEventListener('click', startScreenShare);

Eigener Ton gefiltert: true

Unterstützung vorab prüfen

const supported = navigator.mediaDevices.getSupportedConstraints();

const audioConstraints = supported.restrictOwnAudio
  ? { restrictOwnAudio: true }
  : true; // Fallback: normales Audio anfordern

console.log('restrictOwnAudio unterstützt:', Boolean(supported.restrictOwnAudio));

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

restrictOwnAudio unterstützt: true

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

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

if (track) {
  try {
    await track.applyConstraints({ restrictOwnAudio: { exact: true } });
    console.log('Aktiv:', track.getSettings().restrictOwnAudio);
  } catch (err) {
    // OverconstrainedError, falls der Browser es nicht erzwingen kann
    console.warn('Nicht anwendbar:', err.name);
  }
}

Aktiv: true

// Wichtig · Fallstricke

Experimentell: Derzeit nur in Chromium-basierten Browsern verfügbar. Firefox und Safari ignorieren die Einschränkung. Prüfen Sie die Unterstützung immer mit getSupportedConstraints().
Die Einschränkung wirkt nur bei Audio aus getDisplayMedia(), nicht bei Mikrofonspuren aus getUserMedia().
Ob überhaupt Systemton aufgenommen wird, hängt von Betriebssystem, Browser und der Auswahl des Nutzers ab (z. B. Tab statt ganzer Bildschirm). Eine Audiospur kann also ganz fehlen, deshalb gegen undefined absichern.
Mit { exact: true } in applyConstraints() kann ein OverconstrainedError ausgelöst werden. Der einfache Boolean-Wert ist robuster.
Das Filtern erfolgt nach bestem Bemühen. Ton, der z. B. über eingebettete Fremdseiten (iframes anderer Herkunft) oder andere Tabs abgespielt wird, wird nicht unbedingt entfernt.

Siehe auch

MediaTrackConstraints.aspectRatio MediaTrackConstraints.deviceId MediaTrackConstraints.groupId MediaTrackConstraints.autoGainControl MediaTrackConstraints.channelCount