AudioPlaybackStats.toJSON() — Methode · JavaScript-Referenz

Signatur

AudioPlaybackStats.prototype.toJSON()

Beschreibung

Die Methode toJSON() der Schnittstelle AudioPlaybackStats ist ein Serializer. Sie erzeugt ein einfaches JavaScript-Objekt, das die aktuellen Werte aller Statistik-Eigenschaften enthält, zum Beispiel underrunDuration, underrunEvents, totalDuration, averageLatency, minimumLatency und maximumLatency. Dauer- und Latenzwerte werden in Sekunden angegeben.

Ein AudioPlaybackStats-Objekt bekommt man über die Eigenschaft playbackStats eines AudioContext. Die Eigenschaften sind Getter auf dem Prototyp und keine eigenen Eigenschaften der Instanz. Deshalb würde JSON.stringify() ohne toJSON() nur {} liefern. JSON.stringify() ruft toJSON() automatisch auf. Die Methode direkt aufzurufen lohnt sich, wenn Sie eine Momentaufnahme der Werte als normales Objekt speichern, vergleichen oder an einen Telemetrie-Endpunkt schicken wollen.

Typische Einsatzfälle sind das Überwachen der Audioqualität in Echtzeit-Anwendungen (WebRTC, Spiele, Musik-Apps), das Protokollieren von Aussetzern (Underruns) und das Übertragen von Latenzwerten mit navigator.sendBeacon() oder fetch().

Rückgabewert

Typ

Object

Beschreibung

Ein einfaches Objekt mit den aktuellen Werten der AudioPlaybackStats-Eigenschaften (z. B. underrunDuration, underrunEvents, totalDuration, averageLatency, minimumLatency, maximumLatency). Es ist eine Momentaufnahme und aktualisiert sich später nicht mehr.

Beispiele

Momentaufnahme der Wiedergabe-Statistik ausgeben

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

// Nach zwei Sekunden die Statistik auslesen
setTimeout(() => {
  if (!('playbackStats' in ctx)) {
    console.warn('AudioPlaybackStats wird nicht unterstützt');
    return;
  }
  const snapshot = ctx.playbackStats.toJSON();
  console.log(snapshot);
}, 2000);

{ underrunDuration: 0, underrunEvents: 0, totalDuration: 2.01, averageLatency: 0.021, minimumLatency: 0.02, maximumLatency: 0.023 }

Unterschied zwischen JSON.stringify mit und ohne toJSON

const ctx = new AudioContext();
const stats = ctx.playbackStats;

// Die Getter liegen auf dem Prototyp, deshalb gibt es keine eigenen Eigenschaften
console.log(Object.keys(stats));

// JSON.stringify ruft toJSON() automatisch auf
console.log(JSON.stringify(stats, null, 2));

[] { "underrunDuration": 0, "underrunEvents": 0, "totalDuration": 0, ... }

Statistik regelmäßig an einen Telemetrie-Endpunkt senden

const ctx = new AudioContext();

const reportStats = () => {
  const stats = ctx.playbackStats?.toJSON();
  if (!stats) return;

  const payload = {
    timestamp: Date.now(),
    ...stats,
    // Anteil der Aussetzer an der Gesamtdauer
    underrunRatio: stats.totalDuration > 0
      ? stats.underrunDuration / stats.totalDuration
      : 0
  };
  navigator.sendBeacon('/api/audio-telemetry', JSON.stringify(payload));
};

const timer = setInterval(reportStats, 10_000);
// Beim Verlassen der Seite ein letztes Mal senden
addEventListener('pagehide', () => {
  clearInterval(timer);
  reportStats();
});

// Wichtig · Fallstricke

Experimentelle API: AudioContext.playbackStats und AudioPlaybackStats gibt es bisher nur in neueren Chromium-Versionen. Prüfen Sie vorher, ob die Eigenschaft vorhanden ist, z. B. mit 'playbackStats' in ctx oder optionaler Verkettung (ctx.playbackStats?.toJSON()).
Momentaufnahme: Das zurückgegebene Objekt aktualisiert sich nicht. Für neue Werte rufen Sie toJSON() erneut auf. Außerdem aktualisiert der Browser die Werte aus Datenschutzgründen nur in bestimmten Abständen (etwa einmal pro Sekunde). Sehr häufiges Abfragen bringt daher nichts.
Einheiten: Dauer- und Latenzwerte sind in Sekunden angegeben, nicht in Millisekunden.
Die Latenzwerte (averageLatency, minimumLatency, maximumLatency) können Sie mit resetLatency() zurücksetzen. Die Werte für Underruns und die Gesamtdauer zählen trotzdem weiter.
Object.keys(), Spread ({...stats}) und structuredClone() auf das Originalobjekt ergeben keine sinnvollen Daten. Nutzen Sie dafür immer toJSON().

Siehe auch

JSON.stringify() MediaKeyStatusMap.forEach() PerformanceScriptTiming.toJSON() AudioPlaybackStats.resetLatency() ContactAddress.toJSON()