MediaDevices: Methode getUserMedia()

Syntax

getUserMedia(constraints)

Parameter

constraints

Ein Objekt, das die Arten von Medien, die angefordert werden, zusammen mit den Anforderungen für jeden Typ angibt.

Der constraints-Parameter ist ein Objekt mit zwei Mitgliedern: video und audio, die die angeforderten Medientypen beschreiben. Entweder oder beide müssen angegeben werden. Wenn der Browser nicht alle Medienspuren mit den angegebenen Typen finden kann, die den gegebenen Einschränkungen entsprechen, wird das zurückgegebene Promise mit NotFoundError DOMException abgelehnt.

Für sowohl video als auch audio ist der Wert entweder ein boolescher Wert oder ein Objekt. Der Standardwert ist false.

• Wenn für einen Medientyp true angegeben wird, ist der resultierende Stream verpflichtet, diese Art von Spur zu enthalten. Wenn aus irgendeinem Grund keine enthalten werden kann, wird das zurückgegebene Promise abgelehnt.
• Wenn für einen Medientyp false angegeben wird, darf der resultierende Stream diese Art von Spur nicht enthalten oder das zurückgegebene Promise wird abgelehnt. Da sowohl video als auch audio standardmäßig false sind, wird das zurückgegebene Promise immer abgelehnt, wenn das constraints-Objekt keine dieser Eigenschaften enthält oder überhaupt nicht vorhanden ist.
• Wenn für einen Medientyp ein Objekt angegeben ist, wird das Objekt als MediaTrackConstraints-Wörterbuch gelesen.

Rückgabewert

Ein Promise, dessen Fulfillment-Handler ein MediaStream-Objekt erhält, wenn die angeforderten Medien erfolgreich abgerufen wurden.

Ausnahmen

AbortError DOMException

Obwohl sowohl der Benutzer als auch das Betriebssystem den Zugriff auf das Hardwaregerät erteilt haben und keine Hardwareprobleme auftraten, die einen NotReadableError DOMException verursachen würden, wird diese Ausnahme ausgelöst, wenn ein Problem aufgetreten ist, das die Verwendung des Geräts verhindert hat.

InvalidStateError DOMException

Ausgelöst, wenn das aktuelle Dokument nicht vollständig aktiv ist.

NotAllowedError DOMException

Ausgelöst, wenn eines oder mehrere der angeforderten Quellgeräte derzeit nicht verwendet werden können. Dies tritt auf, wenn der Browsing-Kontext unsicher ist (d.h. die Seite wurde mittels HTTP statt HTTPS geladen). Es passiert auch, wenn der Benutzer angegeben hat, dass die aktuelle Browsing-Instanz keinen Zugriff auf das Gerät erhält, der Benutzer den Zugriff für die aktuelle Sitzung verweigert hat oder der Benutzer den Zugriff auf Benutzermediengeräte global verweigert hat. In Browsern, die das Verwalten von Medienberechtigungen mit Berechtigungsrichtlinie unterstützen, wird dieser Fehler zurückgegeben, wenn die Berechtigungsrichtlinie nicht konfiguriert ist, um den Zugriff auf die Eingabequelle(n) zu ermöglichen.

Hinweis: Ältere Versionen der Spezifikation verwendeten SecurityError hierfür stattdessen; SecurityError hat eine neue Bedeutung erhalten.

NotFoundError DOMException

Ausgelöst, wenn keine Medienspuren des angegebenen Typs gefunden wurden, die die gegebenen Einschränkungen erfüllen.

NotReadableError DOMException

Ausgelöst, wenn der Benutzer zwar die Erlaubnis erteilt hat, die passenden Geräte zu verwenden, jedoch ein Hardwarefehler auf Webseite-, Betriebssystem- oder Browserebene aufgetreten ist, der den Zugriff auf das Gerät verhindert hat.

OverconstrainedError DOMException

Ausgelöst, wenn die angegebenen Einschränkungen zu keinen Kandidatengeräten führten, die die gewünschten Kriterien erfüllten. Der Fehler ist ein Objekt vom Typ OverconstrainedError und hat eine constraint-Eigenschaft, deren Zeichenfolgenwert der Name einer Einschränkung ist, die nicht erfüllt werden konnte, sowie eine message-Eigenschaft, die eine menschenlesbare Zeichenfolge zur Erläuterung des Problems enthält.

Hinweis: Da dieser Fehler auch auftreten kann, wenn der Benutzer noch keine Erlaubnis zur Verwendung des zugrunde liegenden Geräts erteilt hat, kann er potenziell als Fingerprinting-Oberfläche genutzt werden.

SecurityError DOMException

