MediaDevices: getDisplayMedia() Methode

options Optional

Ein optionales Objekt, das Anforderungen für den zurückgegebenen MediaStream angibt. 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 Options-Eigenschaften für getDisplayMedia() lautet wie folgt:

video Optional

Ein Boolean oder eine Instanz von MediaTrackConstraints; der Standardwert ist true. Wenn diese Option weggelassen oder auf true gesetzt wird, enthält der Stream einen Videotrack. Ein Wert von true zeigt an, dass der zurückgegebene MediaStream einen Videotrack enthalten wird. Da getDisplayMedia() einen Videotrack erfordert, schlägt die Promise fehl, wenn diese Option auf false gesetzt ist, und löst einen TypeError aus.

audio Optional

Ein Boolean oder eine Instanz von MediaTrackConstraints; der Standardwert ist false. Ein Wert von true zeigt an, dass der zurückgegebene MediaStream einen Audiotrack enthalten wird, wenn Audio unterstützt und für die vom Benutzer gewählte Bildschirmoberfläche verfügbar ist.

controller Experimentell Optional

Eine Instanz eines CaptureController-Objekts, das Methoden enthält, die zur weiteren Manipulation der Erfassungssitzung verwendet werden können, wenn sie enthalten ist.

monitorTypeSurfaces Optional

Ein enumerierter Wert, der angibt, ob der Browser in den dem Benutzer präsentierten Bildschirmaufnahmeoptionen vollständige Bildschirme zusammen mit Registerkarten- und Fensteroptionen anbieten sollte. Diese Option soll Unternehmen davor schützen, dass durch einen Mitarbeiterfehler in Videokonferenz-Apps private Informationen durchsickern. Mögliche Werte sind include, was darauf hindeutet, dass der Browser Bildschirmoptionen einschließen sollte, und exclude, was darauf hindeutet, dass sie ausgeschlossen werden sollten. Ein Standardwert ist in der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browser-spezifische Standardeinstellungen.

Hinweis: Sie können nicht monitorTypeSurfaces: "exclude" gleichzeitig mit displaySurface: "monitor" setzen, da die beiden Einstellungen widersprüchlich sind. Ein solcher Versuch führt dazu, dass der getDisplayMedia()-Aufruf mit einem TypeError fehlschlägt.

preferCurrentTab Nicht standardisiert Experimentell Optional

Ein Boolean; ein Wert von true weist den Browser an, die aktuelle Registerkarte als die hervorstechendste Erfassen-Quelle anzubieten, d.h. als separate "Diese Registerkarte"-Option in den "Wählen Sie aus, was Sie teilen möchten"-Optionen, die dem Benutzer präsentiert werden. Dies ist nützlich, da viele App-Typen normalerweise nur die aktuelle Registerkarte teilen möchten. Beispielsweise kann eine Folienpräsentation-App dem Benutzer erlauben, die aktuelle Registerkarte, die die Präsentation enthält, zu einem virtuellen Konferenz-Stream hinzuzufügen. Ein Standardwert ist in der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browser-spezifische Standardeinstellungen.

selfBrowserSurface Experimentell Optional

Ein enumerierter Wert, der angibt, ob der Browser dem Benutzer erlauben sollte, die aktuelle Registerkarte zur Erfassung auszuwählen. Dies hilft, den Effekt des "endlosen Spiegelkorridors" zu vermeiden, der auftritt, wenn eine Videokonferenz-App versehentlich ihre eigene Anzeige teilt. Mögliche Werte sind include, was darauf hindeutet, dass der Browser die aktuelle Registerkarte in den Auswahlmöglichkeiten für die Erfassung einschließen sollte, und exclude, was darauf hindeutet, dass sie ausgeschlossen werden sollte. Ein Standardwert ist in der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browser-spezifische Standardeinstellungen.

surfaceSwitching Experimentell Optional

Ein enumerierter Wert, der angibt, ob der Browser eine Steuerung anzeigen sollte, um dem Benutzer zu ermöglichen, während der Bildschirmfreigabe dynamisch die geteilte Registerkarte 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 hindeutet, dass der Browser die Steuerung einschließen sollte, und exclude, was darauf hindeutet, dass sie nicht angezeigt werden sollte. Ein Standardwert ist in der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browser-spezifische Standardeinstellungen.

systemAudio Experimentell Optional

