AudioSession — Schnittstelle · JavaScript-Referenz

Signatur

interface AudioSession extends EventTarget

Beschreibung

Die Schnittstelle AudioSession gehört zur Audio Session API. Eine Webseite teilt damit dem Browser und dem Betriebssystem mit, welche Art von Audio sie ausgibt oder aufnimmt. Das ist vor allem auf Mobilgeräten wichtig. Dort entscheidet das System anhand dieser Angabe, ob Musik anderer Apps gestoppt, leiser gestellt („Ducking“) oder weiter abgespielt wird. Außerdem entscheidet es, ob Audio trotz Stummschalter hörbar ist.

Man legt kein eigenes Objekt an. Es gibt genau eine Instanz pro Dokument, erreichbar über navigator.audioSession. Das wichtigste Element ist die Eigenschaft type. Sie kann einen dieser Werte haben:

"auto" (Standard): Der Browser wählt den Typ selbst.
"playback": Musik oder Podcasts. Andere Wiedergaben werden unterbrochen.
"transient": Kurze Hinweistöne. Anderes Audio wird dabei leiser gestellt (Ducking).
"transient-solo": Kurze Ausgabe, bei der anderes Audio pausiert, z. B. Ansagen eines Navigationssystems.
"ambient": Hintergrundgeräusche, die sich mit anderem Audio mischen, z. B. in Spielen.
"play-and-record": Gleichzeitig abspielen und aufnehmen, z. B. bei Video- und Sprachanrufen mit WebRTC.

Die Spezifikation beschreibt außerdem die schreibgeschützte Eigenschaft state ("inactive", "active", "interrupted") und das Ereignis statechange. Damit lassen sich Unterbrechungen erkennen, etwa durch einen eingehenden Telefonanruf. Diese Teile sind bisher kaum umgesetzt.

Setzen Sie den Typ möglichst bevor die Wiedergabe oder Aufnahme startet. Ein späterer Wechsel wirkt je nach Plattform erst bei der nächsten Audio-Aktivierung.

Parameter

Name	Typ	Default	Beschreibung
$type	"auto" \| "playback" \| "transient" \| "transient-solo" \| "ambient" \| "play-and-record"	"auto"	Eigenschaft, die gelesen und geschrieben werden kann. Legt die Art der Audio-Sitzung des Dokuments fest. Ungültige Werte werden ohne Fehlermeldung ignoriert.
$state	"inactive" \| "active" \| "interrupted"		Schreibgeschützte Eigenschaft, nur in der Spezifikation: aktueller Zustand der Sitzung. Bisher kaum umgesetzt.
$onstatechange	((event: Event) => void) \| null	null	Nur in der Spezifikation: Handler, der aufgerufen wird, wenn sich `state` ändert. Alternative: `addEventListener("statechange", …)`.

Rückgabewert

Typ

AudioSession

Beschreibung

navigator.audioSession liefert die eine AudioSession-Instanz des aktuellen Dokuments. In Browsern ohne Unterstützung ist der Wert undefined.

Beispiele

Unterstützung prüfen und Typ für einen Musik-Player setzen

const player = document.querySelector('audio');

if ('audioSession' in navigator) {
  // Musik soll andere Wiedergaben unterbrechen
  navigator.audioSession.type = 'playback';
  console.log('Sitzungstyp:', navigator.audioSession.type);
} else {
  console.log('Audio Session API nicht verfügbar');
}

document.querySelector('#play').addEventListener('click', () => player.play());

Sitzungstyp: playback

Videoanruf: Typ vor getUserMedia setzen

const startCall = async () => {
  if (navigator.audioSession) {
    // Gleichzeitig aufnehmen und wiedergeben
    navigator.audioSession.type = 'play-and-record';
  }
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true });
  document.querySelector('#self').srcObject = stream;
  return stream;
};

document.querySelector('#call').addEventListener('click', startCall);

Kurzer Hinweiston, der Hintergrundmusik nur leiser stellt

const ping = new Audio('/sounds/notification.mp3');

const notify = async () => {
  if (navigator.audioSession) {
    navigator.audioSession.type = 'transient';
  }
  await ping.play();
};

ping.addEventListener('ended', () => {
  // Nach dem Ton wieder den Browser entscheiden lassen
  if (navigator.audioSession) navigator.audioSession.type = 'auto';
});

notify();

Unterbrechungen erkennen (nur in der Spezifikation)

const session = navigator.audioSession;

if (session && 'state' in session) {
  const onStateChange = () => {
    console.log('Zustand der Audio-Sitzung:', session.state);
    if (session.state === 'interrupted') {
      document.querySelector('audio')?.pause();
    }
  };
  session.addEventListener('statechange', onStateChange);
  // Später wieder entfernen:
  // session.removeEventListener('statechange', onStateChange);
}

Zustand der Audio-Sitzung: interrupted

// Wichtig · Fallstricke

Kompatibilität: Die API ist experimentell und bisher nur in Safari umgesetzt (macOS und iOS ab 16.4), und dort nur die Eigenschaft type. Chrome, Edge und Firefox unterstützen sie nicht. Prüfen Sie deshalb immer mit 'audioSession' in navigator. Die API ist nur eine zusätzliche Verbesserung und darf nie Voraussetzung für die Kernfunktion sein.

Fallstricke:

Ungültige Werte für type lösen keinen Fehler aus. Sie werden stillschweigend ignoriert.
Der Typ gilt für das ganze Dokument und nicht für einzelne <audio>-Elemente oder einen einzelnen AudioContext.
Sehr wahrscheinlich kann "ambient" auf iOS vom Stummschalter stummgeschaltet werden. "playback" ist dagegen trotz Stummschalter hörbar.
state und statechange stehen zwar in der Spezifikation, sind aber in keinem Browser verlässlich verfügbar.
Die Regeln für Autoplay gelten weiterhin. Ein Sitzungstyp ersetzt keine Nutzeraktion, die vor der Wiedergabe nötig ist.

Siehe auch

Navigator.audioSession MediaSession XRSession AudioDecoder AudioSinkInfo