MediaDevices: getDisplayMedia() Methode

Syntax

getDisplayMedia()
getDisplayMedia(options)

Parameter

options Optional

Ein Objekt, das Anforderungen für den zurückgegebenen MediaStream spezifiziert. Die Optionen für getDisplayMedia() funktionieren ähnlich 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 Optionseigenschaften für getDisplayMedia() ist wie folgt:

video Optional

Ein boolescher Wert oder eine MediaTrackConstraints Instanz; der Standardwert ist true. Wenn diese Option weggelassen oder auf true gesetzt wird, enthält der zurückgegebene MediaStream einen Video-Track. Da getDisplayMedia() einen Video-Track erfordert, wird das Versprechen abgelehnt, wenn diese Option auf false gesetzt ist, mit einem TypeError.

audio Optional

Ein boolescher Wert oder eine MediaTrackConstraints Instanz; der Standardwert ist false. Ein Wert von true gibt an, dass der zurückgegebene MediaStream einen Audio-Track enthält, falls Audio unterstützt und für die vom Benutzer ausgewählte Anzeigeoberfläche verfügbar ist.

controller Experimentell Optional

Eine CaptureController Objektinstanz, die Methoden enthält, die zur weiteren Manipulation der Aufnahmesitzung verwendet werden können, falls eingeschlossen.

monitorTypeSurfaces Experimentell Optional

Ein aufgezählter Wert, der angibt, ob der Browser gesamte Bildschirme in den dem Benutzer angebotenen Bildschirmaufnahmeoptionen zusammen mit Tab- und Fensteroptionen anbieten sollte. Diese Option soll Unternehmen davor schützen, dass private Informationen durch Benutzerfehler bei der Verwendung von Videokonferenz-Apps durchsickern. Mögliche Werte sind:

• include: Hinweis, dass der Browser Bildschirmoptionen einschließen sollte.
• exclude: Hinweis, dass Bildschirmoptionen ausgeschlossen werden sollten.

Hinweis: Sie können monitorTypeSurfaces: "exclude" nicht gleichzeitig mit displaySurface: "monitor" festlegen, da die beiden Einstellungen widersprüchlich sind. Der Versuch, dies zu tun, führt dazu, dass der getDisplayMedia() Aufruf 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 die hervorgehobene Aufnahmequelle anzubieten, das heißt, als separate "Dieser Tab" Option in den dem Benutzer angebotenen "Teilen, was Sie teilen möchten" Optionen. Dies ist nützlich, da viele App-Typen im Allgemeinen nur den aktuellen Tab teilen möchten. Beispielsweise könnte eine Präsentations-App dem Benutzer erlauben, den aktuellen Tab mit der Präsentation zu einem virtuellen Konferenz zu streamen.

selfBrowserSurface Experimentell Optional

Ein aufgezählter Wert, der angibt, ob der Browser dem Benutzer erlauben sollte, den aktuellen Tab zur Aufnahme auszuwählen. Dies hilft, den "unendlichen Spiegelkabinett"-Effekt zu vermeiden, der auftritt, wenn eine Videokonferenz-App versehentlich ihr eigenes Display teilt. Mögliche Werte sind:

• include: Hinweis, dass der Browser den aktuellen Tab in die angebotenen Auswahlmöglichkeiten für die Aufnahme einschließen sollte.
• exclude: Hinweis, dass der aktuelle Tab von den Auswahlmöglichkeiten ausgeschlossen werden sollte.

surfaceSwitching Experimentell Optional

Ein aufgezählter Wert, der angibt, ob der Browser eine Steuerung anzeigen sollte, um dem Benutzer zu ermöglichen, während der Bildschirmübertragung dynamisch den geteilten Tab zu wechseln. Dies ist bequemer, als jedes Mal, wenn ein Benutzer den geteilten Tab wechseln will, den gesamten Freigabeprozess erneut durchlaufen zu müssen. Mögliche Werte sind:

• include: Hinweis, dass der Browser die Steuerung einschließen sollte.
• exclude: Hinweis, dass die Steuerung nicht angezeigt werden sollte.

systemAudio Experimentell Optional

