RTCRtpReceiver — Schnittstelle · JavaScript-Referenz

Signatur

interface RTCRtpReceiver

Beschreibung

RTCRtpReceiver ist die Empfangsseite eines RTCRtpTransceiver. Jede eingehende Audio- oder Videospur einer RTCPeerConnection hat genau einen Empfänger. Er nimmt die RTP-Pakete vom Netzwerk entgegen, dekodiert sie und stellt das Ergebnis als MediaStreamTrack (Eigenschaft track) bereit.

Einen Konstruktor gibt es nicht. Instanzen erhältst du über RTCPeerConnection.getReceivers(), über RTCRtpTransceiver.receiver oder über die Eigenschaft receiver des track-Events (RTCTrackEvent).

Wichtige Mitglieder:

Eigenschaften: track (die empfangene Spur), transport (der zugehörige RTCDtlsTransport oder null), transform (für Encoded Transforms, z. B. Ende-zu-Ende-Verschlüsselung), jitterBufferTarget (gewünschte Pufferverzögerung in Millisekunden).
Methoden: getParameters() (aktuell ausgehandelte Codecs und Header-Erweiterungen), getStats() (Statistiken, nur für diesen Empfänger), getSynchronizationSources() und getContributingSources() (SSRC/CSRC mit Pegel und Zeitstempel, z. B. für Sprecheranzeigen).
Statische Methode: RTCRtpReceiver.getCapabilities(kind) gibt an, welche Codecs und Header-Erweiterungen der Browser empfangen kann.

Typische Anwendungsfälle sind das Anzeigen entfernter Streams, die Qualitätsüberwachung (Paketverlust, Jitter, Bitrate), Sprecheranzeigen über Audiopegel und die Codec-Auswahl zusammen mit RTCRtpTransceiver.setCodecPreferences().

Parameter

Name	Typ	Default	Beschreibung
$kind Pflicht	"audio" \| "video"		Nur für die statische Methode `RTCRtpReceiver.getCapabilities(kind)`: Die Medienart, deren Empfangsfähigkeiten abgefragt werden.
$jitterBufferTarget	number \| null	null	Beschreibbare Eigenschaft: gewünschte Zielverzögerung des Jitter-Puffers in Millisekunden (0–4000). Bei `null` entscheidet der Browser selbst.
$transform	RTCRtpScriptTransform \| null	null	Beschreibbare Eigenschaft: Transform, der die kodierten Frames vor dem Dekodieren bearbeitet, z. B. für Ende-zu-Ende-Verschlüsselung in einem Worker.

Rückgabewert

Typ

RTCRtpReceiver

Beschreibung

Eine vom Browser erzeugte Instanz, die du über getReceivers(), transceiver.receiver oder event.receiver erhältst. getStats() gibt Promise<RTCStatsReport> zurück, getCapabilities() gibt RTCRtpCapabilities | null zurück.

Beispiele

Empfänger im track-Event abgreifen und Video anzeigen

const pc = new RTCPeerConnection();
const remoteVideo = document.querySelector('#remote');

pc.addEventListener('track', (event) => {
  const { receiver, streams } = event;
  console.log('Neuer Empfänger:', receiver.track.kind, receiver.track.id);
  // Stream an das Video-Element hängen
  if (remoteVideo.srcObject !== streams[0]) {
    remoteVideo.srcObject = streams[0];
  }
});

// Später: alle Empfänger auflisten
const kinds = pc.getReceivers().map((r) => r.track.kind);
console.log(kinds);

Neuer Empfänger: video 3f2c… ["audio", "video"]

Empfangsqualität mit getStats() überwachen

const logInboundStats = async (receiver) => {
  const report = await receiver.getStats();
  report.forEach((stat) => {
    if (stat.type === 'inbound-rtp') {
      console.log(
        `${stat.kind}: ${stat.packetsReceived} Pakete, ` +
        `${stat.packetsLost} verloren, Jitter ${stat.jitter?.toFixed(3)} s`
      );
    }
  });
};

const videoReceiver = pc.getReceivers().find((r) => r.track.kind === 'video');
setInterval(() => logInboundStats(videoReceiver), 2000);

video: 18342 Pakete, 12 verloren, Jitter 0.004 s

Unterstützte Empfangs-Codecs abfragen und bevorzugen

const caps = RTCRtpReceiver.getCapabilities('video');
console.log(caps.codecs.map((c) => c.mimeType));

// VP9 bevorzugen, übrige Codecs als Rückfall behalten
const transceiver = pc.addTransceiver('video', { direction: 'recvonly' });
const sorted = [
  ...caps.codecs.filter((c) => c.mimeType === 'video/VP9'),
  ...caps.codecs.filter((c) => c.mimeType !== 'video/VP9'),
];
transceiver.setCodecPreferences(sorted);

["video/VP8", "video/rtx", "video/VP9", "video/H264", "video/AV1", …]

Sprecheranzeige über Audiopegel und geringere Latenz

const audioReceiver = pc.getReceivers().find((r) => r.track.kind === 'audio');

// Niedrige Latenz anfordern (sofern unterstützt)
if ('jitterBufferTarget' in audioReceiver) {
  audioReceiver.jitterBufferTarget = 50;
}

setInterval(() => {
  const [source] = audioReceiver.getSynchronizationSources();
  if (source) {
    const speaking = (source.audioLevel ?? 0) > 0.05;
    console.log(`SSRC ${source.source}: Pegel ${source.audioLevel?.toFixed(2)}, spricht: ${speaking}`);
  }
}, 250);

SSRC 123456789: Pegel 0.21, spricht: true

// Wichtig · Fallstricke

Kein Konstruktor: new RTCRtpReceiver() wirft einen TypeError. Empfänger entstehen nur durch Aushandlung (setRemoteDescription) oder addTransceiver().
track ist sofort vorhanden: Die Spur existiert schon vor dem Eintreffen von Daten. Sie bleibt stumm (muted), bis Pakete ankommen. Bei Bedarf auf das unmute-Event der Spur hören.
transport ist null, solange die Aushandlung nicht abgeschlossen ist. Bei BUNDLE teilen sich mehrere Empfänger denselben Transport.
getSynchronizationSources() liefert nur Quellen der letzten ca. 10 Sekunden; audioLevel gibt es nur bei Audio und nur, wenn die Header-Erweiterung ausgehandelt wurde.
getCapabilities() gibt bei unbekanntem kind null zurück. Die Liste enthält auch Hilfscodecs wie rtx, red und ulpfec.
Kompatibilität: transform (RTCRtpScriptTransform) unterstützen Firefox und Safari; Chrome bietet stattdessen das nicht standardisierte createEncodedStreams() an. jitterBufferTarget gibt es noch nicht in allen Browsern, daher vorher per Feature-Erkennung prüfen. Die Methode getStats() am Empfänger fehlte in älteren Safari-Versionen.
WebRTC gibt es nur in sicheren Kontexten (HTTPS oder localhost).

Siehe auch

RTCRtpTransceiver RTCRtpSender RTCDTMFSender RTCTrackEvent RTCErrorEvent FragmentDirective