A set of Python tools that clean up a large local music library by finding and embedding missing album art into MP3 ID3 tags. It started as a one-off script and grew into a resumable batch processor and a desktop picker with image previews, built around the iTunes Search API and the Mutagen tagging library.
Recursively scan the library and read artist and album tags from each MP3
Group tracks into albums using normalized keys, so one lookup covers a whole album
Search iTunes with progressively looser queries and fetch 1000×1000 artwork
Embed the cover as an APIC frame in every track and checkpoint progress
Walks an entire library, skips albums that already have art, and embeds the top iTunes match for the rest. Writes a report of albums that were not found and files with missing tags. Progress is saved after every album, so a stopped run resumes where it left off.
A Tkinter GUI that shows each album's candidate covers with resolution and file size, and lets me accept, step to the next candidate, run a custom search, browse for a local image, or skip. Network calls run on worker threads that report back through a queue, so the window stays responsive. An option lets me re-review albums that already have art.
For fixing one album at a time. Derives a search query from the first track's tags (falling back to the folder name), opens each candidate in the system image viewer, and prompts to accept, skip, search again, or supply a file by hand.
The original minimal version: point it at an album folder and an image file, and it embeds that image into every MP3 in the folder. Still the quickest option when I already have the exact cover I want.
Regex cleaning strips bracketed text, "Disc N" suffixes, and featured or secondary artists before building a case-folded artist and album key. Deluxe editions, multi-disc sets, and collaborations group correctly, and untagged files fall back to grouping by parent folder.
Requests are throttled with random jitter, and artwork downloads use a shorter interval than API searches. Repeated 403 responses trip an escalating circuit breaker (2, 5, 15, then 30 minute cooldowns), and 429 or 503 responses trigger backoff. Albums that fail on network errors are left unresolved so the next run retries them, while genuine misses are recorded separately.
Each album is searched as artist plus title first, then with the subtitle after a colon removed, then by title alone. This recovers matches that a strict query would miss.
Existing APIC frames are replaced rather than duplicated, MIME type is detected from the image bytes, and files with no ID3 header get a fresh tag. Files are read for existing art before any network request is made.