Verwendung der Screen Capture API

Bildschirminhalt erfassen

Das Erfassen von Bildschirminhalt als Live-MediaStream wird durch Aufrufen von navigator.mediaDevices.getDisplayMedia() initiiert, was ein Versprechen zurckgibt, das zu einem Stream mit dem Live-Bildschirminhalt aufgelst wird. Das Objekt displayMediaOptions, das in den folgenden Beispielen referenziert wird, knnte folgendermaen aussehen:

const displayMediaOptions = {
  video: {
    displaySurface: "browser",
  },
  audio: {
    suppressLocalAudioPlayback: false,
  },
  preferCurrentTab: false,
  selfBrowserSurface: "exclude",
  systemAudio: "include",
  surfaceSwitching: "include",
  monitorTypeSurfaces: "include",
};

Bildschirmaufnahme starten: async/await-Stil

async function startCapture(displayMediaOptions) {
  let captureStream = null;

  try {
    captureStream =
      await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
  } catch (err) {
    console.error(`Error: ${err}`);
  }
  return captureStream;
}

Sie knnen diesen Code entweder unter Verwendung einer asynchronen Funktion und des await-Operators schreiben, wie oben gezeigt, oder das Promise direkt verwenden, wie unten gezeigt.

Bildschirmaufnahme starten: Promise-Stil

function startCapture(displayMediaOptions) {
  return navigator.mediaDevices
    .getDisplayMedia(displayMediaOptions)
    .catch((err) => {
      console.error(err);
      return null;
    });
}

In beiden Fllen reagiert der User Agent, indem er eine Benutzeroberflche prsentiert, die den Benutzer dazu auffordert, den zu teilenden Bildschirmbereich auszuwhlen. Beide Implementierungen von startCapture() geben den MediaStream zurck, der die aufgenommenen Display-Bilder enthlt.

Weitere Informationen darber, wie Sie den gewnschten Oberflchentyp angeben, sowie andere Mglichkeiten zum Anpassen des resultierenden Streams, finden Sie im Abschnitt Optionen und Einschrnkungen weiter unten.

Beispiel fr ein Fenster, das es dem Benutzer ermglicht, eine Display-Oberflche zur Aufnahme auszuwhlen

[Screenshot von Chromes Fenster zur Auswahl einer Quellenoberflche]

Sie knnen dann den aufgenommenen Stream, captureStream, fr alles verwenden, das einen Stream als Eingabe akzeptiert. Die Beispiele weiter unten zeigen einige Mglichkeiten zur Nutzung des Streams.

Sichtbare vs. logische Anzeigeoberflchen

Im Kontext der Screen Capture API ist eine Anzeigeoberflche jedes Inhaltsobjekt, das von der API fr Freigabezwecke ausgewhlt werden kann. Freigegebene Oberflchen umfassen den Inhalt eines Browser-Tabs, ein komplettes Fenster und einen Monitor (oder eine Gruppe von Monitoren, die zu einer Oberflche zusammengefasst sind).

Es gibt zwei Arten von Anzeigeoberflchen. Eine sichtbare Anzeigeoberflche ist eine Oberflche, die vollstndig auf dem Bildschirm sichtbar ist, wie zum Beispiel das vorderste Fenster oder der vorderste Tab, oder der gesamte Bildschirm.

Eine logische Anzeigeoberflche ist eine, die teilweise oder vollstndig verdeckt ist, entweder indem sie in gewissem Umfang von einem anderen Objekt berlappt wird oder vollstndig verdeckt oder auerhalb des Bildschirms liegt. Wie diese von der Screen Capture API behandelt werden, variiert. Im Allgemeinen liefert der Browser ein Bild, das den versteckten Teil der logischen Anzeigeoberflche in irgendeiner Weise verschleiert, etwa durch Unschrfe oder Ersetzung mit einer Farbe oder einem Muster. Dies geschieht aus Sicherheitsgrnden, da der Inhalt, der vom Benutzer nicht gesehen werden kann, Daten enthalten kann, die er nicht teilen mchte.

Ein User Agent knnte die Erfassung des vollstndigen Inhalts eines verdeckten Fensters erlauben, nachdem er die Erlaubnis des Benutzers dazu erhalten hat. In diesem Fall kann der User Agent den verdeckten Inhalt einbeziehen, entweder indem er den aktuellen Inhalt des verdeckten Teils des Fensters erhlt oder indem er den zuletzt sichtbaren Inhalt darstellt, falls der aktuelle Inhalt nicht verfgbar ist.

Optionen und Einschrnkungen

Das in getDisplayMedia() bergebene Optionsobjekt wird verwendet, um Optionen fr den resultierenden Stream festzulegen.

