RTCIceCandidatePair.remote — Eigenschaft · JavaScript-Referenz

Signatur

RTCIceCandidatePair.remote

Beschreibung

Ein RTCIceCandidatePair beschreibt ein Paar aus einem lokalen und einem entfernten ICE-Kandidaten, über das eine WebRTC-Verbindung tatsächlich Daten austauscht. Die Eigenschaft remote enthält dabei den entfernten Kandidaten als RTCIceCandidate-Objekt. Das Gegenstück ist RTCIceCandidatePair.local.

Ein solches Paar bekommen Sie nicht über einen Konstruktor, sondern über RTCIceTransport.getSelectedCandidatePair(). Den RTCIceTransport erreichen Sie über RTCRtpSender.transport.iceTransport bzw. RTCRtpReceiver.transport.iceTransport oder, bei Datenkanälen, über RTCPeerConnection.sctp.transport.iceTransport.

In der Praxis nutzen Sie remote für Diagnose und Überwachung: Sie können z. B. prüfen, ob die Gegenseite direkt (type === "host" oder "srflx") oder über einen TURN-Server ("relay") erreicht wird, welches Protokoll (udp/tcp) verwendet wird und welche Adresse und welcher Port im Spiel sind. Das hilft beim Debuggen von NAT- und Firewall-Problemen und beim Abschätzen der Verbindungsqualität.

Weil ICE das gewählte Paar während einer laufenden Sitzung wechseln kann (z. B. bei Netzwechsel oder ICE-Neustart), sollten Sie das Ereignis selectedcandidatepairchange am RTCIceTransport beobachten, statt den Wert nur einmal auszulesen.

Rückgabewert

Typ

RTCIceCandidate

Beschreibung

Ein RTCIceCandidate, der den entfernten Endpunkt des Paares beschreibt – mit Eigenschaften wie address, port, protocol, type, priority und candidate. Nur lesbar.

Beispiele

Remote-Kandidaten des gewählten Paares auslesen

// pc ist eine verbundene RTCPeerConnection mit mindestens einem Sender
const logRemoteCandidate = (pc) => {
  const sender = pc.getSenders().find((s) => s.transport);
  const iceTransport = sender?.transport?.iceTransport;
  const pair = iceTransport?.getSelectedCandidatePair?.();

  if (!pair) {
    console.log('Noch kein Kandidatenpaar gewählt oder API nicht unterstützt');
    return;
  }

  const { address, port, protocol, type } = pair.remote;
  console.log(`Gegenstelle: ${address}:${port} über ${protocol} (${type})`);
};

pc.addEventListener('connectionstatechange', () => {
  if (pc.connectionState === 'connected') logRemoteCandidate(pc);
});

Gegenstelle: 203.0.113.42:54321 über udp (srflx)

Wechsel des Kandidatenpaares überwachen und TURN-Nutzung erkennen

const watchCandidatePair = (pc) => {
  const iceTransport = pc.sctp?.transport?.iceTransport
    ?? pc.getSenders()[0]?.transport?.iceTransport;
  if (!iceTransport) return;

  iceTransport.addEventListener('selectedcandidatepairchange', () => {
    const pair = iceTransport.getSelectedCandidatePair();
    const viaRelay = pair.local.type === 'relay' || pair.remote.type === 'relay';
    console.log('Neues Paar:', pair.local.address, '->', pair.remote.address);
    console.log(viaRelay ? 'Verbindung läuft über TURN' : 'Direkte Verbindung');
  });
};

watchCandidatePair(pc);

Neues Paar: 192.168.0.10 -> 198.51.100.7 Direkte Verbindung

Browserübergreifender Fallback über getStats()

// Funktioniert auch dort, wo getSelectedCandidatePair() fehlt (z. B. Firefox)
const getRemoteCandidateInfo = async (pc) => {
  const stats = await pc.getStats();
  let pair;
  stats.forEach((report) => {
    if (report.type === 'transport' && report.selectedCandidatePairId) {
      pair = stats.get(report.selectedCandidatePairId);
    }
  });
  // Fallback: nominiertes, erfolgreiches Paar suchen
  if (!pair) {
    stats.forEach((r) => {
      if (r.type === 'candidate-pair' && r.nominated && r.state === 'succeeded') pair = r;
    });
  }
  const remote = pair && stats.get(pair.remoteCandidateId);
  return remote ? { address: remote.address, port: remote.port, type: remote.candidateType } : null;
};

console.log(await getRemoteCandidateInfo(pc));

{ address: '198.51.100.7', port: 3478, type: 'relay' }

// Wichtig · Fallstricke

Browser-Kompatibilität: RTCIceTransport.getSelectedCandidatePair() – und damit der Zugriff auf RTCIceCandidatePair – wird von Chromium-Browsern und Safari unterstützt, von Firefox aber nicht zuverlässig. Prüfen Sie vorher, ob die Methode vorhanden ist, und greifen Sie sonst auf RTCPeerConnection.getStats() (Berichte vom Typ candidate-pair und remote-candidate) zurück.
Vor dem Verbindungsaufbau gibt getSelectedCandidatePair() null zurück – greifen Sie also erst ab iceConnectionState "connected" bzw. "completed" auf remote zu.
Das Objekt ist eine Momentaufnahme: Nach einem ICE-Neustart oder Netzwechsel kann ein anderes Paar gewählt werden. Beobachten Sie dafür selectedcandidatepairchange.
Datenschutz: remote.address kann die echte IP-Adresse der Gegenstelle enthalten. Protokollieren oder übertragen Sie diese Daten nicht ohne Grund; lokale Host-Kandidaten werden von Browsern oft durch mDNS-Namen (*.local) verschleiert, sodass address auch ein Hostname oder leer sein kann.
Die Eigenschaft ist nur lesbar; Zuweisungen haben keine Wirkung.

Siehe auch

RTCIceCandidatePair RTCIceCandidatePair.local RTCIceTransport.getSelectedCandidatePair() RTCIceCandidate RTCPeerConnection.getStats() QuotaExceededError.requested