Skip to main content

Getting Started

PeerJS simplifies peer-to-peer data, video, and audio calls.

This guide will show you the basic concepts of the PeerJS API.

Setup​

1. Include the JavaScript client​

Add the PeerJS client library to your webpage.

npm install --save peerjs

2. Create the Peer object​

The Peer object is where we create and receive connections.

var peer = new Peer();

PeerJS uses PeerServer for session metadata and candidate signaling. You can also run your own PeerServer if you don't like the cloud.

We're now ready to start making connections!

Usage​

Every Peer object is assigned a random, unique ID when it's created.

peer.on("open", function (id) {
  console.log("My peer ID is: " + id);
});

When we want to connect to another peer, we'll need to know their peer ID. You're in charge of communicating the peer IDs between users of your site. Optionally, you can pass in your own IDs to the Peer constructor.

Read the Peer API reference for complete information on its options, methods, events, and error handling.

Data connections​

Start a data connection by calling peer.connect with the peer ID of the destination peer. Anytime another peer attempts to connect to your peer ID, you'll receive a connection event.

Start connection

var conn = peer.connect("dest-peer-id");

Receive connection

peer.on('connection', function(conn) { ... });

peer.connect and the callback of the connection event will both provide a DataConnection object. This object will allow you to send and receive data:

conn.on("open", function () {
  // Receive messages
  conn.on("data", function (data) {
    console.log("Received", data);
  });

  // Send messages
  conn.send("Hello!");
});

Read the DataConnection API reference for complete details on its methods and events.

Video/audio calls​

Call another peer by calling peer.call with the peer ID of the destination peer. When a peer calls you, the call event is emitted.

Unlike data connections, when receiving a call event, the call must be answered or no connection is established.

Start call

// Call a peer, providing our mediaStream
var call = peer.call("dest-peer-id", mediaStream);

Answer call

peer.on("call", function (call) {
  // Answer the call, providing our mediaStream
  call.answer(mediaStream);
});

When calling or answering a call, a MediaStream should be provided. The MediaStream represents the local video (webcam) or audio stream and can be obtained with some (browser-specific) version of navigator.getUserMedia. When answering a call, the MediaStream is optional and if none is provided then a one-way call is established. Once the call is established, its open property is set to true.

peer.call and the callback of the call event provide a MediaConnection object. The MediaConnection object itself emits a stream event whose callback includes the video/audio stream of the other peer.

call.on("stream", function (stream) {
  // `stream` is the MediaStream of the remote peer.
  // Here you'd add it to an HTML video/canvas element.
});

Read the MediaConnection API reference for complete details on its methods and events.