Doc no. SK-404Rev 2026.09Sheet 2.3 of 4

music-tools

Cleans up a local music library: adds missing cover art from YouTube thumbnails and fixes songs MusicBrainz Picard tagged as the wrong track.

Source on GitHub $ music-tools art

Block diagram

Fig. 1 — Missing cover art signal path

Art sources	An image next to the song, then a YouTube video ID in the filename or tags, then a YouTube search on the tags, the filename and simplified versions of both
Matching	Exact word match only is applied automatically (`min_match = 1.0`), and one-word searches never are; otherwise you pick from the top results, paste a link, or skip
Filenames	Undoes yt-dlp's look-alike characters (⧸ ｜？) and macOS's decomposed Korean/Japanese names before searching
Tag fixer	Rebuilds Title/Artist/Album from the filename for songs Picard matched to the wrong release, keeps track numbers and removes the wrong MusicBrainz/AcoustID IDs. Preview only unless you pass `--apply`
Formats	mp3, m4a, flac, ogg, opus; `--convert-webm` copies a .webm's audio into .opus without re-encoding, checks the copy, then moves the original to the Trash
Safety	List and dry-run modes write nothing; Ctrl-C lets files being written finish; a corrupt or read-only file is reported and skipped; songs left without art are saved for `--retry`
Interface	Full-screen interactive menu (with a cat that listens along), direct subcommands, parallel workers with progress bars and a saved log of every run
Tests	26 unit tests, run on GitHub Actions