Navigator.audioSession — Eigenschaft · JavaScript-Referenz

Signatur

get Navigator.audioSession

Beschreibung

Die schreibgeschützte Eigenschaft navigator.audioSession ist der Einstieg in die Audio Session API. Sie liefert ein AudioSession-Objekt. Über dieses Objekt teilt eine Webseite dem Betriebssystem mit, welche Art von Audio sie abspielt. Daraus ergibt sich zum Beispiel, ob andere Audioquellen wie eine Musik-App leiser gestellt, pausiert oder mit dem Ton der Seite gemischt werden. Außerdem entscheidet der Typ, ob der Ton auch im Stumm-Modus des Geräts zu hören ist.

Die wichtigste Eigenschaft ist audioSession.type. Sie ist beschreibbar und akzeptiert folgende Werte:

"auto" (Standard): Der Browser wählt den Typ selbst.
"playback": Medienwiedergabe, etwa Musik oder Podcasts. Andere Audioquellen werden unterbrochen.
"transient": kurze Töne wie Benachrichtigungen. Andere Audioquellen werden leiser gestellt (Ducking).
"transient-solo": kurze Töne, bei denen andere Audioquellen pausiert werden, etwa Sprachansagen.
"ambient": Hintergrundgeräusche, die mit anderen Audioquellen gemischt werden.
"play-and-record": gleichzeitige Aufnahme und Wiedergabe, etwa bei Videokonferenzen.

Die Spezifikation beschreibt außerdem die Eigenschaft state ("inactive", "active", "interrupted") und das Ereignis statechange. Damit kann eine Seite erkennen, ob ihr Audio vom System unterbrochen wurde, zum Beispiel durch einen Anruf. Diese Teile sind noch nicht in allen Implementierungen vorhanden. Man sollte ihre Verfügbarkeit deshalb immer prüfen.

Die API lohnt sich vor allem auf Mobilgeräten wie dem iPhone. Dort macht es einen großen Unterschied, ob z. B. ein Spiel mit Hintergrundmusik die Musik-App des Nutzers stoppt oder sich nur dazumischt.

Rückgabewert

Typ

AudioSession

Beschreibung

Das AudioSession-Objekt des aktuellen Dokuments. Es ist pro Dokument immer dasselbe Objekt. In Browsern ohne Unterstützung ist die Eigenschaft nicht vorhanden, der Zugriff liefert also undefined.

Beispiele

Unterstützung prüfen und aktuellen Typ auslesen

if ('audioSession' in navigator) {
  console.log('Aktueller Typ:', navigator.audioSession.type);
} else {
  console.log('Audio Session API nicht verfügbar');
}

Aktueller Typ: auto

Hintergrundmusik eines Spiels mit anderen Apps mischen

// Die Musik der Musik-App soll weiterlaufen
const setupGameAudio = async () => {
  if (navigator.audioSession) {
    navigator.audioSession.type = 'ambient';
  }
  const ctx = new AudioContext();
  const response = await fetch('/sounds/background.mp3');
  const buffer = await ctx.decodeAudioData(await response.arrayBuffer());
  const source = ctx.createBufferSource();
  source.buffer = buffer;
  source.loop = true;
  source.connect(ctx.destination);
  source.start();
};

document.querySelector('#start').addEventListener('click', setupGameAudio);

Podcast-Player: Wiedergabe-Typ setzen und Unterbrechungen beobachten

const audio = document.querySelector('audio');
const session = navigator.audioSession;

if (session) {
  session.type = 'playback';

  // state/statechange sind nicht überall implementiert
  if ('state' in session) {
    session.addEventListener('statechange', () => {
      console.log('Session-Status:', session.state);
      if (session.state === 'interrupted') {
        audio.pause();
      }
    });
  }
}

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

Session-Status: active Session-Status: interrupted

Kurzen Benachrichtigungston abspielen und Typ zurücksetzen

const playNotification = async () => {
  const session = navigator.audioSession;
  const previous = session?.type;
  if (session) session.type = 'transient';

  const sound = new Audio('/sounds/ping.mp3');
  await sound.play();
  sound.addEventListener('ended', () => {
    if (session) session.type = previous;
  }, { once: true });
};

// Wichtig · Fallstricke

Experimentell und nur in WebKit: Die API wird bisher nur von Safari ab 16.4 (iOS/iPadOS/macOS) unterstützt. Chrome und Firefox kennen sie nicht. Prüfen Sie die Unterstützung daher immer mit 'audioSession' in navigator oder mit optionaler Verkettung (navigator.audioSession?.type).
navigator.audioSession selbst ist schreibgeschützt. Ändern kann man nur die Eigenschaft type des zurückgegebenen Objekts.
Ein ungültiger Wert für type löst keinen Fehler aus. Er wird wie bei WebIDL-Enums üblich stillschweigend ignoriert.
Den Typ am besten vor dem Start der Wiedergabe setzen. Wird er während einer laufenden Wiedergabe geändert, wirkt sich das je nach Implementierung erst verzögert oder gar nicht aus.
Autoplay-Richtlinien gelten unabhängig von der Audio Session. Die Wiedergabe braucht weiterhin eine Nutzergeste.
state und statechange stehen in der Spezifikation, sind aber nicht überall implementiert. Sie sollten deshalb nur nach einer Verfügbarkeitsprüfung genutzt werden.
Mit "playback" kann Audio unter iOS auch bei aktivem Stumm-Schalter hörbar sein. Setzen Sie den Typ deshalb bewusst ein, damit Nutzer nicht überrascht werden.

Siehe auch

AudioSession AudioSession.type Navigator AudioContext HTMLMediaElement.play() Navigator.mediaSession MediaKeySession.sessionId