bubblemix
🍬 An atproto-based social Instant Mix plugin for Navidrome bubblemix.cuducos.me
navidrome-plugin
Star
Fork
Watch
bubblemix CONTRIBUTING.md
2.7 kB · 62 lines
Markdown
at main

Contributing and self-hosting #

Requirements #

Running the backend #

$ just up

This starts Postgres and Qdrant on Docker Compose, builds the backend, and runs it listening on 127.0.0.1:8080.

To backfill into the database once, use docker compose run --rm -e BUBBLEMIX_JETSTREAM_API_KEY=<API key> bubblemix backfill (hosts that charge for archive replay require the key).

Every BUBBLEMIX_REBUILD_INTERVAL the backend recomputes the co-listen graph from all stored scrobbles and syncs one sparse vector per song (its normalized co-listen profile) into Qdrant, which serves the related-song queries with server-side MMR re-ranking.

Environment #

Variable Default Purpose
BUBBLEMIX_LISTEN_ADDR :8080 Listen address
BUBBLEMIX_DATABASE_URL postgres://bubblemix:bubblemix@127.0.0.1:5432/bubblemix Postgres connection string
BUBBLEMIX_QDRANT_URL http://127.0.0.1:6334 Qdrant gRPC endpoint
BUBBLEMIX_COLLECTION bubblemix Qdrant collection
BUBBLEMIX_JETSTREAM_URL wss://jetstream.us-west.bsky.network Jetstream host for the live tail
BUBBLEMIX_JETSTREAM_BACKFILL_URL same as live Jetstream host for the backfill
BUBBLEMIX_API_TOKEN — When set, requests need Authorization: Bearer <token>
BUBBLEMIX_REBUILD_INTERVAL 8h Interval between graph rebuilds
BUBBLEMIX_MAX_SONGS_PER_DID 512 Songs per listener considered when computing co-listen edges

API #

Route Returns
GET /health 200 while the process runs
GET /v1/related Songs people who listen to a song also listen to, re-ranked with MMR

/v1/related takes artist and title (or mbid and isrc), optional album, count (1–128, default 32), and diversity (0–1, default 0.8: how much results favor variety over pure similarity):

$ curl "localhost:8080/v1/related?artist=Chico%20Science&title=Da%20Lama%20ao%20Caos&count=3"

{
  "song": {"title": "Da Lama ao Caos", "artist": "Chico Science", "score": 0},
  "results": [
    {"title": "A Cidade", "artist": "Chico Science", "score": 0.83},
    {"title": "O Canto da Cidade", "artist": "Daniela Mercury", "score": 0.71}
  ],
  "count": 2
}

Reference implementations #

  • Docker Compose: the compose.yml works for production, but you might want to double-check how you want to persist data on your volumes (e.g. point them to a directory to make it easy to back up).
  • Kubernetes: you can copy what I have at my home lab.