new ImageCapture() — Methode · JavaScript-Referenz

Signatur

new ImageCapture(videoTrack)

Beschreibung

Der Konstruktor ImageCapture() gehört zur MediaStream Image Capture API. Er nimmt einen Video-MediaStreamTrack entgegen, typischerweise von navigator.mediaDevices.getUserMedia(), und gibt ein ImageCapture-Objekt zurück, das an genau diese Videoquelle (z. B. eine Kamera) gebunden ist.

Mit dem Objekt stehen zwei Aufnahmewege zur Verfügung:

takePhoto() löst eine echte Fotoaufnahme aus und liefert einen Blob. Je nach Gerät hat das Foto eine höhere Auflösung als der Videostream, und Blitz, Rote-Augen-Reduktion oder Auflösung lassen sich einstellen.
grabFrame() nimmt den aktuellen Frame des Videostreams schnell als ImageBitmap auf. Das eignet sich gut für Bildverarbeitung, Canvas-Ausgabe oder Machine Learning.

Außerdem liefern getPhotoCapabilities() und getPhotoSettings() Angaben dazu, was die Kamera unterstützt und wie sie gerade eingestellt ist. Wichtig: Der übergebene Track muss vom Typ "video" sein und darf nicht beendet sein (readyState === "live").

Parameter

Name	Typ	Default	Beschreibung
$videoTrack Pflicht	MediaStreamTrack		Ein Video-Track (`kind === "video"`), aus dem Bilder aufgenommen werden sollen, z. B. aus `stream.getVideoTracks()[0]`.

Rückgabewert

Typ

ImageCapture

Beschreibung

Ein neues ImageCapture-Objekt, das an den übergebenen Video-Track gebunden ist. Der Track ist über die Eigenschaft track erreichbar.

Beispiele

ImageCapture aus der Webcam erzeugen

const startCapture = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({ video: true });
  const [track] = stream.getVideoTracks();
  const imageCapture = new ImageCapture(track);
  console.log(imageCapture.track.kind, imageCapture.track.readyState);
  return imageCapture;
};

startCapture().catch((err) => console.error('Kamera nicht verfügbar:', err));

video live

Foto aufnehmen und im <img> anzeigen

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

  const blob = await imageCapture.takePhoto();
  const img = document.querySelector('#photo');
  img.src = URL.createObjectURL(blob);
  console.log(`Foto: ${blob.type}, ${blob.size} Bytes`);

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

document.querySelector('#snap').addEventListener('click', takeSnapshot);

Foto: image/jpeg, 184233 Bytes

Frame als ImageBitmap auf Canvas zeichnen (mit Feature-Erkennung)

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

  const bitmap = await imageCapture.grabFrame();
  canvas.width = bitmap.width;
  canvas.height = bitmap.height;
  canvas.getContext('2d').drawImage(bitmap, 0, 0);
  bitmap.close();
  console.log(`Frame: ${canvas.width}x${canvas.height}`);
};

drawFrame(document.querySelector('canvas'));

Frame: 640x480

Kamera-Fähigkeiten abfragen

const showCapabilities = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({ video: true });
  const imageCapture = new ImageCapture(stream.getVideoTracks()[0]);
  const caps = await imageCapture.getPhotoCapabilities();
  console.log('Max. Breite:', caps.imageWidth.max);
  console.log('Blitzmodi:', caps.fillLightMode);
};

showCapabilities();

Max. Breite: 1920 Blitzmodi: ["off"]

// Wichtig · Fallstricke

Browser-Kompatibilität: ImageCapture gibt es nur in Chromium-basierten Browsern (Chrome, Edge, Opera, Chrome für Android). Firefox und Safari unterstützen die API nicht. Deshalb vorher mit 'ImageCapture' in window prüfen und notfalls auf <video> plus canvas.drawImage() ausweichen.
Wird ein Track übergeben, der kein Video-Track ist (z. B. Audio), wirft der Konstruktor einen NotSupportedError (DOMException); ohne Argument gibt es einen TypeError.
getUserMedia() funktioniert nur in einem sicheren Kontext (HTTPS oder localhost) und braucht die Kamerafreigabe durch den Nutzer. In iframes muss außerdem die Permissions Policy camera erlaubt sein.
Ist der Track beendet (track.stop() oder readyState === "ended"), schlagen takePhoto() und grabFrame() mit InvalidStateError fehl.
takePhoto() kann den Videostream kurz unterbrechen oder die Kamera neu einstellen. Für schnelle, wiederholte Aufnahmen ist grabFrame() die bessere Wahl. Zurückgegebene ImageBitmap-Objekte sollten mit close() freigegeben werden.
Die API ist noch als experimentell gekennzeichnet. Einzelne Fähigkeiten wie Blitz oder Rote-Augen-Reduktion hängen stark vom Gerät ab.

Siehe auch

new ImageData() new Image() new ImageDecoder() new DataCue() new DragEvent()