Design a Music Streaming Service (Spotify)

Audio Streaming Architecture

Audio playback is CDN-backed with chunked HTTP range requests so that application API servers remain completely decoupled from the audio byte transfer path.

1. The client requests song metadata from the API server, which validates access and returns track metadata along with a CDN signed URL for the requested bitrate.
2. The client downloads audio chunks incrementally from the nearest CDN edge node using HTTP range requests rather than streaming a single monolithic file. The player begins decoding immediately upon receiving initial playable audio data and builds a steady-state buffer of 30 to 60 seconds ahead in the background.
3. Gapless playback: The client engine prefetches the initial 5 seconds of the subsequent track while the current song is finishing its final bars.
4. Crossfade transitions: The playback engine overlaps the trailing decibels of the current song with the rising audio curve of the next song based on user preferences.
5. Audio codec format: Tracks are pre-encoded in OGG Vorbis across four fixed bitrates (24, 96, 160, and 320 kbps) to support diverse network conditions.
6. Loudness normalization: ReplayGain metadata adjusts track gain client-side to ensure consistent perceived loudness across albums without re-encoding masters.

Music Catalog Service

The catalog service owns song, artist, and album metadata, serving a read-heavy workload that is aggressively cached across edge layers and in-memory stores.

• It maintains the authoritative master database for all songs, albums, artists, genres, and associated copyright metadata.
• Ingestion pipelines: Record labels and digital distributors submit tracks and metadata through automated batch ingestion workflows with format validation.
• Relational hierarchies: Models structured relationships linking songs to albums and artists, mapping tracks to multiple genres, and connecting remix or featured artist references.
• Database topology: MySQL cluster horizontally sharded by artist_id or song_id with multi-AZ read replicas to service high read concurrency.

Search Service (Elasticsearch)

The search service maintains an inverted index in Elasticsearch that is populated asynchronously from authoritative MySQL catalog writes via change data capture (CDC), providing fast full-text discovery with eventual consistency.

• Provides full-text search across tracks, artists, albums, user playlists, and podcast episodes.
• Query capabilities: Supports fuzzy matching (such as mapping "bettles" to "Beatles"), instantaneous prefix autocomplete, and did-you-mean spell correction.
• Indexed document fields: Indexes title, artist name, album name, genre, synchronized lyrics where available, and popularity scores.
• Search ranking function: Combines BM25 text relevance scores with global track popularity multipliers and recency decay curves.

Playlist Service

Playlists exhibit write-light and read-heavy access patterns, making them suitable for cache-aside architectures layered over distributed columnar storage.

• Personal playlists: Created and modified by individual users, stored partitioned by user and playlist identifiers in Cassandra.
• Collaborative playlists: Shared playlists where multiple authorized collaborators append, remove, and reorder songs using optimistic concurrency controls. Each playlist has an authoritative version field. Mutations route to the playlist's authoritative home write region: read version, submit mutation with expectedVersion, execute a conditional version update, apply positional track changes, and replicate asynchronously to follower read regions. When gaps in sparse position ordering (10, 20, 30) become exhausted, the service locally renumbers a bounded window of neighboring tracks.
• Algorithmic playlists: Dynamic collections generated by the recommendation engine, including Discover Weekly, Daily Mix, and Release Radar.

Recommendation Engine: Deep Dive

Recommendations are pre-computed offline and cached in memory so that machine learning inference never blocks the synchronous audio playback path.

Collaborative Filtering

The system analyzes collective user activity through both user-user filtering (identifying listeners with similar playback patterns) and item-item filtering (connecting tracks frequently co-listened across sessions). Alternating Least Squares (ALS) matrix factorization decomposes the sparse user-song interaction matrix into latent preference vectors.

Content-Based Filtering

Deep learning models analyze raw audio features including tempo, musical key, acoustic energy, danceability, and acousticness. These acoustic profiles combine with genre classifications and artist graph metadata to recommend acoustically similar tracks regardless of existing stream volume.

Production Recommendation Ensemble

The recommendation stack blends multiple algorithmic signals into a coherent candidate generation pipeline:

• Audio embeddings: Convolutional neural networks analyze raw spectrogram waveforms to generate 128-dimensional acoustic embedding vectors for new and cold-start tracks.
• Natural language processing on playlists: Word2Vec-style sequence models treat playlists as sentences and tracks as words to learn implicit contextual similarities.
• Knowledge graph traversal: Multi-hop graph networks capture relationships between artists, record labels, collaborators, and shared genres.
• Multi-armed bandit exploration: The system deliberately introduces unfamiliar tracks to balance exploitation of known user preferences with ongoing taste discovery.

Offline Apache Spark batch jobs pre-compute the top 100 candidate recommendations per user and populate Redis clusters, allowing client feed requests to be served in under 50 milliseconds.

Spotify Connect (Cross-Device Playback)

Cross-device playback handoff relies on a centralized session registry so that audio state transfers smoothly between hardware endpoints without re-buffering delays.

• Every connected device (mobile phone, desktop client, smart speaker, web player) maintains an active registration with the Device Session Service.
• The user interface renders an active device selector allowing the user to redirect audio streams dynamically across local and remote hardware.
• Transfer protocol: The controlling device issues a transfer command to the API Gateway, which notifies the target device over an open WebSocket or MQTT connection. The target device immediately resumes chunked streaming from the exact millisecond offset.
• Bidirectional control: Any authenticated client can act as a remote control, adjusting volume, scrub positions, and playback queues on the active hardware target.

