AudioEncoder.state — Eigenschaft · JavaScript-Referenz

Signatur

AudioEncoder.state

Beschreibung

Die schreibgeschützte Eigenschaft state eines AudioEncoder zeigt an, in welchem Lebenszyklus-Zustand sich der zugrunde liegende Codec befindet. Mögliche Werte:

"unconfigured" – Der Encoder wurde erzeugt (oder mit reset() zurückgesetzt), aber noch nicht per configure() eingerichtet. encode() und flush() sind in diesem Zustand nicht erlaubt.
"configured" – Ein gültiger Codec wurde konfiguriert; Audiodaten können mit encode() verarbeitet werden.
"closed" – Der Encoder wurde mit close() dauerhaft geschlossen oder ist wegen eines Fehlers (z. B. nicht unterstützte Konfiguration) automatisch geschlossen worden. Er kann nicht wiederverwendet werden.

Die Eigenschaft ist nützlich, um vor Aufrufen von encode(), flush() oder configure() zu prüfen, ob der Encoder sich im passenden Zustand befindet. So lassen sich InvalidStateError-Ausnahmen vermeiden – etwa wenn ein Aufnahme-Stream noch Daten liefert, nachdem der Encoder bereits geschlossen wurde.

Der Zustand wechselt synchron beim Aufruf von configure(), reset() und close(). Ob eine Konfiguration tatsächlich unterstützt wird, stellt sich dagegen erst asynchron heraus: Schlägt sie fehl, wird der error-Callback aufgerufen und state wechselt zu "closed".

Rückgabewert

Typ

"unconfigured" | "configured" | "closed"

Beschreibung

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

Beispiele

Zustandswechsel im Lebenszyklus beobachten

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

console.log(encoder.state); // direkt nach dem Erzeugen

encoder.configure({
  codec: 'opus',
  sampleRate: 48000,
  numberOfChannels: 2,
  bitrate: 128_000
});
console.log(encoder.state);

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

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

unconfigured configured unconfigured closed

Sicher encodieren: nur im Zustand "configured"

const encodeSafely = (encoder, audioData) => {
  if (encoder.state !== 'configured') {
    console.warn(`Frame verworfen – Encoder ist "${encoder.state}"`);
    audioData.close(); // Speicher trotzdem freigeben
    return false;
  }
  encoder.encode(audioData);
  audioData.close();
  return true;
};

// Beispiel mit einem synthetischen Stille-Frame
const encoder = new AudioEncoder({ output: () => {}, error: console.error });
const frame = new AudioData({
  format: 'f32-planar',
  sampleRate: 48000,
  numberOfFrames: 960,
  numberOfChannels: 1,
  timestamp: 0,
  data: new Float32Array(960)
});
console.log(encodeSafely(encoder, frame));

Frame verworfen – Encoder ist "unconfigured" false

Aufnahme sauber beenden

const stopRecording = async (encoder) => {
  if (encoder.state === 'configured') {
    await encoder.flush(); // restliche Chunks ausgeben
  }
  if (encoder.state !== 'closed') {
    encoder.close();
  }
  console.log('Endzustand:', encoder.state);
};

const encoder = new AudioEncoder({ output: () => {}, error: console.error });
encoder.configure({ codec: 'opus', sampleRate: 48000, numberOfChannels: 1 });
await stopRecording(encoder);

Endzustand: closed

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an state wird ignoriert (im Strict Mode TypeError). Der Zustand ändert sich nur über configure(), reset(), close() oder durch Fehler.
„configured“ heißt nicht „unterstützt“: Direkt nach configure() steht der Wert auf "configured", auch wenn der Codec später asynchron abgelehnt wird. Vorab mit AudioEncoder.isConfigSupported() prüfen.
„closed“ ist endgültig: Ein geschlossener Encoder lässt sich nicht erneut konfigurieren – jeder weitere Methodenaufruf wirft InvalidStateError. Stattdessen eine neue Instanz erzeugen.
Nach einem internen Fehler wird der Encoder automatisch geschlossen; im error-Callback ist state bereits "closed".
Kompatibilität: Die WebCodecs API ist nur in sicheren Kontexten (HTTPS) verfügbar und funktioniert in Fenstern und dedizierten Workern. Vor der Nutzung mit 'AudioEncoder' in globalThis auf Unterstützung prüfen – ältere Safari- und Firefox-Versionen kennen AudioEncoder nicht.

Siehe auch

AudioEncoder.encodeQueueSize AudioDecoder.state VideoEncoder.state VideoDecoder.state MediaRecorder.state