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
« 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.
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``.
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.
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"""
34from __future__ import annotations
36import base64
37import json
38import re
39import time
40from threading import Lock
41from typing import Any, Optional
43import httpx
44from loguru import logger
46from .file_naming import file_name_key
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
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)"')
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')
86_token_cache: dict[str, Any] = {'token': '', 'exp': 0.0}
87_token_lock = Lock()
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
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."""
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)
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)
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
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.
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`).
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 """
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
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."""
177 try:
178 return _search_artist_row(name)
179 except ValueError:
180 return None
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 """
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
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."""
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
207_ARTIST_LINK_SLUG_RE = re.compile(r'/artist/([^/?]+/\d+)')
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).
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 """
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
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 """
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
269 rows = payload.get('data') or []
270 attrs = rows[0].get('attributes', {}) if rows else {}
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 )
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)]
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 }