ImageDecoder.tracks — Eigenschaft · JavaScript-Referenz

Signatur

ImageDecoder.tracks

Beschreibung

ImageDecoder.tracks gibt ein ImageTrackList-Objekt zurück, das die im Bild enthaltenen Spuren beschreibt. Die meisten Formate haben genau eine Spur. Manche Container wie AVIF oder animiertes WebP bzw. GIF können aber mehrere Spuren oder eine animierte Spur enthalten, etwa ein Standbild und zusätzlich eine Animationssequenz.

Die Liste ist erst dann vollständig befüllt, wenn das Promise tracks.ready erfüllt ist. Danach stehen length, selectedIndex, selectedTrack und der Zugriff per Index (tracks[0]) zur Verfügung. Jedes Element ist ein ImageTrack mit den Eigenschaften animated, frameCount, repetitionCount und selected.

Brauchbar ist die Eigenschaft vor allem dann, wenn du vor dem Decodieren wissen willst, ob ein Bild animiert ist und wie viele Frames es hat, oder wenn du gezielt eine andere Spur auswählen möchtest. Dafür setzt du track.selected = true. Nachfolgende decode()-Aufrufe beziehen sich immer auf die ausgewählte Spur.

Rückgabewert

Typ

ImageTrackList

Beschreibung

Eine live aktualisierte Liste von ImageTrack-Objekten mit ready (Promise<void>), length, selectedIndex und selectedTrack.

Beispiele

Prüfen, ob ein Bild animiert ist

const response = await fetch('/bilder/animation.gif');
const decoder = new ImageDecoder({
  data: response.body,
  type: 'image/gif'
});

// Warten, bis die Spurinformationen verfügbar sind
await decoder.tracks.ready;

const track = decoder.tracks.selectedTrack;
console.log('Spuren:', decoder.tracks.length);
console.log('Animiert:', track.animated);
console.log('Wiederholungen:', track.repetitionCount);

Spuren: 1 Animiert: true Wiederholungen: Infinity

Alle Spuren auflisten und die animierte Spur auswählen

const blob = await (await fetch('/bilder/foto.avif')).blob();
const decoder = new ImageDecoder({
  data: await blob.arrayBuffer(),
  type: 'image/avif'
});

await decoder.tracks.ready;

for (let i = 0; i < decoder.tracks.length; i++) {
  const t = decoder.tracks[i];
  console.log(`Spur ${i}: animiert=${t.animated}, Frames=${t.frameCount}`);
}

// Die erste animierte Spur auswählen, falls es eine gibt
const animierteSpur = Array.from(
  { length: decoder.tracks.length },
  (_, i) => decoder.tracks[i]
).find((t) => t.animated);

if (animierteSpur) animierteSpur.selected = true;
console.log('Ausgewählt:', decoder.tracks.selectedIndex);

Spur 0: animiert=false, Frames=1 Spur 1: animiert=true, Frames=24 Ausgewählt: 1

Alle Frames der ausgewählten Spur auf ein Canvas zeichnen

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

const response = await fetch('/bilder/lader.webp');
const decoder = new ImageDecoder({ data: response.body, type: 'image/webp' });

// Bei Streams erst warten, bis alle Daten da sind: dann ist frameCount endgültig
await decoder.completed;
const { frameCount } = decoder.tracks.selectedTrack;

for (let frameIndex = 0; frameIndex < frameCount; frameIndex++) {
  const { image } = await decoder.decode({ frameIndex });
  ctx.drawImage(image, 0, 0);
  image.close(); // VideoFrame sofort freigeben
}
console.log(`${frameCount} Frames gezeichnet`);

12 Frames gezeichnet

// Wichtig · Fallstricke

Erst auf ready warten: Direkt nach dem Konstruktor ist die Liste oft noch leer (length === 0), und selectedTrack ist null. Nutze deshalb immer vorher await decoder.tracks.ready.
frameCount kann wachsen: Wenn die Daten als ReadableStream kommen, steigt frameCount weiter an, solange noch Daten nachgeladen werden. Den endgültigen Wert bekommst du erst nach await decoder.completed.
ImageTrackList ist kein echtes Array. Methoden wie map oder find gibt es nicht. Nutze Indexzugriff oder Array.from({ length }, …).
Wird die Spur gewechselt (selected = true), verwirft der Decoder laufende Decodierungen. Noch offene decode()-Promises werden dann abgelehnt.
Nach decoder.close() sind die Spurinformationen nicht mehr gültig.
Kompatibilität: Die Eigenschaft gehört zur WebCodecs-API und ist nur in sicheren Kontexten (HTTPS) verfügbar, im Fenster ebenso wie in Workern. Chromium-Browser unterstützen sie seit Version 94. In Firefox ist sie erst in neueren Versionen vorhanden, in Safari nicht bzw. nur eingeschränkt. Prüfe die Unterstützung vorab mit 'ImageDecoder' in window und dem gewünschten Format mit ImageDecoder.isTypeSupported(type).

Siehe auch

ImageDecoder.type ImageDecoder.complete ImageDecoder.completed ImageCapture.track AudioDecoder.state