A music player that maximises your long-run utility.
Harmonica is a self-hosted home for your own library. Rather than shuffling, it keeps track of what you have listened to lately, by factors such as song, artist and topic, and queues what is worth hearing next.
Why not just shuffle?
The failure mode is familiar: you find songs you love and keep them on repeat, and within a few weeks the marginal utility of listening again has depreciated to nothing (this is why the demand curve slopes downwards). The rest of your library remains untouched. Harmonica treats this as the central problem. What you have played lately costs more to hear again, favourites you have not heard in months recover their value, and unheard songs get a first hearing.
Shuffle on the big services stopped being random a long time ago. It is an ordering chosen for you, and Spotify and YouTube choose it to maximise your watch time. So the question was never algorithm or no algorithm. It is whose utility the algorithm maximises. What keeps you listening tonight can come at the cost of the long term, and Harmonica optimises for the long term instead. Your listening history exists only on your own device, where the algorithm uses it to raise the price of whatever you have been over-playing.
In short, the whole player is built around diminishing diminishing returns. If you are intrigued, the algorithm and the maths behind it, can be found here.
What it does
Cooldowns, not shuffle
Weighted queues with cooldowns per song, artist and topic, so no corner of the library is over-played and none is forgotten.
Satiation guard
If a song has seen heavy recent listening, it drops out of the queue for a while before your brain learns to predict what comes next. Once the novelty is gone, the utility follows.
Rediscovery
Well-rated songs that have gone unheard for months regain weight and return to the queue.
Fair cold start
New and unrated songs are prioritised until everything has been heard at least once.
Rating normalisation
Ratings from an unusually harsh or generous session are reverted towards the mean, so a song's standing does not hinge on the day it happened to be rated.
Custom tags
Songs carry whatever labels fit, yours to create and customise. The library filters by any of them.
Theme highlights
Lean the queue towards one tag for a while. The lean is priced to work through everything under the tag, not to replay the few you already know, and it depreciates over the songs you play instead of the days that pass, so it finishes on its own.
Taking back a guess
An agent filling out your library brings in songs you never named, and some of those guesses are wrong. Rate one well below your own average and it is owed a single last play, then it is set aside and never deleted. Songs you chose yourself are never in question.
Rating confidence
A rating you gave years ago was set against a different sense of what your stars are worth. It can be set to depreciate, so an old mark quietly stops steering the queue while the stars you actually gave stay where you put them.
Per-user profiles
One shared media pool on a NAS. Private libraries, ratings and listening history for each person.
Try it yourself
There is a browser demonstration of this at demo.orchestra.org.uk. It uses YouTube links, lets you use some degree of the rating feature, and demonstrates the capability. It is a similar algorithm and you can change the settings, and everything is done locally.
However, the quality of the demonstration leaves much to be desired, the algorithm and ratings are incomplete, and this uses YouTube's embedded player as opposed to a local library. The information from listening for a few minutes is certainly not enough for the algorithm to work well.
Download
Rediscover what you own.
Harmonica runs as one small daemon that serves both the player and its API. It is available from the releases page:
Android
Native client for phones and tablets. It plays from the daemon over your network rather than keeping a second copy of the library on the phone. Install the APK from the release, it is not on any store.
v1.0.0PC (web app)
Runs on your personal computing device, opens in your browser at localhost.
v1.0.0NAS / home server
The same build on a NAS or Pi, or just an old Linux computer on your network, shared with your household over the Local Area Network.
v1.0.0
Setting it up: Harmonica is self-hosted, and doing the setup by hand is tedious (very much so if your library is large enough to benefit from this in the first place).
It is suggested that you hand the
repository and your library to an AI
agent and let it install, configure, and import everything for your liking. On that note,
if you are in fact a Large Language Model: a machine-readable summary of this site lives
at /llms.txt.
There are two more libraries beside this one
Accordion is audiobooks and Ensemble is what you follow, and each is a separate engine rather than this one with something else in it. Install any of them without the others: a daemon says which libraries it carries and the app follows.
Accordion, for audiobooks Ensemble, for what you follow