BaseAudioContext: statechange — Ereignis · JavaScript-Referenz

Signatur

baseAudioContext.addEventListener("statechange", handler)

Beschreibung

Das Ereignis statechange wird an einem BaseAudioContext ausgelöst, sobald sich der Wert seiner Eigenschaft state ändert. Mögliche Zustände sind "suspended", "running" und "closed". Bei AudioContext gibt es in einigen Browsern zusätzlich "interrupted", etwa wenn das Betriebssystem die Audiowiedergabe unterbricht.

Einen Handler registrieren Sie entweder mit addEventListener("statechange", handler) oder über die Eigenschaft onstatechange. Das Ereignis ist ein einfaches Event ohne eigene Zusatzdaten. Den neuen Zustand lesen Sie deshalb im Handler aus event.target.state bzw. audioCtx.state aus.

Typische Anwendungsfälle:

Die Benutzeroberfläche mit dem Audiozustand abgleichen, z. B. den Play-/Pause-Button aktualisieren.
Erkennen, dass die Autoplay-Richtlinie des Browsers einen Kontext im Zustand "suspended" startet. Dann zeigen Sie einen Hinweis „Zum Abspielen klicken“ an.
Nach close() Ressourcen aufräumen.

Der Zustand wechselt durch resume(), suspend() und close(), aber auch ohne Ihr Zutun, zum Beispiel wenn der Browser den Kontext beim ersten Starten freigibt.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"statechange"`.
$handler Pflicht	(event: Event) => void		Callback, der bei jeder Zustandsänderung aufgerufen wird. `event.target` ist der betroffene Audio-Kontext.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` (zum Entfernen per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das an den Handler übergebene Objekt ist ein einfaches Event.

Beispiele

Zustandswechsel mit addEventListener protokollieren

const audioCtx = new AudioContext();

audioCtx.addEventListener('statechange', (event) => {
  console.log('Neuer Zustand:', event.target.state);
});

// Nach einer Nutzerinteraktion fortsetzen, später schließen
document.querySelector('#start').addEventListener('click', async () => {
  await audioCtx.resume();
  setTimeout(() => audioCtx.close(), 2000);
});

Neuer Zustand: running Neuer Zustand: closed

Play/Pause-Button über onstatechange synchronisieren

const audioCtx = new AudioContext();
const button = document.querySelector('#toggle');

const updateButton = () => {
  button.textContent = audioCtx.state === 'running' ? 'Pause' : 'Abspielen';
  button.disabled = audioCtx.state === 'closed';
};

audioCtx.onstatechange = updateButton;
updateButton(); // Anfangszustand, oft "suspended" wegen Autoplay-Richtlinie

button.addEventListener('click', () => {
  audioCtx.state === 'running' ? audioCtx.suspend() : audioCtx.resume();
});

Listener per AbortController wieder entfernen

const audioCtx = new AudioContext();
const controller = new AbortController();

const onStateChange = () => {
  console.log('Zustand:', audioCtx.state);
  if (audioCtx.state === 'closed') {
    controller.abort(); // Listener abmelden
  }
};

audioCtx.addEventListener('statechange', onStateChange, { signal: controller.signal });
// Alternativ: audioCtx.removeEventListener('statechange', onStateChange);

await audioCtx.resume();
await audioCtx.close();

Zustand: running Zustand: closed

// Wichtig · Fallstricke

Autoplay-Richtlinie: Ein Kontext, der ohne Nutzerinteraktion erzeugt wird, startet meist im Zustand "suspended". Den Anfangszustand prüfen Sie daher sofort nach dem Erzeugen, denn nicht jeder Browser löst dafür ein Ereignis aus.
Das Ereignis enthält den alten Zustand nicht. Wenn Sie ihn brauchen, speichern Sie ihn selbst.
Nach "closed" ist kein weiterer Wechsel möglich. Dann können Sie den Listener entfernen und Audioknoten freigeben.
OfflineAudioContext erbt das Ereignis ebenfalls. Er wechselt beim Start von startRendering() auf "running" und nach Abschluss auf "closed".
Der Zustand "interrupted" ist neu und bisher nur teilweise umgesetzt, z. B. in Safari. Behandeln Sie unbekannte Zustände defensiv.
Ältere WebKit-Versionen mit webkitAudioContext unterstützen das Ereignis teilweise nicht. Alle aktuellen Browser unterstützen es.

Siehe auch

AudioContext: sinkchange AudioSession: statechange MIDIAccess: statechange MIDIPort: statechange ServiceWorker: statechange