Verwendung der Screen Capture API

Bildschirminhalte erfassen

Um Bildschirminhalte als Live-MediaStream zu erfassen, rufen Sie navigator.mediaDevices.getDisplayMedia() auf. Die Methode gibt ein Promise zurück, das mit einem Stream der aktuellen Bildschirminhalte erfüllt wird. Das in den folgenden Beispielen verwendete Objekt displayMediaOptions könnte etwa so aussehen:

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

Bildschirmerfassung starten: mit async/await

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

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

Sie können diesen Code wie oben gezeigt mit einer asynchronen Funktion und dem Operator await schreiben oder das Promise direkt verwenden, wie im folgenden Beispiel.

Bildschirmerfassung starten: mit Promise

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

In beiden Fällen zeigt der User Agent eine Benutzeroberfläche an, auf der die Person den freizugebenden Bildschirmbereich auswählen kann. Beide Implementierungen von startCapture() geben den MediaStream mit den erfassten Bildschirminhalten zurück.

Unter Optionen und Einschränkungen erfahren Sie, wie Sie die gewünschte Art der Anzeigefläche festlegen und den resultierenden Stream anderweitig anpassen können.

Beispiel eines Fensters zur Auswahl einer Anzeigefläche für die Erfassung

Anschließend können Sie den erfassten Stream captureStream überall dort verwenden, wo ein Stream als Eingabe akzeptiert wird. Die folgenden Beispiele zeigen einige Möglichkeiten dafür.

Sichtbare und logische Anzeigeflächen

Für die Screen Capture API ist eine Anzeigefläche jedes Inhaltsobjekt, das über die API zur Freigabe ausgewählt werden kann. Dazu gehören der Inhalt eines Browser-Tabs, eines vollständigen Fensters oder eines Monitors (beziehungsweise mehrerer Monitore, die zu einer Fläche zusammengefasst sind).

Es gibt zwei Arten von Anzeigeflächen. Eine sichtbare Anzeigefläche ist vollständig auf dem Bildschirm zu sehen, etwa das vorderste Fenster oder Tab oder der gesamte Bildschirm.

Eine logische Anzeigefläche ist teilweise oder vollständig verdeckt: Sie wird beispielsweise von einem anderen Objekt überlagert, ist ganz ausgeblendet oder befindet sich außerhalb des sichtbaren Bildschirmbereichs. Wie die Screen Capture API damit umgeht, ist unterschiedlich. Im Allgemeinen stellt der Browser ein Bild bereit, in dem der verborgene Teil der logischen Anzeigefläche auf irgendeine Weise unkenntlich gemacht wird, etwa durch Weichzeichnen oder durch Ersetzen mit einer Farbe oder einem Muster. Dies geschieht aus Sicherheitsgründen, da für die Person nicht sichtbare Inhalte Daten enthalten können, die sie nicht teilen möchte.

Ein User Agent kann die Erfassung des gesamten Inhalts eines verdeckten Fensters ermöglichen, nachdem die Person dies genehmigt hat. In diesem Fall kann er den verdeckten Inhalt einbeziehen, indem er den aktuellen Inhalt des verborgenen Fensterbereichs erfasst oder, falls dieser nicht verfügbar ist, den zuletzt sichtbaren Inhalt zeigt.

Optionen und Einschränkungen

Mit dem an getDisplayMedia() übergebenen Optionsobjekt legen Sie Optionen für den resultierenden Stream fest.

Die Objekte video und audio im Optionsobjekt können außerdem zusätzliche, für die jeweiligen Medientracks geltende Einschränkungen enthalten. Unter Eigenschaften freigegebener Bildschirmtracks finden Sie Einzelheiten zu zusätzlichen Einschränkungen für die Konfiguration eines Bildschirmerfassungsstreams, die zu MediaTrackConstraints hinzugefügt werden, sowie zu den von MediaDevices.getSupportedConstraints() zurückgegebenen unterstützten Einschränkungen und zu MediaTrackSettings).

Die Einschränkungen werden erst angewendet, nachdem der zu erfassende Inhalt ausgewählt wurde. Sie verändern die Darstellung im resultierenden Stream. Wenn Sie beispielsweise für das Video eine Einschränkung für width angeben, wird das Video skaliert, nachdem die Person den freizugebenden Bereich ausgewählt hat. Die Größe der Quelle selbst wird dadurch nicht beschränkt.

Solange Bildschirminhalte erfasst und geteilt werden, zeigt das betreffende Gerät einen Hinweis an, damit die Person weiß, dass die Freigabe aktiv ist.

Freigegebenes Audio erfassen

