Skip to content

MusicBrainz metadata migration

scripts/musicbrainz_migrate.py scans a directory of MP3 files, matches each track against MusicBrainz, and writes canonical metadata (recording MBID, title, artist, album, year, and cover art) to the files. It reuses the py_musicbrainz client and the matching and tagging logic from the main package.

Usage

python scripts/musicbrainz_migrate.py --source DIR --user-agent "MyApp/1.0 (you@example.com)" [OPTIONS]

--source and --user-agent are required. Use a MusicBrainz-compliant user agent identifying your app and contact email.

Options

Option Description
--source DIR Directory to scan (required).
--user-agent STRING User-Agent for MusicBrainz (required).
--recursive Scan subdirectories.
--dry-run Preview changes without writing.
--overwrite Re-match files that already have an MBID.
--musicbrainz-url MusicBrainz API URL (default: https://musicbrainz.org).
--log-level LEVEL debug, info, warning, or error (default: info).

What it does per file

  1. Reads title/artist/album/year from the file's ID3 tags; falls back to parsing Artist - Title or Artist_Title from the filename.
  2. Skips files that already have a MusicBrainz ID, unless --overwrite is given, and skips files with no usable title and artist.
  3. Searches MusicBrainz by title and artist (title-only as a fallback) and picks the best match using the same scoring as the main app.
  4. Fetches cover art for the first release of the matched recording.
  5. Writes the canonical metadata and the MusicBrainz UFID, unless --dry-run.

Exit codes

Code Meaning
0 Success (no files failed).
1 Error (invalid args or missing source).
2 Partial success (some files failed).

Notes

  • The script is rate-limit-aware via the shared py_musicbrainz client.
  • A dry run is strongly recommended before the first real migration, e.g. --source /srv/music --recursive --dry-run.