RTCOutboundRtpStreamStats.active — Eigenschaft · JavaScript-Referenz

Signatur

RTCOutboundRtpStreamStats.active

Beschreibung

Die Eigenschaft active gehört zum Statistik-Wörterbuch RTCOutboundRtpStreamStats. Dieses Objekt liefert RTCPeerConnection.getStats() bzw. RTCRtpSender.getStats() für jeden Eintrag mit type === "outbound-rtp". Der Wert zeigt, ob der zugehörige RTP-Stream laut Konfiguration senden soll.

Der Wert spiegelt das Feld active der passenden Kodierung in RTCRtpSender.getParameters().encodings wider. Setzt man eine Kodierung mit RTCRtpSender.setParameters() auf active: false, meldet die Statistik danach active: false. Das ist vor allem bei Simulcast praktisch: Jede Simulcast-Schicht (erkennbar an rid) erscheint als eigener outbound-rtp-Eintrag, und über active sieht man, welche Schichten gerade eingeschaltet sind.

active beschreibt nur die Konfiguration, nicht, ob tatsächlich Pakete fließen. Ein Stream kann aktiv sein und trotzdem nichts senden, etwa wenn die Bandbreitenschätzung eine Schicht abschaltet, der Track stummgeschaltet ist oder noch keine Verbindung besteht. Ob wirklich gesendet wird, zeigen erst die Veränderungen von packetsSent oder bytesSent zwischen zwei Messungen.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der RTP-Stream zum Senden konfiguriert ist, false, wenn er deaktiviert wurde (z. B. über encodings[i].active = false). Die Eigenschaft ist schreibgeschützt und kann in Browsern ohne Unterstützung fehlen (undefined).

Beispiele

Aktivitätsstatus aller ausgehenden Streams auslesen

// pc ist eine bestehende RTCPeerConnection
const logOutboundActive = async (pc) => {
  const report = await pc.getStats();
  report.forEach((stats) => {
    if (stats.type !== "outbound-rtp") return;
    console.log(
      `${stats.kind} ssrc=${stats.ssrc} rid=${stats.rid ?? "-"} active=${stats.active}`
    );
  });
};

await logOutboundActive(pc);

video ssrc=1234567 rid=q active=true video ssrc=2345678 rid=h active=true video ssrc=3456789 rid=f active=false audio ssrc=4567890 rid=- active=true

Simulcast-Schicht abschalten und in den Statistiken prüfen

const sender = pc.getSenders().find((s) => s.track?.kind === "video");

// Höchste Schicht (rid "f") deaktivieren, z. B. um Bandbreite zu sparen
const params = sender.getParameters();
params.encodings = params.encodings.map((enc) =>
  enc.rid === "f" ? { ...enc, active: false } : enc
);
await sender.setParameters(params);

// Kontrolle über die Statistik des Senders
const report = await sender.getStats();
for (const stats of report.values()) {
  if (stats.type === "outbound-rtp") {
    console.log(stats.rid, stats.active);
  }
}

q true h true f false

Konfiguration mit tatsächlichem Sendefluss vergleichen

// Erkennt Streams, die aktiv sein sollen, aber keine Pakete senden
const previous = new Map();

const checkStalledStreams = async (pc) => {
  const report = await pc.getStats();
  report.forEach((stats) => {
    if (stats.type !== "outbound-rtp") return;
    const last = previous.get(stats.id) ?? 0;
    const delta = stats.packetsSent - last;
    previous.set(stats.id, stats.packetsSent);

    if (stats.active === true && delta === 0) {
      console.warn(`Stream ${stats.rid ?? stats.ssrc} ist aktiv, sendet aber nicht`);
    }
  });
};

setInterval(() => checkStalledStreams(pc), 2000);

Stream f ist aktiv, sendet aber nicht

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Eigenschaft ist relativ neu und bisher vor allem in Chromium-basierten Browsern verfügbar. In anderen Browsern kann sie fehlen, dann ist der Wert undefined. Prüfe deshalb mit typeof stats.active === "boolean" und greife sonst auf sender.getParameters().encodings[i].active zurück.
Konfiguration statt tatsächlicher Sendung: active: true heißt nicht, dass Daten fließen. Die Bandbreitenanpassung kann Simulcast-Schichten selbstständig pausieren; der Grund steht dann eventuell in qualityLimitationReason. Ob wirklich gesendet wird, zeigen nur packetsSent bzw. bytesSent im Zeitverlauf.
Verzögerung: Nach setParameters() kann es einen Moment dauern, bis getStats() den neuen Wert meldet. Statistiken sind Momentaufnahmen und werden nicht live aktualisiert.
Deaktivierte Streams bleiben im Statistikbericht, ihre Zähler steigen aber nicht mehr. Filtere sie bei Bitraten-Berechnungen gezielt heraus.
Das Statistik-Objekt ist eine Kopie. Wer active darauf ändert, beeinflusst den Stream nicht. Ändern lässt sich der Zustand nur über RTCRtpSender.setParameters().

Siehe auch

RTCOutboundRtpStreamStats RTCPeerConnection.getStats() RTCRtpSender.getStats() RTCRtpSender.setParameters() RTCRtpSender.getParameters() RTCOutboundRtpStreamStats.rid RTCOutboundRtpStreamStats.qualityLimitationReason