RTCAudioSourceStats — Schnittstelle · JavaScript-Referenz

Signatur

interface RTCAudioSourceStats extends RTCMediaSourceStats

Beschreibung

RTCAudioSourceStats ist kein Konstruktor, sondern ein Wörterbuch (Dictionary). Die Objekte stecken im RTCStatsReport, den RTCPeerConnection.getStats() oder RTCRtpSender.getStats() zurückgibt. Erkennbar sind sie an type === "media-source" zusammen mit kind === "audio". Sie beschreiben die lokale Quelle, also das Mikrofonsignal, bevor es kodiert und versendet wird.

Nützlich sind die Werte vor allem für Pegelanzeigen („Sie sind stummgeschaltet“ oder „Mikrofon empfängt nichts“), für die Diagnose der Echounterdrückung (echoReturnLoss, echoReturnLossEnhancement) und für die Überwachung der Audioqualität im laufenden Gespräch. Weil die Statistik direkt aus dem Mediensystem stammt, brauchen Sie dafür keinen zusätzlichen AudioContext mit AnalyserNode.

Die Zählerwerte totalAudioEnergy und totalSamplesDuration steigen fortlaufend an. Den mittleren Pegel über einen Zeitraum berechnen Sie aus der Differenz zweier Messungen: Math.sqrt(ΔEnergie / ΔDauer). audioLevel ist dagegen nur eine Momentaufnahme.

Parameter

Name	Typ	Default	Beschreibung
$id Pflicht	string	—	Eindeutige Kennung des Statistik-Objekts im Report (geerbt von `RTCStats`).
$timestamp Pflicht	DOMHighResTimeStamp	—	Zeitpunkt der Messung in Millisekunden.
$type Pflicht	string	—	Immer `"media-source"`.
$kind Pflicht	string	—	Immer `"audio"` (bei `"video"` handelt es sich um `RTCVideoSourceStats`).
$trackIdentifier Pflicht	string	—	Die `id` der zugehörigen `MediaStreamTrack`.
$audioLevel	number	—	Aktueller Pegel zwischen 0 (Stille) und 1 (0 dBov). Die Skala ist linear.
$totalAudioEnergy	number	—	Aufsummierte Audioenergie seit Beginn. Zusammen mit `totalSamplesDuration` ergibt sich daraus der RMS-Pegel.
$totalSamplesDuration	number	—	Gesamtdauer aller erfassten Samples in Sekunden.
$echoReturnLoss	number	—	Echodämpfung in dB (nur vorhanden, wenn die Echounterdrückung aktiv ist).
$echoReturnLossEnhancement	number	—	Zusätzliche Echodämpfung durch den Echounterdrücker in dB.
$totalSamplesCaptured	number	—	Anzahl der erfassten Samples (experimentell).
$droppedSamplesDuration	number	—	Dauer der verworfenen Samples in Sekunden (experimentell).
$droppedSamplesEvents	number	—	Anzahl der Ereignisse, bei denen Samples verworfen wurden (experimentell).
$totalCaptureDelay	number	—	Aufsummierte Verzögerung bei der Aufnahme in Sekunden (experimentell).

Rückgabewert

Typ

RTCAudioSourceStats

Beschreibung

Ein einfaches Objekt als Eintrag in einem RTCStatsReport (einer Map-ähnlichen Struktur). Es wird nie direkt erzeugt.

Beispiele

Audio-Quellstatistik aus getStats() auslesen

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

const report = await pc.getStats();
report.forEach((stats) => {
  if (stats.type === 'media-source' && stats.kind === 'audio') {
    console.log('Track:', stats.trackIdentifier);
    console.log('Pegel:', stats.audioLevel);
    console.log('Dauer (s):', stats.totalSamplesDuration);
  }
});

Track: 3f1c… Pegel: 0.0421 Dauer (s): 1.23

Mikrofon-Pegelanzeige per Polling

const sender = pc.getSenders().find((s) => s.track?.kind === 'audio');
const meter = document.querySelector('#mic-level');

const timer = setInterval(async () => {
  const report = await sender.getStats();
  for (const stats of report.values()) {
    if (stats.type === 'media-source' && stats.kind === 'audio') {
      meter.value = stats.audioLevel ?? 0; // <meter min="0" max="1">
    }
  }
}, 200);

// Später: clearInterval(timer);

Mittleren RMS-Pegel über ein Intervall berechnen

const getAudioSource = async (sender) => {
  const report = await sender.getStats();
  return [...report.values()].find(
    (s) => s.type === 'media-source' && s.kind === 'audio'
  );
};

const sender = pc.getSenders().find((s) => s.track?.kind === 'audio');
const a = await getAudioSource(sender);
await new Promise((r) => setTimeout(r, 1000));
const b = await getAudioSource(sender);

const dEnergy = b.totalAudioEnergy - a.totalAudioEnergy;
const dDuration = b.totalSamplesDuration - a.totalSamplesDuration;
const rms = dDuration > 0 ? Math.sqrt(dEnergy / dDuration) : 0;
console.log(rms < 0.01 ? 'Mikrofon scheint stumm' : `RMS: ${rms.toFixed(3)}`);

RMS: 0.057

// Wichtig · Fallstricke

Browserunterstützung: Chromium-Browser und Safari liefern media-source-Statistiken. Firefox unterstützt sie nur teilweise oder erst in neueren Versionen. Prüfen Sie jedes Feld mit ?? oder in, bevor Sie es verwenden.
Experimentelle Felder wie totalCaptureDelay oder droppedSamplesDuration fehlen in vielen Browsern.
echoReturnLoss und echoReturnLossEnhancement gibt es nur, wenn echoCancellation aktiv ist und der Browser die Werte liefert.
Ist die Spur mit track.enabled = false stummgeschaltet, meldet audioLevel in der Regel 0. Das eignet sich, um eine Stummschaltung zu erkennen.
Rufen Sie getStats() nicht zu oft auf, denn jeder Aufruf kostet Rechenzeit. 100–500 ms sind für Pegelanzeigen ein üblicher Abstand.
Das Objekt ist erst im Report enthalten, wenn die Spur einem Sender zugeordnet ist (addTrack bzw. replaceTrack).

Siehe auch

RTCVideoSourceStats RTCCodecStats RTCTransportStats AudioPlaybackStats RTCCertificateStats