Skip to content

Peer

The Peer class is a entry point for P2P connection and room connection. In order to use ECLWebRTC, Peer instance is necessary.

Constructor(id, options)

Constructor(options)

Create a new Peer instance. new Peer() starts connection to ECLWebRTC's signaling server.

Sample

// Set debug level to 3
const peer = new Peer('some-peer-name', {
  key:   "<YOUR-API-KEY>"
  debug: 3,
});
// Use TURN server forcely
const peer = new Peer({
  key:   "<YOUR-API-KEY>"
  config: {
    iceTransportPolicy: 'relay',
  },
});

Parameter

Name Type Required Default Description
id string Your Peer ID. If no value is given, the Peer ID is generated by the signaling server.
options options object Options to configure connection parameters.

options object

Name Type Required Default Description
key string ECLWebRTC API key.
debug number 0 Log level. NONE: 0, ERROR: 1, WARN: 2, FULL: 3.
turn boolean true Whether using ECLWebRTC's TURN server or NOT.
credential credential object The credential to authenticate peer.
config RTCConfiguration Default RTCConfiguration object RTCConfiguration object passed into RTCPeerConnection. This is advanced option.

credential object

See Peer authentication example for details.

Name Type Required Default Description
timestamp number Current UNIX timestamp.
ttl number Time to live; The credential expires at timestamp + ttl.
authToken string Credential token calculated with HMAC.

Default RTCConfiguration object

const defaultConfig = {
  iceServers: [{
    urls: 'stun:stun.webrtc.ecl.ntt.com:3478',
    url:  'stun:stun.webrtc.ecl.ntt.com:3478',
  }],
  iceTransportPolicy: 'all',
  sdpSemantics: 'unified-plan',
};

Members

Name Type Description
id string The Peer ID specified by a user or generated by signaling server.
open boolean Whether the socket is connecting to the signaling server or NOT.
connections Object Object contains all connections.
rooms Object Object contains all rooms.
options Object Object reflects Constructor() options and default options.

Methods

call(peerId[, stream][, options])

Create a new MediaConnection with Peer ID. With option, bandwidth or/and codec can be specified.

Parameters

Name Type Required Default Description
peerId string The Peer ID you are calling.
stream MediaStream The MediaStream to send to the remote peer. If not set, connection will behave as recvonly.
options call options object Options for call().
call options object
Name Type Required Default Description
metadata Object Any additional data to send to the remote peer.
videoBandwidth number A max video bandwidth(kbps).
audioBandwidth number A max audio bandwidth(kbps).
videoCodec string A video codec such as 'H264'.
audioCodec string A audio codec such as 'PCMU'.
videoReceiveEnabled boolean Set to true and your stream does not include video track, you will be video receive only mode.
audioReceiveEnabled boolean Set to true and your stream does not include audio track, you will be audio receive only mode.
connectionId string The ID to identify each connection.
label string Deprecated! The Label to identify each connection. Use connectionId instead.

Return value

A MediaConnection instance.

Sample

// Call a remote peer with your stream
const call = peer.call('peerID', localStream);
// Call a remote peer with your stream and metadata
const call = peer.call('peerID', localStream, {
  metadata: {
    foo: 'bar',
  }
});
// Call a remote peer with H264 as a video codec
const call = peer.call('peerID', localStream, {
  videoCodec: 'H264',
});
// Call a remote peer with audio receive only mode
const call = peer.call('peerID', null, {
  audioReceiveEnabled: true,
});

connect(peerId[, options])

Create a new DataConnection with Peer ID.

Parameters

Name Type Required Default Description
peerId string The Peer ID you are connecting.
options connect options object Options for connect().
connect options object
Name Type Required Default Description
metadata Object Any additional data to send to the remote peer.
serialization string 'binary' Serialization for data when sending. One of 'binary', 'json', or 'none'.
dcInit RTCDataChannelInit {} RTCDataChannelInit object passed into createDataChannel() to change reliability. It is defaulting to true.
connectionId string The ID to identify each connection.
label string Deprecated! The Label to identify each connection. Use connectionId instead.

Return value

A DataConnection instance.

Sample

// Connect a remote peer with reliable mode(default)
peer.connect('peerId');
// Connect a remote peer with metadata
peer.connect('peerId', {
  metadata: {
    hoge: "foobar",
  }
});
// Connect a remote peer with unreliable mode
peer.connect('peerId', {
  dcInit: {
    maxRetransmits: 2,
  },
});

