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.
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
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.
