fast-rtc-swarm

A full-mesh WebRTC swarm built on top of WebSockets & fast-rtc-peer

Installation

yarn add @mattkrick/fast-rtc-swarm

What is it

fast-rtc-peer offers a great API to connect 2 peers. If you'd like to connect more than 2 peers, you're on your own. That's why this exists. It uses a full mesh (vs. partial mesh) network so every client is connected to every other client. A full mesh is great for up to ~100 connections. After that, you'll probably want to move to a partial mesh & trade a little latency for memory.

How's it different from webrtc-swarm?

fast-rtc-swarm is different.

It's built on fast-rtc-peer, which is built on the new WebRTC v1.0 spec (transceivers instead of stage 2 tracks or stage 1 streams)
The signaling server doesn't have to be server sent events. It can be anything. (see reference implementation)
It doesn't bother the signaling server with a heartbeat. We can derive that info from the swarm by listening to disconnected on each peer. If timeouts are an issue, then add a WebSocket#ping on your server. Don't make the client do more work than necessary!
It only connects to 1 signaling server. Multiple servers is a proxy problem. Again, don't make the client work hard!
No unauthenticated-by-default signaling server CLI. I'm not gonna make it easier for you to write an insecure server :-)
No multiplexing streams. If you need a new data channel, open another one natively, not with expensive (and LARGE) stream packages.
It uses the fast-rtc protocol for the fastest connection possible

What makes it so fast?

The fast-rtc protocol completes a WebRTC handshake in only 2 round trips. Other implementations take 3 (or even 4!) It does this by keeping a peerBuffer of offers and candidates. Think of it like "pay-it-forward". You buy the person behind you a coffee, so they get a free coffee when they get to register & buy the person behind them a coffee.

Here's how it works:

Alice is the first peer to join the swarm:

She gives the server an OFFER that can be used by the next person to join
As CANDIDATES and additional OFFERS trickle in, she forwards them to the server
The server groups CANDIDATES and OFFERS in a single CHUNK, awaiting an ACCEPT
When someone ACCEPTS her CHUNK, the server REQUESTS another from her
As CANDIDATES and OFFERS continue to trickle in, they are forwarded to client that ACCEPTED the original chunk

When Bob joins the swarm:

He follows the same procedure as Alice
He takes one CHUNK from each client on the server
If Alice does not have a CHUNK readily available, Bob puts his name on her waiting list
On the client, Bob creates an ANSWER to each OFFER and forwards it to the signaling server
The signaling server forwards Bob's ANSWER to Alice
Alice uses Bob's ANSWER to initiate the connection

That's it! See reference implementation and the example below to see how to add it to your own server.

Usage

// client
import FastRTCSwarm from '@mattkrick/fast-rtc-swarm'

const socket = new WebSocket('ws://localhost:3000');
socket.addEventListener('open', () => {
  const swarm = new FastRTCSwarm()
  // send the signal to the signaling server
  swarm.on('signal', (signal) => {
    socket.send(JSON.stringify(signal))
  })
  // when the signal come back, dispatch it to the swarm
  socket.addEventListener('message', (event) => {
    const payload = JSON.parse(event.data)
    swarm.dispatch(payload)
  })
  // when the connection is open, say hi to your new peer
  swarm.on('dataOpen', (peer) => {
    console.log('data channel open!')
    peer.send('hi')
  })
  // when your peer says hi, log it
  swarm.on('data', (data, peer) => {
    console.log('data received', data, peer)
  })
})

API

Config: A superset of fast-rtc-peer's config. To add a TURN server to the default list of ICE candidates, see fast-rtc-peer.

roomId: a string to define the room all the peers are joining
peerBuffer: the number of additional offers to keep on the server (default 0)

Methods on FastRTCSwarm

addStreams(streamDict): similar to fast-rtc-peer's addStreams, but updates your tracks for future peers
broadcast(message): send a string or buffer to all connected peers
close(): destroy all peer connections
dispatch(signal): receive an incoming signal from the signal server
muteTrack(trackName): mute's the track for all peers & future peers

Events

swarm.on('open', (peer) => {}): fired when a peer connects
swarm.on('close', (peer) => {}): fired when a peer disconnects
swarm.on('data', (data, peer) => {}): fired when a peer sends data
swarm.on('signal', (signal, peer) => {}): fired when a peer creates an offer, ICE candidate, or answer.
swarm.on('stream', (stream, peer) => {}): fired when a peer creates or updates an audio/video track.
swarm.on('error', (error, peer) => {}): fired when a peer has a signaling error.
swarm.on('connection', (stream, peer) => {}): fired when a peer's ICE connection state changes

License

MIT

mattkrick/fast-rtc-swarm

mattkrick

Reviews

Repository Details