stashify-cli 1.3.0__py3-none-any.whl

stashify/sources.py

@@ -0,0 +1,130 @@
+"""Find the best YouTube source for a Spotify track.
+
+Search results are scored with a transparent heuristic: duration closeness
+and word overlap between the Spotify metadata and the video title. The
+highest scoring candidate wins. Everything here is plain Python, no code is
+fetched or executed from anywhere.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+import yt_dlp
+
+from .models import Track
+
+SEARCH_COUNT = 8
+MIN_ACCEPT_SCORE = 30
+
+_WORD_RE = re.compile(r"[a-z0-9]{3,}")
+_PENALTY_TERMS = (
+    "karaoke", "cover", "reaction", "remix",
+    "live", "instrumental", "sped up", "slowed",
+)
+
+
+@dataclass
+class Source:
+    url: str
+    title: str = ""
+    channel: str = ""
+    duration_seconds: float | None = None
+    score: float = 0.0
+
+
+def _words(text: str) -> set[str]:
+    return set(_WORD_RE.findall((text or "").lower()))
+
+
+def score_candidate(track: Track, candidate_title: str, duration_seconds: float | None) -> float:
+    score = 100.0
+
+    if duration_seconds is not None and track.duration_ms > 0:
+        diff = abs(duration_seconds - track.duration_ms / 1000.0)
+        if diff <= 2:
+            score += 50
+        elif diff <= 10:
+            score += 20
+        elif diff <= 30:
+            score += 0
+        else:
+            score -= 60
+
+    candidate_words = _words(candidate_title)
+    wanted = _words(track.search_query())
+    overlap = len(wanted & candidate_words)
+    score += min(5 * overlap, 25)
+
+    lowered = (candidate_title or "").lower()
+    for term in _PENALTY_TERMS:
+        # Keep the penalty off when the track itself asks for that kind of version.
+        if term in lowered and term not in _words(track.search_query()):
+            score -= 40
+    if "official" in lowered:
+        score += 10
+
+    return score
+
+
+def _search_entries(query: str, search_count: int) -> list[dict]:
+    options = {
+        "quiet": True,
+        "no_warnings": True,
+        "skip_download": True,
+        "extract_flat": True,
+        "default_search": "ytsearch",
+    }
+    try:
+        with yt_dlp.YoutubeDL(options) as ydl:
+            result = ydl.extract_info(f"ytsearch{search_count}:{query}", download=False)
+    except Exception as exc:  # yt-dlp raises many error types; surface one clear message.
+        from .errors import SourceNotFoundError
+
+        raise SourceNotFoundError(f"Could not search YouTube: {exc}") from exc
+    return (result or {}).get("entries") or []
+
+
+def find_source(track: Track, search_count: int = SEARCH_COUNT) -> Source:
+    query = track.search_query()
+    entries = _search_entries(query, search_count)
+    if not entries:
+        # YouTube sometimes returns nothing for the plain "artist - title" query.
+        entries = _search_entries(f"{track.artists_text} {track.title}", search_count)
+    if not entries:
+        entries = _search_entries(
+            f"{track.artists_text} {track.title} audio", search_count
+        )
+
+    best: Source | None = None
+    for entry in entries:
+        if not entry:
+            continue
+        url = entry.get("url") or entry.get("id")
+        if not url:
+            continue
+        if not str(url).startswith("http"):
+            url = f"https://www.youtube.com/watch?v={url}"
+        duration = entry.get("duration")
+        title = entry.get("title") or ""
+        candidate = Source(
+            url=str(url),
+            title=title,
+            channel=(entry.get("channel") or entry.get("uploader") or ""),
+            duration_seconds=float(duration) if duration is not None else None,
+        )
+        candidate.score = score_candidate(track, candidate.title, candidate.duration_seconds)
+        if best is None or candidate.score > best.score:
+            best = candidate
+
+    from .errors import SourceNotFoundError
+
+    if best is None:
+        raise SourceNotFoundError(f"No YouTube results for {track.display()!r}.")
+    if best.score < MIN_ACCEPT_SCORE:
+        raise SourceNotFoundError(
+            f"Best YouTube match for {track.display()!r} looks unreliable "
+            f"(score {best.score:.0f}). Try the full URL instead."
+        )
+    return best

stashify/spotify.py

@@ -0,0 +1,256 @@
+"""Client for the official Spotify Web API.
+
+Uses the client credentials flow. The user supplies their own client id and
+secret, created in a Spotify developer app. No internal or undocumented
+endpoints are used.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+from dataclasses import dataclass
+
+import requests
+
+from .errors import SpotifyApiError, SpotifyAuthError, StashifyError
+from .models import Track
+
+TOKEN_URL = "https://accounts.spotify.com/api/token"
+API_BASE = "https://api.spotify.com/v1"
+DEFAULT_TIMEOUT = 15
+MAX_RETRIES = 3
+_API_UNAVAILABLE_MESSAGE = (
+    "Official Web API access to playlists and artist top tracks was removed by "
+    "Spotify in February 2026 (Development Mode apps). Use the default embed "
+    "provider instead, no credentials needed."
+)
+
+_ID_RE = re.compile(r"^[A-Za-z0-9]{22}$")
+_KINDS = ("track", "album", "playlist", "artist")
+
+_URL_RE = re.compile(
+    r"^(?:(?:https?://)?(?:www\.)?open\.spotify\.com/)?(?P<kind>track|album|playlist|artist)/(?P<id>[A-Za-z0-9]{22})(?:[/?#].*)?$"
+)
+_URI_RE = re.compile(
+    r"^spotify:(?P<kind>track|album|playlist|artist):(?P<id>[A-Za-z0-9]{22})$"
+)
+
+
+def parse_spotify_url(text: str) -> tuple[str, str]:
+    """Extract (kind, id) from a Spotify URL or URI.
+
+    Accepts open.spotify.com URLs, spotify: URIs, and bare "kind:id" pairs.
+    Rejects anything else so user input can never reach a path unchecked.
+    """
+    text = (text or "").strip()
+    for pattern in (_URL_RE, _URI_RE):
+        match = pattern.match(text)
+        if match:
+            return match.group("kind"), match.group("id")
+    match = re.match(r"^(?P<kind>track|album|playlist|artist):(?P<id>[A-Za-z0-9]{22})$", text)
+    if match:
+        return match.group("kind"), match.group("id")
+    raise StashifyError(
+        f"Not a recognized Spotify link: {text!r}. "
+        "Expected a track, album, playlist or artist URL."
+    )
+
+
+def client_credentials_from_env() -> tuple[str, str]:
+    client_id = os.environ.get("SPOTIFY_CLIENT_ID", "").strip()
+    client_secret = os.environ.get("SPOTIFY_CLIENT_SECRET", "").strip()
+    if not client_id or not client_secret:
+        raise StashifyError(
+            "Spotify credentials are not set. Create an app at "
+            "https://developer.spotify.com/dashboard and set SPOTIFY_CLIENT_ID "
+            "and SPOTIFY_CLIENT_SECRET, or pass --client-id and --client-secret."
+        )
+    return client_id, client_secret
+
+
+@dataclass
+class SpotifyClient:
+    client_id: str
+    client_secret: str
+    timeout: int = DEFAULT_TIMEOUT
+    market: str = "US"
+
+    def __post_init__(self) -> None:
+        self._session = requests.Session()
+        self._token: str | None = None
+        self._token_expires_at: float = 0.0
+
+    def _token_now(self) -> str:
+        if self._token and time.time() < self._token_expires_at - 30:
+            return self._token
+        response = self._session.post(
+            TOKEN_URL,
+            data={"grant_type": "client_credentials"},
+            auth=(self.client_id, self.client_secret),
+            timeout=self.timeout,
+        )
+        if response.status_code != 200:
+            raise SpotifyAuthError(
+                "Could not get a Spotify access token. Check that SPOTIFY_CLIENT_ID "
+                "and SPOTIFY_CLIENT_SECRET are correct and that the app is enabled."
+            )
+        payload = response.json()
+        token = payload.get("access_token")
+        if not token:
+            raise SpotifyAuthError("Spotify returned an empty access token.")
+        self._token = token
+        self._token_expires_at = time.time() + float(payload.get("expires_in", 3600))
+        return token
+
+    def _get(self, path: str, params: dict | None = None) -> dict:
+        url = f"{API_BASE}{path}"
+        headers = {"Authorization": f"Bearer {self._token_now()}"}
+        attempts = 0
+        while True:
+            attempts += 1
+            try:
+                response = self._session.get(
+                    url, params=params, headers=headers, timeout=self.timeout
+                )
+            except requests.RequestException as exc:
+                raise SpotifyApiError(f"Could not reach Spotify: {exc}") from exc
+
+            if response.status_code == 401 and attempts <= MAX_RETRIES:
+                self._token = None
+                headers["Authorization"] = f"Bearer {self._token_now()}"
+                continue
+            if response.status_code == 429 and attempts <= MAX_RETRIES:
+                retry_after = response.headers.get("Retry-After")
+                try:
+                    delay = min(float(retry_after), 10.0) if retry_after else 1.0
+                except ValueError:
+                    delay = 1.0
+                time.sleep(delay)
+                continue
+            if response.status_code >= 500 and attempts <= MAX_RETRIES:
+                time.sleep(0.5 * attempts)
+                continue
+            if response.status_code != 200:
+                message = _error_message(response)
+                raise SpotifyApiError(
+                    f"Spotify request failed ({response.status_code}): {message}"
+                )
+            try:
+                return response.json()
+            except ValueError as exc:
+                raise SpotifyApiError("Spotify returned an unreadable response.") from exc
+
+    def _get_paged(self, path: str, params: dict | None = None) -> list[dict]:
+        params = dict(params or {})
+        params.setdefault("limit", 100)
+        params.setdefault("offset", 0)
+        items: list[dict] = []
+        url = path
+        page = 0
+        while url:
+            page += 1
+            if page > 100:
+                raise SpotifyApiError("Spotify pagination exceeded the safety limit.")
+            data = self._get(url, params)
+            items.extend(data.get("items", []))
+            next_url = data.get("next")
+            if next_url:
+                # next is absolute; _get only accepts paths, so strip the base.
+                url = next_url.replace(API_BASE, "", 1)
+                params = {}
+            else:
+                url = ""
+        return items
+
+    # Public API -----------------------------------------------------------
+
+    def fetch_tracks(self, url: str) -> list[Track]:
+        kind, spotify_id = parse_spotify_url(url)
+        if kind == "track":
+            return [self.track_from_api(self._get(f"/tracks/{spotify_id}"))]
+        if kind == "album":
+            return self._album_tracks(spotify_id)
+        raise StashifyError(_API_UNAVAILABLE_MESSAGE)
+
+    def track_from_api(self, data: dict) -> Track:
+        album = data.get("album") or {}
+        external_ids = data.get("external_ids") or {}
+        artists = [a.get("name", "") for a in data.get("artists") or [] if a.get("name")]
+        album_artists = [
+            a.get("name", "") for a in album.get("artists") or [] if a.get("name")
+        ]
+        images = album.get("images") or []
+        cover = _largest_image(images)
+        return Track(
+            title=data.get("name", ""),
+            artists=artists,
+            album=album.get("name", ""),
+            album_artist=album_artists[0] if album_artists else "",
+            track_number=int(data.get("track_number") or 0),
+            disc_number=int(data.get("disc_number") or 1),
+            total_tracks=int(album.get("total_tracks") or 0),
+            duration_ms=int(data.get("duration_ms") or 0),
+            release_date=str(album.get("release_date") or ""),
+            isrc=str(external_ids.get("isrc") or ""),
+            cover_url=cover,
+            spotify_url=(data.get("external_urls") or {}).get("spotify", ""),
+            explicit=bool(data.get("explicit") or False),
+        )
+
+    def _album_tracks(self, album_id: str) -> list[Track]:
+        album = self._get(f"/albums/{album_id}")
+        tracks_data = self._get_paged(f"/albums/{album_id}/tracks")
+        images = (album or {}).get("images") or []
+        cover = _largest_image(images)
+        album_artists = [
+            a.get("name", "") for a in album.get("artists") or [] if a.get("name")
+        ]
+        album_artist = album_artists[0] if album_artists else ""
+        total_tracks = int(album.get("total_tracks") or len(tracks_data))
+        release_date = str(album.get("release_date") or "")
+        tracks: list[Track] = []
+        for item in tracks_data:
+            track = self.track_from_api(
+                {
+                    **item,
+                    "album": {
+                        "name": album.get("name", ""),
+                        "artists": album.get("artists") or [],
+                        "images": images,
+                        "total_tracks": total_tracks,
+                        "release_date": release_date,
+                    },
+                }
+            )
+            track.cover_url = cover
+            track.album_artist = album_artist
+            tracks.append(track)
+        return tracks
+
+
+def _largest_image(images: list[dict]) -> str:
+    if not images:
+        return ""
+
+    def area(image: dict) -> int:
+        return int(image.get("width") or 0) * int(image.get("height") or 0)
+
+    return str(max(images, key=area).get("url") or "")
+
+
+def _error_message(response: requests.Response) -> str:
+    try:
+        payload = response.json()
+    except ValueError:
+        text = (response.text or "").strip().replace("\n", " ")
+        return text[:200] if text else "no details"
+    error = payload.get("error") if isinstance(payload, dict) else None
+    if isinstance(error, dict):
+        message = error.get("message") or error.get("error_description")
+        if message:
+            return str(message)
+    if isinstance(error, str):
+        return error
+    return "no details"

