codetta 0.8.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. codetta/CHANGELOG.md +153 -0
  2. codetta/__init__.py +8 -0
  3. codetta/__main__.py +5 -0
  4. codetta/cli/__init__.py +0 -0
  5. codetta/cli/__main__.py +59 -0
  6. codetta/cli/run.py +129 -0
  7. codetta/core/__init__.py +0 -0
  8. codetta/core/acoustid.py +225 -0
  9. codetta/core/activity.py +161 -0
  10. codetta/core/artwork.py +238 -0
  11. codetta/core/auth.py +362 -0
  12. codetta/core/avatar.py +92 -0
  13. codetta/core/changelog.py +51 -0
  14. codetta/core/connections.py +159 -0
  15. codetta/core/describe.py +69 -0
  16. codetta/core/engine.py +470 -0
  17. codetta/core/health.py +520 -0
  18. codetta/core/inbox.py +195 -0
  19. codetta/core/index.py +672 -0
  20. codetta/core/library.py +177 -0
  21. codetta/core/musicbrainz.py +662 -0
  22. codetta/core/notifications.py +77 -0
  23. codetta/core/onboarding.py +39 -0
  24. codetta/core/organize.py +490 -0
  25. codetta/core/plugins.py +183 -0
  26. codetta/core/presets.py +452 -0
  27. codetta/core/providers.py +203 -0
  28. codetta/core/rawtags.py +135 -0
  29. codetta/core/slskd.py +650 -0
  30. codetta/core/tagmap.py +538 -0
  31. codetta/core/undo.py +186 -0
  32. codetta/core/updates.py +132 -0
  33. codetta/plugins/__init__.py +63 -0
  34. codetta/plugins/builtin/__init__.py +3 -0
  35. codetta/plugins/builtin/tidy.py +70 -0
  36. codetta/web/__init__.py +0 -0
  37. codetta/web/app.py +2909 -0
  38. codetta/web/security.py +170 -0
  39. codetta/web/static/app.css +2684 -0
  40. codetta/web/static/app.js +5694 -0
  41. codetta/web/static/apple-touch-icon.png +0 -0
  42. codetta/web/static/fonts/LICENSE-Inter.txt +93 -0
  43. codetta/web/static/fonts/LICENSE-SchibstedGrotesk.txt +93 -0
  44. codetta/web/static/fonts/inter-cyrillic.woff2 +0 -0
  45. codetta/web/static/fonts/schibsted-grotesk.woff2 +0 -0
  46. codetta/web/static/icon.svg +1 -0
  47. codetta/web/static/icons/codetta-dark.png +0 -0
  48. codetta/web/static/icons/codetta-dark.svg +1 -0
  49. codetta/web/static/icons/codetta-dark.webp +0 -0
  50. codetta/web/static/icons/codetta-light.png +0 -0
  51. codetta/web/static/icons/codetta-light.svg +1 -0
  52. codetta/web/static/icons/codetta-light.webp +0 -0
  53. codetta/web/static/icons/codetta.png +0 -0
  54. codetta/web/static/icons/codetta.svg +1 -0
  55. codetta/web/static/icons/codetta.webp +0 -0
  56. codetta/web/static/index.html +473 -0
  57. codetta/web/static/theme.js +12 -0
  58. codetta-0.8.1.dist-info/METADATA +282 -0
  59. codetta-0.8.1.dist-info/RECORD +63 -0
  60. codetta-0.8.1.dist-info/WHEEL +5 -0
  61. codetta-0.8.1.dist-info/entry_points.txt +2 -0
  62. codetta-0.8.1.dist-info/licenses/LICENSE +661 -0
  63. codetta-0.8.1.dist-info/top_level.txt +1 -0
