Building Whimcall: Video Calls That Recover by Themselves
How Whimcall keeps a link-based video call alive: signaling that reconnects without a second seat, a one-way move from peer-to-peer to an SFU, and step-by-step recovery when the media path breaks.
A guest opens a link and is in a video call: no account, no download, no setup. That was the promise of Whimcall (opens in a new tab). The promise is easy to make for the first minute of a call. The hard part is the rest of the call.
During a call, the Wi-Fi changes, a deploy restarts the server, a company firewall blocks direct media, or a third person joins a call that was made for two. The call must recover by itself from each of these, without a second seat for the same person and without a stuck screen. So I designed Whimcall as a set of state machines, and I gave each failure a defined path back.
What Whimcall is
Whimcall supports camera and microphone calls, screen sharing, picture in picture, live captions, room chat, and group rooms. The app uses TanStack Start, React, TypeScript, Tailwind CSS, Motion and WebRTC. Cloudflare Workers and Durable Objects coordinate the rooms. Two-person calls use direct peer-to-peer media; group rooms use Cloudflare Realtime SFU. Better Auth with passkeys, Cloudflare D1 with Drizzle, Plunk for email, and Stripe for billing handle accounts and paid rooms. I did the product concept, the brand and interface design, the full-stack development, the media architecture and the deployment.
Signaling that comes back
Each browser keeps one WebSocket to the Durable Object of its room. The socket carries offers, answers, ICE candidates, presence and media state. Close codes tell the browser whether it must reconnect or stop, so the browser never retries a room that ended or that is full.
- Backoff with jitter. After a drop, the browser waits 1, 2, 4 and then at most 8 seconds, times a random 0.8 to 1.0. When a deploy drops every socket in a room at once, the jitter spreads the reconnects.
- Hibernating rooms. Rooms use the WebSocket Hibernation API of Durable Objects. Each socket stores its session (role, name, mute state, tracks) in its attachment, so an idle room can leave memory and keep its sockets.
- One seat per person. The browser keeps its signaling session ID in session storage. On reconnect, the room finds the old socket for that session, keeps its role, admission and media state, and closes the old socket. A reconnect never takes a second seat.
- A full room says so. A room with no free seat answers with close code 4005. The browser shows the limit and does not retry in a loop. Free rooms hold 2 people, and rooms from Pro hosts hold up to 100.
Two people, then a group
A full mesh of direct connections does not scale: each new person adds one upload for each other person. So the room stores which media path it uses, and it changes the path only in one direction during a call.
When a third admitted person joins, the room tells every browser to close its peer connection and publish to Cloudflare Realtime SFU. The room stays on the SFU when it drops back to two people, so the call does not switch paths again in the middle of a conversation. In SFU mode, camera video publishes three simulcast layers. The person on stage gets the full layer and grid tiles get the quarter layer. A browser pulls video only for the tiles on screen, and audio only from people who are not muted.
Recovery of a direct call
Direct media must first find a path. The browser tries STUN, and uses TURN only when ICE needs it. The Worker mints short-lived Cloudflare Realtime TURN credentials, with a fallback to static TURN settings. Credentials go only to an open signaling session, at most 6 for each session, so nobody gets relay access without a seat in the room.
Then the path can break when the network changes under the call. The browser watches the peer connection and gives each kind of break its own step:
- Many drops heal by themselves, so a “disconnected” state gets 4 seconds first.
- After that, or at once on “failed”, the browser reconnects signaling, loads fresh ICE servers and restarts ICE.
- If media does not come back within 12 seconds, the browser closes the peer connection and builds a new one. Only one recovery runs at a time.
What I learned
Every exit needs a name
The close codes did more for reliability than any retry loop. When the browser knows why a socket closed, it can choose between “reconnect”, “show the limit” and “stop”, and it never spins on a room that will not let it in.
Membership is the socket
The open sockets are the room membership, keyed by a session ID that survives a reconnect. There is no second count that can disagree with them, so a reconnect or a second device cannot become a ghost seat or a duplicate seat.
Move in one direction
Each switch between peer-to-peer and the SFU is a moment when the media can fail. So a room switches up one time, and goes back only when it is empty. That is simpler and steadier than a switch each time someone leaves.
Try Whimcall
Start a room at whimcall.com (opens in a new tab) and share the link. The Whimcall case study shows these state machines with a table of each state and transition, the failure modes, and the source files behind each claim.
Comments
Sign in to write a comment.
Loading