AudioSession: statechange — Ereignis · JavaScript-Referenz

Signatur

navigator.audioSession.addEventListener("statechange", handler)

Beschreibung

Das Ereignis statechange gehört zur experimentellen Audio Session API. Über navigator.audioSession teilt eine Webseite dem Betriebssystem mit, wie sie Audio nutzt, etwa für Wiedergabe, kurze Hinweistöne, Hintergrundklänge oder Aufnahme. Das System verwaltet die Sitzung und meldet Zustandswechsel über dieses Ereignis.

Die Eigenschaft AudioSession.state kann drei Werte haben:

"active": Die Seite spielt gerade Audio ab oder nimmt auf.
"interrupted": Das System hat die Sitzung unterbrochen, z. B. durch einen eingehenden Anruf, einen Wecker oder eine andere App mit höherer Priorität.
"inactive": Die Sitzung ist nicht aktiv.

Typische Einsätze sind: die Oberfläche eines Mediaplayers anpassen (Wiedergabe-Knopf auf „Pause“ stellen), die Wiedergabeposition speichern, eine WebRTC-Aufnahme stumm schalten oder nach einer Unterbrechung eine Schaltfläche „Fortsetzen“ anzeigen. Das Ereignis ist ein einfaches Event ohne eigene Zusatzdaten. Den neuen Zustand liest man deshalb direkt aus navigator.audioSession.state.

Einen Handler kann man mit addEventListener("statechange", …) registrieren oder über die Eigenschaft navigator.audioSession.onstatechange zuweisen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, immer `"statechange"`.
$handler Pflicht	(event: Event) => void		Die Rückruffunktion. Sie erhält ein einfaches `Event`. `event.target` ist die betroffene `AudioSession`.
$options	boolean \| AddEventListenerOptions	false	Die üblichen Listener-Optionen wie `once`, `signal` oder `passive`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Den neuen Zustand liest man aus navigator.audioSession.state ("active" | "interrupted" | "inactive").

Beispiele

Unterbrechungen im Mediaplayer behandeln (addEventListener)

const audio = document.querySelector('audio');
const resumeBtn = document.querySelector('#resume');

if ('audioSession' in navigator) {
  navigator.audioSession.type = 'playback';

  navigator.audioSession.addEventListener('statechange', () => {
    const { state } = navigator.audioSession;
    console.log('AudioSession-Zustand:', state);

    if (state === 'interrupted') {
      // z. B. eingehender Anruf: Position merken, Knopf anzeigen
      localStorage.setItem('position', String(audio.currentTime));
      resumeBtn.hidden = false;
    } else if (state === 'active') {
      resumeBtn.hidden = true;
    }
  });

  resumeBtn.addEventListener('click', () => audio.play());
} else {
  console.log('Audio Session API wird nicht unterstützt');
}

AudioSession-Zustand: active AudioSession-Zustand: interrupted

Handler über die onstatechange-Eigenschaft setzen und wieder entfernen

const session = navigator.audioSession;

if (session) {
  session.onstatechange = (event) => {
    console.log(`Neuer Zustand: ${event.target.state}`);
  };

  // Später, z. B. beim Verlassen der Ansicht:
  const cleanup = () => {
    session.onstatechange = null;
  };
  window.addEventListener('pagehide', cleanup, { once: true });
}

Neuer Zustand: active

Listener mit AbortController entfernen (Videoanruf)

const controller = new AbortController();

const startCall = async () => {
  navigator.audioSession.type = 'play-and-record';
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  const [track] = stream.getAudioTracks();

  navigator.audioSession.addEventListener('statechange', () => {
    // Mikrofon während einer Unterbrechung stumm schalten
    track.enabled = navigator.audioSession.state !== 'interrupted';
    console.log('Mikrofon aktiv:', track.enabled);
  }, { signal: controller.signal });
};

const endCall = () => controller.abort(); // entfernt den Listener

if ('audioSession' in navigator) startCall();

Mikrofon aktiv: false Mikrofon aktiv: true

// Wichtig · Fallstricke

Kompatibilität: Die Audio Session API ist experimentell und bislang nur in WebKit/Safari implementiert (ab etwa 16.4, besonders relevant unter iOS). Chromium und Firefox unterstützen sie nicht. Prüfe deshalb immer vorab mit 'audioSession' in navigator.

Das Ereignis enthält keine Zusatzdaten wie den alten Zustand. Wer den vorherigen Zustand braucht, muss ihn selbst speichern.
Nach einer Unterbrechung setzt der Browser die Wiedergabe nicht zwingend selbst fort. Ein erneutes play() erfordert unter Umständen eine Nutzerinteraktion (Autoplay-Richtlinien).
Der Zustand wechselt erst, wenn tatsächlich Audio abgespielt oder aufgenommen wird. Das bloße Setzen von type löst kein statechange aus.
Die Spezifikation ist noch im Entwurf. Namen und Werte können sich ändern.

Siehe auch

AudioSession AudioSession.state AudioSession.type Navigator.audioSession EventTarget.addEventListener() AudioScheduledSourceNode: ended