MediaTrackSettings.logicalSurface — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSettings.logicalSurface

Beschreibung

Die Eigenschaft logicalSurface des Wörterbuchs MediaTrackSettings zeigt an, ob die Quelle einer Bildschirmaufnahme eine logische Anzeigefläche ist. Den Wert erhält man über MediaStreamTrack.getSettings() für einen Videotrack, den navigator.mediaDevices.getDisplayMedia() geliefert hat. Bei Kamera- oder Mikrofontracks gibt es die Eigenschaft nicht.

Eine logische Oberfläche ist nicht unbedingt vollständig auf dem Bildschirm zu sehen. Sie kann teilweise oder ganz verdeckt sein oder außerhalb des sichtbaren Bereichs liegen. Typische Beispiele sind ein Browser-Tab oder ein Anwendungsfenster, dessen gesamter Inhalt aufgenommen wird, auch die verdeckten Teile. Eine sichtbare Oberfläche, etwa ein ganzer Monitor, liefert false. Dann enthält die Aufnahme genau das, was auf dem Bildschirm zu sehen ist, inklusive überlappender Fenster.

Nützlich ist der Wert, wenn eine Anwendung ihr Verhalten an die Art der Aufnahme anpassen will. Ein Beispiel ist der Hinweis an Nutzer, dass bei einer Monitorfreigabe auch darüberliegende Fenster (etwa Chat-Benachrichtigungen) zu sehen sind. Ein anderes ist die Optimierung von Auflösung oder Bildrate. Meist wird logicalSurface zusammen mit displaySurface ausgewertet.

Die Eigenschaft kann nur gelesen werden. Welche Oberfläche erfasst wird, entscheidet der Nutzer im Auswahldialog des Browsers. Deshalb lässt sich logicalSurface in den Constraints von getDisplayMedia() nicht erzwingen.

Rückgabewert

Typ

boolean | undefined

Beschreibung

true, wenn die erfasste Fläche eine logische Oberfläche ist (z. B. ein Tab oder ein Fenster, das teilweise nicht sichtbar ist). false bei einer sichtbaren Oberfläche wie einem ganzen Monitor. undefined, wenn der Browser die Eigenschaft nicht unterstützt oder der Track keine Bildschirmaufnahme ist.

Beispiele

logicalSurface einer Bildschirmfreigabe auslesen

const startCapture = async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
  const [track] = stream.getVideoTracks();
  const { logicalSurface, displaySurface } = track.getSettings();

  console.log('Oberflächentyp:', displaySurface);
  console.log('Logische Oberfläche:', logicalSurface);
  return stream;
};

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

Oberflächentyp: window Logische Oberfläche: true

Feature-Erkennung vor dem Auslesen

const supported = navigator.mediaDevices.getSupportedConstraints();

if (supported.logicalSurface) {
  console.log('logicalSurface wird unterstützt.');
} else {
  console.log('logicalSurface wird von diesem Browser nicht gemeldet.');
}

logicalSurface wird von diesem Browser nicht gemeldet.

Nutzer bei Monitorfreigabe warnen

const shareScreen = async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({ video: true, audio: false });
  const [track] = stream.getVideoTracks();
  const settings = track.getSettings();

  // false = sichtbare Fläche: überlappende Fenster werden mit aufgenommen
  if (settings.logicalSurface === false) {
    const hint = document.querySelector('#hint');
    hint.textContent = 'Achtung: Alle sichtbaren Fenster, auch Benachrichtigungen, werden geteilt.';
    hint.hidden = false;
  }

  document.querySelector('video').srcObject = stream;
  track.addEventListener('ended', () => console.log('Freigabe beendet'));
};

shareScreen().catch((err) => console.error('Freigabe abgebrochen:', err.name));

// Wichtig · Fallstricke

Browser-Unterstützung: Die Eigenschaft ist in der Screen Capture Spezifikation definiert, wird aber nur von wenigen Browsern tatsächlich gemeldet. Vorher mit navigator.mediaDevices.getSupportedConstraints().logicalSurface prüfen und undefined immer einplanen.
Der Wert steht nur bei Videotracks aus getDisplayMedia() zur Verfügung, nicht bei getUserMedia()-Tracks.
Auf den Wert vergleichen, statt ihn nur als wahr oder falsch zu prüfen: === false unterscheidet „sichtbare Oberfläche“ von „nicht unterstützt“ (undefined).
getDisplayMedia() funktioniert nur in einem sicheren Kontext (HTTPS) und nur nach einer Nutzeraktion wie einem Klick. Sonst wird das Promise mit einem Fehler abgelehnt, z. B. NotAllowedError oder InvalidStateError.
Datenschutz: Bei logicalSurface === false (ganzer Monitor) können sensible Inhalte anderer Fenster mit aufgenommen werden. Nutzer sollten darauf hingewiesen werden.

Siehe auch

MediaTrackConstraints.logicalSurface MediaTrackSettings.displaySurface MediaTrackSettings.frameRate MediaTrackSettings.sampleRate MediaTrackSettings.volume