@@ -0,0 +1,662 @@
1
+ """MusicBrainz: match an album folder to a release and propose its tags.
2
+
3
+ Like every provider this only *suggests*: it turns a MusicBrainz release into
4
+ "these files should get these values", and the web layer shows that as a
5
+ preview and writes it through ``MetadataEngine.update_tags()`` when asked.
6
+
7
+ The unit is the album: one folder of files <-> one MusicBrainz *release*
8
+ (a specific edition: "the 2011 UK CD"). Files are paired with the release's
9
+ tracks by disc and track number, then by title and length for the rest.
10
+
11
+ Tag names and values follow MusicBrainz Picard, which is what Navidrome and
12
+ most players expect (``musicbrainz_albumid``, ``releasetype`` = ``album``...).
13
+
14
+ MusicBrainz asks for at most one request per second and a User-Agent that
15
+ names the app; both are handled here. Cover art comes from the Cover Art
16
+ Archive. Data is CC0, so there are no licensing strings attached.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import difflib
22
+ import re
23
+ import threading
24
+ import time
25
+ import unicodedata
26
+ import urllib.parse
27
+ from collections import OrderedDict
28
+ from collections.abc import Callable
29
+ from dataclasses import dataclass, field
30
+
31
+ from codetta.core.providers import ProviderError
32
+
33
+ MB_BASE = "https://musicbrainz.org/ws/2"
34
+ CAA_BASE = "https://coverartarchive.org"
35
+ VARIOUS_ARTISTS = "89ad4ac3-39f7-470e-963a-56509c546377"
36
+ MAX_MB_BYTES = 8 * 1024 * 1024 # a big box set with full credits is a few MB
37
+ MAX_VALUE_CHARS = 2000
38
+
39
+ _MBID = r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
40
+ MBID_RE = re.compile(f"^{_MBID}$")
41
+
42
+ # Everything the review screen needs about a release, in one request.
43
+ RELEASE_INC = "+".join((
44
+ "artist-credits", "labels", "recordings", "release-groups", "media", "isrcs", "genres",
45
+ "artist-rels", "recording-level-rels", "work-rels", "work-level-rels",
46
+ ))
47
+
48
+ # MusicBrainz relationship type -> Codetta tag (as Picard maps them).
49
+ CREDIT_TYPES = {
50
+ "producer": "producer",
51
+ "engineer": "engineer", "audio": "engineer", "recording": "engineer", "sound": "engineer",
52
+ "mix": "mixer",
53
+ "mix-DJ": "djmixer",
54
+ "arranger": "arranger", "orchestrator": "arranger", "instrument arranger": "arranger",
55
+ "vocal arranger": "arranger", "instrumentator": "arranger",
56
+ "conductor": "conductor", "chorus master": "conductor",
57
+ "composer": "composer",
58
+ "lyricist": "lyricist", "librettist": "lyricist",
59
+ }
60
+
61
+ # How the review screen groups the fields. Genre is opinionated (community
62
+ # tags), so it starts unticked.
63
+ FIELD_GROUPS: tuple[tuple[str, str, tuple[str, ...]], ...] = (
64
+ ("basics", "Titles & numbering", ("title", "artist", "album", "albumartist", "tracknumber", "discnumber", "date")),
65
+ ("credits", "Credits", ("artists", "albumartists", "composer", "lyricist", "producer", "engineer",
66
+ "mixer", "djmixer", "arranger", "conductor")),
67
+ ("release", "Release details", ("originaldate", "releasetype", "releasestatus", "releasecountry", "label",
68
+ "catalognumber", "barcode", "media", "discsubtitle", "compilation", "script")),
69
+ ("sorting", "Sort names", ("artistsort", "albumartistsort")),
70
+ ("ids", "MusicBrainz IDs & ISRC", ("musicbrainz_albumid", "musicbrainz_releasegroupid", "musicbrainz_trackid",
71
+ "musicbrainz_releasetrackid", "musicbrainz_artistid",
72
+ "musicbrainz_albumartistid", "musicbrainz_workid", "isrc")),
73
+ ("genre", "Genre (community tags)", ("genre",)),
74
+ )
75
+ DEFAULT_OFF = frozenset({"genre"})
76
+ # Labels for fields the editor doesn't list (the rest come from tagmap.FIELDS).
77
+ ID_LABELS = {
78
+ "musicbrainz_albumid": "Release ID",
79
+ "musicbrainz_releasegroupid": "Release group ID",
80
+ "musicbrainz_trackid": "Recording ID",
81
+ "musicbrainz_releasetrackid": "Track ID",
82
+ "musicbrainz_artistid": "Artist IDs",
83
+ "musicbrainz_albumartistid": "Album artist IDs",
84
+ "musicbrainz_workid": "Work ID",
85
+ "script": "Script",
86
+ }
87
+ ALL_FIELDS = tuple(k for _, _, keys in FIELD_GROUPS for k in keys)
88
+
89
+
90
+ def default_fields() -> list[str]:
91
+ return [k for k in ALL_FIELDS if k not in DEFAULT_OFF]
92
+
93
+
94
+ def parse_release_id(text: str) -> str | None:
95
+ """A release MBID from a bare ID or a musicbrainz.org/release/<id> link."""
96
+ text = (text or "").strip().lower()
97
+ if MBID_RE.match(text):
98
+ return text
99
+ m = re.search(rf"musicbrainz\.org/(?:[a-z-]+/)?release/({_MBID})", text)
100
+ return m.group(1) if m else None
101
+
102
+
103
+ # --- Text helpers ---------------------------------------------------------------------
104
+
105
+
106
+ def _norm(text: str) -> str:
107
+ text = unicodedata.normalize("NFKD", text or "").casefold()
108
+ text = "".join(c for c in text if not unicodedata.combining(c))
109
+ text = text.replace("&", " and ")
110
+ return " ".join(re.sub(r"[^\w]+", " ", text).split())
111
+
112
+
113
+ def similarity(a: str, b: str) -> float:
114
+ """0..1, forgiving of case, accents, punctuation and "(Deluxe)" style extras."""
115
+ a, b = _norm(a), _norm(b)
116
+ if not a or not b:
117
+ return 0.0
118
+ if a == b:
119
+ return 1.0
120
+ ratio = difflib.SequenceMatcher(None, a, b).ratio()
121
+ if f" {a} " in f" {b} " or f" {b} " in f" {a} ":
122
+ ratio = max(ratio, 0.85)
123
+ return ratio
124
+
125
+
126
+ def _lucene(text: str) -> str:
127
+ """Escape a value for MusicBrainz's search syntax."""
128
+ return re.sub(r'([+\-!(){}\[\]^"~*?:\\/]|&&|\|\|)', r"\\\1", " ".join(text.split()))
129
+
130
+
131
+ def _clip(value: str) -> str:
132
+ return value[:MAX_VALUE_CHARS]
133
+
134
+
135
+ def _unique(values) -> list[str]:
136
+ return list(dict.fromkeys(_clip(v) for v in values if isinstance(v, str) and v.strip()))
137
+
138
+
139
+ def credit_string(credits: list | None, sort: bool = False) -> str:
140
+ out = []
141
+ for c in credits or []:
142
+ if not isinstance(c, dict):
143
+ continue
144
+ artist = c.get("artist") or {}
145
+ name = (artist.get("sort-name") if sort else None) or c.get("name") or artist.get("name") or ""
146
+ out.append(f"{name}{c.get('joinphrase') or ''}")
147
+ return _clip("".join(out).strip())
148
+
149
+
150
+ def credit_names(credits: list | None) -> list[str]:
151
+ return _unique(c.get("name") or (c.get("artist") or {}).get("name") for c in credits or [] if isinstance(c, dict))
152
+
153
+
154
+ def credit_ids(credits: list | None) -> list[str]:
155
+ ids = ((c.get("artist") or {}).get("id") for c in credits or [] if isinstance(c, dict))
156
+ return _unique(i for i in ids if isinstance(i, str) and MBID_RE.match(i))
157
+
158
+
159
+ # --- The client -------------------------------------------------------------------------
160
+
161
+ Fetcher = Callable[[str], object] # url -> parsed JSON, or None for 404
162
+
163
+
164
+ class MusicBrainz:
165
+ def __init__(self, fetch: Fetcher, base: str = MB_BASE, min_interval: float = 1.0,
166
+ clock: Callable[[], float] = time.monotonic, sleep: Callable[[float], None] = time.sleep) -> None:
167
+ self.fetch = fetch
168
+ self.base = base.rstrip("/")
169
+ self.min_interval = min_interval
170
+ self._clock, self._sleep = clock, sleep
171
+ self._rate_lock = threading.Lock()
172
+ self._last = -1e9
173
+ self._cache: OrderedDict[str, object] = OrderedDict()
174
+ self._cache_lock = threading.Lock()
175
+
176
+ def _get(self, path: str, params: dict[str, str]) -> object:
177
+ url = f"{self.base}/{path}?{urllib.parse.urlencode({**params, 'fmt': 'json'})}"
178
+ with self._cache_lock:
179
+ if url in self._cache:
180
+ self._cache.move_to_end(url)
181
+ return self._cache[url]
182
+ with self._rate_lock: # one request at a time, at most one per min_interval
183
+ for attempt in (1, 2):
184
+ wait = self._last + self.min_interval - self._clock()
185
+ if wait > 0:
186
+ self._sleep(wait)
187
+ try:
188
+ data = self.fetch(url)
189
+ break
190
+ except ProviderError as exc:
191
+ # "Busy" (503): MusicBrainz asks clients to slow down. Wait a little longer, try once more.
192
+ if attempt == 2 or "busy" not in str(exc).lower():
193
+ raise
194
+ self._sleep(1.5 * self.min_interval)
195
+ finally:
196
+ self._last = self._clock()
197
+ with self._cache_lock:
198
+ self._cache[url] = data
199
+ while len(self._cache) > 64:
200
+ self._cache.popitem(last=False)
201
+ return data
202
+
203
+ def search(self, album: str, artist: str = "", limit: int = 10) -> list[dict]:
204
+ album, artist = album.strip(), artist.strip()
205
+ if not album and not artist:
206
+ raise ProviderError("Type an album or artist to search for.")
207
+ parts = []
208
+ if album:
209
+ parts.append(f"release:({_lucene(album)})")
210
+ if artist:
211
+ parts.append(f"artist:({_lucene(artist)})")
212
+ data = self._get("release", {"query": " AND ".join(parts), "limit": str(limit)})
213
+ releases = data.get("releases") if isinstance(data, dict) else None
214
+ return [r for r in releases or [] if isinstance(r, dict) and MBID_RE.match(str(r.get("id", "")))]
215
+
216
+ def releases_by_id(self, ids: list[str]) -> list[dict]:
217
+ """Search-result summaries for up to 25 known releases, in one request."""
218
+ ids = [i for i in ids if MBID_RE.match(i)][:25]
219
+ if not ids:
220
+ return []
221
+ data = self._get("release", {"query": " OR ".join(f"reid:{i}" for i in ids), "limit": str(len(ids))})
222
+ releases = data.get("releases") if isinstance(data, dict) else None
223
+ return [r for r in releases or [] if isinstance(r, dict) and r.get("id") in ids]
224
+
225
+ def release(self, mbid: str) -> dict:
226
+ if not MBID_RE.match(mbid or ""):
227
+ raise ProviderError("That isn't a MusicBrainz release ID.")
228
+ data = self._get(f"release/{mbid}", {"inc": RELEASE_INC})
229
+ if data is None:
230
+ raise ProviderError("MusicBrainz doesn't have that release (it may have been merged or removed).")
231
+ if not isinstance(data, dict) or not isinstance(data.get("media"), list):
232
+ raise ProviderError("MusicBrainz sent a release Codetta couldn't read.")
233
+ return data
234
+
235
+
236
+ # --- Exploring (the !mb bang): artists and their releases, not tied to any files ---
237
+
238
+ def search_artists(self, text: str, limit: int = 8) -> list[dict]:
239
+ data = self._get("artist", {"query": _lucene(text), "limit": str(limit)})
240
+ items = data.get("artists") if isinstance(data, dict) else None
241
+ return [a for a in items or [] if isinstance(a, dict) and MBID_RE.match(str(a.get("id", "")))]
242
+
243
+ def search_release_groups(self, text: str, limit: int = 15) -> list[dict]:
244
+ data = self._get("release-group", {"query": _lucene(text), "limit": str(limit)})
245
+ items = data.get("release-groups") if isinstance(data, dict) else None
246
+ return [g for g in items or [] if isinstance(g, dict) and MBID_RE.match(str(g.get("id", "")))]
247
+
248
+ def artist(self, mbid: str) -> dict:
249
+ if not MBID_RE.match(mbid or ""):
250
+ raise ProviderError("That isn't a MusicBrainz artist ID.")
251
+ data = self._get(f"artist/{mbid}", {"inc": "url-rels+genres"})
252
+ if not isinstance(data, dict):
253
+ raise ProviderError("MusicBrainz doesn't have that artist.")
254
+ return data
255
+
256
+ def artist_release_groups(self, mbid: str) -> list[dict]:
257
+ """The artist's albums, EPs and singles (up to 100), oldest first."""
258
+ data = self._get("release-group", {"artist": mbid, "limit": "100", "type": "album|ep|single"})
259
+ items = data.get("release-groups") if isinstance(data, dict) else None
260
+ groups = [g for g in items or [] if isinstance(g, dict) and MBID_RE.match(str(g.get("id", "")))]
261
+ return sorted(groups, key=lambda g: (g.get("first-release-date") or "9999", g.get("title") or ""))
262
+
263
+ def release_group(self, mbid: str) -> dict:
264
+ if not MBID_RE.match(mbid or ""):
265
+ raise ProviderError("That isn't a MusicBrainz release group ID.")
266
+ data = self._get(f"release-group/{mbid}", {"inc": "releases+artist-credits+genres"})
267
+ if not isinstance(data, dict):
268
+ raise ProviderError("MusicBrainz doesn't have that release.")
269
+ return data
270
+
271
+ def release_tracks_summary(self, mbid: str) -> dict:
272
+ """A release with its tracklist and labels (lighter than ``release``)."""
273
+ if not MBID_RE.match(mbid or ""):
274
+ raise ProviderError("That isn't a MusicBrainz release ID.")
275
+ data = self._get(f"release/{mbid}", {"inc": "recordings+labels+artist-credits+media"})
276
+ if not isinstance(data, dict):
277
+ raise ProviderError("MusicBrainz doesn't have that release.")
278
+ return data
279
+
280
+
281
+ def cover_url(mbid: str, size: int | None = 1200, base: str = CAA_BASE, kind: str = "release") -> str:
282
+ if not MBID_RE.match(mbid or ""):
283
+ raise ProviderError("That isn't a MusicBrainz release ID.")
284
+ if kind not in ("release", "release-group"):
285
+ raise ProviderError("Unknown cover kind.")
286
+ return f"{base}/{kind}/{mbid}/front" + (f"-{size}" if size else "")
287
+
288
+
289
+ # --- Exploring: plain summaries for the page ------------------------------------------------
290
+
291
+ _SAFE_LINK = re.compile(r"^https?://[^\s<>\"']+$")
292
+ LINK_TYPES = {"official homepage": "Website", "wikipedia": "Wikipedia", "wikidata": "Wikidata",
293
+ "bandcamp": "Bandcamp", "discogs": "Discogs", "allmusic": "AllMusic", "last.fm": "Last.fm",
294
+ "soundcloud": "SoundCloud", "youtube": "YouTube", "streaming": "Streaming",
295
+ "free streaming": "Streaming", "social network": "Social"}
296
+
297
+
298
+ def _year(date: str | None) -> str:
299
+ return (date or "")[:4]
300
+
301
+
302
+ def artist_summary(a: dict) -> dict:
303
+ life = a.get("life-span") or {}
304
+ area = (a.get("area") or {}).get("name") or ""
305
+ return {"id": a.get("id"), "name": a.get("name") or "", "type": a.get("type") or "",
306
+ "country": a.get("country") or "", "area": area, "disambiguation": a.get("disambiguation") or "",
307
+ "begin": _year(life.get("begin")), "end": _year(life.get("end")), "ended": bool(life.get("ended")),
308
+ "score": a.get("score")}
309
+
310
+
311
+ def group_summary(g: dict) -> dict:
312
+ credit = g.get("artist-credit")
313
+ first = next((c.get("artist") or {} for c in credit or [] if isinstance(c, dict)), {})
314
+ return {"id": g.get("id"), "title": g.get("title") or "", "artist": credit_string(credit) if credit else "",
315
+ "artist_id": first.get("id") or "", "type": g.get("primary-type") or "",
316
+ "secondary": [t for t in g.get("secondary-types") or [] if isinstance(t, str)],
317
+ "year": _year(g.get("first-release-date")), "date": g.get("first-release-date") or "",
318
+ "score": g.get("score")}
319
+
320
+
321
+ def artist_links(a: dict) -> list[dict]:
322
+ out, seen = [], set()
323
+ for rel in a.get("relations") or []:
324
+ url = ((rel or {}).get("url") or {}).get("resource") or ""
325
+ label = LINK_TYPES.get((rel or {}).get("type") or "")
326
+ if label and _SAFE_LINK.match(url) and url not in seen:
327
+ seen.add(url)
328
+ out.append({"label": label, "url": url})
329
+ return out[:10]
330
+
331
+
332
+ def pick_release(group: dict) -> dict | None:
333
+ """The edition to show for a release group: the earliest official one."""
334
+ rels = [r for r in group.get("releases") or [] if isinstance(r, dict) and MBID_RE.match(str(r.get("id", "")))]
335
+ official = [r for r in rels if (r.get("status") or "").lower() == "official"] or rels
336
+ return min(official, key=lambda r: r.get("date") or "9999") if official else None
337
+
338
+
339
+ def tracklist(rel: dict) -> list[dict]:
340
+ out = []
341
+ discs = [m for m in rel.get("media") or [] if isinstance(m, dict)]
342
+ for disc_no, m in enumerate(discs, 1):
343
+ for t in m.get("tracks") or []:
344
+ if not isinstance(t, dict):
345
+ continue
346
+ length = t.get("length") or (t.get("recording") or {}).get("length")
347
+ out.append({"disc": disc_no, "discs": len(discs), "number": t.get("number") or str(t.get("position") or ""),
348
+ "title": t.get("title") or "", "length": round(length / 1000) if isinstance(length, int) else None,
349
+ "artist": credit_string(t.get("artist-credit")) if t.get("artist-credit") else ""})
350
+ return out
351
+
352
+
353
+ # --- Turning a release into something readable -------------------------------------------
354
+
355
+
356
+ def summarize(rel: dict) -> dict:
357
+ """The facts that tell two editions apart, for the candidate list."""
358
+ rg = rel.get("release-group") or {}
359
+ media = [m for m in rel.get("media") or [] if isinstance(m, dict)]
360
+ formats: OrderedDict[str, int] = OrderedDict()
361
+ for m in media:
362
+ fmt = m.get("format") or "Unknown format"
363
+ formats[fmt] = formats.get(fmt, 0) + 1
364
+ track_count = rel.get("track-count")
365
+ if not isinstance(track_count, int):
366
+ track_count = sum(m.get("track-count") or len(m.get("tracks") or []) for m in media)
367
+ labels = []
368
+ for li in rel.get("label-info") or []:
369
+ if not isinstance(li, dict):
370
+ continue
371
+ name = (li.get("label") or {}).get("name") or ""
372
+ cat = li.get("catalog-number") or ""
373
+ if cat == "[none]":
374
+ cat = ""
375
+ labels.append(" ".join(p for p in (name, cat and f"({cat})") if p))
376
+ types = [rg.get("primary-type")] + list(rg.get("secondary-types") or [])
377
+ caa = rel.get("cover-art-archive") or {}
378
+ return {
379
+ "id": rel.get("id"),
380
+ "title": rel.get("title") or "",
381
+ "artist": credit_string(rel.get("artist-credit")),
382
+ "disambiguation": rel.get("disambiguation") or "",
383
+ "date": rel.get("date") or "",
384
+ "country": rel.get("country") or "",
385
+ "status": rel.get("status") or "",
386
+ "type": " · ".join(t for t in types if t),
387
+ "labels": _unique(labels),
388
+ "barcode": rel.get("barcode") or "",
389
+ "formats": " + ".join(f"{n}×{f}" if n > 1 else f for f, n in formats.items()),
390
+ "track_count": track_count,
391
+ "disc_count": len(media) or None,
392
+ "mb_score": rel.get("score") if isinstance(rel.get("score"), int) else None,
393
+ # Search results don't say; a full lookup does. None = unknown, try anyway.
394
+ "has_cover": caa.get("front") if isinstance(caa.get("front"), bool) else None,
395
+ "url": f"https://musicbrainz.org/release/{rel.get('id')}",
396
+ }
397
+
398
+
399
+ @dataclass
400
+ class FileInfo:
401
+ """What Codetta knows about one file before matching."""
402
+
403
+ path: str
404
+ title: str = ""
405
+ artist: str = ""
406
+ album: str = ""
407
+ albumartist: str = ""
408
+ tracknumber: int | None = None
409
+ discnumber: int | None = None
410
+ duration: float | None = None
411
+ albumid: str = ""
412
+
413
+
414
+ def number(value: str | None) -> int | None:
415
+ """ "3/12" -> 3, "A2" -> None."""
416
+ m = re.match(r"^\s*(\d+)", value or "")
417
+ return int(m.group(1)) if m else None
418
+
419
+
420
+ def score_candidate(summary: dict, files: list[FileInfo], album: str, artist: str) -> int:
421
+ """0..100: how well a release fits these files and the search."""
422
+ n = len(files)
423
+ tracks = summary.get("track_count") or 0
424
+ if n and tracks:
425
+ count = 1.0 if tracks == n else max(0.0, 1 - abs(tracks - n) / max(n, tracks) * 2)
426
+ else:
427
+ count = 0.5
428
+ title = similarity(album, summary["title"]) if album else 0.5
429
+ who = similarity(artist, summary["artist"]) if artist else 0.5
430
+ mb = (summary.get("mb_score") or 50) / 100
431
+ score = 0.35 * title + 0.25 * who + 0.30 * count + 0.10 * mb
432
+ if summary.get("status") == "Official":
433
+ score += 0.02
434
+ return max(0, min(100, round(score * 100)))
435
+
436
+
437
+ # --- Tracks and pairing -------------------------------------------------------------------
438
+
439
+
440
+ @dataclass
441
+ class TrackRef:
442
+ id: str
443
+ disc: int
444
+ position: int
445
+ index: int # position across the whole release (1-based)
446
+ number: str # as printed ("A1" on vinyl)
447
+ title: str
448
+ artist: str
449
+ length: float | None # seconds
450
+ medium: dict = field(repr=False, default_factory=dict)
451
+ track: dict = field(repr=False, default_factory=dict)
452
+
453
+ def to_dict(self) -> dict:
454
+ return {"id": self.id, "disc": self.disc, "position": self.position, "number": self.number,
455
+ "title": self.title, "artist": self.artist, "length": self.length}
456
+
457
+
458
+ def release_tracks(rel: dict) -> list[TrackRef]:
459
+ out: list[TrackRef] = []
460
+ for mi, medium in enumerate(m for m in rel.get("media") or [] if isinstance(m, dict)):
461
+ disc = medium.get("position") if isinstance(medium.get("position"), int) else mi + 1
462
+ for ti, track in enumerate(t for t in medium.get("tracks") or [] if isinstance(t, dict)):
463
+ if not isinstance(track.get("id"), str):
464
+ continue
465
+ rec = track.get("recording") or {}
466
+ length = track.get("length") or rec.get("length")
467
+ out.append(TrackRef(
468
+ id=track["id"], disc=disc,
469
+ position=track.get("position") if isinstance(track.get("position"), int) else ti + 1,
470
+ index=len(out) + 1, number=str(track.get("number") or ""),
471
+ title=track.get("title") or rec.get("title") or "",
472
+ artist=credit_string(track.get("artist-credit") or rec.get("artist-credit")),
473
+ length=length / 1000 if isinstance(length, (int, float)) else None,
474
+ medium=medium, track=track,
475
+ ))
476
+ return out
477
+
478
+
479
+ @dataclass
480
+ class Pairing:
481
+ track: TrackRef | None
482
+ confidence: str # "high", "check" or "none"
483
+ notes: list[str] = field(default_factory=list)
484
+
485
+
486
+ def _fit_notes(f: FileInfo, t: TrackRef) -> tuple[float, list[str]]:
487
+ """How well a file fits a track by title and length (0..1), and what looks off."""
488
+ notes = []
489
+ title = similarity(f.title, t.title) if f.title else None
490
+ diff = abs(f.duration - t.length) if f.duration and t.length else None
491
+ if diff is not None and diff > 10:
492
+ notes.append(f"Length differs by {round(diff)} s")
493
+ if title is not None and title < 0.6:
494
+ notes.append(f"Title differs (file: “{f.title[:60]}”)")
495
+ parts = []
496
+ if title is not None:
497
+ parts.append((0.6, title))
498
+ if diff is not None:
499
+ parts.append((0.4, max(0.0, 1 - diff / 20)))
500
+ fit = sum(w * v for w, v in parts) / sum(w for w, _ in parts) if parts else 0.5
501
+ return fit, notes
502
+
503
+
504
+ def pair_files(files: list[FileInfo], tracks: list[TrackRef],
505
+ chosen: dict[str, str | None] | None = None,
506
+ recordings: dict[str, list[str]] | None = None) -> dict[str, Pairing]:
507
+ """Pair each file with a release track. ``chosen`` holds the user's own
508
+ picks (path -> track id, or None for "leave this file alone");
509
+ ``recordings`` what AcoustID heard in each file (path -> recording IDs)."""
510
+ chosen = chosen or {}
511
+ recordings = recordings or {}
512
+ by_id = {t.id: t for t in tracks}
513
+ discs = len({t.disc for t in tracks})
514
+ result: dict[str, Pairing] = {}
515
+ taken: set[str] = set()
516
+
517
+ for f in files: # 1. the user's picks
518
+ if f.path in chosen:
519
+ t = by_id.get(chosen[f.path] or "")
520
+ result[f.path] = Pairing(t, "high" if t else "none", _fit_notes(f, t)[1] if t else [])
521
+ if t:
522
+ taken.add(t.id)
523
+
524
+ for f in files: # 2. identified by sound: the track that is that recording
525
+ heard = recordings.get(f.path)
526
+ if f.path in result or not heard:
527
+ continue
528
+ options = [t for t in tracks if t.id not in taken and (t.track.get("recording") or {}).get("id") in heard]
529
+ if f.duration:
530
+ options.sort(key=lambda t: abs((t.length or f.duration) - f.duration))
531
+ if options:
532
+ t = options[0]
533
+ notes = [n for n in _fit_notes(f, t)[1] if n.startswith("Length")]
534
+ result[f.path] = Pairing(t, "high" if not notes else "check", notes)
535
+ taken.add(t.id)
536
+
537
+ for f in files: # 3. disc + track number, when the title/length don't contradict it
538
+ if f.path in result or f.tracknumber is None:
539
+ continue
540
+ if discs > 1 and f.discnumber is None:
541
+ # Multi-disc release, files numbered straight through (1..N).
542
+ t = next((t for t in tracks if t.index == f.tracknumber), None)
543
+ else:
544
+ disc = f.discnumber if discs > 1 else None
545
+ t = next((t for t in tracks if t.position == f.tracknumber and (disc is None or t.disc == disc)), None)
546
+ if t is None or t.id in taken:
547
+ continue
548
+ fit, notes = _fit_notes(f, t)
549
+ if fit < 0.35 and len(notes) == 2: # both title and length disagree: numbering is probably off
550
+ continue
551
+ if f.title and similarity(f.title, t.title) < 0.6 and any(
552
+ o.id not in taken and o is not t and similarity(f.title, o.title) >= 0.85 for o in tracks):
553
+ continue # the title clearly names another track: numbering is off, pair by title below
554
+ result[f.path] = Pairing(t, "high" if not notes else "check", notes)
555
+ taken.add(t.id)
556
+
557
+ # 4. everything else by title and length, best pairs first.
558
+ left_files = [f for f in files if f.path not in result]
559
+ left_tracks = [t for t in tracks if t.id not in taken]
560
+ scored = sorted(((_fit_notes(f, t)[0], fi, ti) for fi, f in enumerate(left_files)
561
+ for ti, t in enumerate(left_tracks)), reverse=True)
562
+ used_f, used_t = set(), set()
563
+ for fit, fi, ti in scored:
564
+ if fit < 0.55 or fi in used_f or ti in used_t:
565
+ continue
566
+ f, t = left_files[fi], left_tracks[ti]
567
+ notes = _fit_notes(f, t)[1]
568
+ result[f.path] = Pairing(t, "check", notes or ["Matched by title and length"])
569
+ used_f.add(fi)
570
+ used_t.add(ti)
571
+
572
+ for f in files:
573
+ result.setdefault(f.path, Pairing(None, "none", ["No matching track on this release"]))
574
+ return result
575
+
576
+
577
+ # --- Tags ---------------------------------------------------------------------------------
578
+
579
+
580
+ def _credits(relations: list | None) -> dict[str, list[str]]:
581
+ out: dict[str, list[str]] = {}
582
+ for r in relations or []:
583
+ if not isinstance(r, dict) or r.get("target-type") != "artist":
584
+ continue
585
+ key = CREDIT_TYPES.get(r.get("type") or "")
586
+ artist = r.get("artist") or {}
587
+ name = r.get("target-credit") or artist.get("name")
588
+ if key and name:
589
+ out.setdefault(key, []).append(name)
590
+ return out
591
+
592
+
593
+ def album_tags(rel: dict) -> dict[str, list[str]]:
594
+ rg = rel.get("release-group") or {}
595
+ credits = rel.get("artist-credit")
596
+ tags: dict[str, list[str]] = {
597
+ "album": [rel.get("title") or ""],
598
+ "albumartist": [credit_string(credits)],
599
+ "albumartists": credit_names(credits),
600
+ "albumartistsort": [credit_string(credits, sort=True)],
601
+ "musicbrainz_albumartistid": credit_ids(credits),
602
+ "musicbrainz_albumid": [rel.get("id") or ""],
603
+ "musicbrainz_releasegroupid": [rg.get("id") or ""],
604
+ "date": [rel.get("date") or ""],
605
+ "originaldate": [rg.get("first-release-date") or ""],
606
+ "releasetype": [t.lower() for t in [rg.get("primary-type")] + list(rg.get("secondary-types") or []) if t],
607
+ "releasestatus": [(rel.get("status") or "").lower()],
608
+ "releasecountry": [rel.get("country") or ""],
609
+ "barcode": [rel.get("barcode") or ""],
610
+ "script": [(rel.get("text-representation") or {}).get("script") or ""],
611
+ }
612
+ infos = [li for li in rel.get("label-info") or [] if isinstance(li, dict)]
613
+ tags["label"] = _unique((li.get("label") or {}).get("name") for li in infos)
614
+ tags["catalognumber"] = _unique(li.get("catalog-number") for li in infos if li.get("catalog-number") != "[none]")
615
+ if VARIOUS_ARTISTS in tags["musicbrainz_albumartistid"]:
616
+ tags["compilation"] = ["1"]
617
+ genres = [g for g in (rel.get("genres") or rg.get("genres") or []) if isinstance(g, dict) and g.get("name")]
618
+ genres.sort(key=lambda g: -(g.get("count") or 0))
619
+ tags["genre"] = _unique(g["name"].title() for g in genres[:3])
620
+ return tags
621
+
622
+
623
+ def track_tags(rel: dict, t: TrackRef, album: dict[str, list[str]] | None = None) -> dict[str, list[str]]:
624
+ """Every tag this release has for one track (empty values left out)."""
625
+ tags = dict(album if album is not None else album_tags(rel))
626
+ track, medium = t.track, t.medium
627
+ rec = track.get("recording") or {}
628
+ credits = track.get("artist-credit") or rec.get("artist-credit")
629
+ media_count = len([m for m in rel.get("media") or [] if isinstance(m, dict)])
630
+ track_count = medium.get("track-count") or len(medium.get("tracks") or [])
631
+ tags.update({
632
+ "title": [t.title],
633
+ "artist": [credit_string(credits)],
634
+ "artists": credit_names(credits),
635
+ "artistsort": [credit_string(credits, sort=True)],
636
+ "musicbrainz_artistid": credit_ids(credits),
637
+ "musicbrainz_trackid": [rec.get("id") or ""],
638
+ "musicbrainz_releasetrackid": [track.get("id") or ""],
639
+ "tracknumber": [f"{t.position}/{track_count}" if track_count else str(t.position)],
640
+ "discnumber": [f"{t.disc}/{media_count}" if media_count else str(t.disc)],
641
+ "media": [medium.get("format") or ""],
642
+ "discsubtitle": [medium.get("title") or ""],
643
+ "isrc": _unique(rec.get("isrcs") or []),
644
+ })
645
+ # Credits: the release's own (apply to every track), the recording's, and
646
+ # the composer/lyricist of the work it performs.
647
+ credit_map: dict[str, list[str]] = {}
648
+ for source in (_credits(rel.get("relations")), _credits(rec.get("relations"))):
649
+ for k, v in source.items():
650
+ credit_map.setdefault(k, []).extend(v)
651
+ work_ids = []
652
+ for r in rec.get("relations") or []:
653
+ if isinstance(r, dict) and r.get("target-type") == "work" and r.get("type") == "performance":
654
+ work = r.get("work") or {}
655
+ if isinstance(work.get("id"), str):
656
+ work_ids.append(work["id"])
657
+ for k, v in _credits(work.get("relations")).items():
658
+ credit_map.setdefault(k, []).extend(v)
659
+ for k, v in credit_map.items():
660
+ tags[k] = _unique(v)
661
+ tags["musicbrainz_workid"] = _unique(work_ids)
662
+ return {k: _unique(v) for k, v in tags.items() if _unique(v)}