Heardle

Why I built it

Me and my friends really enjoy Songless but it only works with its own curated library. I wanted a version where we could paste any Spotify playlist and play with whatever we were listening to at the time with no setup, just paste a link and start guessing.

How it works

The user pastes any public Spotify playlist URL. The backend fetches all tracks using the Spotify Web API with Client Credentials flow, no user login required, any public playlist just works. A random track is selected, and the backend uses yt-dlp to search YouTube and download the first 16 seconds as an MP3.

The clip is cached by Spotify track ID so replays are instant. The frontend plays only a tiny portion, revealing more each time the player guesses wrong:

The guess input filters the playlist tracks client-side in real time, so no server round-trip is needed to check a guess.

What I learned

This was my first time integrating a third-party API that needed credentials. The Spotify Client Credentials flow where the app authenticates as itself rather than on behalf of a user. I kept it simple and meant anyone could use any public playlist without logging in to anything.

I also used type annotations properly for the first time on this project and ran mypy to check them. Catching type errors statically rather than at runtime made the code easier to debug and reason about. I've used the same approach on every project since.

Caching the audio clips was a lesson in noticing a real performance problem and fixing it. yt-dlp searches take a few seconds without caching, every replay of the same song would re-download from YouTube. Keying the cache by Spotify track ID made replays near-instant.