Coverage for downtify/providers.py: 90%

1479 statements  

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

1"""Audio search/match helpers: YouTube Music, YouTube and SoundCloud.""" 

2 

3from __future__ import annotations 

4 

5import json 

6import os 

7import re 

8import time 

9import zlib 

10from collections.abc import Iterable, Iterator 

11from concurrent.futures import ThreadPoolExecutor 

12from contextlib import contextmanager 

13from contextvars import ContextVar 

14from datetime import datetime, timezone 

15from difflib import SequenceMatcher 

16from threading import Lock 

17from typing import Any, Optional 

18from urllib.parse import quote, unquote, urlparse 

19 

20import yt_dlp 

21from loguru import logger 

22from ytmusicapi import YTMusic 

23from ytmusicapi.continuations import ( 

24 get_continuations, 

25 get_reloadable_continuation_params, 

26) 

27from ytmusicapi.navigation import ( 

28 CONTENT, 

29 GRID, 

30 GRID_ITEMS, 

31 HEADER_SIDE, 

32 MULTI_SELECT, 

33 SECTION, 

34 SECTION_LIST_CONTINUATION, 

35 SECTION_LIST_ITEM, 

36 SINGLE_COLUMN_TAB, 

37 TITLE_TEXT, 

38 nav, 

39) 

40from ytmusicapi.parsers.library import parse_albums as _parse_ytm_albums 

41 

42from .album_artist import album_artist_fields, is_act_of 

43from .file_naming import file_name_key 

44from .proxy_config import requests_proxies_for_youtube_music 

45from .telemetry import json_log_blob, redact_sensitive_mapping 

46 

47 

48def _log_ytm_response(label: str, payload: Any) -> None: 

49 """Full YT Music payloads (truncated); enable DEBUG level to inspect.""" 

50 

51 logger.debug( 

52 'YouTube Music response {} {} chars: {}', 

53 label, 

54 len(json.dumps(payload, default=str)), 

55 json_log_blob(redact_sensitive_mapping(payload)), 

56 ) 

57 

58 

59def _log_ytm_summary_search( 

60 *, 

61 phase: str, 

62 query: str, 

63 filt: str, 

64 results_len: int, 

65 first_titles: list[str], 

66) -> None: 

67 logger.info( 

68 'YouTube Music search [{}] filter={!r} q={!r} hits={} first_titles={}', 

69 phase, 

70 filt, 

71 query[:120], 

72 results_len, 

73 first_titles, 

74 ) 

75 

76 

77_client: Optional[YTMusic] = None 

78_lock = Lock() 

79# Parsed ``get_album`` payload per browse id — avoids N identical API calls when 

80# downloading every track off the same LP. 

81_album_track_cache: dict[ 

82 str, 

83 tuple[list[dict[str, Any]], Optional[int]], 

84] = {} 

85# Album-level metadata (title/year/thumbnails) per browse id, populated 

86# alongside ``_album_track_cache`` from the same ``get_album`` call. 

87_album_meta_cache: dict[str, dict[str, Any]] = {} 

88# ``artist|album`` (case-folded hints) → album ``browseId`` from a songs filter. 

89_album_browse_search_cache: dict[str, str] = {} 

90# Artist names per album browse id, captured from an albums-filter search 

91# result (``search_albums``) — used as a fallback for the album artist tag 

92# when the later ``get_album`` call for the same browse id doesn't itself 

93# return an ``artists`` field. 

94_album_search_artist_cache: dict[str, list[str]] = {} 

95# Official-audio (ATV) preference result per original (OMV) video id. 

96# ``album_tracks_from_browse_id`` gets called several times over for the 

97# same album across a single download (once per caller resolving the 

98# tracklist for display, once more when the download itself resolves it 

99# server-side) even though the raw album payload is already cached above — 

100# without this, every one of those calls reruns a live YouTube Music search 

101# per music-video track, which is most of what makes an album "slow to 

102# start" downloading. 

103_omv_preference_cache: dict[str, tuple[str, int]] = {} 

104# Artist channel id -> the channel's own name. 

105_artist_channel_name_cache: dict[str, str] = {} 

106# Artist channel id -> when reading its name last failed (monotonic): it is 

107# tried again after _CHANNEL_NAME_RETRY_SECONDS, not on every credit. 

108_artist_channel_name_failed: dict[str, float] = {} 

109_CHANNEL_NAME_RETRY_SECONDS = 600 

110# How many artist channels a playlist reads at once (see 

111# _prefetch_artist_channel_names). 

112_CHANNEL_NAME_WORKERS = 4 

113 

114 

115def _ytm() -> YTMusic: 

116 global _client 

117 if _client is None: 

118 with _lock: 

119 if _client is None: 

120 _client = YTMusic(proxies=requests_proxies_for_youtube_music()) 

121 return _client 

122 

123 

124def _artist_channel_name(channel_id: str) -> str: 

125 """The name of the YouTube Music artist channel *channel_id*, cached; 

126 '' when it can't be read (tried again a while later).""" 

127 

128 with _lock: 

129 if channel_id in _artist_channel_name_cache: 

130 return _artist_channel_name_cache[channel_id] 

131 failed = _artist_channel_name_failed.get(channel_id) 

132 if ( 

133 failed is not None 

134 and time.monotonic() - failed < _CHANNEL_NAME_RETRY_SECONDS 

135 ): 

136 return '' 

137 try: 

138 data = _ytm().get_artist(channel_id) or {} 

139 name = str(data.get('name') or '').strip() 

140 except Exception: 

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

142 'YouTube Music get_artist failed for {}', channel_id 

143 ) 

144 with _lock: 

145 _artist_channel_name_failed[channel_id] = time.monotonic() 

146 return '' 

147 with _lock: 

148 _artist_channel_name_cache[channel_id] = name 

149 _artist_channel_name_failed.pop(channel_id, None) 

150 return name 

151 

152 

153def _prefetch_artist_channel_names(rows: Any) -> None: 

154 """Read, a few at once, the artist channels :func:`_credited_artist_names` 

155 will look up for *rows* (playlist rows), so a long playlist doesn't 

156 wait on one lookup after another.""" 

157 

158 wanted: set[str] = set() 

159 for row in rows or []: 

160 entries = [ 

161 entry 

162 for entry in (row or {}).get('artists') or [] 

163 if isinstance(entry, dict) and str(entry.get('name') or '').strip() 

164 ] 

165 if len(entries) < 2: 

166 continue 

167 wanted.update( 

168 str(entry.get('id') or '') for entry in entries if entry.get('id') 

169 ) 

170 with _lock: 

171 wanted -= _artist_channel_name_cache.keys() 

172 if len(wanted) < 2: 

173 return 

174 with ThreadPoolExecutor(max_workers=_CHANNEL_NAME_WORKERS) as pool: 

175 list(pool.map(_artist_channel_name, sorted(wanted))) 

176 

177 

178def _credited_artist_names(entries: Any) -> list[str]: 

179 """The artist names of a YouTube Music credit (a list of ``{name, 

180 id}``), one per artist - with an act it split into its members joined 

181 back into one name. 

182 

183 YouTube Music credits some duos as their members: "Henrique & 

184 Juliano" comes back as "Henrique" (linked to the duo's own channel) 

185 and "Juliano" (linked to an unrelated namesake), on the album as well 

186 as on its tracks - and in either order: "Mateus" (a namesake), then 

187 "Jorge" (linked to "Jorge & Mateus"). The tell is a member's channel 

188 named after the whole act rather than after the name credited, and 

189 that act's name made of the names next to it. A real collaboration 

190 ("Christina Aguilera, Lil' Kim, ...") credits each artist under their 

191 own channel's name, so it's left alone. Costs one lookup per artist 

192 channel in a credit of two or more, cached. 

193 """ 

194 

195 credited = [ 

196 (str(entry.get('name') or '').strip(), str(entry.get('id') or '')) 

197 for entry in entries or [] 

198 if isinstance(entry, dict) and str(entry.get('name') or '').strip() 

199 ] 

200 index = 0 

201 while len(credited) > 1 and index < len(credited): 

202 name, channel_id = credited[index] 

203 act = _artist_channel_name(channel_id) if channel_id else '' 

204 span = None 

205 if act and act.casefold() != name.casefold(): 

206 span = _act_span([n for n, _id in credited], index, act) 

207 if span is None: 

208 index += 1 

209 continue 

210 start, end = span 

211 credited[start:end] = [(act, '')] 

212 index = start + 1 

213 return [name for name, _id in credited] 

214 

215 

216def _act_span( 

217 names: list[str], index: int, act: str 

218) -> Optional[tuple[int, int]]: 

219 """The ``(start, end)`` of the run of *names* around *index* that make 

220 up *act* (see :func:`album_artist.is_act_of`), the longest first; 

221 ``None`` when there is none.""" 

222 

223 for size in range(len(names), 1, -1): 

224 for start in range( 

225 max(0, index - size + 1), min(index, len(names) - size) + 1 

226 ): 

227 if is_act_of(names[start : start + size], act): 

228 return start, start + size 

229 return None 

230 

231 

232DEFAULT_COVER_RESOLUTION = 1200 

233 

234# Mutable module-level target, set from Settings (see 

235# set_cover_resolution) so every function below that resolves a YouTube 

236# Music thumbnail through _upgrade_thumbnail picks it up without each of 

237# them needing to accept and thread a resolution parameter through their 

238# own callers. Verified against the live CDN: YouTube Music resizes the 

239# release's master image to the size asked for, and sends the master 

240# itself - 1400 to 2400px for the releases measured - when asked for 

241# more, never an enlarged copy. 

242_cover_resolution = DEFAULT_COVER_RESOLUTION 

243# The "Minimum cover size" setting (0 = off). A first request smaller 

244# than it would only be thrown away for a larger cover from another 

245# source (downloader._download_cover_meeting), so the first request asks 

246# for at least this much - up to _MAX_FIRST_REQUEST, the largest master 

247# YouTube Music or iTunes has been seen to keep. 

248_cover_minimum = 0 

249_MAX_FIRST_REQUEST = 3000 

250 

251 

252def set_cover_resolution(pixels: int) -> None: 

253 """Set the target size (in pixels, both dimensions) for YouTube 

254 Music cover art requested via _upgrade_thumbnail from here on. 

255 

256 Spotify-sourced cover art is unaffected: Downtify already picks the 

257 largest size Spotify's embed API offers (see spotify._largest_image) 

258 and Spotify's image URLs have no equivalent resizable suffix to 

259 raise further. 

260 """ 

261 global _cover_resolution 

262 _cover_resolution = pixels 

263 

264 

265def set_cover_minimum(pixels: int) -> None: 

266 """Set the "Minimum cover size" (0 = off) the cover size is raised 

267 to (see :func:`cover_resolution`).""" 

268 

269 global _cover_minimum 

270 _cover_minimum = max(0, int(pixels or 0)) 

271 

272 

273def cover_resolution() -> int: 

274 """The cover size to ask YouTube Music and Deezer for: the "Cover 

275 size" setting (see set_cover_resolution), raised to the minimum 

276 cover size when that is larger (capped at _MAX_FIRST_REQUEST). 

277 downtify.deezer reads this too, picking the smallest of Deezer's four 

278 fixed image sizes that still meets it, since a Deezer image can't be 

279 resized by editing its URL the way a YouTube Music thumbnail can (see 

280 deezer._cover_from_images).""" 

281 return max(_cover_resolution, min(_cover_minimum, _MAX_FIRST_REQUEST)) 

282 

283 

284def _resize_thumbnail(url: str, size: int) -> str: 

285 """Replace the size suffix on a YT thumbnail with the given one.""" 

286 

287 if not url: 

288 return url 

289 return re.sub(r'=w\d+-h\d+.*$', f'=w{size}-h{size}-l90-rj', url) 

290 

291 

292def resize_thumbnail(url: str, size: int) -> str: 

293 """*url* (a YouTube Music cover) asked for at *size* pixels.""" 

294 

295 return _resize_thumbnail(url, size) 

296 

297 

298def _upgrade_thumbnail(url: str) -> str: 

299 """Replace the size suffix on a YT thumbnail with a larger one.""" 

300 

301 return _resize_thumbnail(url, cover_resolution()) 

302 

303 

304# Playlist (not per-track) cover art always targets this size, independent 

305# of the user's configured cover_resolution — mirroring how Spotify 

306# playlist covers already use the largest size its embed API offers, 

307# unaffected by that same setting (see set_cover_resolution). 

308_PLAYLIST_COVER_SIZE = 1200 

309 

310 

311def _parse_duration(value: Any) -> int: 

312 if isinstance(value, int): 

313 return value 

314 if not isinstance(value, str): 

315 return 0 

316 parts = value.split(':') 

317 try: 

318 nums = [int(p) for p in parts] 

319 except ValueError: 

320 return 0 

321 if len(nums) == 2: 

322 return nums[0] * 60 + nums[1] 

323 if len(nums) == 3: 

324 return nums[0] * 3600 + nums[1] * 60 + nums[2] 

325 return 0 

326 

327 

328def _result_to_song( 

329 result: dict[str, Any], *, rejoin_acts: bool = False 

330) -> Optional[dict[str, Any]]: 

331 """*result* (a search or playlist row) as a song dict. *rejoin_acts* 

332 joins back an act YouTube Music split into its members (see 

333 :func:`_credited_artist_names`) - for a row about to be downloaded, 

334 not for a page of search results, as it may cost a lookup.""" 

335 

336 video_id = result.get('videoId') 

337 if not video_id: 

338 return None 

339 if rejoin_acts: 

340 artists = _credited_artist_names(result.get('artists')) 

341 else: 

342 artists = [ 

343 a.get('name', '') 

344 for a in (result.get('artists') or []) 

345 if isinstance(a, dict) and a.get('name') 

346 ] 

347 artists = _extract_title_featuring_artist(result.get('title', ''), artists) 

348 thumbs = result.get('thumbnails') or [] 

349 cover = thumbs[-1].get('url', '') if thumbs else '' 

350 cover = _upgrade_thumbnail(cover) 

351 album = result.get('album') or {} 

352 album_name = album.get('name', '') if isinstance(album, dict) else '' 

353 album_id = str(album.get('id') or '') if isinstance(album, dict) else '' 

354 duration = result.get('duration_seconds') or _parse_duration( 

355 result.get('duration') 

356 ) 

357 year_str = str(result.get('year') or '').strip() 

358 release_date = ( 

359 year_str if len(year_str) == 4 and year_str.isdigit() else '' 

360 ) 

361 row = { 

362 'song_id': video_id, 

363 'name': result.get('title', ''), 

364 'artists': artists, 

365 'album_name': album_name, 

366 # Where the search page's album and artist names lead: the 

367 # YouTube Music album and each credited artist's channel. 

368 'album_url': ( 

369 f'https://music.youtube.com/browse/{album_id.strip()}' 

370 if album_id.strip() 

371 else '' 

372 ), 

373 'artist_urls': _artist_channel_urls(result.get('artists')), 

374 'cover_url': cover, 

375 'duration': duration, 

376 'url': f'https://music.youtube.com/watch?v={video_id}', 

377 'explicit': bool(result.get('isExplicit')), 

378 'year': year_str, 

379 'release_date': release_date, 

380 'source': 'youtube', 

381 } 

382 row['spotify_url'] = spotify_open_url(row) 

383 return row 

384 

385 

386def _artist_channel_urls(artists: Any) -> dict[str, str]: 

387 """``{name: YouTube Music channel URL}`` for each artist entry of a 

388 search row that carries a channel id (uncredited ones don't).""" 

389 

390 urls: dict[str, str] = {} 

391 for artist in artists or []: 

392 if not isinstance(artist, dict): 

393 continue 

394 name = str(artist.get('name') or '').strip() 

395 channel_id = str(artist.get('id') or '').strip() 

396 if name and channel_id: 

397 urls[name] = f'https://music.youtube.com/channel/{channel_id}' 

398 return urls 

399 

400 

401def spotify_open_url(song: dict[str, Any]) -> str: 

402 """Web URL to open this row on Spotify (track link or search fallback).""" 

403 

404 raw = str(song.get('url') or '').strip() 

405 if 'open.spotify.com' in raw: 

406 return raw 

407 artists = song.get('artists') or [] 

408 artist = ', '.join(str(a).strip() for a in artists[:3] if str(a).strip()) 

409 title = str(song.get('name') or '').strip() 

410 term = f'{artist} {title}'.strip() if artist else title 

411 if not term: 

412 return '' 

413 return f'https://open.spotify.com/search/{quote(term)}' 

414 

415 

416def _parse_text_search_query(query: str) -> tuple[list[str], str]: 

417 text = query.strip() 

418 if not text: 

419 return [], '' 

420 if ' - ' in text: 

421 left, right = text.split(' - ', 1) 

422 artist = left.strip() 

423 title = right.strip() 

424 if artist and title: 

425 return [artist], title 

426 return [], text 

427 

428 

429def song_stub_from_text_query(query: str) -> Optional[dict[str, Any]]: 

430 """Build a minimal song row for slskd matching when browse search has no hits.""" 

431 artists, title = _parse_text_search_query(query) 

432 text = query.strip() 

433 if not text: 

434 return None 

435 song_id = f'search-{zlib.crc32(text.encode()):08x}' 

436 row = { 

437 'song_id': song_id, 

438 'name': title, 

439 'artists': artists, 

440 'album_name': '', 

441 'cover_url': '', 

442 'duration': 0, 

443 'url': f'downtify-search:{song_id}', 

444 'explicit': False, 

445 'year': '', 

446 'release_date': '', 

447 'source': 'text_search', 

448 } 

449 row['spotify_url'] = spotify_open_url(row) 

450 return row 

451 

452 

453def search_songs(query: str, limit: int = 20) -> list[dict[str, Any]]: 