Ein enumerierter Wert, der angibt, ob der Browser das Systemaudio zu den dem Benutzer angebotenen möglichen Audioquellen hinzufügen sollte. Mögliche Werte sind include, was darauf hindeutet, dass der Browser das Systemaudio in die Liste der Auswahlmöglichkeiten aufnehmen sollte, und exclude, was darauf hindeutet, dass es ausgeschlossen werden sollte. Ein Standardwert ist in der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browser-spezifische Standardeinstellungen.

monitorTypeSurfaces Experimentell Optional

Ein enumerierter Wert, der angibt, ob die Anwendung dem Benutzeragenten anbieten möchte, die Option für die Auswahl von Anzeigeflächen, deren Typ Monitor ist, zu präsentieren. Mögliche Werte sind include, was darauf hindeutet, dass der Browser die Anzeigeflächen, deren Typ Monitor ist, einbeziehen sollte, und exclude, was darauf hindeutet, dass es ausgeschlossen werden sollte. Ein Standardwert ist in der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browser-spezifische Standardeinstellungen.

Ein Promise, das sich zu einem MediaStream auflöst, der eine Videospur enthält, deren Inhalte aus einem vom Benutzer ausgewählten Bildschirmbereich stammen, sowie eventuell eine Audiospur.

AbortError DOMException

Wird ausgelöst, wenn ein Fehler oder Fehlschlag keinem der hier aufgelisteten anderen Ausnahmen entspricht.

InvalidStateError DOMException

Wird ausgelöst, wenn der Aufruf von getDisplayMedia() nicht von Code ausgeführt wurde, der aufgrund eines flüchtigen Aktivierung, wie einem Ereignis-Handler, ausgeführt wurde. Oder wenn der Browserkontext nicht vollständig aktiv oder nicht fokussiert ist. Oder wenn die controller-Option bereits zur Erstellung eines anderen MediaStream verwendet wurde.

NotAllowedError DOMException

Wird ausgelöst, wenn die Erlaubnis zum Zugriff auf einen Bildschirmbereich vom Benutzer verweigert wurde oder die aktuelle Browsersitzung nicht die Berechtigung zum Zugriff auf Bildschirmfreigabe hat (zum Beispiel durch eine Berechtigungsrichtlinie).

NotFoundError DOMException

Wird ausgelöst, wenn keine Quellen von Bildschirmvideo zur Erfassung 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, jedoch ein Hardware- oder Betriebssystemebenenfehler oder -aussperrung aufgetreten ist, der das Teilen der ausgewählten Quelle verhindert.

OverconstrainedError DOMException

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

TypeError

Wird ausgelöst, wenn die angegebenen options Werte enthalten, die nicht zulässig sind, wenn getDisplayMedia() aufgerufen wird, zum Beispiel eine video-Eigenschaft, die auf false gesetzt ist, oder wenn angegebene MediaTrackConstraints nicht erlaubt sind. min- und exact-Werte sind in Constraints, die bei getDisplayMedia()-Aufrufen verwendet werden, nicht zulässig.

Da getDisplayMedia() auf bösartige Weise eingesetzt werden könnte, kann es eine Quelle erheblich beeinträchtigender Privatsphäre- und Sicherheitsbedenken sein. Aus diesem Grund beschreibt die Spezifikation Maßnahmen, die Browser ergreifen müssen, um die volle Unterstützung von getDisplayMedia() sicherzustellen.

• Die angegebenen Optionen können nicht verwendet werden, um die dem Benutzer verfügbaren Auswahlmöglichkeiten einzuschränken. Stattdessen müssen sie nach der Quellenauswahl durch den Benutzer angewendet werden, um eine Ausgabe zu erzeugen, die den Optionen entspricht.
• Die Genehmigung zur Nutzung von getDisplayMedia() kann nicht gespeichert werden. Der Benutzer muss jedes Mal um Erlaubnis gefragt werden.
• Eine flüchtige Benutzeraktivierung ist erforderlich. Der Benutzer muss mit der Seite oder einem UI-Element interagieren, damit diese Funktion funktioniert.
• Browser werden dazu angehalten, den Benutzern eine Warnung auszugeben, wenn sie Displays oder Fenster teilen, die Browser enthalten, 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 mit einem Satz von Spezifikationen durch den Parameter displayMediaOptions die Bildschirmerfassung 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 die Anzeigesergebnisse enthält, wie durch die angegebenen Optionen angefordert. Der Stream wird dann dem Aufrufer zur Nutzung zurückgegeben, vielleicht um ihn zu einem WebRTC-Anruf mit RTCPeerConnection.addTrack() hinzuzufügen, um den Videotrack aus dem Stream hinzuzufügen.

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