Skip to content

Keeping friends in sync: clock offsets and drift correction for group listening

How Melodius Jams keep everyone on the same second of a song: server-anchored positions, NTP-style clock offsets, gentle playback-rate correction and reconnects with jitter.

3 min read

A Jam in Melodius lets friends hear the same second of the same track on different devices. Sending "play" to everyone at once is not enough: messages arrive at different times, device clocks disagree, and audio drifts as it plays. This is the small amount of maths that makes it work, all of it in the shared TypeScript core so web, desktop and Android behave identically.

Why "play at the same time" is hard

  • A command reaches each listener after a different network delay.
  • Each device's clock is off from the server's by an unknown amount, sometimes seconds.
  • Two players started together still drift apart by tens of milliseconds over a song.

So the protocol never says "you are at 0:42". It says "at server time T, the song was at position P".

Anchor positions to server time

Every state update carries a position and the server time it was true. A listener projects forward:

typescript
const projected = isPlaying
  ? positionMsAtAnchor + Math.max(0, serverNowMs - anchorServerTimeMs)
  : positionMsAtAnchor;
// clamped to [0, duration]

A late message is no longer wrong, just older: projecting it forward gives the right position as long as the listener knows the server's current time.

Estimating the clock offset

Knowing server time means knowing how far your clock is from it. Heartbeats every 15 seconds double as clock samples, the same trick NTP uses: note when the ping left, the server's time in the reply, and when the reply arrived. Assuming the trip is symmetric, the server's time was read halfway through:

typescript
const offset = (s: ClockSample) =>
  s.serverTimeMs - (s.requestSentAtMs + s.responseReceivedAtMs) / 2;

One sample is noisy, so the client keeps the last eight and uses the median. A single slow round trip cannot drag the estimate, which a mean would allow.

Correcting drift without a jump

Comparing the local position with the projected target gives a drift, and the correction depends on its size:

  • Under 250 ms: do nothing. Nobody hears it, and constant nudging sounds worse.
  • 250 ms to 1.5 s: change the playback rate slightly, by at most 3%, to close the gap over about four seconds. Speeding up 3% is inaudible for most music.
  • Over 1.5 s: seek. A gap that big would take too long to close smoothly.
  • While paused: seek if off by more than 120 ms, since nobody hears a paused seek.
typescript
const adjustment = clamp(drift / 4_000, -0.03, 0.03);
return { kind: "rate", playbackRate: 1 + adjustment };

A socket that survives bad networks

  • Reconnects back off exponentially from 500 ms to 15 s, with up to 250 ms of random jitter so a server restart is not met by every client at the same instant.
  • State-changing commands such as play, seek and skip stay pending until the server acknowledges them, at most 32 with the oldest dropped first, and are sent again when the socket reconnects.
  • The session ticket rides in the WebSocket subprotocol list, so it never appears in a URL or a log line.
  • Auth failures and rate limits are reported as their own errors, so the UI can say "sign in again" instead of retrying forever.

The result feels simple to listeners, which is the goal. The same core also drives playback recovery, covered in retry, skip or wait.

Illustrated avatar of Kumar Manas

Written by Kumar Manas

Full-stack developer in India. I build Melodius and Krypton.

Related projectMelodius: music streaming platform