Die in das Optionsobjekt bergebenen video- und audio-Objekte knnen auch zustzliche Einschrnkungen enthalten, die spezifisch fr diese Medientracks sind. Weitere Einzelheiten ber zustzliche Einschrnkungen zur Konfiguration eines Bildschirmaufnahme-Streams, die den MediaTrackConstraints, MediaTrackSupportedConstraints und MediaTrackSettings hinzugefgt werden, finden Sie unter Eigenschaften von freigegebenen Bildschirm-Tracks.

Keine der Einschrnkungen wird in irgendeiner Weise angewendet, bis der einzufangende Inhalt ausgewhlt wurde. Die Einschrnkungen verndern, was Sie in dem resultierenden Stream sehen. Wenn Sie beispielsweise eine width-Einschrnkung fr das Video angeben, wird sie angewendet, indem das Video skaliert wird, nachdem der Benutzer den zu teilenden Bereich ausgewhlt hat. Sie stellt keine Einschrnkung hinsichtlich der Gre der Quelle selbst dar.

Whrend die Bildschirmfreigabe aktiv ist, wird die Maschine, die Bildschirminhalt teilt, eine Art Indikator anzeigen, damit der Benutzer wei, dass gerade eine Freigabe stattfindet.

Aufnahme von geteiltem Audio

getDisplayMedia() wird am hufigsten verwendet, um Video vom Bildschirm eines Benutzers (oder Teilen davon) aufzunehmen. Allerdings knnen User Agents die Aufnahme von Audio zusammen mit dem Videoinhalt ermglichen. Die Quelle dieses Audios knnte das ausgewhlte Fenster, das gesamte Audiosystem des Computers oder das Mikrofon des Benutzers (oder eine Kombination all dieser) sein.

Bevor Sie ein Projekt starten, das die Freigabe von Audio erfordert, sollten Sie die Browser-Kompatibilitt fr getDisplayMedia() berprfen, um sicherzustellen, ob die von Ihnen gewnschten Browser Untersttzung fr Audio in aufgenommenen Bildschirmstreams haben.

Um zu verlangen, dass der Bildschirm mit Audio geteilt wird, knnten die in getDisplayMedia() bergebenen Optionen folgendermaen aussehen:

const displayMediaOptions = {
  video: true,
  audio: true,
};

Damit wird dem Benutzer vllige Freiheit eingerumt, auszuwhlen, was er innerhalb der Mglichkeiten, die der User Agent untersttzt, mchte. Dies knnte weiter verfeinert werden, indem zustzliche Optionen und Einschrnkungen innerhalb der audio- und video-Objekte spezifiziert werden:

const displayMediaOptions = {
  video: {
    displaySurface: "window",
  },
  audio: {
    echoCancellation: true,
    noiseSuppression: true,
    sampleRate: 44100,
    suppressLocalAudioPlayback: true,
  },
  surfaceSwitching: "include",
  selfBrowserSurface: "exclude",
  systemAudio: "exclude",
};

In diesem Beispiel soll die aufgenommene Anzeigeoberflche das gesamte Fenster sein. Der Audiotrack sollte idealerweise ber Rauschunterdrckungs- und Echounterdrckungsfunktionen verfgen sowie ber eine ideale Audio-Abtastrate von 44,1 kHz und die Unterdrckung der lokalen Audio-Wiedergabe.

Darber hinaus gibt die App dem User Agent einen Hinweis darauf, dass er:

• Ein Kontrollfeld whrend der Bildschirmfreigabe bereitstellen sollte, das es dem Benutzer erlaubt, den freigegebenen Tab dynamisch zu wechseln.
• Den aktuellen Tab aus der Liste der dem Benutzer bei der Anforderungsaufforderung prsentierten Optionen auszublenden.
• Das Systemaudio nicht zu den vom Benutzer angebotenen mglichen Audioquellen hinzuzufgen.

Die Aufnahme von Audio ist immer optional, und selbst wenn Webinhalte einen Stream mit sowohl Audio als auch Video anfordern, kann der zurckgegebene MediaStream immer noch nur einen Videotrack enthalten, ohne Audio.

Verwendung des aufgenommenen Streams

Das von getDisplayMedia() zurckgegebene Promise wird zu einem MediaStream aufgelst, das mindestens einen Videostream enthlt, das den Bildschirm oder Bildschirmbereich enthlt, und das basierend auf den bei der Aufrufung von getDisplayMedia() spezifizierten Einschrnkungen angepasst oder gefiltert wurde.

Potenzielle Risiken

Datenschutz- und Sicherheitsprobleme im Zusammenhang mit Bildschirmfreigabe sind in der Regel nicht bermig ernst, aber sie existieren. Das grte potenzielle Problem besteht darin, dass Benutzer Inhalte versehentlich teilen, die sie nicht teilen wollten.

