get-spotify 0.1.0__py3-none-any.whl

get_spotify/__init__.py

@@ -0,0 +1,3 @@
+"""Download mp3/mp4 media exposed by Spotify embed pages."""
+
+__version__ = "0.1.0"

get_spotify/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m get_spotify``."""
+
+from get_spotify.cli import main
+
+raise SystemExit(main())

get_spotify/cli.py

@@ -0,0 +1,222 @@
+"""Command-line entry point for get-spotify."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from get_spotify import __version__
+from get_spotify.download import DownloadError, build_filename, download_file
+from get_spotify.embed import (
+    EmbedError,
+    EmbedResult,
+    MediaCandidate,
+    fetch_embed,
+)
+from get_spotify.urls import SpotifyRef, UrlError, parse_spotify_url
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="get-spotify",
+        description=(
+            "Download mp3/mp4 media URLs exposed by Spotify embed pages. "
+            "Works best for podcasts/episodes with passthrough media; "
+            "full music tracks are usually DRM-protected and will fail."
+        ),
+    )
+    parser.add_argument(
+        "url",
+        help="Spotify episode, track, show, or embed URL (or spotify: URI)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default=".",
+        help="Output directory (default: current directory)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="List discovered media URLs without downloading",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Print extra diagnostics",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser
+
+
+def _log(verbose: bool, message: str) -> None:
+    if verbose:
+        print(message, file=sys.stderr)
+
+
+def _is_full_media(media: list[MediaCandidate]) -> bool:
+    return any(item.kind != "preview" for item in media)
+
+
+def _merge_media(
+    existing: list[MediaCandidate],
+    incoming: list[MediaCandidate],
+) -> list[MediaCandidate]:
+    bucket = {item.url: item for item in existing}
+    for item in incoming:
+        prev = bucket.get(item.url)
+        if prev is None or (
+            item.kind != "preview" and prev.kind == "preview"
+        ):
+            bucket[item.url] = item
+    merged = list(bucket.values())
+    if _is_full_media(merged):
+        return [item for item in merged if item.kind != "preview"]
+    return merged
+
+
+def _discover_for_ref(
+    ref: SpotifyRef,
+    *,
+    verbose: bool,
+) -> tuple[EmbedResult | None, list[MediaCandidate]]:
+    last_result: EmbedResult | None = None
+    media: list[MediaCandidate] = []
+    for page_url in ref.embed_candidates():
+        _log(verbose, f"Fetching embed: {page_url}")
+        result = fetch_embed(page_url)
+        last_result = result
+        if result.media:
+            media = _merge_media(media, result.media)
+            if _is_full_media(media):
+                return result, media
+            _log(verbose, f"Only preview media in {page_url}; trying next")
+        else:
+            _log(verbose, f"No media in {page_url}")
+    return last_result, media
+
+
+def _resolve_media(
+    ref: SpotifyRef,
+    *,
+    verbose: bool,
+) -> tuple[SpotifyRef, EmbedResult | None, list[MediaCandidate]]:
+    result, media = _discover_for_ref(ref, verbose=verbose)
+    if media:
+        return ref, result, media
+
+    # Show pages: try the first linked episode.
+    if ref.type == "show" and result and result.episode_ids:
+        episode_id = result.episode_ids[0]
+        _log(verbose, f"Show has no direct media; trying episode {episode_id}")
+        episode_ref = SpotifyRef(type="episode", id=episode_id)
+        episode_result, episode_media = _discover_for_ref(
+            episode_ref,
+            verbose=verbose,
+        )
+        return episode_ref, episode_result, episode_media
+
+    return ref, result, []
+
+
+def _preview_only(media: list[MediaCandidate]) -> bool:
+    return bool(media) and all(item.kind == "preview" for item in media)
+
+
+def run(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        ref = parse_spotify_url(args.url)
+    except UrlError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    try:
+        active_ref, result, media = _resolve_media(ref, verbose=args.verbose)
+    except EmbedError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    title = result.title if result else None
+    if args.verbose and title:
+        _log(True, f"Title: {title}")
+
+    if not media:
+        if ref.type == "track":
+            print(
+                "error: no downloadable mp3/mp4 found for this track. "
+                "Spotify music is usually DRM-protected; only short "
+                "previews (or nothing) appear in the public embed.",
+                file=sys.stderr,
+            )
+        else:
+            print(
+                "error: no downloadable mp3/mp4 found in the Spotify embed. "
+                "This episode may be DRM-protected or lack passthrough media "
+                '(passthrough: "NONE").',
+                file=sys.stderr,
+            )
+        return 1
+
+    if _preview_only(media):
+        if active_ref.type == "track":
+            print(
+                "note: only a short Spotify preview was found for this track "
+                "(full songs are not available via embed).",
+                file=sys.stderr,
+            )
+        else:
+            print(
+                "note: only preview media was found "
+                "(no passthrough/full mp3/mp4 in the embed HTML).",
+                file=sys.stderr,
+            )
+
+    if args.dry_run:
+        for item in media:
+            print(f"{item.kind}\t{item.ext}\t{item.url}")
+        return 0
+
+    output_dir = Path(args.output)
+    saved = 0
+    for index, item in enumerate(media, start=1):
+        filename = build_filename(
+            item,
+            title=title,
+            resource_id=active_ref.id,
+            index=index,
+            total=len(media),
+        )
+        dest = output_dir / filename
+        _log(args.verbose, f"Saving {item.kind} -> {dest}")
+        try:
+            path = download_file(item, dest, progress=True)
+        except DownloadError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            continue
+        print(f"saved: {path}")
+        saved += 1
+
+    if saved == 0:
+        return 1
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        return run(argv)
+    except KeyboardInterrupt:
+        print("interrupted", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

get_spotify/download.py

@@ -0,0 +1,125 @@
+"""Stream-download media files with safe filenames."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from get_spotify.embed import USER_AGENT, MediaCandidate
+
+_WINDOWS_BAD = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
+_MULTI_SPACE = re.compile(r"\s+")
+
+
+class DownloadError(RuntimeError):
+    """Raised when a media file cannot be downloaded."""
+
+
+def sanitize_filename(name: str, *, max_len: int = 120) -> str:
+    """Make a string safe for Windows and POSIX filenames."""
+    cleaned = _WINDOWS_BAD.sub("", name)
+    cleaned = cleaned.replace("\n", " ").replace("\r", " ")
+    cleaned = _MULTI_SPACE.sub(" ", cleaned).strip(" .")
+    if not cleaned:
+        cleaned = "spotify-media"
+    if len(cleaned) > max_len:
+        cleaned = cleaned[:max_len].rstrip(" .")
+    return cleaned
+
+
+def build_filename(
+    candidate: MediaCandidate,
+    *,
+    title: str | None,
+    resource_id: str,
+    index: int,
+    total: int,
+) -> str:
+    base = sanitize_filename(title) if title else sanitize_filename(resource_id)
+    if total > 1:
+        base = f"{base}-{index}"
+    if candidate.kind == "preview" and "preview" not in base.lower():
+        base = f"{base}-preview"
+    return f"{base}.{candidate.ext}"
+
+
+def _content_ok(content_type: str | None, ext: str) -> bool:
+    if not content_type:
+        return True
+    ctype = content_type.split(";", 1)[0].strip().lower()
+    if ctype in {"application/octet-stream", "binary/octet-stream"}:
+        return True
+    if ext == "mp3":
+        return ctype in {"audio/mpeg", "audio/mp3", "audio/mpeg3", "audio/x-mpeg"}
+    if ext == "mp4":
+        return ctype in {
+            "video/mp4",
+            "audio/mp4",
+            "application/mp4",
+            "video/mpeg",
+        }
+    return False
+
+
+def download_file(
+    candidate: MediaCandidate,
+    dest: Path,
+    *,
+    timeout: float = 60.0,
+    progress: bool = True,
+) -> Path:
+    """Download one media URL to dest. Returns the final path."""
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    request = Request(
+        candidate.url,
+        headers={
+            "User-Agent": USER_AGENT,
+            "Accept": "*/*",
+            "Referer": "https://open.spotify.com/",
+        },
+    )
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            content_type = response.headers.get("Content-Type")
+            if not _content_ok(content_type, candidate.ext):
+                raise DownloadError(
+                    f"Skipping {candidate.url}: unexpected Content-Type "
+                    f"{content_type!r}"
+                )
+            total = response.headers.get("Content-Length")
+            total_bytes = int(total) if total and total.isdigit() else None
+            tmp = dest.with_suffix(dest.suffix + ".part")
+            downloaded = 0
+            with tmp.open("wb") as handle:
+                while True:
+                    chunk = response.read(64 * 1024)
+                    if not chunk:
+                        break
+                    handle.write(chunk)
+                    downloaded += len(chunk)
+                    if progress:
+                        _print_progress(dest.name, downloaded, total_bytes)
+            tmp.replace(dest)
+            if progress:
+                sys.stderr.write("\n")
+                sys.stderr.flush()
+            return dest
+    except HTTPError as exc:
+        raise DownloadError(f"HTTP {exc.code} downloading {candidate.url}") from exc
+    except URLError as exc:
+        raise DownloadError(
+            f"Network error downloading {candidate.url}: {exc.reason}"
+        ) from exc
+
+
+def _print_progress(name: str, downloaded: int, total: int | None) -> None:
+    if total:
+        pct = min(100.0, downloaded * 100.0 / total)
+        msg = f"\rDownloading {name}: {pct:5.1f}% ({downloaded}/{total} bytes)"
+    else:
+        msg = f"\rDownloading {name}: {downloaded} bytes"
+    sys.stderr.write(msg)
+    sys.stderr.flush()

get_spotify/embed.py

@@ -0,0 +1,332 @@
+"""Fetch Spotify embed HTML and extract mp3/mp4 media URLs."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from html import unescape
+from typing import Iterable
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+USER_AGENT = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/122.0.0.0 Safari/537.36"
+)
+
+PREVIEW_HINTS = (
+    "p.scdn.co/mp3-preview/",
+    "smart-preview-clips.spotifycdn.com",
+    "/previews/",
+)
+IMAGE_EXT = (".png", ".jpg", ".jpeg", ".gif", ".svg", ".ico", ".webp")
+_NAME_RE = re.compile(r'"name"\s*:\s*"((?:\\.|[^"\\])*)"')
+
+_TITLE_RE = re.compile(r"<title[^>]*>([^<]*)</title>", re.IGNORECASE | re.DOTALL)
+_OG_VIDEO_RE = re.compile(
+    r'<meta[^>]+property=["\']og:video(?::url)?["\'][^>]+content=["\']([^"\']+)["\']',
+    re.IGNORECASE,
+)
+_OG_VIDEO_RE_ALT = re.compile(
+    r'<meta[^>]+content=["\']([^"\']+)["\'][^>]+property=["\']og:video(?::url)?["\']',
+    re.IGNORECASE,
+)
+_OG_AUDIO_RE = re.compile(
+    r'<meta[^>]+property=["\']og:audio(?::url)?["\'][^>]+content=["\']([^"\']+)["\']',
+    re.IGNORECASE,
+)
+_OG_AUDIO_RE_ALT = re.compile(
+    r'<meta[^>]+content=["\']([^"\']+)["\'][^>]+property=["\']og:audio(?::url)?["\']',
+    re.IGNORECASE,
+)
+_PASSTHROUGH_RE = re.compile(
+    r'"passthroughUrl"\s*:\s*"(https?://[^"\\]+)"',
+    re.IGNORECASE,
+)
+_MEDIA_URL_RE = re.compile(
+    r'https?://[^\s"\'<>\\]+?\.(?:mp3|mp4)(?:\?[^\s"\'<>\\]*)?',
+    re.IGNORECASE,
+)
+_EPISODE_LINK_RE = re.compile(
+    r"https?://open\.spotify\.com/(?:embed/)?episode/([A-Za-z0-9]+)",
+    re.IGNORECASE,
+)
+_ESCAPED_MEDIA_RE = re.compile(
+    r'https?:\\+/\\+/[^\s"\'<>]+?\.(?:mp3|mp4)(?:\\?[^"\'\\]*)?',
+    re.IGNORECASE,
+)
+
+
+@dataclass(frozen=True)
+class MediaCandidate:
+    """A downloadable media URL discovered in an embed page."""
+
+    url: str
+    ext: str
+    kind: str  # passthrough | video | preview | unknown
+
+
+@dataclass(frozen=True)
+class EmbedResult:
+    """Parsed result from one embed page fetch."""
+
+    page_url: str
+    title: str | None
+    media: list[MediaCandidate]
+    episode_ids: list[str]
+
+
+class EmbedError(RuntimeError):
+    """Raised when an embed page cannot be fetched."""
+
+
+def fetch_html(url: str, *, timeout: float = 30.0) -> str:
+    """GET a URL and return decoded HTML text."""
+    request = Request(
+        url,
+        headers={
+            "User-Agent": USER_AGENT,
+            "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+            "Accept-Language": "en-US,en;q=0.9",
+        },
+    )
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            charset = response.headers.get_content_charset() or "utf-8"
+            return response.read().decode(charset, errors="replace")
+    except HTTPError as exc:
+        raise EmbedError(f"HTTP {exc.code} fetching {url}") from exc
+    except URLError as exc:
+        raise EmbedError(f"Network error fetching {url}: {exc.reason}") from exc
+
+
+def extract_title(html: str) -> str | None:
+    match = _TITLE_RE.search(html)
+    if match:
+        title = unescape(match.group(1)).strip()
+        title = re.sub(r"\s*\|\s*Spotify\s*$", "", title, flags=re.IGNORECASE)
+        if title:
+            return title
+
+    # Embed pages often ship an empty <title>; fall back to JSON "name".
+    for match in _NAME_RE.finditer(html):
+        raw = match.group(1)
+        try:
+            name = json.loads(f'"{raw}"')
+        except json.JSONDecodeError:
+            name = unescape(raw)
+        name = str(name).strip()
+        if name and name.lower() != "spotify":
+            return name
+    return None
+
+
+def _ext_from_url(url: str) -> str:
+    path = url.split("?", 1)[0].lower()
+    if path.endswith(".mp4"):
+        return "mp4"
+    if path.endswith(".mp3"):
+        return "mp3"
+    # Preview hosts sometimes omit a real extension in path segments.
+    if "mp3-preview" in path:
+        return "mp3"
+    return "mp3"
+
+
+def _is_preview_url(url: str) -> bool:
+    lower = url.lower()
+    return any(hint in lower for hint in PREVIEW_HINTS)
+
+
+def _kind_for(url: str, *, forced: str | None = None) -> str:
+    if forced == "passthrough":
+        return "passthrough"
+    if forced == "preview" or _is_preview_url(url):
+        return "preview"
+    if forced:
+        return forced
+    if url.lower().split("?", 1)[0].endswith(".mp4"):
+        return "video"
+    return "unknown"
+
+
+def _is_image_url(url: str) -> bool:
+    path = url.split("?", 1)[0].lower()
+    return any(path.endswith(ext) for ext in IMAGE_EXT)
+
+
+def _normalize_url(url: str) -> str:
+    url = unescape(url.strip())
+    url = url.replace("\\/", "/")
+    url = url.replace("\\u0026", "&")
+    return url
+
+
+def _add_candidate(
+    bucket: dict[str, MediaCandidate],
+    url: str,
+    *,
+    kind: str | None = None,
+) -> None:
+    url = _normalize_url(url)
+    if not url.startswith("http"):
+        return
+    if _is_image_url(url):
+        return
+    ext = _ext_from_url(url)
+    if ext not in {"mp3", "mp4"}:
+        return
+    candidate = MediaCandidate(
+        url=url,
+        ext=ext,
+        kind=_kind_for(url, forced=kind),
+    )
+    existing = bucket.get(url)
+    if existing is None:
+        bucket[url] = candidate
+        return
+    # Prefer more specific kinds over unknown/preview.
+    rank = {
+        "passthrough": 3,
+        "video": 2,
+        "unknown": 1,
+        "preview": 0,
+    }
+    if rank.get(candidate.kind, 0) > rank.get(existing.kind, 0):
+        bucket[url] = candidate
+
+
+def _walk_json(node: object) -> Iterable[tuple[str, str | None]]:
+    """Yield (url, kind_hint) pairs from nested JSON-like structures."""
+    if isinstance(node, dict):
+        passthrough = node.get("passthroughUrl")
+        if isinstance(passthrough, str) and passthrough:
+            yield passthrough, "passthrough"
+
+        audio_preview = node.get("audioPreview")
+        if isinstance(audio_preview, dict):
+            preview_url = audio_preview.get("url")
+            if isinstance(preview_url, str) and preview_url:
+                yield preview_url, "preview"
+
+        audio = node.get("audio")
+        if isinstance(audio, dict):
+            items = audio.get("items") or []
+            if isinstance(items, list):
+                for item in items:
+                    if not isinstance(item, dict):
+                        continue
+                    item_url = item.get("url")
+                    if not isinstance(item_url, str) or not item_url:
+                        continue
+                    if item.get("externallyHosted"):
+                        yield item_url, "passthrough"
+                    elif ".mp3" in item_url.lower() or ".mp4" in item_url.lower():
+                        yield item_url, None
+
+        for value in node.values():
+            yield from _walk_json(value)
+    elif isinstance(node, list):
+        for item in node:
+            yield from _walk_json(item)
+
+
+def _extract_json_blobs(html: str) -> list[object]:
+    blobs: list[object] = []
+    # Common embed payload markers.
+    patterns = [
+        r'<script[^>]+id="__NEXT_DATA__"[^>]*>(\{.*?\})</script>',
+        r"Spotify\.Entity\s*=\s*(\{.*?\});",
+        r'"props"\s*:\s*(\{.*?\})\s*,\s*"page"',
+    ]
+    for pattern in patterns:
+        for match in re.finditer(pattern, html, re.DOTALL):
+            raw = match.group(1)
+            try:
+                blobs.append(json.loads(raw))
+            except json.JSONDecodeError:
+                continue
+    return blobs
+
+
+def extract_media(html: str) -> list[MediaCandidate]:
+    """Extract mp3/mp4 candidates from embed HTML."""
+    bucket: dict[str, MediaCandidate] = {}
+
+    for match in _PASSTHROUGH_RE.finditer(html):
+        _add_candidate(bucket, match.group(1), kind="passthrough")
+
+    for blob in _extract_json_blobs(html):
+        for url, kind in _walk_json(blob):
+            _add_candidate(bucket, url, kind=kind)
+
+    # Also try to parse large JSON-looking substrings that include passthrough.
+    for match in re.finditer(r"\{[^{}]*passthroughUrl[^{}]*\}", html):
+        try:
+            obj = json.loads(match.group(0))
+        except json.JSONDecodeError:
+            continue
+        for url, kind in _walk_json(obj):
+            _add_candidate(bucket, url, kind=kind)
+
+    for regex in (_OG_VIDEO_RE, _OG_VIDEO_RE_ALT):
+        for match in regex.finditer(html):
+            _add_candidate(bucket, match.group(1), kind="video")
+
+    for regex in (_OG_AUDIO_RE, _OG_AUDIO_RE_ALT):
+        for match in regex.finditer(html):
+            _add_candidate(bucket, match.group(1), kind=None)
+
+    for match in _MEDIA_URL_RE.finditer(html):
+        _add_candidate(bucket, match.group(0), kind=None)
+
+    for match in _ESCAPED_MEDIA_RE.finditer(html):
+        _add_candidate(bucket, match.group(0), kind=None)
+
+    return _rank_media(list(bucket.values()))
+
+
+def _rank_media(media: list[MediaCandidate]) -> list[MediaCandidate]:
+    """Prefer passthrough/full media over short previews when both exist."""
+    rank = {
+        "passthrough": 0,
+        "video": 1,
+        "unknown": 2,
+        "preview": 3,
+    }
+    sorted_media = sorted(
+        media,
+        key=lambda m: (rank.get(m.kind, 9), m.ext != "mp3", m.url),
+    )
+    has_full = any(m.kind in {"passthrough", "video", "unknown"} for m in sorted_media)
+    if has_full:
+        return [m for m in sorted_media if m.kind != "preview"]
+    return sorted_media
+
+
+def extract_episode_ids(html: str) -> list[str]:
+    """Collect episode ids linked from a show embed page."""
+    seen: set[str] = set()
+    ordered: list[str] = []
+    for match in _EPISODE_LINK_RE.finditer(html):
+        episode_id = match.group(1)
+        if episode_id not in seen:
+            seen.add(episode_id)
+            ordered.append(episode_id)
+    return ordered
+
+
+def parse_embed(page_url: str, html: str) -> EmbedResult:
+    return EmbedResult(
+        page_url=page_url,
+        title=extract_title(html),
+        media=extract_media(html),
+        episode_ids=extract_episode_ids(html),
+    )
+
+
+def fetch_embed(page_url: str, *, timeout: float = 30.0) -> EmbedResult:
+    html = fetch_html(page_url, timeout=timeout)
+    return parse_embed(page_url, html)

get_spotify/urls.py

@@ -0,0 +1,95 @@
+"""Parse Spotify URLs and normalize them to embed player URLs."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+SUPPORTED_TYPES = frozenset({"episode", "track", "show"})
+
+# open.spotify.com/{embed/}?{type}/{id}[/video]
+_OPEN_PATH = re.compile(
+    r"^/(?:embed/)?(?P<type>episode|track|show)/(?P<id>[A-Za-z0-9]+)"
+    r"(?P<video>/video)?/?$",
+    re.IGNORECASE,
+)
+
+# spotify:episode:ID / spotify:track:ID / spotify:show:ID
+_URI = re.compile(
+    r"^spotify:(?P<type>episode|track|show):(?P<id>[A-Za-z0-9]+)$",
+    re.IGNORECASE,
+)
+
+
+@dataclass(frozen=True)
+class SpotifyRef:
+    """A normalized Spotify resource reference."""
+
+    type: str
+    id: str
+    video: bool = False
+
+    def embed_url(self, *, video: bool | None = None) -> str:
+        use_video = self.video if video is None else video
+        base = f"https://open.spotify.com/embed/{self.type}/{self.id}"
+        if use_video and self.type == "episode":
+            return f"{base}/video"
+        return base
+
+    def embed_candidates(self) -> list[str]:
+        """Ordered embed URLs to try (prefer the form the user opened)."""
+        if self.type != "episode":
+            return [self.embed_url(video=False)]
+
+        primary = self.embed_url(video=self.video)
+        secondary = self.embed_url(video=not self.video)
+        urls = [primary]
+        if secondary not in urls:
+            urls.append(secondary)
+        return urls
+
+
+class UrlError(ValueError):
+    """Raised when the input is not a supported Spotify URL."""
+
+
+def parse_spotify_url(raw: str) -> SpotifyRef:
+    """Parse an open.spotify.com URL or spotify: URI into a SpotifyRef."""
+    text = (raw or "").strip()
+    if not text:
+        raise UrlError("URL is empty")
+
+    uri_match = _URI.match(text)
+    if uri_match:
+        return SpotifyRef(
+            type=uri_match.group("type").lower(),
+            id=uri_match.group("id"),
+        )
+
+    if not re.match(r"^https?://", text, re.IGNORECASE):
+        text = "https://" + text
+
+    parsed = urlparse(text)
+    host = (parsed.hostname or "").lower()
+    if host not in {"open.spotify.com", "www.open.spotify.com"}:
+        raise UrlError(
+            f"Unsupported host {host!r}; expected open.spotify.com"
+        )
+
+    path_match = _OPEN_PATH.match(parsed.path or "")
+    if not path_match:
+        raise UrlError(
+            "Unsupported Spotify path; expected "
+            "/episode|/track|/show/{id} (or /embed/...)"
+        )
+
+    resource_type = path_match.group("type").lower()
+    if resource_type not in SUPPORTED_TYPES:
+        raise UrlError(f"Unsupported resource type {resource_type!r}")
+
+    return SpotifyRef(
+        type=resource_type,
+        id=path_match.group("id"),
+        video=bool(path_match.group("video")),
+    )

get_spotify-0.1.0.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: get-spotify
+Version: 0.1.0
+Summary: Download mp3/mp4 media exposed by Spotify embed pages
+Project-URL: Homepage, https://github.com/involvex/get-spotify
+Project-URL: Repository, https://github.com/involvex/get-spotify
+Project-URL: Issues, https://github.com/involvex/get-spotify/issues
+Author: involvex
+License-Expression: MIT
+Keywords: cli,download,podcast,spotify
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# get-spotify
+
+CLI that downloads **mp3/mp4** media URLs exposed by Spotify **embed** pages.
+
+It does **not** bypass DRM. It only downloads direct media links already present
+in the public embed HTML (the same approach as feeding an embed URL to
+`you-get`'s universal scraper, but with a strict media-only filter so favicons
+and images are skipped).
+
+## Install
+
+### From GitHub (pip)
+
+```bash
+pip install git+https://github.com/involvex/get-spotify.git
+```
+
+### From GitHub (uv)
+
+```bash
+# Install as a user tool (gets the `get-spotify` command)
+uv tool install git+https://github.com/involvex/get-spotify.git
+
+# Or one-off without installing permanently
+uvx --from git+https://github.com/involvex/get-spotify.git get-spotify --help
+```
+
+### Local development
+
+With **uv** (recommended):
+
+```bash
+uv sync
+uv run get-spotify --help
+uv run pytest
+```
+
+With **pip**:
+
+```bash
+python -m pip install -e ".[dev]"
+python -m get_spotify --help
+pytest
+```
+
+## Usage
+
+```bash
+get-spotify <spotify-url> [-o DIR] [--dry-run] [-v]
+```
+
+Examples:
+
+```bash
+# Podcast episode
+get-spotify "https://open.spotify.com/episode/1TzHqdEz21lHPS9Akc9vRl"
+
+# Already an embed / video embed URL
+get-spotify "https://open.spotify.com/embed/episode/1TzHqdEz21lHPS9Akc9vRl/video"
+
+# List media URLs without downloading
+get-spotify "https://open.spotify.com/episode/..." --dry-run
+
+# Track (usually fails or only finds a short preview)
+get-spotify "https://open.spotify.com/track/..." -v
+```
+
+### Exit codes
+
+| Code | Meaning |
+| ---: | --- |
+| 0 | At least one file saved (or listed with `--dry-run`) |
+| 1 | Valid Spotify URL, but no downloadable mp3/mp4 |
+| 2 | Bad URL or network/HTTP failure |
+
+## What works / what does not
+
+| Input | Typical result |
+| --- | --- |
+| Podcast/episode with publisher passthrough (`passthroughUrl`) | Downloads full mp3 (and mp4 when the video embed exposes it) |
+| Episode with DRM / `passthrough: NONE` | Downloads only short preview clips if the embed exposes them; prints a note |
+| Music track | Usually preview-only or empty; full songs are DRM-protected |
+| Show URL | Tries the show embed, then the first linked episode |
+
+## How it works
+
+1. Normalize the input to `https://open.spotify.com/embed/{type}/{id}`
+2. For episodes, also try `.../video` if the audio embed has no media
+3. Parse embed HTML for `passthroughUrl`, Open Graph media, and `.mp3`/`.mp4` links
+4. Download only those files
+
+## Disclaimer
+
+Use this only for content you have the right to download. Spotify's terms
+restrict downloading Spotify-hosted/DRM content. Publisher-hosted podcast files
+exposed via passthrough are still subject to the publisher's rights.

get_spotify-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+get_spotify/__init__.py,sha256=Lb9ln7ut_CsepsdP_EuRw0OSfa1Ta2nlU1BpfLRY-64,87
+get_spotify/__main__.py,sha256=pecbDlHSzDaxUm4ZEgMt2T6lz4zOxGDreg1L-Axr7k0,104
+get_spotify/cli.py,sha256=5Mt6V0ymDo6U8mTBQv1KEdtdoD5Mqc3TO9tVJyysBTQ,6710
+get_spotify/download.py,sha256=0zAlztvxuOnQJ3Rk_SAqq7S6PBn3Dyr0GzRrYg7xqLg,4167
+get_spotify/embed.py,sha256=2nUQAryVWXd1o3_4PxfHFnZ24ntVIFHle2YFPC1_X5s,10566
+get_spotify/urls.py,sha256=fXTpxpCtaSrcTsG4TliBxpy-SxN_6Is2BpUOYaK84i0,2908
+get_spotify-0.1.0.dist-info/METADATA,sha256=60eOAqQgCiZSuG_d1YJ9cP1iDxMCWuuWaDOcwfhL6R0,3395
+get_spotify-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+get_spotify-0.1.0.dist-info/entry_points.txt,sha256=awzfubxfUuu6dvkdmtr4kCJxiw_fVB8NhQiSoRx4jcg,53
+get_spotify-0.1.0.dist-info/RECORD,,

get_spotify-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

get_spotify-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+get-spotify = get_spotify.cli:main