RTCPeerConnection : EventTarget

constructor

Enables Real Time Communication of audio, video, and data to another browser/computer using the WebRTC peer to peer protocol.

Although WebRTC is a peer to peer protocol, the peers need some information about each other before they can communicate. Typically this is done with a Signaling Server, but any mechanism to transfer data can be used. The following demonstrates setting up the peer connection using the clipboard (via copy/paste) to transfer the connection data.

Offerer

This example demonstrates the peer that creates the offer.

Example:

<button id="copy" disabled>Copy Offer/Candidates to Clipboard</button><br>
<input id="paste" placeholder="Paste Answer/Candidates here" disabled>
<table>
<tr><td>local</td><td>remote</td></tr>
<tr>
  <td><video id="local" autoplay></video></td>
  <td><video id="remote" autoplay></video></td>
</tr>
</table>

<script>
  // Use an offscreen canvas as the video source.
  const canvas = document.createElement('canvas');
  const context = canvas.getContext('2d');
  let color = 0;
  const draw = () => {
    color = (color + 2) % 255;
    context.fillStyle = `rgb(${color}, 0, 0)`;
    context.fillRect(0, 0, 300, 150);
    requestAnimationFrame(draw);
  }
  draw();

  const localVideo = document.getElementById('local');
  const stream = canvas.captureStream();
  localVideo.srcObject = stream;

  const peerConnection = new RTCPeerConnection({ iceServers: [ { urls: 'stun:stun.l.google.com:19302' } ] });

  stream.getTracks().forEach(t => peerConnection.addTrack(t, stream));

  // Save a list of ice candidates to send to the peer
  const iceCandidates = [];
  peerConnection.onicecandidate = e => {
    if (e.candidate) {
      iceCandidates.push(e.candidate);
    }
  };

  peerConnection.ontrack = e => { 
    document.getElementById('remote').srcObject = e.streams[0];
  };

  (async () => {
    const copyButton = document.getElementById('copy');

    peerConnection.onicegatheringstatechange = () => {
      if (peerConnection.iceGatheringState === 'complete') {
        copyButton.disabled = false;
        console.log('Offer ready, click copy button.');
      }
    };

    const offer = await peerConnection.createOffer();
    await peerConnection.setLocalDescription(offer);

    const pasteInput = document.getElementById('paste');

    copyButton.onclick = () => {
      navigator.clipboard.writeText(JSON.stringify({ offer, iceCandidates }));
      console.log('Offer copied/candidates. Paste in Answerer example.');

      pasteInput.disabled = false;
    };

    pasteInput.onpaste = async (e) => {
      const { answer, iceCandidates } = JSON.parse(e.clipboardData.getData('text/plain'));
      await peerConnection.setRemoteDescription(answer);
      iceCandidates.forEach(c => peerConnection.addIceCandidate(c));
    };
  })();
</script>

<style>
  video {
    width: 150px;
    height: 100px;
  }
  input {
    width: 250px;
  }
</style>

Run

Results:

Answerer

This example demonstrates the peer that receives the offer and creates the answer.

Example:

<input id="paste" placeholder="Paste Offer/Candidates here"><br>
<button id="copy" disabled>Copy Answer/Candidates to Clipboard</button><br>
<table>
<tr><td>local</td><td>remote</td></tr>
<tr>
  <td><video id="local" autoplay></video></td>
  <td><video id="remote" autoplay></video></td>
</tr>
</table>

