RTCAudioSourceStats.totalSamplesDuration — Eigenschaft · JavaScript-Referenz

Signatur

RTCAudioSourceStats.totalSamplesDuration

Beschreibung

totalSamplesDuration ist eine schreibgeschützte Eigenschaft des Wörterbuchs RTCAudioSourceStats. Solche Einträge liefert RTCPeerConnection.getStats() bzw. RTCRtpSender.getStats() mit type === "media-source" und kind === "audio". Der Wert ist eine Gleitkommazahl in Sekunden. Er gibt an, wie viel Audio die lokale Quelle (etwa ein Mikrofon-Track) insgesamt erzeugt hat, seit das Statistikobjekt besteht.

Der Zähler ist kumulativ und steigt nur an. Sinnvoll wird er vor allem zusammen mit totalAudioEnergy. Du liest zwei Berichte zu verschiedenen Zeitpunkten und teilst die Differenz der Energie durch die Differenz der Dauer. Die Wurzel aus diesem Quotienten ist der durchschnittliche Audiopegel im Messintervall (Wertebereich 0 bis 1). Das ist genauer als der Momentwert audioLevel.

Typische Einsätze sind Pegelanzeigen für das eigene Mikrofon, das Erkennen stummgeschalteter oder hängender Quellen und Qualitätsmonitoring. Wächst totalSamplesDuration nicht mehr, liefert die Quelle keine Samples mehr.

Rückgabewert

Typ

number

Beschreibung

Kumulierte Dauer aller erzeugten Audio-Samples in Sekunden, als Gleitkommazahl (z. B. 12.34). Fehlt die Eigenschaft, ist sie undefined.

Beispiele

Gesamtdauer der Mikrofon-Samples auslesen

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const pc = new RTCPeerConnection();
const [track] = stream.getAudioTracks();
const sender = pc.addTrack(track, stream);

// Kurz warten, damit Samples erzeugt werden
await new Promise((r) => setTimeout(r, 2000));

const report = await sender.getStats();
report.forEach((stat) => {
  if (stat.type === 'media-source' && stat.kind === 'audio') {
    console.log(`Erzeugte Audiodauer: ${stat.totalSamplesDuration?.toFixed(2)} s`);
  }
});

Erzeugte Audiodauer: 2.01 s

Durchschnittlichen Pegel über ein Intervall berechnen

const getAudioSource = async (pc) => {
  const report = await pc.getStats();
  for (const stat of report.values()) {
    if (stat.type === 'media-source' && stat.kind === 'audio') return stat;
  }
  return null;
};

const measureAverageLevel = async (pc, intervalMs = 1000) => {
  const a = await getAudioSource(pc);
  await new Promise((r) => setTimeout(r, intervalMs));
  const b = await getAudioSource(pc);
  if (!a || !b) return null;

  const energy = b.totalAudioEnergy - a.totalAudioEnergy;
  const duration = b.totalSamplesDuration - a.totalSamplesDuration;
  return duration > 0 ? Math.sqrt(energy / duration) : 0;
};

// Nutzung mit einer bestehenden RTCPeerConnection "pc"
const level = await measureAverageLevel(pc);
console.log('Durchschnittspegel:', level?.toFixed(3));

Durchschnittspegel: 0.042

Hängende Audioquelle erkennen

const watchSource = (pc, onStall) => {
  let last = null;
  const id = setInterval(async () => {
    const report = await pc.getStats();
    const src = [...report.values()].find(
      (s) => s.type === 'media-source' && s.kind === 'audio'
    );
    if (!src) return;
    if (last !== null && src.totalSamplesDuration === last) onStall();
    last = src.totalSamplesDuration;
  }, 2000);
  return () => clearInterval(id);
};

const stop = watchSource(pc, () => console.warn('Audioquelle liefert keine Samples mehr'));
// später: stop();

Audioquelle liefert keine Samples mehr (nur wenn die Quelle stockt)

// Wichtig · Fallstricke

Kumulativer Wert: Der absolute Wert sagt wenig aus. Arbeite immer mit Differenzen zwischen zwei Messungen, besonders zusammen mit totalAudioEnergy.
Division durch null: Ist die Differenz von totalSamplesDuration gleich 0, etwa bei sehr kurzen Intervallen oder angehaltener Quelle, fange das vor der Pegelberechnung ab.
Nur lokale Quellen: Die Eigenschaft beschreibt die gesendete Quelle (media-source). Für empfangenes Audio gibt es das gleichnamige Feld in RTCInboundRtpStreamStats.
Stummschaltung: Ist ein Track mit track.enabled = false deaktiviert, kann die Dauer weiter steigen, während die Energie nahezu 0 bleibt. Der Wert zeigt also nicht, ob Ton übertragen wird.
Kompatibilität: Chromium-Browser und Safari unterstützen die Eigenschaft, Firefox liefert keine media-source-Audiostatistiken mit diesem Feld. Prüfe den Wert deshalb vor der Verwendung, z. B. mit typeof stat.totalSamplesDuration === 'number'.

Siehe auch

RTCAudioSourceStats RTCAudioSourceStats.totalAudioEnergy RTCAudioSourceStats.audioLevel RTCPeerConnection.prototype.getStats() RTCRtpSender.prototype.getStats() RTCStatsReport