AudioPlaybackStats — Schnittstelle · JavaScript-Referenz

Signatur

interface AudioPlaybackStats

Beschreibung

Die Schnittstelle AudioPlaybackStats gehört zur Web Audio API. Mit ihr lässt sich die Qualität der Audioausgabe eines AudioContext überwachen. Man erzeugt sie nicht selbst: Jeder AudioContext stellt über die Eigenschaft playbackStats ein passendes Objekt bereit.

Die Schnittstelle bietet folgende schreibgeschützte Eigenschaften, alle Zeitangaben in Sekunden:

totalDuration: Gesamtdauer der bisher abgespielten Audiodaten (inklusive Aussetzern).
underrunDuration: Gesamtdauer der Aussetzer. Das sind Abschnitte, in denen der Audio-Thread nicht rechtzeitig Daten liefern konnte und Stille ausgegeben wurde.
underrunEvents: Anzahl der Aussetzer-Ereignisse. Aufeinanderfolgende ausgefallene Frames zählen als ein Ereignis.
averageLatency, minimumLatency, maximumLatency: Durchschnittliche, minimale und maximale Ausgabelatenz seit dem Start bzw. seit dem letzten resetLatency().

Dazu kommen die Methoden resetLatency() (setzt die Latenzwerte auf den aktuellen Wert zurück, damit ein neues Messintervall beginnt) und toJSON() (gibt einen Schnappschuss als einfaches Objekt zurück).

Typische Einsatzfälle sind Telemetrie in Musik-, DAW- oder Spiele-Anwendungen, WebRTC- und Streaming-Clients sowie adaptive Logik. Ein Beispiel: Bei häufigen Aussetzern wird der Audio-Graph vereinfacht oder die latencyHint erhöht.

Rückgabewert

Typ

AudioPlaybackStats

Beschreibung

Wird über AudioContext.prototype.playbackStats abgerufen. Pro Kontext gibt es ein Objekt, dessen Werte der Browser laufend aktualisiert.

Beispiele

Statistiken eines AudioContext auslesen

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

// Nach zwei Sekunden Wiedergabe die Statistik ausgeben
setTimeout(() => {
  const stats = ctx.playbackStats;
  console.log(`Gespielt: ${stats.totalDuration.toFixed(2)} s`);
  console.log(`Aussetzer: ${stats.underrunEvents} (${stats.underrunDuration.toFixed(3)} s)`);
  console.log(`Latenz Ø: ${(stats.averageLatency * 1000).toFixed(1)} ms`);
  osc.stop();
}, 2000);

Gespielt: 2.00 s Aussetzer: 0 (0.000 s) Latenz Ø: 21.3 ms

Latenz pro Messintervall mit resetLatency() überwachen

const ctx = new AudioContext({ latencyHint: 'interactive' });

const report = () => {
  const { minimumLatency, averageLatency, maximumLatency } = ctx.playbackStats;
  console.table({
    min: `${(minimumLatency * 1000).toFixed(1)} ms`,
    avg: `${(averageLatency * 1000).toFixed(1)} ms`,
    max: `${(maximumLatency * 1000).toFixed(1)} ms`
  });
  // Nächstes Intervall startet mit frischen Latenzwerten
  ctx.playbackStats.resetLatency();
};

setInterval(report, 10_000);

Aussetzerquote als Telemetrie senden (mit Feature-Erkennung)

const ctx = new AudioContext();

const sendTelemetry = () => {
  if (!('playbackStats' in ctx)) return; // API nicht unterstützt
  const snapshot = ctx.playbackStats.toJSON();
  const ratio = snapshot.totalDuration > 0
    ? snapshot.underrunDuration / snapshot.totalDuration
    : 0;

  navigator.sendBeacon('/api/audio-stats', JSON.stringify({
    ...snapshot,
    underrunRatio: ratio
  }));

  if (ratio > 0.01) {
    console.warn('Mehr als 1 % Aussetzer – Audio-Graph vereinfachen?');
  }
};

addEventListener('pagehide', sendTelemetry);

// Wichtig · Fallstricke

Experimentell: Die API wird derzeit nur von Chromium-basierten Browsern unterstützt. Firefox und Safari kennen sie (noch) nicht. Prüfen Sie deshalb immer mit 'playbackStats' in audioContext, bevor Sie darauf zugreifen.
Datenschutz und Aktualisierung: Um Fingerprinting und Timing-Angriffe zu erschweren, aktualisiert der Browser die Werte nur in groben Abständen (etwa einmal pro Sekunde). Innerhalb derselben Aufgabe (Task) bleiben sie konstant. Für Messungen mit feiner zeitlicher Auflösung taugen sie daher nicht.
Alle Zeitwerte sind Gleitkommazahlen in Sekunden, nicht in Millisekunden.
OfflineAudioContext hat kein playbackStats, da er nichts an ein Ausgabegerät abspielt.
Solange der Kontext im Zustand suspended ist (z. B. vor der ersten Nutzerinteraktion wegen der Autoplay-Regeln), wächst totalDuration nicht.
Die Latenzwerte beschreiben nur die Ausgabelatenz. Die Verarbeitungszeit des Audio-Graphen ist darin nicht enthalten. Vergleichbar sind sie mit AudioContext.outputLatency.

Siehe auch

AudioContext AudioContext.playbackStats AudioContext.outputLatency AudioContext.baseLatency BaseAudioContext AudioWorkletNode