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.