destroy()

Destroy all connections and disconnect socket to the signaling server.

Return value

undefined

disconnect()

Disconnect socket to the signaling server, then emit disconnected event.

Return value

undefined

reconnect()

Reconnect to the signaling server.

Return value

undefined

joinRoom(roomName[, roomOptions])

Join full-mesh type or SFU type room. See this page for the difference between full-mesh and SFU type.

Parameters

Name Type Rquired Default Description
roomName string The room name you are joining.
roomOptions room options object {} Options for joinRoom().
room options object
Name Type Required Default Description
mode string 'mesh' One of 'sfu' or 'mesh'.
stream MediaStream The MediaStream you want to emit.
videoBandwidth number A max video bandwidth(kbps). Only available when mode is 'mesh'.
audioBandwidth number A max audio bandwidth(kbps). Only available when mode is 'mesh'.
videoCodec string A video codec such as 'H264'. Only available when mode is 'mesh'.
audioCodec string A audio codec such as 'PCMU'. Only available when mode is 'mesh'.
videoReceiveEnabled boolean Set to true and your stream does not include video track, you will be video receive only mode. Only available when mode is 'mesh'.
audioReceiveEnabled boolean Set to true and your stream does not include audio track, you will be audio receive only mode. Only available when mode is 'mesh'.

Return value

An SFURoom instance or a MeshRoom instance.

Sample

// Join full-mesh room
const room = peer.joinRoom('roomName', {
  mode: 'mesh',
  stream: localStream,
});
// Join sfu room
const room = peer.joinRoom('roomName', {
  mode: 'sfu',
  stream: localStream,
});

listAllPeers(callback)

Call REST API to get the list of Peer IDs associated with API key.

Parameters

Name Type Required Default Description
callback Function The callback function to get Peer IDs.

Return value

undefined

Sample

peer.listAllPeers(peers => {
  console.log(peers)
  // => ["yNtQkNyjAojJNGrt", "EzAmgFhCKBQMzKw9"]
});

getConnection(peerId, connectionId)

Query the created MediaConnection or DataConnection.

Parameters

Name Type Required Default Description
peerId string The Peer ID.
connectionId string The connection ID.

Return value

MediaConnection instance or DataConnection instance or null.

updateCredential(credential)

Update credential to extend TTL of authentication. See Peer authentication example for details.

Parameters

Name Type Required Default Description
credential credential object A new credential generated by user.

Return value

undefined

Events

Event names can be referred by static property EVENTS of Peer class.

// These are the same
peer.on('open', () => {});
peer.on(Peer.EVENTS.open, () => {});

Event: 'open'

Fired when connected to the signaling server successfully.

Name Type Description
id string The Peer ID.
peer.on('open', id => {
  // ...
});

Event: 'call'

Fired when received a media call from remote peer.

Name Type Description
call MediaConnection A MediaConnection instance.
peer.on('call', call => {
  // ...
});

Event: 'close'

Fired when finished closing all connections.

peer.on('close', () => {
  // ...
});

Event: 'connection'

Fired when received a data connection from remote peer.

Name Type Description
conn DataConnection A DataConnection instance.
peer.on('connection', conn => {
  // ...
});

Event: 'disconnected'

Fired when disconnected from the signaling server.

Name Type Description
id string The Peer ID.
peer.on('disconnected', id => {
  // ...
});

Event: 'expiresin'

Fired when the former credential expired.

Name Type Description
sec number The second before credential expires.
peer.on('expiresin', sec => {
  // ...
});

Event: 'error'

Fired upon some error.

Name Type Description
error Error An error object.

Error object has type property to know its details.

Type Description
room-error Room name must be defined.
Room type is different (e.g. On the condition that the mesh room was created, that another user tries to create SFU room with same room name of Mesh cause this error)
SFU usage is disabled. Please enable SFU usage on dashboard.
Unknown-error. Please wait for a while and connect again.
Failed to fetch the room log. Please wait for a while and connect again
authentication Failed to authenticate
permission The room usage is not permitted
list-error Look like you have permission to list peers IDs. Please enable the ECLWebRTC REST API on dashboard.
disconnected Cannot connect to new Peer before connecting to ECLWebRTC server or after disconnecting from the server.
socket-error Lost connection to server
invalid-key API key is invalid
server-error Could not get peers from the server.
// If you join a room without room name
peer.on('error', error => {
  console.log(`${error.type}: ${error.message}`);
  // => room-error: Room name must be defined.
});