VideoEncoder.isConfigSupported() — Methode · JavaScript-Referenz

Signatur

VideoEncoder.isConfigSupported(config)

Beschreibung

Die statische Methode VideoEncoder.isConfigSupported() gehört zur WebCodecs-API. Sie prüft, ob der Browser eine bestimmte Encoder-Konfiguration (Codec, Auflösung, Bitrate, Hardware-Beschleunigung usw.) unterstützt. Das Ergebnis ist ein Promise, das zu einem Objekt mit den Feldern supported und config aufgelöst wird.

Rufen Sie die Methode vor VideoEncoder.prototype.configure() auf. configure() meldet eine nicht unterstützte Konfiguration nämlich erst später über den error-Callback und schließt den Encoder dabei. Mit isConfigSupported() können Sie stattdessen mehrere Kandidaten nacheinander testen, etwa AV1 → VP9 → H.264, und dann den ersten nehmen, der funktioniert.

Das zurückgegebene config enthält nur die Einträge, die der Browser erkannt hat. Unbekannte Schlüssel werden entfernt. So sehen Sie, welche Optionen tatsächlich berücksichtigt werden. Wichtig ist der Unterschied zwischen zwei Fehlerarten: Ist die Konfiguration formal ungültig (z. B. leerer codec oder width gleich 0), wird das Promise mit einem TypeError abgelehnt. Ist sie gültig, wird aber nicht unterstützt, wird es mit supported: false erfüllt.

Parameter

Name	Typ	Default	Beschreibung
$config Pflicht	VideoEncoderConfig		Konfigurationsobjekt mit denselben Feldern wie bei `configure()`. Pflicht: `codec` (z. B. `'avc1.42001f'`, `'vp8'`, `'vp09.00.10.08'`, `'av01.0.04M.08'`), `width`, `height`. Optional: `displayWidth`, `displayHeight`, `bitrate`, `framerate`, `hardwareAcceleration` (`'no-preference'` \| `'prefer-hardware'` \| `'prefer-software'`), `alpha` (`'discard'` \| `'keep'`), `scalabilityMode` (z. B. `'L1T2'`), `bitrateMode` (`'constant'` \| `'variable'` \| `'quantizer'`), `latencyMode` (`'quality'` \| `'realtime'`), `contentHint` sowie codecspezifische Felder wie `avc: { format: 'annexb' \| 'avc' }`.

Rückgabewert

Typ

Promise<VideoEncoderSupport>

Beschreibung

Ein Promise, das zu einem Objekt { supported: boolean, config: VideoEncoderConfig } aufgelöst wird. supported gibt an, ob die Konfiguration nutzbar ist. config ist eine bereinigte Kopie, die nur die erkannten Felder enthält. Bei einer formal ungültigen Konfiguration wird das Promise mit einem TypeError abgelehnt.

Beispiele

Einfache Prüfung einer H.264-Konfiguration

const config = {
  codec: 'avc1.42001f', // H.264 Baseline, Level 3.1
  width: 1280,
  height: 720,
  bitrate: 2_000_000,
  framerate: 30,
};

const { supported, config: geprueft } = await VideoEncoder.isConfigSupported(config);
console.log(supported ? 'H.264 wird unterstützt' : 'H.264 nicht verfügbar');
console.log(geprueft.codec);

H.264 wird unterstützt avc1.42001f

Besten verfügbaren Codec auswählen (Fallback-Kette)

const kandidaten = [
  { codec: 'av01.0.04M.08', width: 1920, height: 1080, bitrate: 4_000_000, framerate: 30 },
  { codec: 'vp09.00.10.08', width: 1920, height: 1080, bitrate: 5_000_000, framerate: 30 },
  { codec: 'avc1.640028', width: 1920, height: 1080, bitrate: 6_000_000, framerate: 30, avc: { format: 'annexb' } },
];

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

const config = await waehleKonfiguration();
if (!config) throw new Error('Kein unterstützter Video-Codec gefunden');

const encoder = new VideoEncoder({
  output: (chunk, meta) => console.log('Chunk', chunk.type, chunk.byteLength),
  error: (e) => console.error(e),
});
encoder.configure(config);
console.log('Encoder konfiguriert mit', config.codec);

Encoder konfiguriert mit vp09.00.10.08

Hardware-Beschleunigung für Echtzeit-Übertragung testen

const pruefeHardware = async (codec) => {
  const basis = { codec, width: 1280, height: 720, bitrate: 1_500_000, framerate: 30, latencyMode: 'realtime' };

  const hw = await VideoEncoder.isConfigSupported({ ...basis, hardwareAcceleration: 'prefer-hardware' });
  if (hw.supported) return { ...hw.config, quelle: 'hardware' };

  const sw = await VideoEncoder.isConfigSupported({ ...basis, hardwareAcceleration: 'prefer-software' });
  return sw.supported ? { ...sw.config, quelle: 'software' } : null;
};

if ('VideoEncoder' in window) {
  const ergebnis = await pruefeHardware('vp8');
  console.log(ergebnis?.quelle ?? 'nicht unterstützt');
} else {
  console.log('WebCodecs nicht verfügbar');
}

hardware

Unterschied: ungültig vs. nicht unterstützt

try {
  // width 0 ist formal ungültig -> TypeError
  await VideoEncoder.isConfigSupported({ codec: 'vp8', width: 0, height: 480 });
} catch (e) {
  console.log(e.name);
}

// Formal gültig, aber unbekannter Codec -> supported: false
const res = await VideoEncoder.isConfigSupported({ codec: 'foo.bar', width: 640, height: 480 });
console.log(res.supported);

TypeError false

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser ab Version 94, Safari ab 16.4, Firefox ab 130. Prüfen Sie vorher mit 'VideoEncoder' in window, ob die API vorhanden ist. Verfügbar ist sie nur in sicheren Kontexten (HTTPS), sowohl im Hauptthread als auch in dedizierten Workern.
TypeError statt false: Formal ungültige Konfigurationen führen zu einem abgelehnten Promise, etwa bei fehlendem oder leerem codec, width/height gleich 0 oder nur einem der beiden Werte displayWidth/displayHeight. Setzen Sie deshalb immer try/catch ein.
Exakte Codec-Strings: Allgemeine Angaben wie 'avc1' oder 'vp9' reichen meist nicht. Nötig sind vollständige Strings mit Profil und Level, z. B. 'avc1.42001f' oder 'vp09.00.10.08'. Nur 'vp8' kommt ohne Zusatz aus.
Keine Garantie für später: supported: true bedeutet nicht, dass ein späteres configure() sicher gelingt. Hardware-Ressourcen können inzwischen belegt sein, zum Beispiel durch mehrere gleichzeitige Encoder. Werten Sie trotzdem den error-Callback aus.
Bereinigtes config: Unbekannte Felder fehlen im Ergebnis. Daran erkennen Sie, ob Optionen wie contentHint oder scalabilityMode überhaupt berücksichtigt werden. Codecspezifische Wörterbücher wie avc bleiben nur erhalten, wenn der Codec passt.
Datenschutz: Die Ergebnisse verraten Details über die Hardware und lassen sich für Fingerprinting nutzen. Manche Browser vereinfachen die Antworten deshalb absichtlich.

Siehe auch

VideoEncoder.configure() VideoEncoder.close() VideoEncoder.encode() VideoEncoder.flush() VideoEncoder.reset() VideoDecoder.close()