Ein aufgezählter Wert, der angibt, ob der Browser das Systemaudio unter den dem Benutzer angebotenen möglichen Audioquellen einschließen sollte. Mögliche Werte sind:

• include: Hinweis, dass der Browser das Systemaudio in die Auswahlmöglichkeiten einschließen sollte.
• exclude: Hinweis, dass das Systemaudio von den angezeigten Auswahlmöglichkeiten ausgeschlossen werden sollte.

windowAudio Experimentell Optional

Ein aufgezählter Wert, der dem Browser Hinweise gibt, welche Audiofreigabeoption der Benutzer neben Fensterfreigabeoptionen präsentiert werden sollte. Mögliche Werte sind:

• exclude: Hinweis, dass Audio nicht freigegeben werden sollte, wenn eine Fensterfreigabeoption gewählt wird.
• window: Hinweis, dass beim Auswählen einer Fensterfreigabeoption nur Audio, das von diesem Fenster stammt, freigegeben werden sollte.
• system: Hinweis, dass beim Auswählen einer Fensterfreigabeoption das gesamte Systemaudio freigegeben werden sollte.

Rückgabewert

Ein Promise, das zu einem MediaStream auflöst, der einen Videotrack enthält, dessen Inhalte aus einem vom Benutzer ausgewählten Bildschirmbereich stammen, sowie ein optionaler Audiotrack.

Ausnahmen

AbortError DOMException

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

InvalidStateError DOMException

Wird ausgelöst, wenn der Aufruf von getDisplayMedia() nicht von Code ausgeführt wird, der aufgrund einer flüchtigen Aktivierung, z. B. einem Ereignishandler, ausgeführt wird. Oder wenn der Browserkontext nicht vollständig aktiv oder nicht fokussiert ist. Oder wenn die controller Optionen bereits bei der Erstellung eines anderen MediaStream verwendet wurde.

NotAllowedError DOMException

Wird ausgelöst, wenn die Erlaubnis zum Zugreifen auf einen Bildschirmbereich vom Benutzer verweigert wurde oder die aktuelle Browsing-Instanz nicht für den Zugriff auf Bildschirmfreigabe berechtigt ist (zum Beispiel durch eine Berechtigungsrichtlinie).

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, einen Tab oder eine andere Quelle für Bildschirmdaten ausgewählt hat, aber ein Hardware- oder Betriebssystem-Ebene-Fehler oder eine Sperrung aufgetreten ist, die das Teilen der ausgewählten Quelle verhindert.

OverconstrainedError DOMException

Wird ausgelöst, wenn nach der Erstellung des Streams das Anwenden von angegebenen Einschränkungen fehlschlägt, da 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 angegebene MediaTrackConstraints nicht erlaubt sind. min- und exact-Werte sind in Einschränkungen, die in getDisplayMedia()-Aufrufen verwendet werden, nicht erlaubt.

Sicherheit

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

• Die angegebenen Optionen können nicht verwendet werden, um die dem Benutzer zur Verfügung stehenden Auswahlmöglichkeiten einzuschränken. Stattdessen müssen sie angewandt werden, nachdem der Benutzer eine Quelle gewählt hat, um eine Ausgabe zu generieren, die den Optionen entspricht.
• Die Erlaubnis, getDisplayMedia() zu verwenden, kann nicht für eine spätere Verwendung gespeichert werden. Der Benutzer muss jedes Mal um Erlaubnis gebeten werden.
• Flüchtige Benutzeraktivierung ist erforderlich. Der Benutzer muss mit der Seite oder einem UI-Element interagieren, damit diese Funktion funktioniert.
• Browser werden dazu ermutigt, Benutzer zu warnen, wenn Sie Bildschirme oder Fenster teilen, die Browser enthalten, und genau darauf zu achten, welche anderen Inhalte möglicherweise erfasst und anderen Benutzern angezeigt werden könnten.

Beispiele

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

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 angeforderten Display-Inhalte gemäß den angegebenen Optionen enthält. Der Stream wird dann an den Aufrufer zur Verwendung zurückgegeben, möglicherweise um ihn zu einem WebRTC-Anruf hinzuzufügen, indem RTCPeerConnection.addTrack() verwendet wird, um den Videotrack aus dem Stream hinzuzufügen.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• 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