Zum Beispiel knnen Datenschutz- und/oder Sicherheitsverletzungen leicht auftreten, wenn der Benutzer seinen Bildschirm teilt und ein sichtbares Hintergrundfenster persnliche Informationen enthlt oder wenn ihr Passwortmanager im geteilten Stream sichtbar ist. Dieser Effekt kann verstrkt werden, wenn logische Anzeigeoberflchen aufgenommen werden, die Inhalte enthalten knnen, die der Benutzer berhaupt nicht kennt, geschweige denn sieht.

User Agents, die den Datenschutz ernst nehmen, sollten Inhalte verschleiern, die tatschlich nicht auf dem Bildschirm sichtbar sind, es sei denn, es wurde eine Berechtigung gegeben, diesen Inhalt spezifisch zu teilen.

Autorisierung der Aufnahme von Anzeigeinhalten

Bevor das Streaming von aufgenommenen Bildschirminhalten beginnen kann, wird der User Agent den Benutzer bitten, die Freigabeanforderung zu besttigen und den zu teilenden Inhalt auszuwhlen.

Beispiele

Bildschirmaufnahme-Streaming

In diesem Beispiel werden die Inhalte des aufgenommenen Bildschirmbereichs in einem <video>-Element auf derselben Seite gestreamt.

JavaScript

Es ist nicht allzu viel Code erforderlich, um dies zum Laufen zu bringen, und wenn Sie vertraut mit der Verwendung von getUserMedia() zur Videoaufnahme von einer Kamera sind, wird Ihnen getDisplayMedia() sehr vertraut erscheinen.

Einrichtung

Zuerst werden einige Konstanten eingerichtet, um auf die Seitenelemente zu verweisen, auf die wir Zugriff bentigen: das <video>, in das der aufgenommene Bildschirminhalt gestreamt wird, eine Box, in der geloggte Ausgaben gezeichnet werden, und die Start- und Stopp-Tasten, die die Aufnahme von Bildschirmbildern ein- und ausschalten.

Das Objekt displayMediaOptions enthlt die Optionen, die in getDisplayMedia() bergeben werden; hier wird die Eigenschaft displaySurface auf window gesetzt, was angibt, dass das gesamte Fenster aufgenommen werden soll.

Schlielich werden Ereignis-Listener eingerichtet, um Benutzerklicks auf die Start- und Stopp-Tasten zu erkennen.

const videoElem = document.getElementById("video");
const logElem = document.getElementById("log");
const startElem = document.getElementById("start");
const stopElem = document.getElementById("stop");

// Options for getDisplayMedia()

const displayMediaOptions = {
  video: {
    displaySurface: "window",
  },
  audio: false,
};

// Set event listeners for the start and stop buttons
startElem.addEventListener("click", (evt) => {
  startCapture();
});

stopElem.addEventListener("click", (evt) => {
  stopCapture();
});

Inhalte loggen

In diesem Beispiel werden bestimmte Methoden der console berschrieben, um ihre Nachrichten an den <pre>-Block auszugeben, dessen ID log ist.

console.log = (msg) => (logElem.textContent = `${logElem.textContent}\n${msg}`);
console.error = (msg) =>
  (logElem.textContent = `${logElem.textContent}\nError: ${msg}`);

Dadurch knnen wir console.log() und console.error() verwenden, um Informationen in das Logbuch im Dokument zu schreiben.

Bildschirmaufnahme starten

Die Methode startCapture(), unten, startet die Aufnahme eines MediaStream, dessen Inhalte aus einem vom Benutzer ausgewhlten Bereich des Bildschirms stammen. startCapture() wird aufgerufen, wenn die Schaltflche "Start Capture" geklickt wird.

async function startCapture() {
  logElem.textContent = "";

  try {
    videoElem.srcObject =
      await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
    dumpOptionsInfo();
  } catch (err) {
    console.error(err);
  }
}

Nachdem die Inhalte des Logs geleert wurden, um alle verbleibenden Texte vom vorherigen Verbindungsversuch zu entfernen, ruft startCapture() getDisplayMedia() auf und bergibt das durch displayMediaOptions definierte Einschrnkungsobjekt. Durch die Nutzung von await wird die folgende Zeile des Codes erst ausgefhrt, nachdem das von getDisplayMedia() zurckgegebene Promise aufgelst wurde. Bei Auflsung gibt das Versprechen einen MediaStream zurck, der den Inhalt des Bildschirms, Fensters oder eines anderen vom Benutzer ausgewhlten Bereichs streamt.

Der Stream wird mit dem <video>-Element verbunden, indem der zurckgegebene MediaStream im srcObject des Elements gespeichert wird.

Die Funktion dumpOptionsInfo(), die wir gleich betrachten werden, gibt Informationen ber den Stream in das Logbuch aus, zu Lernzwecken.

Sollte dies fehlschlagen, gibt der catch()-Abschnitt eine Fehlermeldung in das Logbuch aus.

