01
Import
Paste any public Spotify playlist URL.
CASE STUDY · MUSIC PLATFORM
Singuessr
Singuessr is a dynamic music blind test platform built for fans of all genres. It combines two music APIs: the Spotify Web API (via a custom high-performance Cloudflare Worker proxy) provides playlist metadata and album cover art, while the Apple Music / iTunes Search API delivers the 30-second audio previews that drive each round. The hybrid serverless architecture handles regional API restrictions, high-concurrency recursive fetching, and cross-catalog track matching.
reactserverlessspotify-apiapple-music-api
THE PROBLEM
Traditional music blind tests are static, pre-defined, and limited in scope.
Built to solve the limitations of static music trivia. Singuessr uses Spotify as the source-of-truth for playlists and cover art (because that's where users curate their music), but routes audio playback through the public Apple Music / iTunes preview catalogue — which is globally reachable, unauthenticated, and free of OAuth complexity.
- Regional licensing blocks Spotify previews. Cloud servers get 403 errors from Spotify preview URLs for EU-region content — audio simply doesn't play for most users.
- Static blind tests get boring fast. Pre-defined song lists don't scale and quickly lose replay value after a few sessions.
- Large playlists are slow to load. Fetching 100+ tracks from Spotify's paginated API creates painful loading latency.
Music lovers & friend groups
Anyone who wants to run a real-time blind test on their own curated Spotify playlists
∞
playable playlists
<200ms
large playlist load
0
regional blocks
THE SOLUTION
the ultimate dynamic blind test.
A hybrid serverless architecture: React SPA for the UI and a Cloudflare Worker for the API proxy layer. The Worker handles Spotify OAuth2, recursive playlist flattening, and cross-catalog matching against the public iTunes Search API to resolve each track's Apple Music preview URL. The frontend manages the interactive audio loop and feeds the round queue directly from those preview URLs. Deployment is fully automated via Cloudflare's edge network.
02
Resolve
Edge worker flattens Spotify tracks and matches each to its Apple Music preview.
03
Play
Apple Music previews stream round by round, with cover art from Spotify.
04
Score
Fuzzy matching validates song title guesses.
in progress
Before
fragmented tools · high manual overhead
After
single unified product · fast & automated
KEY FEATURES
Built around how music lovers & friend groups actually work.
FEATURE 01
Cloudflare Worker Proxy
A lightweight Worker orchestrates two APIs: it hits Spotify for playlist data + album covers (with the right market headers to dodge regional blocks), then resolves every track to its Apple Music preview URL via iTunes Search.
- Resolves Spotify 403 regional blocks transparently to the client
- Cross-catalog matching against iTunes Search to find each preview URL
- Handles OAuth2 token flow and request orchestration at the edge
FEATURE 02
Recursive Playlist Flattening
A single fetch call recursively pages through all of Spotify's paginated endpoints, returning a flat track array — each enriched with its matched Apple Music preview — in one round-trip.
- Handles Spotify's 100-item page limit transparently
- Sub-200ms for large playlists via edge colocation
FEATURE 03
Audio Lifecycle Management
A custom state machine pre-fetches the next Apple Music preview buffer during active round play, eliminating perceived latency between game rounds.
- Zero-latency round transitions via background pre-fetch
- Race condition handling during fast-paced guessing sequences
TECHNICAL CHALLENGE
Hard problems solved.
The proxy uses a 'flatten-and-cache' strategy for Spotify playlist metadata (covers + titles + artists) and pipes each track into a parallel iTunes Search lookup that returns a 30-second Apple Music preview URL. Audio is then played in the React SPA via the HTML5 Audio API with a custom state machine that handles loading, playback, and race conditions during fast-paced guessing rounds.
What made it hard
- Architecting a Cloudflare Worker proxy to bypass CORS restrictions and regional licensing locks when fetching Spotify playlist data (injecting market=FR headers and handling OAuth2 token refresh at the edge).
- Matching every Spotify track to its Apple Music / iTunes preview equivalent across two independent catalogues, with fuzzy normalization to cope with naming inconsistencies between providers.
- Implementing recursive API fetching to flatten large Spotify playlists (100+ tracks) into a single, high-speed JSON payload for the frontend.
- Developing a 'fuzzy' scoring algorithm that normalizes song titles, stripping metadata like '- Remastered' or '(Bonus Track)' to ensure fair guessing.
- Optimizing the media lifecycle in React to pre-fetch upcoming Apple Music audio buffers, ensuring a zero-latency transition between game rounds.
architecture.ts
1 const frontend = [ "React", "Tailwind CSS", "HTML5 Audio API" ];
2 const edge_/_backend = [ "Cloudflare Workers", "Spotify Web API", "Apple Music / iTunes Search API" ];
3 const algorithms = [ "Regex normalization", "Cross-catalog matching", "Fuzzy matching", "State machine" ];
4 const monetization = [ "A-Ads (privacy-first)" ];
THE STACK
Technologies used.
Frontend
ReactTailwind CSSHTML5 Audio API
Edge / Backend
Cloudflare WorkersSpotify Web APIApple Music / iTunes Search API
Algorithms
Regex normalizationCross-catalog matchingFuzzy matchingState machine
Monetization
A-Ads (privacy-first)
WHAT THIS PROVES
What Singuessr demonstrates.
Serverless architecture
Designed and shipped a Cloudflare Worker that proxies and orchestrates two music APIs at the edge.
Regional restriction bypass
Combined Spotify (playlists + cover art) with Apple Music (globally reachable previews) so audio plays for every user, regardless of region.
Performance engineering
Achieved sub-200ms large playlist loading by collocating data flattening and cross-catalog matching at the CDN edge.
Media state machine
Built a robust audio lifecycle manager that handles pre-fetching and race conditions in a fast-paced game context.
WORK WITH ME
Want to build something like this?
Bring me your idea or half-built project. We'll scope it, design it and ship it — using the same workflow behind Singuessr.