AudioPlaybackStats.totalDuration — Eigenschaft · JavaScript-Referenz

Signatur

AudioPlaybackStats.totalDuration

Beschreibung

totalDuration ist eine schreibgeschützte Eigenschaft der Schnittstelle AudioPlaybackStats. Das zugehörige Objekt erhalten Sie über audioContext.playbackStats. Der Wert ist eine Gleitkommazahl in Sekunden. Er gibt an, wie viele Audioframes der Audiokontext seit seiner Initialisierung insgesamt an das Ausgabegerät geliefert hat. Frames, die wegen eines Unterlaufs (Underrun) als Stille ersetzt wurden, zählen ebenfalls mit.

Nützlich ist die Eigenschaft vor allem als Bezugsgröße für andere Kennzahlen. Zusammen mit underrunDuration berechnen Sie zum Beispiel, wie viel Prozent der Wiedergabe von Aussetzern (Glitches) betroffen waren. So lässt sich die Audioqualität in Web-Apps wie Videokonferenzen, Spielen, DAWs oder Streaming-Playern überwachen und an ein Monitoring melden.

Beachten Sie: Die Statistik läuft nicht in Echtzeit mit. Aus Datenschutzgründen (Schutz vor Fingerprinting) aktualisiert der Browser die Werte nur in Abständen. Solange der Kontext im Zustand "suspended" ist, wird keine Audiodauer hinzugezählt. Zum Messen einer Zeitspanne lesen Sie den Wert zweimal aus und bilden die Differenz. Ein Zurücksetzen von totalDuration gibt es nicht.

Rückgabewert

Typ

number

Beschreibung

Gesamtdauer der ausgegebenen Audioframes in Sekunden (double, ≥ 0). Der Wert wächst monoton, solange der Kontext läuft.

Beispiele

Gesamtdauer der Wiedergabe auslesen

const ctx = new AudioContext();
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 { totalDuration } = ctx.playbackStats;
  console.log(`Abgespielt: ${totalDuration.toFixed(2)} s`);
  osc.stop();
}, 3000);

Abgespielt: 3.00 s (ungefähr, der Wert wird nur in Abständen aktualisiert)

Glitch-Anteil berechnen (Underrun-Quote)

const glitchRatio = (ctx) => {
  const { totalDuration, underrunDuration } = ctx.playbackStats;
  if (totalDuration === 0) return 0;
  return underrunDuration / totalDuration;
};

const ctx = new AudioContext();
// ... Audiograph aufbauen und abspielen ...
setInterval(() => {
  const pct = (glitchRatio(ctx) * 100).toFixed(3);
  console.log(`Aussetzer-Anteil: ${pct} %`);
}, 5000);

Aussetzer-Anteil: 0.012 %

Zeitfenster per Differenz messen und melden

const ctx = new AudioContext();
let last = { total: 0, underrun: 0 };

const report = () => {
  const s = ctx.playbackStats;
  const deltaTotal = s.totalDuration - last.total;
  const deltaUnderrun = s.underrunDuration - last.underrun;
  last = { total: s.totalDuration, underrun: s.underrunDuration };

  if (deltaTotal > 0) {
    navigator.sendBeacon('/metrics/audio', JSON.stringify({
      seconds: deltaTotal,
      glitchSeconds: deltaUnderrun,
      avgLatency: s.averageLatency
    }));
  }
};

setInterval(report, 30_000);

// Wichtig · Fallstricke

Experimentell: AudioContext.playbackStats und AudioPlaybackStats gibt es bisher nur in neueren Chromium-Versionen. Firefox und Safari unterstützen die Schnittstelle nicht. Prüfen Sie die Unterstützung vorher, zum Beispiel mit 'playbackStats' in ctx.
Werte kommen verzögert: Aus Datenschutzgründen aktualisiert der Browser die Werte nur in Abständen. Für eine sample-genaue Zeitmessung eignet sich totalDuration nicht, nutzen Sie dafür AudioContext.currentTime.
Nicht verwechseln mit currentTime: totalDuration zählt nur Frames, die tatsächlich an das Ausgabegerät geliefert wurden, einschließlich Stille bei Underruns.
resetLatency() setzt nur die Latenzwerte zurück, nicht totalDuration. Für Messungen über ein bestimmtes Zeitfenster bilden Sie deshalb selbst die Differenz.
Bei OfflineAudioContext steht die Eigenschaft nicht zur Verfügung, weil es dort kein Ausgabegerät gibt.

Siehe auch

AudioPlaybackStats AudioPlaybackStats.underrunDuration AudioPlaybackStats.underrunEvents AudioPlaybackStats.averageLatency AudioPlaybackStats.resetLatency() AudioContext.playbackStats BaseAudioContext.currentTime