SK-404

Doc no. SK-404DatasheetRev 2026.11Sheet 2.14 of 4

U2

music-tools

Cleans up a local music library: fills in missing cover art and artist pictures, finds lyrics, fixes tags MusicBrainz Picard got wrong, and tidies duplicates and folders.

Shipped

01

Block diagram

Songno cover art Normalize⧸ | ? · NFC Lookupfile · ID · search Matchexact words Embed artMutagen · Pillow else: you pick → failures saved for --retry
Fig. 1: Missing cover art signal path
02

Characteristics

Toolkitcovers, artists, lyrics, fix (tags), dupes, tidy (with undo), organize and check, plus auto to look at your library and run the steps you pick in order. Every tool previews before it changes anything
Art sourcesAn 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
MatchingExact 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
FilenamesUndoes yt-dlp's look-alike characters (⧸ | ?) and macOS's decomposed Korean/Japanese names before searching
Tag fixerRebuilds 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
Formatsmp3, 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 (macOS only; elsewhere it is kept)
SafetyList 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
InterfaceFull-screen interactive menu (with a cat that listens along), direct subcommands, parallel workers with progress bars and a saved log of every run
Tests391 unit tests, run on GitHub Actions on Linux, macOS and Windows
  • Python
  • yt-dlp
  • Mutagen
  • Pillow
  • tqdm
03

Overview & build notes

Built around the real quirks of large mixed local libraries, especially tracks pulled via yt-dlp where full-width lookalike slashes (⧸) or NFD-decomposed CJK filenames trip up ordinary taggers.

Every subcommand previews changes before touching audio tags or filenames, writes reversible manifests (mt undo) for folder reorganisations and saves unresolved tracks to retry cleanly later. Auto-matching requires exact word overlap (min_match = 1.0) so ambiguous tracks are always handed to you to confirm.

Shared library paths and thresholds live in one config.example.toml-derived configuration file, tested across macOS, Linux and Windows with 391 pytest unit tests.

04

Files & artifacts

KindFileDetailsSize
Sourceinteractive.pyFull-screen menu interface, library scanner and workflow runner on GitHubGitHub
Sourcefix_album_art.pyCover art lookup, YouTube ID extraction and Mutagen/Pillow embedderGitHub
Sourcefind_lyrics.pySynced .lrc fetcher with lrclib lookup on GitHubGitHub
Configconfig.example.tomlAnnotated configuration template for library paths and matching rulesGitHub

U8Music Visualiser