webrtc-link v2.0.0

WebRTC Link

A JavaScript module for working with WebRTC in the browser.

Features

• Supports video and audio streams.
• Tested using the latest versions of Google Chrome, Mozilla Firefox, Opera and Safari.
• Ability to configure the internal data channel for ultra low latency.
• 10KB bundle size.
• Written according to the latest version of the WebRTC 1.0 specification.

Install

$ npm install webrtc-link

Example

const WebRTCPeer = require('webrtc-link')

const peerOne = new WebRTCPeer({
  isInitiator: true,
  streams: [stream] // media stream from navigator.mediaDevices.getUserMedia
})

const peerTwo = new WebRTCPeer()

peerOne.on('signal', signal => peerTwo.signal(signal))
peerTwo.on('signal', signal => peerOne.signal(signal))

peerOne.on('connect', () => peerOne.send('Hello!'))
peerTwo.on('data', data => console.log(data)) // 'Hello!'

Events

Event: 'signal'

peer.on('signal', function (signal) {
  console.log('Transfer the signal data to the remote peer.')
})

Emitted when the peer wants to send the signal data to the remote peer.

The exact details of the signal object are unspecified.

Transporting the signal data to the remote peer is usually done over WebSockets.

A good WebSockets module is one-websocket.

Event: 'connect'

peer.on('connect', function () {
  console.log('Peer connection established.')
})

Emitted when the peer connection and data channel are ready to use.

Event: 'data'

peer.on('data', function (data) {
  console.log(`Received message: ${data}`)
})

Emitted when a message is received from the remote peer over the data channel.

Note that the data will be lost if there is no listener for the 'data' event.

Event: 'stream'

peer.on('stream', function (stream) {
  const video = document.createElement('video')
  video.srcObject = stream
  document.body.appendChild(video)
  video.play()
})

Emitted when a media stream has been received from the remote peer.

Event: 'track'

peer.on('track', function (track, stream) {})

Emitted when a media track has been received from the remote peer.

Event: 'removetrack'

peer.on('removetrack', function (track, stream) {})

Emitted when a media track has been removed by the remote peer.

Event: 'close'

peer.on('close', function () {
  console.log('The connection has been closed.')
})

Emitted once the peer connection has fully closed. No new events will be emitted on this peer.

Event: 'error'

peer.on('error', function (err) {
  console.log(err)
})

Emitted when a fatal error occurs - a single Error object is passed to the event handler function.

API

Constructor parameter: new WebRTCPeer(options)

options

If options are passed to the constructor then the default options (shown below) will be overridden.

{
  dataChannelConfig: {},
  isInitiator: false,
  isTrickleIceEnabled: true,
  peerConnectionConfig: { iceServers: [] },
  sdpTransformer: sdp => sdp,
  streams: []
}

peer.addStream(stream)

Send a MediaStream to the remote peer.

peer.addTrack(track, stream)

Send a MediaStreamTrack to the remote peer.

peer.destroy(err)

Destroy and cleanup this peer connection.

If err is specified, an 'error' event will be emitted and any listeners for that event will receive err as an argument.

peer.getStats()

Returns a Promise which is fulfilled once the statistics are available. The promise's fulfillment handler receives as a parameter a RTCStatsReport object containing the collected statistics.

peer.isConnected()

Returns a Boolean value indicating whether the peer is currently connected to the remote peer.

peer.isDestroyed()

Returns a Boolean value that indicates if the peer is destroyed or not. Once destroyed no further data can be transferred using it. No further events will be emitted.

peer.removeStream(stream)

Remove a MediaStream that is being sent to the remote peer.

peer.removeTrack(track)

Remove a MediaStreamTrack that is being sent to the remote peer.

peer.send(data)

Send the data to the remote peer.

Invoking send while the peer is not connected will throw an error. send will also throw an error if called after the peer has been destroyed.

peer.signal(data)

Invoke the signal function with the data generated by the other peer.

otherPeer.on('signal', function (signal) {
  peer.signal(signal)
})

This is a required part of the handshake process to set up a connection with the remote peer.

Error Codes

• ERR_ADD_ICE_CANDIDATE
• ERR_CREATE_ANSWER
• ERR_CREATE_OFFER
• ERR_DATA_CHANNEL
• ERR_ICE_CONNECTION_CLOSED
• ERR_ICE_CONNECTION_FAILURE
• ERR_PEER_IS_DESTROYED
• ERR_REMOVE_TRACK
• ERR_SET_LOCAL_DESCRIPTION
• ERR_SET_REMOTE_DESCRIPTION
• ERR_SIGNALING
• ERR_WEBRTC_SUPPORT

STUN/TURN Servers

STUN/TURN servers can be specified via the WebRTC Peer constructor.

const iceServers = [
  { urls: '<your stun/turn server url>' },
  { urls: '<another stun/turn server url>' }
]

const peerOne = new WebRTCPeer({
  isInitiator: true,
  iceServers: iceServers
})

const peerTwo = new WebRTCPeer({
  iceServers: iceServers
})

Data Channel Configuration

The internal data channel can be configured in the WebRTCPeer constructor by specifying the dataChannelConfig option.

Below is an example of making the data channel UDP like.

const peerOne = new WebRTCPeer({
  isInitiator: true,
  dataChannelConfig: {
    maxRetransmits: 0,
    ordered: false
  }
})

Development

Run the browser tests locally.

$ npm run test-browser-local

Visit http://localhost:8080/airtap using Google Chrome, Mozilla Firefox, Opera or Safari. Open the developer tools window and view the console window to see additional test output.

Latest browser versions which have passed successfully:

Google Chrome 75.0.3770.100 (Official Build) (64-bit)

Mozilla Firefox Quantam 67.0.4 (64-bit) for Ubuntu canonical-1.0

License

MIT. Copyright (c) Shane Bloomer.