Genre tags are a blunt instrument. Two songs tagged "rock" can sound nothing alike, and two songs from completely different genres can flow into each other perfectly. If you've ever manually built a playlist by ear, skipping between folders trying to find the next song that "feels right" after the current one, you've already done the job Auto-DJ automates: finding songs that are acoustically similar, not just similarly labeled.
The problem
Manual curation and tag-based discovery both have the same blind spot: they rely on metadata (genre, mood, era) as a stand-in for how a song actually sounds. That's a lossy proxy. What actually makes two songs flow well together is closer to their acoustic fingerprint — timbre, texture, the shape of the sound itself — which tags don't capture directly.
How it's built
Auto-DJ works in three phases:
- Feature extraction — for every song in a local library, librosa extracts 13 MFCCs (Mel-frequency cepstral coefficients — a standard way of representing the timbre of audio) at a 22,050 Hz sample rate, averaged into a single fingerprint vector per song.
- Library management — the library is scanned recursively, fingerprints are persisted to a local JSON database so they don't need to be recomputed on every run, and a similarity matrix between every pair of songs is built using Euclidean distance between fingerprints.
- Playlist generation — an interactive CLI takes a seed song and a target length, then walks the similarity matrix to build a playlist of acoustically related tracks, exporting it as a standard M3U file any music player can open.
Each phase has its own test suite, and the whole thing runs locally against your own music collection — no streaming service, no cloud model, no data leaving your machine.
Why MFCCs
MFCCs were originally developed for speech recognition, but they turn out to be a solid general- purpose summary of a sound's timbral character — closer to "what does this actually sound like" than raw frequency data, and much more compact than the full waveform. Averaging 13 coefficients per song into one fingerprint vector is a deliberately simple representation, but it's enough to make Euclidean distance between songs a meaningful proxy for "these sound alike," which is exactly what a similarity-based playlist generator needs.
Try it
The code is on GitHub. Point it at your own music library and see what it pulls together from a seed song you like — it's a different kind of discovery than scrolling through genre playlists.