Frontend System Design13 min readPremium

Design a Music Player – Frontend System Design

Design a Music Player - Frontend System Design

We’ll walk through the frontend system design for a music streaming app like Spotify. Our goal is a browseable catalog with a player that never dies when the route changes: a persistent bar, a reorderable queue, adaptive bitrate audio, and a resume position that survives a refresh. You’ll see why the player is a singleton outside the router, how MSE (and DRM) actually feed an <audio> element, and how progress writes stay off the hot path.

The interview fails the moment a song stops because the user clicked a playlist. That is an architecture bug, not a CSS bug. We’ll mount the audio engine on the app shell, keep timeupdate out of the global store, and treat playback as a server-issued session so a second device can take over.

Problem Statement

Build the frontend for a music streaming app like Spotify.

Requirements:

  • Browse playlists, albums, and search
  • A persistent player bar that keeps playing while the user navigates
  • A queue the user can reorder
  • Offline downloads for a playlist
  • Playback should resume where the user left off

Describe the player, the queue, how audio streams in the browser, and how you keep playback alive across routes.

Interviewers want the shell/player split first. Then they want you to say HLS/DASH + MSE, not “we set audio.src to an mp3.” DRM and gapless are follow-ups — name them, do not design a licensor on the whiteboard.


Clarifying Questions

# Question Interviewer’s Answer
1 Web only? Yes. Mention how a native app would share the same API.
2 Podcasts and lyrics? Out of scope.
3 DRM? Yes, treat tracks as licensed audio.
4 Gapless playback and crossfade? Nice to have. Call them out.
5 Casting / multiple devices? Out of scope, besides “one active player per account.”

“One active player per account” is a product rule with an API: starting playback elsewhere returns 409 PLAYBACK_TAKEN and this tab pauses. Native apps would call the same POST /api/playback/:trackId and the same progress endpoint — say that so they know the web client is not a special snowflake.


Requirements

  • App shell with a player that is never unmounted on route change
  • Queue: play next, history, shuffle, repeat
  • Adaptive bitrate audio (lower bitrate on cell)
  • Offline: downloaded tracks play from IndexedDB / Cache Storage
  • Resume position synced to the server

Non-Functional Requirements

  • Clicking play starts audio within a perceived instant (first segment, not the whole track)
  • Seek is accurate to the segment boundary you advertise; do not pretend you have frame-accurate scrub if you do not
  • timeupdate must not re-render the playlist or the search page
  • Progress survives refresh and “play on another device”
  • Downloaded playlists play with the network off

Napkin Math

Metric Estimate
160kbps track, 3:30 ~4 MB
Progress heartbeat every 30s, plus pause / seek / track end
Queue tens to a few hundred tracks. Keep it in memory.

Scalability Estimates

Audio is small next to video, but the chatty part is progress and the catalog, not the file.

Metric Estimate Calculation Notes
160kbps × 3:30 ~4.0 MB 160,000 bits/s × 210s / 8 = 4,200,000 bytes A full-file download is fine for offline; streaming should not wait for 4MB.
First playable chunk ~40–80KB ~2s of 160kbps is 40KB Time-to-first-audio is this fetch + MSE append, not the whole track.
Renditions 96 / 160 / 320 kbps Pick from navigator.connection + buffer health Cell → 96. Wi-Fi → 160. Premium / explicit 320.
Progress writes ~2–4/min while playing Heartbeat 30s + pause/seek/end Throttle. sendBeacon on hide.
Queue size tens to a few hundred Track ids + denormalized metadata In memory. Persist ids to the server.
Offline playlist of 50 tracks ~200 MB at 160kbps 50 × 4MB Ask before download. Store by track id + rendition.

If you PUT progress on every timeupdate (~4Hz), a single listening session is hundreds of writes. That is the number you use to justify the 30s heartbeat.


Architecture

Spotify Frontend System Design Architecture
The player cannot live inside a page. If it does, changing routes tears it down and the song stops.

The shell is the product. Router views (home, search, playlist, album) mount and unmount freely. PlayerBar sits beside the router, not under it. usePlayer() is a module singleton (or a React context at the shell). Playback state (currentTime, buffered, status) stays out of the global browse store so timeupdate doesn’t re-render the app.

