unlistenbrainz

Overview

This project is a Python utility for cleaning up a ListenBrainz listening history by finding and deleting listens that match selected artists. It was built to make account cleanup faster, safer, and more manageable for large histories.

What the project does

The script reads a ListenBrainz username and token from environment variables, scans the user’s listen history through the API, and identifies matching listens using artist MBIDs or artist names. It then saves the matches to a JSON file, shows a preview, asks for confirmation, and deletes only the selected listens. It also includes retry logic for rate limits and connection issues, plus resume support for long scans.

Problem

ListenBrainz does not provide a simple bulk “delete by artist” workflow, so removing unwanted listens can be slow and repetitive. This becomes especially painful for users with large histories, imported duplicates, or bad scrobbles tied to a specific artist. Missing or incomplete metadata can also make matching difficult if you rely only on MBIDs.

Solution

The script automates the cleanup process by combining API scanning, flexible matching, and cautious deletion. It supports both exact MBID matching and artist-name fallback matching, which improves coverage when metadata is incomplete. To reduce risk, it lists all matches first, saves them for review, and requires confirmation before deleting anything.