Fork me on GitHub

rtc-signaller Protocol Overview

The signalling used by rtc-signaller follows some very simple rules:

Transport Agnostic

While the rtc-signaller module provides some default behaviour to connect via websockets, it is in fact a transport "agnostic" protocol.

Basically, if you can send text over x then you could use x to send rtc-signaller messages.

Sender Metadata

Sender metadata is injected into a message directly after the command (or initial message part) for all messages. The only exception is a /to message which has no sender metadata attached as this should be contained within the wrapped message.

At this stage only the sender id is included in the sender metadata (JSON), but this may be extended in the future to include additional information.

Core Commands

There are only a few core commands which make up the rtc-signaller signalling. These core commands should receive "special" treatment from a signalling server, whereas other commands are simply "passed through" to connected clients.


The announce command is used to tell a signalling server (and connected peers) that a new client is joining a virtual room. The payload of the command is JSON and requires at least an id and a room attribute to be specified.

For example, this is what an announce message would typically look like (line breaks added for clarity):



Unsurprisingly, a /leave message is the counterpart to an /announce message and is sent when a peer is disconnecting from the room.

NOTE: As most client leave actions are "hard closes", i.e. a browser window / tab has been closed, a signalling server should monitor disconnections and issue an appropriate /leave message if the client has not issued one already.


The /to command allows you to direct a message to a particular peer rather than broadcasting it to all peers connected to the same room as you.

An example /to command might look something like (again line breaks for clarity):


For security reasons a signaling server is encouraged to direct /to messages only the connected peer; however, a client implementing this protocol should drop all '/to' messages that do not match it's own id.

That's Pretty Much It

From a "protocol" perspective that's really all there is to it.

Writing a Client

The responsibilities of a client are fairly simple:

Writing a Server

The responsibilities of a server are also simple:

What About Authentication?

While this hasn't been implemented in any applications to date, encrypted credentials or a session token could be supplied as part of the announce metadata.

Additionally for per message authentication a session token could be included as part of the sender metadata that is included in each message. This could be validated by the signaling server and stripped from the message before passing onto connected peers.

What About Scaling?

My intention was to minimally but adequately map out the interation required between peers, ensuring that both broadcast and direct messages were catered for. The likelihood is that implementing server -> server message passing and routing will require some additional work but this isn't something the end clients should have to care about.