454 if not query.strip(): 

455 return [] 

456 try: 

457 results = _ytm().search(query, filter='songs', limit=limit) 

458 except Exception: 

459 logger.exception('YouTube Music search failed') 

460 return [] 

461 titles = [ 

462 str(r.get('title') or '')[:60] 

463 for r in results[:8] 

464 if isinstance(r, dict) 

465 ] 

466 _log_ytm_summary_search( 

467 phase='browse', 

468 query=query, 

469 filt='songs', 

470 results_len=len(results), 

471 first_titles=titles, 

472 ) 

473 _log_ytm_response(f'search songs q={query[:80]!r}', results) 

474 songs: list[dict[str, Any]] = [] 

475 for result in results: 

476 song = _result_to_song(result) 

477 if song: 

478 songs.append(song) 

479 return songs 

480 

481 

482def _watch_track_to_song( 

483 entry: Any, *, position: int, total: int 

484) -> Optional[dict[str, Any]]: 

485 """One ``get_watch_playlist`` entry as a downloadable song row. 

486 

487 ``match`` decays with the position: YouTube ranks "Up next" by 

488 relevance but gives no score, so the first row counts as a perfect 

489 match and the last one as barely related. 

490 """ 

491 

492 if not isinstance(entry, dict): 

493 return None 

494 video_id = str(entry.get('videoId') or '').strip() 

495 title = str(entry.get('title') or '').strip() 

496 artists = [ 

497 str(a.get('name') or '').strip() 

498 for a in (entry.get('artists') or []) 

499 if isinstance(a, dict) and str(a.get('name') or '').strip() 

500 ] 

501 if not video_id or not title or not artists: 

502 return None 

503 thumbs = entry.get('thumbnail') or [] 

504 cover = ( 

505 _upgrade_thumbnail(str(thumbs[-1].get('url') or '')) 

506 if isinstance(thumbs, list) and thumbs 

507 else '' 

508 ) 

509 album = entry.get('album') if isinstance(entry.get('album'), dict) else {} 

510 match = round(max(0.0, 1.0 - position / max(total, 1)), 4) 

511 return { 

512 'song_id': video_id, 

513 'name': title, 

514 'artists': artists, 

515 'album_name': str(album.get('name') or ''), 

516 'cover_url': cover, 

517 'duration': _parse_duration(entry.get('length')), 

518 'url': f'https://music.youtube.com/watch?v={video_id}', 

519 'explicit': False, 

520 'source': 'youtube', 

521 'match': match, 

522 } 

523 

524 

525def _seed_video_id( 

526 artist: str, track: str 

527) -> tuple[str, list[dict[str, Any]]]: 

528 """The seed track's videoId: the first search hit by its artist. 

529 

530 Falls back to the very first hit when none names the artist (a 

531 translation, a feature credit) - a radio mix off a wrong video is 

532 still closer than no mix at all. With only one of the two (an 

533 artist or a bare title) the seed is simply the top hit for it. 

534 """ 

535 

536 artist = str(artist or '').strip() 

537 track = str(track or '').strip() 

538 if not artist and not track: 

539 raise ValueError('artist or track is required') 

540 query = f'{artist} {track}'.strip() 

541 hits = search_songs(query, limit=5) 

542 label = f'{artist} - {track}' if artist and track else (artist or track) 

543 if not hits: 

544 raise ValueError(f'No match on YouTube Music for {label}') 

545 if artist and track: 

546 want = artist.casefold() 

547 for hit in hits: 

548 names = [ 

549 str(a or '').casefold() for a in (hit.get('artists') or []) 

550 ] 

551 if want and any(want in name or name in want for name in names): 

552 video_id = str(hit.get('song_id') or '').strip() 

553 if video_id: 

554 return video_id, hits 

555 video_id = str(hits[0].get('song_id') or '').strip() 

556 if not video_id: 

557 raise ValueError(f'No match on YouTube Music for {label}') 

558 return video_id, hits 

559 

560 

561def youtube_similar_tracks( 

562 artist: str, track: str, *, limit: int = 20 

563) -> dict[str, Any]: 

564 """Tracks similar to *track* by *artist*, from YouTube Music itself. 

565 

566 Resolves the seed to a video, then reads its radio mix ("Up next" 

567 for that video): what YouTube plays after it. Needs no API key. 

568 Either *artist* or *track* alone is enough: a bare artist seeds 

569 from its top hit, a bare title from the top hit for it. 

570 Returns ``{artist, track, source, tracks}`` where each track is a 

571 downloadable song row plus ``match``. Raises :class:`ValueError` 

572 when the seed has no match or YouTube Music can't be reached. 

573 """ 

574 

575 artist = str(artist or '').strip() 

576 track = str(track or '').strip() 

577 if not artist and not track: 

578 raise ValueError('artist or track is required') 

579 limit = max(1, min(50, int(limit or 20))) 

580 seed_id, hits = _seed_video_id(artist, track) 

581 if not artist or not track: 

582 seed_hit = next( 

583 ( 

584 h 

585 for h in hits 

586 if str(h.get('song_id') or '').strip() == seed_id 

587 ), 

588 hits[0], 

589 ) 

590 seed_artists = [ 

591 str(a or '').strip() 

592 for a in (seed_hit.get('artists') or []) 

593 if str(a or '').strip() 

594 ] 

595 seed_title = str(seed_hit.get('name') or '').strip() 

596 if not artist and seed_artists: 

597 artist = seed_artists[0] 

598 if not track and seed_title: 

599 track = seed_title 

600 try: 

601 mix = _ytm().get_watch_playlist(seed_id, limit=limit + 1, radio=True) 

602 except Exception as exc: 

603 raise ValueError(f'YouTube Music did not answer: {exc}') from exc 

604 entries = mix.get('tracks') if isinstance(mix, dict) else None 

605 if not isinstance(entries, list): 

606 raise ValueError('YouTube Music answered with an unreadable reply') 

607 tracks: list[dict[str, Any]] = [] 

608 seen = {seed_id} 

609 for entry in entries: 

610 song = _watch_track_to_song(entry, position=len(tracks), total=limit) 

611 if song is None or song['song_id'] in seen: 

612 continue 

613 seen.add(song['song_id']) 

614 tracks.append(song) 

615 if len(tracks) >= limit: 

616 break 

617 return { 

618 'artist': artist, 

619 'track': track, 

620 'source': 'youtube', 

621 'tracks': tracks, 

622 } 

623 

624 

625def _album_summary(result: dict[str, Any]) -> Optional[dict[str, Any]]: 

626 browse_id = result.get('browseId') 

627 if not isinstance(browse_id, str) or not browse_id.strip(): 

628 return None 

629 artists = [ 

630 a.get('name', '') 

631 for a in (result.get('artists') or []) 

632 if isinstance(a, dict) and a.get('name') 

633 ] 

634 if artists: 

635 with _lock: 

636 _album_search_artist_cache[browse_id.strip()] = artists 

637 thumbs = result.get('thumbnails') or [] 

638 cover = _upgrade_thumbnail(thumbs[-1].get('url', '')) if thumbs else '' 

639 return { 

640 'album_id': browse_id.strip(), 

641 'name': result.get('title', ''), 

642 'artists': artists, 

643 'artist': ', '.join(artists), 

644 'cover_url': cover, 

645 'year': str(result.get('year') or '').strip(), 

646 'explicit': bool(result.get('isExplicit')), 

647 'url': f'https://music.youtube.com/browse/{browse_id.strip()}', 

648 'source': 'youtube', 

649 # YouTube Music's own release-type classification: 'Album', 

650 # 'Single', or 'EP'. Not every release is actually an "album" — 

651 # surface it as-is so callers (UI badge, audio tags) don't have 

652 # to guess. 

653 'release_type': result.get('type') or '', 

654 } 

655 

656 

657def search_albums(query: str, limit: int = 10) -> list[dict[str, Any]]: 

658 """Search YouTube Music for albums matching ``query``. 

659 

660 Returns lightweight album summaries (not full tracklists) suitable 

661 for a search-results list; resolve a chosen album's tracks via 

662 :func:`album_tracks_from_browse_id`. 

663 """ 

664 

665 if not query.strip(): 

666 return [] 

667 try: 

668 results = _ytm().search(query, filter='albums', limit=limit) 

669 except Exception: 

670 logger.exception('YouTube Music album search failed') 

671 return [] 

672 titles = [ 

673 str(r.get('title') or '')[:60] 

674 for r in results[:8] 

675 if isinstance(r, dict) 

676 ] 

677 _log_ytm_summary_search( 

678 phase='browse_albums', 

679 query=query, 

680 filt='albums', 

681 results_len=len(results), 

682 first_titles=titles, 

683 ) 

684 _log_ytm_response(f'search albums q={query[:80]!r}', results) 

685 albums: list[dict[str, Any]] = [] 

686 for result in results: 

687 if not isinstance(result, dict): 

688 continue 

689 album = _album_summary(result) 

690 if album: 

691 albums.append(album) 

692 return albums 

693 

694 

695def _artist_summary(result: dict[str, Any]) -> Optional[dict[str, Any]]: 

696 channel_id = result.get('browseId') 

697 if not isinstance(channel_id, str) or not channel_id.strip(): 

698 return None 

699 thumbs = result.get('thumbnails') or [] 

700 cover = _upgrade_thumbnail(thumbs[-1].get('url', '')) if thumbs else '' 

701 return { 

702 'artist_id': channel_id.strip(), 

703 'name': result.get('artist') or '', 

704 'cover_url': cover, 

705 'url': f'https://music.youtube.com/channel/{channel_id.strip()}', 

706 'source': 'youtube', 

707 } 

708 

709 

710def search_artists(query: str, limit: int = 10) -> list[dict[str, Any]]: 

711 """Search YouTube Music for artists matching ``query``. 

712 

713 Returns lightweight artist summaries; resolve a chosen artist's full 

714 discography (every album and single, each with its full tracklist) 

715 via :func:`artist_discography_from_channel_id`. 

716 """ 

717 

718 if not query.strip(): 

719 return [] 

720 try: 

721 results = _ytm().search(query, filter='artists', limit=limit) 

722 except Exception: 

723 logger.exception('YouTube Music artist search failed') 

724 return [] 

725 titles = [ 

726 str(r.get('artist') or '')[:60] 

727 for r in results[:8] 

728 if isinstance(r, dict) 

729 ] 

730 _log_ytm_summary_search( 

731 phase='browse_artists', 

732 query=query, 

733 filt='artists', 

734 results_len=len(results), 

735 first_titles=titles, 

736 ) 

737 _log_ytm_response(f'search artists q={query[:80]!r}', results) 

738 artists: list[dict[str, Any]] = [] 

739 for result in results: 

740 if not isinstance(result, dict): 

741 continue 

742 artist = _artist_summary(result) 

743 if artist: 

744 artists.append(artist) 

745 return artists 

746 

747 

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

749 """YouTube Music channel id for an exact name match, or ``None`` if no 

750 search result's name matches exactly. Case and the characters a file 

751 name can't hold are ignored (``ACDC`` matches ``AC/DC``, see 

752 :func:`downtify.file_naming.file_name_key`). 

753 

754 Deliberately strict, same reasoning as 

755 :func:`downtify.deezer.resolve_artist_id`/ 

756 :func:`downtify.apple_music.resolve_artist_id`: an unrelated top 

757 result would silently attach the wrong artist's id to this one's 

758 profile. Used by :func:`downtify.artist_profile.resolve_platform_ids` 

759 to fill in ``platforms_id.youtubemusic`` - YouTube Music has no bio 

760 of its own in the profile picker anymore, just this id. 

761 """ 

762 

763 text = name.strip() 

764 wanted = file_name_key(text) 

765 if not wanted: 

766 return None 

767 for artist in search_artists(text, limit=25): 

768 if file_name_key(str(artist.get('name') or '')) == wanted: 

769 return artist.get('artist_id') or None 

770 return None 

771 

772 

773def _artist_discography_browse_id(channel_id: str) -> str: 

774 """BrowseId for an artist's full "See all" albums/singles grid page. 

775 

776 Distinct from the artist's own channelId. YouTube Music's "More" 

777 button on an artist's Albums/Singles shelf links to this same id 

778 (``MPAD`` + channelId) — visible directly in the button's own 

779 navigation endpoint, and in the URL if you click it yourself: 

780 ``https://music.youtube.com/browse/MPAD<channelId>``. 

781 """ 

782 return f'MPAD{channel_id}' 

783 

784 

785def _fetch_full_artist_section( 

786 channel_id: str, params: str 

787) -> list[dict[str, Any]]: 

788 """Fetch every entry of an artist's 'albums' or 'singles' shelf. 

789 

790 ytmusicapi's own ``get_artist_albums(channelId, params)`` sends the 

791 artist's own channelId as the browseId, which returns the *artist's 

792 home page* again (a channel can have several other carousels besides 

793 Albums/Singles, e.g. "Top songs") instead of the dedicated 

794 discography grid — its navigation code then assumes the first 

795 section of that response is the grid it wants, finds an unrelated 

796 shelf instead, and raises a KeyError. Upstream closed this as "not 

797 planned": https://github.com/sigma67/ytmusicapi/issues/595. This 

798 requests the correct discography browseId directly instead (see 

799 ``_artist_discography_browse_id``), reusing ytmusicapi's own 

800 lower-level request/parse/continuation helpers. 

801 """ 

802 body = { 

803 'browseId': _artist_discography_browse_id(channel_id), 

804 'params': params, 

805 } 

806 ytm = _ytm() 

807 response = ytm._send_request('browse', body) 

808 results = nav(response, SINGLE_COLUMN_TAB + SECTION_LIST_ITEM) 

809 contents = nav(results, GRID_ITEMS, True) or [] 

810 albums = _parse_ytm_albums(contents) 

811 grid = nav(results, GRID, True) or {} 

812 if 'continuations' in grid: 

813 

814 def _request_more(additional_params: Any) -> Any: 

815 return ytm._send_request('browse', body, additional_params) 

816 

817 albums.extend( 

818 get_continuations( 

819 grid, 

820 'gridContinuation', 

821 None, 

822 _request_more, 

823 _parse_ytm_albums, 

824 ) 

825 ) 

826 return albums 

827 

828 

829def _artist_albums_full_list( 

830 channel_id: str, section: dict[str, Any] 

831) -> list[dict[str, Any]]: 

832 """Return every entry of an artist page's 'albums'/'singles' section. 

833 

834 The section as returned by ``get_artist`` only ever holds a short 

835 preview (~10 entries); the ``params`` continuation token it carries 

836 is used to fetch the complete list from the artist's discography 

837 browse page (see ``_fetch_full_artist_section``). 

838 """ 

839 

840 results = [ 

841 r for r in (section.get('results') or []) if isinstance(r, dict) 

842 ] 

843 params = section.get('params') 

844 if not params: 

845 return results 

846 try: 

847 full = _fetch_full_artist_section(channel_id, params) 

848 except Exception: 

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

850 'Fetching full artist discography failed for {}', channel_id 

851 ) 

852 return results 

853 return [r for r in (full or []) if isinstance(r, dict)] or results 

854 

855 

856def artist_info_from_channel_id(channel_id: str) -> dict[str, Any]: 

857 """Resolve an artist's own profile info: name, thumbnail, bio. 

858 

859 Distinct from :func:`artist_albums_from_channel_id` (their releases) 

860 and :func:`artist_top_songs_from_channel_id`/ 

861 :func:`artist_top_albums_from_channel_id` (their popular tracks/ 

862 albums) - this is just the "About" info for the artist page itself. 

863 Returns ``{}`` if the artist can't be resolved at all. 

864 """ 

865 

866 try: 

867 artist_data = _ytm().get_artist(channel_id) 

868 except Exception: 

869 logger.exception('YouTube Music get_artist failed for {}', channel_id) 

870 return {} 

871 

872 thumbs = artist_data.get('thumbnails') or [] 

873 cover = _upgrade_thumbnail(thumbs[-1].get('url', '')) if thumbs else '' 

874 return { 

875 'artist_id': channel_id, 

876 'name': str(artist_data.get('name') or '').strip(), 

877 'cover_url': cover, 

878 'description': str(artist_data.get('description') or '').strip(), 

879 'url': f'https://music.youtube.com/channel/{channel_id}', 

880 'source': 'youtube', 

881 } 

882 

883 

884def artist_similar_from_channel_id(channel_id: str) -> list[dict[str, Any]]: 

885 """Resolve an artist's "Fans might also like" shelf as lightweight 

886 artist summaries. Same shape as :func:`search_artists` results. 

887 

888 YouTube Music only ever offers a short, fixed list here (~10 - no 

889 'params' continuation is offered, unlike the albums/singles shelves). 

890 """ 

891 

892 try: 

893 artist_data = _ytm().get_artist(channel_id) 

894 except Exception: 

895 logger.exception('YouTube Music get_artist failed for {}', channel_id) 

896 return [] 

897 

898 section = artist_data.get('related') 

899 if not isinstance(section, dict): 

900 return [] 

901 artists = [] 

902 for entry in section.get('results') or []: 

903 if not isinstance(entry, dict): 

904 continue 

905 related_id = entry.get('browseId') 

906 if not isinstance(related_id, str) or not related_id.strip(): 

907 continue 

908 thumbs = entry.get('thumbnails') or [] 

909 cover = _upgrade_thumbnail(thumbs[-1].get('url', '')) if thumbs else '' 

910 artists.append({ 

911 'artist_id': related_id.strip(), 

912 'name': entry.get('title') or '', 

913 'cover_url': cover, 

914 'url': f'https://music.youtube.com/channel/{related_id.strip()}', 

915 'source': 'youtube', 

916 }) 

917 return artists 

918 

919 