<script>
  // Use an offscreen canvas as the video source.
  const canvas = document.createElement('canvas');
  const context = canvas.getContext('2d');
  let color = 0;
  const draw = () => {
    color = (color - 2 + 255) % 255;
    context.fillStyle = `rgb(0, 0, ${color})`;
    context.fillRect(0, 0, 300, 150);
    requestAnimationFrame(draw);
  }
  draw();

  const localVideo = document.getElementById('local');
  const stream = canvas.captureStream();
  localVideo.srcObject = stream;

  const peerConnection = new RTCPeerConnection({ iceServers: [ { urls: 'stun:stun.l.google.com:19302' } ] });

  stream.getTracks().forEach(t => peerConnection.addTrack(t, stream));

  // Save a list of ice candidates to send to the peer
  const iceCandidates = [];
  peerConnection.onicecandidate = e => {
    if (e.candidate) {
      iceCandidates.push(e.candidate);
    }
  };

  peerConnection.ontrack = e => { 
    document.getElementById('remote').srcObject = e.streams[0];
  };

  const copyButton = document.getElementById('copy');
   
  document.getElementById('paste').onpaste = async (e) => {
    const { offer, iceCandidates } = JSON.parse(e.clipboardData.getData('text/plain'));

    peerConnection.onicegatheringstatechange = () => {
      if (peerConnection.iceGatheringState === 'complete') {
        copyButton.disabled = false;
        console.log('Answer ready, click copy button.');
      }
    };

    await peerConnection.setRemoteDescription(offer);
    const answer = await peerConnection.createAnswer();
    await peerConnection.setLocalDescription(answer);

    copyButton.onclick = () => {
      navigator.clipboard.writeText(JSON.stringify({ answer, iceCandidates }));
      console.log('Copied answer/candidates. Paste in Offerer example.');
    };

    iceCandidates.forEach(c => peerConnection.addIceCandidate(c));
  };
</script>

<style>
  video {
    width: 150px;
    height: 100px;
  }
  input {
    width: 250px;
  }
</style>

Run

Results:

Spec

Constructors

new RTCPeerConnection([configuration : Object]) : RTCPeerConnection

configuration : {

iceServers :	Iterable
iceTransportPolicy :	String	Either `'relay'` or `'all'`.
bundlePolicy :	String	One of `'balanced'`, `'max-compat'`, or `'max-bundle'`.
rtcpMuxPolicy :	String	Must be `'require'`
certificates :	Iterable<RTCCertificate>
iceCandidatePoolSize :	Number

}

The elements of the iceServers property in the configuration argument should be of type: { url : (String or Iterable<String>), username : String, credential : String, credentialType : String }

Instance Properties

canTrickleIceCandidates : Boolean readonly

Returns true if the remote peer accepts trickled ice candidates. Only valid after calling setRemoteDescription().

connectionState : String readonly

One of 'closed', 'failed', 'disconnected', 'new', 'connecting', or 'connected'.

currentLocalDescription : RTCSessionDescription readonly

currentRemoteDescription : RTCSessionDescription readonly

iceConnectionState : String readonly

One of 'closed', 'failed', 'disconnected', 'new', 'checking', 'completed', or 'connected'.

iceGatheringState : String readonly

One of 'new', 'gathering', or 'complete'.

localDescription : RTCSessionDescription readonly

pendingLocalDescription : RTCSessionDescription readonly

pendingRemoteDescription : RTCSessionDescription readonly

remoteDescription : RTCSessionDescription readonly

sctp : RTCSctpTransport readonly

signalingState : String readonly

One of 'stable', 'have-local-offer', 'have-remote-offer', 'have-local-pranswer', 'have-remote-pranswer', or 'closed'

Instance Methods

addIceCandidate([candidate : Object]) : Promise<undefined>

candidate : {

candidate :	String
sdpMid :	String
sdpMLineIndex :	Number
usernameFragment :	String

}

addTrack(track : MediaStreamTrack, [stream1 : MediaStream, [stream2 : MediaStream, [...]]]) : RTCRtpSender

addTransceiver(kind : String, configuration : Object) : RTCRtpTransceiver

configuration : {

direction :	String	One of `'sendrecv'`, `'sendonly'`, `'recvonly'`, `'inactive'`, or `'stopped'`. Defaults to `'sendrecv'`.
streams :	Iterable<MediaStream>
sendEncodings :	Iterable

}

The elements of the sendEncodings property in the configuration argument should be of type: { rid : String, active : Boolean /* Default = true */, maxBitrate : Number, scalingResolutionDownBy : Number }

close() : undefined

createAnswer([options : Object]) : Promise<RTCSessionDescriptionInit>

options : {

}

createDataChannel(label : String, [options : Object]) : RTCDataChannel

options : {