VideoDecoder.isConfigSupported() — Methode · JavaScript-Referenz

Signatur

VideoDecoder.isConfigSupported(config)

Beschreibung

Die statische Methode VideoDecoder.isConfigSupported() gehört zur WebCodecs API. Sie prüft, ob der Benutzeragent einen VideoDecoder mit der angegebenen Konfiguration einrichten kann, also ob Codec, Profil, Level, Auflösung und weitere Optionen unterstützt werden. Dabei wird kein Decoder erzeugt und kein Zustand verändert.

Man verwendet sie vor dem Aufruf von VideoDecoder.prototype.configure(). Ist eine Konfiguration nicht unterstützt, schlägt configure() nämlich erst asynchron fehl: Der Decoder wird geschlossen und der error-Callback mit einer NotSupportedError-DOMException aufgerufen. Mit isConfigSupported() lässt sich das vorher klären und bei Bedarf auf einen anderen Codec zurückfallen, zum Beispiel von AV1 auf VP9 oder H.264.

Das zurückgegebene Promise wird mit einem Objekt vom Typ VideoDecoderSupport erfüllt. Es enthält den booleschen Wert supported und eine bereinigte Kopie der Konfiguration (config). In dieser Kopie stehen nur die Felder, die der Browser erkannt hat. Unbekannte Schlüssel fehlen darin.

Parameter

Name	Typ	Default	Beschreibung
$config Pflicht	VideoDecoderConfig		Konfigurationsobjekt mit folgenden Feldern: `codec` (string, Pflichtfeld): Codec-String, z. B. `"avc1.42E01E"`, `"vp09.00.10.08"`, `"av01.0.04M.08"`, `"hev1.1.6.L93.B0"` `description` (BufferSource, optional): codec-spezifische Zusatzdaten, z. B. der `avcC`-Block bei H.264 im AVC-Format `codedWidth` / `codedHeight` (number, optional): kodierte Breite und Höhe in Pixeln `displayAspectWidth` / `displayAspectHeight` (number, optional): Seitenverhältnis bei der Anzeige `colorSpace` (VideoColorSpaceInit, optional): Farbraum-Angaben `hardwareAcceleration` (`"no-preference"` \| `"prefer-hardware"` \| `"prefer-software"`, optional, Standard: `"no-preference"`) `optimizeForLatency` (boolean, optional): Decoder auf möglichst geringe Latenz auslegen

Rückgabewert

Typ

Promise<VideoDecoderSupport>

Beschreibung

Promise, das mit einem Objekt { supported: boolean, config: VideoDecoderConfig } erfüllt wird. config enthält nur die vom Browser erkannten Felder. Das Promise wird mit einem TypeError abgelehnt, wenn die Konfiguration formal ungültig ist, z. B. bei leerem codec oder codedWidth von 0.

Beispiele

Einfache Unterstützungsprüfung für H.264

const config = {
  codec: 'avc1.42E01E', // H.264 Baseline, Level 3.0
  codedWidth: 1280,
  codedHeight: 720,
};

const { supported } = await VideoDecoder.isConfigSupported(config);
console.log(`H.264 720p unterstützt: ${supported}`);

H.264 720p unterstützt: true

Codec-Fallback: den ersten unterstützten Codec wählen

const kandidaten = [
  { codec: 'av01.0.04M.08', codedWidth: 1920, codedHeight: 1080 },
  { codec: 'vp09.00.10.08', codedWidth: 1920, codedHeight: 1080 },
  { codec: 'avc1.640028', codedWidth: 1920, codedHeight: 1080 },
];

const findeUnterstuetztenCodec = async (liste) => {
  for (const config of liste) {
    try {
      const support = await VideoDecoder.isConfigSupported(config);
      if (support.supported) return support.config;
    } catch (err) {
      console.warn('Ungültige Konfiguration:', config.codec, err.message);
    }
  }
  return null;
};

const gewaehlt = await findeUnterstuetztenCodec(kandidaten);
console.log(gewaehlt ? `Verwende ${gewaehlt.codec}` : 'Kein Codec verfügbar');

Verwende vp09.00.10.08

Vor configure() prüfen, mit Hardware-Präferenz

if (!('VideoDecoder' in window)) {
  throw new Error('WebCodecs wird nicht unterstützt');
}

const basis = { codec: 'vp09.00.10.08', codedWidth: 3840, codedHeight: 2160 };

// Erst Hardware versuchen, sonst ohne Präferenz
let { supported, config } = await VideoDecoder.isConfigSupported({
  ...basis,
  hardwareAcceleration: 'prefer-hardware',
});
if (!supported) {
  ({ supported, config } = await VideoDecoder.isConfigSupported(basis));
}

if (supported) {
  const decoder = new VideoDecoder({
    output: (frame) => { /* Frame zeichnen */ frame.close(); },
    error: (e) => console.error('Decoder-Fehler:', e),
  });
  decoder.configure(config);
  console.log('Decoder-Status:', decoder.state);
}

Decoder-Status: configured

// Wichtig · Fallstricke

Formale Fehler vs. fehlende Unterstützung: Bei einer formal ungültigen Konfiguration (leerer oder fehlender codec, Breite oder Höhe 0, abgelöstes description-Buffer) wird das Promise mit einem TypeError abgelehnt. Wird die Konfiguration schlicht nicht unterstützt, wird es dagegen mit supported: false erfüllt. Deshalb gehört der Aufruf immer in try/catch.
Codec-Strings müssen vollständig sein: Kurzformen wie \"vp9\" oder \"avc1\" ohne Profil und Level gelten als ungültig bzw. nicht unterstützt. Verwende vollständige Strings nach RFC 6381, z. B. \"vp09.00.10.08\".
Keine Garantie für später: Auch bei supported: true kann configure() in seltenen Fällen noch scheitern, etwa wenn Hardware-Ressourcen erschöpft sind. Der error-Callback bleibt also nötig.
Fingerprinting: Browser können die Antworten verallgemeinern, um Fingerprinting zu erschweren. hardwareAcceleration: \"prefer-hardware\" liefert daher nicht immer eine verlässliche Aussage über die tatsächliche Hardware.
Kompatibilität: Die Methode ist nur in sicheren Kontexten (HTTPS) verfügbar, im Hauptthread und in Dedicated Workern. Firefox unterstützt WebCodecs erst ab Version 130 (Desktop), Safari ab 16.4. Prüfe die Verfügbarkeit vorab mit 'VideoDecoder' in globalThis.

Siehe auch

VideoDecoder.configure() VideoDecoder.close() VideoDecoder.decode() VideoDecoder.flush() VideoDecoder.reset()