920def artist_albums_from_channel_id(channel_id: str) -> list[dict[str, Any]]: 

921 """Resolve every album and single for an artist as lightweight summaries. 

922 

923 Same shape as :func:`search_albums` results (no tracklists). This is 

924 deliberate: listing an artist's releases never needs their tracks - a 

925 caller that wants a specific release's tracks resolves it separately, 

926 once the user actually opens it, via :func:`album_tracks_from_browse_id`. 

927 Resolving every tracklist just to list the discography would mean one 

928 extra YouTube Music round-trip *per release*, turning a single 

929 ``get_artist`` call into dozens for a prolific artist. Duplicates (a 

930 release appearing in both the albums and singles sections) are 

931 de-duplicated. 

932 """ 

933 

934 try: 

935 artist_data = _ytm().get_artist(channel_id) 

936 except Exception: 

937 logger.exception('YouTube Music get_artist failed for {}', channel_id) 

938 return [] 

939 

940 artist_name = str(artist_data.get('name') or '').strip() 

941 entries: list[tuple[dict[str, Any], str]] = [] 

942 for section_key, release_type in ( 

943 ('albums', 'Album'), 

944 ('singles', 'Single'), 

945 ): 

946 section = artist_data.get(section_key) 

947 if not isinstance(section, dict): 

948 continue 

949 for entry in _artist_albums_full_list(channel_id, section): 

950 entries.append((entry, release_type)) 

951 

952 # dedupe by browseId (a release occasionally shows up in both sections) 

953 deduped: dict[str, tuple[dict[str, Any], str]] = {} 

954 for entry, default_release_type in entries: 

955 browse_id = entry.get('browseId') 

956 if not isinstance(browse_id, str) or not browse_id.strip(): 

957 continue 

958 deduped.setdefault(browse_id.strip(), (entry, default_release_type)) 

959 

960 logger.info( 

961 'YouTube Music get_artist {!r} channelId={} albums={} singles={} ' 

962 'unique={}', 

963 artist_name, 

964 channel_id, 

965 sum(1 for _, rt in entries if rt == 'Album'), 

966 sum(1 for _, rt in entries if rt == 'Single'), 

967 len(deduped), 

968 ) 

969 

970 return [ 

971 _artist_album_entry_to_summary( 

972 browse_id, entry, artist_name, default_release_type 

973 ) 

974 for browse_id, (entry, default_release_type) in deduped.items() 

975 ] 

976 

977 

978def _artist_album_entry_to_summary( 

979 browse_id: str, 

980 entry: dict[str, Any], 

981 artist_name: str, 

982 default_release_type: str, 

983) -> dict[str, Any]: 

984 """Build one album summary dict from a raw ``get_artist`` shelf entry. 

985 

986 Same shape as :func:`search_albums` results (no tracklists) — shared 

987 by :func:`artist_albums_from_channel_id` (full discography) and 

988 :func:`artist_top_albums_from_channel_id` (the shelf's own preview, 

989 unexpanded). 

990 """ 

991 thumbs = entry.get('thumbnails') or [] 

992 cover = _upgrade_thumbnail(thumbs[-1].get('url', '')) if thumbs else '' 

993 return { 

994 'album_id': browse_id, 

995 'name': entry.get('title') or '', 

996 'artists': [artist_name] if artist_name else [], 

997 'artist': artist_name, 

998 'cover_url': cover, 

999 'year': str(entry.get('year') or '').strip(), 

1000 'explicit': bool(entry.get('isExplicit')), 

1001 'url': f'https://music.youtube.com/browse/{browse_id}', 

1002 'source': 'youtube', 

1003 # the singles section carries YTM's own 'Single'/'EP' split; 

1004 # the albums section doesn't distinguish further, so it always 

1005 # falls back to the section's own default ('Album'). 

1006 'release_type': entry.get('type') or default_release_type, 

1007 } 

1008 

1009 

1010_TOP_ALBUMS_LIMIT = 5 

1011 

1012 

1013def _popularity_sort_continuation( 

1014 response: dict[str, Any], 

1015) -> Optional[dict[str, Any]]: 

1016 """Find the "Popularity" entry in a discography page's sort-order 

1017 menu and return its reloadable-continuation payload, or ``None`` if 

1018 the page doesn't carry a sort menu at all (e.g. too few releases for 

1019 YouTube Music to bother offering one). 

1020 """ 

1021 try: 

1022 sort_options = nav( 

1023 response, 

1024 SINGLE_COLUMN_TAB 

1025 + SECTION 

1026 + HEADER_SIDE 

1027 + [ 

1028 'endItems', 

1029 0, 

1030 'musicSortFilterButtonRenderer', 

1031 'menu', 

1032 'musicMultiSelectMenuRenderer', 

1033 'options', 

1034 ], 

1035 ) 

1036 except Exception: 

1037 return None 

1038 for option in sort_options: 

1039 title = nav(option, MULTI_SELECT + TITLE_TEXT, True) 

1040 if isinstance(title, str) and title.strip().lower() == 'popularity': 

1041 return nav( 

1042 option, 

1043 [ 

1044 *MULTI_SELECT, 

1045 'selectedCommand', 

1046 'commandExecutorCommand', 

1047 'commands', 

1048 -1, 

1049 'browseSectionListReloadEndpoint', 

1050 ], 

1051 True, 

1052 ) 

1053 return None 

1054 

1055 

1056def _fetch_artist_section_by_popularity( 

1057 channel_id: str, params: str, limit: int 

1058) -> list[dict[str, Any]]: 

1059 """Fetch an artist's 'albums'/'singles' shelf sorted by YouTube 

1060 Music's own "Popularity" ordering, truncated to ``limit`` entries. 

1061 

1062 This is literally what selecting "Popularity" from the sort dropdown 

1063 on an artist's discography page does — see 

1064 ``_fetch_full_artist_section``'s docstring for why the discography 

1065 browseId, not the artist's channelId itself, is needed to even reach 

1066 that page (and its sort menu) in the first place. 

1067 """ 

1068 body = { 

1069 'browseId': _artist_discography_browse_id(channel_id), 

1070 'params': params, 

1071 } 

1072 ytm = _ytm() 

1073 response = ytm._send_request('browse', body) 

1074 continuation = _popularity_sort_continuation(response) 

1075 if not continuation: 

1076 return [] 

1077 additional_params = get_reloadable_continuation_params({ 

1078 'continuations': [continuation['continuation']] 

1079 }) 

1080 response = ytm._send_request('browse', body, additional_params) 

1081 results = nav(response, SECTION_LIST_CONTINUATION + CONTENT) 

1082 contents = nav(results, GRID_ITEMS, True) or [] 

1083 return _parse_ytm_albums(contents)[:limit] 

1084 

1085 

1086def artist_top_albums_from_channel_id(channel_id: str) -> list[dict[str, Any]]: 

1087 """Resolve an artist's most popular albums as lightweight summaries. 

1088 

1089 Fetches the discography page sorted by YouTube Music's own 

1090 "Popularity" order and takes the first :data:`_TOP_ALBUMS_LIMIT`. 

1091 Falls back to the "Albums" shelf's own (unsorted) preview when no 

1092 'params' continuation is offered at all, or the popularity fetch 

1093 fails for any reason — an artist with too few releases for YouTube 

1094 Music to paginate doesn't get a sort menu either, so this covers the 

1095 same case that would make the continuation lookup a no-op anyway. 

1096 Singles/EPs are not included, matching the "Albums" shelf itself. 

1097 """ 

1098 

1099 try: 

1100 artist_data = _ytm().get_artist(channel_id) 

1101 except Exception: 

1102 logger.exception('YouTube Music get_artist failed for {}', channel_id) 

1103 return [] 

1104 

1105 artist_name = str(artist_data.get('name') or '').strip() 

1106 section = artist_data.get('albums') 

1107 if not isinstance(section, dict): 

1108 return [] 

1109 

1110 params = section.get('params') 

1111 entries: list[dict[str, Any]] = [] 

1112 if params: 

1113 try: 

1114 entries = _fetch_artist_section_by_popularity( 

1115 channel_id, params, _TOP_ALBUMS_LIMIT 

1116 ) 

1117 except Exception: 

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

1119 'Fetching popularity-sorted albums failed for {}', 

1120 channel_id, 

1121 ) 

1122 if not entries: 

1123 entries = [ 

1124 r for r in (section.get('results') or []) if isinstance(r, dict) 

1125 ][:_TOP_ALBUMS_LIMIT] 

1126 

1127 albums = [] 

1128 for entry in entries: 

1129 browse_id = entry.get('browseId') 

1130 if not isinstance(browse_id, str) or not browse_id.strip(): 

1131 continue 

1132 albums.append( 

1133 _artist_album_entry_to_summary( 

1134 browse_id.strip(), entry, artist_name, 'Album' 

1135 ) 

1136 ) 

1137 return albums 

1138 

1139 

1140def artist_top_songs_from_channel_id(channel_id: str) -> list[dict[str, Any]]: 

1141 """Resolve an artist's 'Top songs' shelf as lightweight song summaries. 

1142 

1143 Same shape as :func:`search_songs` results. This is YouTube Music's 

1144 own popularity-ranked preview (~10 entries, no further pagination 

1145 offered) — distinct from the full discography, which is resolved a 

1146 release at a time via :func:`album_tracks_from_browse_id`. 

1147 """ 

1148 

1149 try: 

1150 artist_data = _ytm().get_artist(channel_id) 

1151 except Exception: 

1152 logger.exception('YouTube Music get_artist failed for {}', channel_id) 

1153 return [] 

1154 

1155 section = artist_data.get('songs') 

1156 if not isinstance(section, dict): 

1157 return [] 

1158 results = [ 

1159 r for r in (section.get('results') or []) if isinstance(r, dict) 

1160 ] 

1161 songs: list[dict[str, Any]] = [] 

1162 for result in results: 

1163 song = _result_to_song(result) 

1164 if song: 

1165 songs.append(song) 

1166 return songs 

1167 

1168 

1169_PLAYS_RE = re.compile(r'^\s*(\d[\d.,]*)\s*([KMB])?\s+plays?\s*$', re.I) 

1170_PLAYS_MULTIPLIER = {'': 1, 'K': 10**3, 'M': 10**6, 'B': 10**9} 

1171 

1172 

1173def _parse_play_count(text: Any) -> int: 

1174 """``'1.2B plays'`` -> ``1200000000``; ``0`` if it isn't a play count. 

1175 

1176 YouTube Music only reports a rounded figure (``4.4M plays``), so the 

1177 result is an approximation, not the real total. The text is English 

1178 because the client is created without a language. 

1179 """ 

1180 

1181 match = _PLAYS_RE.match(text) if isinstance(text, str) else None 

1182 if match is None: 

1183 return 0 

1184 digits, suffix = match.group(1), (match.group(2) or '').upper() 

1185 try: 

1186 value = float(digits.replace(',', '')) 

1187 except ValueError: 

1188 return 0 

1189 return int(round(value * _PLAYS_MULTIPLIER[suffix])) 

1190 

1191 

1192def _music_list_rows(node: Any) -> list[dict[str, Any]]: 

1193 """Every ``musicResponsiveListItemRenderer`` under *node*.""" 

1194 

1195 rows: list[dict[str, Any]] = [] 

1196 if isinstance(node, dict): 

1197 row = node.get('musicResponsiveListItemRenderer') 

1198 if isinstance(row, dict): 

1199 rows.append(row) 

1200 for value in node.values(): 

1201 rows.extend(_music_list_rows(value)) 

1202 elif isinstance(node, list): 

1203 for value in node: 

1204 rows.extend(_music_list_rows(value)) 

1205 return rows 

1206 

1207 

1208def _playlist_play_counts(playlist_id: str) -> dict[str, int]: 

1209 """``{videoId: approximate play count}`` for a playlist's first page. 

1210 

1211 ``ytmusicapi`` reads the "plays" column only for albums, so 

1212 ``get_playlist`` reports ``views: None`` for a playlist like an 

1213 artist's Top songs even though every row carries it. This reads the 

1214 same ``browse`` response directly instead. Best effort: any failure 

1215 returns ``{}`` and the songs simply have no count. 

1216 """ 

1217 

1218 browse_id = ( 

1219 playlist_id if playlist_id.startswith('VL') else f'VL{playlist_id}' 

1220 ) 

1221 try: 

1222 response = _ytm()._send_request('browse', {'browseId': browse_id}) 

1223 except Exception: 

1224 logger.opt(exception=True).warning( 

1225 'YouTube Music play counts unavailable for {}', playlist_id 

1226 ) 

1227 return {} 

1228 

1229 counts: dict[str, int] = {} 

1230 for row in _music_list_rows(response): 

1231 video_id = (row.get('playlistItemData') or {}).get('videoId') 

1232 if not video_id: 

1233 continue 

1234 for column in row.get('flexColumns') or []: 

1235 runs = ( 

1236 column.get('musicResponsiveListItemFlexColumnRenderer') or {} 

1237 ).get('text', {}).get('runs') or [] 

1238 plays = _parse_play_count(runs[0].get('text') if runs else None) 

1239 if plays: 

1240 counts[video_id] = plays 

1241 break 

1242 return counts 

1243 

1244 

1245def artist_full_top_songs_from_channel_id( 

1246 channel_id: str, 

1247) -> list[dict[str, Any]]: 

1248 """Full 'Top songs' playlist for an artist, beyond the ~5-10 item 

1249 preview :func:`artist_top_songs_from_channel_id` returns. 

1250 

1251 The artist's ``songs`` shelf carries its own ``browseId`` for an 

1252 auto-generated playlist covering the shelf in full — resolved the same 

1253 way any YouTube Music playlist is, via :func:`playlist_tracks_from_id`. 

1254 Each song gets an approximate ``play_count`` (with 

1255 ``play_count_approx``) when the response has one. 

1256 Returns ``[]`` if the artist, its songs shelf, or the shelf's browseId 

1257 can't be resolved at all. 

1258 """ 

1259 

1260 try: 

1261 artist_data = _ytm().get_artist(channel_id) 

1262 except Exception: 

1263 logger.exception('YouTube Music get_artist failed for {}', channel_id) 

1264 return [] 

1265 

1266 section = artist_data.get('songs') 

1267 if not isinstance(section, dict): 

1268 return [] 

1269 browse_id = section.get('browseId') 

1270 if not browse_id: 

1271 return [] 

1272 

1273 try: 

1274 songs = playlist_tracks_from_id(browse_id) 

1275 except Exception: 

1276 logger.exception( 

1277 'Failed to resolve full top-songs playlist {} for artist {}', 

1278 browse_id, 

1279 channel_id, 

1280 ) 

1281 return [] 

1282 

1283 plays = _playlist_play_counts(browse_id) if songs else {} 

1284 for song in songs: 

1285 count = plays.get(song.get('song_id') or '') 

1286 if count: 

1287 song['play_count'] = count 

1288 song['play_count_approx'] = True 

1289 return songs 

1290 

1291 

1292_YOUTUBE_URL_HOSTS = ('youtube.com', 'youtu.be', 'music.youtube.com') 

1293_YOUTUBE_VIDEO_ID_RE = re.compile( 

1294 r'(?:[?&]v=|youtu\.be/|/shorts/)([A-Za-z0-9_-]{6,})' 

1295) 

1296_YOUTUBE_ALBUM_BROWSE_RE = re.compile(r'/browse/(MPREb_[A-Za-z0-9_-]+)') 

1297_YOUTUBE_ALBUM_PLAYLIST_RE = re.compile(r'[?&]list=(OLAK5uy_[A-Za-z0-9_-]+)') 

1298_YOUTUBE_ARTIST_CHANNEL_RE = re.compile(r'/channel/(UC[A-Za-z0-9_-]+)') 

1299_YOUTUBE_ARTIST_HANDLE_RE = re.compile(r'\.com/(@[^/?#&]+)') 

1300_YOUTUBE_PLAYLIST_ID_RE = re.compile(r'[?&]list=([A-Za-z0-9_-]+)') 

1301_YOUTUBE_PLAYLIST_BROWSE_RE = re.compile(r'/browse/VL([A-Za-z0-9_-]+)') 

1302 

1303 

1304def _is_radio_mix(playlist_id: str) -> bool: 

1305 # "RD..." ids are endless auto-generated radio mixes (not a fixed 

1306 # list); "RDCLAK5uy_..." ones are YouTube Music's curated playlists. 

1307 return playlist_id.startswith('RD') and not playlist_id.startswith( 

1308 'RDCLAK5uy_' 

1309 ) 

1310 

1311 

1312def parse_youtube_url(url: str) -> Optional[tuple[str, str]]: 

1313 """Parse a YouTube/YouTube Music URL into ``(kind, id)``. 

1314 

1315 ``kind`` is ``'track'`` (a watchable videoId), ``'album'`` (a 

1316 ``MPREb_`` browse id, or an ``OLAK5uy_`` audio-playlist id — pass 

1317 either straight to :func:`album_tracks_from_browse_id`, which 

1318 resolves the playlist form to a browse id itself), ``'playlist'`` (a 

1319 user or curated playlist id — pass to :func:`playlist_tracks_from_id`) 

1320 or ``'artist'`` (a ``UC``-prefixed channel id, or an ``@handle`` — 

1321 pass either to :func:`resolve_artist_channel_id` first). Returns 

1322 ``None`` for URLs that aren't recognized YouTube links at all. 

1323 

1324 A ``watch?v=...&list=...`` URL is the song that was playing, not the 

1325 playlist around it, so it stays a ``'track'``. 

1326 """ 

1327 

1328 if not url or not any(host in url for host in _YOUTUBE_URL_HOSTS): 

1329 return None 

1330 match = _YOUTUBE_ALBUM_BROWSE_RE.search(url) 

1331 if match: 

