M4AForge v1.0.1

M4AForge v1.0.1

An update to v1.0.0. This release overhauls the metadata pipeline so all
providers contribute to a single merged record, fixes several scoring
and matching bugs, and cleans up the lyrics that get embedded into your
files.

---

⚡ Highlights

• Merged multi-provider pipeline. iTunes, MusicBrainz, Discogs, and
  Genius all contribute on every track. If Genius has the title and
  iTunes has the album, you get both — no more one provider winning
  outright and leaving gaps that other providers could have filled.
• Lyrics actually work now. Genius lyrics are validated (rejecting
  hits whose returned artist/title don't match the track), cleaned (no
  more 29 Contributors / Translations / Read More junk at the
  top), and embedded only when they're really for that song.
• Correct albums more often. Candidates whose album looks like a
  live set, compilation, promo, or film soundtrack are now penalized in
  scoring, so the canonical studio release wins the vote when both
  match.
• min_confidence default lowered from 0.72 to 0.60. With the
  merge step in place the spine is guaranteed to be the highest-scoring
  candidate, so the tighter gate was just rejecting good matches.

---

🔧 What's fixed

• MusicBrainz 503 responses were treated as permanent blocks and
  made the provider drop out for the rest of the track. 503 is
  transient overload — the retry ladder now backs off and retries.
• Discogs release-level results could win the vote with no title and
  no artist, writing an unrelated album name into the file. Those
  candidates are now scored 0.
• Genius sometimes returned lyrics for the wrong song (a cover, a
  translation, or an unrelated compilation with a similar name). The
  new lyrics-hit validator rejects anything whose artist/title don't
  match your track's metadata at ≥85%.
• Case-sensitive fuzzy matching rejected valid hits like
  twenty one pilots vs Twenty One Pilots. Comparisons are now
  case-insensitive.
• Floating-point threshold comparison — a score mathematically
  equal to the threshold was rejected by rounding. Uses a 1e-9 epsilon
  now.
• PIL.Image handle leak in artwork downloads fixed.
• KeyboardInterrupt in the worker pool now cancels pending
  futures immediately instead of waiting on in-flight network I/O.
• Bare except Exception in integrity.py and metadata.py
  replaced with except (MutagenError, OSError).
• ALTER TABLE … ADD COLUMN in db.py is now guarded by a
  whitelist.
• Rate limiter minimum sleep reduced from 10 ms to 1 ms.

---

⚠️ Known limitations

• album_artist is never populated — none of the four providers
  expose it. Everything else is filled in.
• Occasional compilation albums still win the vote for a handful of
  older tracks (e.g. some Dr. Dre, Coolio, Gloria Gaynor). The
  penalty list catches the obvious cases but not every compilation
  title.
• Some tracks get no lyrics — when Genius's top hit is a cover,
  translation, or unrelated song, the tool rejects it rather than embed
  the wrong lyrics. This is intentional; the file just ends up with
  lyrics=None.
• No CAPTCHA or anti-bot circumvention. A block from any provider
  is logged and the pipeline moves on.

M4AForge v1.0.0

Changelog

All notable changes to this project are documented in this file.
The format follows Keep a Changelog.

[1.0.0] — Initial public release

Added

• Multi-provider metadata lookup with automatic fallback: iTunes →
  MusicBrainz → Discogs → Genius, in a configurable per-run order.
• Interactive provider-selection prompt with per-provider status
  (ready / unavailable-and-why) and comma-separated ordering input.
  -y / --no-prompt skips it; the prompt auto-skips on non-TTY stdin.
• Smart filename cleaning: strips (Official Audio), [HD],
  (Live), (Remastered), feat./ft., leading track numbers.
• Extended tag support: title, artist, album, album artist, genre,
  year, track/disc number, composer, comment, copyright, explicit,
  compilation, artwork, lyrics.
• Confidence-scored candidate matching with duration cross-check
  and provider cross-validation; candidates below min_confidence
  are left untouched and reported to
  reports/uncertain_<run_id>.csv rather than guessed at.
• Local SQLite cache so re-runs don't re-hit provider APIs.
• Per-provider token-bucket rate limiter shared across worker threads.
• SHA256 integrity verification around every write.
• Pre-modification backup store with --restore (whole-run undo).
• Per-file checkpointing so an interrupted run resumes.
• Multi-threaded execution (--workers N) with rate limiting.
• Duplicate detection (checksum + optional metadata key).
• Album-level validation (missing/duplicate track numbers,
  inconsistent album names).
• CSV / JSON / HTML run reports.
• Plugin loader for custom MetadataProvider / LyricsProvider
  modules.
• Optional local LLM genre normalization via Ollama.
• Rich console UI: banner, live progress bar, summary tables,
  interactive review mode, automatic plain-text fallback.

Notes

• No provider attempts to circumvent CAPTCHAs or anti-bot blocks —
  a block is logged and the pipeline moves on.
• Scraped lyrics are intended for personal use, not redistribution.
• Automatic update checking is deliberately not implemented —
  it would imply phoning home to a version endpoint.