RTCPeerConnection.getSenders() — Methode · JavaScript-Referenz

Signatur

RTCPeerConnection.prototype.getSenders()

Beschreibung

getSenders() liefert eine Momentaufnahme aller RTCRtpSender-Objekte, die zur RTCPeerConnection gehören. Ein Sender entsteht, wenn Sie mit addTrack() einen Track hinzufügen oder mit addTransceiver() einen Transceiver anlegen. Über den Sender steuern Sie, was und wie an die Gegenseite gesendet wird.

Typische Anwendungsfälle:

Tracks ersetzen ohne Neuverhandlung: Mit sender.replaceTrack() wechseln Sie z. B. von der Kamera zur Bildschirmfreigabe.
Stummschalten bzw. Kamera aus: Sie suchen den Sender und setzen sender.track.enabled = false.
Bitrate und Encoding anpassen: Mit getParameters()/setParameters() ändern Sie z. B. maxBitrate oder scaleResolutionDownBy.
Statistiken: sender.getStats() liefert Sendestatistiken wie gesendete Bytes und Paketverluste.
Tracks entfernen: pc.removeTrack(sender) braucht das Sender-Objekt, nicht den Track.

Das zurückgegebene Array ist eine Kopie. Später hinzugefügte oder entfernte Sender tauchen darin nicht auf, deshalb rufen Sie die Methode bei Bedarf erneut auf. Zurückgegeben werden die Sender aller Transceiver, die nicht gestoppt sind. Ein Sender kann auch track === null haben, etwa nach removeTrack() oder bei einem Transceiver ohne Track.

Rückgabewert

Typ

RTCRtpSender[]

Beschreibung

Ein neues Array mit einem RTCRtpSender pro nicht gestopptem Transceiver der Verbindung. Gibt es keine Sender, ist das Array leer.

Beispiele

Alle Sender und ihre Tracks auflisten

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

for (const sender of pc.getSenders()) {
  console.log(sender.track?.kind, sender.track?.label);
}

audio Standard – Mikrofon video FaceTime HD Camera

Kamera durch Bildschirmfreigabe ersetzen (ohne Neuverhandlung)

const startScreenShare = async (pc) => {
  const screen = await navigator.mediaDevices.getDisplayMedia({ video: true });
  const [screenTrack] = screen.getVideoTracks();

  const videoSender = pc.getSenders().find((s) => s.track?.kind === 'video');
  if (!videoSender) throw new Error('Kein Video-Sender vorhanden');

  const cameraTrack = videoSender.track;
  await videoSender.replaceTrack(screenTrack);

  // Beim Beenden der Freigabe zurück zur Kamera wechseln
  screenTrack.addEventListener('ended', () => videoSender.replaceTrack(cameraTrack));
};

Mikrofon stummschalten und Video-Bitrate begrenzen

const toggleMute = (pc, muted) => {
  pc.getSenders()
    .filter((s) => s.track?.kind === 'audio')
    .forEach((s) => { s.track.enabled = !muted; });
};

const limitVideoBitrate = async (pc, maxBitrate) => {
  const sender = pc.getSenders().find((s) => s.track?.kind === 'video');
  if (!sender) return;
  const params = sender.getParameters();
  if (!params.encodings.length) params.encodings = [{}];
  params.encodings[0].maxBitrate = maxBitrate; // in Bit/s
  await sender.setParameters(params);
  console.log('Neue maxBitrate:', sender.getParameters().encodings[0].maxBitrate);
};

toggleMute(pc, true);
await limitVideoBitrate(pc, 500_000);

Neue maxBitrate: 500000

Alle Tracks entfernen und Verbindung aufräumen

const hangUp = (pc) => {
  pc.getSenders().forEach((sender) => {
    sender.track?.stop();   // Kamera/Mikrofon freigeben
    pc.removeTrack(sender); // Sender vom Track lösen
  });
  pc.close();
  console.log('Verbleibende Sender:', pc.getSenders().length);
};

Verbleibende Sender: 0

// Wichtig · Fallstricke

Momentaufnahme: Das Array aktualisiert sich nicht von selbst. Rufen Sie getSenders() nach addTrack(), removeTrack() oder einer Neuverhandlung erneut auf.
track kann null sein: Nach removeTrack() bleibt der Sender bestehen, sein track ist dann aber null. Nutzen Sie deshalb optionale Verkettung wie sender.track?.kind.
Nach close(): Die Transceiver einer geschlossenen Verbindung gelten als gestoppt, deshalb liefert getSenders() dann ein leeres Array.
replaceTrack() vs. removeTrack()/addTrack(): replaceTrack() braucht keine SDP-Neuverhandlung. Der neue Track muss aber von derselben Art sein (audio/video).
setParameters(): Übergeben Sie immer das Objekt, das Sie direkt vorher mit getParameters() geholt haben. Sonst wird die Promise wegen einer veralteten transactionId mit InvalidModificationError abgelehnt.
Kompatibilität: Unterstützt in Chrome, Edge, Firefox und Safari (ab 11). Ältere, veraltete APIs wie getLocalStreams() sollten Sie nicht mehr verwenden.
Datenschutz: track.label kann Gerätenamen enthalten. Geben Sie ihn nicht ungefiltert an Dritte weiter.

Siehe auch

RTCPeerConnection RTCRtpSender RTCPeerConnection.getReceivers() RTCPeerConnection.getTransceivers() RTCPeerConnection.addTrack() RTCPeerConnection.removeTrack() RTCRtpSender.replaceTrack() RTCRtpSender.setParameters()