MediaTrackSettings.displaySurface — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSettings.displaySurface

Beschreibung

Die Eigenschaft displaySurface des Dictionaries MediaTrackSettings ist ein String. Er beschreibt, welche Art von Anzeigefläche ein Video-Track aus navigator.mediaDevices.getDisplayMedia() gerade aufnimmt. Den Wert liest man über MediaStreamTrack.getSettings() aus, nachdem die Nutzerin oder der Nutzer im Auswahldialog des Browsers eine Quelle gewählt hat.

Mögliche Werte:

"monitor": ein ganzer Bildschirm bzw. Monitor.
"window": ein einzelnes Anwendungsfenster.
"browser": ein Browser-Tab (Registerkarte).

Damit kann eine Anwendung auf die Wahl reagieren. Beispiele: Beim Teilen des ganzen Bildschirms wird vor versehentlich sichtbaren privaten Inhalten gewarnt. Nur bei einem geteilten Tab werden Tab-spezifische Funktionen wie Capture Handle oder Region Capture angeboten. Oder man passt Auflösung und Bildrate an die Quelle an.

Welche Quelle der Dialog vorschlägt, lässt sich über die Constraint displaySurface in getDisplayMedia() nur beeinflussen, nicht erzwingen. Die endgültige Entscheidung trifft immer der Mensch vor dem Bildschirm. Deshalb sollte man nach dem Start immer den tatsächlichen Wert aus getSettings() prüfen.

Rückgabewert

Typ

"monitor" | "window" | "browser" | undefined

Beschreibung

Der Typ der erfassten Anzeigefläche. Der Wert ist undefined, wenn der Track keine Bildschirmaufnahme ist (z. B. eine Kamera) oder der Browser die Eigenschaft nicht unterstützt.

Beispiele

Erfasste Anzeigefläche nach dem Teilen auslesen

const startShare = async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
  const [track] = stream.getVideoTracks();
  const { displaySurface } = track.getSettings();
  console.log(`Geteilte Fläche: ${displaySurface}`);
  return stream;
};

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

Geteilte Fläche: browser

Warnung beim Teilen des ganzen Bildschirms

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

  switch (track.getSettings().displaySurface) {
    case 'monitor':
      alert('Achtung: Ihr gesamter Bildschirm ist sichtbar – inklusive Benachrichtigungen.');
      break;
    case 'window':
      console.log('Ein einzelnes Fenster wird geteilt.');
      break;
    case 'browser':
      console.log('Ein Browser-Tab wird geteilt.');
      break;
    default:
      console.log('Anzeigefläche unbekannt oder nicht unterstützt.');
  }
  return stream;
};

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

Ein Browser-Tab wird geteilt.

Tab im Auswahldialog bevorzugen und Ergebnis prüfen

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

  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: { displaySurface: 'browser' } // nur ein Hinweis an den Dialog
  });
  const [track] = stream.getVideoTracks();
  const actual = track.getSettings().displaySurface;

  if (actual !== 'browser') {
    console.log(`Gewünscht: browser, gewählt: ${actual}`);
  }
  return stream;
};

document.querySelector('#share-tab').addEventListener('click', shareTab);

Gewünscht: browser, gewählt: window

// Wichtig · Fallstricke

Nur bei Bildschirmaufnahmen: Die Eigenschaft ist nur bei Tracks aus getDisplayMedia() gesetzt. Bei Kamera-Tracks aus getUserMedia() ist sie undefined.
Keine Garantie: Die Constraint displaySurface in getDisplayMedia() legt nur fest, welche Option der Dialog vorab auswählt. Ob sie berücksichtigt wird, hängt vom Browser ab. Firefox und Safari ignorieren sie teilweise. Das tatsächliche Ergebnis immer über getSettings() prüfen.
Nutzeraktion und sicherer Kontext: getDisplayMedia() funktioniert nur über HTTPS (oder localhost) und in der Regel nur als Reaktion auf eine Nutzeraktion, etwa einen Klick. Mobile Browser unterstützen die Bildschirmaufnahme meist gar nicht.
Kompatibilität: Unterstützung vorab mit navigator.mediaDevices.getSupportedConstraints().displaySurface prüfen. Der Wert "application" aus früheren Spezifikationsentwürfen ist entfernt worden und kommt in modernen Browsern nicht mehr vor.
Datenschutz: Beim Teilen von "monitor" können sensible Inhalte sichtbar werden (Benachrichtigungen, andere Fenster). Darauf sollte man die Nutzer hinweisen.

Siehe auch

MediaStreamTrackProcessor.discardedFrames MediaTrackConstraints.displaySurface MediaTrackSettings.logicalSurface MediaTrackSettings.sampleRate MediaTrackSettings.frameRate