MediaTrackSupportedConstraints.restrictOwnAudio — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSupportedConstraints.restrictOwnAudio

Beschreibung

Die Eigenschaft restrictOwnAudio gehört zum Verzeichnis MediaTrackSupportedConstraints. Dieses Objekt bekommen Sie von navigator.mediaDevices.getSupportedConstraints(). Die Eigenschaft ist nur vorhanden, wenn der Browser die gleichnamige Constraint versteht. In diesem Fall hat sie immer den Wert true. Unterstützt der Browser die Constraint nicht, fehlt die Eigenschaft, und eine Abfrage liefert undefined.

Die Constraint restrictOwnAudio wird bei navigator.mediaDevices.getDisplayMedia() für den Audio-Track verwendet. Mit true bittet die Anwendung den Browser, aus dem aufgenommenen Ton alles herauszufiltern, was das aufnehmende Dokument selbst abspielt. Das gilt zum Beispiel für die Audioausgabe des eigenen Tabs, wenn der ganze Bildschirm oder das System-Audio aufgenommen wird. So vermeiden Sie Echos und Rückkopplungen, etwa wenn eine Videokonferenz-App ihren Bildschirm teilt und dabei die Stimmen der anderen Teilnehmenden wieder an sie zurückschicken würde.

Prüfen Sie diese Eigenschaft, bevor Sie die Constraint setzen. Dann wissen Sie, ob der Browser sie beachtet oder unbekannterweise einfach ignoriert. So können Sie bei Bedarf eine Alternative anbieten, etwa einen Hinweis an die Nutzenden oder das Aufnehmen ohne System-Audio.

Rückgabewert

Typ

boolean | undefined

Beschreibung

true, wenn der Browser die Constraint restrictOwnAudio unterstützt. Ohne Unterstützung fehlt die Eigenschaft, und der Wert ist undefined. false kommt nicht vor.

Beispiele

Unterstützung prüfen

const supported = navigator.mediaDevices.getSupportedConstraints();

if (supported.restrictOwnAudio) {
  console.log('restrictOwnAudio wird unterstützt.');
} else {
  console.log('restrictOwnAudio wird NICHT unterstützt.');
}

restrictOwnAudio wird unterstützt. // bzw. „NICHT unterstützt“ in anderen Browsern

Bildschirm teilen ohne eigene Audioausgabe (z. B. Videokonferenz)

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

  const audioConstraints = supported.restrictOwnAudio
    ? { restrictOwnAudio: true }
    : true; // Alternative: normales Audio, Echo möglich

  try {
    const stream = await navigator.mediaDevices.getDisplayMedia({
      video: true,
      audio: audioConstraints
    });
    document.querySelector('video#preview').srcObject = stream;
    return stream;
  } catch (err) {
    console.error('Bildschirmfreigabe fehlgeschlagen:', err.name);
  }
};

// Muss aus einer Nutzerinteraktion heraus aufgerufen werden
document.querySelector('#share').addEventListener('click', startScreenShare);

Tatsächlich angewendete Einstellung auslesen

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

  const [audioTrack] = stream.getAudioTracks();
  if (!audioTrack) {
    console.log('Kein Audio-Track freigegeben.');
    return;
  }

  const { restrictOwnAudio } = audioTrack.getSettings();
  console.log('restrictOwnAudio aktiv:', restrictOwnAudio);
};

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

restrictOwnAudio aktiv: true

// Wichtig · Fallstricke

Experimentell: Derzeit gibt es die Eigenschaft nur in neueren Chromium-basierten Browsern. Firefox und Safari kennen sie nicht. Prüfen Sie deshalb immer mit getSupportedConstraints(), ob sie unterstützt wird.
Die Eigenschaft sagt nur, ob der Browser die Constraint kennt. Ob sie beim aufgenommenen Stream wirklich wirkt, sehen Sie erst mit MediaStreamTrack.getSettings().
Die Constraint wirkt nur bei Audio aus getDisplayMedia(), also Tab-, Fenster- oder System-Audio. Bei getUserMedia() für Mikrofone hat sie keine Bedeutung. Gegen Mikrofon-Echo gibt es stattdessen echoCancellation.
Die Nutzenden entscheiden im Freigabedialog selbst, ob sie überhaupt Audio teilen. Der Audio-Track kann also fehlen, auch wenn Sie audio anfordern.
getDisplayMedia() braucht einen sicheren Kontext (HTTPS) und eine vorherige Nutzerinteraktion.
Nicht verwechseln mit suppressLocalAudioPlayback: Diese Constraint schaltet nur die lokale Wiedergabe des aufgenommenen Tabs stumm, verändert aber nicht den aufgenommenen Ton.

Siehe auch

MediaTrackConstraints.restrictOwnAudio MediaTrackSupportedConstraints.aspectRatio MediaTrackSupportedConstraints.deviceId MediaTrackSupportedConstraints.groupId MediaTrackSupportedConstraints.autoGainControl