tunegrab 0.6.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. tunegrab/__init__.py +10 -0
  2. tunegrab/__main__.py +3 -0
  3. tunegrab/browse.py +474 -0
  4. tunegrab/cli.py +1148 -0
  5. tunegrab/config.py +422 -0
  6. tunegrab/doctor.py +288 -0
  7. tunegrab/download/__init__.py +1 -0
  8. tunegrab/download/convert.py +51 -0
  9. tunegrab/download/ytdlp.py +458 -0
  10. tunegrab/errors.py +12 -0
  11. tunegrab/imports.py +173 -0
  12. tunegrab/library/__init__.py +1 -0
  13. tunegrab/library/archive.py +740 -0
  14. tunegrab/library/paths.py +255 -0
  15. tunegrab/library/playlists.py +45 -0
  16. tunegrab/library/sync.py +132 -0
  17. tunegrab/logs.py +47 -0
  18. tunegrab/matching/__init__.py +1 -0
  19. tunegrab/matching/base.py +37 -0
  20. tunegrab/matching/matcher.py +109 -0
  21. tunegrab/matching/scoring.py +257 -0
  22. tunegrab/matching/youtube.py +97 -0
  23. tunegrab/matching/ytmusic.py +116 -0
  24. tunegrab/metadata/__init__.py +1 -0
  25. tunegrab/metadata/base.py +59 -0
  26. tunegrab/metadata/resolver.py +94 -0
  27. tunegrab/metadata/spotify_api.py +551 -0
  28. tunegrab/metadata/spotify_embed.py +365 -0
  29. tunegrab/models.py +195 -0
  30. tunegrab/net.py +165 -0
  31. tunegrab/pacing.py +78 -0
  32. tunegrab/pipeline.py +607 -0
  33. tunegrab/preflight.py +58 -0
  34. tunegrab/runner.py +146 -0
  35. tunegrab/services.py +102 -0
  36. tunegrab/storage.py +285 -0
  37. tunegrab/tagging/__init__.py +1 -0
  38. tunegrab/tagging/lyrics.py +105 -0
  39. tunegrab/tagging/tagger.py +268 -0
  40. tunegrab/ui.py +193 -0
  41. tunegrab/updates.py +167 -0
  42. tunegrab/urls.py +168 -0
  43. tunegrab/video.py +694 -0
  44. tunegrab/web/__init__.py +1 -0
  45. tunegrab/web/app.py +867 -0
  46. tunegrab/web/desktop.py +45 -0
  47. tunegrab/web/jobs.py +725 -0
  48. tunegrab/web/static/app.css +334 -0
  49. tunegrab/web/static/app.js +1352 -0
  50. tunegrab/web/static/index.html +209 -0
  51. tunegrab-0.6.1.dist-info/METADATA +904 -0
  52. tunegrab-0.6.1.dist-info/RECORD +55 -0
  53. tunegrab-0.6.1.dist-info/WHEEL +4 -0
  54. tunegrab-0.6.1.dist-info/entry_points.txt +3 -0
  55. tunegrab-0.6.1.dist-info/licenses/LICENSE +674 -0
