MediaTrackConstraints.facingMode — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackConstraints.facingMode

Beschreibung

Die Eigenschaft facingMode des Dictionaries MediaTrackConstraints ist ein ConstrainDOMString. Damit gibst du an, in welche Richtung die Kamera zeigen soll, wenn du über navigator.mediaDevices.getUserMedia() oder MediaStreamTrack.applyConstraints() einen Video-Stream anforderst. Das ist vor allem auf Smartphones und Tablets nützlich, um gezielt zwischen Front- und Rückkamera zu wählen, ohne die Geräte-IDs zu kennen.

Erlaubte Werte sind:

"user" – Kamera zeigt zum Nutzer (Frontkamera, Selfie).
"environment" – Kamera zeigt vom Nutzer weg (Rückkamera, z. B. für Barcode-Scanner).
"left" / "right" – Kamera zeigt nach links bzw. rechts vom Nutzer (selten unterstützt).

Der Wert kann als einfacher String, als Array von Strings oder als Objekt mit ideal bzw. exact angegeben werden. Ein einfacher String oder ideal ist nur eine Bevorzugung – der Browser liefert notfalls eine andere Kamera. Mit exact wird die Einschränkung zwingend; ist keine passende Kamera vorhanden, schlägt der Aufruf mit einem OverconstrainedError fehl.

Welche Ausrichtung tatsächlich aktiv ist, liest du über MediaStreamTrack.getSettings().facingMode aus. Ob der Browser die Einschränkung überhaupt kennt, verrät navigator.mediaDevices.getSupportedConstraints().facingMode.

Parameter

Name	Typ	Default	Beschreibung
$facingMode	string \| string[] \| { exact?: string \| string[], ideal?: string \| string[] }		Gewünschte Kamera-Ausrichtung: `"user"`, `"environment"`, `"left"` oder `"right"`. Einfacher Wert und `ideal` sind Wünsche, `exact` ist verpflichtend.

Rückgabewert

Typ

ConstrainDOMString

Beschreibung

Der festgelegte Einschränkungswert – ein String, ein String-Array oder ein Objekt mit exact/ideal.

Beispiele

Frontkamera bevorzugt anfordern

const startSelfie = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({
    video: { facingMode: 'user' }
  });
  document.querySelector('video').srcObject = stream;
  const [track] = stream.getVideoTracks();
  console.log('Aktiv:', track.getSettings().facingMode);
};

startSelfie().catch(err => console.error(err.name, err.message));

Aktiv: user

Rückkamera zwingend für Barcode-Scanner, mit Fallback

const openScanner = async () => {
  try {
    return await navigator.mediaDevices.getUserMedia({
      video: { facingMode: { exact: 'environment' } }
    });
  } catch (err) {
    if (err.name === 'OverconstrainedError') {
      console.warn('Keine Rückkamera – nutze beliebige Kamera.');
      return navigator.mediaDevices.getUserMedia({ video: true });
    }
    throw err;
  }
};

openScanner().then(stream => {
  document.querySelector('#scanner').srcObject = stream;
});

Keine Rückkamera – nutze beliebige Kamera. (nur auf Geräten ohne Rückkamera)

Zwischen Front- und Rückkamera umschalten

let currentMode = 'user';
let stream = null;
const video = document.querySelector('video');

const switchCamera = async () => {
  currentMode = currentMode === 'user' ? 'environment' : 'user';
  // Alten Stream zuerst stoppen – viele Mobilgeräte erlauben nur eine offene Kamera
  stream?.getTracks().forEach(t => t.stop());
  stream = await navigator.mediaDevices.getUserMedia({
    video: { facingMode: { ideal: currentMode } }
  });
  video.srcObject = stream;
  console.log('Umgeschaltet auf:', currentMode);
};

document.querySelector('#switch').addEventListener('click', switchCamera);

Umgeschaltet auf: environment

Unterstützung prüfen

const supported = navigator.mediaDevices.getSupportedConstraints();
console.log('facingMode unterstützt:', Boolean(supported.facingMode));

facingMode unterstützt: true

// Wichtig · Fallstricke

Desktop-Geräte: Webcams melden meist keine Ausrichtung. Ein exact-Wert führt dort häufig zu OverconstrainedError; getSettings().facingMode kann undefined sein. Nutze für Desktops lieber ideal oder deviceId.
Mehrere Rückkameras: Moderne Smartphones haben oft Weitwinkel-, Tele- und Ultraweitwinkel-Kameras, die alle "environment" melden. Für eine bestimmte Linse musst du über enumerateDevices() und deviceId gehen.
Umschalten per applyConstraints(): Das Wechseln der physischen Kamera über applyConstraints({ facingMode }) funktioniert nicht zuverlässig in allen Browsern – robuster ist es, den alten Track zu stoppen und getUserMedia() neu aufzurufen.
Sicherer Kontext: getUserMedia() ist nur über HTTPS (oder localhost) verfügbar und erfordert die Zustimmung des Nutzers.
"left" und "right" werden von kaum einem Gerät gemeldet.
Die Frontkamera-Vorschau ist nicht automatisch gespiegelt; für eine Selfie-Ansicht ggf. per CSS transform: scaleX(-1) spiegeln.

Siehe auch

MediaTrackConstraints.deviceId MediaTrackConstraints.frameRate MediaTrackConstraints.height MediaTrackConstraints.latency MediaTrackConstraints.sampleRate