new RTCPeerConnection() — Methode · JavaScript-Referenz

Signatur

new RTCPeerConnection(configuration)

Beschreibung

Der Konstruktor RTCPeerConnection() ist der Einstieg in jede WebRTC-Anwendung. Er erzeugt ein Verbindungsobjekt, das den Austausch von Audio, Video und beliebigen Daten (über RTCDataChannel) direkt zwischen zwei Peers ermöglicht – ohne dass die Nutzdaten über einen eigenen Server laufen.

Über das optionale Konfigurationsobjekt legst du vor allem die ICE-Server fest: STUN-Server ermitteln die öffentliche Adresse hinter einem NAT, TURN-Server leiten den Verkehr weiter, wenn keine direkte Verbindung möglich ist. Außerdem lassen sich Bündelungsstrategie, ICE-Transportrichtlinie und vorab erzeugte Zertifikate angeben.

Der Konstruktor stellt noch keine Verbindung her. Danach folgt der typische Ablauf: Medienspuren mit addTrack() oder Datenkanäle mit createDataChannel() hinzufügen, ein Angebot mit createOffer() erzeugen, Beschreibungen mit setLocalDescription()/setRemoteDescription() setzen und ICE-Kandidaten über das Ereignis icecandidate austauschen. Den Austausch dieser Signalisierungsdaten (SDP, Kandidaten) musst du selbst übernehmen, z. B. über WebSocket.

Parameter

Name	Typ	Default	Beschreibung
$configuration	RTCConfiguration	{}	Konfigurationsobjekt. Wichtige Felder: `iceServers` – Array von `{ urls, username?, credential? }` für STUN/TURN `iceTransportPolicy` – `"all"` (Standard) oder `"relay"` (nur TURN) `bundlePolicy` – `"balanced"`, `"max-compat"` oder `"max-bundle"` `rtcpMuxPolicy` – nur `"require"` `iceCandidatePoolSize` – Anzahl vorab gesammelter Kandidaten (Standard `0`) `certificates` – Array von `RTCCertificate` aus `RTCPeerConnection.generateCertificate()`

Rückgabewert

Typ

RTCPeerConnection

Beschreibung

Eine neue, noch nicht verbundene RTCPeerConnection mit signalingState "stable" und connectionState "new".

Beispiele

Verbindung mit STUN- und TURN-Server erzeugen

const pc = new RTCPeerConnection({
  iceServers: [
    { urls: 'stun:stun.l.google.com:19302' },
    {
      urls: 'turn:turn.example.com:3478',
      username: 'nutzer',
      credential: 'geheim'
    }
  ]
});

console.log(pc.connectionState, pc.signalingState);

new stable

Angebot erstellen und ICE-Kandidaten an den Signalisierungsserver senden

const signaling = new WebSocket('wss://signal.example.com');
const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
});

// Kamera und Mikrofon hinzufügen
const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
stream.getTracks().forEach((track) => pc.addTrack(track, stream));

// Gefundene Kandidaten an die Gegenseite weiterleiten
pc.addEventListener('icecandidate', ({ candidate }) => {
  if (candidate) signaling.send(JSON.stringify({ type: 'candidate', candidate }));
});

pc.addEventListener('connectionstatechange', () => {
  console.log('Status:', pc.connectionState);
});

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
signaling.send(JSON.stringify({ type: 'offer', sdp: pc.localDescription }));

Status: connecting Status: connected

Lokaler Datenkanal zwischen zwei Verbindungen (Test ohne Server)

const a = new RTCPeerConnection();
const b = new RTCPeerConnection();

a.onicecandidate = (e) => e.candidate && b.addIceCandidate(e.candidate);
b.onicecandidate = (e) => e.candidate && a.addIceCandidate(e.candidate);

const channel = a.createDataChannel('chat');
channel.onopen = () => channel.send('Hallo von A');

b.ondatachannel = ({ channel: incoming }) => {
  incoming.onmessage = (e) => console.log('B empfängt:', e.data);
};

await a.setLocalDescription(await a.createOffer());
await b.setRemoteDescription(a.localDescription);
await b.setLocalDescription(await b.createAnswer());
await a.setRemoteDescription(b.localDescription);

B empfängt: Hallo von A

// Wichtig · Fallstricke

Sicherer Kontext: Zugriff auf Kamera/Mikrofon (getUserMedia) funktioniert nur über HTTPS oder localhost.
Ohne TURN-Server scheitern Verbindungen hinter symmetrischen NATs oder restriktiven Firmen-Firewalls häufig. Für den Produktivbetrieb einen TURN-Server (z. B. coturn) einplanen.
TURN-Zugangsdaten sind im Client-Code sichtbar. Verwende kurzlebige, serverseitig erzeugte Zugangsdaten statt fester Passwörter.
Eine ungültige Konfiguration (z. B. fehlerhafte urls) löst sofort einen SyntaxError bzw. InvalidAccessError aus. Ein Aufruf ohne new wirft einen TypeError.
Verbindungen mit pc.close() schließen, sobald du sie nicht mehr brauchst. Sonst bleiben Netzwerk- und Medienressourcen belegt.
Präfix-Versionen wie webkitRTCPeerConnection sind veraltet. Für ältere Browser hilft die Bibliothek adapter.js.
Datenschutz: ICE-Kandidaten können lokale IP-Adressen verraten. Moderne Browser verschleiern sie per mDNS; mit iceTransportPolicy: \"relay\" lässt sich das zusätzlich erzwingen.

Siehe auch

RTCPeerConnection RTCPeerConnection.prototype.createOffer() RTCPeerConnection.prototype.setLocalDescription() RTCPeerConnection.prototype.addTrack() RTCPeerConnection.prototype.createDataChannel() MediaDevices.prototype.getUserMedia()