MediaDevices: getDisplayMedia() Methode
Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.
Die getDisplayMedia()
Methode der MediaDevices
Schnittstelle fordert den Benutzer auf, eine Auswahl zu treffen und die Erlaubnis zu erteilen, die Inhalte eines Bildschirms oder eines Teils davon (z.B. ein Fenster) als einen MediaStream
zu erfassen.
Der resultierende Stream kann dann mit der MediaStream Recording API aufgezeichnet oder als Teil einer WebRTC-Sitzung übertragen werden.
Weitere Details und ein Beispiel finden Sie unter Verwendung der Screen Capture API.
Syntax
getDisplayMedia()
getDisplayMedia(options)
Parameter
options
Optional-
Ein optionales Objekt, das Anforderungen für den zurückgegebenen
MediaStream
angibt. Die Optionen fürgetDisplayMedia()
funktionieren ähnlich wie die Einschränkungen für die MethodeMediaDevices.getUserMedia()
, obwohl in diesem Fall nuraudio
undvideo
angegeben 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, enthält der Stream einen Videotrack. Ein Wert vontrue
zeigt an, dass der zurückgegebeneMediaStream
einen Videotrack enthalten wird. DagetDisplayMedia()
einen Videotrack erfordert, schlägt die Promise fehl, wenn diese Option auffalse
gesetzt ist, und löst einenTypeError
aus. 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 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, undexclude
, 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 mitdisplaySurface: "monitor"
setzen, da die beiden Einstellungen widersprüchlich sind. Ein solcher Versuch 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, 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, undexclude
, 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, undexclude
, 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, undexclude
, 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, undexclude
, 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.
Hinweis: Siehe den Artikel Fähigkeiten, Einschränkungen und Einstellungen für viel mehr Details darüber, wie diese Optionen funktionieren.
Rückgabewert
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.
Hinweis: Die Browserunterstützung für Audiospuren variiert, sowohl dahingehend, ob sie vom Medienrekorder überhaupt unterstützt werden, als auch, welche Audioquellen unterstützt werden. Überprüfen Sie die Kompatibilitätstabelle für Details zu jedem Browser.
Ausnahmen
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 diecontroller
-Option bereits zur Erstellung eines anderenMediaStream
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, wenngetDisplayMedia()
aufgerufen wird, zum Beispiel einevideo
-Eigenschaft, die auf false gesetzt ist, oder wenn angegebeneMediaTrackConstraints
nicht erlaubt sind.min
- undexact
-Werte sind in Constraints, die beigetDisplayMedia()
-Aufrufen verwendet werden, nicht zulässig.
Sicherheit
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.
Beispiele
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.
Hinweis: Die Bildschirmfreigabe-Steuerungen Demo bietet eine vollständige Implementierung, die es Ihnen ermöglicht, eine Bildschirmaufnahme mit Ihrer Wahl an getDisplayMedia()
-Einschränkungen und Optionen zu erstellen.
Spezifikationen
Specification |
---|
Screen Capture # dom-mediadevices-getdisplaymedia |
Browser-Kompatibilität
BCD tables only load in the browser
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