README
📯 Trystero
Serverless WebRTC matchmaking for painless P2P: make any site multiplayer in a few lines
👉 TRY THE DEMO 👈
Trystero manages a clandestine courier network that lets your application's users talk directly with one another, encrypted and without a server middleman.
Peers can connect via BitTorrent, Firebase, or IPFS – all using the same API.
- How it works
- Get started
- Listen for events
- Broadcast events
- Audio and video
- Advanced
- API
- Strategy comparison
- Firebase setup
How it works
👉 If you just want to try out Trystero, you can skip this explainer and jump into using it.
To establish a direct peer-to-peer connection with WebRTC, a signalling channel is needed to exchange peer information (SDP). Typically this involves running your own matchmaking server but Trystero abstracts this away for you and offers multiple "serverless" strategies for connecting peers (currently BitTorrent, Firebase, and IPFS).
The important point to remember is this:
🔒
Beyond peer discovery, your app's data never touches the strategy medium and is sent directly peer-to-peer and end-to-end encrypted between users.
👆
You can compare strategies here.
Get started
You can install with npm (npm i trystero) and import like so:
import {joinRoom} from 'trystero'
Or maybe you prefer a simple script tag?
<script type="module">
import {joinRoom} from 'https://cdn.skypack.dev/trystero'
</script>
By default, the BitTorrent strategy is used. To use a different one just deep import like so (your bundler should handle including only relevant code):
import {joinRoom} from 'trystero/firebase'
// or
import {joinRoom} from 'trystero/ipfs'
Next, join the user to a room with a namespace:
const config = {appId: 'san_narciso_3d'}
const room = joinRoom(config, 'yoyodyne')
The first argument is a configuration object that requires an appId. This
should be a completely unique identifier for your app (for the BitTorrent and
IPFS strategies) or your Firebase database ID if you're using Firebase. The
second argument is the room name.
Why rooms? Browsers can only handle a limited amount of WebRTC connections at a time so it's recommended to design your app such that users are divided into groups (or rooms, or namespaces, or channels... whatever you'd like to call them).
Listen for events
Listen for peers joining the room:
room.onPeerJoin(peerId => console.log(`${peerId} joined`))
Listen for peers leaving the room:
room.onPeerLeave(peerId => console.log(`${peerId} left`))
Listen for peers sending their audio/video streams:
room.onPeerStream(
(stream, peerId) => (peerElements[peerId].video.srcObject = stream)
)
To unsubscribe from events, leave the room:
room.leave()
Broadcast events
Send peers your video stream:
room.addStream(
await navigator.mediaDevices.getUserMedia({audio: true, video: true})
)
Send and subscribe to custom P2P actions:
const [sendDrink, getDrink] = room.makeAction('drink')
// buy drink for a friend
sendDrink({drink: 'negroni', withIce: true}, friendId)
// buy round for the house (second argument omitted)
sendDrink({drink: 'mezcal', withIce: false})
// listen for drinks sent to you
getDrink((data, peerId) =>
console.log(
`got a ${data.drink} with${data.withIce ? '' : 'out'} ice from ${peerId}`
)
)
You can also use actions to send binary data, like images:
const [sendPic, getPic] = room.makeAction('pic')
// blobs are automatically handled, as are any form of TypedArray
canvas.toBlob(blob => sendPic(blob))
// binary data is received as raw ArrayBuffers so your handling code should
// interpret it in a way that makes sense
getPic(
(data, peerId) => (imgs[peerId].src = URL.createObjectURL(new Blob([data])))
)
Let's say we want users to be able to name themselves:
const idsToNames = {}
const [sendName, getName] = room.makeAction('name')
// tell other peers currently in the room our name
sendName('Oedipa')
// tell newcomers
room.onPeerJoin(peerId => sendName('Oedipa', peerId))
// listen for peers naming themselves
getName((name, peerId) => (idsToNames[peerId] = name))
room.onPeerLeave(peerId =>
console.log(`${idsToNames[peerId] || 'a weird stranger'} left`)
)
Actions are smart and handle serialization and chunking for you behind the scenes. This means you can send very large files and whatever data you send will be received on the other side as the same type (a number as a number, a string as a string, an object as an object, binary as binary, etc.).
Audio and video
Here's a simple example of how you could create an audio chatroom:
// this object can store audio instances for later
const peerAudios = {}
// get a local audio stream from the microphone
const selfStream = await navigator.mediaDevices.getUserMedia({
audio: true,
video: false
})
// send stream to peers currently in the room
room.addStream(selfStream)
// send stream to peers who join later
room.onPeerJoin(peerId => room.addStream(selfStream, peerId))
// handle streams from other peers
room.onPeerStream((stream, peerId) => {
// create an audio instance and set the incoming stream
const audio = new Audio()
audio.srcObject = stream
audio.autoplay = true
// add the audio to peerAudio object if you want to address it for something
// later (volume, etc.)
peerAudios[peerId] = audio
})
Doing the same with video is similar, just be sure to add incoming streams to video elements in the DOM:
const peerVideos = {}
const videoContainer = document.getElementById('videos')
room.onPeerStream((stream, peerId) => {
let video = peerVideos[peerId]
// if this peer hasn't sent a stream before, create a video element
if (!video) {
video = document.createElement('video')
video.autoplay = true
// add video element to the DOM
videoContainer.appendChild(video)
}
video.srcObject = stream
peerVideos[peerId] = video
})
Advanced
Binary metadata
Let's say your app supports sending various types of files and you want to annotate the raw bytes being sent with metadata about how they should be interpreted. Instead of manually adding metadata bytes to the buffer you can simply pass a metadata argument in the sender action for your binary payload:
const [sendFile, getFile] = makeAction('file')
getFile((data, peerId, metadata) =>
console.log(
`got a file (${metadata.name}) from ${peerId} with type ${metadata.type}`,
data
)
)
// to send metadata, pass a third argument
// to broadcast to the whole room, set the second peer ID argument to null
sendFile(buffer, null, {name: 'The Courierʼs Tragedy', type: 'application/pdf'})
Action promises
Action sender functions return a promise that resolves when they're done sending. You can optionally use this to indicate to the user when a large transfer is done.
await sendFile(amplePayload)
console.log('done sending to all peers')
Progress updates
Action sender functions also take an optional callback function that will be continuously called as the transmission progresses. This can be used for showing a progress bar to the sender for large tranfers. The callback is called with a percentage value between 0 and 1 and the receiving peer's ID:
sendFile(
payload,
// notice the peer target argument for any action sender can be a single peer
// ID, an array of IDs, or null (meaning send to all peers in the room)
[peerIdA, peerIdB, peerIdC],
// metadata, which can also be null if you're only interested in the
// progress handler
{filename: 'paranoids.flac'},
// assuming each peer has a loading bar added to the DOM, its value is
// updated here
(percent, peerId) => (loadingBars[peerId].value = percent)
)
Similarly you can listen for progress events as a receiver like this:
const [sendFile, getFile, onFileProgress] = room.makeAction('file')
onFileProgress((percent, peerId, metadata) =>
console.log(
`${percent * 100}% done receiving ${metadata.filename} from ${peerId}`
)
)
Notice that any metadata is sent with progress events so you can show the receiving user that there is a transfer in progress with perhaps the name of the incoming file.
Since a peer can send multiple transmissions in parallel, you can also use metadata to differentiate between them, e.g. by sending a unique ID.
Encryption
Once peers are connected to each other all of their communications are
end-to-end encrypted. During the initial connection / discovery process, peers'
SDPs are sent via
the chosen peering strategy medium. The SDP is encrypted over the wire, but is
visible in plaintext as it passes through the medium (a public torrent tracker
for example). This is fine for most use cases but you can choose to hide SDPs
from the peering medium with Trystero's encryption option. To opt in, just pass
a password parameter in the app configuration object:
joinRoom({appId: 'kinneret', password: 'MuchoMaa