Browse data is a normal HTTP cache: playlists, search hits, album pages. Player data is a session: queue, current index, status, volume. Mixing those two stores is how a seek re-renders 200 playlist rows.


<AppShell>
  <Router />                 // browse, search, playlist
  <PlayerBar>
    usePlayer()              // singleton
    <AudioEngine />          // <audio> + MSE
    <NowPlaying />
    <QueueDrawer />
  </PlayerBar>
</AppShell>

Component Structure and Responsibilities

  • AppShell mounts the player once per tab. It also registers Media Session actions (play, pause, next, seek) so lock-screen controls work.
  • Router views are dumb about audio. A playlist page calls player.playFrom(trackIds, index). It does not create an <audio>.
  • AudioEngine owns the hidden <audio>, the MediaSource, and the EME license dance. It exposes play/pause/seek/setRendition. It emits time on a ref plus a 250ms tick for the seek bar only.
  • NowPlaying is the bar UI: artwork, title, transport, volume. It subscribes to track and status, not to every time tick — the seek bar has its own small subscriber.
  • QueueDrawer is a reorderable list of the singleton queue. Drag-and-drop writes the in-memory array and debounces PUT /api/queue.
  • OfflineManager downloads segments into Cache Storage, keyed by trackId + rendition. The engine checks cache before network.

Network Layer and Data Management

Two clients, one auth cookie.

  • Catalog client: playlists, search, album — cursor-paginated GET, cacheable
  • Playback client: POST /api/playback/:trackId returns sessionId, manifestUrl, licenseUrl, resumeSec
  • Progress client: throttled PUT, plus sendBeacon on pagehide
  • Queue client: GET/PUT the list of track ids for this user
  • Signed manifest URLs expire. When they do, the engine re-POSTs playback for the same track and session if still valid

Core Playback Workflow

  1. User hits play on a playlist row. The view calls player.playFrom(ids, index).
  2. The singleton sets the queue, marks status loading, and POST /api/playback/:trackId.
  3. The engine attaches MSE to the hidden <audio>, fetches the first HLS/DASH segment (cache first), appends, and calls audio.play() from the user gesture when possible.
  4. If the catalog is licensed, EME requests a license with the session cookie. Keys stay in the CDM, not in localStorage.
  5. timeupdate writes a ref. The seek bar reads it on rAF or a 250ms interval. The rest of the app does not subscribe.
  6. Near the end (last ~10s), prefetch the next track’s first segment for gapless. On ended, swap the buffer and play.
  7. Every 30s, on pause, on seek, and on ended: PUT progress. On tab hide: sendBeacon.

Building the Audio Engine

Same idea as Netflix, smaller files — but “put it in <audio src>” is still the wrong answer. A file URL cannot switch bitrate mid-song, cannot decrypt Widevine, and cannot splice the next track without a gap.

What the singleton actually owns

One hidden <audio> (or an AudioContext destination) lives in the shell for the life of the tab. React never unmounts it on route change. The rest of the app talks to a player module:


type Engine = {
  audio: HTMLAudioElement;
  mediaSource?: MediaSource;
  sourceBuffer?: SourceBuffer;
  next: { trackId: string; buffer: ArrayBuffer } | null;
  unlocked: boolean; // true after the first user-gesture play()
};
  • HLS or DASH of AAC/Opus renditions (96 / 160 / 320 kbps)
  • MSE appends segments into that hidden element
  • EME + Widevine/FairPlay if the catalog is licensed — keys stay in the CDM
  • ABR is the same as video: throughput + buffer length, step down fast, climb slow

Safari’s native HLS-in-<audio> is a valid fallback if MSE+HLS is painful. Feature-detect. Do not maintain two UIs.

Gapless is a buffer, not a second element

One audio element, next track prefetched for gapless swap
When duration - currentTime < 10s, fetch the next track’s first segment (cache first) and hold it in engine.next. On ended (or at the encoder’s padding boundary), reset the MediaSource, append that segment, and play() immediately. The user gesture from the original click still covers you because the element never left the document.

A second <audio> you start at ended will click. The gap is the time to create the element, set src, and wait for canplay. That is why you reuse one element and keep the next bytes in memory.

