Coverage for downtify/apple_music.py: 94%

117 statements  

« prev     ^ index     » next       coverage.py v7.17.4, created at 2026-11-21 22:18 +0000

1"""Fetch artist bio/origin/formation data from Apple Music's internal 

2catalog API, keyed off ids resolved via the public iTunes Search API. 

3 

4``itunes.apple.com/search`` (see :mod:`downtify.itunes`) is public and 

5keyless, but its artist schema has no bio/origin field at all - only 

6``artistName``/``artistId``/``primaryGenreName`` (verified live). The 

7richer data (``artistBio``, ``origin``, ``bornOrFormed``, ``isGroup``, 

8hero artwork) only exists on Apple Music's *internal* web-player API, 

9``amp-api.music.apple.com``. 

10 

11That API needs a bearer token, but - same fragility class as Deezer's 

12anonymous GraphQL token (:mod:`downtify.deezer`) - it is **not** a 

13logged-in session: it's a fixed "developer token" Apple's own web player 

14embeds in its public JS bundle for itself, servable to any anonymous 

15visitor. :func:`_scrape_web_token` fetches ``music.apple.com``'s browse 

16page to find the current bundle URL, downloads that bundle, and regexes 

17the token out of it - no Apple ID, no credentials. Cached in memory until 

18its own ``exp`` claim is close, since it's long-lived (~70 days observed) 

19and the bundle can be several MB. 

20 

21Localization is not just an ``Accept-Language`` header - confirmed live 

22that header alone changes nothing. The catalog is split into per-country 

23"storefronts", each with its own fixed ``supportedLanguageTags`` list 

24(``GET /v1/storefronts`` enumerates them); the ``l=`` query parameter 

25must be one of *that storefront's* supported tags or the response 

26silently falls back to the storefront's default language instead of 

27erroring. :data:`_STOREFRONT_LANG` maps each of Downtify's UI locales to 

28a ``(storefront, tag)`` pair known to work, resolved by querying that 

29endpoint live - ``bg`` has no working pair (the ``bg`` storefront only 

30supports ``en-GB``), so it always falls back to English, same shape of 

31gap already documented for YouTube Music's own bio fallback. 

32""" 

33 

34from __future__ import annotations 

35 

36import base64 

37import json 

38import re 

39import time 

40from threading import Lock 

41from typing import Any, Optional 

42 

43import httpx 

44from loguru import logger 

45 

46from .file_naming import file_name_key 

47 

48_SEARCH_URL = 'https://itunes.apple.com/search' 

49_BROWSE_URL = 'https://music.apple.com/us/browse' 

50_CATALOG_URL = 'https://amp-api.music.apple.com/v1/catalog/{storefront}/artists/{artist_id}' 

51_TIMEOUT = 10 

52_BUNDLE_TIMEOUT = 20 

53 

54# The exact header segment of the token's JWT ({"typ":"JWT","alg":"ES256", 

55# "kid":"WebPlayKid"}, base64url-encoded) - matching on this specific, 

56# stable prefix instead of a generic "any JWT-looking string" pattern 

57# avoids picking up one of the bundle's *other* embedded tokens (it also 

58# ships a per-storefront one, `kid` different, not accepted here). 

59_TOKEN_HEADER = ( 

60 'eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IldlYlBsYXlLaWQifQ' 

61) 

62_TOKEN_RE = re.compile( 

63 re.escape(_TOKEN_HEADER) + r'\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+' 

64) 

65_BUNDLE_SRC_RE = re.compile(r'src="(/assets/index~[^"]+\.js)"') 

66 

67# (storefront, language tag) known to work for each Downtify UI locale - 

68# confirmed live against `GET /v1/storefronts/<id>` and by round-tripping 

69# an actual artist bio and checking the response `url` echoed `?l=<tag>` 

70# back (silent fallback otherwise). Not just the country's own top-level 

71# domain: e.g. Greek is served by the `gr` storefront, but Bulgarian 

72# genuinely isn't offered by Apple Music at all (`bg` storefront only 

73# supports `en-GB`) - no substitute exists, so it falls back to English. 

74_STOREFRONT_LANG: dict[str, tuple[str, str]] = { 

75 'en': ('us', 'en-US'), 

76 'pt-BR': ('br', 'pt-BR'), 

77 'es': ('es', 'es-ES'), 

78 'fr': ('fr', 'fr-FR'), 

79 'tr': ('tr', 'tr'), 

80 'hu': ('hu', 'hu'), 

81 'bg': ('bg', 'en-GB'), 

82 'el': ('gr', 'el'), 

83} 

