Coverage for downtify/musicbrainz.py: 90%
167 statements
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
1"""MusicBrainz: a watched artist's whole catalogue (issue #581, phase 2).
3MusicBrainz is the open music encyclopedia Lidarr is built on; its core
4data is CC0. Downtify reads its public web service directly, as its rules
5ask: at most one request a second (:data:`_INTERVAL`, shared by every
6caller in the process) and a User-Agent naming Downtify. A ``503`` means
7"slow down" and is retried after a pause.
9How a watch uses it (``monitor._musicbrainz_releases``):
11* :func:`artist_id_for` maps the watched artist to a MusicBrainz artist,
12 once: through the artist's Deezer or YouTube Music page (MusicBrainz
13 keeps links to both), else by name - only when exactly one artist of
14 exactly that name scores 100, so a common name never picks a stranger.
15* :func:`release_groups` lists the artist's release groups. A group is
16 one album, single or EP with all of its editions (*Views* has nine:
17 CD, digital, clean, explicit, hi-res...), typed like Lidarr's metadata
18 profiles: a primary type (Album, Single, EP...) and secondary types
19 (Mixtape/Street, Live, Compilation, Remix...).
20* :func:`wanted` keeps the artist's own groups (not the ones they are a
21 guest on) of the asked types; :data:`KINDS` are the secondary types a
22 user can let in.
23* :func:`release_group_tracks` picks one edition of a group
24 (:func:`_edition_rank`: official, explicit, the most tracks) and turns
25 its tracks into Downtify songs, with their ISRCs and a Cover Art
26 Archive cover when there is one.
27"""
29from __future__ import annotations
31import re
32import threading
33import time
34from typing import Any, Iterable, Optional
36import httpx
37from loguru import logger
39from . import __version__
40from .album_artist import album_artist_fields
41from .file_naming import file_name_key
43BASE = 'https://musicbrainz.org/ws/2/'
44COVER_ART = 'https://coverartarchive.org/'
46#: Seconds between two requests (MusicBrainz allows one a second).
47_INTERVAL = 1.1
48#: Tries of a request MusicBrainz answers with "slow down".
49_RETRIES = 4
50_TIMEOUT = 20
52_lock = threading.Lock()
53_last_request = 0.0
55#: Primary types Artist Watch downloads (the watch's ``release_types``).
56PRIMARY_TYPES = ('album', 'single', 'ep')
58#: Secondary types a user can let in, by setting name -> MusicBrainz's.
59KINDS = {
60 'mixtape': 'mixtape/street',
61 'soundtrack': 'soundtrack',
62 'live': 'live',
63 'compilation': 'compilation',
64 'remix': 'remix',
65 'dj-mix': 'dj-mix',
66 'demo': 'demo',
67}
68#: Let in by default: a mixtape or a soundtrack is the artist's own music;
69#: live albums, compilations, remixes, DJ mixes and demos repeat it.
70DEFAULT_KINDS = ('mixtape', 'soundtrack')
72# A joinphrase that makes the artists after it guests ("A feat. B").
73_GUEST = re.compile(r'\b(?:feat|ft|featuring|with)\b', re.IGNORECASE)
76class MusicBrainzError(RuntimeError):
77 """MusicBrainz couldn't answer (unreachable, busy, refused)."""
80class NotFound(MusicBrainzError):
81 """MusicBrainz has no such entity (a ``404``)."""
84def _user_agent() -> str:
85 return (
86 f'Downtify/{__version__} '
87 '( https://github.com/henriquesebastiao/downtify )'
88 )
91def _get(path: str, **params: Any) -> dict[str, Any]:
92 """A web service GET as JSON, at most one a second process-wide."""
94 global _last_request # noqa: PLW0603 # the shared request clock
95 params['fmt'] = 'json'
96 for attempt in range(_RETRIES):
97 with _lock:
98 wait = _INTERVAL - (time.monotonic() - _last_request)
99 if wait > 0:
100 time.sleep(wait)
101 try:
102 resp = httpx.get(
103 BASE + path,
104 params=params,
105 headers={
106 'User-Agent': _user_agent(),
107 'Accept': 'application/json',
108 },
109 timeout=_TIMEOUT,
110 )
111 except httpx.HTTPError as exc:
112 raise MusicBrainzError('Could not reach MusicBrainz') from exc
113 finally:
114 _last_request = time.monotonic()
115 if resp.status_code in {429, 503}:
116 logger.debug('MusicBrainz asked to slow down ({})', path)
117 time.sleep(_INTERVAL * 2 * (attempt + 1))
118 continue
119 if resp.status_code == 404:
120 raise NotFound(f'MusicBrainz has no {path}')
121 if resp.status_code >= 400:
122 raise MusicBrainzError(
123 f'MusicBrainz refused the request ({resp.status_code})'
124 )
125 try:
126 data = resp.json()
127 except ValueError as exc:
128 raise MusicBrainzError(
129 'MusicBrainz sent an unreadable answer'
130 ) from exc
131 if not isinstance(data, dict):
132 raise MusicBrainzError('MusicBrainz sent an unexpected answer')
133 return data
134 raise MusicBrainzError('MusicBrainz is busy; try again later')
137# ── The artist ──────────────────────────────────────────────────────────
140def _artist_by_url(resource: str) -> str:
141 """The one artist a page (``https://www.deezer.com/artist/…``) is
142 linked to in MusicBrainz, else ``''``."""
144 try:
145 data = _get('url', resource=resource, inc='artist-rels')
146 except NotFound:
147 return ''
148 found = {
149 str(rel['artist'].get('id') or '')
150 for rel in data.get('relations') or []
151 if isinstance(rel, dict) and isinstance(rel.get('artist'), dict)
152 }
153 found.discard('')
154 return found.pop() if len(found) == 1 else ''
157def _artist_by_name(name: str) -> str:
158 """The artist named exactly *name*, when only one such artist
159 matches fully; ``''`` otherwise (none, or an ambiguous name)."""
161 wanted = file_name_key(name)
162 if not wanted:
163 return ''
164 quoted = name.replace('\\', '\\\\').replace('"', '\\"')
165 data = _get('artist', query=f'artist:"{quoted}"', limit=10)
166 exact = [
167 str(artist.get('id') or '')
168 for artist in data.get('artists') or []
169 if isinstance(artist, dict)
170 and int(artist.get('score') or 0) == 100
171 and file_name_key(str(artist.get('name') or '')) == wanted
172 ]
173 return exact[0] if len(exact) == 1 and exact[0] else ''
176def artist_id_for(
177 name: str, *, deezer_id: str = '', channel_id: str = ''
178) -> str:
179 """The MusicBrainz artist of a watched artist: through their Deezer
180 page, then their YouTube Music channel, then by name. ``''`` when
181 none of these settles it."""
183 pages = []
184 if deezer_id:
185 pages.append(f'https://www.deezer.com/artist/{deezer_id}')
186 if channel_id:
187 pages.append(f'https://music.youtube.com/channel/{channel_id}')
188 for page in pages:
189 found = _artist_by_url(page)
190 if found:
191 return found
192 return _artist_by_name(name)
195# ── Release groups ──────────────────────────────────────────────────────
198def _credit(rows: Any) -> list[tuple[str, str, str]]:
199 """An artist credit as ``(artist id, name, joinphrase)`` rows."""
201 credit = []
202 for row in rows or []:
203 if not isinstance(row, dict):
204 continue
205 artist = (
206 row.get('artist') if isinstance(row.get('artist'), dict) else {}
207 )
208 credit.append((
209 str(artist.get('id') or ''),
210 str(row.get('name') or artist.get('name') or '').strip(),
211 str(row.get('joinphrase') or ''),
212 ))
213 return credit
216def credit_text(credit: list[tuple[str, str, str]]) -> str:
217 """The credit as it is printed: "PARTYNEXTDOOR & Drake"."""
219 return ''.join(name + join for _id, name, join in credit).strip()
222def _group(row: Any) -> Optional[dict[str, Any]]:
223 if not isinstance(row, dict) or not row.get('id') or not row.get('title'):
224 return None
225 return {
226 'id': str(row['id']),
227 'title': str(row['title']).strip(),
228 'primary': str(row.get('primary-type') or '').strip().lower(),
229 'secondary': [
230 str(kind).strip().lower()
231 for kind in row.get('secondary-types') or []
232 if kind
233 ],
234 'date': str(row.get('first-release-date') or ''),
235 'credit': _credit(row.get('artist-credit')),
236 }
239def release_groups(artist_id: str) -> list[dict[str, Any]]:
240 """Every release group MusicBrainz credits *artist_id* on (their own
241 and the ones they are a guest on - see :func:`credited`), as
242 ``{id, title, primary, secondary, date, credit}``.
244 Groups made only of bootlegs are left out (``website-default``, the
245 list MusicBrainz's own artist page shows): a big rapper has dozens
246 of fan-made "street" compilations of songs he already released -
247 Drake 24 of 37 mixtapes."""
249 groups: list[dict[str, Any]] = []
250 offset = 0
251 while True:
252 page = _get(
253 'release-group',
254 artist=artist_id,
255 inc='artist-credits',
256 limit=100,
257 offset=offset,
258 **{'release-group-status': 'website-default'},
259 )
260 rows = page.get('release-groups') or []
261 groups += [g for g in (_group(row) for row in rows) if g]
262 offset += len(rows)
263 if not rows or offset >= int(page.get('release-group-count') or 0):
264 return groups
267def credited(group: dict[str, Any], artist_id: str) -> bool:
268 """Whether a release group is the artist's own: credited to them, or
269 jointly ("PARTYNEXTDOOR & Drake"), not as a guest ("Rihanna feat.
270 Drake")."""
272 for artist, _name, join in group.get('credit') or []:
273 if artist == artist_id:
274 return True
275 if _GUEST.search(join):
276 return False
277 return False
280def kinds_from_setting(value: Any) -> set[str]:
281 """The MusicBrainz secondary types a setting lets in (a list of
282 :data:`KINDS` names; anything else is the default)."""
284 if not isinstance(value, (list, tuple)):
285 value = DEFAULT_KINDS
286 return {KINDS[str(v).lower()] for v in value if str(v).lower() in KINDS}
289def wanted(
290 group: dict[str, Any],
291 artist_id: str,
292 primary: Iterable[str],
293 kinds: set[str],
294) -> bool:
295 """A group Artist Watch downloads: the artist's own, of one of the
296 watch's *primary* types, and with only secondary types in *kinds*
297 (a remixed mixtape is out unless remixes are let in)."""
299 return (
300 group['primary'] in set(primary)
301 and all(kind in kinds for kind in group['secondary'])
302 and credited(group, artist_id)
303 )
306def release_summary(group: dict[str, Any]) -> dict[str, Any]:
307 """A release group as Artist Watch's release summary (the shape the
308 YouTube Music and Deezer discographies have)."""
310 return {
311 'album_id': group['id'],
312 'name': group['title'],
313 'artist': credit_text(group['credit']),
314 'year': group['date'][:4],
315 'release_date': group['date'],
316 'release_type': 'EP'
317 if group['primary'] == 'ep'
318 else group['primary'].title(),
319 'kinds': list(group['secondary']),
320 'cover_url': f'{COVER_ART}release-group/{group["id"]}/front-250',
321 'url': f'https://musicbrainz.org/release-group/{group["id"]}',
322 'source': 'musicbrainz',
323 }
326# ── One edition's tracks ────────────────────────────────────────────────
329def _track_count(release: dict[str, Any]) -> int:
330 return sum(
331 len(medium.get('tracks') or [])
332 for medium in release.get('media') or []
333 if isinstance(medium, dict)
334 )
337def _edition_rank(release: dict[str, Any]) -> tuple[Any, ...]:
338 """How good an official edition of a group is to download: not a
339 clean (edited) version, the most tracks (a deluxe edition holds the
340 standard one), digital, then the earliest."""
342 note = str(release.get('disambiguation') or '').casefold()
343 digits = re.sub(r'\D', '', str(release.get('date') or ''))
344 return (
345 not any(word in note for word in ('clean', 'edited', 'censored')),
346 _track_count(release),
347 any(
348 str(medium.get('format') or '') == 'Digital Media'
349 for medium in release.get('media') or []
350 if isinstance(medium, dict)
351 ),
352 -int((digits + '00000000')[:8]) if digits else -99999999,
353 )
356def _cover_url(release_id: str) -> str:
357 """The release's front cover on the Cover Art Archive (500 px), as
358 the image's own address - the archive redirects, and the cover
359 download doesn't follow redirects. ``''`` without one."""
361 try:
362 resp = httpx.head(
363 f'{COVER_ART}release/{release_id}/front-500',
364 headers={'User-Agent': _user_agent()},
365 follow_redirects=True,
366 timeout=_TIMEOUT,
367 )
368 except httpx.HTTPError:
369 logger.opt(exception=True).debug('Cover Art Archive unreachable')
370 return ''
371 return str(resp.url) if resp.status_code == 200 else ''
374def _songs(release: dict[str, Any], cover: str) -> list[dict[str, Any]]:
375 album_credit = _credit(release.get('artist-credit'))
376 album = str(release.get('title') or '').strip()
377 date = str(release.get('date') or '')
378 total = _track_count(release)
379 fields = album_artist_fields(
380 credit_text(album_credit),
381 artist_id=album_credit[0][0] if album_credit else '',
382 )
383 songs: list[dict[str, Any]] = []
384 number = 0
385 for medium in release.get('media') or []:
386 if not isinstance(medium, dict):
387 continue
388 for track in medium.get('tracks') or []:
389 if not isinstance(track, dict):
390 continue
391 number += 1
392 recording = (
393 track.get('recording')
394 if isinstance(track.get('recording'), dict)
395 else {}
396 )
397 credit = (
398 _credit(
399 track.get('artist-credit')
400 or recording.get('artist-credit')
401 )
402 or album_credit
403 )
404 title = str(track.get('title') or recording.get('title') or '')
405 if not recording.get('id') or not title.strip() or not credit:
406 continue
407 length = track.get('length') or recording.get('length') or 0
408 isrcs = [str(i) for i in recording.get('isrcs') or [] if i]
409 song = {
410 'song_id': f'mb-{recording["id"]}',
411 'name': title.strip(),
412 'artists': [name for _id, name, _join in credit if name],
413 'album_name': album,
414 'cover_url': cover,
415 'duration': round(int(length) / 1000) if length else 0,
416 'url': f'https://musicbrainz.org/recording/{recording["id"]}',
417 'year': date[:4],
418 'release_date': date,
419 'track_number': number,
420 'album_track_total': total,
421 'source': 'musicbrainz',
422 **fields,
423 }
424 if isrcs:
425 song['isrc'] = isrcs[0]
426 songs.append(song)
427 return songs
430def release_group_tracks(
431 group_id: str,
432) -> tuple[dict[str, Any], list[dict[str, Any]]]:
433 """``(edition, songs)`` for a release group: its best official
434 edition (:func:`_edition_rank`) and that edition's tracks as
435 Downtify songs, in order. ``({}, [])`` for a group with no official
436 edition - bootlegs, promos and fan uploads aren't downloaded."""
438 data = _get(
439 'release',
440 **{'release-group': group_id},
441 inc='recordings+artist-credits+isrcs+media',
442 limit=100,
443 )
444 releases = [
445 r
446 for r in data.get('releases') or []
447 if isinstance(r, dict) and r.get('status') == 'Official'
448 ]
449 if not releases:
450 return {}, []
451 edition = max(releases, key=_edition_rank)
452 cover = _cover_url(str(edition.get('id') or ''))
453 return edition, _songs(edition, cover)