Crossfade is the follow-up: two buffers into a Web Audio graph, each through a GainNode, destination = speakers. You ramp A down and B up over 4–8s. Mention it, leave it out of v1. Media Session and the seek bar still read a single logical playhead (the one the user thinks is “the song”).

Web Audio vs <audio>

<audio> + MSE Web Audio graph
Use for Catalog playback, DRM, Media Session EQ, crossfade, spatial, meters
DRM EME works You cannot pipe CDM PCM into a ScriptProcessor
Background tab Keeps playing AudioContext suspends unless you resume

Interview default: <audio> + MSE. If they ask for an equalizer, captureStream() is not how you do it for licensed audio. You apply DSP only to unencrypted catalog, or you live with the OS equalizer. Say that.

Media Session, lock screen, and the seek bar

navigator.mediaSession.metadata and the action handlers (play, pause, previoustrack, nexttrack, seekto) are how headphones and the lock screen work. Set them on track change, not on every timeupdate.

timeupdate writes a ref. The seek bar is the only React subscriber, and it polls the ref at 4–10 Hz. The rest of the app must not re-render at 4 Hz.

Offline

Download segments into Cache Storage, keyed by trackId + rendition. IndexedDB holds the manifest (which ids, which rendition, bytes stored). The engine checks the cache before the network. Downloaded tracks skip ABR and play the stored rendition. Quota: navigator.storage.estimate(), evict least-recently-played first, never evict the currently playing track.

Autoplay policy: the first play() must sit in a click/tap handler. After that, the engine may call play() on track advance because the session is already unlocked. If a route change happens before the first gesture, do not surprise-start a song.

Queue is a snapshot

Play from search, an album, or a playlist copies that list into a queue snapshot. The player operates on the snapshot. Shuffle, repeat, and “remove this song” do not mutate the playlist document. Next/prev walk the snapshot. If the source playlist changes while you listen, you do not jump.

Shared core, thin adapters

Queue math, repeat, checkpoints, and reconnect live in one module. Web wraps <audio> + MSE. Desktop swaps in a native decoder and a real filesystem for downloads. OS media keys and the lock screen talk to the same controller. Do not fork shuffle for Electron.

Playback is a state machine. The element emits play, waiting, ended, error. The UI does not subscribe to those. The controller maps them to loading | playing | stalled | ended | error and writes the checkpoint in one place. Otherwise the bar, the Media Session, and the speaker drift apart.

Connect (follow-up)

Each device registers with the server and heartbeats. Transfer is “export the queue + checkpoint, other device plays, this one becomes a remote.” You already have the session types. The new piece is a command channel, not a second player architecture. Lyrics, EQ, and private playlists are the same kind of follow-up — do not design them first.


State and Data Flow

Split the stores or you will fight React for the entire interview.

  1. Catalog views fetch and render lists. They never see currentTime.
  2. A play gesture writes the queue on the player singleton and starts the engine.
  3. The engine updates a ref on timeupdate. The seek bar is the only React subscriber, and it throttles.
  4. Track/status changes (new song, pause, error) are coarse events. Now Playing and the Media Session metadata update then.
  5. Progress and queue sync are side effects of those coarse events, not of every tick.

Performance, Prefetching, and Caching

  • Keep the player mounted. Lazy-load lyrics / queue UI, not the engine.
  • Prefetch next track audio in the last 10s. Prefetch playlist JSON when a row is hovered, not every artwork at 320kbps.
  • Artwork via CDN srcset. The bar image is tiny (64px). The Now Playing view can request 300px. Do not reuse a 640px file in a list of 50.
  • Catalog cache: stale-while-revalidate for playlist pages so back-navigation is instant and the song does not hitch.
  • Offline cache: Cache Storage for segments. IndexedDB for the download manifest (which track ids, which rendition, bytes stored).
  • Code split: search, lyrics (out of scope), and the queue drawer load on demand. The engine loads with the shell.

navigator.connection.effectiveType is a hint, not a contract. If the buffer stalls twice, drop from 160 to 96 even on “wifi.” If the buffer is healthy, you may step up at a segment boundary.


Data Model

Queue items are track ids plus enough metadata to render the bar without a fetch after a refresh.


