Rooms & codes
A junto room is not a place on a server; there is no server. A room is just a random 128-bit secret, and the room code is how that secret travels. When you run junto create movie.mkv, junto generates the room and prints a code like jun1nve3pbfqpfj5qtwkayld3365ui, copied to your clipboard automatically.
That jun1… string is the secret. From it, both sides derive (with domain-separated SHA-256) two things: a public room ID used only to filter for the room’s messages on relays, and a NIP-44 key that encrypts every message. Each participant also uses a throwaway nostr keypair per session, so there’s no long-lived identity to link sessions together. Anyone with the code can join; anyone without it sees only noise. So treat the code like a key to your front door: share it with the friends you want in the room, and not more widely.
Because the code carries the encryption keys, the security model is simple to reason about:
- Knowing the code lets you join the room and decrypt its coordination.
- Not knowing the code means relays carrying the traffic see only ciphertext, so they cannot tell what you are watching, or even that it is junto.
- There is no account to compromise and no central database of rooms to leak, because neither exists.
Sync engine
Once everyone is in, junto keeps playback identical across the room with a leaderless design. There is no host-as-authority that everyone else obeys; any peer can play, pause, seek, change speed, switch subtitle track, or move through a playlist, and that action propagates to everyone else.
Conflicts (two people poking the controls at once) resolve by last-writer-wins: each event carries a timestamp, and the newest one is the state the room converges on. Small clock and playback differences are smoothed by continuous drift correction: peers compare where they actually are against where the room says they should be and nudge playback to match, so you stay together to within about a second without anyone re-syncing by hand.
Every one of these messages is NIP-44 encrypted end-to-end before it leaves your machine, sent as ephemeral nostr events (kind 29888, which relays forward but never store) and published redundantly to several free public relays (relay.damus.io, nos.lol, relay.primal.net, nostr.mom by default). The relays that ferry them between peers are untrusted by design: they pass along ciphertext under an unlinkable room tag and learn nothing about the content. Drop a relay and junto re-dials it silently; lose them all briefly and the worst you see is a “reconnecting…” notice.
Transfer & streaming
Coordination is small. The movie is not, so junto moves the file directly between peers over a WebRTC data channel. The joiner opens one persistent connection per file: a single SDP offer/answer (non-trickle ICE) travels through the room’s encrypted channel, then byte ranges are negotiated on the data channel itself. The whole file streams over that one ordered, reliable channel with backpressure, and a seek simply redirects the stream to a new offset instead of tearing the connection down and rebuilding it. No third party ever holds the file, and it is SHA-256 verified so everyone ends up with a byte-identical, intact copy.
You do not wait for the whole download before pressing play. junto uses streaming playback: a joiner starts watching within seconds at the current playhead while the rest of the file arrives in the background. Because media players read an index when they open a file, junto fetches the index region first: for mp4/mov it walks the box structure to pull the moov atom exactly, wherever it sits and whatever its size; for other containers (like mkv Cues) it grabs the last 16 MiB. Either way, files whose index lives at the end still start instantly. If a transfer drops, it resumes from the last byte, even across sessions, so you can quit mid-download and rejoining picks up where you left off.
Streaming stays smooth as long as the download keeps ahead of the file’s bitrate. A very high-bitrate file (a 4K or Blu-ray remux runs tens of Mbit/s, and spikes higher in busy scenes) over a link that can’t keep up will pause to buffer until it catches up, so the bigger and higher-quality the file and the slower the link, the more buffering you trade for that quality. The always-smooth option is to have each watcher bring the file locally with junto join <code> <file>, which skips the transfer entirely.
The one rule streaming imposes: you cannot watch data you do not have yet. If someone seeks past the downloaded region, junto pauses the whole room with a “buffering…” notice, waits for that part to arrive, and then resumes everyone together. Nobody silently runs ahead of the group.
Subtitles ride along. If a sidecar subtitle file (.srt, .ass, .ssa, .vtt) sits next to a shared video, the host offers it automatically; streaming joiners fetch it first and load it into mpv for the right playlist item. So subtitle track and delay stay in sync without anyone hunting down subtitles separately.
Before any of this, a readiness gate lines everyone up: as friends join and load the file, the host sees a live count like 2/3 ready, and presses Enter to start the room at the same instant.
What relays can and cannot see
junto’s coordination rides free, public nostr relays. They are deliberately given as little as possible:
| What | Visible to a relay? |
|---|---|
| The fact that some encrypted messages are flowing | Yes. Relays route traffic, so they can see ciphertext exists |
| Your play / pause / seek / speed / subtitle actions | No. NIP-44 encrypted end-to-end, so relays see ciphertext only |
| The room code or its keys | No. Never transmitted in the clear |
| The filename or what you are watching | No. Never sent to a relay |
| The media file itself | No. It transfers directly peer-to-peer, never through a relay |
| Your IP address | Yes, to the relay you connect to, as with any internet service |
In short: relays are dumb pipes for encrypted coordination, and your file never touches them at all.
Read the source
This is the honest, plain-English version. The authoritative version is the code: junto is MIT-licensed and open source, so you can verify every claim on this page for yourself.