Bildschirmaufnahme stoppen

Die Methode stopCapture() wird aufgerufen, wenn die Schaltflche "Stop Capture" geklickt wird. Sie stoppt den Stream, indem sie seine Trackliste mit MediaStream.getTracks() abruft und dann die stop()-Methode jedes Tracks aufruft. Sobald das erledigt ist, wird srcObject auf null gesetzt, um sicherzustellen, dass jeder, der interessiert ist, versteht, dass kein Stream verbunden ist.

function stopCapture(evt) {
  let tracks = videoElem.srcObject.getTracks();

  tracks.forEach((track) => track.stop());
  videoElem.srcObject = null;
}

Konfigurationsinformationen ausgeben

Aus Informationsgrnden ruft die oben gezeigte Methode startCapture() eine Methode namens dumpOptions() auf, die die aktuellen Track-Einstellungen sowie die beim Erstellen des Streams festgelegten Einschrnkungen ausgibt.

function dumpOptionsInfo() {
  const videoTrack = videoElem.srcObject.getVideoTracks()[0];

  console.log("Track settings:");
  console.log(JSON.stringify(videoTrack.getSettings(), null, 2));
  console.log("Track constraints:");
  console.log(JSON.stringify(videoTrack.getConstraints(), null, 2));
}

Die Trackliste wird durch Aufruf von getVideoTracks() auf dem aufgenommenen Bildschirm-MediaStream(/de/docs/Web/API/MediaStream) erhalten. Die aktuell wirksamen Einstellungen werden mit getSettings() und die festgelegten Einschrnkungen mit getConstraints() abgerufen.

HTML

Das HTML beginnt mit einem einfhrenden Absatz und geht dann ins Eingemachte.

<p>
  This example shows you the contents of the selected part of your display.
  Click the Start Capture button to begin.
</p>

<p>
  <button id="start">Start Capture</button>&nbsp;<button id="stop">
    Stop Capture
  </button>
</p>

<video id="video" autoplay></video>
<br />

<strong>Log:</strong>
<br />
<pre id="log"></pre>

Die Schlsselteile des HTML sind:

1. Ein <button> mit der Beschriftung "Start Capture", der beim Klicken die Funktion startCapture() aufruft, um auf die Bildschirminhalte zuzugreifen und deren Aufnahme zu beginnen.
2. Ein zweiter Button, "Stop Capture", der beim Klicken stopCapture() aufruft, um die Aufnahme der Bildschirminhalte zu beenden.
3. Ein <video>, in das die aufgenommenen Bildschirminhalte gestreamt werden.
4. Ein <pre>-Block, in den durch die abgefangene console-Methode Protokolltexte eingefgt werden.

CSS

Das CSS ist in diesem Beispiel rein kosmetisch. Das Video erhlt einen Rahmen und seine Breite wird so eingestellt, dass es fast die gesamte verfgbare horizontale Flche einnimmt (width: 98%). max-width wird auf 860px gesetzt, um eine absolute Obergrenze fr die Gre des Videos festzulegen.

#video {
  border: 1px solid #999999;
  width: 98%;
  max-width: 860px;
}

#log {
  width: 25rem;
  height: 15rem;
  border: 1px solid black;
  padding: 0.5rem;
  overflow: scroll;
}

Ergebnis

Das Endprodukt sieht folgendermaen aus. Wenn Ihr Browser die Screen Capture API untersttzt, wird beim Klicken auf "Start Capture" die Benutzeroberflche des User Agent zur Auswahl eines zu teilenden Bildschirms, Fensters oder Tabs prsentiert.

Sicherheit

Um zu funktionieren, wenn die Permissions Policy aktiviert ist, bentigen Sie die Berechtigung display-capture. Dies kann durch die Verwendung des Permissions-Policy HTTP-Headers oder - wenn Sie die Screen Capture API in einem <iframe> verwenden - mit dem <iframe>-Elementattribut allow vorgenommen werden.

Beispielsweise aktiviert diese Zeile in den HTTP-Headern die Screen Capture API fr das Dokument und eingebettete <iframe>-Elemente, die von derselben Quelle geladen werden:

Permissions-Policy: display-capture=(self)

Wenn Sie Bildschirmaufnahme innerhalb eines <iframe> durchfhren, knnen Sie die Berechtigung nur fr diesen Rahmen anfordern, was klarerweise sicherer ist, als die Berechtigung allgemeiner anzufordern:

<iframe src="https://mycode.example.net/etc" allow="display-capture"> </iframe>

Browser-Kompatibilitt

Siehe auch

• Screen Capture API
• Media Capture and Streams API
• Stillfotos mit WebRTC aufnehmen
• HTMLCanvasElement.captureStream(), um einen MediaStream mit dem Live-Inhalt eines <canvas> zu erhalten