Device Session Service

The device session service tracks all active hardware endpoints per account, coordinating real-time Connect transfers while enforcing concurrency boundaries.

• It maintains the active hardware state per account to distinguish between passive controllers and the single active streaming endpoint.
• Redis session store:
  • session:{user_id}:active stores the device_id of the hardware currently receiving and decoding audio bytes.
  • session:{user_id}:devices holds a Redis set containing JSON payloads for all discovered devices with their type, human-readable name, and last seen heartbeat timestamp.
• When playback transfers to a new device, the service updates the active key and dispatches an asynchronous notification to the destination hardware over MQTT or WebSocket.
• If a device fails to transmit a heartbeat for 60 seconds, a background reaper removes it from the discovered devices set.
• The service strictly enforces single-stream playback policies for standard accounts by validating the active key before issuing CDN range tokens to a new device.

Playback and Royalty Pipeline

Royalty accounting is processed asynchronously where playback events flow through distributed Kafka topics before feeding financial ledger systems.

The streaming pipeline tracks every listened second to power user analytics, billboard charts, and rights-holder royalty disbursements:

1. The client writes playback events to a local durable SQLite buffer on the device. An asynchronous background worker transmits periodic retryable reports to POST /api/v1/playback/report with an immutable event_id, track_id, duration_listened_ms, completion status, bitrate quality, device_id, and session_id. If a network request fails, the client retries with exponential backoff, ensuring network dropouts never silently lose royalty records. Live audio decoding remains completely asynchronous and decoupled from ingestion.
2. The API Gateway validates tokens, acknowledges the upload with an HTTP 202 status indicating pending processing (accepted: true, event_id: ..., processing_status: 'pending'), and produces the event to the Kafka topic playback-events, partitioned by user_id to maintain sequential FIFO ordering. The synchronous API intentionally does not declare royalty eligibility prior to asynchronous processing.
3. An Apache Flink stateful streaming job processes incoming event streams:
   • Deduplication and idempotency: Downstream processing is idempotent. Flink enforces authoritative idempotency using the immutable event_id to deduplicate retried uploads, while a secondary 5-minute sliding window on (user_id, track_id, session_id) suppresses duplicate beacons.
   • Duration validation: Enforces the industry standard rule requiring at least 30 continuous seconds of playback before qualifying an event as a payable stream.
   • Fraud filtering: Identifies and filters bot behavior including inhuman listening velocities exceeding 500 tracks per hour, zero-skip loops, and rapid repeat plays from unverified accounts.
   • Eligibility determination and enrichment: Once an event passes duration, deduplication, and fraud verification, Flink marks it as royalty-eligible, joins against catalog caches to append artist IDs and record label licensing terms, and emits to royalty-events.
4. Dedicated consumers of royalty-events distribute qualified records to PostgreSQL for daily track counts, ClickHouse for high-cardinality listening analytics, and the authoritative Royalty Ledger Database for financial auditing and payout settlement.
5. A monthly Apache Spark batch job executes pro-rata calculations across the platform revenue pool, distributing royalties to record labels, publishers, and performing artists according to contractual ownership splits.

Playback Event Bus (Kafka)

The event bus decouples event producers from consumers, buffering traffic spikes and establishing an immutable audit log for rights-holder reconciliation.

# Playback event bus topic specifications and consumer topology
topics:
  playback_events:
    name: "playback-events"
    partitions: 128
    partition_key: "user_id (guarantees per-user FIFO ordering)"
    retention: "7 days (immutable audit trail)"
    replication_factor: 3
    min_insync_replicas: 2
    producers:
      - "Playback Report Ingestion API (receives durable client uploads backed by local device buffer)"
    consumers:
      - name: "Flink royalty-aggregation"
        idempotency: "Authoritative idempotency deduplicates retried uploads using immutable event_id"
        deduplication: "Secondary (user_id, track_id, session_id) sliding window suppresses duplicate beacons"
        validation: "duration_listened_ms >= 30000 required for royalty qualification"
        fraud_filter: "Bot velocity tracking and repeat-loop detection"
        dead_letter_queue: "playback-events-dlq after 3 retries"
        lag_alert_threshold: "Consumer lag > 300 seconds triggers on-call alert"

  royalty_events:
    name: "royalty-events"
    partitions: 64
    partition_key: "artist_id"
    producers:
      - "Flink royalty-aggregation (emits only validated, fraud-cleared, royalty-qualified streams)"
    consumers:
      - "Royalty Ledger Database Writer"
      - "ClickHouse Listening Analytics"

  listen_history:
    name: "listen-history"
    partitions: 128
    partition_key: "user_id"
    producers:
      - "Playback Service (track start, skip, and completion events)"
    consumers:
      - "Cassandra listen_history Writer (writes to time-bucketed user partitions)"
      - "Spark Recommendation Batch Pipeline"

execution_paths:
  synchronous: "Client requests track metadata, receives signed CDN URL, and starts playback upon first playable audio (< 200 ms under normal networks)"
  asynchronous: "Client flushes durable playback events while the API responds with 202 Accepted ('pending'), and downstream Flink validates >=30s listens to emit qualified royalty events (2B daily streams, ~23K/sec)"