Ausgelöst, wenn die Unterstützung für Benutzermedien im Document, auf dem getUserMedia() aufgerufen wurde, deaktiviert ist. Der Mechanismus, durch den die Unterstützung für Benutzermedien aktiviert und deaktiviert wird, bleibt dem individuellen Benutzeragenten überlassen.

TypeError

Ausgelöst, wenn die Liste der angegebenen Einschränkungen leer ist oder alle Einschränkungen auf false gesetzt sind. Dies kann auch passieren, wenn Sie versuchen, getUserMedia() in einem unsicheren Kontext aufzurufen, da navigator.mediaDevices in einem unsicheren Kontext undefined ist.

Datenschutz und Sicherheit

Als eine API, die erhebliche Datenschutzbedenken aufwerfen kann, legt die Spezifikation von getUserMedia() eine Vielzahl von Datenschutz- und Sicherheitsanforderungen fest, die Browser einhalten müssen.

getUserMedia() ist ein leistungsstarkes Feature, das nur in sicheren Kontexten verwendet werden kann; in unsicheren Kontexten ist navigator.mediaDevices undefined, was den Zugriff auf getUserMedia() verhindert. Ein sicherer Kontext ist im Wesentlichen eine Seite, die über HTTPS oder das file:///-URL-Schema geladen wurde oder eine Seite, die von localhost geladen wurde.

Zudem ist immer die Erlaubnis des Benutzers erforderlich, um auf die Audio- und Videoeingänge des Benutzers zuzugreifen. Nur das oberste Dokumentkontextfenster für einen gültigen Ursprung kann überhaupt die Erlaubnis zum Verwenden von getUserMedia() anfordern, es sei denn, der oberste Kontext gewährt ausdrücklich die Berechtigung für ein bestimmtes <iframe>, dies zu tun, unter Verwendung der Permissions Policy. Andernfalls wird der Benutzer niemals um Erlaubnis für die Verwendung der Eingabegeräte gebeten.

Für zusätzliche Details zu diesen Anforderungen und Regeln, wie sie im Kontext, in dem Ihr Code ausgeführt wird, reflektiert werden, und darüber, wie Browser Datenschutz- und Sicherheitsprobleme des Benutzers verwalten, lesen Sie weiter.

Datenschutz des Benutzers

Als eine API, die erhebliche Datenschutzbedenken aufwerfen kann, wird getUserMedia() von der Spezifikation sehr spezifischen Anforderungen an Benachrichtigung und Berechtigungsverwaltung unterworfen. Zuerst muss getUserMedia() stets die Benutzererlaubnis einholen, bevor es ein Medienerfassungsgerät wie eine Webcam oder ein Mikrofon öffnet. Browser können eine Einmal-pro-Domain-Berechtigungsfunktion anbieten, aber sie müssen mindestens beim ersten Mal nachfragen, und der Benutzer muss ausdrücklich eine fortwährende Erlaubnis erteilen, wenn er sich dazu entscheidet.

Von ebenso hoher Bedeutung sind die Benachrichtigungsregeln. Browser müssen ein Anzeigeelement anzeigen, das zeigt, dass eine Kamera oder ein Mikrofon verwendet wird, über jedwelche vorhandenen Hardwareanzeigen hinaus. Sie müssen auch ein Anzeigeelement anzeigen, das anzeigt, dass die Erlaubnis zur Verwendung eines Geräts erteilt wurde, selbst wenn das Gerät momentan nicht aktiv aufzeichnet.

Zum Beispiel zeigt die URL-Leiste in Firefox ein pulsierendes rotes Icon an, um anzuzeigen, dass eine Aufnahme im Gange ist. Das Icon ist grau, wenn die Erlaubnis erteilt wurde, die Aufnahme aber momentan nicht im Gange ist. Das physische Licht des Geräts wird verwendet, um anzuzeigen, ob die Aufnahme gerade aktiv ist oder nicht. Wenn Sie Ihre Kamera stummgeschaltet haben (sogenanntes „facemuting“), erlischt das Kameralicht, um anzuzeigen, dass die Kamera nicht aktiv aufzeichnet, ohne die Erlaubnis zum Fortfahren der Verwendung der Kamera nach Beendigung des Stummschaltens zu widerrufen.

Sicherheit

Es gibt eine Reihe von Möglichkeiten, wie Sicherheitsmanagement und -kontrollen in einem Benutzeragent dazu führen können, dass getUserMedia() einen sicherheitsbezogenen Fehler zurückgibt.

Berechtigungsrichtlinie

Die beiden Berechtigungsrichtlinie-Direktiven, die für getUserMedia() gelten, sind camera und microphone.

Zum Beispiel wird dieser HTTP-Header die Verwendung einer Kamera durch das Dokument und alle eingebetteten <iframe>-Elemente, die vom selben Ursprung geladen werden, aktivieren:

Permissions-Policy: camera=(self)

