MediaDevices: getDisplayMedia() Methode

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Die getDisplayMedia() Methode des MediaDevices Interfaces fordert den Benutzer auf, die Erlaubnis zu erteilen, die Inhalte eines Bildschirms oder eines Teils davon (wie zum Beispiel eines Fensters) als MediaStream aufzunehmen.

Der resultierende Stream kann dann mithilfe der MediaStream Recording API aufgezeichnet oder als Teil einer WebRTC Sitzung übertragen werden.

Weitere Details und ein Beispiel finden Sie unter Using the Screen Capture API.

Syntax

js
getDisplayMedia()
getDisplayMedia(options)

Parameter

options Optional

Ein optionales Objekt, das Anforderungen für den zurückgegebenen MediaStream spezifiziert. Die Optionen für getDisplayMedia() funktionieren ähnlich wie die Constraints für die Methode MediaDevices.getUserMedia(), obwohl in diesem Fall nur audio und video spezifiziert 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, wird der Stream einen Videotrack enthalten. Ein Wert von true zeigt an, dass der zurückgegebene MediaStream einen Videotrack enthalten wird. Da getDisplayMedia() einen Videotrack erfordert, wird das Versprechen mit einem TypeError verworfen, wenn diese Option auf false gesetzt wird.

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 wird und für die vom Benutzer gewählte Bildschirmoberfläche verfügbar ist.

controller Experimentell Optional

Ein CaptureController Objekt, das Methoden enthält, die zur weiteren Bearbeitung der Aufnahmesitzung verwendet werden können, wenn es enthalten ist.

monitorTypeSurfaces Experimentell Optional

Ein enumerierter Wert, der angibt, ob der Browser vollständige Bildschirme in den dem Benutzer angezeigten Bildschirmaufnahmeoptionen neben Tab- und Fensteroptionen anbieten soll. Diese Option soll Unternehmen vor der Preisgabe privater Informationen durch Mitarbeiterfehler bei der Verwendung von Videokonferenz-Apps schützen. 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 ist von der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browserspezifische Standards.

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 Boolean; ein Wert von true weist den Browser an, den aktuellen Tab als prominenteste Aufnahmequelle anzubieten, d. h. als separate Option "Dieser Tab" in den dem Benutzer angezeigten Optionen "Wählen Sie aus, was Sie freigeben möchten". Dies ist nützlich, da viele App-Typen im Allgemeinen nur den aktuellen Tab freigeben möchten. Zum Beispiel möchte eine Präsentations-App möglicherweise dem Benutzer ermöglichen, den aktuellen Tab, der die Präsentation enthält, an eine virtuelle Konferenz zu streamen. Ein Standardwert ist von der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browserspezifische Standards.

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 "endlosen Spiegelungseffekt" zu vermeiden, der auftritt, wenn eine Videokonferenz-App versehentlich ihr eigenes Display teilt. Mögliche Werte sind include, was darauf hinweist, dass der Browser den aktuellen Tab in die zur Auswahl angebotenen Optionen aufnehmen soll, und exclude, was darauf hinweist, dass er ausgeschlossen werden soll. Ein Standardwert ist von der Spezifikation nicht vorgeschrieben; siehe den Abschnitt Browser-Kompatibilität für browserspezifische Standards.

surfaceSwitching Experimentell Optional

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

systemAudio Experimentell Optional

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

Hinweis: Siehe den Artikel Fähigkeiten, Constraints und Einstellungen für ausführlichere Informationen darüber, wie diese Optionen funktionieren.

Rückgabewert

Ein Promise, das zu einem MediaStream aufgelöst wird, der einen Videotrack enthält, dessen Inhalte aus einem vom Benutzer gewählten Bildschirmbereich stammen, sowie einen optionalen Audiotrack.

Hinweis: Die Browserunterstützung für Audiotracks variiert, sowohl in Bezug darauf, ob sie überhaupt vom Medienrekorder unterstützt werden, als auch in Bezug auf die unterstützten Audioquellen. Überprüfen Sie die Kompatibilitätstabelle für Details zu jedem Browser.

Ausnahmen

AbortError DOMException

Wird ausgelöst, wenn ein Fehler oder Ausfall mit keiner der hier aufgeführten anderen Ausnahmen übereinstimmt.

InvalidStateError DOMException

Wird ausgelöst, wenn der Aufruf von getDisplayMedia() nicht von einem durch eine transiente Aktivierung verursachten Code stammt, wie z. B. einem Ereignishandler. Oder wenn der Browserkontext nicht vollständig aktiv ist oder nicht fokussiert ist. Oder wenn die controller-Option bereits bei der Erstellung eines anderen MediaStream verwendet wurde.

NotAllowedError DOMException

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

NotFoundError DOMException

Wird ausgelöst, wenn keine Quellenscreen-Videoquellen 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 Betriebssystemfehler oder eine Sperre aufgetreten ist, die die Freigabe der ausgewählten Quelle verhindert.

OverconstrainedError DOMException

Wird ausgelöst, wenn, nachdem der Stream erstellt wurde, das Anwenden der angegebenen Constraints fehlschlägt, weil kein kompatibler Stream generiert werden konnte.

TypeError

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

Sicherheit

Da getDisplayMedia() auf bösartige Weise verwendet werden könnte, kann es eine Quelle erheblicher Datenschutz- und Sicherheitsbedenken sein. Aus diesem Grund legt die Spezifikation Maßnahmen fest, die Browser treffen 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 zu begrenzen. Stattdessen müssen sie angewandt werden, nachdem der Benutzer eine Quelle ausgewählt hat, um Ausgaben zu erzeugen, die den Optionen entsprechen.
  • Die Erlaubnis zur Verwendung von getDisplayMedia() kann nicht für eine spätere Verwendung beibehalten werden. Der Benutzer muss jedes Mal um Erlaubnis gebeten werden.
  • 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 bezüglich der Freigabe von Displays oder Fenstern, die Browser enthalten, zu geben und genau zu beobachten, welche anderen Inhalte möglicherweise erfasst und anderen Benutzern angezeigt werden.

Beispiele

Im folgenden Beispiel wird eine startCapture() Methode erstellt, die die Bildschirmaufnahme mit einer Reihe von Optionen startet, die mit dem Parameter displayMediaOptions angegeben werden.

js
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 gewünschten Anzeigeinhalte gemäß den angegebenen Optionen enthält. Der Stream wird dann an den Aufrufer zurückgegeben, möglicherweise zur Verwendung, um ihn z. B. mit RTCPeerConnection.addTrack() zu einem WebRTC-Anruf hinzuzufügen, um den Videotrack aus dem Stream hinzuzufügen.

Hinweis: Die Screen sharing controls-Demo bietet eine vollständige Implementierung, die es Ihnen ermöglicht, eine Bildschirmaufnahme mit Ihrer Wahl der getDisplayMedia()-Constraints und -Optionen zu erstellen.

Spezifikationen

Specification
Screen Capture
# dom-mediadevices-getdisplaymedia

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
getDisplayMedia()
Audio capture support
controller option
Experimental
monitorTypeSurfaces option
Experimental
preferCurrentTab option
ExperimentalNon-standard
selfBrowserSurface option
Experimental
surfaceSwitching option
Experimental
systemAudio option
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
No support
No support
Experimental. Expect behavior to change in the future.
Non-standard. Check cross-browser support before using.
See implementation notes.
Has more compatibility info.

Siehe auch