MediaDevices: Methode getDisplayMedia()

options Optional

Ein optionales Objekt, das Anforderungen für den zurückgegebenen MediaStream spezifiziert. Die Optionen für getDisplayMedia() funktionieren ähnlich wie die Einschränkungen für die Methode MediaDevices.getUserMedia(), obwohl in diesem Fall nur audio und video angegeben werden können. Die Liste der möglichen Optionseigenschaften für getDisplayMedia() ist wie folgt:

video Optional

Ein Boolescher Wert oder eine Instanz von MediaTrackConstraints; der Standardwert ist true. Wird diese Option ausgelassen oder auf true gesetzt, enthält der Stream eine Videospur. Ein Wert von true gibt an, dass der zurückgegebene MediaStream eine Videospur enthält. Da getDisplayMedia() eine Videospur erfordert, wird das Versprechen abgelehnt, wenn diese Option auf false gesetzt ist, mit einem TypeError.

audio Optional

Ein Boolescher Wert oder eine Instanz von MediaTrackConstraints; der Standardwert ist false. Ein Wert von true gibt an, dass der zurückgegebene MediaStream eine Audiospur enthält, sofern Audio unterstützt wird und für die vom Benutzer gewählte Bildschirmoberfläche verfügbar ist.

controller Experimentell Optional

Eine CaptureController-Objektinstanz, die Methoden enthält, mit denen die Aufnahme weiter manipuliert werden kann, wenn sie enthalten ist.

monitorTypeSurfaces Experimentell Optional

Ein enumerierter Wert, der angibt, ob der Browser in den dem Benutzer präsentierten Bildschirmaufnahmeoptionen vollständige Bildschirme neben Registerkarten- und Fensteroptionen anbieten soll. Diese Option soll verhindern, dass Unternehmen durch Benutzerfehler beim Einsatz von Videokonferenz-Apps private Informationen leaken. Mögliche Werte sind include, was darauf hinweist, dass der Browser Bildschirmoptionen einschließen soll, und exclude, was darauf hinweist, dass sie ausgeschlossen werden sollen. Ein Standardwert wird von der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browserspezifische Standardeinstellungen.

Hinweis: Sie können nicht monitorTypeSurfaces: "exclude" gleichzeitig mit displaySurface: "monitor" einstellen, da die beiden Einstellungen widersprüchlich sind. Der Versuch, dies zu tun, führt dazu, dass der Aufruf von getDisplayMedia() mit einem TypeError fehlschlägt.

preferCurrentTab Nicht standardisiert Experimentell Optional

Ein Boolescher Wert; ein Wert von true gibt dem Browser an, die aktuelle Registerkarte als wichtigste Aufnahmequelle anzubieten, d.h. als separate "Diese Registerkarte"-Option in den dem Benutzer präsentierten "Wählen Sie, was Sie teilen möchten"-Optionen. Dies ist nützlich, da viele App-Typen im Allgemeinen nur die aktuelle Registerkarte teilen möchten. Beispielsweise könnte eine Präsentationsfolien-App dem Benutzer erlauben, die aktuelle Registerkarte mit der Präsentation an eine virtuelle Konferenz zu streamen. Ein Standardwert wird von der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browserspezifische Standardeinstellungen.

selfBrowserSurface Experimentell Optional

Ein enumerierter Wert, der angibt, ob der Browser dem Benutzer erlauben sollte, die aktuelle Registerkarte für die Aufnahme auszuwählen. Dies hilft, den "unendlichen Spiegelkabinett"-Effekt zu vermeiden, der entsteht, wenn eine Videokonferenz-App versehentlich ihren eigenen Bildschirm teilt. Mögliche Werte sind include, was darauf hinweist, dass der Browser die aktuelle Registerkarte in die zur Aufnahme angebotenen Optionen aufnehmen soll, und exclude, was darauf hinweist, dass sie ausgeschlossen werden soll. Ein Standardwert wird von der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browserspezifische Standardeinstellungen.

surfaceSwitching Experimentell Optional

Ein enumerierter Wert, der angibt, ob der Browser ein Steuerelement anzeigen soll, das dem Benutzer ermöglicht, die geteilte Registerkarte während des Bildschirmtrennens dynamisch zu wechseln. Dies ist viel bequemer, als jedes Mal den gesamten Freigabeprozess erneut durchlaufen zu müssen, wenn ein Benutzer die geteilte Registerkarte wechseln möchte. Mögliche Werte sind include, was darauf hinweist, dass der Browser das Steuerelement einschließen soll, und exclude, was darauf hinweist, dass es nicht gezeigt werden soll. Ein Standardwert wird von der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browserspezifische Standardeinstellungen.

systemAudio Experimentell Optional

