ImageCapture.getPhotoSettings() — Methode · JavaScript-Referenz

Signatur

ImageCapture.prototype.getPhotoSettings()

Beschreibung

Die Methode getPhotoSettings() der Schnittstelle ImageCapture liest die Einstellungen aus, die für die nächste Aufnahme mit takePhoto() gelten. Das Promise wird mit einem PhotoSettings-Objekt erfüllt. Es enthält diese Eigenschaften:

fillLightMode: Blitzmodus, "auto", "off" oder "flash".
imageHeight und imageWidth: Auflösung des Fotos in Pixeln.
redEyeReduction: true oder false, je nachdem, ob die Rote-Augen-Korrektur aktiv ist.

Die Methode ist das Gegenstück zu getPhotoCapabilities(). Diese liefert die möglichen Werte, getPhotoSettings() die aktuell eingestellten. So kannst du zum Beispiel die UI mit den aktuellen Werten füllen, bevor der Nutzer die Einstellungen ändert und du sie als photoSettings-Argument an takePhoto() übergibst.

Welche Eigenschaften tatsächlich im Objekt stehen, hängt von der Kamera und dem Treiber ab. Fehlende Eigenschaften bedeuten, dass das Gerät die jeweilige Einstellung nicht meldet oder nicht unterstützt.

Rückgabewert

Typ

Promise<PhotoSettings>

Beschreibung

Ein Promise, das mit einem Objekt mit den Eigenschaften fillLightMode, imageHeight, imageWidth und redEyeReduction erfüllt wird. Das Promise wird mit einer InvalidStateError-DOMException abgelehnt, wenn der zugehörige MediaStreamTrack nicht mehr aktiv ist (readyState !== "live"). Kann das Gerät die Werte nicht liefern, wird es mit einer OperationError abgelehnt.

Beispiele

Aktuelle Fotoeinstellungen auslesen

const zeigeFotoEinstellungen = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({ video: true });
  const [track] = stream.getVideoTracks();
  const imageCapture = new ImageCapture(track);

  const settings = await imageCapture.getPhotoSettings();
  console.log('Auflösung:', `${settings.imageWidth}x${settings.imageHeight}`);
  console.log('Blitz:', settings.fillLightMode);
  console.log('Rote-Augen-Korrektur:', settings.redEyeReduction);

  track.stop(); // Kamera wieder freigeben
};

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

Auflösung: 1280x720 Blitz: off Rote-Augen-Korrektur: false

Einstellungen mit den Fähigkeiten abgleichen und maximale Auflösung wählen

const fotoInMaxAufloesung = async (track) => {
  const imageCapture = new ImageCapture(track);

  const [capabilities, settings] = await Promise.all([
    imageCapture.getPhotoCapabilities(),
    imageCapture.getPhotoSettings()
  ]);

  const maxBreite = capabilities.imageWidth.max;
  console.log(`Aktuell: ${settings.imageWidth}px, möglich: ${maxBreite}px`);

  // Aktuelle Einstellungen übernehmen, nur die Breite erhöhen
  const blob = await imageCapture.takePhoto({
    ...settings,
    imageWidth: maxBreite
  });
  console.log('Fotogröße:', blob.size, 'Bytes');
  return blob;
};

Aktuell: 1280px, möglich: 4032px Fotogröße: 2345678 Bytes

Feature-Erkennung und Fehler bei beendetem Track

const pruefeEinstellungen = async () => {
  if (!('ImageCapture' in window)) {
    console.warn('ImageCapture wird in diesem Browser nicht unterstützt.');
    return;
  }
  const stream = await navigator.mediaDevices.getUserMedia({ video: true });
  const [track] = stream.getVideoTracks();
  const imageCapture = new ImageCapture(track);

  track.stop(); // Track beendet: readyState ist jetzt "ended"

  try {
    await imageCapture.getPhotoSettings();
  } catch (err) {
    console.log('Fehler:', err.name);
  }
};

pruefeEinstellungen();

Fehler: InvalidStateError

// Wichtig · Fallstricke

Browser-Unterstützung: Die Image Capture API gibt es nur in Chromium-Browsern (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer mit 'ImageCapture' in window, ob sie verfügbar ist.
Sicherer Kontext: getUserMedia() funktioniert nur über HTTPS (oder localhost) und braucht die Kamera-Erlaubnis des Nutzers.
Die Werte beziehen sich auf die Fotoaufnahme mit takePhoto(), nicht auf den laufenden Video-Stream. Die Einstellungen des Videos liest du mit MediaStreamTrack.getSettings() aus. Zoom, Fokus, Belichtung und Taschenlampe (torch) sind Track-Constraints und stehen daher nicht in PhotoSettings.
Die gemeldeten Werte können je nach Gerät und Treiber unvollständig sein. Prüfe einzelne Eigenschaften immer auf undefined.
Rufst du die Methode auf einem beendeten Track auf, wird das Promise mit InvalidStateError abgelehnt. Prüfe vorher track.readyState === "live".

Siehe auch

ImageCapture ImageCapture.getPhotoCapabilities() ImageCapture.takePhoto() ImageCapture.grabFrame() MediaStreamTrack.getSettings() MediaDevices.getUserMedia()