Dies wird den Zugriff auf das Mikrofon für den aktuellen Ursprung und den spezifischen Ursprung https://developer.mozilla.org anfordern:

Permissions-Policy: microphone=(self "https://developer.mozilla.org")

Wenn Sie getUserMedia() innerhalb eines <iframe> verwenden, können Sie die Berechtigung nur für diesen Frame anfordern, was offensichtlich sicherer ist als eine allgemeinere Berechtigung anzufordern. Hierbei geben wir an, dass wir die Fähigkeit benötigen, sowohl Kamera als auch Mikrofon zu verwenden:

<iframe src="https://mycode.example.net/etc" allow="camera; microphone">
</iframe>

Sicherheitsmaßnahmen auf Basis von Verschlüsselung

Die getUserMedia()-Methode ist nur in sicheren Kontexten verfügbar. Ein sicherer Kontext ist einer, bei dem der Browser mit angemessener Zuversicht davon ausgehen kann, dass er ein Dokument enthält, das sicher geladen wurde, unter Verwendung von HTTPS/TLS, und das nur begrenzt anfällig für unsichere Kontexte ist. Wenn ein Dokument nicht in einem sicheren Kontext geladen wird, ist die navigator.mediaDevices-Eigenschaft undefined, was den Zugriff auf getUserMedia() unmöglich macht.

Der Versuch, getUserMedia() in dieser Situation aufzurufen, führt zu einem TypeError.

Sicherheitsmaßnahmen bezogen auf die Dokumentquelle

Aufgrund der offensichtlichen Sicherheitsbedenken, die mit getUserMedia() verbunden sein können, wenn es unerwartet oder ohne sorgfältig verwaltete Sicherheit verwendet wird, kann es nur in sicheren Kontexten verwendet werden. Es gibt eine Reihe von unsicheren Möglichkeiten, ein Dokument zu laden, das wiederum versuchen könnte, getUserMedia() aufzurufen. Im Folgenden sind Beispiele für Situationen, in denen getUserMedia() nicht aufgerufen werden darf:

• Ein Dokument, das in ein sandboxed <iframe>-Element geladen wurde, kann getUserMedia() nicht aufrufen, es sei denn, das <iframe> hat sein sandbox-Attribut auf allow-same-origin gesetzt.
• Ein Dokument, das über eine data://- oder blob://-URL geladen wurde, die keinen Ursprung hat (wie z.B. wenn eine dieser URLs von einem Benutzer in die Adressleiste eingegeben wird), kann getUserMedia() nicht aufrufen. Diese Arten von URLs, die von JavaScript-Code geladen werden, erben die Berechtigungen des Skripts.
• Jede andere Situation, in der es keinen Ursprung gibt, wie z.B., wenn das srcdoc-Attribut verwendet wird, um den Inhalt eines Rahmens zu spezifizieren.

Beispiele

Verwendung von getUserMedia()

Im Allgemeinen werden Sie auf das MediaDevices-Singleton-Objekt über navigator.mediaDevices zugreifen, wie folgt:

async function getMedia(constraints) {
  let stream = null;

  try {
    stream = await navigator.mediaDevices.getUserMedia(constraints);
    /* use the stream */
  } catch (err) {
    /* handle the error */
  }
}

Ähnlich sieht der Code bei Verwendung der rohen Promises direkt so aus:

navigator.mediaDevices
  .getUserMedia(constraints)
  .then((stream) => {
    /* use the stream */
  })
  .catch((err) => {
    /* handle the error */
  });

Im Folgenden sind einige Beispiele für den constraints-Parameter aufgeführt.

Der folgende Code fordert sowohl Audio als auch Video ohne spezifische Anforderungen an:

getUserMedia({
  audio: true,
  video: true,
});

Während Informationen über die Kameras und Mikrofone eines Benutzers aus Datenschutzgründen nicht zugänglich sind, kann eine Anwendung die Kamera- und Mikrofonfähigkeiten anfordern, die sie benötigt und wünscht, indem zusätzliche Einschränkungen verwendet werden. Das Folgende drückt eine Präferenz für 1280x720-Kameraauflösung aus:

getUserMedia({
  audio: true,
  video: { width: 1280, height: 720 },
});

Der Browser wird versuchen, die Einschränkungen zu erfüllen und eine passende Spur zurückzugeben, wenn sie von der zugrunde liegenden Hardware unterstützt wird. Wenn sie nicht unterstützt wird, kann der Browser versuchen, einen Stream mit höherer Auflösung von der zugrunde liegenden Hardware zu beschneiden und herunterskaliert zurückzugeben, um die Einschränkungen zu erfüllen (und könnte auch die Bildrate reduzieren, wenn dies eingeschränkt wurde). Dieses Verhalten kann erzwungen werden, indem die resizeMode-Einschränkung auf crop-and-scale gesetzt wird (oder deaktiviert wird, indem sie auf none gesetzt wird):

