peerjs/docs/api.md

PeerJS API Reference

Due to browsers' incomplete support of the WebRTC DataChannel specification, many features of PeerJS have caveats. View the status page for full details.

Class: peerjs.Peer

This class is a Peer, which can connect to other peers and listen for connections. It is an EventEmitter.

new Peer([id], [options])

• id String. The id by which this peer will be identified when other peers try to connect to it. If no id is given, one will be generated by the server
• options Object
  • key String. API key for cloud PeerServer. Is not used for servers other than cloud.peerjs.com
  • host String. Server host. Default cloud.peerjs.com. Also accepts '/' for relative hostname.
  • port Number. Server port. Default 80
  • config Object. Configuration hash passed to RTCPeerConnection. This hash contains the ICE servers. Default { 'iceServers': [{ 'url': 'stun:stun.l.google.com:19302' }] }
  • debug Boolean. Prints verbose log messages. Default false

Construct a new Peer object.

The Peer object is used to connect to other Peer clients and also to receive connections from other clients.

The first argument is the id that other peers will use to connect to this peer, thus it must be unique for the given key (if you're using PeerServer cloud) or server.

In the options, either a PeerServer Cloud key must be provided or host and port for your own PeerServer. Note that the server is only for brokering connections and does not proxy data between peers.

The config object is passed straight into instances of RTCPeerConnection. For compatibility with symmetric NATs, you can provide your own TURN server. By default the STUN server provided by Google is used.

peer.id

The given id of this peer.

If no id was specified in the constructor, this value will be undefined util the open event fires.

peer.connections

A hash of all current connections with the current peer. Keys are ids and values are instances of DataConnection.

peer.connect(id, [options])

Connects to the remote peer specified by id.

Returns a DataConnection object.

• id String. The id of the remote peer to connect to.
• options Object.
  • metadata Optional metadata to pass to the remote peer. Can be any serializable type.
  • serialization String, which can be binary, binary-utf8, json, or none. This will be the serialization format of all data sent over the P2P DataConnection. Defaults to binary.
  • reliable Boolean, which if true activates experimental reliable transfer (while waiting for actual reliable transfer to be implemented in Chrome). Defaults to false until Chrome implements reliable/large data transfer. This parameter is only available in the most recent build.

Before writing to / data will be emitted from the DataConnection object that is returned, the open event must fire. Also the error event should be checked in case a connection cannot be made.

peer.destroy()

Close the server and terminate all connections.

Event: 'connection'

function (connection, meta) { }

When a new connection is established from another peer to this peer, the DataConnection object is emitted with this event. The meta argument contains whatever metadata values passed into peer.connection(...) by the remote peer.

Note: the open event must fire on the DataConnection before it is ready to read/write.

Event: 'open'

function(id) { }

Fired when the PeerServer connection is succesfully, fully, open. This event does not need to fire before creating or receiving connections. You should not wait for open before connecting to other peers or expecting to receive connections if connection speed is important.

id is the id of this Peer object, either provided in the constructor, or generated automatically by the PeerServer.

Event: 'error'

function (error) { }

Emitted when an unexpected event occurs. Errors on the Peer are always fatal. Errors from the underlying socket and PeerConnections are forwarded here.

The error object also has a type parameter that may be helpful in responding to client errors properly:

• invalid-id: The ID passed into the Peer constructor contains illegal characters.
• invalid-key: The API key passed into the Peer constructor contains illegal characters or is not in the system (cloud server only).
• unavailable-id: The ID passed into the Peer constructor is already taken.
• Errors types that shouldn't regularly appear:
  • server-error: Unable to reach the server.
  • socket-error: An error from the underlying socket.
  • socket-closed: The underlying socket closed unexpectedly.
• (The Peer object is destroyed after one of the errors above are emitted.)
• peer-destroyed: A Peer that has been destroyed is being used to try to connect.

Event: 'close'

function () { }

Emitted when the Peer object has closed its connection with PeerServer so no more remote peer connections can be made or received.

To be extra certain that Peer objects clean up cleanly (and because it takes the WS server and DataChannel some time to realize that a Peer has disconnected), it is best to call destroy() on a Peer when it is no longer needed.

Class: peerjs.DataConnection

This class is the interface two communicate between two peers. It is an EventEmitter.

There is no constructor. A DataConnection object must be obtained in the callback of peer.connect(...) when initiating a peer-to-peer connection or emitted in the peer.on('connection', ...) event when receiving a connection.

EXPERIMENTAL reliable and large file transfer:

Simply pass in reliable: true when calling .connect(...). This module is experimental, temporary, and exists here: https://github.com/michellebu/reliable

connection.id

The id of the local peer that this connection belongs to.

connection.peer

The id of the remote peer this connection is connected to.

connection.open

Whether the connection is open (ready for read and write).

connection.metadata

The metadata passed in when the connection was created with peer.connect(...).

connection.serialization

The serialization format of the connection. Can be binary, binary-utf8, json, or none for no serialization. Default serialization format is binary.

Note: binary-utf8 will take a performance hit because of the way utf8 strings are packed into binary.

connection.send(data)

Accepts data of any JSON type or binary type.

To configure which serialization format to use, specify binary, binary-utf8, json, or none as the serialization property of the options object in peer.connect(...).

Data is serialized using BinaryPack (binary) by default and then sent to the remote peer.

connection.close()

Gracefully closes the connection.

Event: 'data'

function (data) { }

Emitted when data is received from the remote peer.

The data parameter contains values exactly as put into the connection.send(...). Binary types will have been deserialized to ArrayBuffer.

Event: 'open'

function () { }

Emitted when the connection is established and ready for writing. data from the remote peer will also start to be emitted.

Event: 'error'

function (error) { }

If the client emits an error, this event is emitted (errors from the underlying DataChannel are forwarded here).

error is an Error object.

Event: 'close'

function () { }

Is emitted when the connection is closed.

The close event is also emitted when the remote peer closes the connection.