84_DEFAULT_STOREFRONT_LANG = ('us', 'en-US') 

85 

86_token_cache: dict[str, Any] = {'token': '', 'exp': 0.0} 

87_token_lock = Lock() 

88 

89 

90def _decode_jwt_exp(token: str) -> float: 

91 try: 

92 payload_b64 = token.split('.')[1] 

93 padded = payload_b64 + '=' * (-len(payload_b64) % 4) 

94 payload = json.loads(base64.urlsafe_b64decode(padded)) 

95 return float(payload.get('exp') or 0) 

96 except Exception: 

97 return 0.0 

98 

99 

100def _scrape_web_token() -> str: 

101 """Pull the current public "web play" developer token straight out 

102 of ``music.apple.com``'s own JS bundle - see module docstring.""" 

103 

104 resp = httpx.get(_BROWSE_URL, timeout=_TIMEOUT, follow_redirects=True) 

105 resp.raise_for_status() 

106 match = _BUNDLE_SRC_RE.search(resp.text) 

107 if not match: 

108 raise ValueError('Could not find Apple Music web bundle') 

109 bundle_url = 'https://music.apple.com' + match.group(1) 

110 

111 bundle_resp = httpx.get(bundle_url, timeout=_BUNDLE_TIMEOUT) 

112 bundle_resp.raise_for_status() 

113 token_match = _TOKEN_RE.search(bundle_resp.text) 

114 if not token_match: 

115 raise ValueError('Could not find Apple Music web token in bundle') 

116 return token_match.group(0) 

117 

118 

119def _current_token() -> str: 

120 with _token_lock: 

121 if _token_cache['token'] and _token_cache['exp'] > time.time() + 60: 

122 return _token_cache['token'] 

123 token = _scrape_web_token() 

124 with _token_lock: 

125 _token_cache['token'] = token 

126 _token_cache['exp'] = _decode_jwt_exp(token) 

127 return token 

128 

129 

130def _search_artist_row(name: str) -> Optional[dict[str, Any]]: 

131 """The full iTunes Search API row for an exact name match - ignoring 

132 case and the characters a file name can't hold, so ``ACDC`` matches 

133 ``AC/DC`` (see :func:`downtify.file_naming.file_name_key`) - or 

134 ``None`` when the search answered and nothing matches. 

135 

136 Raises :class:`ValueError` when the search itself failed: that is not 

137 "no such artist", and a caller that saves what it finds must not treat 

138 it as one (see :func:`lookup_artist_id`). 

139 

140 Deliberately strict, same reasoning as 

141 :func:`downtify.deezer.resolve_artist_id`: an unrelated top result 

142 would silently attach the wrong artist's bio/origin. 

143 """ 

144 

145 text = name.strip() 

146 wanted = file_name_key(text) 

147 if not wanted: 

148 return None 

149 try: 

150 resp = httpx.get( 

151 _SEARCH_URL, 

152 params={'term': text, 'entity': 'musicArtist', 'limit': 25}, 

153 timeout=_TIMEOUT, 

154 ) 

155 resp.raise_for_status() 

156 data = resp.json() 

157 results = data.get('results') or [] 

158 except Exception as exc: 

159 logger.opt(exception=True).debug('Apple Music artist id lookup failed') 

160 raise ValueError('Could not reach Apple Music') from exc 

161 for row in results: 

162 if ( 

163 isinstance(row, dict) 

164 and file_name_key(str(row.get('artistName') or '')) == wanted 

165 ): 

166 return row 

167 return None 

168 

169 

170def _resolve_artist_row(name: str) -> Optional[dict[str, Any]]: 

171 """:func:`_search_artist_row`, with a failed search reading as no match 

172 (``None``) - for the callers where that is good enough. Shared by 

173 :func:`resolve_artist_id` (numeric id) and :func:`resolve_artist_slug_id` 

174 (``slug/numeric-id``, for ``platforms_id``), so both reuse the one search 

175 call/match loop instead of each doing their own.""" 

176 

177 try: 

178 return _search_artist_row(name) 

179 except ValueError: 

180 return None 

181 

182 

183def resolve_artist_id(name: str) -> Optional[str]: 

184 """Apple Music's numeric artist id for an exact name match on the 

185 public iTunes Search API (see :func:`_resolve_artist_row`), or ``None``. 

186 """ 

187 

188 row = _resolve_artist_row(name) 

189 if row is None: 

190 return None 

191 artist_id = row.get('artistId') 

192 return str(artist_id) if artist_id is not None else None 

