ImageCapture.track — Eigenschaft · JavaScript-Referenz

Signatur

ImageCapture.track

Beschreibung

Die Eigenschaft track eines ImageCapture-Objekts liefert eine Referenz auf den Video-MediaStreamTrack, mit dem die Instanz erstellt wurde. Die Eigenschaft ist schreibgeschützt: Welcher Track zu einer Instanz gehört, steht nach dem Konstruktor-Aufruf fest und lässt sich nicht mehr ändern.

Nützlich ist track vor allem dann, wenn man nur noch das ImageCapture-Objekt zur Hand hat, aber auf den zugrunde liegenden Track zugreifen muss, etwa um die Kamera mit track.stop() auszuschalten, den Zustand über track.readyState zu prüfen, Kameraeinstellungen mit track.getSettings() und track.getCapabilities() auszulesen oder Einschränkungen wie Zoom oder Taschenlampe per track.applyConstraints() zu setzen.

Zurückgegeben wird dasselbe Objekt (gleiche Identität), keine Kopie. Änderungen am Track, zum Beispiel enabled = false oder stop(), wirken sich daher direkt auf alle anderen Stellen aus, die ihn verwenden, etwa ein <video>-Element, das denselben Stream anzeigt.

Rückgabewert

Typ

MediaStreamTrack

Beschreibung

Der Video-MediaStreamTrack (kind === "video"), der dem Konstruktor new ImageCapture(track) übergeben wurde.

Beispiele

Track über die ImageCapture-Instanz abrufen

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

// Es wird dasselbe Objekt zurückgegeben
console.log(imageCapture.track === videoTrack);
console.log(imageCapture.track.kind, imageCapture.track.readyState);

true video live

Foto aufnehmen und danach die Kamera ausschalten

const takePhotoAndStop = async (imageCapture) => {
  if (imageCapture.track.readyState !== 'live') {
    throw new Error('Kamera-Track ist nicht mehr aktiv');
  }
  const blob = await imageCapture.takePhoto();
  // Kamera freigeben, die Kontroll-LED erlischt
  imageCapture.track.stop();
  return URL.createObjectURL(blob);
};

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const capture = new ImageCapture(stream.getVideoTracks()[0]);
document.querySelector('img').src = await takePhotoAndStop(capture);
console.log(capture.track.readyState);

ended

Zoom über den Track einstellen, falls unterstützt

const setZoom = async (imageCapture, factor) => {
  const { track } = imageCapture;
  const caps = track.getCapabilities();
  if (!('zoom' in caps)) {
    console.log('Zoom wird von dieser Kamera nicht unterstützt');
    return;
  }
  const zoom = Math.min(caps.zoom.max, Math.max(caps.zoom.min, factor));
  await track.applyConstraints({ advanced: [{ zoom }] });
  console.log('Zoom:', track.getSettings().zoom);
};

const stream = await navigator.mediaDevices.getUserMedia({ video: { pan: true, tilt: true, zoom: true } });
await setZoom(new ImageCapture(stream.getVideoTracks()[0]), 2);

Zoom: 2

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Image Capture API gibt es nur in Chromium-basierten Browsern (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari kennen ImageCapture nicht. Prüfe deshalb vorher mit 'ImageCapture' in window, ob die API vorhanden ist.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wie imageCapture.track = other wird im nicht-strikten Modus stillschweigend ignoriert. Für einen anderen Track brauchst du eine neue ImageCapture-Instanz.
Nach imageCapture.track.stop() hat der Track den readyState "ended". Aufrufe von takePhoto() und grabFrame() schlagen dann mit einem InvalidStateError fehl.
Der Konstruktor akzeptiert nur Video-Tracks. Wird ein Audio-Track übergeben, wirft er einen NotSupportedError.
getUserMedia() funktioniert nur in sicheren Kontexten (HTTPS oder localhost) und nur, wenn der Nutzer den Kamerazugriff erlaubt.

Siehe auch

ImageCapture ImageCapture.prototype.takePhoto() ImageCapture.prototype.grabFrame() MediaStreamTrack MediaDevices.prototype.getUserMedia() ImageTrack.animated