ImageCapture.getPhotoCapabilities() — Methode · JavaScript-Referenz

Signatur

ImageCapture.prototype.getPhotoCapabilities()

Beschreibung

getPhotoCapabilities() fragt bei der Kamera hinter einem ImageCapture-Objekt nach, welche Einstellungen für Standbilder möglich sind. Das Promise wird mit einem PhotoCapabilities-Objekt erfüllt. Es hat folgende Eigenschaften:

imageWidth und imageHeight: jeweils ein MediaSettingsRange mit min, max und step. Sie geben die möglichen Fotoauflösungen in Pixeln an.
redEyeReduction: "never", "always" oder "controllable". Nur bei "controllable" lässt sich die Rote-Augen-Korrektur selbst ein- oder ausschalten.
fillLightMode: ein Array aus "auto", "off" und "flash". Es gibt an, welche Blitzmodi unterstützt werden.

Die Methode wird typischerweise vor takePhoto(photoSettings) aufgerufen. So lassen sich gültige Werte für photoSettings bestimmen, etwa die höchste Auflösung. Mit den Werten kann man auch Bedienelemente wie Schieberegler oder Blitz-Auswahl dynamisch aufbauen.

Die Methode betrifft nur Fotos. Einstellungen des laufenden Videostreams (Zoom, Fokus, Belichtung, Schwenken/Neigen) beschreibt MediaStreamTrack.getCapabilities(). Ändern lassen sie sich mit applyConstraints().

Rückgabewert

Typ

Promise<PhotoCapabilities>

Beschreibung

Ein Promise, das mit einem PhotoCapabilities-Objekt (imageWidth, imageHeight, redEyeReduction, fillLightMode) erfüllt wird. Es wird mit einer InvalidStateError-DOMException abgelehnt, wenn der Videotrack nicht mehr "live" ist, und mit OperationError, wenn die Werte nicht abgefragt werden können.

Beispiele

Fotoeinstellungen der Kamera abfragen

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

const caps = await imageCapture.getPhotoCapabilities();
console.log('Breite:', caps.imageWidth);
console.log('Höhe:', caps.imageHeight);
console.log('Blitzmodi:', caps.fillLightMode);
console.log('Rote-Augen-Korrektur:', caps.redEyeReduction);

Breite: { max: 4032, min: 640, step: 1 } Höhe: { max: 3024, min: 480, step: 1 } Blitzmodi: ['auto', 'off', 'flash'] Rote-Augen-Korrektur: controllable (Die Werte hängen vom Gerät ab.)

Foto in maximaler Auflösung mit Blitz aufnehmen

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

  try {
    const caps = await imageCapture.getPhotoCapabilities();
    const settings = {
      imageWidth: caps.imageWidth.max,
      imageHeight: caps.imageHeight.max
    };
    // Blitz nur setzen, wenn er unterstützt wird
    if (caps.fillLightMode?.includes('flash')) {
      settings.fillLightMode = 'flash';
    }
    const blob = await imageCapture.takePhoto(settings);
    console.log(`Foto: ${blob.size} Bytes, Typ ${blob.type}`);
    return blob;
  } finally {
    track.stop(); // Kamera wieder freigeben
  }
};

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

Foto: 2345678 Bytes, Typ image/jpeg

Schieberegler für die Fotobreite aus den Werten aufbauen

const setupWidthSlider = async (imageCapture) => {
  const slider = document.querySelector('#photo-width');
  const { imageWidth } = await imageCapture.getPhotoCapabilities();

  slider.min = imageWidth.min;
  slider.max = imageWidth.max;
  slider.step = imageWidth.step;
  slider.value = imageWidth.max;

  const photoBtn = document.querySelector('#snap');
  photoBtn.addEventListener('click', async () => {
    const blob = await imageCapture.takePhoto({ imageWidth: Number(slider.value) });
    document.querySelector('#preview').src = URL.createObjectURL(blob);
  });
};

if ('ImageCapture' in window) {
  const stream = await navigator.mediaDevices.getUserMedia({ video: true });
  await setupWidthSlider(new ImageCapture(stream.getVideoTracks()[0]));
} else {
  console.warn('ImageCapture wird in diesem Browser nicht unterstützt.');
}

// Wichtig · Fallstricke

Browser-Unterstützung: Die API gibt es nur in Chromium-Browsern (Chrome, Edge, Opera, Chrome für Android). Firefox und Safari haben kein ImageCapture. Deshalb vorher mit 'ImageCapture' in window prüfen und sonst ein Standbild über <canvas> und drawImage() aus dem <video>-Element erzeugen.
Sicherer Kontext: Die Methode funktioniert nur über HTTPS oder localhost. Außerdem muss der Nutzer den Kamerazugriff über getUserMedia() erlaubt haben.
Track muss aktiv sein: Nach track.stop() oder wenn die Kamera getrennt wurde, wird das Promise mit InvalidStateError abgelehnt.
Werte hängen vom Gerät ab: fillLightMode kann ein leeres Array sein, etwa bei Webcams ohne Blitz. Die Auflösungsbereiche können sich zwischen den Kameras eines Geräts stark unterscheiden. Nie fest verdrahtete Werte an takePhoto() übergeben.
Nicht mit Track-Fähigkeiten verwechseln: Zoom, Fokus oder Taschenlampe (torch) stehen nicht hier, sondern in MediaStreamTrack.getCapabilities().
Auf manchen Geräten dauert der Aufruf spürbar lange, weil die Kamera kurz umkonfiguriert wird. Das Ergebnis am besten einmal zwischenspeichern.

Siehe auch

ImageCapture.getPhotoSettings() ImageCapture.grabFrame() ImageCapture.takePhoto() RTCRtpSender.getCapabilities() RTCRtpReceiver.getCapabilities()