RTCOutboundRtpStreamStats.qualityLimitationReason — Eigenschaft · JavaScript-Referenz

Signatur

RTCOutboundRtpStreamStats.qualityLimitationReason

Beschreibung

Die schreibgeschützte Eigenschaft qualityLimitationReason des Wörterbuchs RTCOutboundRtpStreamStats (Statistik-Typ "outbound-rtp") sagt Ihnen, warum der Browser die Qualität eines gesendeten Video-Streams gerade absenkt. Gemeint ist zum Beispiel eine geringere Auflösung oder Bildrate. Den Wert lesen Sie über RTCPeerConnection.getStats() oder RTCRtpSender.getStats() aus.

Mögliche Werte:

"none": Die Qualität ist nicht eingeschränkt.
"cpu": Die Qualität ist gedrosselt, weil die CPU überlastet ist.
"bandwidth": Die Qualität ist gedrosselt, weil die geschätzte Bandbreite nicht ausreicht.
"other": Ein anderer Grund, zum Beispiel eine Einstellung der Anwendung.

Die Eigenschaft hilft beim Überwachen und Diagnostizieren von Videokonferenzen. Sie können damit Nutzer auf eine schwache Verbindung oder ein überlastetes Gerät hinweisen, Probleme protokollieren oder selbst reagieren. Mögliche Reaktionen sind, maxBitrate zu senken, Simulcast-Schichten abzuschalten oder scaleResolutionDownBy anzupassen. Zusammen mit qualityLimitationDurations und qualityLimitationResolutionChanges zeigen Sie, wie lange und wie oft gedrosselt wurde.

Rückgabewert

Typ

"none" | "cpu" | "bandwidth" | "other"

Beschreibung

Ein String, der den aktuellen Grund für die Qualitätsdrosselung angibt. Bei Audio-Streams fehlt die Eigenschaft meist, der Wert ist dann undefined.

Beispiele

Grund der Drosselung für alle ausgehenden Video-Streams auslesen

const logQualityLimitation = async (pc) => {
  const report = await pc.getStats();
  report.forEach((stats) => {
    if (stats.type === 'outbound-rtp' && stats.kind === 'video') {
      console.log(`SSRC ${stats.ssrc}: ${stats.qualityLimitationReason ?? 'unbekannt'}`);
    }
  });
};

// pc ist eine bestehende RTCPeerConnection mit Video-Track
await logQualityLimitation(pc);

SSRC 123456789: bandwidth

Nutzer regelmäßig auf Engpässe hinweisen

const hints = {
  cpu: 'Ihr Gerät ist ausgelastet – schließen Sie andere Anwendungen.',
  bandwidth: 'Ihre Verbindung ist zu langsam – die Videoqualität wird reduziert.',
  other: 'Die Videoqualität ist derzeit eingeschränkt.'
};

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

const timer = setInterval(async () => {
  const report = await sender.getStats();
  for (const stats of report.values()) {
    if (stats.type !== 'outbound-rtp') continue;
    const reason = stats.qualityLimitationReason;
    document.querySelector('#status').textContent =
      reason && reason !== 'none' ? hints[reason] : '';
  }
}, 2000);

// Beim Auflegen: clearInterval(timer);

Bei CPU-Engpass die Auflösung selbst reduzieren

const adaptOnCpuLimit = async (sender) => {
  const report = await sender.getStats();
  const outbound = [...report.values()].find((s) => s.type === 'outbound-rtp');
  if (outbound?.qualityLimitationReason !== 'cpu') return;

  const params = sender.getParameters();
  params.encodings.forEach((enc) => {
    enc.scaleResolutionDownBy = Math.min((enc.scaleResolutionDownBy ?? 1) * 2, 8);
  });
  await sender.setParameters(params);
  console.log('Auflösung wegen CPU-Last halbiert');
};

Auflösung wegen CPU-Last halbiert

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser und Safari unterstützen die Eigenschaft. Firefox liefert sie derzeit nicht. Prüfen Sie den Wert deshalb immer auf undefined, zum Beispiel mit ?? 'unbekannt'.
Die Eigenschaft ist nur für Video aussagekräftig. Bei Audio-Streams fehlt sie normalerweise.
Der Wert beschreibt nur den aktuellen Zustand und kann schnell wechseln. Für stabile Aussagen fragen Sie mehrmals ab oder werten zusätzlich qualityLimitationDurations aus. Reagieren Sie nicht bei jeder einzelnen Abfrage, sonst schwankt die Qualität ständig hin und her.
Bei Simulcast gibt es pro Schicht (rid) einen eigenen outbound-rtp-Eintrag mit jeweils eigenem Grund.
getStats() ist nicht kostenlos. Häufiges Abfragen (unter einer Sekunde) kostet unnötig CPU und kann einen "cpu"-Engpass sogar verschärfen.
Die Werte selbst wurden in der Spezifikation nie als veraltet markiert. In älteren Chrome-Versionen standen sie aber im inzwischen entfernten track-Statistikeintrag statt in outbound-rtp.

Siehe auch

RTCOutboundRtpStreamStats RTCOutboundRtpStreamStats.qualityLimitationDurations RTCPeerConnection.prototype.getStats() RTCRtpSender.prototype.getStats() RTCRtpSender.prototype.setParameters()