stashify/sync.py

@@ -0,0 +1,93 @@
+"""State files for keeping a local directory in sync with a playlist.
+
+The state file is plain JSON. It records which tracks were downloaded into
+which paths, so a later `stashify sync` can add new songs and remove files
+that disappeared from the playlist, without touching anything else the user
+put in the folder.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .errors import StashifyError
+from .models import Track
+
+STATE_VERSION = 1
+
+
+def track_key(track: Track) -> str:
+    if track.spotify_url:
+        return track.spotify_url
+    return f"{track.artist}-{track.album}-{track.title}-{track.track_number}"
+
+
+def load_state(path: Path) -> dict:
+    path = Path(path)
+    if not path.exists():
+        return {"version": STATE_VERSION, "url": "", "entries": []}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise StashifyError(f"Could not read state file {path}: {exc}") from exc
+    if not isinstance(data, dict) or not isinstance(data.get("entries", []), list):
+        raise StashifyError(f"State file {path} is not a Stashify state file.")
+    data.setdefault("version", STATE_VERSION)
+    data.setdefault("url", "")
+    data.setdefault("entries", [])
+    return data
+
+
+def save_state(path: Path, state: dict) -> None:
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(state, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+
+
+def plan_sync(state: dict, current: list[Track]) -> tuple[list[Track], list[dict]]:
+    """Return (tracks to download, entries to remove)."""
+    current_keys = {track_key(t) for t in current}
+    existing = {entry.get("key"): entry for entry in state.get("entries", [])}
+    missing = [t for t in current if track_key(t) not in existing]
+    removed = [entry for key, entry in existing.items() if key not in current_keys]
+    return missing, removed
+
+
+def remove_entries(removed: list[dict], out_dir: Path) -> list[str]:
+    """Delete files referenced by removed entries, confined to out_dir."""
+    out_dir = Path(out_dir).resolve()
+    deleted: list[str] = []
+    for entry in removed:
+        rel = entry.get("path")
+        if not rel:
+            continue
+        # Older state files may contain OS-native separators; normalize both.
+        rel = str(rel).replace("\\", "/")
+        candidate = (out_dir / rel).resolve()
+        try:
+            candidate.relative_to(out_dir)
+        except ValueError:
+            continue  # Never delete outside the output directory.
+        try:
+            candidate.unlink()
+            deleted.append(str(candidate))
+        except OSError:
+            continue
+    return deleted
+
+
+def state_entry(track: Track, path: Path, out_dir: Path) -> dict:
+    try:
+        rel = Path(path).resolve().relative_to(Path(out_dir).resolve())
+    except ValueError:
+        rel = Path(path)
+    # Always store forward slashes so the file can be moved across OSes.
+    return {
+        "key": track_key(track),
+        "path": rel.as_posix(),
+        "title": track.title,
+        "artist": track.artist,
+    }