get-spotify 0.1.0__tar.gz

get_spotify-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.venv/
+venv/
+uv.lock.bak
+.env
+*.part
+*.mp3
+*.mp4
+out/
+_tmp.html
+tmp_embed.html
+tmp_dl/
+.python-version
+
+out/

get_spotify-0.1.0/AGENTS.md

@@ -0,0 +1,66 @@
+# AGENTS.md — get-spotify
+
+Guidance for coding agents working in this repository.
+
+## What this project is
+
+A small **stdlib-first Python CLI** that:
+
+1. Accepts a Spotify episode / track / show URL (or `spotify:` URI)
+2. Rewrites it to the public **embed** page
+3. Scrapes **only** `.mp3` / `.mp4` (and `passthroughUrl`) from that HTML
+4. Downloads those files
+
+It does **not** wrap `you-get`, use the Spotify Web API, or bypass DRM/Widevine.
+
+## Layout
+
+| Path | Role |
+| --- | --- |
+| `src/get_spotify/cli.py` | argparse entry, exit codes |
+| `src/get_spotify/urls.py` | URL / URI → embed candidates |
+| `src/get_spotify/embed.py` | fetch HTML + media extraction |
+| `src/get_spotify/download.py` | stream download + safe filenames |
+| `tests/` | fixtures + unit tests (no live Spotify required in CI) |
+| `pyproject.toml` | hatchling package; console script `get-spotify` |
+
+## Commands
+
+```bash
+# Local editable (uv)
+uv sync
+uv run get-spotify "https://open.spotify.com/episode/..." --dry-run -v
+uv run pytest
+
+# Or pip
+python -m pip install -e ".[dev]"
+pytest
+python -m get_spotify "https://open.spotify.com/episode/..." --dry-run
+```
+
+Install from GitHub (after the repo is public):
+
+```bash
+pip install git+https://github.com/involvex/get-spotify.git
+uv tool install git+https://github.com/involvex/get-spotify.git
+```
+
+## Invariants
+
+- **Stdlib networking** (`urllib`) unless the user asks for a HTTP library.
+- **Media filter only**: never download favicons / png / jpeg / ico as the main result.
+- **No DRM circumvention.** If embed HTML has `passthrough: NONE`, preview clips or a clear failure are correct.
+- **Exit codes:** `0` success / dry-run list, `1` no media, `2` bad URL or network, `130` interrupt.
+- Prefer small diffs. Do not add OAuth, playlist batching, or `you-get` unless requested.
+
+## Good change targets
+
+- Better title / filename extraction from embed JSON
+- Clearer messaging when only previews are found
+- Extra fixtures for real embed HTML shapes (sanitized, committed under `tests/fixtures/`)
+
+## Avoid
+
+- Committing downloaded `out/`, `*.mp3`, `*.mp4`, or `_tmp.html`
+- Printing secrets or Spotify auth tokens (this tool should not need them)
+- Claiming full track downloads work for DRM music

get_spotify-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,96 @@
+# 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/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "get-spotify"
+version = "0.1.0"
+description = "Download mp3/mp4 media exposed by Spotify embed pages"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "involvex" }]
+keywords = ["spotify", "podcast", "cli", "download"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Sound/Audio",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://github.com/involvex/get-spotify"
+Repository = "https://github.com/involvex/get-spotify"
+Issues = "https://github.com/involvex/get-spotify/issues"
+
+[project.scripts]
+get-spotify = "get_spotify.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/get_spotify"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/tests",
+  "/README.md",
+  "/AGENTS.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.uv]
+default-groups = ["dev"]
+
+[dependency-groups]
+dev = ["pytest>=8.0"]

get_spotify-0.1.0/src/get_spotify/__init__.py

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

get_spotify-0.1.0/src/get_spotify/__main__.py

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

get_spotify-0.1.0/src/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())