Player¶
components/PlayerBar.tsx owns the single <audio> element. Its src is always the local
endpoint http://127.0.0.1:<port>/api/stream/<id>/audio; the browser handles buffering and
seeking by sending Range requests (serving).
Load sequence¶
When state.currentSong changes, load(song) runs:
const gen = ++loadGen.current; // this load's generation
loadAbort.current?.abort(); // cancel the previous /play
const ctrl = new AbortController();
audio.pause(); audio.removeAttribute("src"); audio.load(); // stop the old song now
const info = await api.playSong(song.id, ctrl.signal); // POST /play: resolves the stream
if (gen !== loadGen.current) return; // a newer song was chosen meanwhile
store.setDurationMs(info.duration_ms);
audio.src = api.getStreamAudioUrl(song.id);
await audio.play();
Clicking five songs quickly fires five /play requests, but only the last one sets audio.src:
earlier ones are aborted or fail the generation check. The backend does the same on its side
(_play_seq), so the session also ends on the last song.
duration_ms from /play (exact, from the segment table) is shown until the element's own
loadedmetadata arrives. A spinner replaces the play button while loading.
The time from load() to the playing event is logged to the API relay as
TTFA <id> <ms> cached=<bool> (Logs → API relay). Typical values: ~25 ms when init and the first
segment are cached, 1.3–1.6 s for an uncached song.
Segment bar¶
/api/stream/{id}/chunks is polled every 500 ms (with an in-flight guard) and drawn as one cell
per segment, sized by duration and coloured by status: pending, downloading (pulsing),
downloaded, error. Cell offsets are computed in a useMemo. Clicking the bar maps the x
position to a time and seeks:
audio.currentTime = t; // browser issues a Range request
api.seek(t * 1000); // backend bumps the epoch, buffers from there
App.tsx polls /api/stream/cache-info (every 5 s) for the cache usage in the sidebar.
Persistence¶
state.ts saves {songs, currentIndex, volume, repeat} to localStorage under amp.queue.v1,
debounced 500 ms, inside try/catch (storage can be unavailable). On startup,
player/persistence.ts validates what it reads: song IDs must be 11-character YouTube IDs, the
index and volume are clamped, and anything malformed is dropped.
The restored song is shown paused and isn't loaded: playToken stays at 0, so the load
effect does nothing. The play button sees that the loaded ID doesn't match and calls load().
Next-song prefetch¶
// player/prefetch.ts
shouldPrefetch(positionMs, durationMs) =
durationMs - positionMs < 20_000 || positionMs > 0.8 * durationMs;
The 2 s position tick checks this. The first time it's true for a song,
POST /api/stream/buffer/<next>?mode=prefetch is sent once. The backend resolves the next
song's stream and downloads its first segments at low priority, so the next /play returns in
milliseconds and playback starts from disk.
Error handling¶
| Failure | Shown as |
|---|---|
/play fails with a coded error |
describeError(): e.g. auth_required → "Sign in required for this track", node_missing → "Node.js not found. Install it and restart." |
fetch itself fails |
"Backend not reachable" |
audio.play() rejected (autoplay policy) |
"Autoplay blocked — click play to start" |
<audio> error after src was set |
describeMediaError(code): 1 aborted, 2 network, 3 decode, 4 format not supported |
On a network error (MEDIA_ERR_NETWORK) mid-song, the player reloads the source once per load
and resumes at currentTime. This pairs with the backend's rule of aborting the connection
rather than sending a short body when a segment fails. A second failure is shown to the user.
The texts live in player/errors.ts, next to the codes from api/errors.py. Keep them in sync.