RTCAudioSourceStats.kind — Eigenschaft · JavaScript-Referenz

Signatur

RTCAudioSourceStats.kind

Beschreibung

Die Eigenschaft kind gehört zum Dictionary RTCAudioSourceStats. Das ist die Audio-Variante der Statistiken vom Typ "media-source", die RTCPeerConnection.getStats() bzw. RTCRtpSender.getStats() zurückgeben. Bei diesen Einträgen ist der Wert immer "audio".

Wofür man das braucht: Im Statistikbericht haben Audio- und Videoquellen denselben type, nämlich "media-source". Erst über kind kann man sie auseinanderhalten. Ist kind === "audio", weiß man, dass das Objekt audiospezifische Felder wie audioLevel, totalAudioEnergy oder totalSamplesDuration enthält. Bei "video" (RTCVideoSourceStats) gibt es stattdessen Felder wie width, height und framesPerSecond.

Man nutzt kind typischerweise beim Durchlaufen eines RTCStatsReport, zum Beispiel für Pegelanzeigen, Überwachung der Mikrofonaktivität oder Diagnose-Dashboards.

Rückgabewert

Typ

string

Beschreibung

Immer "audio" für RTCAudioSourceStats-Objekte.

Beispiele

Audioquellen im Statistikbericht finden

const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
stream.getTracks().forEach((track) => pc.addTrack(track, stream));

const report = await pc.getStats();
report.forEach((stats) => {
  if (stats.type === 'media-source' && stats.kind === 'audio') {
    console.log(stats.id, stats.kind, stats.trackIdentifier);
  }
});

SA1 audio 3f2a9c…

Mikrofonpegel regelmäßig auslesen

const zeigePegel = async (sender) => {
  const report = await sender.getStats();
  for (const stats of report.values()) {
    if (stats.type === 'media-source' && stats.kind === 'audio') {
      // audioLevel liegt zwischen 0 und 1
      console.log(`Pegel: ${(stats.audioLevel ?? 0).toFixed(3)}`);
    }
  }
};

const [audioSender] = pc.getSenders().filter((s) => s.track?.kind === 'audio');
const timer = setInterval(() => zeigePegel(audioSender), 1000);
// später: clearInterval(timer);

Pegel: 0.042

Quellen nach Art gruppieren

const quellenNachArt = async (pc) => {
  const report = await pc.getStats();
  const gruppen = { audio: [], video: [] };
  report.forEach((s) => {
    if (s.type === 'media-source') gruppen[s.kind]?.push(s);
  });
  return gruppen;
};

const { audio } = await quellenNachArt(pc);
console.log(`${audio.length} Audioquelle(n)`);

1 Audioquelle(n)

// Wichtig · Fallstricke

Immer zuerst type === "media-source" prüfen. Andere Statistiktypen wie "inbound-rtp" und "outbound-rtp" haben ebenfalls eine Eigenschaft kind mit dem Wert "audio" oder "video". Eine Prüfung nur auf kind liefert daher auch fremde Objekte.
Der Wert kommt vom Browser und ist nur lesbar. Es handelt sich um ein Datenobjekt (Dictionary) ohne Prototyp-Getter. Eigene Zuweisungen haben keinen Einfluss auf die WebRTC-Verbindung.
Browser-Unterstützung: In Chromium-Browsern und Safari vorhanden. Firefox liefert keine "media-source"-Statistiken. Deshalb sollte man optionale Felder wie audioLevel mit ?? absichern.
media-source-Einträge gibt es nur für lokal gesendete Tracks, also nicht für empfangene Audiodaten. Für empfangenes Audio nutzt man RTCInboundRtpStreamStats.
getUserMedia() erfordert einen sicheren Kontext (HTTPS) und die Zustimmung des Nutzers.

Siehe auch

RTCAudioSourceStats.id RTCAudioSourceStats.type RTCAudioSourceStats.timestamp RTCAudioSourceStats.audioLevel RTCAudioSourceStats.trackIdentifier