tunegrab/__init__.py ADDED
@@ -0,0 +1,10 @@
1
+ """TuneGrab: Spotify metadata -> YouTube audio -> tagged local files."""
2
+
3
+ from importlib.metadata import PackageNotFoundError, version
4
+
5
+ try:
6
+ __version__ = version("tunegrab")
7
+ except PackageNotFoundError: # running from a source tree without installing
8
+ __version__ = "0.0.0+unknown"
9
+
10
+ __all__ = ["__version__"]
tunegrab/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from tunegrab.cli import app
2
+
3
+ app(prog_name="tunegrab")
tunegrab/browse.py ADDED
@@ -0,0 +1,474 @@
1
+ """Browsing for the web UI: an artist's releases (to tick and queue) and release track lists.
2
+
3
+ Sources, best first:
4
+
5
+ * Spotify Web API (with credentials): the complete discography.
6
+ * Spotify's public artist page (no credentials): the newest 8 albums, 8 singles and
7
+ 1 compilation, plus top tracks. Spotify embeds this as base64 JSON (``initialState``).
8
+ * YouTube Music (no credentials): the complete discography with video IDs, used when the
9
+ Spotify list is incomplete. Tracks from it skip matching (the video is known).
10
+
11
+ Plain text goes to YouTube Music search: an artist's name opens the artist, anything else
12
+ ("Discovery Daft Punk", "One More Time") lists matching albums and songs.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import base64
18
+ import binascii
19
+ import json
20
+ import logging
21
+ import re
22
+ from typing import Any, Literal
23
+
24
+ from pydantic import BaseModel, Field
25
+ from rapidfuzz import fuzz
26
+
27
+ from tunegrab.matching.base import SearchError
28
+ from tunegrab.matching.ytmusic import YTMusicClient, best_thumbnail
29
+ from tunegrab.metadata.base import MetadataError, NotFoundError
30
+ from tunegrab.models import Candidate, Collection, Match, Track
31
+ from tunegrab.net import BROWSER_USER_AGENT, HttpClient, NetworkError
32
+
33
+ log = logging.getLogger(__name__)
34
+
35
+ ReleaseKind = Literal["album", "single", "compilation"]
36
+ ReleaseSource = Literal["spotify", "ytmusic"]
37
+ _INITIAL_STATE = re.compile(r'<script id="initialState" type="text/plain">([^<]+)</script>')
38
+ _KINDS: dict[str, ReleaseKind] = {
39
+ "album": "album",
40
+ "single": "single",
41
+ "ep": "single",
42
+ "compilation": "compilation",
43
+ }
44
+
45
+
46
+ class Release(BaseModel):
47
+ id: str
48
+ name: str
49
+ kind: ReleaseKind = "album"
50
+ year: str | None = None
51
+ cover_url: str | None = None
52
+ source: ReleaseSource = "spotify"
53
+ total_tracks: int | None = None
54
+ artist: str | None = None # set in search results, where releases mix artists
55
+
56
+
57
+ class ArtistOverview(BaseModel):
58
+ id: str | None = None
59
+ name: str
60
+ image_url: str | None = None
61
+ source: str
62
+ complete: bool # False when the list is known to be cut short
63
+ releases: list[Release] = Field(default_factory=list)
64
+ top_tracks: list[Track] = Field(default_factory=list)
65
+ note: str | None = None
66
+
67
+
68
+ class SongHit(BaseModel):
69
+ """A song from YouTube Music search; queueable as is (the video is known)."""
70
+
71
+ id: str # video ID
72
+ title: str
73
+ artists: list[str] = Field(default_factory=list)
74
+ album: str | None = None
75
+ album_id: str | None = None
76
+ duration_s: int | None = None
77
+ explicit: bool = False
78
+ cover_url: str | None = None
79
+
80
+
81
+ class ArtistHit(BaseModel):
82
+ id: str # YouTube Music channel ID
83
+ name: str
84
+
85
+
86
+ class SearchResults(BaseModel):
87
+ query: str
88
+ artist: ArtistHit | None = None # an artist the text may also mean
89
+ releases: list[Release] = Field(default_factory=list)
90
+ songs: list[SongHit] = Field(default_factory=list)
91
+
92
+
93
+ ARTIST_MATCH = 90 # text this close to the top result's artist name opens the artist
94
+ MAX_SONGS = 10
95
+ MAX_ALBUMS = 12
96
+
97
+
98
+ def _norm(text: str) -> str:
99
+ return " ".join(re.sub(r"[^\w\s]", " ", text.casefold()).split())
100
+
101
+
102
+ def _names(runs: Any) -> list[str]:
103
+ return [str(a["name"]) for a in runs or [] if isinstance(a, dict) and a.get("name")]
104
+
105
+
106
+ def _artist_of(result: dict[str, Any]) -> ArtistHit | None:
107
+ runs = [a for a in result.get("artists") or [] if isinstance(a, dict) and a.get("name")]
108
+ name = runs[0]["name"] if runs else result.get("artist")
109
+ channel = (runs[0].get("id") if runs else None) or result.get("browseId")
110
+ if not name or not channel:
111
+ return None
112
+ return ArtistHit(id=str(channel), name=str(name))
113
+
114
+
115
+ def _named_artist(text: str, results: list[dict[str, Any]]) -> ArtistHit | None:
116
+ top = results[0] if results else {}
117
+ if top.get("resultType") != "artist":
118
+ return None
119
+ hit = _artist_of(top)
120
+ if hit is None or fuzz.ratio(_norm(text), _norm(hit.name)) < ARTIST_MATCH:
121
+ return None
122
+ return hit
123
+
124
+
125
+ def song_match(hit: SongHit) -> Match:
126
+ """A search hit as a ready-made match, so the download skips matching."""
127
+ track = Track(
128
+ title=hit.title,
129
+ artists=hit.artists,
130
+ album=hit.album,
131
+ album_artist=hit.artists[0] if hit.artists else None,
132
+ album_id=hit.album_id,
133
+ duration_ms=(hit.duration_s or 0) * 1000,
134
+ explicit=hit.explicit,
135
+ cover_url=hit.cover_url,
136
+ )
137
+ candidate = Candidate(
138
+ video_id=hit.id,
139
+ title=hit.title,
140
+ artists=hit.artists,
141
+ duration_s=hit.duration_s or 0,
142
+ source="ytmusic_song",
143
+ album=hit.album,
144
+ thumbnail_url=hit.cover_url,
145
+ )
146
+ return Match(track=track, candidate=candidate, score=100, reason="picked from search")
147
+
148
+
149
+ def _kind(value: str | None) -> ReleaseKind:
150
+ return _KINDS.get((value or "album").lower(), "album")
151
+
152
+
153
+ def _largest(sources: list[dict[str, Any]] | None) -> str | None:
154
+ if not sources:
155
+ return None
156
+ best = max(sources, key=lambda s: (s.get("width") or 0) * (s.get("height") or 0))
157
+ url = best.get("url")
158
+ return str(url) if url else None
159
+
160
+
161
+ def _id(uri: str | None) -> str | None:
162
+ return uri.rsplit(":", 1)[-1] if uri else None
163
+
164
+
165
+ # --- Spotify public artist page ---------------------------------------------------------
166
+ def parse_artist_page(page: str, artist_id: str) -> ArtistOverview:
167
+ match = _INITIAL_STATE.search(page)
168
+ if not match:
169
+ raise MetadataError("Spotify artist page had no data (layout changed?)")
170
+ try:
171
+ state = json.loads(base64.b64decode(match.group(1)))
172
+ except (binascii.Error, ValueError) as exc:
173
+ raise MetadataError(f"Could not decode Spotify artist page: {exc}") from exc
174
+ entity = (state.get("entities") or {}).get("items", {}).get(f"spotify:artist:{artist_id}")
175
+ if not isinstance(entity, dict) or "discography" not in entity:
176
+ raise NotFoundError(f"Spotify artist {artist_id} not found")
177
+ disc = entity["discography"]
178
+ releases: list[Release] = []
179
+ seen: set[str] = set()
180
+ for group in ("albums", "singles", "compilations"):
181
+ for item in (disc.get(group) or {}).get("items") or []:
182
+ for rel in (item.get("releases") or {}).get("items") or []:
183
+ rid = _id(rel.get("uri"))
184
+ if not rid or rid in seen or not rel.get("name"):
185
+ continue
186
+ seen.add(rid)
187
+ year = (rel.get("date") or {}).get("year")
188
+ releases.append(
189
+ Release(
190
+ id=rid,
191
+ name=rel["name"],
192
+ kind=_kind(rel.get("type")),
193
+ year=str(year) if year else None,
194
+ cover_url=_largest((rel.get("coverArt") or {}).get("sources")),
195
+ )
196
+ )
197
+ top: list[Track] = []
198
+ for item in (disc.get("topTracks") or {}).get("items") or []:
199
+ track = item.get("track") or {}
200
+ tid = _id(track.get("uri"))
201
+ if not tid or not track.get("name"):
202
+ continue
203
+ album = track.get("albumOfTrack") or {}
204
+ top.append(
205
+ Track(
206
+ spotify_id=tid,
207
+ title=track["name"],
208
+ artists=[
209
+ a["profile"]["name"]
210
+ for a in (track.get("artists") or {}).get("items") or []
211
+ if (a.get("profile") or {}).get("name")
212
+ ],
213
+ album_id=_id(album.get("uri")),
214
+ cover_url=_largest((album.get("coverArt") or {}).get("sources")),
215
+ explicit=(track.get("contentRating") or {}).get("label") == "EXPLICIT",
216
+ )
217
+ )
218
+ name = (entity.get("profile") or {}).get("name") or artist_id
219
+ image = _largest(((entity.get("visuals") or {}).get("avatarImage") or {}).get("sources"))
220
+ return ArtistOverview(
221
+ id=artist_id,
222
+ name=name,
223
+ image_url=image,
224
+ source="spotify-page",
225
+ complete=False, # the page only lists the newest releases of each kind
226
+ releases=releases,
227
+ top_tracks=top,
228
+ note=(
229
+ "Spotify's public page lists only the newest 8 albums and 8 singles. "
230
+ "Use “Full discography” to load every release from YouTube Music."
231
+ ),
232
+ )
233
+
234
+
235
+ # --- Spotify Web API -------------------------------------------------------------------
236
+ def api_artist_overview(api: Any, artist_id: str) -> ArtistOverview:
237
+ """Complete discography through ``SpotifyAPIProvider._get/_paginate``."""
238
+ artist = api._get(f"/artists/{artist_id}")
239
+ pages = api._paginate(
240
+ api._get(
241
+ f"/artists/{artist_id}/albums",
242
+ params={"include_groups": "album,single,compilation", "limit": 10},
243
+ )
244
+ )
245
+ releases = [
246
+ Release(
247
+ id=a["id"],
248
+ name=a.get("name") or a["id"],
249
+ kind=_kind(a.get("album_type")),
250
+ year=(a.get("release_date") or "")[:4] or None,
251
+ cover_url=_largest(a.get("images")),
252
+ total_tracks=a.get("total_tracks"),
253
+ )
254
+ for a in pages
255
+ if a.get("id")
256
+ ]
257
+ return ArtistOverview(
258
+ id=artist_id,
259
+ name=artist.get("name") or artist_id,
260
+ image_url=_largest(artist.get("images")),
261
+ source="spotify-api",
262
+ complete=True,
263
+ releases=releases,
264
+ )
265
+
266
+
267
+ # --- YouTube Music ---------------------------------------------------------------------
268
+ def _year(value: Any) -> str | None:
269
+ text = str(value or "")
270
+ found = re.search(r"\b(19|20)\d{2}\b", text)
271
+ return found.group(0) if found else None
272
+
273
+
274
+ class YTMusicCatalog:
275
+ def __init__(self, client: YTMusicClient) -> None:
276
+ self.client = client
277
+
278
+ def find_artist(self, name: str) -> str:
279
+ results = self.client.call("search", name, filter="artists", limit=5) or []
280
+ best: tuple[float, str] | None = None
281
+ for result in results:
282
+ browse_id = result.get("browseId")
283
+ if not browse_id:
284
+ continue
285
+ score = fuzz.WRatio(name.lower(), str(result.get("artist") or "").lower())
286
+ if best is None or score > best[0]:
287
+ best = (score, browse_id)
288
+ if best is None or best[0] < 80:
289
+ raise NotFoundError(f"No YouTube Music artist named {name!r}")
290
+ return best[1]
291
+
292
+ def lookup(self, text: str) -> ArtistOverview | SearchResults:
293
+ """The artist when the text is their name (YouTube Music's top result), otherwise
294
+ the albums and songs that match."""
295
+ results = self._everything(text)
296
+ named = _named_artist(text, results)
297
+ if named is not None:
298
+ return self.artist(named.name, channel=named.id)
299
+ suggestion = None
300
+ for result in results:
301
+ hit = _artist_of(result) if result.get("resultType") == "artist" else None
302
+ if hit and fuzz.partial_ratio(_norm(hit.name), _norm(text)) >= ARTIST_MATCH:
303
+ suggestion = hit
304
+ break
305
+ return self.search(text, suggestion)
306
+
307
+ def named_artist(self, text: str) -> ArtistHit | None:
308
+ """The artist the text names, if that's what YouTube Music puts on top."""
309
+ return _named_artist(text, self._everything(text))
310
+
311
+ def _everything(self, text: str) -> list[dict[str, Any]]:
312
+ found = self.client.call("search", text, limit=10) or []
313
+ return [r for r in found if isinstance(r, dict)]
314
+
315
+ def search(self, text: str, artist: ArtistHit | None = None) -> SearchResults:
316
+ songs: list[SongHit] = []
317
+ for item in self.client.call("search", text, filter="songs", limit=MAX_SONGS) or []:
318
+ if not isinstance(item, dict) or not item.get("videoId") or len(songs) >= MAX_SONGS:
319
+ continue
320
+ album: dict[str, Any] = item["album"] if isinstance(item.get("album"), dict) else {}
321
+ seconds = item.get("duration_seconds")
322
+ songs.append(
323
+ SongHit(
324
+ id=str(item["videoId"]),
325
+ title=str(item.get("title") or "Unknown"),
326
+ artists=_names(item.get("artists")),
327
+ album=album.get("name"),
328
+ album_id=album.get("id"),
329
+ duration_s=int(seconds) if seconds else None,
330
+ explicit=bool(item.get("isExplicit")),
331
+ cover_url=best_thumbnail(item.get("thumbnails")),
332
+ )
333
+ )
334
+ releases: list[Release] = []
335
+ for item in self.client.call("search", text, filter="albums", limit=MAX_ALBUMS) or []:
336
+ if not isinstance(item, dict) or not item.get("browseId"):
337
+ continue
338
+ if len(releases) >= MAX_ALBUMS:
339
+ break
340
+ artists = _names(item.get("artists"))
341
+ releases.append(
342
+ Release(
343
+ id=str(item["browseId"]),
344
+ name=str(item.get("title") or item["browseId"]),
345
+ kind=_kind(str(item.get("type") or "album")),
346
+ year=_year(item.get("year")),
347
+ cover_url=best_thumbnail(item.get("thumbnails")),
348
+ source="ytmusic",
349
+ artist=", ".join(artists) or None,
350
+ )
351
+ )
352
+ if not songs and not releases:
353
+ raise NotFoundError(f"Nothing on YouTube Music matches \u201c{text}\u201d.")
354
+ return SearchResults(query=text, artist=artist, releases=releases, songs=songs)
355
+
356
+ def artist(self, name: str, channel: str | None = None) -> ArtistOverview:
357
+ channel = channel or self.find_artist(name)
358
+ data = self.client.call("get_artist", channel) or {}
359
+ releases: list[Release] = []
360
+ seen: set[str] = set()
361
+ for group, kind in (("albums", "album"), ("singles", "single")):
362
+ section = data.get(group) or {}
363
+ items = section.get("results") or []
364
+ if section.get("params") and section.get("browseId"):
365
+ try:
366
+ items = (
367
+ self.client.call(
368
+ "get_artist_albums", section["browseId"], section["params"], limit=None
369
+ )
370
+ or items
371
+ )
372
+ except SearchError as exc:
373
+ log.warning("YouTube Music %s list failed: %s", group, exc)
374
+ for item in items:
375
+ browse_id = item.get("browseId")
376
+ if not browse_id or browse_id in seen:
377
+ continue
378
+ seen.add(browse_id)
379
+ item_type = str(item.get("type") or kind).lower()
380
+ releases.append(
381
+ Release(
382
+ id=browse_id,
383
+ name=str(item.get("title") or browse_id),
384
+ kind=_kind("single" if item_type in ("single", "ep") else kind),
385
+ year=_year(item.get("year")),
386
+ cover_url=best_thumbnail(item.get("thumbnails")),
387
+ source="ytmusic",
388
+ )
389
+ )
390
+ return ArtistOverview(
391
+ id=channel,
392
+ name=str(data.get("name") or name),
393
+ image_url=best_thumbnail(data.get("thumbnails")),
394
+ source="ytmusic",
395
+ complete=True,
396
+ releases=releases,
397
+ )
398
+
399
+ def album(self, browse_id: str) -> tuple[Collection, dict[str, Match]]:
400
+ """A YouTube Music album as a Collection plus a ready-made match per track."""
401
+ data = self.client.call("get_album", browse_id) or {}
402
+ if not data.get("tracks"):
403
+ raise NotFoundError(f"YouTube Music album {browse_id} not found")
404
+ album_artists = [a["name"] for a in data.get("artists") or [] if a.get("name")]
405
+ cover = best_thumbnail(data.get("thumbnails"))
406
+ year = _year(data.get("year"))
407
+ playable = [t for t in data["tracks"] if t.get("videoId") and t.get("isAvailable", True)]
408
+ tracks: list[Track] = []
409
+ matches: dict[str, Match] = {}
410
+ for number, item in enumerate(playable, start=1):
411
+ artists = [a["name"] for a in item.get("artists") or [] if a.get("name")]
412
+ seconds = item.get("duration_seconds") or 0
413
+ track = Track(
414
+ title=str(item.get("title") or "Unknown"),
415
+ artists=artists or album_artists,
416
+ album=str(data.get("title") or ""),
417
+ album_artist=album_artists[0] if album_artists else None,
418
+ album_id=browse_id,
419
+ track_number=item.get("trackNumber") or number,
420
+ total_tracks=data.get("trackCount") or len(playable),
421
+ release_date=year,
422
+ duration_ms=int(seconds) * 1000,
423
+ explicit=bool(item.get("isExplicit")),
424
+ cover_url=cover,
425
+ )
426
+ candidate = Candidate(
427
+ video_id=str(item["videoId"]),
428
+ title=track.title,
429
+ artists=track.artists,
430
+ duration_s=int(seconds),
431
+ source="ytmusic_song",
432
+ album=track.album,
433
+ thumbnail_url=cover,
434
+ )
435
+ matches[candidate.video_id] = Match(
436
+ track=track, candidate=candidate, score=100, reason="YouTube Music album track"
437
+ )
438
+ tracks.append(track)
439
+ collection = Collection(
440
+ kind="album",
441
+ id=browse_id,
442
+ name=str(data.get("title") or browse_id),
443
+ owner=album_artists[0] if album_artists else None,
444
+ tracks=tracks,
445
+ source="ytmusic",
446
+ )
447
+ return collection, matches
448
+
449
+
450
+ # --- the facade used by the web app ------------------------------------------------------
451
+ class Browser:
452
+ def __init__(self, http: HttpClient, ytmusic: YTMusicCatalog, api: Any | None = None) -> None:
453
+ self.http = http
454
+ self.ytmusic = ytmusic
455
+ self.api = api
456
+
457
+ def spotify_artist(self, artist_id: str) -> ArtistOverview:
458
+ if self.api is not None:
459
+ try:
460
+ return api_artist_overview(self.api, artist_id)
461
+ except MetadataError as exc:
462
+ log.info("API artist listing failed (%s); using the public page", exc)
463
+ try:
464
+ response = self.http.get(
465
+ f"https://open.spotify.com/artist/{artist_id}",
466
+ headers={"User-Agent": BROWSER_USER_AGENT, "Accept-Language": "en"},
467
+ )
468
+ except NetworkError as exc:
469
+ raise MetadataError(str(exc)) from exc
470
+ if response.status_code == 404:
471
+ raise NotFoundError(f"Spotify artist {artist_id} not found")
472
+ if not response.is_success:
473
+ raise MetadataError(f"Spotify artist page returned HTTP {response.status_code}")
474
+ return parse_artist_page(response.content.decode("utf-8", "replace"), artist_id)