Home

Awesome

rtc-signaller

The rtc-signaller module provides a transportless signalling mechanism for WebRTC.

NPM

Build Status stable Gitter chat

Purpose

The signaller provides set of client-side tools that assist with the setting up an PeerConnection and helping them communicate. All that is required for the signaller to operate is a suitable messenger. A messenger is simply a function that is able to create a pull-stream Source and/or Sink. From version 5.0.0 the rtc-signaller package will use pull-streams to ensure robust delivery of messages.

By using this approach, we can conduct signalling over any number of mechanisms:

In the event that you want to implement a signaller without using pull-streams, then you can work from a base signaller using the rtc-signal/signaller implementation.

Getting Started

While the signaller is capable of communicating by a number of different messengers (i.e. anything that can send and receive messages over a wire) it comes with support for understanding how to connect to an rtc-switchboard out of the box.

The following code sample demonstrates how:

// create a new signaller, connecting to the target switchboard
var messenger = require('rtc-switchboard-messenger');
var signaller = require('rtc-signaller')(messenger('//switchboard.rtc.io/'));

// when a new peer is announced, log it
signaller.on('peer:announce', function(data) {
 console.log('new peer found in room: ', data);
});

// for our sanity, pop a message once we are connected
signaller.once('connected', function() {
  console.log('we have successfully connected');
});

// send through an announce message
// this will occur once the websocket has been opened and active
signaller.announce({ room: 'signaller-getting-started' });

Signaller Events

There are a number of events that are generating throughout the lifecycle of a signaller.

Events regarding local state

The following events are generated by the signaller in response to updates n it's own state:

Events regarding peer state

The following events relate to information that has been relayed to this signaller about other peers:

Signal Flow Diagrams

Displayed below are some diagrams how the signalling flow between peers behaves. In each of the diagrams we illustrate three peers (A, B and C) participating discovery and coordinating RTCPeerConnection handshakes.

In each case, only the interaction between the clients is represented not how a signalling server (such as rtc-switchboard) would pass on broadcast messages, etc. This is done for two reasons:

  1. It is out of scope of this documentation.
  2. The rtc-signaller has been designed to work without having to rely on any intelligence in the server side signalling component. In the instance that a signaller broadcasts all messages to all connected peers then rtc-signaller should be smart enough to make sure everything works as expected.

Peer Discovery / Announcement

This diagram illustrates the process of how peer A announces itself to peers B and C, and in turn they announce themselves.

Editing / Updating the Diagrams

Each of the diagrams has been generated using mscgen and the source for these documents can be found in the docs/ folder of this repository.

Identifying Participants

When working with rtc-signaller and upstream packages (such as rtc-quickconnect) there is a temptation to provide a custom id field when creating the signaller instance. While this is supported in the API, it is strongly discouraged and will likely be removed at some point in the future. The reason for this is that the signaller relies on this id field being unique in order to deliver messages that relate to a particular peer connection, to that peer connection.

A better approach is to include an additional uid (or similar) field in the announce message that will be sent to peers as part of the data payload. The value of this field can be unique for each session, or persist between sessions (consider saving the value to localStorage for example) and thus used to identify users within the context of WebRTC sessions.

Reference

The rtc-signaller module is designed to be used primarily in a functional way and when called it creates a new signaller that will enable you to communicate with other peers via your messaging network.

// create a signaller from something that knows how to send messages
var signaller = require('rtc-signaller')(messenger);

As demonstrated in the getting started guide, you can also pass through a string value instead of a messenger instance if you simply want to connect to an existing rtc-switchboard instance.

signaller.connect()

Manually connect the signaller using the supplied messenger.

NOTE: This should never have to be called if the default setting for autoconnect is used.

announce(data?)

The announce function of the signaller will pass an /announce message through the messenger network. When no additional data is supplied to this function then only the id of the signaller is sent to all active members of the messenging network.

Joining Rooms

To join a room using an announce call you simply provide the name of the room you wish to join as part of the data block that you annouce, for example:

signaller.announce({ room: 'testroom' });

Signalling servers (such as rtc-switchboard) will then place your peer connection into a room with other peers that have also announced in this room.

Once you have joined a room, the server will only deliver messages that you send to other peers within that room.

Providing Additional Announce Data

There may be instances where you wish to send additional data as part of your announce message in your application. For instance, maybe you want to send an alias or nick as part of your announce message rather than just use the signaller's generated id.

If for instance you were writing a simple chat application you could join the webrtc room and tell everyone your name with the following announce call:

signaller.announce({
  room: 'webrtc',
  nick: 'Damon'
});

Announcing Updates

The signaller is written to distinguish between initial peer announcements and peer data updates (see the docs on the announce handler below). As such it is ok to provide any data updates using the announce method also.

For instance, I could send a status update as an announce message to flag that I am going offline:

signaller.announce({ status: 'offline' });

leave()

Tell the signalling server we are leaving. Calling this function is usually not required though as the signalling server should issue correct /leave messages when it detects a disconnect event.

License(s)

Apache 2.0

Copyright 2013 - 2014 National ICT Australia Limited (NICTA)

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.