Coverage for downtify/musicbrainz.py: 90%

167 statements  

« 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). 

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. 

8 

9How a watch uses it (``monitor._musicbrainz_releases``): 

10 

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""" 

28 

29from __future__ import annotations 

30 

31import re 

32import threading 

33import time 

34from typing import Any, Iterable, Optional 

35 

36import httpx 

37from loguru import logger 

38 

39from . import __version__ 

40from .album_artist import album_artist_fields 

41from .file_naming import file_name_key 

42 

43BASE = 'https://musicbrainz.org/ws/2/' 

44COVER_ART = 'https://coverartarchive.org/' 

45 

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 

51 

52_lock = threading.Lock() 

53_last_request = 0.0 

54 

55#: Primary types Artist Watch downloads (the watch's ``release_types``). 

56PRIMARY_TYPES = ('album', 'single', 'ep') 

57 

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') 

71 

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) 

74 

75 

76class MusicBrainzError(RuntimeError): 

77 """MusicBrainz couldn't answer (unreachable, busy, refused).""" 

78 

79 

80class NotFound(MusicBrainzError): 

81 """MusicBrainz has no such entity (a ``404``).""" 

82 

83 

84def _user_agent() -> str: 

85 return ( 

86 f'Downtify/{__version__} ' 

87 '( https://github.com/henriquesebastiao/downtify )' 

88 ) 

89 

90 

91def _get(path: str, **params: Any) -> dict[str, Any]: 

92 """A web service GET as JSON, at most one a second process-wide.""" 

93 

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') 

135 

136 

137# ── The artist ────────────────────────────────────────────────────────── 

138 

139 

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 ``''``.""" 

143 

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 '' 

155 

156 

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).""" 

160 

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 '' 

174 

175 

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.""" 

182 

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) 

193 

194 

195# ── Release groups ────────────────────────────────────────────────────── 

196 

197 

198def _credit(rows: Any) -> list[tuple[str, str, str]]: 

199 """An artist credit as ``(artist id, name, joinphrase)`` rows.""" 

200 

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 

214 

215 

216def credit_text(credit: list[tuple[str, str, str]]) -> str: 

217 """The credit as it is printed: "PARTYNEXTDOOR & Drake".""" 

218 

219 return ''.join(name + join for _id, name, join in credit).strip() 

220 

221 

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 } 

237 

238 

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}``. 

243 

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.""" 

248 

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 

265 

266 

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").""" 

271 

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 

278 

279 

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).""" 

283 

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} 

287 

288 

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).""" 

298 

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 ) 

304 

305 

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).""" 

309 

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 } 

324 

325 

326# ── One edition's tracks ──────────────────────────────────────────────── 

327 

328 

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 ) 

335 

336 

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.""" 

341 

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 ) 

354 

355 

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.""" 

360 

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 '' 

372 

373 

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 

428 

429 

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.""" 

437 

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)