</> programmierung.net
Start · Sprachen · JavaScript · Referenz · AudioEncoder.isConfigSupported()

AudioEncoder.isConfigSupported()

Methode

Statische Methode, die asynchron prüft, ob sich ein <code>AudioEncoder</code> mit der angegebenen Konfiguration erfolgreich konfigurieren lässt.

seit JavaScript WebCodecs API – Chrome/Edge 94+, Firefox 130+, Saf Kategorie: webapi

Signatur

AudioEncoder.isConfigSupported(config)

Beschreibung

AudioEncoder.isConfigSupported() ist eine statische Methode der WebCodecs API. Mit ihr prüfen Sie vor dem Erzeugen und Konfigurieren eines Encoders, ob Browser und Plattform eine bestimmte Kombination aus Codec, Abtastrate, Kanalzahl, Bitrate und weiteren Optionen unterstützen. Der Aufruf braucht keine Encoder-Instanz und verändert keinen Zustand.

Die Methode gibt ein Promise zurück. Es wird mit einem Objekt erfüllt, das die Eigenschaft supported (ein boolean) und eine bereinigte Kopie der Konfiguration unter config enthält. In dieser Kopie stehen nur die Felder, die der Browser erkannt hat. Unbekannte Schlüssel fehlen darin. So sehen Sie auch, welche Optionen überhaupt ausgewertet wurden.

Typischer Einsatz: eine Liste bevorzugter Konfigurationen der Reihe nach durchprüfen (zum Beispiel erst Opus, dann AAC) und die erste unterstützte Konfiguration an AudioEncoder.prototype.configure() übergeben. Damit vermeiden Sie Fehler, die sonst erst asynchron im error-Callback des Encoders ankommen würden.

Parameter

Name Typ Default Beschreibung
$config Pflicht AudioEncoderConfig Konfigurationsobjekt mit denselben Feldern wie bei AudioEncoder.prototype.configure():
  • codec (string, Pflicht): Codec-Zeichenkette, z. B. "opus", "mp4a.40.2" (AAC-LC), "flac".
  • sampleRate (number, Pflicht): Abtastrate in Hz, z. B. 48000.
  • numberOfChannels (number, Pflicht): Anzahl der Kanäle.
  • bitrate (number, optional): Ziel-Bitrate in Bit/s.
  • bitrateMode ("constant" | "variable", optional, Standard "variable").
  • Codec-spezifisch: opus (z. B. { complexity, frameDuration, packetlossperc, useinbandfec, usedtx, format }), aac ({ format: "aac" | "adts" }), flac ({ blockSize, compressLevel }).

Rückgabewert

Typ
Promise<{ supported: boolean, config: AudioEncoderConfig }>
Beschreibung
Ein Promise, das mit einem Objekt erfüllt wird: supported gibt an, ob die Konfiguration unterstützt wird, config enthält eine bereinigte Kopie der geprüften Konfiguration. Das Promise wird mit einem TypeError abgelehnt, wenn die Konfiguration ungültig ist (z. B. leerer codec oder fehlende Pflichtfelder).

Beispiele

Einfache Prüfung einer Opus-Konfiguration

const config = {
  codec: 'opus',
  sampleRate: 48000,
  numberOfChannels: 2,
  bitrate: 128_000,
};

const { supported, config: geprueft } = await AudioEncoder.isConfigSupported(config);
console.log(supported ? 'Opus wird unterstützt' : 'Opus wird NICHT unterstützt');
console.log(geprueft);
Opus wird unterstützt { codec: 'opus', sampleRate: 48000, numberOfChannels: 2, bitrate: 128000, ... }

Erste unterstützte Konfiguration aus einer Liste wählen

const kandidaten = [
  { codec: 'opus', sampleRate: 48000, numberOfChannels: 2, bitrate: 96_000 },
  { codec: 'mp4a.40.2', sampleRate: 44100, numberOfChannels: 2, bitrate: 128_000, aac: { format: 'aac' } },
  { codec: 'flac', sampleRate: 48000, numberOfChannels: 2 },
];

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

const config = await waehleKonfiguration(kandidaten);
console.log('Gewählt:', config?.codec ?? 'keine');
Gewählt: opus

Prüfen, dann Encoder konfigurieren (mit Feature-Erkennung)

const starteEncoder = async () => {
  if (!('AudioEncoder' in window)) {
    throw new Error('WebCodecs AudioEncoder wird nicht unterstützt');
  }

  const config = {
    codec: 'opus',
    sampleRate: 48000,
    numberOfChannels: 1,
    bitrate: 32_000,
    opus: { frameDuration: 20_000, usedtx: true },
  };

  const { supported } = await AudioEncoder.isConfigSupported(config);
  if (!supported) throw new Error('Konfiguration nicht unterstützt');

  const encoder = new AudioEncoder({
    output: (chunk, meta) => console.log('Chunk:', chunk.byteLength, 'Bytes'),
    error: (e) => console.error('Encoder-Fehler:', e),
  });
  encoder.configure(config);
  return encoder;
};

const encoder = await starteEncoder();
console.log(encoder.state);
configured

// Wichtig · Fallstricke

  • Abgelehntes Promise und supported: false sind zwei verschiedene Fälle: Ist die Konfiguration formal ungültig (fehlender oder leerer codec, sampleRate oder numberOfChannels fehlt oder ist 0), wird das Promise mit einem TypeError abgelehnt. Ist sie gültig, wird aber nicht unterstützt, lautet das Ergebnis supported: false. Fangen Sie deshalb beide Fälle ab, etwa mit try/catch.
  • supported: true garantiert nicht, dass das Kodieren später fehlerfrei läuft. Hardware- oder Ressourcenengpässe können trotzdem Fehler im error-Callback auslösen.
  • Unbekannte Felder werden stillschweigend ignoriert und fehlen im zurückgegebenen config. Vergleichen Sie diese Kopie mit Ihrer Eingabe, wenn Ihnen bestimmte Optionen wichtig sind.
  • Die Codec-Zeichenketten müssen der WebCodecs-Codec-Registry entsprechen (z. B. \"mp4a.40.2\" statt \"aac\").
  • Kompatibilität: Die Methode steht nur in sicheren Kontexten (HTTPS) zur Verfügung, im Fenster und in Dedicated Workern. Chromium-Browser unterstützen sie seit Version 94, Firefox seit 130. Safari hat den AudioEncoder erst spät eingeführt. Prüfen Sie daher vorher mit 'AudioEncoder' in globalThis, ob die API vorhanden ist.
  • Welche Codecs verfügbar sind, hängt von Browser und Betriebssystem ab. AAC ist in Chromium-Builds ohne proprietäre Codecs zum Beispiel oft nicht vorhanden.

Siehe auch

AudioEncoder.configure() AudioEncoder.close() AudioEncoder.encode() AudioEncoder.flush() AudioEncoder.reset()
← Vorheriger Eintrag AudioEncoder.flush()