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
getDisplayMedia()
getDisplayMedia(options)
Parameter
options
Optional-
Ein optionales Objekt, das Anforderungen für den zurückgegebenen
MediaStream
spezifiziert. Die Optionen fürgetDisplayMedia()
funktionieren ähnlich wie die Constraints für die MethodeMediaDevices.getUserMedia()
, obwohl in diesem Fall nuraudio
undvideo
spezifiziert werden können. Die Liste der möglichen Options-Eigenschaften fürgetDisplayMedia()
lautet wie folgt:video
Optional-
Ein Boolean oder eine Instanz von
MediaTrackConstraints
; der Standardwert isttrue
. Wenn diese Option weggelassen oder auftrue
gesetzt wird, wird der Stream einen Videotrack enthalten. Ein Wert vontrue
zeigt an, dass der zurückgegebeneMediaStream
einen Videotrack enthalten wird. DagetDisplayMedia()
einen Videotrack erfordert, wird das Versprechen mit einemTypeError
verworfen, wenn diese Option auffalse
gesetzt wird. audio
Optional-
Ein Boolean oder eine Instanz von
MediaTrackConstraints
; der Standardwert istfalse
. Ein Wert vontrue
zeigt an, dass der zurückgegebeneMediaStream
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, undexclude
, 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 mitdisplaySurface: "monitor"
festlegen, da die beiden Einstellungen widersprüchlich sind. Der Versuch, dies zu tun, führt dazu, dass dergetDisplayMedia()
-Aufruf mit einemTypeError
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, undexclude
, 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, undexclude
, 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, undexclude
, 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 diecontroller
-Option bereits bei der Erstellung eines anderenMediaStream
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 vongetDisplayMedia()
nicht zulässig sind, zum Beispiel eine auf false gesetztevideo
-Eigenschaft, oder wenn angegebeneMediaTrackConstraints
nicht zulässig sind.min
undexact
Werte sind in Constraints, die ingetDisplayMedia()
-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.
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 GitHubdesktop | mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
getDisplayMedia() | ||||||||||||
Audio capture support | ||||||||||||
controller option | ||||||||||||
monitorTypeSurfaces option | ||||||||||||
preferCurrentTab option | ||||||||||||
selfBrowserSurface option | ||||||||||||
surfaceSwitching option | ||||||||||||
systemAudio option |
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
- Screen Capture API
- Using the Screen Capture API
- Media Capture and Streams API
- WebRTC API
getUserMedia()
: Erfassung von Medien von einer Kamera und/oder einem Mikrofon