Harmonica♪

A music player built around diminishing diminishing returns.

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.

Download View source on GitHub

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. Recently played material is rested, neglected favourites recover their value, and unheard songs get a first hearing.

Spotify and YouTube are built to maximise your watch time, and what keeps you listening tonight can come at the cost of long-term utility. Harmonica does not maximise watch time. It is built for the long term instead. Your listening history exists only on your own device, where the algorithm uses it to rest whatever you have been over-playing.

For the curious: the full mechanics, with the maths, are on the algorithm page.

What it does

  • Cooldowns, not shuffle

    Weighted queues with cooldowns per song, artist and topic, so no corner of the library is worn out.

  • Satiation guard

    If a song has seen heavy recent listening, it is rested 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.

  • Per-user profiles

    One shared media pool on a NAS. Private libraries, ratings and listening history for each person.

Download

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.

    Coming soon

  • PC (web app)

    Runs on your personal computing device, opens in your browser at localhost.

    v1.0.0

  • NAS / 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.