AudioPlaybackStats.underrunEvents — Eigenschaft · JavaScript-Referenz

Signatur

AudioPlaybackStats.underrunEvents

Beschreibung

Die Eigenschaft underrunEvents des Interfaces AudioPlaybackStats zählt, wie oft die Audio-Engine ihre Ausgabepuffer nicht rechtzeitig füllen konnte. Zu einem solchen Underrun kommt es, wenn der Audio-Rendering-Thread die nächsten Samples nicht bis zur Frist fertig hat, etwa weil ein AudioWorkletProcessor zu viel rechnet, der Graph zu groß ist oder das System stark ausgelastet ist. Der Browser füllt die Lücke dann mit Stille auf. Zu hören sind Knackser, Aussetzer oder „Glitches“.

Das Objekt AudioPlaybackStats erreichst du über audioContext.playbackStats. Der Zähler steigt ab dem Start des Kontexts nur an. Wenn du wissen willst, ob in einem bestimmten Zeitraum Aussetzer aufgetreten sind, speicherst du den Wert, liest ihn später erneut und bildest die Differenz. Zusammen mit underrunDuration (gesamte Dauer der aufgefüllten Stille) und totalDuration kannst du berechnen, wie gut die Wiedergabe insgesamt läuft.

Typische Einsatzfälle sind Telemetrie in Web-DAWs, Synthesizern, Spielen und WebRTC-Anwendungen. Auch eine adaptive Qualitätssteuerung ist möglich: Häufen sich die Underruns, verringert die Anwendung die Zahl der Effekte oder Stimmen, oder sie erzeugt den Kontext mit einem größeren latencyHint neu.

Rückgabewert

Typ

number

Beschreibung

Eine nicht negative ganze Zahl: die Anzahl der Underrun-Ereignisse seit dem Start des Audio-Kontexts. Die Eigenschaft ist schreibgeschützt.

Beispiele

Underruns einmalig auslesen (mit Feature-Erkennung)

const ctx = new AudioContext();

if ('playbackStats' in ctx) {
  const stats = ctx.playbackStats;
  console.log(`Underruns bisher: ${stats.underrunEvents}`);
  console.log(`Stille insgesamt: ${stats.underrunDuration.toFixed(3)} s`);
} else {
  console.log('AudioPlaybackStats wird nicht unterstützt.');
}

Underruns bisher: 0 Stille insgesamt: 0.000 s

Neue Aussetzer regelmäßig überwachen

const ctx = new AudioContext({ latencyHint: 'interactive' });
const osc = new OscillatorNode(ctx, { frequency: 440 });
osc.connect(ctx.destination);

const startButton = document.querySelector('#start');
startButton.addEventListener('click', async () => {
  await ctx.resume();
  osc.start();

  let lastCount = ctx.playbackStats.underrunEvents;

  setInterval(() => {
    const current = ctx.playbackStats.underrunEvents;
    const delta = current - lastCount;
    if (delta > 0) {
      console.warn(`${delta} neue Underrun(s) in der letzten Sekunde`);
    }
    lastCount = current;
  }, 1000);
});

3 neue Underrun(s) in der letzten Sekunde

Qualität automatisch reduzieren und Telemetrie senden

const ctx = new AudioContext();
let reducedQuality = false;
let baseline = ctx.playbackStats?.underrunEvents ?? 0;

const reduceVoices = () => {
  // Anwendungsspezifisch: z. B. Hall abschalten, weniger Stimmen
  console.log('Qualität reduziert, um Aussetzer zu vermeiden.');
};

const checkGlitches = () => {
  const stats = ctx.playbackStats;
  if (!stats) return;

  const recent = stats.underrunEvents - baseline;
  baseline = stats.underrunEvents;

  if (recent >= 5 && !reducedQuality) {
    reducedQuality = true;
    reduceVoices();
  }
};

setInterval(checkGlitches, 2000);

// Beim Verlassen der Seite: Kennzahlen an den Server schicken
addEventListener('pagehide', () => {
  const stats = ctx.playbackStats;
  if (stats) {
    navigator.sendBeacon('/api/audio-stats', JSON.stringify(stats.toJSON()));
  }
});

Qualität reduziert, um Aussetzer zu vermeiden.

// Wichtig · Fallstricke

Experimentell: AudioContext.playbackStats und AudioPlaybackStats sind neu und bisher nur in Chromium-Browsern verfügbar. Prüfe vor dem Zugriff immer mit 'playbackStats' in ctx oder mit optionaler Verkettung (ctx.playbackStats?.underrunEvents).
Zähler statt Rate: Der Wert steigt ab dem Start des Kontexts nur an. Für aktuelle Aussetzer vergleichst du zwei Messungen und bildest die Differenz. Ein neu erzeugter AudioContext beginnt wieder bei 0.
Verzögerte Aktualisierung: Die Statistik wird nicht nach jedem Render-Quantum aktualisiert, sondern in Abständen. Zu viele Abfragen pro Sekunde liefern deshalb keine zusätzlichen Daten.
Anzahl ist nicht Schwere: Ein einzelnes langes Ereignis kann stärker stören als mehrere kurze. Werte deshalb zusätzlich underrunDuration aus.
Mögliche Ursachen: aufwendige AudioWorkletProcessor-Logik, Speicherbereinigung (Garbage Collection) im Worklet, sehr niedriger latencyHint, ein ausgelastetes System oder ein Tab im Hintergrund. Ein größerer latencyHint (z. B. 'playback') verringert die Zahl der Underruns, erhöht aber die Latenz.
Datenschutz: Die Angaben verraten etwas über die Leistung des Geräts. Übermittle sie nur zusammengefasst und im Einklang mit deiner Datenschutzerklärung.

Siehe auch

AudioPlaybackStats.underrunDuration AudioPlaybackStats.averageLatency AudioPlaybackStats.maximumLatency AudioPlaybackStats.minimumLatency AudioPlaybackStats.totalDuration