Signatur
Beschreibung
outputLatency ist eine schreibgeschützte Eigenschaft von AudioContext. Sie liefert eine Schätzung in Sekunden, wie viel Zeit vergeht, nachdem der Audio-Graph ein Sample berechnet hat, bis das Signal über das Ausgabegerät (Lautsprecher, Kopfhörer, Bluetooth-Gerät) tatsächlich zu hören ist. Dazu gehören Puffer des Betriebssystems, des Audiotreibers und der Hardware.
Zusammen mit baseLatency ergibt sich die gesamte Latenz: baseLatency beschreibt die Verzögerung innerhalb der Web-Audio-Verarbeitung, outputLatency die Verzögerung danach. Die Summe beider Werte gibt an, wie weit das Gehörte hinter currentTime zurückliegt.
Nützlich ist die Eigenschaft vor allem, wenn Audio mit anderen Dingen synchron laufen muss, zum Beispiel mit Animationen, Video, Rhythmusspielen oder visuellen Metronomen. Genauer als outputLatency allein ist oft getOutputTimestamp(), das Kontextzeit und Performance-Zeit als Paar zurückgibt.
Der Wert kann sich während der Laufzeit ändern, etwa wenn der Nutzer das Ausgabegerät wechselt (z. B. von Lautsprechern auf Bluetooth-Kopfhörer). Lies ihn deshalb bei Bedarf neu aus und speichere ihn nicht nur einmal.
Rückgabewert
double), z. B. 0.02 für 20 ms. Solange der Kontext noch nicht läuft, ist der Wert oft 0.Beispiele
Gesamte Latenz in Millisekunden anzeigen
const ctx = new AudioContext();
// Nach einer Nutzeraktion starten, damit die Autoplay-Sperre nicht greift
document.querySelector('#start').addEventListener('click', async () => {
await ctx.resume();
const total = ctx.baseLatency + ctx.outputLatency;
console.log(`Basis: ${(ctx.baseLatency * 1000).toFixed(1)} ms`);
console.log(`Ausgabe: ${(ctx.outputLatency * 1000).toFixed(1)} ms`);
console.log(`Gesamt: ${(total * 1000).toFixed(1)} ms`);
});Visuelles Metronom mit Latenzausgleich
const ctx = new AudioContext();
const dot = document.querySelector('#beat');
const scheduleClick = (when) => {
const osc = new OscillatorNode(ctx, { frequency: 1000 });
const gain = new GainNode(ctx, { gain: 0.3 });
osc.connect(gain).connect(ctx.destination);
osc.start(when);
osc.stop(when + 0.05);
// Zeitpunkt, zu dem der Klick tatsächlich hörbar ist
const latency = ctx.baseLatency + (ctx.outputLatency || 0);
const delayMs = (when - ctx.currentTime + latency) * 1000;
setTimeout(() => {
dot.classList.add('active');
setTimeout(() => dot.classList.remove('active'), 80);
}, delayMs);
};
document.querySelector('#start').addEventListener('click', async () => {
await ctx.resume();
const start = ctx.currentTime + 0.1;
for (let i = 0; i < 8; i++) scheduleClick(start + i * 0.5);
});Gerätewechsel erkennen und Latenz neu auslesen
const ctx = new AudioContext();
const logLatency = () => {
if (!('outputLatency' in ctx)) {
console.warn('outputLatency wird nicht unterstützt');
return;
}
console.log(`Aktuelle Ausgabe-Latenz: ${(ctx.outputLatency * 1000).toFixed(1)} ms`);
};
// Beim Wechsel von Lautsprecher auf Bluetooth-Kopfhörer ändert sich der Wert
navigator.mediaDevices.addEventListener('devicechange', () => {
// kurz warten, bis das System umgeschaltet hat
setTimeout(logLatency, 500);
});
ctx.resume().then(logLatency);// Wichtig · Fallstricke
- Nur eine Schätzung: Die tatsächliche Verzögerung kann abweichen, vor allem bei Bluetooth-Geräten, die oft 100–300 ms Latenz haben und dem Browser ungenaue Werte melden.
- Wert ist oft
0, solange der Kontext im Zustandsuspendedist. Lies ihn erst aus, wennctx.state === 'running'gilt. - Nicht bei
OfflineAudioContext: Die Eigenschaft gibt es nur beiAudioContext, weil ein Offline-Kontext kein echtes Ausgabegerät hat. - Browser-Kompatibilität: Firefox unterstützt die Eigenschaft seit Version 70, Chromium-Browser seit Version 102, Safari erst ab 18.4. Prüfe mit
'outputLatency' in ctx, ob sie vorhanden ist, und nimm sonst0odergetOutputTimestamp()als Ersatz. - Datenschutz: Einige Browser runden den Wert oder machen ihn ungenauer, damit er nicht zum Fingerprinting verwendet werden kann.