Signatur
Beschreibung
Die Eigenschaft audioLevel gehört zu den Statistiken vom Typ "inbound-rtp", die du über RTCPeerConnection.getStats() oder RTCRtpReceiver.getStats() bekommst. Sie gibt an, wie laut das Audio ist, das gerade von der Gegenstelle empfangen und abgespielt wird. Der Wert ist eine Gleitkommazahl von 0 bis 1.
Die Skala ist linear: 1.0 entspricht 0 dBov (maximaler Pegel), 0 steht für Stille, und 0.5 liegt ungefähr 6 dB unter 0 dBov. Der Wert wird über ein kurzes Zeitfenster gemittelt. Deshalb eignet er sich gut für Sprecher-Anzeigen, z. B. einen leuchtenden Rahmen um das Video der Person, die gerade spricht, oder für VU-Meter und für die Diagnose („Kommt überhaupt Ton an?“).
Die Eigenschaft gibt es nur bei Audio-Streams (kind === "audio"). Bei Video-Einträgen vom Typ inbound-rtp ist sie undefined. Wenn du einen genaueren Durchschnittspegel über einen bestimmten Zeitraum brauchst, nimm die kumulativen Werte totalAudioEnergy und totalSamplesDuration. Der Momentanwert von audioLevel ist dafür nicht gedacht.
Rückgabewert
0 (Stille) und 1 (0 dBov). Bei Video-Streams oder wenn der Browser die Eigenschaft nicht unterstützt: undefined.Beispiele
Audiopegel aller empfangenen Audio-Streams auslesen
// pc ist eine bestehende, verbundene RTCPeerConnection
const logInboundAudioLevels = async (pc) => {
const stats = await pc.getStats();
stats.forEach((report) => {
if (report.type === 'inbound-rtp' && report.kind === 'audio') {
console.log(`SSRC ${report.ssrc}: Pegel ${report.audioLevel?.toFixed(3)}`);
}
});
};
await logInboundAudioLevels(pc);Sprecher-Anzeige per Polling
// Hebt das Video hervor, solange die Gegenstelle spricht
const SPEAKING_THRESHOLD = 0.02;
const watchSpeaker = (receiver, videoElement) => {
const timer = setInterval(async () => {
const stats = await receiver.getStats();
for (const report of stats.values()) {
if (report.type === 'inbound-rtp' && report.kind === 'audio') {
const level = report.audioLevel ?? 0;
videoElement.classList.toggle('speaking', level > SPEAKING_THRESHOLD);
}
}
}, 200);
return () => clearInterval(timer); // Aufräumfunktion
};
const [audioReceiver] = pc.getReceivers().filter((r) => r.track.kind === 'audio');
const stopWatching = watchSpeaker(audioReceiver, document.querySelector('#remoteVideo'));Durchschnittspegel über ein Intervall aus totalAudioEnergy berechnen
// Genauer als der Momentanwert: RMS-Pegel zwischen zwei Messungen
const getAudioInbound = async (pc) => {
const stats = await pc.getStats();
return [...stats.values()].find((r) => r.type === 'inbound-rtp' && r.kind === 'audio');
};
const a = await getAudioInbound(pc);
await new Promise((resolve) => setTimeout(resolve, 1000));
const b = await getAudioInbound(pc);
const energy = b.totalAudioEnergy - a.totalAudioEnergy;
const duration = b.totalSamplesDuration - a.totalSamplesDuration;
const avgLevel = duration > 0 ? Math.sqrt(energy / duration) : 0;
console.log('Momentan:', b.audioLevel.toFixed(3), '| Mittel (1 s):', avgLevel.toFixed(3));// Wichtig · Fallstricke
- Lineare Skala, keine Dezibel: Für eine Anzeige in dB rechne den Wert mit
20 * Math.log10(audioLevel)um. Bei0ergibt das-Infinity, also diesen Fall vorher abfangen. - Nur bei Audio: Prüfe immer
report.kind === "audio". Bei Video-Einträgen fehlt die Eigenschaft. - Nur ein Momentanwert: Die Stats werden intern nur in Abständen aktualisiert. Wenn du häufiger als ungefähr alle 50–100 ms abfragst, bekommst du keine neuen Daten, verbrauchst aber trotzdem Rechenzeit. Für Durchschnittswerte
totalAudioEnergy/totalSamplesDurationverwenden. - Stumm ist nicht gleich 0: Wenn Pakete fehlen oder der Track stummgeschaltet ist, kann der Wert fehlen oder auf dem letzten Stand stehen bleiben. Werte außerdem
packetsReceivedaus. - Browser-Kompatibilität: Wird in Chromium-Browsern und Safari unterstützt. In Firefox ist die Unterstützung je nach Version eingeschränkt. Deshalb defensiv mit
?? 0bzw.?.zugreifen. Als Alternative, die überall funktioniert, kannst du den Pegel mit einemAnalyserNodeder Web Audio API messen. - Datenschutz: Pegelwerte verraten, wann jemand spricht. Übertrage sie nicht unnötig an Server oder Dritte.