Coverage for downtify/providers.py: 90%
1479 statements
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
1"""Audio search/match helpers: YouTube Music, YouTube and SoundCloud."""
3from __future__ import annotations
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
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
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
48def _log_ytm_response(label: str, payload: Any) -> None:
49 """Full YT Music payloads (truncated); enable DEBUG level to inspect."""
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 )
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 )
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
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
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)."""
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
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."""
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)))
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.
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 """
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]
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."""
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
232DEFAULT_COVER_RESOLUTION = 1200
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
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.
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
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`)."""
269 global _cover_minimum
270 _cover_minimum = max(0, int(pixels or 0))
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))
284def _resize_thumbnail(url: str, size: int) -> str:
285 """Replace the size suffix on a YT thumbnail with the given one."""
287 if not url:
288 return url
289 return re.sub(r'=w\d+-h\d+.*$', f'=w{size}-h{size}-l90-rj', url)
292def resize_thumbnail(url: str, size: int) -> str:
293 """*url* (a YouTube Music cover) asked for at *size* pixels."""
295 return _resize_thumbnail(url, size)
298def _upgrade_thumbnail(url: str) -> str:
299 """Replace the size suffix on a YT thumbnail with a larger one."""
301 return _resize_thumbnail(url, cover_resolution())
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
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
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."""
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
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)."""
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
401def spotify_open_url(song: dict[str, Any]) -> str:
402 """Web URL to open this row on Spotify (track link or search fallback)."""
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)}'
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
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
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
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.
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 """
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 }
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.
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 """
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
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.
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 """
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 }
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 }
657def search_albums(query: str, limit: int = 10) -> list[dict[str, Any]]:
658 """Search YouTube Music for albums matching ``query``.
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 """
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
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 }
710def search_artists(query: str, limit: int = 10) -> list[dict[str, Any]]:
711 """Search YouTube Music for artists matching ``query``.
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 """
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
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`).
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 """
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
773def _artist_discography_browse_id(channel_id: str) -> str:
774 """BrowseId for an artist's full "See all" albums/singles grid page.
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}'
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.
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:
814 def _request_more(additional_params: Any) -> Any:
815 return ytm._send_request('browse', body, additional_params)
817 albums.extend(
818 get_continuations(
819 grid,
820 'gridContinuation',
821 None,
822 _request_more,
823 _parse_ytm_albums,
824 )
825 )
826 return albums
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.
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 """
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
856def artist_info_from_channel_id(channel_id: str) -> dict[str, Any]:
857 """Resolve an artist's own profile info: name, thumbnail, bio.
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 """
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 {}
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 }
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.
888 YouTube Music only ever offers a short, fixed list here (~10 - no
889 'params' continuation is offered, unlike the albums/singles shelves).
890 """
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 []
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
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.
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 """
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 []
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))
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))
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 )
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 ]
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.
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 }
1010_TOP_ALBUMS_LIMIT = 5
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
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.
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]
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.
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 """
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 []
1105 artist_name = str(artist_data.get('name') or '').strip()
1106 section = artist_data.get('albums')
1107 if not isinstance(section, dict):
1108 return []
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]
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
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.
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 """
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 []
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
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}
1173def _parse_play_count(text: Any) -> int:
1174 """``'1.2B plays'`` -> ``1200000000``; ``0`` if it isn't a play count.
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 """
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]))
1192def _music_list_rows(node: Any) -> list[dict[str, Any]]:
1193 """Every ``musicResponsiveListItemRenderer`` under *node*."""
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
1208def _playlist_play_counts(playlist_id: str) -> dict[str, int]:
1209 """``{videoId: approximate play count}`` for a playlist's first page.
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 """
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 {}
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
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.
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 """
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 []
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 []
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 []
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
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_-]+)')
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 )
1312def parse_youtube_url(url: str) -> Optional[tuple[str, str]]:
1313 """Parse a YouTube/YouTube Music URL into ``(kind, id)``.
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.
1324 A ``watch?v=...&list=...`` URL is the song that was playing, not the
1325 playlist around it, so it stays a ``'track'``.
1326 """
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
1354_channel_id_cache: dict[str, str] = {}
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.
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 """
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
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
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)
1413@contextmanager
1414def excluding_sources(sources: Iterable[str]) -> Iterator[None]:
1415 """Within the block, no matcher picks any of *sources*."""
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)
1426def excluded_source(source: Any) -> bool:
1427 """Whether *source* was rejected for the song being matched."""
1429 return bool(source) and str(source) in _EXCLUDED_SOURCES.get()
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``.
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.
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 """
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
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
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."""
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))
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)``.
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 """
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
1516 video_id, result = _search_youtube_music_match(
1517 query, title, artists, album, duration
1518 )
1519 if video_id:
1520 return video_id, result
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
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
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``.
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 """
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
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
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)
1698def _youtube_core_title(title: Any) -> str:
1699 """``title`` without featured-artist credits, for cross-site matching."""
1701 value = str(title or '').replace('’', "'")
1702 value = _YOUTUBE_TITLE_FEATURING_RE.sub('', value)
1703 return re.sub(r'\s+', ' ', value).strip()
1706def _youtube_search(query: str, limit: int) -> list[dict[str, Any]]:
1707 """Flat standard-YouTube search results (``ytsearch``) via yt-dlp."""
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)]
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`)."""
1728 return _youtube_search(query, limit)
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-]+')
1772def parse_soundcloud_url(url: str) -> Optional[tuple[str, str]]:
1773 """``('track', canonical URL)`` for a SoundCloud track link, else
1774 ``None``.
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 """
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)
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."""
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
1826def _soundcloud_ydl_opts(**extra: Any) -> dict[str, Any]:
1827 """yt-dlp options for a SoundCloud lookup (never a download)."""
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
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."""
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()
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."""
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 ''
1870def _soundcloud_release(info: dict[str, Any]) -> tuple[str, str]:
1871 """``(year, release_date)`` from the release date, else the upload."""
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 '', ''
1884def soundcloud_track_from_url(url: str) -> dict[str, Any]:
1885 """Resolve a SoundCloud track link into Downtify's song shape.
1887 SoundCloud has no albums: a track that names none is its own album,
1888 like a single.
1889 """
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 }
1927def _soundcloud_normalize(value: str) -> str:
1928 return ''.join(char for char in value.casefold() if char.isalnum())
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)
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."""
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 )
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
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``.
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 """
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]
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."""
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]
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.
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 """
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 }
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``.
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 """
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
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)
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)
2164def find_match_youtube_only(song: dict[str, Any]) -> Optional[str]:
2165 """Standard-YouTube-only match, for the ``youtube`` audio provider.
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 """
2172 video_id, _diff = _find_match_via_youtube(song)
2173 return video_id
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.
2181 Used when the caller already has a target video and wants to enrich
2182 metadata without risking switching to a different track.
2183 """
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
2215def _norm_compact_title(value: Any) -> str:
2216 """Lowercase collapsed title for forgiving comparisons."""
2218 return re.sub(r'\s+', ' ', str(value or '').casefold()).strip()
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+([^()\[\]]+?)$')
2271def _names_match(target: Any, candidate: Any) -> bool:
2272 """True when two free-text names (title or album) refer to the same release.
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 """
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)
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)
2315def _albums_match(target: Any, candidate: Any) -> bool:
2316 """True when two album names refer to the same release. See :func:`_names_match`."""
2318 return _names_match(target, candidate)
2321def _titles_match(target: Any, candidate: Any) -> bool:
2322 """True when two song titles refer to the same recording. See :func:`_names_match`.
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 """
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
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
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 ''
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 ''
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)
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
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."""
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
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.
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
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
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
2582def _cached_album_meta(browse_id: str) -> dict[str, Any]:
2583 """Album-level metadata for ``browse_id``, if already resolved and cached.
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 """
2590 with _lock:
2591 return dict(_album_meta_cache.get(browse_id) or {})
2594def _cached_album_title(browse_id: str) -> str:
2595 return _cached_album_meta(browse_id).get('title', '')
2598def _cached_album_release_type(browse_id: str) -> str:
2599 return _cached_album_meta(browse_id).get('type', '')
2602def _cached_album_year(browse_id: str) -> str:
2603 return _cached_album_meta(browse_id).get('year', '')
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)
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.
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
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)
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]
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'
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
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."""
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 }
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.
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 """
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
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)
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
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.
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 """
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
2865 browse_id = _album_browse_id_from_search({}, song)
2866 if not browse_id:
2867 return None, None
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
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.
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 """
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
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
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."""
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
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.
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 """
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)
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")."""
3108 value = re.sub(r'\s+', ' ', name.casefold()).strip()
3109 return re.sub(r'^the\s+', '', value)
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)
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)
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
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
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
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
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
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
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
3204 if score < best_score:
3205 best_score = score
3206 best = result
3207 return best
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."""
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 []
3238def _song_from_video_details(video_id: str) -> dict[str, Any]:
3239 """Basic song info from ``get_song``'s raw video-player payload.
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 """
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 }
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.
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 """
3295 song = _song_from_video_details(video_id)
3296 if not song.get('name'):
3297 return song
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
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
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)
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"."""
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
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})/')
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."""
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
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.
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 """
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
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.
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 """
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
3443def playlist_tracks_from_id(playlist_id: str) -> list[dict[str, Any]]:
3444 return playlist_info_and_tracks_from_id(playlist_id)[1]
3447def playlist_cover_url_from_id(playlist_id: str) -> str:
3448 """Largest cover art YouTube Music's API offers for a playlist.
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)