193 

194 

195def lookup_artist_id(name: str) -> Optional[str]: 

196 """Like :func:`resolve_artist_id`, but a failed search raises 

197 :class:`ValueError` instead of reading as ``None``: ``None`` here really 

198 means Apple Music has no artist by that name.""" 

199 

200 row = _search_artist_row(name) 

201 if row is None: 

202 return None 

203 artist_id = row.get('artistId') 

204 return str(artist_id) if artist_id is not None else None 

205 

206 

207_ARTIST_LINK_SLUG_RE = re.compile(r'/artist/([^/?]+/\d+)') 

208 

209 

210def resolve_artist_slug_id(name: str) -> Optional[str]: 

211 """*name*'s ``slug/numeric-id`` form (e.g. ``'paramore/75950796'``) - 

212 the shape ``platforms_id.applemusic`` actually needs (see 

213 :func:`downtify.artist_profile._default_profile`) - parsed straight 

214 out of the matched search result's own ``artistLinkUrl``, no extra 

215 request needed (unlike :func:`fetch_artist_full`, which needs a full 

216 catalog fetch just to read this off its own ``url`` field - worth 

217 paying for a bio fetch, not just to resolve an id). 

218 

219 ``None`` if nothing matched, or the matched row's link isn't a 

220 ``music.apple.com`` artist page - the search API occasionally 

221 returns a same-named non-music result (an author, a book) even with 

222 ``entity=musicArtist``, confirmed live. 

223 """ 

224 

225 row = _resolve_artist_row(name) 

226 if row is None: 

227 return None 

228 link = str(row.get('artistLinkUrl') or '') 

229 if 'music.apple.com' not in link: 

230 return None 

231 match = _ARTIST_LINK_SLUG_RE.search(link) 

232 return match.group(1) if match else None 

233 

234 

235def fetch_artist_full(artist_id: str, lang: str) -> dict[str, Any]: 

236 """Bio, origin, formation year, genre and hero colour for an Apple Music 

237 artist id, localized to *lang* when a storefront supports it (see 

238 module docstring - falls back to that storefront's own default 

239 language rather than erroring). Raises :class:`ValueError` if the 

240 token can't be obtained or the request fails. 

241 """ 

242 

243 storefront, tag = _STOREFRONT_LANG.get(lang, _DEFAULT_STOREFRONT_LANG) 

244 try: 

245 token = _current_token() 

246 resp = httpx.get( 

247 _CATALOG_URL.format(storefront=storefront, artist_id=artist_id), 

248 params={ 

249 'extend': 'artistBio,bornOrFormed,origin,isGroup,hero', 

250 'l': tag, 

251 }, 

252 headers={ 

253 'Authorization': f'Bearer {token}', 

254 'Origin': 'https://music.apple.com', 

255 'Referer': 'https://music.apple.com/', 

256 }, 

257 timeout=_TIMEOUT, 

258 ) 

259 resp.raise_for_status() 

260 payload = resp.json() 

261 except Exception as exc: 

262 logger.opt(exception=True).debug( 

263 'Apple Music artist fetch failed for {}', artist_id 

264 ) 

265 raise ValueError( 

266 'Could not fetch artist info from Apple Music' 

267 ) from exc 

268 

269 rows = payload.get('data') or [] 

270 attrs = rows[0].get('attributes', {}) if rows else {} 

271 

272 hero_bg = '' 

273 hero = attrs.get('hero') or [] 

274 if hero: 

275 content = (hero[0] or {}).get('content') or [] 

276 if content: 

277 hero_bg = str( 

278 (content[0] or {}).get('artwork', {}).get('bgColor') or '' 

279 ) 

280 

281 url_match = re.search(r'/artist/([^/?]+/\d+)', str(attrs.get('url') or '')) 

282 # Always a single entry in practice (checked live across a dozen 

283 # artists), localized by the storefront's language like the bio is 

284 # ('Hard rock' / 'Alternativo' in pt-BR, 'Alternative' in en). 

285 genres = [g for g in attrs.get('genreNames') or [] if isinstance(g, str)] 

286 

287 return { 

288 'bio_html': str(attrs.get('artistBio') or ''), 

289 'origin': str(attrs.get('origin') or ''), 

290 'born_or_formed': str(attrs.get('bornOrFormed') or ''), 

291 'is_group': bool(attrs.get('isGroup')), 

292 'genre': genres[0].strip() if genres else '', 

293 'banner_bg_color': hero_bg, 

294 'applemusic_id': url_match.group(1) if url_match else '', 

295 }