From e61d57425e06610655d2e8dc8f76379d0831c80c Mon Sep 17 00:00:00 2001 From: Honey Date: Wed, 12 Aug 2026 01:51:54 +0200 Subject: [PATCH] =?UTF-8?q?docs(CLAUDE):=20document=20the=20single-track?= =?UTF-8?q?=20metadata=20resolver=20(Deezer=E2=86=92MusicBrainz=E2=86=92cl?= =?UTF-8?q?ean=20fallback)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- CLAUDE.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index d7b2ff4..d2b5f4c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -105,6 +105,17 @@ Backend runs in Docker (see `docker-compose.yml`); on the deploy host it lives a - **Duplicate detection** (`metadata.js findExistingTrack`): searches case-insensitively across all album folders under the matching artist folder; compares normalized artist+title ignoring track prefix and release/variant suffix. Handles DJ OKAWARI vs DJ Okawari and "- Single" drift. +- **Single-track metadata resolver = `backend/lib/trackmeta.js`** (Deezer → MusicBrainz → clean + fallback). Deezer's `pickTrackMatch` requires an **artist correspondence** (equal, or one name + contained in the other after stripping non-alphanumerics) — the old blind *title-only* fallback + grabbed a same-titled song by a different artist (e.g. "Memories" by Rab Noakes for "☆NoAki☆") and + applied its wrong album/cover/year. On no match it returns `{}`; then `musicbrainz.js` (rate-limited + ~1/s, `User-Agent` required, Cover Art Archive for covers, **same** artist discipline) is tried; if + that also misses, the download's built-in clean fallback runs (**album_artist = song artist, album = + "Singles", cover = source thumbnail, year/genre left untouched**). Only the three *single-track* + call sites use `trackmeta`; the album batch stays Deezer-only (avoids MB's rate limit). The clean + fallback always existed but was unreachable while the match was too greedy. Matching is unit-tested + (`deezer.test.js`, `musicbrainz.test.js`). - **Known limitation:** yt-dlp's YTM/YouTube *search* can't surface very obscure Art Tracks by ambiguously-named artists (e.g. "MINA") — the browser finds them, yt-dlp's API extraction doesn't (confirmed across params/clients/deno). For those, the **direct link in the importer**