export type Track = {
  id: string;
  title: string;
  artist: string;
  durationSec: number;
  artworkUrl: string;
};

export type RepeatMode = "off" | "one" | "all";

export type PlayerStatus = "idle" | "loading" | "playing" | "paused" | "stalled" | "error";

export type PlaybackSession = {
  sessionId: string;
  trackId: string;
  manifestUrl: string;
  licenseUrl?: string;
  resumeSec: number;
  renditions: { kbps: number; id: string }[];
};

export type QueueState = {
  trackIds: string[];
  tracksById: Record<string, Track>;
  index: number;
  shuffle: boolean;
  repeat: RepeatMode;
  history: string[];
};

export type ProgressPayload = {
  sessionId: string;
  trackId: string;
  positionSec: number;
  updatedAt: string;
};

Shuffle copies a shuffled order; it does not mutate the user’s playlist on the server. Repeat-one does not advance the index on ended. History is what “previous” means when you are not at index 0.


API


export type Track = {
  id: string;
  title: string;
  artist: string;
  durationSec: number;
  artworkUrl: string;
};

// GET  /api/playlists/:id
// POST /api/playback/:trackId  -> { sessionId, manifestUrl, licenseUrl, resumeSec }
// PUT  /api/progress/:trackId  { sessionId, positionSec, updatedAt }
// GET  /api/queue
// PUT  /api/queue              { trackIds: string[] }

One active playback session per user. Starting a song on another device should pause this tab (the server returns 409 PLAYBACK_TAKEN).

Endpoints

Action Method & Endpoint Description
Playlist GET /api/playlists/:id Tracks + metadata. Cacheable. Not the player.
Search GET /api/search?q=&cursor= Albums, playlists, tracks. Debounce the input ~200ms.
Start playback POST /api/playback/:trackId Returns PlaybackSession. 409 PLAYBACK_TAKEN if another device stole the slot — this tab pauses.
Progress PUT /api/progress/:trackId Body { sessionId, positionSec, updatedAt }. Heartbeat 30s + pause/seek/end.
Read queue GET /api/queue User’s current queue ids + index.
Write queue PUT /api/queue Body { trackIds, index }. Debounce reorders.
Offline license POST /api/licenses/offline If DRM downloads need a persistent license. Do not invent a key store on the client.

Example: Progress + Media Session


function bindProgress(audio: HTMLAudioElement, getCtx: () => { sessionId: string; trackId: string }) {
  let lastSent = 0;

  const flush = (useBeacon: boolean) => {
    const { sessionId, trackId } = getCtx();
    const body = JSON.stringify({
      sessionId,
      positionSec: audio.currentTime,
      updatedAt: new Date().toISOString(),
    });
    if (useBeacon && navigator.sendBeacon) {
      navigator.sendBeacon(`/api/progress/${trackId}`, body);
      return;
    }
    fetch(`/api/progress/${trackId}`, { method: "PUT", body, headers: { "Content-Type": "application/json" }, keepalive: true });
  };

  audio.addEventListener("timeupdate", () => {
    const now = Date.now();
    if (now - lastSent < 30_000) return;
    lastSent = now;
    flush(false);
  });

  audio.addEventListener("pause", () => flush(false));
  document.addEventListener("visibilitychange", () => {
    if (document.visibilityState === "hidden") flush(true);
  });
}

function bindMediaSession(track: Track, audio: HTMLAudioElement) {
  if (!navigator.mediaSession) return;
  navigator.mediaSession.metadata = new MediaMetadata({
    title: track.title,
    artist: track.artist,
    artwork: [{ src: track.artworkUrl, sizes: "300x300" }],
  });
  navigator.mediaSession.setActionHandler("play", () => audio.play());
  navigator.mediaSession.setActionHandler("pause", () => audio.pause());
  navigator.mediaSession.setActionHandler("nexttrack", () => player.next());
}

keepalive: true covers browsers where sendBeacon plus JSON is awkward. The 30s guard is the whole optimization.


Optimizations

  • Keep the player mounted. Lazy-load lyrics / queue UI, not the engine
  • Media Session API so lock-screen controls work on mobile
  • Throttle progress writes; sendBeacon on tab hide
  • Artwork via CDN srcset; the player bar image is tiny