1332 return 'album', match.group(1) 

1333 match = _YOUTUBE_ALBUM_PLAYLIST_RE.search(url) 

1334 if match: 

1335 return 'album', match.group(1) 

1336 match = _YOUTUBE_ARTIST_CHANNEL_RE.search(url) 

1337 if match: 

1338 return 'artist', match.group(1) 

1339 match = _YOUTUBE_ARTIST_HANDLE_RE.search(url) 

1340 if match: 

1341 return 'artist', unquote(match.group(1)) 

1342 match = _YOUTUBE_PLAYLIST_BROWSE_RE.search(url) 

1343 if match: 

1344 return 'playlist', match.group(1) 

1345 video = _YOUTUBE_VIDEO_ID_RE.search(url) 

1346 if video: 

1347 return 'track', video.group(1) 

1348 match = _YOUTUBE_PLAYLIST_ID_RE.search(url) 

1349 if match and not _is_radio_mix(match.group(1)): 

1350 return 'playlist', match.group(1) 

1351 return None 

1352 

1353 

1354_channel_id_cache: dict[str, str] = {} 

1355 

1356 

1357def resolve_artist_channel_id(channel_or_handle: str) -> str: 

1358 """Turn the ``'artist'`` id from :func:`parse_youtube_url` into a 

1359 ``UC...`` channel id. 

1360 

1361 A channel id is returned as is. An ``@handle`` is resolved through 

1362 YouTube Music's own URL resolver, the same call its web app makes 

1363 when a ``music.youtube.com/@handle`` link is opened. A handle that 

1364 doesn't belong to an artist resolves to the YouTube Music home page 

1365 instead of a channel, and raises ``ValueError``. 

1366 """ 

1367 

1368 value = (channel_or_handle or '').strip() 

1369 if value.startswith('UC'): 

1370 return value 

1371 if not value.startswith('@'): 

1372 raise ValueError(f'Not a YouTube channel id or handle: {value!r}') 

1373 with _lock: 

1374 cached = _channel_id_cache.get(value.casefold()) 

1375 if cached: 

1376 return cached 

1377 # The resolver only maps handles to artist pages on the 

1378 # music.youtube.com host; a www.youtube.com URL comes back unresolved. 

1379 response = _ytm()._send_request( 

1380 'navigation/resolve_url', 

1381 {'url': f'https://music.youtube.com/{quote(value, safe="@")}'}, 

1382 ) 

1383 _log_ytm_response(f'resolve_url {value}', response) 

1384 endpoint = (response or {}).get('endpoint') or {} 

1385 browse_id = (endpoint.get('browseEndpoint') or {}).get('browseId') or '' 

1386 if not browse_id.startswith('UC'): 

1387 raise ValueError(f'No YouTube Music artist found for {value}') 

1388 with _lock: 

1389 _channel_id_cache[value.casefold()] = browse_id 

1390 return browse_id 

1391 

1392 

1393# A YouTube Music hit further than this (seconds) from the source track's 

1394# length is a weak match — likely a different recording that happens to 

1395# share title and artist, such as a dubbed/translated version — so 

1396# standard YouTube is searched for a closer one before settling for it. 

1397_STRONG_MATCH_MAX_DURATION_DIFF = 10 

1398# Standard-YouTube hits are mostly music videos and user uploads; beyond 

1399# this gap it's a long intro/outro cut, a loop or a compilation, never the 

1400# song itself. 

1401_YOUTUBE_MAX_DURATION_DIFF = 30 

1402_YOUTUBE_SEARCH_LIMIT = 10 

1403 

1404 

1405#: Sources (YouTube video ids, SoundCloud track URLs) the match being 

1406#: made must not pick: uploads found wrong for this song before (see 

1407#: ``downtify/download_sources.py``). Set with :func:`excluding_sources`. 

1408_EXCLUDED_SOURCES: ContextVar[frozenset[str]] = ContextVar( 

1409 'downtify_excluded_sources', default=frozenset() 

1410) 

1411 

1412 

1413@contextmanager 

1414def excluding_sources(sources: Iterable[str]) -> Iterator[None]: 

1415 """Within the block, no matcher picks any of *sources*.""" 

1416 

1417 token = _EXCLUDED_SOURCES.set( 

1418 frozenset(str(s) for s in sources if s) | _EXCLUDED_SOURCES.get() 

1419 ) 

1420 try: 

1421 yield 

1422 finally: 

1423 _EXCLUDED_SOURCES.reset(token) 

1424 

1425 

1426def excluded_source(source: Any) -> bool: 

1427 """Whether *source* was rejected for the song being matched.""" 

1428 

1429 return bool(source) and str(source) in _EXCLUDED_SOURCES.get() 

1430 

1431 

1432def find_match( 

1433 song: dict[str, Any], 

1434) -> tuple[Optional[str], Optional[dict[str, Any]]]: 

1435 """Return ``(videoId, full_result)`` that best matches ``song``. 

1436 

1437 YouTube Music is searched first (see :func:`_find_youtube_music_match`) 

1438 since its catalog uploads carry the cleanest audio. Some songs are 

1439 missing there, or only present as a different recording, so when it 

1440 finds nothing — or only a hit whose length is off by more than 

1441 :data:`_STRONG_MATCH_MAX_DURATION_DIFF` — standard YouTube is searched 

1442 too (:func:`_find_match_via_youtube`). A YouTube hit replaces a weak 

1443 YouTube Music one only when its length is strictly closer. 

1444 

1445 The full result is the raw ytmusicapi search hit and is useful for 

1446 enrichment (album name, fallback cover, etc.); it is ``None`` for a 

1447 standard-YouTube match, which carries no catalog metadata. Both 

1448 elements are ``None`` if no acceptable match is found. 

1449 """ 

1450 

1451 video_id, match = _find_youtube_music_match(song) 

1452 ytm_diff = _duration_diff(song, match) 

1453 if video_id and ( 

1454 ytm_diff is None or ytm_diff <= _STRONG_MATCH_MAX_DURATION_DIFF 

1455 ): 

1456 return video_id, match 

1457 

1458 yt_video_id, yt_diff = _find_match_via_youtube(song) 

1459 if not yt_video_id: 

1460 return video_id, match 

1461 if video_id and (yt_diff is None or yt_diff >= ytm_diff): 

1462 logger.info( 

1463 'find_match keeping weak YouTube Music videoId={} (off by {}s) ' 

1464 'over YouTube videoId={} (off by {}s)', 

1465 video_id, 

1466 ytm_diff, 

1467 yt_video_id, 

1468 yt_diff, 

1469 ) 

1470 return video_id, match 

1471 logger.info( 

1472 'find_match using standard YouTube videoId={} for title={!r} ' 

1473 '(YouTube Music: {})', 

1474 yt_video_id, 

1475 song.get('name'), 

1476 f'videoId={video_id} off by {ytm_diff}s' if video_id else 'no match', 

1477 ) 

1478 return yt_video_id, None 

1479 

1480 

1481def _duration_diff( 

1482 song: dict[str, Any], result: Optional[dict[str, Any]] 

1483) -> Optional[int]: 

1484 """Seconds between ``song``'s and ``result``'s lengths, if both known.""" 

1485 

1486 if not result: 

1487 return None 

1488 target = song.get('duration') or 0 

1489 candidate = result.get('duration_seconds') or _parse_duration( 

1490 result.get('duration') 

1491 ) 

1492 if not target or not candidate: 

1493 return None 

1494 return abs(int(candidate) - int(target)) 

1495 

1496 

1497def _find_youtube_music_match( 

1498 song: dict[str, Any], 

1499) -> tuple[Optional[str], Optional[dict[str, Any]]]: 

1500 """YouTube Music half of :func:`find_match`: ``(videoId, result)``. 

1501 

1502 Searches "<artists> <title>" first, then "<title> <artists>" (see 

1503 below), then the album's tracklist. Either element may be ``None`` 

1504 if no acceptable match is found. 

1505 """ 

1506 

1507 artists = song.get('artists') or [] 

1508 artists_q = ' '.join(artists) 

1509 title = song.get('name', '') 

1510 album = song.get('album_name', '') 

1511 query = f'{artists_q} {title}'.strip() 

1512 if not query: 

1513 return None, None 

1514 duration = song.get('duration') or 0 

1515 

1516 video_id, result = _search_youtube_music_match( 

1517 query, title, artists, album, duration 

1518 ) 

1519 if video_id: 

1520 return video_id, result 

1521 

1522 # YouTube Music's ranking depends on word order: for some tracks the 

1523 # artist-first query buries the right song below what the matcher 

1524 # looks at (or omits it), while "<title> <artist>" returns it as the 

1525 # very first result. Same stages and gates, just the other order. 

1526 title_first_query = f'{title} {artists_q}'.strip() 

1527 if title and artists_q and title_first_query != query: 

1528 video_id, result = _search_youtube_music_match( 

1529 title_first_query, title, artists, album, duration 

1530 ) 

1531 if video_id: 

1532 logger.info( 

1533 'YouTube Music find_match resolved videoId={} via ' 

1534 'title-first query={!r}', 

1535 video_id, 

1536 title_first_query[:160], 

1537 ) 

1538 return video_id, result 

1539 

1540 # Text search sometimes never returns the correct video at all (see 

1541 # `_find_match_via_album`'s docstring) — try resolving it directly 

1542 # off the album's tracklist before giving up. 

1543 album_video_id, album_match = _find_match_via_album(song) 

1544 if album_video_id: 

1545 return album_video_id, album_match 

1546 logger.info( 

1547 'YouTube Music find_match: no title-matching result for ' 

1548 'query={!r} or query={!r} target_title={!r}', 

1549 query[:160], 

1550 title_first_query[:160], 

1551 title, 

1552 ) 

1553 return None, None 

1554 

1555 

1556def _search_youtube_music_match( 

1557 query: str, 

1558 title: str, 

1559 artists: list[str], 

1560 album: str, 

1561 duration: int, 

1562) -> tuple[Optional[str], Optional[dict[str, Any]]]: 

1563 """Best gated YouTube Music ``(videoId, result)`` for one ``query``. 

1564 

1565 Runs the unfiltered search (for the "Top result" card), then the 

1566 ``songs`` shelf (``videos`` when that's empty), through 

1567 :func:`_pick_best`. ``(None, None)`` when nothing qualifies. 

1568 """ 

1569 

1570 # Try an unfiltered (default) search first. Unlike the category- 

1571 # filtered searches below, this is the only request that includes 

1572 # YouTube Music's own "Top result" card — its single best guess for 

1573 # the query — and it is empirically far more reliable than the 

1574 # `songs` shelf for tracks the filtered search omits entirely (e.g. 

1575 # "Held Together" and "Fallen Wires (Remastered 2023)" are both absent 

1576 # from `filter='songs'` results for their own artist+title query, 

1577 # yet resolve instantly as the unfiltered Top result). 

1578 try: 

1579 top_results = _ytm().search(query, limit=5) 

1580 except Exception: 

1581 logger.exception('YouTube Music top-result search failed') 

1582 top_results = [] 

1583 _log_ytm_summary_search( 

1584 phase='match_top_result', 

1585 query=query, 

1586 filt='default', 

1587 results_len=len(top_results), 

1588 first_titles=[ 

1589 str(r.get('title') or '')[:60] 

1590 for r in top_results[:8] 

1591 if isinstance(r, dict) 

1592 ], 

1593 ) 

1594 _log_ytm_response(f'find_match top-result q={query[:80]!r}', top_results) 

1595 usable_top_results = [ 

1596 r 

1597 for r in top_results 

1598 if isinstance(r, dict) and r.get('resultType') in {'song', 'video'} 

1599 ] 

1600 top_best = _pick_best(usable_top_results, duration, title, artists, album) 

1601 if top_best is not None: 

1602 logger.info( 

1603 'YouTube Music find_match picked videoId={} title={!r} ' 

1604 'year={!r} via=top_result', 

1605 top_best.get('videoId'), 

1606 top_best.get('title'), 

1607 top_best.get('year'), 

1608 ) 

1609 _log_ytm_response('find_match chosen row (top result)', top_best) 

1610 return top_best.get('videoId'), top_best 

1611 

1612 try: 

1613 results = _ytm().search(query, filter='songs', limit=10) 

1614 except Exception: 

1615 logger.exception('YouTube Music match search failed') 

1616 results = [] 

1617 _log_ytm_summary_search( 

1618 phase='match_songs', 

1619 query=query, 

1620 filt='songs', 

1621 results_len=len(results), 

1622 first_titles=[ 

1623 str(r.get('title') or '')[:60] 

1624 for r in results[:8] 

1625 if isinstance(r, dict) 

1626 ], 

1627 ) 

1628 _log_ytm_response(f'find_match songs q={query[:80]!r}', results) 

1629 if not results: 

1630 try: 

1631 results = _ytm().search(query, filter='videos', limit=10) 

1632 except Exception: 

1633 results = [] 

1634 _log_ytm_summary_search( 

1635 phase='match_videos_fallback', 

1636 query=query, 

1637 filt='videos', 

1638 results_len=len(results), 

1639 first_titles=[ 

1640 str(r.get('title') or '')[:60] 

1641 for r in results[:8] 

1642 if isinstance(r, dict) 

1643 ], 

1644 ) 

1645 _log_ytm_response(f'find_match videos q={query[:80]!r}', results) 

1646 best = _pick_best(results, duration, title, artists, album) 

1647 if best is not None: 

1648 logger.info( 

1649 'YouTube Music find_match picked videoId={} title={!r} year={!r}', 

1650 best.get('videoId'), 

1651 best.get('title'), 

1652 best.get('year'), 

1653 ) 

1654 _log_ytm_response('find_match chosen row', best) 

1655 return best.get('videoId'), best 

1656 for result in results: 

1657 # Same hard title/artist requirements as `_pick_best`: never fall 

1658 # back to "the first result" if its title doesn't actually 

1659 # resemble the source track, or if it shares the title but not 

1660 # the artist (title collisions across unrelated artists happen). 

1661 if ( 

1662 result.get('videoId') 

1663 and not excluded_source(result.get('videoId')) 

1664 and (not title or _titles_match(title, result.get('title'))) 

1665 and _artists_overlap(artists, result) 

1666 ): 

1667 logger.info( 

1668 'YouTube Music find_match fallback first videoId={} title={!r}', 

1669 result.get('videoId'), 

1670 result.get('title'), 

1671 ) 

1672 _log_ytm_response('find_match fallback row', result) 

1673 return result['videoId'], result 

1674 return None, None 

1675 

1676 

1677# Channel-name decorations that aren't part of the artist's name: 

1678# auto-generated "Artist - Topic" channels, "ArtistVEVO", "Artist Official". 

1679_YOUTUBE_CHANNEL_SUFFIX_RE = re.compile( 

1680 r'\s*(?:-\s*topic|vevo|official)\s*$', re.IGNORECASE 

1681) 

1682# Separators between artists in one credit string: an upload's "A & B feat. C 

1683# - Title" head, or a packed YouTube Music entry "A, B, and C". 

1684_ARTIST_CREDIT_SPLIT_RE = re.compile( 

1685 r'\s*(?:,|&|\+|\bx\b|\bvs\.?|\band\b|\bfeat\.?|\bft\.?|\bfeaturing\b)\s*', 

1686 re.IGNORECASE, 

1687) 

1688# A featured-artist credit anywhere in a title — "(feat. X)", "[with X]", 

1689# or a bare trailing "ft. X". Spotify and YouTube uploads format these 

1690# differently, so titles are compared with it stripped from both sides. 

1691_YOUTUBE_TITLE_FEATURING_RE = re.compile( 

1692 r'\s*(?:[\(\[]\s*(?:feat\.?|ft\.?|featuring|with)\s+[^\)\]]*[\)\]]' 

1693 r'|\b(?:feat\.?|ft\.?|featuring)\s+.*$)', 

1694 re.IGNORECASE, 

1695) 

1696 

1697 

1698def _youtube_core_title(title: Any) -> str: 

1699 """``title`` without featured-artist credits, for cross-site matching.""" 

1700 

1701 value = str(title or '').replace('’', "'") 

1702 value = _YOUTUBE_TITLE_FEATURING_RE.sub('', value) 

1703 return re.sub(r'\s+', ' ', value).strip() 

1704 

1705 

1706def _youtube_search(query: str, limit: int) -> list[dict[str, Any]]: 

1707 """Flat standard-YouTube search results (``ytsearch``) via yt-dlp.""" 

1708 

1709 opts: dict[str, Any] = { 

1710 'quiet': True, 

1711 'no_warnings': True, 

1712 'skip_download': True, 

1713 'extract_flat': 'in_playlist', 

1714 } 

1715 if os.getenv('DOWNTIFY_FORCE_IPV4', '').strip() in {'1', 'true', 'yes'}: 

1716 opts['source_address'] = '0.0.0.0' 

1717 with yt_dlp.YoutubeDL(opts) as ydl: 

1718 info = ydl.extract_info(f'ytsearch{limit}:{query}', download=False) 

1719 entries = (info or {}).get('entries') or [] 

1720 return [e for e in entries if isinstance(e, dict)] 

1721 

1722 

1723def youtube_search(query: str, limit: int = 10) -> list[dict[str, Any]]: 

1724 """Standard-YouTube search results as yt-dlp lists them (``id``, 

1725 ``title``, ``channel``, ``duration``...) - for picking a version by 

1726 hand (see :mod:`downtify.audio_replace`).""" 

1727 

1728 return _youtube_search(query, limit) 

1729 

1730 

1731_SOUNDCLOUD_HOSTS = frozenset({ 

1732 'soundcloud.com', 

1733 'www.soundcloud.com', 

1734 'm.soundcloud.com', 

1735}) 

1736#: First path segments of soundcloud.com pages that aren't a user. 

