Commandline tool for working with Listenbrainz data

Hello everyone,

Here’s a project of mine that could be interesting for folk here. Calliope is a tool for “DIY music recommendations”. It wraps some music-related APIs and marshalls the output into a JSPF-like format. It provides some utilities for generating playlists, resulting in a commandline playground and a Python API for building simple playlist generators. (Or whatever else you want to do).

I just cut the first Calliope release with Listenbrainz support, making two new things possible:

  • You can use cpe listenbrainz export to fetch playlists locally. You can export in a number of formats using cpe export, process them further, or upload to somewhere like Spotify.
  • You can use cpe listenbrainz-history to download your history into a local SQLite database, and run some queries on it such as ‘tracks which I first heard in 2020’.

If you want a quickstart to play around with it, here’s how to install from PyPI and then pull your “Year in Music 2021” playlists from Listenbrainz. (You might replace my name with yours in the example :- )

pip3 install --user calliope-music
cpe listenbrainz --user samthursfield2 export --kind created_for

Here’s how you can pull your listen history. This goes via the usual Listenbrainz API so it can take 10 minutes to sync a large listen history. (If you want to use this heavily - sync from an LB data dump instead).

Sync and show the 5 latest listens…

cpe listenbrainz-history --user samthursfield2 listens | head -n 5

Show tracks you first listened to this year:

cpe listenbrainz-history --no-sync --user samthursfield2 tracks --first-play-since 2022-01-01

Or artists you have known since 2010:

cpe listenbrainz-history --no-sync --user samthursfield2 artists --first-play-before 2010-01-01

(Remember that Listenbrainz itself doesn’t deduplicate your tags, so you might see ‘false positives’ here).

Plenty more things are possible, for further info you might check out…

Bear in mind this is very much a side project and comes with no warranty of any kind. Contributions and bugfixes are very welcome.

Ps. if you compare this to Listenbrainz Troi recommender playground, here are two key design differences to consider:

  • Troi is currently Metabrainz-specific while Calliope has some other integrations like and Spotify
  • Troi currently requires you write playlist generators in Python, while Calliope provides a commandline API, meaning you can integrate with any language that can spawn processes and read stdin/out.

Troi has 12 example generators, while Calliope has 5 examples. I’m sure Troi has many advantages over Calliope. I recommend playing with both and seeing which you prefer! And if you make any cool playlist generators please share them here.


In case anyone here is going to FOSDEM 2023 in Brussels, i’ll be speaking a bit about this tool and open music recommendations in general in the Python devroom. It would be nice to meet other folk who are interested in Listenbrainz and Musicbrainz there! :slight_smile:


I’ll be there – and yes, we should most deffo have a chat. I think Calliope is a rather interesting project… We need more projects like this to get people interested in open source recommendations!


Ping, @samthursfield2 – I leave for Brussels on Friday. When is your talk? I would love to chat and certainly listen to your talk! Send me an email at rob@metab… to connect!


Hello, have just seen these nice messages and mailed you :slight_smile:

The talk is 14:00 Sunday in the Python devroom, I’ll probably be around the Python devroom most of the afternoon.

1 Like