getUserMedia({
  audio: true,
  video: { width: 1280, height: 720, resizeMode: "crop-and-scale" },
});

Der Browser kann eine andere Auflösung zurückgeben, wenn keine genaue Übereinstimmung verfügbar ist und die Quelle nicht skaliert werden soll.

Um eine Fähigkeit zu erzwingen und zu scheitern, wenn sie nicht verfügbar ist, verwenden Sie die Schlüsselwörter min, max oder exact (alias min === max). Das Folgende fordert eine Mindestauflösung von 1280x720:

getUserMedia({
  audio: true,
  video: {
    width: { min: 1280 },
    height: { min: 720 },
  },
});

Wenn keine Kamera mit dieser oder höherer Auflösung existiert, wird das zurückgegebene Promise mit OverconstrainedError abgelehnt, und der Benutzer wird nicht aufgefordert.

Der Grund für das unterschiedliche Verhalten ist, dass die Schlüsselwörter min, max und exact inhärent verpflichtend sind – wohingegen einfache Werte und ein Schlüsselwort namens ideal es nicht sind. Hier ist ein vollständiges Beispiel:

getUserMedia({
  audio: true,
  video: {
    width: { min: 1024, ideal: 1280, max: 1920 },
    height: { min: 576, ideal: 720, max: 1080 },
  },
});

Ein ideal-Wert hat Schwerkraft – was bedeutet, dass der Browser versuchen wird, die Einstellung (und Kamera, wenn Sie mehr als eine haben) mit der kleinsten Fitness-Distanz zu den angegebenen idealen Werten zu finden.

Einfache Werte sind inhärent ideal, was bedeutet, dass das erste unserer Auflösungsbeispiele oben so hätte geschrieben werden können:

getUserMedia({
  audio: true,
  video: {
    width: { ideal: 1280 },
    height: { ideal: 720 },
  },
});

Nicht alle Einschränkungen sind Zahlen. Zum Beispiel wird auf Mobilgeräten das Folgende die Frontkamera (wenn verfügbar) der Rückkamera vorziehen:

getUserMedia({
  audio: true,
  video: { facingMode: "user" },
});

Um die Rückkamera zu erzwingen, verwenden Sie:

getUserMedia({
  audio: true,
  video: {
    facingMode: { exact: "environment" },
  },
});

Eine weitere Nicht-Nummer Einschränkung ist die deviceId-Einschränkung. Wenn Sie eine deviceId von mediaDevices.enumerateDevices() haben, können Sie sie verwenden, um ein bestimmtes Gerät anzufordern:

getUserMedia({
  video: {
    deviceId: myPreferredCameraDeviceId,
  },
});

Das Obige wird die angeforderte Kamera zurückgeben oder eine andere Kamera, wenn diese spezielle Kamera nicht mehr verfügbar ist. Um die spezifische Kamera zu erzwingen, würden Sie verwenden:

getUserMedia({
  video: {
    deviceId: {
      exact: myExactCameraOrBustDeviceId,
    },
  },
});

Breite und Höhe

Dieses Beispiel gibt eine Präferenz für die Kameraauflösung an und weist das resultierende MediaStream-Objekt einem Videoelement zu.

// Prefer camera resolution nearest to 1280x720.
const constraints = {
  audio: true,
  video: { width: 1280, height: 720 },
};

navigator.mediaDevices
  .getUserMedia(constraints)
  .then((mediaStream) => {
    const video = document.querySelector("video");
    video.srcObject = mediaStream;
    video.onloadedmetadata = () => {
      video.play();
    };
  })
  .catch((err) => {
    // always check for errors at the end.
    console.error(`${err.name}: ${err.message}`);
  });

Bildrate

Niedrigere Bildraten können in einigen Fällen wünschenswert sein, zum Beispiel bei WebRTC-Übertragungen mit Bandbreitenbeschränkungen.

const constraints = {
  video: { frameRate: { ideal: 10, max: 15 } },
};

Front- und Rückkamera

Auf Mobiltelefonen.

let front = false;
document.getElementById("flip-button").onclick = () => {
  front = !front;
};

const constraints = {
  video: { facingMode: front ? "user" : "environment" },
};

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Die ältere Navigator.getUserMedia()-Legacy-API
• MediaDevices.enumerateDevices(): Auflisten verfügbarer Mediengeräte
• WebRTC API
• Media Capture and Streams API
• Screen Capture API: Erfassen von Bildschirm-Inhalten als MediaStream
• MediaDevices.getDisplayMedia(): Abrufen eines Streams mit Bildschirm-Inhalten
• Webcam-Fotos aufnehmen: Ein Tutorial zur Verwendung von getUserMedia(), um Standbilder statt Videos aufzunehmen