The other half of “feels instant” is not fetching a 320kbps rendition on LTE. Pick a rendition when the session starts, and allow a mid-track switch at the next segment if the buffer starves.


function pickRendition(available: { kbps: number; id: string }[]) {
  const cell = navigator.connection && navigator.connection.effectiveType === "3g";
  const target = cell ? 96 : 160;
  return available.reduce((best, r) => {
    if (Math.abs(r.kbps - target) < Math.abs(best.kbps - target)) return r;
    return best;
  });
}

async function loadFirstSegment(trackId: string, renditionId: string) {
  const cacheKey = `/offline/${trackId}/${renditionId}/0`;
  const cached = await caches.match(cacheKey);
  if (cached) return cached.arrayBuffer();
  const res = await fetch(`/segments/${trackId}/${renditionId}/0`);
  return res.arrayBuffer();
}

Cache-first is what makes offline and repeat-listens cheap. The engine should not care whether the ArrayBuffer came from Cache Storage or the network — it just appends.


Handling User Edge Cases

Case Strategy
User clicks a playlist mid-song Router remounts the view. Player singleton is untouched. playFrom only runs if they hit play, not on navigation.
Another device starts playback Server 409 / push event. This tab pauses, keeps the queue, toasts “Playing on another device.”
Tab refresh GET queue + last progress. Do not autoplay until a gesture. Seek to resumeSec after the first segment.
Seek past buffered range Abort the current append, fetch the segment for that timestamp, show loading on the bar, then play.
Stall / dead cell Status stalled. Drop rendition at the next attempt. Do not spin a silent playhead.
Ended with repeat-one Seek to 0 and play. Do not POST a new session if the license is still valid.
Offline track missing a segment Fall back to network if online; otherwise skip with “Download incomplete.”
Autoplay blocked Stay paused at resumeSec. The big play button on the bar is the gesture.

Pro-Level Optimizations

Area Suggestion
React cost currentTime in a ref. Seek bar ticks at 250ms. Playlist never subscribes.
Start-up Fetch segment 0 first. POST playback in parallel with painting the bar.
Gapless Prefetch next segment 0 at t > duration − 10s. One <audio>, swap SourceBuffer.
Progress 30s heartbeat + pause/seek/end + beacon on hide. Never per timeupdate.
DRM EME license via licenseUrl. Persistent license only for offline. No keys in localStorage.
Mobile Media Session + audio.playsInline. Space pauses only when focus is not in an input.

Accessibility and Security

  • Space plays/pauses only when focus is not in an input
  • The seek bar is an <input type="range"> with an aria-valuetext like “1:21 of 3:30”
  • Signed manifest URLs; DRM for premium catalogs
  • Don’t store raw license keys in localStorage

Transport controls are real buttons with names (“Previous”, “Play”, “Next”). The seek bar’s aria-valuetext updates on the same 250ms tick as the visual fill, not on every audio clock fire. Queue reorder needs keyboard: Alt+Up / Alt+Down on the focused row, not drag-only.

Security is licenses and sessions. Manifest URLs are signed and short-lived; the player re-auths when they expire instead of hotlinking a CDN forever. EME holds keys in the CDM. Offline downloads are still licensed — a Cache Storage dump should not be a zip of raw AAC you can drag to Finder. One session per account: the new device wins, this tab pauses. Do not log manifestUrl or license payloads.


Conclusion: How to Design a Music Player

Spotify’s frontend is a shell with a singleton player. Everything else (browse, search, playlists) can remount. If the song stops when you click a playlist, the architecture is wrong.

The rest of a senior answer is about what that singleton does. It talks to a playback session API, feeds MSE from cache-or-network segments, keeps DRM keys out of your JS, and writes progress on a 30s heartbeat plus sendBeacon. The queue is in-memory ids with a debounced PUT. Time lives on a ref so a playing song does not reconcile the catalog tree four times a second.

Interviewers will forgive a missing crossfade. They will not forgive an <audio> inside a route, a progress PUT on every timeupdate, or a plan that downloads 4MB before the first note. Put the engine in the shell, stream the first segment, and keep React off the audio clock.