MediaDevices: getDisplayMedia() Methode

options Optional

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

video Optional

Ein Boolescher Wert oder eine Instanz von MediaTrackConstraints; der Standardwert ist true. Wenn diese Option weggelassen wird oder auf true gesetzt ist, 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, wenn diese Option auf false gesetzt ist, mit einem TypeError abgelehnt.

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 enthalten wird, wenn Audio unterstützt und für die vom Benutzer gewählte Anzeigefläche verfügbar ist.

controller Experimentell Optional

Eine Instanz eines CaptureController-Objekts mit Methoden, die verwendet werden können, um die Aufnahmesitzung weiter zu manipulieren, falls inklusive.

monitorTypeSurfaces Experimentell Optional

Ein enumerierter Wert, der angibt, ob der Browser gesamte Bildschirme neben Tab- und Fensteroptionen in den Bildschirmaufnahmeoptionen, die dem Benutzer präsentiert werden, anbieten soll. Diese Option ist dazu gedacht, Unternehmen vor der Preisgabe privater Informationen durch Mitarbeiterfehler bei der Verwendung von Videokonferenz-Apps zu schützen. Mögliche Werte sind include, was andeutet, dass der Browser Bildschirmoptionen einbeziehen soll, und exclude, was andeutet, dass sie ausgeschlossen werden sollen. Ein Standardwert wird von der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browserspezifische Standardwerte.

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

preferCurrentTab Nicht standardisiert Experimentell Optional

Ein boolescher Wert; ein Wert von true weist den Browser an, den aktuellen Tab als wichtigste Quelle für die Aufnahme anzubieten, d.h. als separate "Dieser Tab"-Option in den "Teilen, was Sie teilen möchten"-Optionen, die dem Benutzer präsentiert werden. Dies ist nützlich, da viele App-Typen im Allgemeinen nur den aktuellen Tab teilen möchten. Zum Beispiel könnte eine Präsentations-App es dem Benutzer ermöglichen wollen, den aktuellen Tab, der die Präsentation enthält, zu einem virtuellen Konferenzraum zu streamen. Ein Standardwert wird von der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browserspezifische Standardwerte.

selfBrowserSurface Experimentell Optional

Ein enumerierter Wert, der angibt, ob der Browser dem Benutzer erlauben soll, den aktuellen Tab zur Aufnahme auszuwählen. Dies hilft, den "unendlichen Spiegelungeffekt" zu vermeiden, der auftritt, wenn eine Videokonferenz-App versehentlich das eigene Display teilt. Mögliche Werte sind include, was andeutet, dass der Browser den aktuellen Tab in die Auswahlmöglichkeiten für die Aufnahme einbeziehen soll, und exclude, was andeutet, dass er ausgeschlossen werden soll. Ein Standardwert wird von der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browserspezifische Standardwerte.

surfaceSwitching Experimentell Optional

Ein enumerierter Wert, der angibt, ob der Browser eine Steuerung anzeigen soll, um dem Benutzer das dynamische Wechseln des geteilten Tabs während des Bildschirmteilens zu ermöglichen. Dies ist viel bequemer als jedes Mal den ganzen Teilungsprozess erneut durchlaufen zu müssen, wenn ein Benutzer den geteilten Tab wechseln möchte. Mögliche Werte sind include, was andeutet, dass der Browser die Steuerung einbeziehen soll, und exclude, was andeutet, dass sie nicht angezeigt werden soll. Ein Standardwert wird von der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browserspezifische Standardwerte.

systemAudio Experimentell Optional

Ein enumerierter Wert, der angibt, ob der Browser das Systemaudio zu den möglichen Audiowiedergabequellen für den Benutzer hinzufügen soll. Mögliche Werte sind include, was andeutet, dass der Browser das Systemaudio in die Listenauswahl aufnehmen soll, und exclude, was andeutet, dass es ausgeschlossen werden soll. Ein Standardwert wird von der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browserspezifische Standardwerte.

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

AbortError DOMException

Wird ausgelöst, wenn ein Fehler oder Versagen keiner der anderen hier aufgeführten Ausnahmen entspricht.

InvalidStateError DOMException

Wird ausgelöst, wenn der Aufruf von getDisplayMedia() nicht von Code ausgeführt wurde, der aufgrund einer transienten Aktivierung läuft, wie ein Event-Handler. Oder wenn der Browser-Kontext 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 Browserinstanz keinen Zugriff auf das Bildschirmteilen hat (zum Beispiel durch eine Berechtigungsrichtlinie).

NotFoundError DOMException

Wird ausgelöst, wenn keine Quellenvideos für die Bildschirmaufnahme verfügbar sind.

NotReadableError DOMException

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

OverconstrainedError DOMException

Wird ausgelöst, wenn nach der Erstellung des Streams das Anwenden 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 auf false setzen oder wenn angegebene MediaTrackConstraints nicht erlaubt sind. min und exact Werte sind in den Beschränkungen, die in getDisplayMedia()-Aufrufen verwendet werden, nicht erlaubt.

Da getDisplayMedia() auf bösartige Weise verwendet werden könnte, kann es eine Quelle signifikanter Datenschutz- und Sicherheitsbedenken sein. Aus diesem Grund beschreibt die Spezifikation 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 einzuschränken. Stattdessen müssen sie nach der Auswahl einer Quelle durch den Benutzer angewendet werden, um eine Ausgabe zu erstellen, die den Optionen entspricht.
• Die Erlaubnis zur Verwendung von getDisplayMedia() kann nicht zur Wiederverwendung gespeichert werden. Der Benutzer muss jedes Mal um Erlaubnis gebeten werden.
• Eine transiente Benutzeraktivierung ist erforderlich. Der Benutzer muss mit der Seite oder einem UI-Element interagieren, damit dieses Feature funktioniert.
• Browser werden ermutigt, den Benutzern eine Warnung darüber zu geben, dass sie Displays oder Fenster teilen, die Browser enthalten, und genau darauf zu achten, welche anderen Inhalte möglicherweise erfasst und anderen Benutzern angezeigt werden könnten.

Im folgenden Beispiel wird eine startCapture()-Methode erstellt, die die Bildschirmaufnahme mit einem Satz von Optionen startet, die durch den Parameter displayMediaOptions angegeben werden.

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() zu einem MediaStream zu warten, der die angeforderten Display-Inhalte enthält, die durch die angegebenen Optionen spezifiziert wurden. Der Stream wird dann an den Anrufer zur Verwendung zurückgegeben, möglicherweise um einem WebRTC-Anruf mit RTCPeerConnection.addTrack() die Videospur des Streams hinzuzufügen.

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