RTCRtpReceiver.jitterBufferTarget — Eigenschaft · JavaScript-Referenz

Signatur

RTCRtpReceiver.jitterBufferTarget

Beschreibung

Die Eigenschaft jitterBufferTarget eines RTCRtpReceiver ist ein DOMHighResTimeStamp (Millisekunden) oder null. Damit teilt eine Anwendung dem Browser mit, wie lange eingehende Audio- oder Videodaten im Jitter-Puffer liegen sollen, bevor sie wiedergegeben werden. Der Jitter-Puffer gleicht schwankende Paketlaufzeiten aus. Ein größerer Puffer macht die Wiedergabe robuster, erhöht aber die Latenz.

Sinnvoll ist die Eigenschaft, wenn die Standardwahl des Browsers, die meist auf möglichst geringe Latenz ausgelegt ist, nicht zum Anwendungsfall passt:

Höherer Wert (z. B. 500–2000 ms): für Einweg-Übertragungen wie Live-Streams, Webinare oder Überwachungskameras. Dort zählt ruckelfreie Wiedergabe mehr als Echtzeit.
Niedriger Wert (z. B. 0–50 ms): für Cloud-Gaming, Fernsteuerung oder interaktive Anwendungen, bei denen jede Millisekunde zählt.
null: Der Browser entscheidet selbst (Standardwert).

Der Wert ist nur ein Hinweis. Der Browser kann davon abweichen, etwa wegen Audio-Video-Synchronisation oder Netzbedingungen. Wie groß der Puffer tatsächlich ist, zeigen die Statistiken vom Typ inbound-rtp aus getStats(), vor allem jitterBufferTargetDelay, jitterBufferDelay und jitterBufferEmittedCount.

Parameter

Name	Typ	Default	Beschreibung
$value	number \| null	null	Beim Setzen: gewünschte Pufferdauer in Millisekunden, zulässig von `0` bis `4000`. `null` entfernt die Vorgabe.

Rückgabewert

Typ

number | null

Beschreibung

Der zuletzt gesetzte Zielwert in Millisekunden oder null, wenn die Anwendung keine Vorgabe gemacht hat. Das ist nicht die tatsächliche aktuelle Pufferverzögerung.

Beispiele

Größerer Puffer für einen ruckelfreien Live-Stream

const pc = new RTCPeerConnection();

pc.addEventListener('track', (event) => {
  const receiver = event.receiver;
  if ('jitterBufferTarget' in receiver) {
    // Lieber 1 s Verzögerung als Ruckler bei Paketlaufzeit-Schwankungen
    receiver.jitterBufferTarget = 1000;
    console.log(`${event.track.kind}: Ziel =`, receiver.jitterBufferTarget, 'ms');
  }
  document.querySelector('video').srcObject = event.streams[0];
});

video: Ziel = 1000 ms audio: Ziel = 1000 ms

Minimale Latenz für Cloud-Gaming und Zurücksetzen

const setLowLatency = (pc, enabled) => {
  for (const receiver of pc.getReceivers()) {
    if (!('jitterBufferTarget' in receiver)) continue;
    // 0 = so wenig puffern wie möglich, null = Browser entscheidet
    receiver.jitterBufferTarget = enabled ? 0 : null;
  }
};

setLowLatency(pc, true);
console.log(pc.getReceivers().map((r) => r.jitterBufferTarget));

[0, 0]

Tatsächliche Pufferverzögerung per getStats() prüfen

const logJitterBuffer = async (receiver) => {
  const stats = await receiver.getStats();
  for (const report of stats.values()) {
    if (report.type !== 'inbound-rtp') continue;
    const count = report.jitterBufferEmittedCount;
    if (!count) continue;
    const avgDelay = (report.jitterBufferDelay / count) * 1000;
    const avgTarget = (report.jitterBufferTargetDelay / count) * 1000;
    console.log(`${report.kind}: Ist ${avgDelay.toFixed(0)} ms, Ziel ${avgTarget.toFixed(0)} ms`);
  }
};

setInterval(() => pc.getReceivers().forEach(logJitterBuffer), 5000);

video: Ist 985 ms, Ziel 1000 ms

Ungültige Werte abfangen

const receiver = pc.getReceivers()[0];
try {
  receiver.jitterBufferTarget = 5000; // über dem Maximum von 4000 ms
} catch (err) {
  console.error(err.name, err.message);
}

RangeError ...

// Wichtig · Fallstricke

Wertebereich: Nur 0–4000 ms sind erlaubt. Werte außerhalb davon lösen einen RangeError aus.
Nur ein Hinweis: Der Browser muss den Wert nicht genau einhalten. Beim Auslesen bekommst du den gesetzten Zielwert zurück, nicht die aktuelle Verzögerung. Die echten Werte liefert getStats().
Audio-Video-Synchronisation: Wenn Audio- und Video-Receiver synchronisiert werden, kann ein großer Wert auf einem Track auch den anderen verzögern. Setze den Wert am besten für beide Receiver gleich.
Latenz in Gesprächen: Hohe Werte stören Echtzeit-Gespräche spürbar, weil sich Teilnehmer ins Wort fallen. Nutze sie nur für Einweg-Übertragungen.
Kompatibilität: Nicht alle Browser unterstützen die Eigenschaft, vor allem ältere Safari-Versionen nicht. Prüfe sie deshalb vorher mit 'jitterBufferTarget' in receiver. Chrome kannte früher die nicht standardisierte Eigenschaft playoutDelayHint. Sie erwartet Sekunden statt Millisekunden und sollte nicht mehr verwendet werden.

Siehe auch

RTCRtpReceiver RTCRtpReceiver.getStats() RTCPeerConnection RTCPeerConnection.getReceivers() DOMHighResTimeStamp ScriptProcessorNode.bufferSize