AudioDecoder.state — Eigenschaft · JavaScript-Referenz

Signatur

get AudioDecoder.state

Beschreibung

Die Eigenschaft AudioDecoder.state gibt an, in welchem Lebenszyklus-Zustand sich der zugrunde liegende Audio-Codec gerade befindet. Sie ist schreibgeschützt und wird ausschließlich durch Methodenaufrufe wie configure(), reset() und close() oder durch Fehler verändert.

Mögliche Werte:

"unconfigured" – Der Decoder wurde erzeugt (oder per reset() zurückgesetzt), aber noch nicht konfiguriert. Aufrufe von decode() oder flush() werfen einen Fehler.
"configured" – Nach erfolgreichem configure() ist der Decoder bereit, EncodedAudioChunk-Objekte zu dekodieren.
"closed" – Der Decoder wurde mit close() geschlossen oder ist wegen eines schwerwiegenden Fehlers dauerhaft unbrauchbar. Aus diesem Zustand gibt es keinen Weg zurück; es muss eine neue Instanz erzeugt werden.

In der Praxis prüft man state vor dem Aufruf von decode(), flush() oder configure(), um InvalidStateError-Ausnahmen zu vermeiden – etwa in Streaming-Pipelines, in denen Datenpakete auch dann noch eintreffen, wenn der Decoder bereits geschlossen wurde.

Rückgabewert

Typ

"unconfigured" | "configured" | "closed"

Beschreibung

Ein String (Enum CodecState), der den aktuellen Zustand des Decoders beschreibt.

Beispiele

Zustandswechsel im Lebenszyklus beobachten

const decoder = new AudioDecoder({
  output: (audioData) => {
    // Dekodierte Samples weiterverarbeiten
    audioData.close();
  },
  error: (e) => console.error('Decoder-Fehler:', e.message)
});

console.log(decoder.state);

decoder.configure({
  codec: 'opus',
  sampleRate: 48000,
  numberOfChannels: 2
});
console.log(decoder.state);

decoder.reset();
console.log(decoder.state);

decoder.close();
console.log(decoder.state);

unconfigured configured unconfigured closed

Sicheres Dekodieren in einer Streaming-Pipeline

const safeDecode = (decoder, chunk) => {
  if (decoder.state !== 'configured') {
    console.warn(`Chunk verworfen – Decoder ist "${decoder.state}"`);
    return false;
  }
  decoder.decode(chunk);
  return true;
};

// Beispiel: eintreffende Pakete aus einem WebSocket
// socket.onmessage = ({ data }) => {
//   const chunk = new EncodedAudioChunk({
//     type: 'key', timestamp: performance.now() * 1000, data
//   });
//   safeDecode(decoder, chunk);
// };

Chunk verworfen – Decoder ist "closed" (falls bereits geschlossen)

Decoder nach Fehler automatisch neu erstellen

const config = { codec: 'mp4a.40.2', sampleRate: 44100, numberOfChannels: 2 };

const createDecoder = () => {
  const d = new AudioDecoder({
    output: (data) => data.close(),
    error: (e) => console.error('Fehler:', e.name)
  });
  d.configure(config);
  return d;
};

let decoder = createDecoder();

const ensureDecoder = () => {
  // Nach einem fatalen Fehler ist der Zustand "closed"
  if (decoder.state === 'closed') {
    console.log('Decoder geschlossen – erzeuge neue Instanz');
    decoder = createDecoder();
  }
  return decoder;
};

console.log(ensureDecoder().state);

configured

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie decoder.state = 'configured' hat keine Wirkung (im Strict Mode wirft sie einen TypeError).
Zustand "closed" ist endgültig: Weder configure() noch reset() reaktivieren den Decoder – beide werfen dann einen InvalidStateError. Eine neue Instanz ist nötig.
Fehler schließen den Decoder: Tritt während der Dekodierung ein Fehler auf (z. B. NotSupportedError bei nicht unterstütztem Codec oder EncodingError bei defekten Daten), wird der error-Callback aufgerufen und state wechselt auf "closed".
"configured" garantiert keine Unterstützung: configure() arbeitet asynchron; der Zustand ist sofort "configured", auch wenn der Codec später abgelehnt wird. Vorab mit AudioDecoder.isConfigSupported() prüfen.
Kompatibilität: Die WebCodecs API ist nur in sicheren Kontexten (HTTPS) sowie in Window und Dedicated Workern verfügbar. Unterstützung per 'AudioDecoder' in globalThis prüfen; Safari unterstützt AudioDecoder erst seit neueren Versionen.

Siehe auch

AudioDecoder.decodeQueueSize AudioEncoder.state VideoDecoder.state MediaRecorder.state VideoEncoder.state