Signatur
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:
|
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);
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'));
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);
// Wichtig · Fallstricke
- Ausnahmen:
TypeError, wennconfigungültig ist (z. B. leerercodec-String,codedWidthohnecodedHeight, abgelöstedescription).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 vorherVideoDecoder.isConfigSupported()verwenden. - Nach jedem
configure()muss zuerst ein Schlüsselbild decodiert werden, sonst gibt es einenDataError. - Ausgegebene
VideoFrames müssen mitclose()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.