1737_SOUNDCLOUD_PAGES = frozenset({ 

1738 'charts', 

1739 'discover', 

1740 'feed', 

1741 'messages', 

1742 'mobile', 

1743 'notifications', 

1744 'pages', 

1745 'people', 

1746 'search', 

1747 'settings', 

1748 'stations', 

1749 'stream', 

1750 'tags', 

1751 'terms-of-use', 

1752 'upload', 

1753 'you', 

1754}) 

1755#: Second path segments that are a tab of the user's page, not a track 

1756#: (yt-dlp's SoundCloud extractor refuses the same ones). 

1757_SOUNDCLOUD_USER_TABS = frozenset({ 

1758 'albums', 

1759 'comments', 

1760 'followers', 

1761 'following', 

1762 'likes', 

1763 'popular-tracks', 

1764 'reposts', 

1765 'sets', 

1766 'spotlight', 

1767 'tracks', 

1768}) 

1769_SOUNDCLOUD_SLUG = re.compile(r'[\w-]+') 

1770 

1771 

1772def parse_soundcloud_url(url: str) -> Optional[tuple[str, str]]: 

1773 """``('track', canonical URL)`` for a SoundCloud track link, else 

1774 ``None``. 

1775 

1776 Takes ``soundcloud.com/<user>/<track>`` (``www.``/``m.``, with or 

1777 without the scheme) and a private track's ``/<user>/<track>/s-<token>``. 

1778 Sets (albums and playlists), a user's own tabs and short 

1779 ``on.soundcloud.com`` links aren't tracks here. The canonical URL 

1780 drops the query string (the ``?si=`` share tags). 

1781 """ 

1782 

1783 text = str(url or '').strip() 

1784 if text and '://' not in text: 

1785 text = f'https://{text}' 

1786 try: 

1787 parsed = urlparse(text) 

1788 host = (parsed.hostname or '').lower() 

1789 except ValueError: 

1790 return None 

1791 if ( 

1792 parsed.scheme not in {'http', 'https'} 

1793 or parsed.username 

1794 or parsed.password 

1795 or host not in _SOUNDCLOUD_HOSTS 

1796 ): 

1797 return None 

1798 parts = [unquote(part) for part in parsed.path.split('/') if part] 

1799 private = len(parts) == 3 and parts[2].startswith('s-') 

1800 if len(parts) != 2 and not private: 

1801 return None 

1802 if ( 

1803 parts[0].lower() in _SOUNDCLOUD_PAGES 

1804 or parts[1].lower() in _SOUNDCLOUD_USER_TABS 

1805 or not all(_SOUNDCLOUD_SLUG.fullmatch(part) for part in parts) 

1806 ): 

1807 return None 

1808 return 'track', 'https://soundcloud.com/' + '/'.join(parts) 

1809 

1810 

1811def soundcloud_track_url(song: dict[str, Any]) -> Optional[str]: 

1812 """The SoundCloud track *song* is known to be, else ``None``: the 

1813 ``soundcloud_url`` a retry pasted, or the link a SoundCloud song was 

1814 resolved from.""" 

1815 

1816 candidates = [song.get('soundcloud_url')] 

1817 if song.get('source') == 'soundcloud': 

1818 candidates.append(song.get('url')) 

1819 for raw in candidates: 

1820 parsed = parse_soundcloud_url(str(raw or '')) 

1821 if parsed is not None: 

1822 return parsed[1] 

1823 return None 

1824 

1825 

1826def _soundcloud_ydl_opts(**extra: Any) -> dict[str, Any]: 

1827 """yt-dlp options for a SoundCloud lookup (never a download).""" 

1828 

1829 opts: dict[str, Any] = { 

1830 'quiet': True, 

1831 'no_warnings': True, 

1832 'skip_download': True, 

1833 'noplaylist': True, 

1834 **extra, 

1835 } 

1836 if os.getenv('DOWNTIFY_FORCE_IPV4', '').strip() in {'1', 'true', 'yes'}: 

1837 opts['source_address'] = '0.0.0.0' 

1838 return opts 

1839 

1840 

1841def _soundcloud_artist(info: dict[str, Any]) -> str: 

1842 """The credited artist (the publisher metadata) before the uploader: 

1843 a label's upload names the artist there.""" 

1844 

1845 for artist in info.get('artists') or []: 

1846 if str(artist or '').strip(): 

1847 return str(artist).strip() 

1848 return str( 

1849 info.get('artist') or info.get('uploader') or info.get('creator') or '' 

1850 ).strip() 

1851 

1852 

1853def _soundcloud_cover(info: dict[str, Any]) -> str: 

1854 """The 500 px artwork when SoundCloud has it (``original`` can be a 

1855 multi-megabyte PNG), else yt-dlp's pick.""" 

1856 

1857 thumbnails = [ 

1858 thumb 

1859 for thumb in info.get('thumbnails') or [] 

1860 if isinstance(thumb, dict) and thumb.get('url') 

1861 ] 

1862 for thumb in thumbnails: 

1863 if thumb.get('id') == 't500x500': 

1864 return str(thumb['url']) 

1865 if info.get('thumbnail'): 

1866 return str(info['thumbnail']) 

1867 return str(thumbnails[-1]['url']) if thumbnails else '' 

1868 

1869 

1870def _soundcloud_release(info: dict[str, Any]) -> tuple[str, str]: 

1871 """``(year, release_date)`` from the release date, else the upload.""" 

1872 

1873 for key in ('release_timestamp', 'timestamp'): 

1874 try: 

1875 stamp = float(info.get(key) or 0) 

1876 except (TypeError, ValueError): 

1877 continue 

1878 if stamp > 0: 

1879 date = datetime.fromtimestamp(stamp, tz=timezone.utc).date() 

1880 return str(date.year), date.isoformat() 

1881 return '', '' 

1882 

1883 

1884def soundcloud_track_from_url(url: str) -> dict[str, Any]: 

1885 """Resolve a SoundCloud track link into Downtify's song shape. 

1886 

1887 SoundCloud has no albums: a track that names none is its own album, 

1888 like a single. 

1889 """ 

1890 

1891 parsed = parse_soundcloud_url(url) 

1892 if parsed is None: 

1893 raise ValueError('Not a SoundCloud track URL') 

1894 with yt_dlp.YoutubeDL(_soundcloud_ydl_opts()) as ydl: 

1895 # process=False: the metadata, without picking a format to fetch. 

1896 info = ydl.extract_info(parsed[1], download=False, process=False) 

1897 if not isinstance(info, dict) or not str(info.get('title') or '').strip(): 

1898 raise ValueError('SoundCloud track metadata is unavailable') 

1899 title = str(info['title']).strip() 

1900 artist = _soundcloud_artist(info) 

1901 track_url = parse_soundcloud_url(str(info.get('webpage_url') or '')) 

1902 track_url = track_url[1] if track_url else parsed[1] 

1903 year, release_date = _soundcloud_release(info) 

1904 genres = [str(g).strip() for g in info.get('genres') or [] if g] 

1905 try: 

1906 duration = int(float(info.get('duration') or 0)) 

1907 except (TypeError, ValueError): 

1908 duration = 0 

1909 return { 

1910 'song_id': f'soundcloud:{info.get("id") or track_url}', 

1911 'name': title, 

1912 'artists': [artist] if artist else [], 

1913 'artist': artist, 

1914 'album_name': str(info.get('album') or '').strip() or title, 

1915 'album_artist': artist, 

1916 'cover_url': _soundcloud_cover(info), 

1917 'duration': duration, 

1918 'year': year, 

1919 'release_date': release_date, 

1920 'genre': genres[0] if genres else '', 

1921 'url': track_url, 

1922 'soundcloud_url': track_url, 

1923 'source': 'soundcloud', 

1924 } 

1925 

1926 

1927def _soundcloud_normalize(value: str) -> str: 

1928 return ''.join(char for char in value.casefold() if char.isalnum()) 

1929 

1930 

1931#: Words that mark a SoundCloud upload as another take of a song (on top 

1932#: of the YouTube ones): remixes and bootlegs are most of what a search 

1933#: there turns up. 

1934_SOUNDCLOUD_VARIANT_WORDS = ( 

1935 'bootleg', 

1936 'live', 

1937 'mashup', 

1938 'preview', 

1939 'remix', 

1940 'snippet', 

1941) 

1942 

1943 

1944def _soundcloud_is_variant(title: str, result_title: str) -> bool: 

1945 """Whether *result_title* is a variant (remix, live, cover…) that 

1946 *title* doesn't ask for.""" 

1947 

1948 wanted = title.casefold() 

1949 found = result_title.casefold() 

1950 if any(kw in found and kw not in wanted for kw in _NEGATIVE_KEYWORDS): 

1951 return True 

1952 return any( 

1953 re.search(rf'\b{word}\b', found) 

1954 and not re.search(rf'\b{word}\b', wanted) 

1955 for word in _SOUNDCLOUD_VARIANT_WORDS 

1956 ) 

1957 

1958 

1959#: Minimum title similarity (``SequenceMatcher`` ratio, 0-1) for a 

1960#: SoundCloud search result to stand in for a song. 

1961_SOUNDCLOUD_MIN_TITLE_SCORE = 0.72 

1962 

1963 

1964def _soundcloud_candidate_score( 

1965 title: str, artist: str, duration: float, entry: dict[str, Any] 

1966) -> Optional[tuple[float, str]]: 

1967 """``(title similarity, track URL)`` of a flat SoundCloud search 

1968 result that can stand in for the song, else ``None``. 

1969 

1970 The artist must appear in the uploader or the title, the length must 

1971 be within 30 s (or 20 %), and a result that isn't the original 

1972 (live, remix, cover…) only stands in for a song that says the same. 

1973 """ 

1974 

1975 result_title = str(entry.get('title') or '') 

1976 result_artist = _soundcloud_artist(entry) 

1977 normalized_title = _soundcloud_normalize(title) 

1978 normalized_result_title = _soundcloud_normalize(result_title) 

1979 normalized_artist = _soundcloud_normalize(artist) 

1980 if ( 

1981 not normalized_title 

1982 or not normalized_result_title 

1983 or not normalized_artist 

1984 ): 

1985 return None 

1986 if _soundcloud_is_variant(title, result_title): 

1987 return None 

1988 title_score = SequenceMatcher( 

1989 None, normalized_title, normalized_result_title 

1990 ).ratio() 

1991 artist_match = normalized_artist in _soundcloud_normalize( 

1992 f'{result_artist} {result_title}' 

1993 ) 

1994 if artist_match and normalized_title in normalized_result_title: 

1995 # "Artist - Track" uploads: the title holds the artist too. 

1996 title_score = max(title_score, 0.9) 

1997 try: 

1998 result_duration = float(entry.get('duration') or 0) 

1999 except (TypeError, ValueError): 

2000 result_duration = 0 

2001 duration_match = ( 

2002 not duration 

2003 or not result_duration 

2004 or abs(duration - result_duration) <= max(30, duration * 0.2) 

2005 ) 

2006 track = parse_soundcloud_url( 

2007 str(entry.get('webpage_url') or entry.get('url') or '') 

2008 ) 

2009 if ( 

2010 title_score < _SOUNDCLOUD_MIN_TITLE_SCORE 

2011 or not artist_match 

2012 or not duration_match 

2013 or track is None 

2014 ): 

2015 return None 

2016 return title_score, track[1] 

2017 

2018 

2019def find_match_soundcloud(song: dict[str, Any]) -> Optional[str]: 

2020 """The SoundCloud track URL that best stands in for *song*, or 

2021 ``None`` when no search result is close enough.""" 

2022 

2023 title = str(song.get('name') or '').strip() 

2024 artists = song.get('artists') or [] 

2025 artist = str(artists[0] if artists else song.get('artist') or '').strip() 

2026 if not title or not artist: 

2027 return None 

2028 try: 

2029 with yt_dlp.YoutubeDL( 

2030 _soundcloud_ydl_opts(extract_flat='in_playlist') 

2031 ) as ydl: 

2032 info = ydl.extract_info( 

2033 f'scsearch10:{artist} {title}', download=False 

2034 ) 

2035 except Exception: 

2036 logger.opt(exception=True).warning( 

2037 'SoundCloud search failed for {!r}', title 

2038 ) 

2039 return None 

2040 try: 

2041 duration = float(song.get('duration') or 0) 

2042 except (TypeError, ValueError): 

2043 duration = 0 

2044 candidates: list[tuple[float, str]] = [] 

2045 for entry in (info or {}).get('entries') or []: 

2046 if isinstance(entry, dict): 

2047 score = _soundcloud_candidate_score(title, artist, duration, entry) 

2048 if score is not None and not excluded_source(score[1]): 

2049 candidates.append(score) 

2050 if not candidates: 

2051 return None 

2052 # The first of equal scores: SoundCloud ranks the original higher. 

2053 return max(candidates, key=lambda candidate: candidate[0])[1] 

2054 

2055 

2056def _youtube_entry_to_result( 

2057 entry: dict[str, Any], 

2058) -> Optional[dict[str, Any]]: 

2059 """A yt-dlp search entry in the shape :func:`_pick_best` scores. 

2060 

2061 Uploads rarely credit the artist in channel metadata the way YouTube 

2062 Music does, so the artists come from an "Artist - Title" video title 

2063 (split on "&", "feat." etc., keeping the unsplit credit too so names 

2064 like "Florence and the Machine" still match) plus the channel name. 

2065 """ 

2066 

2067 video_id = entry.get('id') 

2068 if not isinstance(video_id, str) or not video_id: 

2069 return None 

2070 if entry.get('live_status') in {'is_live', 'is_upcoming', 'post_live'}: 

2071 return None 

2072 raw_title = str(entry.get('title') or '') 

2073 title, credited = _split_upload_title(raw_title, []) 

2074 # The artist isn't always the first segment: fan/OST uploads read 

2075 # "Game OST - Title - Artist", so every segment is a possible credit. 

2076 segments = _TITLE_NOISE_RE.sub('', raw_title).split(' - ') 

2077 if len(segments) > 1: 

2078 credited = [*credited, *(s.strip() for s in segments if s.strip())] 

2079 artists: list[str] = [] 

2080 for credit in credited: 

2081 artists.extend([ 

2082 credit, 

2083 *(p for p in _ARTIST_CREDIT_SPLIT_RE.split(credit) if p), 

2084 ]) 

2085 channel = _YOUTUBE_CHANNEL_SUFFIX_RE.sub( 

2086 '', str(entry.get('channel') or entry.get('uploader') or '') 

2087 ).strip() 

2088 if channel: 

2089 artists.append(channel) 

2090 unique: list[str] = [] 

2091 for artist in artists: 

2092 if artist.lower() not in {u.lower() for u in unique}: 

2093 unique.append(artist) 

2094 try: 

2095 duration = int(entry.get('duration') or 0) 

2096 except (TypeError, ValueError): 

2097 duration = 0 

2098 return { 

2099 'videoId': video_id, 

2100 'title': _youtube_core_title(title), 

2101 'artists': [{'name': a} for a in unique], 

2102 'duration_seconds': duration, 

2103 'resultType': 'video', 

2104 } 

2105 

2106 

2107def _find_match_via_youtube( 

2108 song: dict[str, Any], 

2109) -> tuple[Optional[str], Optional[int]]: 

2110 """Best standard-YouTube ``(videoId, duration_diff)`` for ``song``. 

2111 

2112 Held to the same gates as YouTube Music hits (title resemblance, 

2113 artist overlap, no karaoke/cover/sped-up variants — checked against 

2114 the raw title, before "(Official Audio)"-style noise is stripped) plus 

2115 a hard :data:`_YOUTUBE_MAX_DURATION_DIFF` length cap. ``(None, None)`` 

2116 when nothing qualifies or the search fails. 

2117 """ 

2118 

2119 artists = song.get('artists') or [] 

2120 title = song.get('name', '') 

2121 query = f'{" ".join(artists)} {title}'.strip() 

2122 if not query: 

2123 return None, None 

2124 try: 

2125 entries = _youtube_search(query, _YOUTUBE_SEARCH_LIMIT) 

2126 except Exception: 

2127 logger.exception('YouTube fallback search failed') 

2128 return None, None 

2129 

2130 target_title_l = title.lower() 

2131 candidates = [] 

2132 for entry in entries: 

2133 raw_title_l = str(entry.get('title') or '').lower() 

2134 if any( 

2135 kw in raw_title_l and kw not in target_title_l 

2136 for kw in _NEGATIVE_KEYWORDS 

2137 ): 

2138 continue 

2139 result = _youtube_entry_to_result(entry) 

2140 if result is None: 

2141 continue 

2142 diff = _duration_diff(song, result) 

2143 if diff is not None and diff > _YOUTUBE_MAX_DURATION_DIFF: 

2144 continue 

2145 candidates.append(result) 

2146 

2147 best = _pick_best( 

2148 candidates, 

2149 song.get('duration') or 0, 

2150 _youtube_core_title(title), 

2151 artists, 

2152 ) 

2153 if best is None: 

2154 logger.info( 

2155 'YouTube fallback: no acceptable result for query={!r} ' 

2156 '({} results)', 

2157 query[:160], 

2158 len(entries), 

2159 ) 

2160 return None, None 

2161 return best['videoId'], _duration_diff(song, best) 

2162 

2163 

2164def find_match_youtube_only(song: dict[str, Any]) -> Optional[str]: 

2165 """Standard-YouTube-only match, for the ``youtube`` audio provider. 

2166 

2167 Same gates as :func:`_find_match_via_youtube`; used when the provider 

2168 order puts plain YouTube on its own instead of as YouTube Music's 

2169 fallback (which :func:`find_match` already covers). 

2170 """ 

2171 

2172 video_id, _diff = _find_match_via_youtube(song) 

