Signatur
Beschreibung
Die schreibgeschützte Eigenschaft averageLatency des AudioPlaybackStats-Interfaces gibt die durchschnittliche Wiedergabelatenz eines AudioContext als Gleitkommazahl in Sekunden an. Gemeint ist die Zeit, die zwischen dem Rendern eines Audio-Frames durch den Kontext und seiner tatsächlichen Ausgabe über das Audiogerät vergeht.
Der Durchschnitt wird über den Zeitraum seit der Initialisierung des Audio-Kontexts gebildet. Wurde zwischendurch AudioPlaybackStats.resetLatency() aufgerufen, beginnt die Messung ab diesem Zeitpunkt neu. So lässt sich die Latenz gezielt für einen bestimmten Abschnitt messen, etwa nach einem Gerätewechsel oder nach dem Start eines Musikstücks.
Du erreichst das Objekt über audioContext.playbackStats. Sinnvoll ist die Eigenschaft vor allem für Telemetrie und Qualitätsüberwachung, zum Beispiel in Videokonferenz-Apps, Musik-Apps im Browser oder Spielen. Dort willst du Audio mit Bild oder Nutzereingaben synchronisieren, oder du willst erkennen, dass bestimmte Geräte (etwa Bluetooth-Kopfhörer) eine hohe Verzögerung verursachen. Zusammen mit minimumLatency und maximumLatency siehst du auch, wie stark die Latenz schwankt.
Rückgabewert
double), gemessen seit Start des Kontexts oder seit dem letzten Aufruf von resetLatency().Beispiele
Durchschnittliche Latenz auslesen
const ctx = new AudioContext();
// Kurz abspielen, damit Statistiken entstehen
const osc = new OscillatorNode(ctx, { frequency: 440 });
osc.connect(ctx.destination);
osc.start();
setTimeout(() => {
if (!('playbackStats' in ctx)) {
console.warn('AudioPlaybackStats wird nicht unterstützt');
return;
}
const ms = ctx.playbackStats.averageLatency * 1000;
console.log(`Ø Latenz: ${ms.toFixed(1)} ms`);
osc.stop();
}, 2000);Latenz-Spanne für Telemetrie erfassen
const collectLatencyReport = (ctx) => {
const { averageLatency, minimumLatency, maximumLatency } = ctx.playbackStats;
return {
avgMs: Math.round(averageLatency * 1000),
minMs: Math.round(minimumLatency * 1000),
maxMs: Math.round(maximumLatency * 1000),
};
};
const ctx = new AudioContext();
// ... Audiograph aufbauen und abspielen ...
setInterval(() => {
const report = collectLatencyReport(ctx);
console.log(report);
// z. B. navigator.sendBeacon('/telemetry', JSON.stringify(report));
}, 10_000);Messung nach Gerätewechsel zurücksetzen
const ctx = new AudioContext();
const switchOutput = async (deviceId) => {
await ctx.setSinkId(deviceId);
// Alte Werte würden den Durchschnitt verfälschen
ctx.playbackStats.resetLatency();
setTimeout(() => {
const avg = ctx.playbackStats.averageLatency;
if (avg > 0.15) {
console.warn(`Hohe Latenz (${(avg * 1000).toFixed(0)} ms) – evtl. Bluetooth-Gerät`);
}
}, 3000);
};// Wichtig · Fallstricke
- Experimentell:
AudioContext.playbackStatsgibt es bisher nur in Chromium-basierten Browsern. Firefox und Safari unterstützen es noch nicht. Prüfe deshalb immer vorab mit'playbackStats' in ctx, ob die Eigenschaft vorhanden ist. - Einheit Sekunden: Der Wert ist eine Gleitkommazahl in Sekunden, nicht in Millisekunden. Für die Anzeige musst du ihn mit 1000 multiplizieren.
- Keine Echtzeitwerte: Aus Datenschutzgründen (Schutz vor Fingerprinting) aktualisiert der Browser die Statistiken nur in groben Abständen, typischerweise etwa einmal pro Sekunde. Wenn du den Wert mehrmals im selben Task abfragst, bekommst du denselben Stand zurück.
- Direkt nach dem Erzeugen des Kontexts oder solange er angehalten ist (
suspended), kann der Wert0sein oder wenig aussagekräftig. - Diese Eigenschaft ist nicht dasselbe wie
AudioContext.baseLatencyundAudioContext.outputLatency. Jene liefern eine Momentaufnahme bzw. Schätzung,averageLatencydagegen einen Mittelwert über einen Zeitraum.