MediaTrackSettings.restrictOwnAudio — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSettings.restrictOwnAudio

Beschreibung

Die Eigenschaft restrictOwnAudio des Wörterbuchs MediaTrackSettings zeigt an, welchen Wert die Einschränkung (Constraint) restrictOwnAudio auf einer Audiospur gerade hat. Die Spur stammt aus einer Bildschirmaufnahme mit navigator.mediaDevices.getDisplayMedia(). Bei true filtert der Browser das Systemaudio heraus, das der aufnehmende Tab selbst erzeugt. Übrig bleibt nur der Ton der übrigen Quellen, etwa anderer Tabs, Fenster oder des Systems.

Gedacht ist das vor allem für Videokonferenzen, Präsentationen und Aufnahmewerkzeuge. Wenn eine Web-App den ganzen Bildschirm aufnimmt und gleichzeitig selbst Ton ausgibt (z. B. Stimmen anderer Teilnehmer oder Benachrichtigungstöne), landet dieser Ton sonst noch einmal in der Aufnahme. Das führt zu Echos, Rückkopplung oder doppelt hörbaren Stimmen. Mit restrictOwnAudio: true wird die Aufnahme sauberer.

Man fordert die Einschränkung beim Aufruf von getDisplayMedia() im Objekt audio an. Man kann sie auch nachträglich mit MediaStreamTrack.applyConstraints() setzen. Welcher Wert tatsächlich aktiv ist, verrät erst MediaStreamTrack.getSettings(). Der Browser darf eine Anforderung nämlich ignorieren, wenn er sie nicht umsetzen kann. Ob der Browser die Einschränkung überhaupt kennt, prüft man vorher mit navigator.mediaDevices.getSupportedConstraints().

Rückgabewert

Typ

boolean | undefined

Beschreibung

true, wenn Audio des erfassenden Tabs aus der Aufnahme gefiltert wird, sonst false. Die Eigenschaft fehlt (undefined), wenn der Browser die Einschränkung nicht unterstützt oder die Spur keine Audiospur einer Bildschirmaufnahme ist.

Beispiele

Unterstützung prüfen und Einschränkung anfordern

const startCapture = async () => {
  const supported = navigator.mediaDevices.getSupportedConstraints();
  if (!supported.restrictOwnAudio) {
    console.warn('restrictOwnAudio wird nicht unterstützt');
  }

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

  const [audioTrack] = stream.getAudioTracks();
  if (audioTrack) {
    const settings = audioTrack.getSettings();
    console.log('restrictOwnAudio:', settings.restrictOwnAudio);
  } else {
    console.log('Nutzer hat kein Audio freigegeben');
  }
  return stream;
};

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

restrictOwnAudio: true

Einstellung nachträglich umschalten

const toggleOwnAudioFilter = async (track, enabled) => {
  try {
    await track.applyConstraints({ restrictOwnAudio: enabled });
  } catch (err) {
    console.error('Einschränkung konnte nicht angewendet werden:', err.name);
  }
  // Tatsächlich aktiven Wert auslesen
  return track.getSettings().restrictOwnAudio;
};

// Nutzung, z. B. in einer Konferenz-App:
// const [track] = stream.getAudioTracks();
// console.log(await toggleOwnAudioFilter(track, false));

false

Fallback bei fehlender Unterstützung

const captureWithoutEcho = async () => {
  const { restrictOwnAudio, suppressLocalAudioPlayback } =
    navigator.mediaDevices.getSupportedConstraints();

  const audio = {};
  if (restrictOwnAudio) audio.restrictOwnAudio = true;
  else if (suppressLocalAudioPlayback) audio.suppressLocalAudioPlayback = true;

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

  const [track] = stream.getAudioTracks();
  console.log(track?.getSettings());
  return stream;
};

{ deviceId: "…", restrictOwnAudio: true, … }

// Wichtig · Fallstricke

Experimentell: Bisher unterstützen nur neuere Chromium-Browser die Eigenschaft. Firefox und Safari kennen sie derzeit nicht. Prüfe die Unterstützung daher immer mit getSupportedConstraints().
Die Eigenschaft wirkt nur bei Audiospuren aus getDisplayMedia(), nicht bei Mikrofonspuren aus getUserMedia(). Bei Mikrofonen verhindert man Echos mit echoCancellation.
Nicht verwechseln mit suppressLocalAudioPlayback: Diese Einschränkung unterdrückt die lokale Wiedergabe des aufgenommenen Tabs. restrictOwnAudio dagegen entfernt den Ton des aufnehmenden Tabs aus der Aufnahme.
Ob überhaupt eine Audiospur entsteht, entscheidet der Nutzer im Auswahldialog. Je nach Betriebssystem und gewählter Quelle (Tab, Fenster oder ganzer Bildschirm) gibt es eventuell gar keinen Ton. getAudioTracks() kann also ein leeres Array liefern.
getDisplayMedia() braucht einen sicheren Kontext (HTTPS) und eine Nutzeraktion, zum Beispiel einen Klick.

Siehe auch

MediaTrackSettings.aspectRatio MediaTrackSettings.deviceId MediaTrackSettings.groupId MediaTrackSettings.screenPixelRatio MediaTrackSettings.autoGainControl