2173 return video_id 

2174 

2175 

2176def find_match_for_video( 

2177 song: dict[str, Any], video_id: str 

2178) -> Optional[dict[str, Any]]: 

2179 """Find the ytmusicapi search result that matches a known videoId. 

2180 

2181 Used when the caller already has a target video and wants to enrich 

2182 metadata without risking switching to a different track. 

2183 """ 

2184 

2185 artists = ' '.join(song.get('artists') or []) 

2186 title = song.get('name', '') 

2187 query = f'{artists} {title}'.strip() 

2188 if not query: 

2189 return None 

2190 try: 

2191 results = _ytm().search(query, filter='songs', limit=10) 

2192 except Exception: 

2193 logger.opt(exception=True).debug('match-by-video search failed') 

2194 return None 

2195 _log_ytm_response( 

2196 f'find_match_for_video vid={video_id} q={query[:80]!r}', results 

2197 ) 

2198 for result in results: 

2199 if result.get('videoId') == video_id: 

2200 logger.info( 

2201 'YouTube Music find_match_for_video hit video={} title={!r}', 

2202 video_id, 

2203 result.get('title'), 

2204 ) 

2205 _log_ytm_response(f'YT match row video={video_id}', result) 

2206 return result 

2207 logger.info( 

2208 'YouTube Music find_match_for_video: no hit for {} in {} results', 

2209 video_id, 

2210 len(results), 

2211 ) 

2212 return None 

2213 

2214 

2215def _norm_compact_title(value: Any) -> str: 

2216 """Lowercase collapsed title for forgiving comparisons.""" 

2217 

2218 return re.sub(r'\s+', ' ', str(value or '').casefold()).strip() 

2219 

2220 

2221# Qualifiers that mark a genuinely different recording — a different 

2222# performance or edit, not just a different pressing of the same audio. 

2223# When one name is a prefix of the other (e.g. "Amber Field" vs "Local 

2224# Valley (Deluxe)"), the extra text is tolerated *unless* it contains one 

2225# of these — a plain "Fernglow" must never match "Fernglow (DJ Koze Remix)". 

2226# Extend this list as new special cases turn up. 

2227_VERSION_QUALIFIER_WORDS = ( 

2228 'live', 

2229 'remix', 

2230 'cover', 

2231 'karaoke', 

2232 'acoustic', 

2233 'unplugged', 

2234 'demo', 

2235 'instrumental', 

2236 'tribute', 

2237 'ao vivo', 

2238 'en vivo', 

2239 'acústico', 

2240 'acustico', 

2241 # A song sung in another language is a different recording: a 

2242 # "(Spanish Version)" must never stand in for the original. 

2243 'spanish', 

2244 'español', 

2245 'espanol', 

2246 'english', 

2247 'inglés', 

2248 'ingles', 

2249 'portuguese', 

2250 'português', 

2251 'portugues', 

2252 'french', 

2253 'français', 

2254 'francais', 

2255 'italian', 

2256 'italiano', 

2257 'german', 

2258 'japanese', 

2259 'korean', 

2260 'chinese', 

2261) 

2262_VERSION_QUALIFIER_RE = re.compile( 

2263 r'\b(' + '|'.join(_VERSION_QUALIFIER_WORDS) + r')\b' 

2264) 

2265# Spotify writes a version as a dash suffix ("Tubarões - Ao Vivo", 

2266# "Song - Remastered 2011") where YouTube Music uses parentheses 

2267# ("Tubarões (Ao Vivo)"); only the last " - " segment is rewritten. 

2268_DASH_VERSION_SUFFIX_RE = re.compile(r'^(.*\S)\s+-\s+([^()\[\]]+?)$') 

2269 

2270 

2271def _names_match(target: Any, candidate: Any) -> bool: 

2272 """True when two free-text names (title or album) refer to the same release. 

2273 

2274 An exact normalized match always counts. Otherwise one name may be a 

2275 prefix of the other, tolerating cosmetic edition tags a reissue adds 

2276 without changing the underlying content (``"(Deluxe)"``, 

2277 ``"(Remastered 2023)"``, ``"(Anniversary Edition)"``). The extra 

2278 text is rejected, however, if it names a genuinely different 

2279 recording — see :data:`_VERSION_QUALIFIER_WORDS`. A common prefix 

2280 shorter than 4 characters is never accepted, so short unrelated 

2281 names don't collide (``"U"`` must not match ``"Unplugged"``). 

2282 Both names are compared with a trailing " - Suffix" rewritten as 

2283 " (Suffix)" — see :data:`_DASH_VERSION_SUFFIX_RE`. 

2284 """ 

2285 

2286 t = _norm_compact_title(target) 

2287 c = _norm_compact_title(candidate) 

2288 if _normalized_names_match( 

2289 _DASH_VERSION_SUFFIX_RE.sub(r'\1 (\2)', t), 

2290 _DASH_VERSION_SUFFIX_RE.sub(r'\1 (\2)', c), 

2291 ): 

2292 return True 

2293 # The rewrite only touches the last " - " segment, so a name that itself 

2294 # contains " - " can be rewritten on one side but not on the other (a 

2295 # "(feat. …)" suffix blocks it); compare the plain forms as well. Only a 

2296 # bracketed tag may follow the shared name there: text that continues 

2297 # its last segment ("- Live" vs "- Live at Wembley") names another take. 

2298 shorter, longer = sorted((t, c), key=len) 

2299 tail = longer[len(shorter) :].lstrip() 

2300 return tail.startswith(('(', '[')) and _normalized_names_match(t, c) 

2301 

2302 

2303def _normalized_names_match(t: str, c: str) -> bool: 

2304 if not t or not c: 

2305 return False 

2306 if t == c: 

2307 return True 

2308 shorter, longer = sorted((t, c), key=len) 

2309 if len(shorter) < 4 or not longer.startswith(shorter): 

2310 return False 

2311 tail = longer[len(shorter) :] 

2312 return not _VERSION_QUALIFIER_RE.search(tail) 

2313 

2314 

2315def _albums_match(target: Any, candidate: Any) -> bool: 

2316 """True when two album names refer to the same release. See :func:`_names_match`.""" 

2317 

2318 return _names_match(target, candidate) 

2319 

2320 

2321def _titles_match(target: Any, candidate: Any) -> bool: 

2322 """True when two song titles refer to the same recording. See :func:`_names_match`. 

2323 

2324 A title may also match one " - "-separated segment of the other: 

2325 uploads bundle extra text that way — "くちづけDiamond - Kuchizuke 

2326 Diamond" (native script and romanization), "Smash Hit OST - Smash Hit 

2327 Theme Full Version - Douglas Holmquist" (game, title, artist). The 

2328 segment must start with the whole title (so "Smash Hit" never matches 

2329 "Smash Hit Theme"), and the remaining segments must not name a 

2330 different recording ("Yellow - Live" is still not "Yellow"). 

2331 """ 

2332 

2333 if _names_match(target, candidate): 

2334 return True 

2335 for whole, segmented in ((target, candidate), (candidate, target)): 

2336 whole_norm = _DASH_VERSION_SUFFIX_RE.sub( 

2337 r'\1 (\2)', _norm_compact_title(whole) 

2338 ) 

2339 segments = _norm_compact_title(segmented).split(' - ') 

2340 if not whole_norm or len(segments) < 2: 

2341 continue 

2342 for i, segment in enumerate(segments): 

2343 rest = ' '.join(segments[:i] + segments[i + 1 :]) 

2344 if ( 

2345 segment.startswith(whole_norm) 

2346 and _names_match(whole_norm, segment) 

2347 and not _VERSION_QUALIFIER_RE.search(rest) 

2348 ): 

2349 return True 

2350 return False 

2351 

2352 

2353def _album_title_hints( 

2354 match: dict[str, Any], song: Optional[dict[str, Any]] 

2355) -> list[str]: 

2356 hints: list[str] = [] 

2357 album = match.get('album') 

2358 if isinstance(album, dict): 

2359 n = str(album.get('name') or '').strip() 

2360 if n: 

2361 hints.append(n) 

2362 if song: 

2363 n = str(song.get('album_name') or '').strip() 

2364 if n and n not in hints: 

2365 hints.append(n) 

2366 # de-dupe while keeping order 

2367 seen: set[str] = set() 

2368 out: list[str] = [] 

2369 for h in hints: 

2370 k = h.casefold() 

2371 if k not in seen: 

2372 seen.add(k) 

2373 out.append(h) 

2374 return out 

2375 

2376 

2377def _primary_artist_for_search( 

2378 match: dict[str, Any], song: Optional[dict[str, Any]] 

2379) -> str: 

2380 if song: 

2381 artists = song.get('artists') or [] 

2382 if isinstance(artists, list) and artists: 

2383 a0 = artists[0] 

2384 if isinstance(a0, str) and a0.strip(): 

2385 return a0.strip() 

2386 for a in match.get('artists') or []: 

2387 if isinstance(a, dict): 

2388 nm = str(a.get('name') or '').strip() 

2389 if nm: 

2390 return nm 

2391 return '' 

2392 

2393 

2394def _album_browse_id_from_search( 

2395 match: dict[str, Any], 

2396 song: Optional[dict[str, Any]], 

2397) -> str: 

2398 titles = _album_title_hints(match, song) 

2399 if not titles: 

2400 return '' 

2401 primary = _primary_artist_for_search(match, song) 

2402 cache_key = f'{primary.casefold()}|{_norm_compact_title(titles[0])}' 

2403 with _lock: 

2404 cached = _album_browse_search_cache.get(cache_key) 

2405 if cached: 

2406 return cached 

2407 q_chunks = [] 

2408 if primary: 

2409 q_chunks.append(primary) 

2410 q_chunks.extend(titles) 

2411 query = ' '.join(q_chunks).strip() 

2412 try: 

2413 results = _ytm().search(query, filter='albums', limit=20) 

2414 except Exception: 

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

2416 'YouTube Music album search failed', 

2417 ) 

2418 return '' 

2419 result_titles = [ 

2420 str(r.get('title') or '')[:60] 

2421 for r in results[:10] 

2422 if isinstance(r, dict) 

2423 ] 

2424 logger.info( 

2425 'YouTube Music album search title_match q={!r} hits={} sample_titles={}', 

2426 query[:120], 

2427 len(results), 

2428 result_titles, 

2429 ) 

2430 _log_ytm_response(f'albums search titles={result_titles!r}', results) 

2431 # Match against the *original* title hints we were looking for — not 

2432 # the search results' own titles (that used to shadow `titles` here, 

2433 # making this check a no-op that always accepted the first result 

2434 # regardless of whether it was actually the right album). 

2435 want = {_norm_compact_title(t) for t in titles if t.strip()} 

2436 for r in results: 

2437 if not isinstance(r, dict): 

2438 continue 

2439 browse = r.get('browseId') 

2440 if not isinstance(browse, str) or not browse.strip(): 

2441 continue 

2442 rt = _norm_compact_title(r.get('title')) 

2443 if rt and rt in want: 

2444 bid = browse.strip() 

2445 with _lock: 

2446 _album_browse_search_cache[cache_key] = bid 

2447 return bid 

2448 return '' 

2449 

2450 

2451def _album_browse_id( 

2452 match: dict[str, Any], 

2453 song: Optional[dict[str, Any]], 

2454) -> str: 

2455 album = match.get('album') 

2456 if isinstance(album, dict): 

2457 for key in ('id', 'browseId'): 

2458 raw = album.get(key) 

2459 if isinstance(raw, str) and raw.strip(): 

2460 return raw.strip() 

2461 return _album_browse_id_from_search(match, song) 

2462 

2463 

2464def _row_video_id(row: dict[str, Any]) -> Optional[str]: 

2465 vid = row.get('videoId') 

2466 if isinstance(vid, str) and len(vid.strip()) >= 11: 

2467 return vid.strip() 

2468 return None 

2469 

2470 

2471def _pick_album_track_row( 

2472 tracks: list[dict[str, Any]], 

2473 video_id: str, 

2474 match: dict[str, Any], 

2475 song: Optional[dict[str, Any]], 

2476) -> tuple[Optional[int], Optional[dict[str, Any]]]: 

2477 """Return ``(list_position 1-based, row)`` for the downloaded video.""" 

2478 

2479 for position, row in enumerate(tracks, start=1): 

2480 if isinstance(row, dict) and _row_video_id(row) == video_id: 

2481 return position, row 

2482 name_norms: set[str] = { 

2483 _norm_compact_title(match.get('title')), 

2484 _norm_compact_title((song or {}).get('name') if song else ''), 

2485 } 

2486 name_norms.discard('') 

2487 if not name_norms: 

2488 return None, None 

2489 hits = [ 

2490 (position, row) 

2491 for position, row in enumerate(tracks, start=1) 

2492 if isinstance(row, dict) 

2493 and _norm_compact_title(row.get('title')) in name_norms 

2494 ] 

2495 if len(hits) == 1: 

2496 return hits[0][0], hits[0][1] 

2497 return None, None 

2498 

2499 

2500def _normalize_ytm_track_slot( 

2501 *, 

2502 declared: Any, 

2503 position_in_album_list: int, 

2504) -> Optional[int]: 

2505 """Return a 1-based track index for tagging. 

2506 

2507 ytmusicapi copies ``trackNumber`` from YouTube's payload (sometimes 

2508 1-based). When it is absent or ``<= 0``, use ordinal position in the 

2509 album's track listing instead. 

2510 """ 

2511 if position_in_album_list <= 0: 

2512 return None 

2513 try: 

2514 n = int(declared) 

2515 except (TypeError, ValueError): 

2516 return position_in_album_list 

2517 if n <= 0: 

2518 return position_in_album_list 

2519 return n 

2520 

2521 

2522def _cached_album_tracks_and_count( 

2523 browse_id: str, 

2524) -> tuple[list[dict[str, Any]], Optional[int]]: 

2525 with _lock: 

2526 hit = _album_track_cache.get(browse_id) 

2527 if hit is not None: 

2528 return hit 

2529 try: 

2530 data = _ytm().get_album(browse_id) or {} 

2531 except Exception: 

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

2533 'YouTube Music get_album failed for {}', browse_id 

2534 ) 

2535 empty: tuple[list[dict[str, Any]], Optional[int]] = ([], None) 

2536 return empty 

2537 

2538 tracks = [t for t in (data.get('tracks') or []) if isinstance(t, dict)] 

2539 logger.info( 

2540 'YouTube Music get_album browseId={!r} title={!r} year={!r} ' 

2541 'trackCount={} parsed_tracks_len={}', 

2542 browse_id, 

2543 data.get('title'), 

2544 data.get('year'), 

2545 data.get('trackCount'), 

2546 len(tracks), 

2547 ) 

2548 _log_ytm_response(f'get_album {browse_id}', data) 

2549 total_ct: Optional[int] = None 

2550 raw_tc = data.get('trackCount') 

2551 try: 

2552 if raw_tc is not None: 

2553 iv = int(raw_tc) 

2554 if iv > 0: 

2555 total_ct = iv 

2556 except (TypeError, ValueError): 

2557 total_ct = None 

2558 if not total_ct and tracks: 

2559 total_ct = len(tracks) 

2560 artists = _credited_artist_names(data.get('artists')) 

2561 tup = (tracks, total_ct) 

2562 with _lock: 

2563 _album_track_cache[browse_id] = tup 

2564 if not artists: 

2565 # get_album's own response doesn't always carry an `artists` 

2566 # field — fall back to what the earlier albums-filter search 

2567 # for this same browse id already told us (search_albums / 

2568 # _album_summary), rather than losing it. 

2569 artists = list(_album_search_artist_cache.get(browse_id) or []) 

2570 _album_meta_cache[browse_id] = { 

2571 'title': data.get('title') or '', 

2572 'year': str(data.get('year') or '').strip(), 

2573 'thumbnails': data.get('thumbnails') or [], 

2574 # 'Album' / 'Single' / 'EP' — YouTube Music's own release 

2575 # classification. 

2576 'type': data.get('type') or '', 

2577 'artists': artists, 

2578 } 

2579 return tup 

2580 

2581 

2582def _cached_album_meta(browse_id: str) -> dict[str, Any]: 

2583 """Album-level metadata for ``browse_id``, if already resolved and cached. 

2584 

2585 Only ever a cache read — populated as a side effect of 

2586 :func:`_cached_album_tracks_and_count`, never triggers its own 

2587 ``get_album`` call. 

2588 """ 

2589 

2590 with _lock: 

2591 return dict(_album_meta_cache.get(browse_id) or {}) 

2592 

2593 

2594def _cached_album_title(browse_id: str) -> str: 

2595 return _cached_album_meta(browse_id).get('title', '') 

2596 

2597 

2598def _cached_album_release_type(browse_id: str) -> str: 

2599 return _cached_album_meta(browse_id).get('type', '') 

2600 

2601 

2602def _cached_album_year(browse_id: str) -> str: 

2603 return _cached_album_meta(browse_id).get('year', '') 

2604 

2605 

2606# Separators YouTube Music uses when it collapses a featuring artist into 

2607# a single combined-name entry instead of a separate artist dict. 

2608# "and"/","/"with"/"x" are deliberately excluded even though YouTube 

2609# Music uses them too, because they routinely appear inside real band 

2610# names (e.g. a duo named "Harbor and the Wren") and could get mis-split 

2611# if the album's own metadata is ever internally inconsistent about the 

2612# artist name used as the anchor below. "&" carries the same risk but is 

2613# kept anyway since it's the single most common combined-name pattern in 

2614# practice, and the anchor check already guards against the common case. 

2615_FEATURING_ARTIST_SEPARATORS = ( 

2616 ' feat. ', 

2617 ' feat ', 

2618 ' featuring ', 

2619 ' ft. ', 

2620 ' ft ', 

2621 ' & ', 

2622) 

