Start · Sprachen · JavaScript · Referenz · VideoDecoder.configure()

VideoDecoder.configure()

Methode

Reiht eine Steuernachricht ein, die den <code>VideoDecoder</code> mit Codec, Auflösung und optionalen Codec-Daten für das Decodieren von <code>EncodedVideoChunk</code>s konfiguriert.

seit JavaScript WebCodecs API – Chrome/Edge 94+, Safari 16.4+ (tei Kategorie: webapi

Signatur

VideoDecoder.prototype.configure(config)

Beschreibung

configure() legt fest, wie ein VideoDecoder die folgenden EncodedVideoChunk-Objekte decodieren soll: welcher Codec verwendet wird (z. B. H.264, VP9, AV1), welche Codec-spezifischen Initialisierungsdaten (description, etwa der avcC-Block aus einem MP4-Container) nötig sind und welche Hinweise zu Auflösung, Farbraum oder Hardwarebeschleunigung gelten.

Die Methode arbeitet asynchron über die interne Steuerwarteschlange: Sie kehrt sofort zurück, setzt decoder.state synchron auf "configured" und verarbeitet die Konfiguration anschließend im Hintergrund. Schlägt die Konfiguration fehl (z. B. weil der Codec nicht unterstützt wird), wird der im Konstruktor übergebene error-Callback mit einer NotSupportedError-DOMException aufgerufen und der Decoder geschlossen.

Nach jedem configure() muss der erste decodierte Chunk ein Schlüsselbild (type: "key") sein. Man kann configure() mehrfach aufrufen, etwa bei Auflösungs- oder Codec-Wechseln im Stream; bereits eingereihte Chunks werden vorher noch mit der alten Konfiguration abgearbeitet. Vorab sollte man mit der statischen Methode VideoDecoder.isConfigSupported() prüfen, ob die Konfiguration überhaupt unterstützt wird.

Parameter

Name Typ Default Beschreibung
$config Pflicht VideoDecoderConfig Konfigurationsobjekt mit folgenden Feldern:
  • codec (string, Pflicht): Codec-String, z. B. "avc1.42E01E", "vp09.00.10.08", "av01.0.04M.08".
  • description (ArrayBuffer | TypedArray | DataView, optional): Codec-spezifische Initialisierungsdaten, z. B. avcC/hvcC-Box. Fehlt sie bei H.264, wird das Annex-B-Format erwartet.
  • codedWidth, codedHeight (number, optional): Codierte Bildgröße in Pixeln.
  • displayAspectWidth, displayAspectHeight (number, optional): Seitenverhältnis für die Anzeige.
  • colorSpace (VideoColorSpaceInit, optional): Farbraum-Angaben (primaries, transfer, matrix, fullRange).
  • hardwareAcceleration ("no-preference" | "prefer-hardware" | "prefer-software", optional, Standard "no-preference").
  • optimizeForLatency (boolean, optional): Bittet den Decoder, Frames möglichst ohne Pufferung auszugeben (wichtig für Echtzeit-Streams).

Beispiele

VP9-Decoder konfigurieren und Frames auf ein Canvas zeichnen

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

const decoder = new VideoDecoder({
  output: (frame) => {
    ctx.drawImage(frame, 0, 0);
    frame.close(); // Speicher sofort freigeben!
  },
  error: (e) => console.error('Decoder-Fehler:', e.message)
});

decoder.configure({
  codec: 'vp09.00.10.08',
  codedWidth: 1280,
  codedHeight: 720
});

console.log(decoder.state);
configured

Unterstützung vorab prüfen und Hardware bevorzugen

const config = {
  codec: 'avc1.64001F', // H.264 High Profile, Level 3.1
  codedWidth: 1920,
  codedHeight: 1080,
  hardwareAcceleration: 'prefer-hardware'
};

const setupDecoder = async () => {
  const { supported, config: normalized } = await VideoDecoder.isConfigSupported(config);
  if (!supported) {
    console.warn('Konfiguration nicht unterstützt:', config.codec);
    return null;
  }
  const decoder = new VideoDecoder({
    output: (frame) => frame.close(),
    error: console.error
  });
  decoder.configure(normalized);
  return decoder;
};

setupDecoder().then((d) => console.log(d?.state ?? 'kein Decoder'));
configured

H.264 aus MP4 mit avcC-Beschreibung und Echtzeit-Modus

// avcCBytes stammt z. B. aus einem MP4-Demuxer (mp4box.js)
const configureFromTrack = (decoder, track, avcCBytes) => {
  decoder.configure({
    codec: track.codec,          // z. B. 'avc1.42E01E'
    codedWidth: track.video.width,
    codedHeight: track.video.height,
    description: avcCBytes,      // Uint8Array mit avcC-Box-Inhalt
    optimizeForLatency: true
  });
};

const decoder = new VideoDecoder({ output: (f) => f.close(), error: console.error });
configureFromTrack(
  decoder,
  { codec: 'avc1.42E01E', video: { width: 640, height: 360 } },
  new Uint8Array([0x01, 0x42, 0xe0, 0x1e, 0xff, 0xe1])
);
// Erster Chunk nach configure() muss ein Schlüsselbild sein
console.log(decoder.state);
configured

// Wichtig · Fallstricke

  • Ausnahmen: TypeError, wenn config ungültig ist (z. B. leerer codec-String, codedWidth ohne codedHeight, abgelöste description). InvalidStateError, wenn der Decoder bereits \"closed\" ist.
  • Ein nicht unterstützter Codec wirft keine synchrone Ausnahme, sondern führt asynchron zum error-Callback (NotSupportedError) und schließt den Decoder. Deshalb vorher VideoDecoder.isConfigSupported() verwenden.
  • Nach jedem configure() muss zuerst ein Schlüsselbild decodiert werden, sonst gibt es einen DataError.
  • Ausgegebene VideoFrames müssen mit close() freigegeben werden, sonst blockiert der Decoder, weil der Frame-Pool (oft GPU-Speicher) erschöpft ist.
  • Der Codec-String muss exakt sein (Profil/Level), ein bloßes \"avc1\" oder \"vp9\" ist ungültig.
  • Kompatibilität: WebCodecs ist nur in sicheren Kontexten (HTTPS) sowie in Window und Dedicated Workern verfügbar. Chromium seit Version 94, Firefox seit 130 (Desktop), Safari mit eingeschränkter Codec-Unterstützung. Feature-Erkennung per 'VideoDecoder' in globalThis.