getDisplayMedia() wird meist verwendet, um den Bildschirm einer Person oder Teile davon als Video zu erfassen. User Agents können jedoch auch die Erfassung von Audio zusammen mit dem Videoinhalt ermöglichen. Dieses Audio kann aus dem ausgewählten Fenster, dem gesamten Audiosystem des Computers oder dem Mikrofon der Person stammen – oder aus einer Kombination dieser Quellen.

Wenn für Ihr Projekt auch Audio geteilt werden muss, prüfen Sie vorab die Browser-Kompatibilität von getDisplayMedia(). So können Sie feststellen, ob die gewünschten Browser Audio in erfassten Bildschirmstreams unterstützen.

Um den Bildschirm einschließlich Audio freizugeben, könnten Sie die folgenden Optionen an getDisplayMedia() übergeben:

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

Damit kann die Person innerhalb der vom User Agent unterstützten Möglichkeiten frei auswählen, was sie teilen möchte. Durch zusätzliche Optionen und Einschränkungen in den Objekten audio und video lässt sich dies weiter anpassen:

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

In diesem Beispiel soll das gesamte Fenster als Anzeigefläche erfasst werden. Für den Audiotrack sollen nach Möglichkeit Rauschunterdrückung und Echounterdrückung aktiviert werden. Außerdem werden eine ideale Audio-Abtastrate von 44,1 kHz und die Unterdrückung der lokalen Audiowiedergabe angegeben.

Darüber hinaus gibt die Anwendung dem User Agent folgende Hinweise:

• Während der Bildschirmfreigabe soll eine Steuerung angeboten werden, mit der die Person dynamisch zu einem anderen freigegebenen Tab wechseln kann.
• Das aktuelle Tab soll nicht in der Auswahlliste erscheinen, die beim Anfordern der Erfassung angezeigt wird.
• Systemaudio soll nicht zu den angebotenen Audioquellen gehören.

Die Erfassung von Audio ist immer optional. Selbst wenn Webinhalte einen Stream mit Audio und Video anfordern, kann der zurückgegebene MediaStream nur einen Videotrack und kein Audio enthalten.

Den erfassten Stream verwenden

Das von getDisplayMedia() zurückgegebene Promise wird mit einem MediaStream erfüllt. Dieser enthält mindestens einen Videostream mit dem Bildschirm oder Bildschirmbereich, dessen Inhalt entsprechend den beim Aufruf von getDisplayMedia() angegebenen Einschränkungen angepasst oder gefiltert wird.

Mögliche Risiken

Datenschutz- und Sicherheitsprobleme bei der Bildschirmfreigabe sind meist nicht besonders schwerwiegend, können aber auftreten. Das größte potenzielle Problem besteht darin, dass Personen versehentlich Inhalte teilen, die sie nicht freigeben wollten.

So kann es beispielsweise leicht zu Datenschutz- oder Sicherheitsverletzungen kommen, wenn während der Bildschirmfreigabe ein sichtbares Fenster im Hintergrund persönliche Informationen enthält oder ein Passwortmanager im geteilten Stream zu sehen ist. Bei der Erfassung logischer Anzeigeflächen kann dieses Problem noch größer sein, da diese Inhalte enthalten können, von denen die Person nichts weiß und die sie erst recht nicht sehen kann.

User Agents, die den Datenschutz ernst nehmen, sollten Inhalte unkenntlich machen, die auf dem Bildschirm nicht tatsächlich sichtbar sind – es sei denn, die Freigabe genau dieser Inhalte wurde genehmigt.

Erfassung von Bildschirminhalten genehmigen

Bevor die Übertragung erfasster Bildschirminhalte beginnen kann, fordert der User Agent die Person auf, die Freigabe zu bestätigen und den freizugebenden Inhalt auszuwählen.

Beispiele

Bildschirmerfassung streamen

In diesem Beispiel wird der Inhalt des erfassten Bildschirmbereichs in ein <video>-Element auf derselben Seite gestreamt.

JavaScript

Dafür ist nicht viel Code nötig. Wenn Sie bereits getUserMedia() verwendet haben, um Video von einer Kamera zu erfassen, wird Ihnen getDisplayMedia() vertraut vorkommen.

Einrichtung

Zunächst werden einige Konstanten für den Zugriff auf Seitenelemente festgelegt: das <video>-Element, in das die erfassten Bildschirminhalte gestreamt werden, ein Bereich für Protokollausgaben sowie die Schaltflächen zum Starten und Beenden der Bildschirmerfassung.

Das Objekt displayMediaOptions enthält die Optionen, die an getDisplayMedia() übergeben werden. Hier ist die Eigenschaft displaySurface auf window gesetzt. Dies gibt an, dass das gesamte Fenster erfasst werden soll.

Schließlich werden Event-Listener eingerichtet, die Klicks auf die Schaltflächen zum Starten und Beenden 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 protokollieren