2623 

2624 

2625def _split_combined_featuring_artist( 

2626 artists: list[str], album_artists: list[str] 

2627) -> list[str]: 

2628 """Split a "Primary feat. Featured" combined name YouTube Music 

2629 sometimes returns as a single artist entry (no separate channel id) 

2630 for featuring tracks — instead of the usual one-dict-per-artist list. 

2631 

2632 Only splits when the combined name is prefixed by an artist already 

2633 known to be on the album, so genuine band names aren't mistakenly 

2634 split apart. 

2635 """ 

2636 if len(artists) != 1: 

2637 return artists 

2638 name = artists[0] 

2639 name_lower = name.lower() 

2640 for album_artist in album_artists: 

2641 for sep in _FEATURING_ARTIST_SEPARATORS: 

2642 prefix = f'{album_artist}{sep}' 

2643 if name_lower.startswith(prefix.lower()): 

2644 featured = name[len(prefix) :].strip() 

2645 if featured: 

2646 return [album_artist, featured] 

2647 return artists 

2648 

2649 

2650# Matches a trailing "(feat. X)" / "(ft. X)" / "(featuring X)" — with 

2651# either parenthesis or square-bracket style — at the end of a title. 

2652_TITLE_FEATURING_RE = re.compile( 

2653 r'[\(\[]\s*(?:feat\.?|ft\.?|featuring)\s+(.+?)\s*[\)\]]\s*$', 

2654 re.IGNORECASE, 

2655) 

2656 

2657 

2658def _extract_title_featuring_artist( 

2659 title: str, artists: list[str] 

2660) -> list[str]: 

2661 """Add a featured artist named in the title's "(feat. X)" suffix to 

2662 ``artists``, for the case where YouTube Music's own artists list 

2663 doesn't credit them at all — e.g. a track titled "Better Way To Live 

2664 (feat. Grian Chatten)" whose ``artists`` is just ``[{"name": 

2665 "KNEECAP"}]``, with no entry whatsoever for the featured artist. 

2666 """ 

2667 match = _TITLE_FEATURING_RE.search(title or '') 

2668 if not match: 

2669 return artists 

2670 featured = match.group(1).strip() 

2671 if not featured: 

2672 return artists 

2673 existing = {a.lower() for a in artists} 

2674 if featured.lower() in existing: 

2675 return artists 

2676 return [*artists, featured] 

2677 

2678 

2679# YouTube Music's own classification of a track's upload (see 

2680# `get_album`/search results' `videoType` field): "ATV" is a studio 

2681# recording uploaded by the artist with static cover art — the actual 

2682# album/single release. "OMV" is a genuine music video, which often uses 

2683# a different edit of the song (extended or spoken intro, alternate 

2684# mix) than the album version, even though it's nominally "the same 

2685# track". ytmusicapi doesn't expose both alternatives on one track 

2686# entry, so swapping requires a follow-up search. 

2687_MUSIC_VIDEO_TYPE_OFFICIAL_AUDIO = 'MUSIC_VIDEO_TYPE_ATV' 

2688_MUSIC_VIDEO_TYPE_MUSIC_VIDEO = 'MUSIC_VIDEO_TYPE_OMV' 

2689 

2690 

2691def _prefer_official_audio_track( 

2692 video_id: str, 

2693 duration: int, 

2694 title: str, 

2695 artists: list[str], 

2696 video_type: str, 

2697) -> tuple[str, int]: 

2698 """Swap a music-video (OMV) track for its official-audio (ATV) 

2699 counterpart when one can be found, since the video edit sometimes 

2700 differs from the actual album recording. Returns the original 

2701 ``(video_id, duration)`` unchanged when the track isn't an OMV, or 

2702 when no matching ATV alternative turns up. 

2703 """ 

2704 if video_type != _MUSIC_VIDEO_TYPE_MUSIC_VIDEO: 

2705 return video_id, duration 

2706 with _lock: 

2707 cached = _omv_preference_cache.get(video_id) 

2708 if cached is not None: 

2709 return cached 

2710 query = f'{" ".join(artists)} {title}'.strip() 

2711 if not query: 

2712 return video_id, duration 

2713 try: 

2714 results = _ytm().search(query, filter='songs', limit=10) 

2715 except Exception: 

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

2717 'Official-audio preference search failed for {!r}', title 

2718 ) 

2719 return video_id, duration 

2720 for result in results: 

2721 if not isinstance(result, dict): 

2722 continue 

2723 if result.get('videoType') != _MUSIC_VIDEO_TYPE_OFFICIAL_AUDIO: 

2724 continue 

2725 if not _titles_match(title, result.get('title')): 

2726 continue 

2727 if not _artists_overlap(artists, result): 

2728 continue 

2729 candidate = result.get('videoId') 

2730 if not (isinstance(candidate, str) and candidate.strip()): 

2731 continue 

2732 candidate_duration = result.get('duration_seconds') or _parse_duration( 

2733 result.get('duration') 

2734 ) 

2735 logger.info( 

2736 'Preferring official-audio (ATV) videoId={} over music-video ' 

2737 '(OMV) videoId={} for title={!r}', 

2738 candidate, 

2739 video_id, 

2740 title, 

2741 ) 

2742 chosen = (candidate.strip(), (candidate_duration or duration)) 

2743 with _lock: 

2744 _omv_preference_cache[video_id] = chosen 

2745 return chosen 

2746 with _lock: 

2747 _omv_preference_cache[video_id] = (video_id, duration) 

2748 return video_id, duration 

2749 

2750 

2751def _album_track_song( 

2752 track: dict[str, Any], 

2753 video_id: str, 

2754 position: int, 

2755 total: int, 

2756 meta: dict[str, Any], 

2757) -> dict[str, Any]: 

2758 """Build one album-track song dict, given the album's cached metadata.""" 

2759 

2760 artists = _credited_artist_names(track.get('artists')) 

2761 artists = _split_combined_featuring_artist( 

2762 artists, meta.get('artists') or [] 

2763 ) 

2764 artists = _extract_title_featuring_artist(track.get('title', ''), artists) 

2765 title = track.get('title', '') 

2766 duration = track.get('duration_seconds') or _parse_duration( 

2767 track.get('duration') 

2768 ) 

2769 video_id, duration = _prefer_official_audio_track( 

2770 video_id, duration, title, artists, track.get('videoType', '') 

2771 ) 

2772 year = meta.get('year', '') 

2773 thumbs = meta.get('thumbnails') or [] 

2774 cover = _upgrade_thumbnail(thumbs[-1].get('url', '')) if thumbs else '' 

2775 track_number = _normalize_ytm_track_slot( 

2776 declared=track.get('trackNumber'), position_in_album_list=position 

2777 ) 

2778 return { 

2779 'song_id': video_id, 

2780 'name': title, 

2781 'artists': artists, 

2782 'artist': ', '.join(artists), 

2783 'album_name': meta.get('title', ''), 

2784 'cover_url': cover, 

2785 'duration': duration, 

2786 'url': f'https://music.youtube.com/watch?v={video_id}', 

2787 'explicit': bool(track.get('isExplicit')), 

2788 'year': year, 

2789 'release_date': year, 

2790 'source': 'youtube', 

2791 'track_number': track_number, 

2792 'album_track_total': total, 

2793 'release_type': meta.get('type', ''), 

2794 # The album's own (first) artist, so every track in the album gets 

2795 # the same "album artist" tag even when a track's own `artists` 

2796 # differs (a feature, a remix credit, ...) - "Various Artists", 

2797 # plus `compilation`, for a compilation. See `album_artist.py`. 

2798 **album_artist_fields((meta.get('artists') or [''])[0]), 

2799 } 

2800 

2801 

2802def album_tracks_from_browse_id( 

2803 browse_id_or_playlist_id: str, 

2804) -> list[dict[str, Any]]: 

2805 """Resolve a YouTube Music album into Spotify-shaped song dicts. 

2806 

2807 Accepts either a ``MPREb_`` browse id or an ``OLAK5uy_`` audio 

2808 playlist id (converted to a browse id first via 

2809 ``get_album_browse_id``). Mirrors 

2810 :func:`spotify.album_tracks_from_id`'s output shape so the same 

2811 batch-download/M3U frontend code path works unchanged for a 

2812 directly-pasted YouTube Music album URL. Returns ``[]`` if the 

2813 album can't be resolved at all. 

2814 """ 

2815 

2816 browse_id = browse_id_or_playlist_id 

2817 if browse_id.startswith('OLAK5uy_'): 

2818 try: 

2819 resolved = _ytm().get_album_browse_id(browse_id) 

2820 except Exception: 

2821 logger.exception( 

2822 'YouTube Music get_album_browse_id failed for {}', browse_id 

2823 ) 

2824 resolved = None 

2825 if not resolved: 

2826 return [] 

2827 browse_id = resolved 

2828 

2829 tracks, total_ct = _cached_album_tracks_and_count(browse_id) 

2830 if not tracks: 

2831 return [] 

2832 total = total_ct or len(tracks) 

2833 meta = _cached_album_meta(browse_id) 

2834 

2835 songs: list[dict[str, Any]] = [] 

2836 for position, track in enumerate(tracks, start=1): 

2837 video_id = _row_video_id(track) 

2838 if not video_id: 

2839 continue 

2840 songs.append(_album_track_song(track, video_id, position, total, meta)) 

2841 return songs 

2842 

2843 

2844def _find_match_via_album( 

2845 song: dict[str, Any], 

2846) -> tuple[Optional[str], Optional[dict[str, Any]]]: 

2847 """Resolve a track by scanning its album's tracklist directly. 

2848 

2849 YouTube Music's text search occasionally omits the correct video 

2850 from an "artist + title" query's own results entirely — e.g. 

2851 searching "Mica Ferreira Held Together" never surfaces "Held Together" itself, 

2852 while surfacing an unrelated track by the same artist (confirmed by 

2853 inspecting the raw search payload). When the source album is known, 

2854 resolving it via the ``albums`` filter and scanning its full 

2855 :func:`_cached_album_tracks_and_count` listing sidesteps that 

2856 search-relevance quirk entirely, since the tracklist is keyed by 

2857 album rather than by a fuzzy text query. 

2858 """ 

2859 

2860 title = song.get('name', '') 

2861 album_name = str(song.get('album_name') or '').strip() 

2862 if not title or not album_name: 

2863 return None, None 

2864 

2865 browse_id = _album_browse_id_from_search({}, song) 

2866 if not browse_id: 

2867 return None, None 

2868 

2869 tracks, _total = _cached_album_tracks_and_count(browse_id) 

2870 for track in tracks: 

2871 if not isinstance(track, dict): 

2872 continue 

2873 video_id = _row_video_id(track) 

2874 if not video_id or excluded_source(video_id): 

2875 continue 

2876 if _titles_match(title, track.get('title')): 

2877 logger.info( 

2878 'YouTube Music find_match album-tracklist fallback hit ' 

2879 'browseId={!r} videoId={} title={!r}', 

2880 browse_id, 

2881 video_id, 

2882 track.get('title'), 

2883 ) 

2884 return video_id, track 

2885 logger.info( 

2886 'YouTube Music find_match album-tracklist fallback: no title ' 

2887 'match in browseId={!r} for title={!r}', 

2888 browse_id, 

2889 title, 

2890 ) 

2891 return None, None 

2892 

2893 

2894def youtube_music_track_index_for_match( 

2895 match: Optional[dict[str, Any]], 

2896 song: Optional[dict[str, Any]] = None, 

2897) -> tuple[Optional[int], Optional[int]]: 

2898 """Resolve ``(track_number, album_track_total)`` from YouTube Music. 

2899 

2900 Uses ``album.id`` on the search hit when present; otherwise resolves the 

2901 release via an ``albums`` search so ``get_album`` can run anyway. 

2902 """ 

2903 

2904 if not isinstance(match, dict): 

2905 logger.debug('YTM track_index: match is not a dict') 

2906 return None, None 

2907 video_id = match.get('videoId') 

2908 if not isinstance(video_id, str) or not video_id.strip(): 

2909 logger.info( 

2910 'YTM track_index: missing videoId on match title={!r}', 

2911 match.get('title'), 

2912 ) 

2913 return None, None 

2914 vid = video_id.strip() 

2915 browse_id = _album_browse_id(match, song) 

2916 if not browse_id: 

2917 logger.info( 

2918 'YTM track_index: cannot resolve album browseId for ' 

2919 'video={!r} spotify_title={!r} match_album={!r} ' 

2920 'spotify_album_name={!r}', 

2921 vid, 

2922 match.get('title'), 

2923 match.get('album'), 

2924 (song or {}).get('album_name'), 

2925 ) 

2926 return None, None 

2927 tracks, total_ct = _cached_album_tracks_and_count(browse_id) 

2928 if not tracks: 

2929 logger.info( 

2930 'YTM track_index: get_album returned zero tracks browseId={!r} ' 

2931 'declared_trackCount={}', 

2932 browse_id, 

2933 total_ct, 

2934 ) 

2935 return None, total_ct 

2936 

2937 fb_total = total_ct if (total_ct and total_ct > 0) else len(tracks) 

2938 position, row = _pick_album_track_row(tracks, vid, match, song) 

2939 if row is None or position is None: 

2940 sample = [_row_video_id(t) or '?' for t in tracks[:6]] 

2941 mtitle = _norm_compact_title(match.get('title')) 

2942 title_matches = sum( 

2943 1 

2944 for t in tracks 

2945 if isinstance(t, dict) 

2946 and _norm_compact_title(t.get('title')) == mtitle 

2947 ) 

2948 logger.info( 

2949 'YTM track_index: video {!r} not matched in album {}; ' 

2950 'match_title={!r} candidate_videoIds(sample)={} ' 

2951 'same_title_row_count={}', 

2952 vid, 

2953 browse_id, 

2954 match.get('title'), 

2955 sample, 

2956 title_matches, 

2957 ) 

2958 return None, fb_total 

2959 tn = _normalize_ytm_track_slot( 

2960 declared=row.get('trackNumber'), 

2961 position_in_album_list=position, 

2962 ) 

2963 logger.debug( 

2964 'YTM track_index OK video={} browseId={} tn={} total={}', 

2965 vid, 

2966 browse_id, 

2967 tn, 

2968 fb_total, 

2969 ) 

2970 return tn, fb_total 

2971 

2972 

2973def enrich_from_match( 

2974 song: dict[str, Any], match: Optional[dict[str, Any]] 

2975) -> dict[str, Any]: 

2976 """Fill metadata gaps from YT Music hit; resolve track index via get_album.""" 

2977 

2978 if not match: 

2979 return song 

2980 _log_ytm_response( 

2981 f'enrich_from_match spotify_title={song.get("name")!r}', 

2982 match, 

2983 ) 

2984 enriched = dict(song) 

2985 # The mark describes the audio that gets downloaded, which is this hit: 

2986 # explicit if either source says so, never un-marked by the match. 

2987 if match.get('isExplicit'): 

2988 enriched['explicit'] = True 

2989 if not enriched.get('album_name'): 

2990 album = match.get('album') or {} 

2991 if isinstance(album, dict) and album.get('name'): 

2992 enriched['album_name'] = album['name'] 

2993 if not enriched.get('cover_url'): 

2994 thumbs = match.get('thumbnails') or [] 

2995 if thumbs: 

2996 enriched['cover_url'] = _upgrade_thumbnail( 

2997 thumbs[-1].get('url', '') 

2998 ) 

2999 if not enriched.get('year') and match.get('year'): 

3000 enriched['year'] = str(match['year']) 

3001 if not enriched.get('release_date'): 

3002 y = str(enriched.get('year') or '').strip() 

3003 if len(y) == 4 and y.isdigit(): 

3004 enriched['release_date'] = y 

3005 if not enriched.get('artists'): 

3006 yt_meta = _result_to_song(match) 

3007 if yt_meta and yt_meta.get('artists'): 

3008 enriched['artists'] = yt_meta['artists'] 

3009 enriched['artist'] = ', '.join(yt_meta['artists']) 

3010 yt_n, yt_tot = youtube_music_track_index_for_match(match, enriched) 

3011 if yt_n is not None: 

3012 enriched.setdefault('track_number', yt_n) 

3013 if yt_tot is not None: 

3014 enriched.setdefault('album_track_total', yt_tot) 

3015 _need_year = not str(enriched.get('year') or '').strip() 

3016 if ( 

3017 not enriched.get('album_name') 

3018 or not enriched.get('release_type') 

3019 or _need_year 

3020 ): 

3021 # `youtube_music_track_index_for_match` already resolved (and 

3022 # cached) the album's browseId while computing the track index 

3023 # above — reuse it to backfill the album title, release type 

3024 # and year too, since the search-derived `match` sometimes 

3025 # lacks `album.name` and a `year` even when the video is 

3026 # genuinely part of a catalogued release. 

3027 browse_id = _album_browse_id(match, enriched) 

3028 if browse_id: 

3029 if not enriched.get('album_name'): 

3030 album_title = _cached_album_title(browse_id) 

3031 if album_title: 

3032 enriched['album_name'] = album_title 

3033 if not enriched.get('release_type'): 

3034 release_type = _cached_album_release_type(browse_id) 

3035 if release_type: 

3036 enriched['release_type'] = release_type 

3037 if _need_year: 

3038 album_year = _cached_album_year(browse_id) 

3039 if len(album_year) == 4 and album_year.isdigit(): 

3040 enriched['year'] = album_year 

3041 if not str(enriched.get('release_date') or '').strip(): 

3042 enriched['release_date'] = album_year 

3043 # Deliberately no album artist from the match's album: YouTube Music 

3044 # links one audio video to whichever of the releases sharing it it 

3045 # likes (often a compilation that doesn't even list that video), so 