Ein enumerierter Wert, der angibt, ob der Browser das Systemaudio unter den dem Benutzer angebotenen möglichen Audioquellen einschließen soll. Mögliche Werte sind include, was darauf hinweist, dass der Browser das Systemaudio in die Liste der Optionen aufnehmen soll, und exclude, was darauf hinweist, dass es ausgeschlossen werden soll. Ein Standardwert wird in der Spezifikation nicht vorgegeben; siehe den Abschnitt Browser-Kompatibilität für browserspezifische Standards.

Ein Promise, das zu einem MediaStream aufgelöst wird, der eine Videospur enthält, deren Inhalt von einem vom Benutzer ausgewählten Bildschirmbereich stammt, sowie optional eine Audiospur.

AbortError DOMException

Wird ausgelöst, wenn ein Fehler oder Ausfall keiner anderen hier aufgelisteten Ausnahme entspricht.

InvalidStateError DOMException

Wird ausgelöst, wenn der Aufruf von getDisplayMedia() nicht aus Code stammt, der aufgrund einer transient activation, wie einem Ereignis-Handler, ausgeführt wird. Oder wenn der Browser-Kontext nicht vollständig aktiv oder nicht fokussiert ist. Oder wenn die controller-Option bereits verwendet wurde, um einen anderen MediaStream zu erstellen.

NotAllowedError DOMException

Wird ausgelöst, wenn die Berechtigung zum Zugriff auf einen Bildschirmbereich vom Benutzer verweigert wurde oder die aktuelle Browsing-Instanz keinen Zugriff auf das Bildschirmteilen hat (z. B. durch eine Permissions Policy).

NotFoundError DOMException

Wird ausgelöst, wenn keine Quellen für Bildschirmvideo zur Aufnahme verfügbar sind.

NotReadableError DOMException

Wird ausgelöst, wenn der Benutzer einen Bildschirm, ein Fenster, eine Registerkarte oder eine andere Quelle von Bildschirmdaten ausgewählt hat, aber ein Hardware- oder Betriebssystemfehler oder eine Sperre aufgetreten ist, die die Freigabe der ausgewählten Quelle verhindert.

OverconstrainedError DOMException

Wird ausgelöst, wenn nach der Erstellung des Streams die Anwendung der angegebenen Einschränkungen fehlschlägt, weil kein kompatibler Stream generiert werden konnte.

TypeError

Wird ausgelöst, wenn die angegebenen options Werte enthalten, die beim Aufruf von getDisplayMedia() nicht erlaubt sind, z. B. eine video-Eigenschaft, die auf false gesetzt ist, oder wenn bestimmte MediaTrackConstraints nicht zulässig sind. min und exact Werte sind in Einschränkungen, die in getDisplayMedia()-Aufrufen verwendet werden, nicht erlaubt.

Da getDisplayMedia() in böswilliger Weise verwendet werden könnte, kann es eine Quelle erheblicher Datenschutz- und Sicherheitsbedenken sein. Aus diesem Grund beschreibt die Spezifikation die Maßnahmen, die Browser ergreifen müssen, um getDisplayMedia() vollständig zu unterstützen.

• Die angegebenen Optionen können nicht verwendet werden, um die dem Benutzer verfügbaren Auswahlmöglichkeiten zu beschränken. Stattdessen müssen sie angewendet werden, nachdem der Benutzer eine Quelle ausgewählt hat, um einen Output zu erzeugen, der den Optionen entspricht.
• Die Erlaubnis, getDisplayMedia() zu verwenden, kann nicht für eine spätere Verwendung gespeichert werden. Der Benutzer muss jedes Mal um eine Erlaubnis gebeten werden.
• Transiente Benutzeraktivierung ist erforderlich. Der Benutzer muss mit der Seite oder einem UI-Element interagieren, damit diese Funktion funktioniert.
• Browser werden ermutigt, den Benutzern eine Warnung über das Teilen von Bildschirmen oder Fenstern, die Browser enthalten, zu geben und genau darauf zu achten, welche anderen Inhalte möglicherweise erfasst und anderen Benutzern gezeigt werden könnten.

Im folgenden Beispiel wird eine startCapture()-Methode erstellt, die die Bildschirmaufnahme mit einer Reihe von durch den Parameter displayMediaOptions spezifizierten Optionen initiiert.

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

async function startCapture(displayMediaOptions) {
  let captureStream;

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

Dies verwendet await, um asynchron auf die Auflösung von getDisplayMedia() mit einem MediaStream zu warten, der den Displayinhalt enthält, wie durch die angegebenen Optionen angefordert. Der Stream wird dann an den Aufrufenden zurückgegeben, vielleicht zur Verwendung in einem WebRTC-Anruf, indem die Videospur des Streams mit RTCPeerConnection.addTrack() hinzugefügt wird.

• Screen Capture API
• Verwendung der Screen Capture API
• Media Capture and Streams API
• WebRTC API
• getUserMedia(): Erfassung von Medien von einer Kamera und/oder einem Mikrofon