Navigator.getUserMedia() — Methode · JavaScript-Referenz

Signatur

Navigator.prototype.getUserMedia(constraints, successCallback, errorCallback)

Beschreibung

navigator.getUserMedia() war die ursprüngliche Schnittstelle von WebRTC, um auf Medien-Eingabegeräte zuzugreifen. Der Browser fragt den Benutzer, ob die Seite bis zu ein Videoeingabegerät (Kamera) und bis zu ein Audioeingabegerät (Mikrofon) verwenden darf. Stimmt der Benutzer zu, wird successCallback mit einem MediaStream aufgerufen. Bei Ablehnung oder wenn kein passendes Gerät vorhanden ist, wird errorCallback aufgerufen.

Die Methode ist veraltet und darf in neuem Code nicht mehr verwendet werden. Ihr Nachfolger ist navigator.mediaDevices.getUserMedia(). Dieser gibt ein Promise zurück und lässt sich deshalb mit async/await nutzen. Viele aktuelle Browser haben die alte Variante bereits entfernt oder bieten sie nur noch mit Präfix an (webkitGetUserMedia, mozGetUserMedia).

Heute begegnet man der Methode vor allem in Altcode und in Polyfills. Wer solchen Code pflegt, sollte ihn auf die Promise-API umstellen. Wenn wirklich sehr alte Browser unterstützt werden müssen, kann man die alte Methode in ein Promise verpacken.

Parameter

Name	Typ	Beschreibung
$constraints Pflicht	MediaStreamConstraints	Objekt mit den Schlüsseln `video` und/oder `audio`. Jeder Wert ist entweder `true`/`false` oder ein Objekt mit genaueren Anforderungen, z. B. `{ width: 1280, height: 720, facingMode: 'user' }`. Mindestens einer der beiden Schlüssel muss angefordert werden.
$successCallback Pflicht	(stream: MediaStream) => void	Wird bei Erfolg mit dem erhaltenen `MediaStream` aufgerufen. Den Stream kann man z. B. über `srcObject` einem `<video>`-Element zuweisen.
$errorCallback Pflicht	(error: DOMException) => void	Wird bei einem Fehler aufgerufen, z. B. mit `NotAllowedError` (Zugriff verweigert), `NotFoundError` (kein Gerät vorhanden) oder `OverconstrainedError` (Anforderungen nicht erfüllbar).

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert. Das Ergebnis kommt ausschließlich über die beiden Callbacks.

Beispiele

Altcode: Kamera in einem Video-Element anzeigen

// Veraltete API mit Fallback auf Präfix-Varianten
const legacyGetUserMedia =
  navigator.getUserMedia ||
  navigator.webkitGetUserMedia ||
  navigator.mozGetUserMedia;

const video = document.querySelector('video');

if (legacyGetUserMedia) {
  legacyGetUserMedia.call(
    navigator,
    { video: { width: 1280, height: 720 }, audio: false },
    (stream) => {
      video.srcObject = stream;
      video.onloadedmetadata = () => video.play();
    },
    (err) => console.error(`Fehler: ${err.name}`)
  );
} else {
  console.warn('getUserMedia wird nicht unterstützt');
}

Kamera-Bild erscheint im Video-Element, oder z. B. "Fehler: NotAllowedError"

Moderner Ersatz mit mediaDevices und async/await

const startCamera = async () => {
  try {
    const stream = await navigator.mediaDevices.getUserMedia({
      video: { facingMode: 'user' },
      audio: true
    });
    document.querySelector('video').srcObject = stream;
    console.log('Tracks:', stream.getTracks().map((t) => t.kind));
  } catch (err) {
    console.error(`Zugriff fehlgeschlagen: ${err.name}`);
  }
};

startCamera();

Tracks: ["audio", "video"]

Promise-Wrapper für Altbrowser (Polyfill-Muster)

const getMedia = (constraints) => {
  if (navigator.mediaDevices?.getUserMedia) {
    return navigator.mediaDevices.getUserMedia(constraints);
  }
  const legacy = navigator.getUserMedia ||
    navigator.webkitGetUserMedia ||
    navigator.mozGetUserMedia;
  if (!legacy) {
    return Promise.reject(new Error('getUserMedia nicht verfügbar'));
  }
  return new Promise((resolve, reject) =>
    legacy.call(navigator, constraints, resolve, reject)
  );
};

const stream = await getMedia({ audio: true });
console.log(stream.active);
// Aufräumen: Mikrofon wieder freigeben
stream.getTracks().forEach((track) => track.stop());

true

// Wichtig · Fallstricke

Veraltet: Die Methode ist aus dem Standard entfernt worden. In Chrome und Safari ist sie ohne Präfix nicht mehr vorhanden, in Firefox steht sie nur noch aus Kompatibilitätsgründen zur Verfügung. Verwende navigator.mediaDevices.getUserMedia(), das seit Langem in allen modernen Browsern unterstützt wird.
Sicherer Kontext: Der Zugriff auf Kamera und Mikrofon funktioniert nur über HTTPS oder auf localhost. Über HTTP ist die API nicht verfügbar oder schlägt fehl.
Kontext von this: Wenn du die Präfix-Varianten einer Variablen zuweist, musst du sie mit .call(navigator, …) aufrufen. Sonst gibt es einen TypeError: Illegal invocation.
Iframes: Eingebettete Frames brauchen die Berechtigung über allow="camera; microphone" (Permissions Policy).
Datenschutz: Hol dir den Zugriff erst, wenn der Benutzer eine Aktion ausgelöst hat, und beende die Tracks mit track.stop(), sobald du sie nicht mehr brauchst. Sonst bleibt die Aufnahme-Anzeige des Geräts aktiv.
Die alte Methode verwendet teils ältere Fehlernamen, z. B. PermissionDeniedError statt NotAllowedError.

Siehe auch

Sanitizer.removeUnsafe() Navigator.getBattery() Navigator.getGamepads() Navigator.setAppBadge() Navigator.canShare()