stashify-cli 1.3.0__py3-none-any.whl

stashify/embed.py

@@ -0,0 +1,271 @@
+"""Metadata from Spotify's public embed pages.
+
+The embed pages served at open.spotify.com/embed/... are public HTML pages
+meant to be loaded by any visitor's browser. Each page embeds a JSON document
+with the entity metadata (title, artists, duration, cover art, the track list
+of an album, playlist or artist). Stashify parses that document instead of the
+official Web API, so no account, login or developer app is required.
+
+Limitations, honestly:
+- Private or unavailable entities cannot be resolved (embed shows a not-found page).
+- Fields like ISRC, album name (for playlist items), track numbers and disc
+  numbers are not available. Album track numbers are derived from the order.
+- The embed format is not a documented public contract and can change.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+
+import requests
+
+from .errors import StashifyError
+from .models import Track
+from .spotify import parse_spotify_url
+
+EMBED_BASE = "https://open.spotify.com/embed"
+EMBED_TIMEOUT = 20
+MAX_EMBED_BYTES = 8 * 1024 * 1024
+USER_AGENT = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/131.0.0.0 Safari/537.36"
+)
+
+_NEXT_DATA_RE = re.compile(
+    r'<script id="__NEXT_DATA__" type="application/json">(.*?)</script>',
+    re.S,
+)
+
+
+@dataclass
+class EmbedResolver:
+    """Resolve public Spotify links into Track objects via embed pages."""
+
+    detailed: bool = True
+    timeout: int = EMBED_TIMEOUT
+
+    def __post_init__(self) -> None:
+        self._local = threading.local()
+
+    def _session(self) -> requests.Session:
+        session = getattr(self._local, "session", None)
+        if session is None:
+            session = requests.Session()
+            self._local.session = session
+        return session
+
+    # Public interface ------------------------------------------------------
+
+    def fetch_tracks(self, url: str) -> list[Track]:
+        kind, spotify_id = parse_spotify_url(url)
+        entity = self._entity(kind, spotify_id)
+        if kind == "track":
+            return [self._track_from_entity(entity)]
+        if kind == "album":
+            entity_title = _clean_str(entity.get("name"))
+            album_artist = _clean_str(entity.get("subtitle"))
+            cover = _largest_image(entity)
+            entries = _track_list(entity)
+            tracks = []
+            for index, entry in enumerate(entries, start=1):
+                track = self._track_from_entry(entry)
+                track.album = entity_title
+                track.album_artist = album_artist or track.artist
+                track.track_number = index
+                track.disc_number = 1
+                track.total_tracks = len(entries)
+                track.cover_url = cover or track.cover_url
+                tracks.append(track)
+            if self.detailed:
+                tracks = self._enrich(tracks)
+            return tracks
+        if kind in ("playlist", "artist"):
+            cover = _largest_image(entity) if kind == "playlist" else ""
+            entries = _track_list(entity)
+            tracks = [self._track_from_entry(entry) for entry in entries]
+            if self.detailed:
+                tracks = self._enrich(tracks)
+            if kind == "playlist":
+                for track in tracks:
+                    if not track.cover_url:
+                        track.cover_url = cover
+            return tracks
+        raise StashifyError(f"Unsupported Spotify link kind: {kind!r}")
+
+    # Internals ------------------------------------------------------------
+
+    def _entity(self, kind: str, spotify_id: str) -> dict:
+        try:
+            response = self._session().get(
+                f"{EMBED_BASE}/{kind}/{spotify_id}",
+                headers={"User-Agent": USER_AGENT},
+                timeout=self.timeout,
+                stream=True,
+            )
+        except requests.RequestException as exc:
+            raise StashifyError(f"Could not reach Spotify embed pages: {exc}") from exc
+
+        content = b""
+        limit = MAX_EMBED_BYTES
+        for chunk in response.iter_content(chunk_size=64 * 1024):
+            limit -= len(chunk)
+            if limit < 0:
+                raise StashifyError("Spotify embed page is unexpectedly large.")
+            content += chunk
+        if response.status_code != 200:
+            raise StashifyError(
+                f"Spotify embed request failed ({response.status_code}). "
+                "The link is probably private or does not exist."
+            )
+        match = _NEXT_DATA_RE.search(content.decode("utf-8", errors="replace"))
+        if not match:
+            raise StashifyError(
+                "Spotify embed page has an unexpected format. "
+                "The embed format may have changed."
+            )
+        try:
+            payload = json.loads(match.group(1))
+        except json.JSONDecodeError as exc:
+            raise StashifyError("Spotify embed page contains invalid JSON.") from exc
+        except RecursionError as exc:
+            raise StashifyError("Spotify embed page JSON is too deeply nested.") from exc
+        entity = (
+            ((payload.get("props") or {}).get("pageProps") or {})
+            .get("state", {})
+            .get("data", {})
+            .get("entity")
+        )
+        if not isinstance(entity, dict):
+            status = (payload.get("props") or {}).get("pageProps", {}).get("status")
+            detail = f" (status: {status})" if status else ""
+            raise StashifyError(
+                f"This {kind} link could not be resolved{detail}. "
+                "It may be private, unavailable or removed."
+            )
+        return entity
+
+    def _track_from_entity(self, entity: dict) -> Track:
+        artists = [
+            _clean_str(a.get("name"))
+            for a in entity.get("artists") or []
+            if _clean_str(a.get("name"))
+        ]
+        if not artists:
+            subtitle = _clean_str(entity.get("subtitle"))
+            artists = _split_artists(subtitle)
+        release = ""
+        raw_date = entity.get("releaseDate") or {}
+        if isinstance(raw_date, dict):
+            release = str(raw_date.get("isoString") or "")[:10]
+        cover = _largest_image(entity)
+        return Track(
+            title=_clean_str(entity.get("name") or entity.get("title")),
+            artists=artists,
+            duration_ms=int(entity.get("duration") or 0),
+            release_date=release,
+            cover_url=cover,
+            spotify_url=_spotify_url(entity),
+            explicit=bool(entity.get("isExplicit") or False),
+        )
+
+    def _track_from_entry(self, entry: dict) -> Track:
+        uri = _clean_str(entry.get("uri"))
+        artists = _split_artists(_clean_str(entry.get("subtitle")))
+        explicit = bool(entry.get("isExplicit") or False)
+        return Track(
+            title=_clean_str(entry.get("title")),
+            artists=artists,
+            duration_ms=int(entry.get("duration") or 0),
+            spotify_url=_spotify_url_from_uri(uri),
+            explicit=explicit,
+        )
+
+    def _enrich(self, tracks: list[Track]) -> list[Track]:
+        """Fill cover art, release year and proper artists via per-track embeds.
+
+        Runs four lookups in parallel; on any failure the basic entry data is
+        kept.
+        """
+
+        def fetch(index: int, track: Track) -> tuple[int, Track]:
+            track_id = _id_from_spotify_url(track.spotify_url)
+            if not track_id:
+                return index, track
+            try:
+                entity = self._entity("track", track_id)
+            except StashifyError:
+                return index, track
+            full = self._track_from_entity(entity)
+            if full.artists:
+                track.artists = full.artists
+            if full.release_date and not track.release_date:
+                track.release_date = full.release_date
+            if full.cover_url:
+                track.cover_url = full.cover_url
+            return index, track
+
+        if len(tracks) > 1:
+            with ThreadPoolExecutor(max_workers=4) as pool:
+                return [track for _, track in sorted(pool.map(fetch, range(len(tracks)), tracks))]
+        return [fetch(0, tracks[0])[1]]
+
+
+def _clean_str(value) -> str:
+    if not isinstance(value, str):
+        return ""
+    return value.strip()
+
+
+def _split_artists(subtitle: str) -> list[str]:
+    parts = [part.strip() for part in (subtitle or "").split(",")]
+    parts = [part for part in parts if part]
+    return parts or ["Unknown Artist"]
+
+
+def _track_list(entity: dict) -> list[dict]:
+    entries = entity.get("trackList") or []
+    result = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        if entry.get("isPlayable") is False:
+            continue
+        if _clean_str(entry.get("uri")) and _clean_str(entry.get("title")):
+            result.append(entry)
+    return result
+
+
+def _largest_image(entity: dict) -> str:
+    images = (entity.get("visualIdentity") or {}).get("image") or []
+    if not images:
+        return ""
+
+    def area(image: dict) -> int:
+        return int(image.get("maxWidth") or 0) * int(image.get("maxHeight") or 0)
+
+    return _clean_str(max(images, key=area).get("url"))
+
+
+def _spotify_url(entity: dict) -> str:
+    kind = entity.get("type") or "track"
+    entity_id = _clean_str(entity.get("id"))
+    if entity_id:
+        return f"https://open.spotify.com/{kind}/{entity_id}"
+    return _clean_str(entity.get("uri"))
+
+
+def _spotify_url_from_uri(uri: str) -> str:
+    match = re.match(r"^spotify:(?P<kind>[a-z]+):(?P<id>[A-Za-z0-9]{22})$", uri or "")
+    if match:
+        return f"https://open.spotify.com/{match.group('kind')}/{match.group('id')}"
+    return uri or ""
+
+
+def _id_from_spotify_url(url: str) -> str:
+    match = re.search(r"(?:track/|spotify:track:)([A-Za-z0-9]{22})", url or "")
+    return match.group(1) if match else ""

stashify/errors.py

@@ -0,0 +1,21 @@
+"""Error types used across Stashify."""
+
+
+class StashifyError(Exception):
+    """A user-facing failure with a clear message."""
+
+
+class SpotifyAuthError(StashifyError):
+    """Authentication or authorization with Spotify failed."""
+
+
+class SpotifyApiError(StashifyError):
+    """A call to the Spotify Web API failed."""
+
+
+class SourceNotFoundError(StashifyError):
+    """No suitable audio source could be found for a track."""
+
+
+class DownloadError(StashifyError):
+    """Downloading or converting a track failed."""

stashify/lyrics.py

@@ -0,0 +1,36 @@
+"""Fetch plain-text lyrics from a free community lyrics API.
+
+Returns None on any failure; lyrics are always optional and must never block
+a download.
+"""
+
+from __future__ import annotations
+
+import requests
+
+from .models import Track
+
+API_URL = "https://api.lyrics.ovh/v1"
+TIMEOUT = 10
+MAX_LYRICS_BYTES = 64 * 1024
+
+
+def fetch_lyrics(track: Track) -> str | None:
+    artist = requests.utils.quote(track.artist, safe="")
+    title = requests.utils.quote(track.title, safe="")
+    try:
+        response = requests.get(
+            f"{API_URL}/{artist}/{title}", timeout=TIMEOUT
+        )
+    except requests.RequestException:
+        return None
+    if response.status_code != 200:
+        return None
+    if len(response.content) > MAX_LYRICS_BYTES:
+        return None
+    try:
+        lyrics = (response.json() or {}).get("lyrics") or ""
+    except ValueError:
+        return None
+    lyrics = lyrics.strip()
+    return lyrics or None

stashify/models.py

@@ -0,0 +1,62 @@
+"""Data model for a single track of music.
+
+A Track is the unit everything else in Stashify works on: metadata is
+collected from Spotify, audio is matched and downloaded for each track,
+and the file is tagged with the same information.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+
+
+@dataclass
+class Track:
+    title: str
+    artists: list[str] = field(default_factory=list)
+    album: str = ""
+    album_artist: str = ""
+    track_number: int = 0
+    disc_number: int = 1
+    total_tracks: int = 0
+    duration_ms: int = 0
+    release_date: str = ""
+    isrc: str = ""
+    cover_url: str = ""
+    genres: list[str] = field(default_factory=list)
+    spotify_url: str = ""
+    explicit: bool = False
+
+    @property
+    def artist(self) -> str:
+        """Primary artist, used for display and file naming."""
+        return self.artists[0] if self.artists else "Unknown Artist"
+
+    @property
+    def artists_text(self) -> str:
+        return ", ".join(self.artists) if self.artists else "Unknown Artist"
+
+    @property
+    def duration_text(self) -> str:
+        minutes, seconds = divmod(int(self.duration_ms) // 1000, 60)
+        return f"{minutes}:{seconds:02d}"
+
+    def display(self) -> str:
+        return f"{self.artists_text} - {self.title}"
+
+    def search_query(self) -> str:
+        """Query string used to look the track up on YouTube."""
+        return f"{self.artists_text} - {self.title}"
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Track:
+        if not isinstance(data, dict):
+            raise ValueError("Track data must be a mapping")
+        known = {f for f in cls.__dataclass_fields__}  # type: ignore[attr-defined]
+        values = {k: v for k, v in data.items() if k in known}
+        if not values.get("title"):
+            raise ValueError("Track data is missing a title")
+        return cls(**values)

stashify/output.py

@@ -0,0 +1,59 @@
+"""Output path rendering and safe file naming."""
+
+from __future__ import annotations
+
+import re
+
+from .models import Track
+
+DEFAULT_TEMPLATE = "{artist} - {title}"
+MAX_SEGMENT = 120
+
+_ILLEGAL = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
+_SPACES = re.compile(r"\s+")
+_TOKENS = re.compile(r"\{([a-z_]+)\}")
+
+
+def release_year(track: Track) -> str:
+    match = re.match(r"^(\d{4})", track.release_date or "")
+    return match.group(1) if match else ""
+
+
+def safe_segment(text: str) -> str:
+    text = _ILLEGAL.sub("", text or "")
+    text = _SPACES.sub(" ", text).strip().strip(".")
+    text = text[:MAX_SEGMENT].rstrip(" .")
+    return text
+
+
+def _token_value(name: str, track: Track) -> str:
+    values = {
+        "artist": track.artist,
+        "artists": track.artists_text,
+        "title": track.title,
+        "album": track.album,
+        "album_artist": track.album_artist or track.artist,
+        "track_number": str(track.track_number) if track.track_number else "",
+        "disc_number": str(track.disc_number) if track.disc_number else "",
+        "release_year": release_year(track),
+    }
+    return values.get(name, "")
+
+
+def render_template(template: str, track: Track) -> str:
+    """Render a path template into a relative, safe path string."""
+    template = template or DEFAULT_TEMPLATE
+
+    def replace(match: re.Match) -> str:
+        value = _token_value(match.group(1), track)
+        return value.replace("/", "-").replace("\\", "-")
+
+    rendered = _TOKENS.sub(replace, template)
+    parts = []
+    for segment in rendered.split("/"):
+        cleaned = safe_segment(segment)
+        if cleaned:
+            parts.append(cleaned)
+    if not parts:
+        parts = [safe_segment(f"{track.artist} - {track.title}")]
+    return "/".join(parts)

stashify/pipeline.py

@@ -0,0 +1,179 @@
+"""Shared pipeline: given tracks, find sources, download, tag, write files."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from .download import download_audio
+from .errors import StashifyError
+from .lyrics import fetch_lyrics
+from .models import Track
+from .output import render_template
+from .sources import find_source
+from .tagger import fetch_cover, tag_file
+
+
+@dataclass
+class TrackOptions:
+    out_dir: Path
+    template: str
+    audio_format: str
+    bitrate: str
+    overwrite: bool = False
+    dry_run: bool = False
+    embed_cover: bool = True
+    embed_lyrics: bool = True
+    jobs: int = 1
+
+
+@dataclass
+class TrackResult:
+    track: Track
+    status: str  # downloaded | skipped | dry-run | failed
+    path: Path | None = None
+    source_url: str = ""
+    detail: str = ""
+
+
+@dataclass
+class _State:
+    claimed: set[Path]
+    cover_cache: dict[str, tuple[bytes, str] | None]
+    claim_lock: threading.Lock
+    cover_lock: threading.Lock
+    print_lock: threading.Lock
+
+    @classmethod
+    def new(cls) -> _State:
+        return cls(
+            claimed=set(),
+            cover_cache={},
+            claim_lock=threading.Lock(),
+            cover_lock=threading.Lock(),
+            print_lock=threading.Lock(),
+        )
+
+
+def target_path(options: TrackOptions, track: Track) -> Path:
+    relative = render_template(options.template, track)
+    extension = options.audio_format.lower().lstrip(".")
+    return Path(options.out_dir).joinpath(*relative.split("/")).with_suffix("." + extension)
+
+
+def _emit(state: _State, progress: Callable[[str], None], message: str) -> None:
+    with state.print_lock:
+        progress(message)
+
+
+def _cover_for(state: _State, track: Track, options: TrackOptions):
+    if not options.embed_cover:
+        return None
+    with state.cover_lock:
+        if track.cover_url in state.cover_cache:
+            return state.cover_cache[track.cover_url]
+    cover = fetch_cover(track)
+    with state.cover_lock:
+        state.cover_cache.setdefault(track.cover_url, cover)
+        return state.cover_cache[track.cover_url]
+
+
+def _process_one(
+    index: int,
+    track: Track,
+    total: int,
+    options: TrackOptions,
+    state: _State,
+    progress: Callable[[str], None],
+) -> TrackResult:
+    label = track.display()
+    prefix = f"[{index}/{total}] {label}"
+    target = target_path(options, track)
+
+    with state.claim_lock:
+        is_duplicate = target in state.claimed
+        state.claimed.add(target)
+
+    if is_duplicate:
+        result = TrackResult(track, "skipped", target, detail="duplicate target in this run")
+        _emit(state, progress, f"{prefix} - skipped (duplicate name)")
+        return result
+    if target.exists() and not options.overwrite:
+        result = TrackResult(track, "skipped", target, detail="already exists")
+        _emit(state, progress, f"{prefix} - skipped (exists)")
+        return result
+
+    try:
+        source = find_source(track)
+    except StashifyError as exc:
+        result = TrackResult(track, "failed", detail=str(exc))
+        _emit(state, progress, f"{prefix} - source not found: {exc}")
+        return result
+
+    if options.dry_run:
+        result = TrackResult(
+            track, "dry-run", target, source_url=source.url, detail=source.title
+        )
+        _emit(state, progress, f"{prefix} - would download: {source.url}")
+        return result
+
+    try:
+        path = download_audio(
+            source,
+            target.with_suffix(""),
+            audio_format=options.audio_format,
+            bitrate=options.bitrate,
+        )
+    except StashifyError as exc:
+        result = TrackResult(track, "failed", source_url=source.url, detail=str(exc))
+        _emit(state, progress, f"{prefix} - download failed: {exc}")
+        return result
+
+    cover = _cover_for(state, track, options)
+    lyrics = fetch_lyrics(track) if options.embed_lyrics else None
+    tag_note = ""
+    try:
+        tag_file(path, track, cover, lyrics)
+    except Exception as exc:  # Keep the audio file; only the tags failed.
+        tag_note = f" (tags not written: {exc})"
+
+    result = TrackResult(track, "downloaded", path, source_url=source.url, detail=tag_note)
+    _emit(state, progress, f"{prefix} - saved: {path}{tag_note}")
+    return result
+
+
+def process_tracks(
+    tracks: list[Track],
+    options: TrackOptions,
+    progress: Callable[[str], None] = print,
+) -> list[TrackResult]:
+    total = len(tracks)
+    state = _State.new()
+    jobs = max(1, options.jobs)
+
+    if jobs <= 1:
+        return [
+            _process_one(index + 1, track, total, options, state, progress)
+            for index, track in enumerate(tracks)
+        ]
+
+    from concurrent.futures import ThreadPoolExecutor
+
+    results: list[TrackResult | None] = [None] * total
+    with ThreadPoolExecutor(max_workers=jobs) as pool:
+        futures = {
+            pool.submit(_process_one, index + 1, track, total, options, state, progress): index
+            for index, track in enumerate(tracks)
+        }
+        for future, index in futures.items():
+            results[index] = future.result()
+    return [result for result in results if result is not None]
+
+
+def summarize(results: list[TrackResult]) -> dict[str, int]:
+    counts = {"downloaded": 0, "skipped": 0, "dry-run": 0, "failed": 0}
+    for result in results:
+        counts[result.status] = counts.get(result.status, 0) + 1
+    return counts