Dieses Beispiel überschreibt bestimmte Methoden von console, damit ihre Meldungen im <pre>-Block mit der ID log ausgegeben werden.

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

So können Sie mit console.log() und console.error() Informationen im Protokollbereich des Dokuments ausgeben.

Bildschirmerfassung starten

Die folgende Methode startCapture() startet die Erfassung eines MediaStream, dessen Inhalt aus einem von der Person ausgewählten Bildschirmbereich stammt. startCapture() wird aufgerufen, wenn auf die Schaltfläche „Start Capture“ geklickt wird.

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

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

Nachdem startCapture() das Protokoll geleert und damit verbliebenen Text eines vorherigen Verbindungsversuchs entfernt hat, ruft die Methode getDisplayMedia() mit dem durch displayMediaOptions definierten Einschränkungsobjekt auf. Durch await wird die nächste Codezeile erst ausgeführt, wenn das von getDisplayMedia() zurückgegebene Promise erfüllt ist. Das Promise liefert dann einen MediaStream, der den Inhalt des von der Person ausgewählten Bildschirms, Fensters oder anderen Bereichs streamt.

Der Stream wird mit dem <video>-Element verbunden, indem der zurückgegebene MediaStream in dessen Eigenschaft srcObject gespeichert wird.

Die Funktion dumpOptionsInfo() – die wir uns gleich ansehen – gibt zu Demonstrationszwecken Informationen über den Stream im Protokollbereich aus.

Falls dabei ein Fehler auftritt, gibt die catch()-Klausel eine Fehlermeldung im Protokollbereich aus.

Bildschirmerfassung beenden

Die Methode stopCapture() wird aufgerufen, wenn auf die Schaltfläche „Stop Capture“ geklickt wird. Sie beendet den Stream, indem sie mit MediaStream.getTracks() dessen Trackliste abruft und für jeden Track die Methode stop() aufruft. Anschließend wird srcObject auf null gesetzt, damit erkennbar ist, dass kein Stream mehr verbunden ist.

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

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

Konfigurationsinformationen ausgeben

Zu Informationszwecken ruft die oben gezeigte Methode startCapture() eine Methode namens dumpOptions() auf. Diese gibt die aktuellen Trackeinstellungen und die Einschränkungen aus, die bei der Erstellung des Streams festgelegt wurden.

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 abgerufen, indem getVideoTracks() für den MediaStream des erfassten Bildschirms aufgerufen wird. Die aktuell wirksamen Einstellungen werden mit getSettings() und die festgelegten Einschränkungen mit getConstraints() abgerufen.

HTML

Der HTML-Code beginnt mit einem einleitenden Absatz, bevor die wesentlichen Elemente folgen.

<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 wichtigsten Bestandteile des HTML-Codes sind:

1. Ein <button> mit der Beschriftung „Start Capture“, der beim Anklicken die Funktion startCapture() aufruft, um Zugriff auf Bildschirminhalte anzufordern und deren Erfassung zu starten.
2. Eine zweite Schaltfläche mit der Beschriftung „Stop Capture“, die beim Anklicken stopCapture() aufruft, um die Erfassung zu beenden.
3. Ein <video>-Element, in das die erfassten Bildschirminhalte gestreamt werden.
4. Ein <pre>-Block, in den die überschriebene console-Methode protokollierten Text schreibt.

CSS

Das CSS dient in diesem Beispiel ausschließlich der Gestaltung. Das Video erhält einen Rahmen und seine Breite wird so festgelegt, dass es fast den gesamten verfügbaren horizontalen Platz einnimmt (width: 98%). max-width wird auf 860px gesetzt, um eine absolute Obergrenze für die Größe 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 Ergebnis sieht folgendermaßen aus. Wenn Ihr Browser die Screen Capture API unterstützt, öffnet ein Klick auf „Start Capture“ die Oberfläche des User Agents, auf der Sie einen Bildschirm, ein Fenster oder ein Tab zur Freigabe auswählen können.

Sicherheit

Damit die API bei aktivierter Permissions Policy funktioniert, benötigen Sie die Berechtigung display-capture. Sie können diese über den HTTP-Header Permissions-Policy erteilen oder – wenn Sie die Screen Capture API in einem <iframe> verwenden – über das Attribut allow des <iframe>-Elements.

Beispielsweise aktiviert die folgende Zeile in den HTTP-Headern die Screen Capture API für das Dokument und alle eingebetteten <iframe>-Elemente, die vom selben Ursprung geladen werden:

Permissions-Policy: display-capture=(self)

Wenn Sie die Bildschirmerfassung innerhalb eines <iframe> durchführen, können Sie die Berechtigung nur für diesen Frame anfordern. Das ist deutlich sicherer, als sie allgemeiner anzufordern:

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

Browser-Kompatibilität

Siehe auch

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