Skip to content

When playback fails: retry, skip or wait

Melodius's recovery rules for a music player: separate a broken song from a broken connection, retry once with a fresh source, never skip while offline, and stop before a queue spins.

3 min read

Music players fail in two very different ways. Sometimes one song cannot play. Sometimes nothing can, because the connection dropped. Treating them the same is how a player skips through your whole queue on a train. These are the rules Melodius uses, written as a pure function in the shared core.

Whose fault is it?

  • Track failures: unavailable, forbidden, decode errors, timeouts. Another song would likely play.
  • Connection failures: network errors, the gateway unavailable. Every song would fail the same way.

Some codes are ambiguous. A request that never reached the server can surface as a timeout or "track unavailable". Before acting on those, the player asks whether Melodius can be reached at all.

The rules

typescript
type RecoveryStep =
  | { kind: "retry"; delayMs: number }  // same track, fresh source
  | { kind: "skip" }                    // next track
  | { kind: "wait" }                    // keep track and position, resume when online
  | { kind: "stop" };                   // show the error
  • Offline: wait. Nothing is the song's fault, so the queue is kept and the track resumes where it stopped once the connection returns.
  • Connection failure while online: retry after 2 s, then 6 s, then stop. Never skip.
  • Track failure: retry once after 1 s with a fresh source, then skip.
  • Can't skip: a Jam guest, repeat-one, or the last track stops instead.
  • Three skips in a row: stop. A queue where nothing plays should not spin through every song.

Knowing you are actually online

The browser's online event, or NetInfo on Android, only knows whether there is a network. A captive portal or a dead uplink still says online. So a failed request is followed by a probe of Melodius's own server: any HTTP answer means reachable. While it fails, the probe repeats with a growing pause, and concurrent checks share one probe so a burst of failures does not become a burst of requests.

Stalls count as failures

A track can "play" with no audio arriving. If a playing track stays stalled for twelve seconds, it is treated as a failed load and goes through the same rules, resuming at the position where it stopped.

Recovery pairs with the speed work in making a track start fast and the race fixed in a skip that played the previous song.

Illustrated avatar of Kumar Manas

Written by Kumar Manas

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

Related projectMelodius: music streaming platform