MediaTrackSettings.facingMode — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSettings.facingMode

Beschreibung

Die Eigenschaft facingMode des Wörterbuchs MediaTrackSettings gibt an, in welche Richtung die Kamera der Videospur tatsächlich zeigt. Das Settings-Objekt bekommt man über MediaStreamTrack.getSettings(). Anders als eine Einschränkung (Constraint), die man bei getUserMedia() oder applyConstraints() nur anfordert, steht hier der Wert, den der Browser am Ende eingestellt hat.

Mögliche Werte:

"user": Die Kamera zeigt zum Nutzer (Frontkamera, Selfie-Kamera).
"environment": Die Kamera zeigt vom Nutzer weg (Rückkamera).
"left": Die Kamera zeigt zum Nutzer, aber nach links versetzt.
"right": Die Kamera zeigt zum Nutzer, aber nach rechts versetzt.

Die Eigenschaft ist nützlich, um nach einem Kamerawechsel zu prüfen, welche Kamera wirklich aktiv ist. So kann man z. B. die Vorschau einer Frontkamera spiegeln oder den Wechsel-Button richtig beschriften. Bei Audiospuren und bei Kameras, die ihre Richtung nicht melden (typisch bei Desktop-Webcams), fehlt die Eigenschaft ganz, sie ist dann also undefined.

Rückgabewert

Typ

string | undefined

Beschreibung

Einer der Werte "user", "environment", "left" oder "right". undefined, wenn das Gerät die Richtung nicht meldet oder die Spur keine Videospur ist.

Beispiele

Aktive Kamerarichtung auslesen

const stream = await navigator.mediaDevices.getUserMedia({
  video: { facingMode: 'environment' }
});
const [track] = stream.getVideoTracks();
const { facingMode } = track.getSettings();
console.log(facingMode ?? 'unbekannt');

environment

Vorschau der Frontkamera spiegeln

const video = document.querySelector('video');
const stream = await navigator.mediaDevices.getUserMedia({ video: { facingMode: 'user' } });
video.srcObject = stream;

const track = stream.getVideoTracks()[0];
// Nur spiegeln, wenn wirklich die Selfie-Kamera aktiv ist
const isFront = track.getSettings().facingMode === 'user';
video.classList.toggle('mirrored', isFront);

Zwischen Front- und Rückkamera umschalten

let stream;

const startCamera = async (mode) => {
  stream?.getTracks().forEach((t) => t.stop());
  stream = await navigator.mediaDevices.getUserMedia({
    video: { facingMode: { ideal: mode } }
  });
  document.querySelector('video').srcObject = stream;
  return stream.getVideoTracks()[0].getSettings().facingMode;
};

document.querySelector('#switch').addEventListener('click', async () => {
  const current = stream?.getVideoTracks()[0].getSettings().facingMode;
  const next = current === 'user' ? 'environment' : 'user';
  const actual = await startCamera(next);
  console.log(`Gewünscht: ${next}, aktiv: ${actual ?? 'unbekannt'}`);
});

await startCamera('user');

Gewünscht: environment, aktiv: environment

// Wichtig · Fallstricke

Nicht immer vorhanden: Desktop-Webcams melden meist keine Richtung, dann ist facingMode undefined. Prüfen Sie den Wert immer, bevor Sie sich darauf verlassen, z. B. mit ?? 'unbekannt'.
Gewünschter und tatsächlicher Wert können sich unterscheiden: { facingMode: 'environment' } ist nur eine Bitte an den Browser (ideal). Nur getSettings().facingMode sagt, welche Kamera wirklich aktiv ist. Soll es genau diese Kamera sein, schreiben Sie { exact: 'environment' }. Fehlt die Kamera, schlägt der Aufruf mit OverconstrainedError fehl.
Ob der Browser die Einschränkung überhaupt kennt, prüfen Sie mit navigator.mediaDevices.getSupportedConstraints().facingMode.
Auf manchen Mobilgeräten (vor allem älteren iOS-Versionen) muss der alte Stream erst mit track.stop() beendet werden, bevor eine andere Kamera starten kann.
getUserMedia() läuft nur in einer sicheren Umgebung (HTTPS oder localhost) und braucht die Kamera-Erlaubnis des Nutzers.

Siehe auch

MediaTrackConstraints.facingMode MediaTrackSettings.cursor MediaTrackSettings.deviceId MediaTrackSettings.frameRate MediaTrackSettings.height