Signatur
Beschreibung
Die Eigenschaft playbackStats eines AudioContext gibt ein AudioPlaybackStats-Objekt zurück. Darüber lässt sich messen, wie zuverlässig der Audio-Graph tatsächlich auf dem Ausgabegerät abgespielt wird. Solche Informationen gab es bisher nur indirekt, etwa über outputLatency oder eigene Messungen per Heuristik.
Das Statistik-Objekt stellt unter anderem folgende Werte bereit:
totalDuration: gesamte abgespielte Dauer in SekundenunderrunDurationundunderrunEvents: Dauer bzw. Anzahl der Aussetzer, bei denen der Audio-Thread nicht rechtzeitig Daten geliefert hat (hörbare Knackser oder Stille)averageLatency,minimumLatency,maximumLatency: Latenzwerte der Ausgabe in SekundenresetLatency(): setzt die Latenz-Statistik zurück, damit neue Messintervalle beginnen können
Typische Einsatzfälle sind Telemetrie in Echtzeit-Audio-Anwendungen wie DAWs, Spielen oder WebRTC-Clients, das Erkennen einer Überlastung durch zu rechenintensive AudioWorklet-Verarbeitung und das dynamische Anpassen der Qualität, zum Beispiel über weniger Effekte oder eine größere latencyHint.
Die Eigenschaft ist schreibgeschützt. Das zurückgegebene Objekt gehört fest zum Kontext und wird fortlaufend aktualisiert. Man liest es also regelmäßig aus und erzeugt es nicht neu.
Rückgabewert
totalDuration, underrunDuration, underrunEvents, averageLatency, minimumLatency und maximumLatency sowie den Methoden resetLatency() und toJSON(). Zeitwerte werden in Sekunden angegeben.Beispiele
Statistiken mit Funktionsprüfung auslesen
const ctx = new AudioContext();
if ('playbackStats' in ctx) {
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`);
} else {
console.warn('AudioContext.playbackStats wird nicht unterstützt.');
}Aussetzer überwachen und Qualität anpassen
const ctx = new AudioContext({ latencyHint: 'interactive' });
const osc = new OscillatorNode(ctx, { frequency: 440 });
osc.connect(ctx.destination);
osc.start();
let lastUnderruns = 0;
const monitor = setInterval(() => {
const { underrunEvents, totalDuration } = ctx.playbackStats;
const neu = underrunEvents - lastUnderruns;
lastUnderruns = underrunEvents;
if (neu > 0) {
console.warn(`${neu} neue Aussetzer nach ${totalDuration.toFixed(1)} s. Effekte werden reduziert.`);
// z. B. aufwendige Hall-Effekte deaktivieren
}
}, 2000);
// Aufräumen
const stop = async () => {
clearInterval(monitor);
await ctx.close();
};Latenz pro Messintervall erfassen und als JSON senden
const ctx = new AudioContext();
const reportLatency = () => {
const stats = ctx.playbackStats;
const payload = JSON.stringify(stats); // nutzt toJSON()
navigator.sendBeacon('/telemetry/audio', payload);
stats.resetLatency(); // neues Latenz-Intervall beginnen
};
setInterval(reportLatency, 10_000);// Wichtig · Fallstricke
Experimentell: Die API ist bisher nur in neueren Chromium-Versionen verfügbar, nicht in Firefox und Safari. Deshalb vorher immer mit 'playbackStats' in ctx prüfen, ob sie unterstützt wird. Name und Form des Objekts können sich noch ändern.
- Die Werte werden aus Datenschutzgründen (Schutz vor Fingerprinting) nicht bei jedem Zugriff neu gemessen, sondern nur in größeren Abständen aktualisiert. Deshalb eignen sie sich nicht zum Messen einzelner Render-Quanten.
resetLatency()setzt nur die Latenzwerte zurück, nichtunderrunEventsodertotalDuration. Unterschiede zwischen zwei Zeitpunkten musst du bei Bedarf selbst ausrechnen.- Solange der Kontext im Zustand
suspendedist, etwa ohne Nutzerinteraktion wegen der Autoplay-Richtlinie, steigen die Werte nicht. - Für einen
OfflineAudioContextgibt es die Eigenschaft nicht, weil dort nichts auf einem Ausgabegerät abgespielt wird.