3046 # it can't tell a track's own album artist - or that its album is a 

3047 # compilation. Only an album download (`_album_track_song`) knows that. 

3048 spotify_tid = enriched.get('song_id') 

3049 if yt_n is None: 

3050 logger.info( 

3051 'YTM enrich: no track_number resolved for Spotify id={} title={!r}', 

3052 spotify_tid, 

3053 enriched.get('name'), 

3054 ) 

3055 yr_ok = bool(str(enriched.get('year') or '').strip()) or bool( 

3056 str(enriched.get('release_date') or '').strip() 

3057 ) 

3058 match_yr = match.get('year') 

3059 if not yr_ok: 

3060 logger.info( 

3061 'YTM enrich: still no year after match for title={!r} ' 

3062 'match.year={!r}', 

3063 enriched.get('name'), 

3064 match_yr, 

3065 ) 

3066 return enriched 

3067 

3068 

3069def _artists_overlap( 

3070 target_artists: Optional[list[str]], result: dict[str, Any] 

3071) -> bool: 

3072 """True when the candidate shares at least one artist with the target. 

3073 

3074 Vacuously true when the target's artist list is unknown, so callers 

3075 without artist context (e.g. an album-tracklist scan) aren't 

3076 unfairly blocked. Otherwise a hard requirement: a song that merely 

3077 shares its exact title with the target (title collisions across 

3078 unrelated artists are common for short/generic names — "Broken 

3079 Arrows" turns up from at least three different acts) must never be 

3080 picked just for being the "least wrong" duration match. 

3081 """ 

3082 

3083 target_set = {_norm_artist_name(a) for a in (target_artists or []) if a} 

3084 target_set.discard('') 

3085 if not target_set: 

3086 return True 

3087 candidate_set: set[str] = set() 

3088 for a in result.get('artists') or []: 

3089 if not isinstance(a, dict): 

3090 continue 

3091 name = a.get('name') or '' 

3092 # YouTube Music sometimes packs every credit into one entry 

3093 # ("JIRAYAUAI, DOUTH!, VITOR BUENO, and SAM SAM"); the unsplit 

3094 # name is kept too so "Rionegro & Solimões" still matches whole. 

3095 candidate_set.add(_norm_artist_name(name)) 

3096 candidate_set.update( 

3097 _norm_artist_name(p) 

3098 for p in _ARTIST_CREDIT_SPLIT_RE.split(name) 

3099 if p 

3100 ) 

3101 return bool(target_set & candidate_set) 

3102 

3103 

3104def _norm_artist_name(name: str) -> str: 

3105 """Casefolded artist name without a leading "The" — Spotify and 

3106 YouTube Music disagree on it ("Eden Project" vs "The Eden Project").""" 

3107 

3108 value = re.sub(r'\s+', ' ', name.casefold()).strip() 

3109 return re.sub(r'^the\s+', '', value) 

3110 

3111 

3112_NEGATIVE_KEYWORDS = ( 

3113 'karaoke', 

3114 'instrumental', 

3115 'cover ', 

3116 'cover)', 

3117 'tribute', 

3118 'guitar lesson', 

3119 'sped up', 

3120 'slowed', 

3121 'reverb', 

3122 'nightcore', 

3123 '8d audio', 

3124 '1 hour', 

3125 'bass boosted', 

3126) 

3127 

3128 

3129def _pick_best( 

3130 results: list[dict[str, Any]], 

3131 target_duration: int, 

3132 target_title: str = '', 

3133 target_artists: Optional[list[str]] = None, 

3134 target_album: str = '', 

3135) -> Optional[dict[str, Any]]: 

3136 target_title_l = (target_title or '').lower() 

3137 target_album_norm = _norm_compact_title(target_album) 

3138 

3139 best: Optional[dict[str, Any]] = None 

3140 best_score: float = float('inf') 

3141 for result in results: 

3142 if not result.get('videoId') or excluded_source(result.get('videoId')): 

3143 continue 

3144 

3145 candidate_title = (result.get('title') or '').lower() 

3146 # Skip results that add a "karaoke"/"instrumental"/etc. modifier 

3147 # which the source song does not have. Catches the most common 

3148 # source of wrong-audio matches. 

3149 if any( 

3150 kw in candidate_title and kw not in target_title_l 

3151 for kw in _NEGATIVE_KEYWORDS 

3152 ): 

3153 continue 

3154 

3155 # Hard requirement: the title must actually resemble the source 

3156 # title. Duration/artist/album scoring alone can otherwise pick a 

3157 # completely unrelated song (e.g. a "- Remastered 2023" suffix 

3158 # throws off the search and every hit is a different track by the 

3159 # same artist) — better to reject the track than embed the wrong 

3160 # audio under the right metadata. 

3161 if target_title and not _titles_match( 

3162 target_title, result.get('title') 

3163 ): 

3164 continue 

3165 

3166 # Hard requirement: at least one artist must overlap. See 

3167 # `_artists_overlap`'s docstring — a title collision with an 

3168 # unrelated artist must never win on duration alone. 

3169 if not _artists_overlap(target_artists, result): 

3170 continue 

3171 

3172 candidate_duration = result.get('duration_seconds') or _parse_duration( 

3173 result.get('duration') 

3174 ) 

3175 if target_duration and candidate_duration: 

3176 score = abs(candidate_duration - target_duration) 

3177 else: 

3178 score = 5 

3179 

3180 # Album is the decisive signal when the source album is known: it 

3181 # separates the studio version from live / compilation / re-recorded 

3182 # takes of the same song that share title, artist and near-identical 

3183 # length (durations differ by a second or two, so duration alone is 

3184 # not enough). Only applied when the candidate carries album info so 

3185 # album-less `videos` results are not unfairly penalised. 

3186 if target_album_norm: 

3187 candidate_album = '' 

3188 alb = result.get('album') 

3189 if isinstance(alb, dict): 

3190 candidate_album = alb.get('name') or '' 

3191 if candidate_album: 

3192 if _albums_match(target_album, candidate_album): 

3193 score -= 25 

3194 else: 

3195 score += 15 

3196 

3197 # Reward exact title matches over loosely-related ones. 

3198 if candidate_title and target_title_l: 

3199 if candidate_title.split('(')[0].strip() == ( 

3200 target_title_l.split('(')[0].strip() 

3201 ): 

3202 score -= 2 

3203 

3204 if score < best_score: 

3205 best_score = score 

3206 best = result 

3207 return best 

3208 

3209 

3210def _watch_playlist_artists(video_id: str) -> list[str]: 

3211 """The artists of *video_id*, one per entry, from the first track of 

3212 its watch playlist - ``[]`` when that can't be read. A guest that 

3213 track names only in its title ("Baby (feat. Ludacris)", credited to 

3214 Justin Bieber alone) is added too, as the album path does.""" 

3215 

3216 try: 

3217 data = _ytm().get_watch_playlist(video_id, limit=1) 

3218 except Exception: 

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

3220 'YouTube Music get_watch_playlist failed for {}', video_id 

3221 ) 

3222 return [] 

3223 for track in (data or {}).get('tracks') or []: 

3224 if not isinstance(track, dict) or track.get('videoId') not in { 

3225 None, 

3226 video_id, 

3227 }: 

3228 continue 

3229 artists = _credited_artist_names(track.get('artists')) 

3230 if not artists: 

3231 return [] 

3232 return _extract_title_featuring_artist( 

3233 str(track.get('title') or ''), artists 

3234 ) 

3235 return [] 

3236 

3237 

3238def _song_from_video_details(video_id: str) -> dict[str, Any]: 

3239 """Basic song info from ``get_song``'s raw video-player payload. 

3240 

3241 This is the only reliable, always-available source for an arbitrary 

3242 videoId (title, uploader/author, duration, thumbnail) — but it is 

3243 raw player data with no catalog metadata (album, track number). 

3244 """ 

3245 

3246 try: 

3247 info = _ytm().get_song(video_id) 

3248 except Exception: 

3249 logger.exception('YouTube Music get_song failed') 

3250 info = {} 

3251 _log_ytm_response(f'get_song {video_id}', info or {}) 

3252 details = (info or {}).get('videoDetails') or {} 

3253 thumbnails = (details.get('thumbnail') or {}).get('thumbnails') or [] 

3254 cover = thumbnails[-1].get('url', '') if thumbnails else '' 

3255 duration = 0 

3256 try: 

3257 duration = int(details.get('lengthSeconds') or 0) 

3258 except (TypeError, ValueError): 

3259 duration = 0 

3260 author = details.get('author', '') 

3261 # `author` joins every artist into one string ("Christina Aguilera, 

3262 # Lil' Kim, Mya, & P!nk") that can't be split safely - "Earth, Wind & 

3263 # Fire" is one artist. The watch playlist lists them one by one. 

3264 artists = _watch_playlist_artists(video_id) or ([author] if author else []) 

3265 return { 

3266 'song_id': video_id, 

3267 'name': details.get('title', ''), 

3268 'artists': artists, 

3269 'album_name': '', 

3270 'cover_url': cover, 

3271 'duration': duration, 

3272 'url': f'https://music.youtube.com/watch?v={video_id}', 

3273 'explicit': False, 

3274 'year': '', 

3275 'release_date': '', 

3276 'source': 'youtube', 

3277 } 

3278 

3279 

3280def song_from_video_id(video_id: str) -> dict[str, Any]: 

3281 """Look up song info for a YouTube videoId, including album/track 

3282 metadata when the video is part of an official YouTube Music album. 

3283 

3284 ``get_song`` (raw player data) never carries catalog metadata, and 

3285 ``get_watch_playlist`` was found — empirically, against the live 

3286 API — not to reliably include it either. Catalog metadata (album, 

3287 track number) is only reliably available through search, so once 

3288 the basic title/artist/duration are known, the resolved title is 

3289 run through the same matching pipeline used for Spotify-sourced 

3290 downloads (:func:`_find_youtube_music_match`) to look up a catalog hit, and 

3291 :func:`enrich_from_match` fills in album/track metadata from it 

3292 when found — never overriding the video actually requested. 

3293 """ 

3294 

3295 song = _song_from_video_details(video_id) 

3296 if not song.get('name'): 

3297 return song 

3298 

3299 # Catalog metadata only lives on YouTube Music, and the video itself is 

3300 # already pinned — a standard-YouTube fallback search would add nothing. 

3301 try: 

3302 _, match = _find_youtube_music_match(song) 

3303 except Exception: 

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

3305 'song_from_video_id: catalog lookup failed for {}', video_id 

3306 ) 

3307 match = None 

3308 if not match: 

3309 return song 

3310 

3311 enriched = enrich_from_match(song, match) 

3312 # enrich_from_match never touches these, but pin them explicitly so 

3313 # the returned song always describes the video the caller asked 

3314 # for, never whichever video the catalog lookup happened to match. 

3315 # That goes for the explicit mark too: the hit may be the album's 

3316 # version of a song whose video this is a clean edit of. 

3317 enriched['explicit'] = bool( 

3318 match.get('isExplicit') and match.get('videoId') == video_id 

3319 ) 

3320 enriched['song_id'] = video_id 

3321 enriched['url'] = f'https://music.youtube.com/watch?v={video_id}' 

3322 enriched['source'] = 'youtube' 

3323 return enriched 

3324 

3325 

3326# A catalog upload (the artist's own studio audio, or anything filed under 

3327# an album) already has the real artists and title. Anything else — a 

3328# user upload, or a music video reposted by a promo channel — is credited 

3329# to whoever uploaded it, and ytmusicapi sometimes even parses the upload 

3330# date or view count as the "artist". Those carry the real credit in the 

3331# title instead: "Artist - Title". 

3332_UPLOAD_METADATA_ARTIST_RE = re.compile( 

3333 r'^(?:[A-Z][a-z]{2,8}\.? \d{1,2}, \d{4}|[\d.,]+[KMB]? views?)$' 

3334) 

3335_TITLE_NOISE_RE = re.compile( 

3336 r'\s*[\(\[][^\)\]]*\b(?:official|lyrics?|visuali[sz]er|audio|video|' 

3337 r'hd|hq|4k|mv)\b[^\)\]]*[\)\]]', 

3338 re.IGNORECASE, 

3339) 

3340# The part after " - " names a version of the song, not the song: in 

3341# "Yellow - Live at Glastonbury", "Yellow" is the title, not an artist. 

3342_TITLE_VERSION_SUFFIX_RE = re.compile( 

3343 r'^(?:' + '|'.join(_VERSION_QUALIFIER_WORDS) + r'|ao vivo|en vivo|' 

3344 r'remaster\w*|radio edit|extended|edit|version|mix)\b', 

3345 re.IGNORECASE, 

3346) 

3347 

3348 

3349def _split_upload_title( 

3350 title: str, artists: list[str] 

3351) -> tuple[str, list[str]]: 

3352 """``(title, artists)`` for an upload whose title reads "Artist - Title".""" 

3353 

3354 clean = _TITLE_NOISE_RE.sub('', title or '').strip() 

3355 head, sep, tail = clean.partition(' - ') 

3356 if not sep or not head.strip() or not tail.strip(): 

3357 return clean, artists 

3358 if _TITLE_VERSION_SUFFIX_RE.match(tail.strip()): 

3359 return clean, artists 

3360 credited = [a.strip() for a in head.split(',') if a.strip()] 

3361 return tail.strip(), credited 

3362 

3363 

3364# A video's thumbnail lives at ``.../vi/<11-character id>/...`` (or 

3365# ``vi_webp``); other artwork (album covers) never matches. 

3366_THUMBNAIL_VIDEO_ID_RE = re.compile(r'/vi(?:_webp)?/([A-Za-z0-9_-]{11})/') 

3367 

3368 

3369def _video_id_from_thumbnails(track: dict[str, Any]) -> Optional[str]: 

3370 """The video id a playlist row's thumbnail URLs point at, if any.""" 

3371 

3372 for thumb in track.get('thumbnails') or []: 

3373 match = _THUMBNAIL_VIDEO_ID_RE.search(str((thumb or {}).get('url'))) 

3374 if match: 

3375 return match.group(1) 

3376 return None 

3377 

3378 

3379def _playlist_track_song(track: dict[str, Any]) -> Optional[dict[str, Any]]: 

3380 """One playlist row as a song dict, pinned to that exact video. 

3381 

3382 Playlists made by importers and converters often list their songs as 

3383 uploads YouTube Music has no catalog entry for: the row comes back with 

3384 ``videoId: null`` and ``isAvailable: false``, yet its thumbnail is the 

3385 video's own and the video plays fine on YouTube. Such a row is kept 

3386 under the id its thumbnail gives. A row that *does* carry a ``videoId`` 

3387 but is flagged unavailable is a deleted or private video, and is 

3388 dropped. 

3389 """ 

3390 

3391 video_id = track.get('videoId') 

3392 if video_id: 

3393 if track.get('isAvailable') is False: 

3394 return None 

3395 else: 

3396 video_id = _video_id_from_thumbnails(track) 

3397 if not video_id: 

3398 return None 

3399 track = {**track, 'videoId': video_id} 

3400 song = _result_to_song(track, rejoin_acts=True) 

3401 if song is None: 

3402 return None 

3403 catalog = track.get('videoType') == _MUSIC_VIDEO_TYPE_OFFICIAL_AUDIO or ( 

3404 isinstance(track.get('album'), dict) and track['album'].get('name') 

3405 ) 

3406 if not catalog: 

3407 artists = [ 

3408 a 

3409 for a in song['artists'] 

3410 if not _UPLOAD_METADATA_ARTIST_RE.match(a) 

3411 ] 

3412 title, artists = _split_upload_title(track.get('title', ''), artists) 

3413 song['name'] = title 

3414 song['artists'] = _extract_title_featuring_artist(title, artists) 

3415 # Pin the download to the playlist's own video: for a song that isn't 

3416 # on Spotify, the upload in the playlist may be the only copy there is. 

3417 song['youtube_id'] = video_id 

3418 return song 

3419 

3420 

3421def playlist_info_and_tracks_from_id( 

3422 playlist_id: str, 

3423) -> tuple[str, list[dict[str, Any]]]: 

3424 """``(title, songs)`` for a YouTube Music playlist. 

3425 

3426 Mirrors :func:`spotify.playlist_info_and_tracks` so a YouTube Music 

3427 playlist goes through the same batch download, M3U and Playlist 

3428 Monitor code. Every track is fetched (``limit=None`` pages through 

3429 the whole list); unavailable (deleted/private) entries are dropped. 

3430 """ 

3431 

3432 data = _ytm().get_playlist(playlist_id, limit=None) 

3433 _log_ytm_response(f'get_playlist {playlist_id}', data) 

3434 _prefetch_artist_channel_names(data.get('tracks')) 

3435 songs = [ 

3436 song 

3437 for track in (data.get('tracks') or []) 

3438 if (song := _playlist_track_song(track)) is not None 

3439 ] 

3440 return str(data.get('title') or playlist_id), songs 

3441 

3442 

3443def playlist_tracks_from_id(playlist_id: str) -> list[dict[str, Any]]: 

3444 return playlist_info_and_tracks_from_id(playlist_id)[1] 

3445 

3446 

3447def playlist_cover_url_from_id(playlist_id: str) -> str: 

3448 """Largest cover art YouTube Music's API offers for a playlist. 

3449 

3450 Fetches only the playlist header (``limit=0`` skips paginating the 

3451 track list) since the cover art lives there regardless of how many 

3452 tracks are requested. 

3453 """ 

3454 data = _ytm().get_playlist(playlist_id, limit=0) 

3455 thumbs = data.get('thumbnails') or [] 

3456 cover = thumbs[-1].get('url', '') if thumbs else '' 

3457 return _resize_thumbnail(cover, _PLAYLIST_COVER_SIZE)