spotify-auto-dl 0.1.0__tar.gz

spotify_auto_dl-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: spotify-auto-dl
+Version: 0.1.0
+Summary: Automatically download new releases from your favorite artists using spotdl
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: spotdl>=4.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: spotipy>=2.23.0
+
+# Spotify Auto Downloader
+
+Automatically download new releases from your favorite Spotify artists to a local drive. Tracks artists you care about, downloads only songs you don't already have, and can run on a schedule to stay up to date automatically.
+
+## How It Works
+
+1. You provide a list of Spotify artist URLs in a config file
+2. On each run, the tool fetches each artist's full discography from Spotify
+3. It compares against a local state file to find tracks you don't have yet
+4. New tracks are downloaded as MP3s via [spotdl](https://github.com/spotDL/spotify-downloader)
+5. The state file is updated so those tracks are skipped on future runs
+
+---
+
+## Requirements
+
+- Python 3.10 or higher
+- A [Spotify Developer account](https://developer.spotify.com/dashboard) (free)
+- `ffmpeg` installed on your machine
+
+Install ffmpeg on Mac:
+```bash
+brew install ffmpeg
+```
+
+---
+
+## Installation
+
+**1. Clone the repo**
+```bash
+git clone https://github.com/your-username/spotify-auto-downloader.git
+cd spotify-auto-downloader
+```
+
+**2. Create and activate a virtual environment**
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+**3. Install the package**
+```bash
+pip install .
+```
+
+---
+
+## Spotify API Credentials
+
+This tool uses the Spotify API to look up artist discographies. You need a free client ID and secret.
+
+1. Go to [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard)
+2. Click **Create App**
+3. Fill in any name and description, set the redirect URI to `http://localhost`
+4. Open the app and copy the **Client ID** and **Client Secret**
+
+**4. Set up your credentials**
+```bash
+cp .env.example .env
+```
+
+Open `.env` and fill in your credentials:
+```
+SPOTIFY_CLIENT_ID=your_client_id_here
+SPOTIFY_CLIENT_SECRET=your_client_secret_here
+```
+
+---
+
+## Configuration
+
+**5. Create your config file**
+```bash
+cp config.yaml.example config.yaml
+```
+
+Open `config.yaml` and edit it:
+```yaml
+download_dir: ~/Music/spotify-auto-dl
+
+artists:
+  - name: Daniel Caesar
+    url: https://open.spotify.com/artist/20wkVLutqVOYrc0kxFs7rA
+
+schedule:
+  interval_hours: 24
+  run_on_start: true
+
+output:
+  format: "{artist}/{album}/{title}.{output-ext}"
+  audio_format: mp3
+  bitrate: 320k
+```
+
+To get an artist URL: open Spotify → artist page → three dots → **Share** → **Copy Artist Link**.
+
+---
+
+## Usage
+
+### Run a one-time sync
+```bash
+spotify-auto-dl sync
+```
+
+### Run continuously on a schedule (daemon mode)
+```bash
+spotify-auto-dl sync --daemon
+```
+Syncs immediately on start (if `run_on_start: true`), then again every `interval_hours` hours. See [Scheduling](#scheduling) for when to use this vs cron.
+
+### Add an artist
+```bash
+spotify-auto-dl add-artist "https://open.spotify.com/artist/ARTIST_ID"
+```
+Looks up the artist name from Spotify automatically and adds them to `config.yaml`.
+
+### Change the download directory
+```bash
+spotify-auto-dl set-destination /Volumes/MyDrive/Music
+```
+Updates `download_dir` in `config.yaml`. Creates the directory if it doesn't exist.
+
+### Use a custom config file path
+```bash
+spotify-auto-dl sync --config /path/to/my-config.yaml
+```
+
+---
+
+## File Organization
+
+Downloaded files are organized using the `output.format` template in `config.yaml`:
+
+```
+{download_dir}/
+└── {artist}/
+    └── {album}/
+        └── {title}.mp3
+```
+
+For example:
+```
+~/Music/spotify-auto-dl/
+└── Daniel Caesar/
+    └── Freudian/
+        ├── Get You (feat. Kali Uchis).mp3
+        └── Best Part (feat. H.E.R.).mp3
+```
+
+---
+
+## State File
+
+Downloaded tracks are recorded in `~/.spotify-auto-dl/state.json`. This file is how the tool knows what you already have — it prevents re-downloading songs across runs. Do not delete it unless you want to re-download everything.
+
+---
+
+## Scheduling
+
+There are two ways to run this tool automatically: **daemon mode** and **cron**. They accomplish the same goal differently.
+
+### Daemon vs Cron
+
+| | Daemon (`--daemon`) | Cron |
+|---|---|---|
+| How it works | Python process that sleeps and loops forever | OS wakes the command at a set time, it runs once and exits |
+| Requires terminal open | Yes | No |
+| Survives reboot | No | Yes |
+| Easy to stop | `Ctrl+C` | `crontab -e` to remove |
+| Best for | Servers, Docker containers | Personal computers |
+
+**For a personal Mac, cron is recommended.** The daemon requires a terminal window to stay open and won't restart if you reboot. Cron is managed by the OS and runs reliably in the background.
+
+---
+
+### Setting Up Cron (Recommended for Mac)
+
+**Step 1 — open your crontab**
+```bash
+crontab -e
+```
+This opens a text editor. If it opens vim, press `i` to start typing.
+
+**Step 2 — add this line** (runs every day at 6am)
+```
+0 6 * * * cd /Users/theoaronow/Documents/Spotify-Auto-Downloader && SPOTIFY_CLIENT_ID=your_id SPOTIFY_CLIENT_SECRET=your_secret /Users/theoaronow/Documents/Spotify-Auto-Downloader/.venv/bin/spotify-auto-dl sync --config /Users/theoaronow/Documents/Spotify-Auto-Downloader/config.yaml >> /Users/theoaronow/.spotify-auto-dl/cron.log 2>&1
+```
+
+Replace `your_id` and `your_secret` with the values from your `.env` file. The credentials must be inline because cron does not load `.env` files automatically.
+
+**Step 3 — save and exit**
+
+If using vim: press `Esc`, type `:wq`, press `Enter`.
+
+**Step 4 — verify it saved**
+```bash
+crontab -l
+```
+
+**Changing the schedule** — edit the `0 6 * * *` part:
+```
+0 8 * * *     every day at 8am
+0 6 * * 1     every Monday at 6am
+0 6,18 * * *  every day at 6am and 6pm
+```
+
+**Checking the log after it runs:**
+```bash
+cat ~/.spotify-auto-dl/cron.log
+```
+
+---
+
+## Troubleshooting
+
+**`KeyError: SPOTIFY_CLIENT_ID`**
+Your `.env` file is missing or the variable names are misspelled. Make sure `.env` exists in the directory where you run the command.
+
+**`FileNotFoundError: config.yaml`**
+Run the command from the project directory, or use `--config /full/path/to/config.yaml`.
+
+**A track shows as new every run**
+The same song can have different Spotify IDs across album versions, deluxe editions, and singles. The tool checks by both ID and title to handle this, but edge cases may occur.
+
+**Downloads are slow**
+Normal — each track requires finding a matching audio source on YouTube. The first run is the slowest since it downloads everything. Future runs only download new releases.
+
+---
+
+## License
+
+MIT

spotify_auto_dl-0.1.0/README.md

@@ -0,0 +1,234 @@
+# Spotify Auto Downloader
+
+Automatically download new releases from your favorite Spotify artists to a local drive. Tracks artists you care about, downloads only songs you don't already have, and can run on a schedule to stay up to date automatically.
+
+## How It Works
+
+1. You provide a list of Spotify artist URLs in a config file
+2. On each run, the tool fetches each artist's full discography from Spotify
+3. It compares against a local state file to find tracks you don't have yet
+4. New tracks are downloaded as MP3s via [spotdl](https://github.com/spotDL/spotify-downloader)
+5. The state file is updated so those tracks are skipped on future runs
+
+---
+
+## Requirements
+
+- Python 3.10 or higher
+- A [Spotify Developer account](https://developer.spotify.com/dashboard) (free)
+- `ffmpeg` installed on your machine
+
+Install ffmpeg on Mac:
+```bash
+brew install ffmpeg
+```
+
+---
+
+## Installation
+
+**1. Clone the repo**
+```bash
+git clone https://github.com/your-username/spotify-auto-downloader.git
+cd spotify-auto-downloader
+```
+
+**2. Create and activate a virtual environment**
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+**3. Install the package**
+```bash
+pip install .
+```
+
+---
+
+## Spotify API Credentials
+
+This tool uses the Spotify API to look up artist discographies. You need a free client ID and secret.
+
+1. Go to [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard)
+2. Click **Create App**
+3. Fill in any name and description, set the redirect URI to `http://localhost`
+4. Open the app and copy the **Client ID** and **Client Secret**
+
+**4. Set up your credentials**
+```bash
+cp .env.example .env
+```
+
+Open `.env` and fill in your credentials:
+```
+SPOTIFY_CLIENT_ID=your_client_id_here
+SPOTIFY_CLIENT_SECRET=your_client_secret_here
+```
+
+---
+
+## Configuration
+
+**5. Create your config file**
+```bash
+cp config.yaml.example config.yaml
+```
+
+Open `config.yaml` and edit it:
+```yaml
+download_dir: ~/Music/spotify-auto-dl
+
+artists:
+  - name: Daniel Caesar
+    url: https://open.spotify.com/artist/20wkVLutqVOYrc0kxFs7rA
+
+schedule:
+  interval_hours: 24
+  run_on_start: true
+
+output:
+  format: "{artist}/{album}/{title}.{output-ext}"
+  audio_format: mp3
+  bitrate: 320k
+```
+
+To get an artist URL: open Spotify → artist page → three dots → **Share** → **Copy Artist Link**.
+
+---
+
+## Usage
+
+### Run a one-time sync
+```bash
+spotify-auto-dl sync
+```
+
+### Run continuously on a schedule (daemon mode)
+```bash
+spotify-auto-dl sync --daemon
+```
+Syncs immediately on start (if `run_on_start: true`), then again every `interval_hours` hours. See [Scheduling](#scheduling) for when to use this vs cron.
+
+### Add an artist
+```bash
+spotify-auto-dl add-artist "https://open.spotify.com/artist/ARTIST_ID"
+```
+Looks up the artist name from Spotify automatically and adds them to `config.yaml`.
+
+### Change the download directory
+```bash
+spotify-auto-dl set-destination /Volumes/MyDrive/Music
+```
+Updates `download_dir` in `config.yaml`. Creates the directory if it doesn't exist.
+
+### Use a custom config file path
+```bash
+spotify-auto-dl sync --config /path/to/my-config.yaml
+```
+
+---
+
+## File Organization
+
+Downloaded files are organized using the `output.format` template in `config.yaml`:
+
+```
+{download_dir}/
+└── {artist}/
+    └── {album}/
+        └── {title}.mp3
+```
+
+For example:
+```
+~/Music/spotify-auto-dl/
+└── Daniel Caesar/
+    └── Freudian/
+        ├── Get You (feat. Kali Uchis).mp3
+        └── Best Part (feat. H.E.R.).mp3
+```
+
+---
+
+## State File
+
+Downloaded tracks are recorded in `~/.spotify-auto-dl/state.json`. This file is how the tool knows what you already have — it prevents re-downloading songs across runs. Do not delete it unless you want to re-download everything.
+
+---
+
+## Scheduling
+
+There are two ways to run this tool automatically: **daemon mode** and **cron**. They accomplish the same goal differently.
+
+### Daemon vs Cron
+
+| | Daemon (`--daemon`) | Cron |
+|---|---|---|
+| How it works | Python process that sleeps and loops forever | OS wakes the command at a set time, it runs once and exits |
+| Requires terminal open | Yes | No |
+| Survives reboot | No | Yes |
+| Easy to stop | `Ctrl+C` | `crontab -e` to remove |
+| Best for | Servers, Docker containers | Personal computers |
+
+**For a personal Mac, cron is recommended.** The daemon requires a terminal window to stay open and won't restart if you reboot. Cron is managed by the OS and runs reliably in the background.
+
+---
+
+### Setting Up Cron (Recommended for Mac)
+
+**Step 1 — open your crontab**
+```bash
+crontab -e
+```
+This opens a text editor. If it opens vim, press `i` to start typing.
+
+**Step 2 — add this line** (runs every day at 6am)
+```
+0 6 * * * cd /Users/theoaronow/Documents/Spotify-Auto-Downloader && SPOTIFY_CLIENT_ID=your_id SPOTIFY_CLIENT_SECRET=your_secret /Users/theoaronow/Documents/Spotify-Auto-Downloader/.venv/bin/spotify-auto-dl sync --config /Users/theoaronow/Documents/Spotify-Auto-Downloader/config.yaml >> /Users/theoaronow/.spotify-auto-dl/cron.log 2>&1
+```
+
+Replace `your_id` and `your_secret` with the values from your `.env` file. The credentials must be inline because cron does not load `.env` files automatically.
+
+**Step 3 — save and exit**
+
+If using vim: press `Esc`, type `:wq`, press `Enter`.
+
+**Step 4 — verify it saved**
+```bash
+crontab -l
+```
+
+**Changing the schedule** — edit the `0 6 * * *` part:
+```
+0 8 * * *     every day at 8am
+0 6 * * 1     every Monday at 6am
+0 6,18 * * *  every day at 6am and 6pm
+```
+
+**Checking the log after it runs:**
+```bash
+cat ~/.spotify-auto-dl/cron.log
+```
+
+---
+
+## Troubleshooting
+
+**`KeyError: SPOTIFY_CLIENT_ID`**
+Your `.env` file is missing or the variable names are misspelled. Make sure `.env` exists in the directory where you run the command.
+
+**`FileNotFoundError: config.yaml`**
+Run the command from the project directory, or use `--config /full/path/to/config.yaml`.
+
+**A track shows as new every run**
+The same song can have different Spotify IDs across album versions, deluxe editions, and singles. The tool checks by both ID and title to handle this, but edge cases may occur.
+
+**Downloads are slow**
+Normal — each track requires finding a matching audio source on YouTube. The first run is the slowest since it downloads everything. Future runs only download new releases.
+
+---
+
+## License
+
+MIT

spotify_auto_dl-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spotify-auto-dl"
+version = "0.1.0"
+description = "Automatically download new releases from your favorite artists using spotdl"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "spotdl>=4.0.0",
+    "click>=8.0.0",
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0.0",
+    "python-dotenv>=1.0.0",
+    "rich>=13.0.0",
+    "spotipy>=2.23.0",
+]
+
+[project.scripts]
+spotify-auto-dl = "spotify_auto_dl.main:cli"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["spotify_auto_dl*"]

spotify_auto_dl-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spotify_auto_dl-0.1.0/spotify_auto_dl/config.py

@@ -0,0 +1,37 @@
+import yaml
+from pathlib import Path
+from pydantic import BaseModel, field_validator, HttpUrl
+
+
+class Artist(BaseModel):
+    name: str
+    url: HttpUrl
+
+
+class Schedule(BaseModel):
+    interval_hours: int = 24
+    run_on_start: bool = True
+
+
+class Output(BaseModel):
+    format: str = "{artist}/{album}/{title}.{output-ext}"
+    audio_format: str = "mp3"
+    bitrate: str = "320k"
+
+
+class Config(BaseModel):
+    download_dir: Path
+    artists: list[Artist]
+    schedule: Schedule = Schedule()
+    output: Output = Output()
+
+    @field_validator("download_dir", mode="before")
+    @classmethod
+    def expand_path(cls, v: str) -> Path:
+        return Path(v).expanduser().resolve()
+
+
+def load_config(path: Path = Path("config.yaml")) -> Config:
+    with open(path) as f:
+        raw = yaml.safe_load(f)
+    return Config(**raw)

spotify_auto_dl-0.1.0/spotify_auto_dl/downloader.py

@@ -0,0 +1,117 @@
+import os
+import logging
+from urllib.parse import urlparse
+
+for _logger in ("spotdl", "yt_dlp", "ytmusicapi", "urllib3", "asyncio"):
+    logging.getLogger(_logger).setLevel(logging.CRITICAL)
+
+import spotipy
+from spotipy.oauth2 import SpotifyClientCredentials
+from spotdl import Spotdl
+from rich.console import Console
+
+from .config import Config
+from .state import State
+
+console = Console()
+
+
+def _init_spotify() -> spotipy.Spotify:
+    return spotipy.Spotify(auth_manager=SpotifyClientCredentials(
+        client_id=os.environ["SPOTIFY_CLIENT_ID"],
+        client_secret=os.environ["SPOTIFY_CLIENT_SECRET"],
+    ))
+
+
+def _init_spotdl(config: Config) -> Spotdl:
+    return Spotdl(
+        client_id=os.environ["SPOTIFY_CLIENT_ID"],
+        client_secret=os.environ["SPOTIFY_CLIENT_SECRET"],
+        downloader_settings={
+            "output": str(config.download_dir / config.output.format),
+            "format": config.output.audio_format,
+            "bitrate": config.output.bitrate,
+        },
+    )
+
+
+def _get_discography(sp: spotipy.Spotify, artist_id: str) -> list[dict]:
+    albums = []
+    results = sp.artist_albums(artist_id, album_type="album,single,compilation", limit=50)
+    albums.extend(results["items"])
+    while results["next"]:
+        results = sp.next(results)
+        albums.extend(results["items"])
+
+    all_tracks = []
+    seen_names: set[str] = set()
+    for album in albums:
+        track_results = sp.album_tracks(album["id"], limit=50)
+        tracks = track_results["items"]
+        while track_results["next"]:
+            track_results = sp.next(track_results)
+            tracks.extend(track_results["items"])
+
+        for track in tracks:
+            artist_ids_on_track = [a["id"] for a in track["artists"]]
+            if artist_id in artist_ids_on_track:
+                name_lower = track["name"].lower()
+                if name_lower not in seen_names:
+                    seen_names.add(name_lower)
+                    all_tracks.append({
+                        "id": track["id"],
+                        "name": track["name"],
+                        "album": album["name"],
+                    })
+    return all_tracks
+
+
+def sync(config: Config, state: State) -> None:
+    sp = _init_spotify()
+    spotdl_client = _init_spotdl(config)
+
+    for artist in config.artists:
+        console.rule(f"[bold]{artist.name}")
+        artist_id = urlparse(str(artist.url)).path.split("/")[-1]
+
+        with console.status("[bold]Fetching discography...[/]", spinner="dots"):
+            all_tracks = _get_discography(sp, artist_id)
+
+        console.print(f"  Found [bold]{len(all_tracks)}[/] total tracks:\n")
+
+        new_tracks = []
+        for track in all_tracks:
+            already = state.is_downloaded(track["id"], title=track["name"])
+            status = "[dim]already downloaded[/dim]" if already else "[green]new[/green]"
+            console.print(f"    {track['name']} — [dim]{track['album']}[/dim] [{status}]")
+            if not already:
+                new_tracks.append(track)
+
+        if not new_tracks:
+            console.print("\n  [green]Already up to date.[/]")
+            continue
+
+        console.print(f"\n  [bold]{len(new_tracks)} new track(s) to download.[/]\n")
+
+        total = len(new_tracks)
+        for i, track in enumerate(new_tracks, 1):
+            console.print(f"  [{i}/{total}] Downloading: [cyan]{track['name']}[/]")
+            track_url = f"https://open.spotify.com/track/{track['id']}"
+            songs = spotdl_client.search([track_url])
+            if songs:
+                _, path = spotdl_client.download(songs[0])
+                if path:
+                    state.mark_downloaded(
+                        track_id=track["id"],
+                        title=track["name"],
+                        artist=artist.name,
+                        album=track["album"],
+                    )
+                    console.print(f"  [{i}/{total}] [green]Done:[/] {track['name']}")
+                else:
+                    console.print(f"  [{i}/{total}] [red]Failed:[/] {track['name']}")
+            else:
+                console.print(f"  [{i}/{total}] [red]Not found on YouTube:[/] {track['name']}")
+
+    state.save()
+    console.print("\n[bold green]Sync complete.[/]")

spotify_auto_dl-0.1.0/spotify_auto_dl/main.py

@@ -0,0 +1,117 @@
+import time
+import os
+import click
+import yaml
+import spotipy
+from dotenv import load_dotenv
+from pathlib import Path
+from spotipy.oauth2 import SpotifyClientCredentials
+from urllib.parse import urlparse
+
+load_dotenv()
+
+from .config import load_config
+from .downloader import sync as run_sync
+from .state import State
+
+
+@click.group()
+def cli():
+    """Automatically download new releases from your favorite Spotify artists."""
+
+
+@cli.command()
+@click.option(
+    "--config",
+    "config_path",
+    default="config.yaml",
+    type=click.Path(exists=True, path_type=Path),
+    help="Path to your config.yaml file.",
+)
+@click.option(
+    "--daemon",
+    is_flag=True,
+    default=False,
+    help="Run on a loop using the interval defined in config.",
+)
+def sync(config_path: Path, daemon: bool) -> None:
+    """Sync new tracks for all artists in your config."""
+    config = load_config(config_path)
+    state = State()
+
+    if not daemon:
+        run_sync(config, state)
+        return
+
+    if config.schedule.run_on_start:
+        run_sync(config, state)
+
+    interval_seconds = config.schedule.interval_hours * 3600
+    click.echo(f"Daemon started. Syncing every {config.schedule.interval_hours}h.")
+    while True:
+        time.sleep(interval_seconds)
+        run_sync(config, state)
+
+
+@cli.command("add-artist")
+@click.argument("url")
+@click.option(
+    "--config",
+    "config_path",
+    default="config.yaml",
+    type=click.Path(path_type=Path),
+    help="Path to your config.yaml file.",
+)
+def add_artist(url: str, config_path: Path) -> None:
+    """Add an artist to your config by Spotify URL."""
+    artist_id = urlparse(url).path.split("/")[-1]
+
+    sp = spotipy.Spotify(auth_manager=SpotifyClientCredentials(
+        client_id=os.environ["SPOTIFY_CLIENT_ID"],
+        client_secret=os.environ["SPOTIFY_CLIENT_SECRET"],
+    ))
+    artist_data = sp.artist(artist_id)
+    name = artist_data["name"]
+
+    with open(config_path) as f:
+        config = yaml.safe_load(f)
+
+    for existing in config.get("artists", []):
+        if existing["url"] == url:
+            click.echo(f"{name} is already in your config.")
+            return
+
+    config.setdefault("artists", []).append({"name": name, "url": url})
+
+    with open(config_path, "w") as f:
+        yaml.dump(config, f, default_flow_style=False, allow_unicode=True)
+
+    click.echo(f"Added {name} to {config_path}.")
+
+
+@cli.command("set-destination")
+@click.argument("path")
+@click.option(
+    "--config",
+    "config_path",
+    default="config.yaml",
+    type=click.Path(path_type=Path),
+    help="Path to your config.yaml file.",
+)
+def set_destination(path: str, config_path: Path) -> None:
+    """Set the download directory in your config."""
+    destination = Path(path).expanduser().resolve()
+
+    if not destination.exists():
+        click.confirm(f"{destination} does not exist. Create it?", abort=True)
+        destination.mkdir(parents=True)
+
+    with open(config_path) as f:
+        config = yaml.safe_load(f)
+
+    config["download_dir"] = str(destination)
+
+    with open(config_path, "w") as f:
+        yaml.dump(config, f, default_flow_style=False, allow_unicode=True)
+
+    click.echo(f"Download directory set to {destination}.")

spotify_auto_dl-0.1.0/spotify_auto_dl/state.py

@@ -0,0 +1,39 @@
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+STATE_FILE = Path("~/.spotify-auto-dl/state.json").expanduser()
+
+
+class State:
+    def __init__(self, path: Path = STATE_FILE):
+        self._path = path
+        self._data: dict[str, dict] = self._load()
+
+    def _load(self) -> dict[str, dict]:
+        if not self._path.exists():
+            return {}
+        with open(self._path) as f:
+            return json.load(f)
+
+    def is_downloaded(self, track_id: str, title: str | None = None) -> bool:
+        if track_id in self._data:
+            return True
+        if title is not None:
+            normalized = title.lower().strip()
+            return any(v["title"].lower().strip() == normalized for v in self._data.values())
+        return False
+
+    def mark_downloaded(self, track_id: str, title: str, artist: str, album: str) -> None:
+        self._data[track_id] = {
+            "title": title,
+            "artist": artist,
+            "album": album,
+            "downloaded_at": datetime.now(timezone.utc).isoformat(),
+        }
+
+    def save(self) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        with open(self._path, "w") as f:
+            json.dump(self._data, f, indent=2)

spotify_auto_dl-0.1.0/spotify_auto_dl.egg-info/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: spotify-auto-dl
+Version: 0.1.0
+Summary: Automatically download new releases from your favorite artists using spotdl
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: spotdl>=4.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: spotipy>=2.23.0
+
+# Spotify Auto Downloader
+
+Automatically download new releases from your favorite Spotify artists to a local drive. Tracks artists you care about, downloads only songs you don't already have, and can run on a schedule to stay up to date automatically.
+
+## How It Works
+
+1. You provide a list of Spotify artist URLs in a config file
+2. On each run, the tool fetches each artist's full discography from Spotify
+3. It compares against a local state file to find tracks you don't have yet
+4. New tracks are downloaded as MP3s via [spotdl](https://github.com/spotDL/spotify-downloader)
+5. The state file is updated so those tracks are skipped on future runs
+
+---
+
+## Requirements
+
+- Python 3.10 or higher
+- A [Spotify Developer account](https://developer.spotify.com/dashboard) (free)
+- `ffmpeg` installed on your machine
+
+Install ffmpeg on Mac:
+```bash
+brew install ffmpeg
+```
+
+---
+
+## Installation
+
+**1. Clone the repo**
+```bash
+git clone https://github.com/your-username/spotify-auto-downloader.git
+cd spotify-auto-downloader
+```
+
+**2. Create and activate a virtual environment**
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+**3. Install the package**
+```bash
+pip install .
+```
+
+---
+
+## Spotify API Credentials
+
+This tool uses the Spotify API to look up artist discographies. You need a free client ID and secret.
+
+1. Go to [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard)
+2. Click **Create App**
+3. Fill in any name and description, set the redirect URI to `http://localhost`
+4. Open the app and copy the **Client ID** and **Client Secret**
+
+**4. Set up your credentials**
+```bash
+cp .env.example .env
+```
+
+Open `.env` and fill in your credentials:
+```
+SPOTIFY_CLIENT_ID=your_client_id_here
+SPOTIFY_CLIENT_SECRET=your_client_secret_here
+```
+
+---
+
+## Configuration
+
+**5. Create your config file**
+```bash
+cp config.yaml.example config.yaml
+```
+
+Open `config.yaml` and edit it:
+```yaml
+download_dir: ~/Music/spotify-auto-dl
+
+artists:
+  - name: Daniel Caesar
+    url: https://open.spotify.com/artist/20wkVLutqVOYrc0kxFs7rA
+
+schedule:
+  interval_hours: 24
+  run_on_start: true
+
+output:
+  format: "{artist}/{album}/{title}.{output-ext}"
+  audio_format: mp3
+  bitrate: 320k
+```
+
+To get an artist URL: open Spotify → artist page → three dots → **Share** → **Copy Artist Link**.
+
+---
+
+## Usage
+
+### Run a one-time sync
+```bash
+spotify-auto-dl sync
+```
+
+### Run continuously on a schedule (daemon mode)
+```bash
+spotify-auto-dl sync --daemon
+```
+Syncs immediately on start (if `run_on_start: true`), then again every `interval_hours` hours. See [Scheduling](#scheduling) for when to use this vs cron.
+
+### Add an artist
+```bash
+spotify-auto-dl add-artist "https://open.spotify.com/artist/ARTIST_ID"
+```
+Looks up the artist name from Spotify automatically and adds them to `config.yaml`.
+
+### Change the download directory
+```bash
+spotify-auto-dl set-destination /Volumes/MyDrive/Music
+```
+Updates `download_dir` in `config.yaml`. Creates the directory if it doesn't exist.
+
+### Use a custom config file path
+```bash
+spotify-auto-dl sync --config /path/to/my-config.yaml
+```
+
+---
+
+## File Organization
+
+Downloaded files are organized using the `output.format` template in `config.yaml`:
+
+```
+{download_dir}/
+└── {artist}/
+    └── {album}/
+        └── {title}.mp3
+```
+
+For example:
+```
+~/Music/spotify-auto-dl/
+└── Daniel Caesar/
+    └── Freudian/
+        ├── Get You (feat. Kali Uchis).mp3
+        └── Best Part (feat. H.E.R.).mp3
+```
+
+---
+
+## State File
+
+Downloaded tracks are recorded in `~/.spotify-auto-dl/state.json`. This file is how the tool knows what you already have — it prevents re-downloading songs across runs. Do not delete it unless you want to re-download everything.
+
+---
+
+## Scheduling
+
+There are two ways to run this tool automatically: **daemon mode** and **cron**. They accomplish the same goal differently.
+
+### Daemon vs Cron
+
+| | Daemon (`--daemon`) | Cron |
+|---|---|---|
+| How it works | Python process that sleeps and loops forever | OS wakes the command at a set time, it runs once and exits |
+| Requires terminal open | Yes | No |
+| Survives reboot | No | Yes |
+| Easy to stop | `Ctrl+C` | `crontab -e` to remove |
+| Best for | Servers, Docker containers | Personal computers |
+
+**For a personal Mac, cron is recommended.** The daemon requires a terminal window to stay open and won't restart if you reboot. Cron is managed by the OS and runs reliably in the background.
+
+---
+
+### Setting Up Cron (Recommended for Mac)
+
+**Step 1 — open your crontab**
+```bash
+crontab -e
+```
+This opens a text editor. If it opens vim, press `i` to start typing.
+
+**Step 2 — add this line** (runs every day at 6am)
+```
+0 6 * * * cd /Users/theoaronow/Documents/Spotify-Auto-Downloader && SPOTIFY_CLIENT_ID=your_id SPOTIFY_CLIENT_SECRET=your_secret /Users/theoaronow/Documents/Spotify-Auto-Downloader/.venv/bin/spotify-auto-dl sync --config /Users/theoaronow/Documents/Spotify-Auto-Downloader/config.yaml >> /Users/theoaronow/.spotify-auto-dl/cron.log 2>&1
+```
+
+Replace `your_id` and `your_secret` with the values from your `.env` file. The credentials must be inline because cron does not load `.env` files automatically.
+
+**Step 3 — save and exit**
+
+If using vim: press `Esc`, type `:wq`, press `Enter`.
+
+**Step 4 — verify it saved**
+```bash
+crontab -l
+```
+
+**Changing the schedule** — edit the `0 6 * * *` part:
+```
+0 8 * * *     every day at 8am
+0 6 * * 1     every Monday at 6am
+0 6,18 * * *  every day at 6am and 6pm
+```
+
+**Checking the log after it runs:**
+```bash
+cat ~/.spotify-auto-dl/cron.log
+```
+
+---
+
+## Troubleshooting
+
+**`KeyError: SPOTIFY_CLIENT_ID`**
+Your `.env` file is missing or the variable names are misspelled. Make sure `.env` exists in the directory where you run the command.
+
+**`FileNotFoundError: config.yaml`**
+Run the command from the project directory, or use `--config /full/path/to/config.yaml`.
+
+**A track shows as new every run**
+The same song can have different Spotify IDs across album versions, deluxe editions, and singles. The tool checks by both ID and title to handle this, but edge cases may occur.
+
+**Downloads are slow**
+Normal — each track requires finding a matching audio source on YouTube. The first run is the slowest since it downloads everything. Future runs only download new releases.
+
+---
+
+## License
+
+MIT

spotify_auto_dl-0.1.0/spotify_auto_dl.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+spotify_auto_dl/__init__.py
+spotify_auto_dl/config.py
+spotify_auto_dl/downloader.py
+spotify_auto_dl/main.py
+spotify_auto_dl/state.py
+spotify_auto_dl.egg-info/PKG-INFO
+spotify_auto_dl.egg-info/SOURCES.txt
+spotify_auto_dl.egg-info/dependency_links.txt
+spotify_auto_dl.egg-info/entry_points.txt
+spotify_auto_dl.egg-info/requires.txt
+spotify_auto_dl.egg-info/top_level.txt

spotify_auto_dl-0.1.0/spotify_auto_dl.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

spotify_auto_dl-0.1.0/spotify_auto_dl.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spotify-auto-dl = spotify_auto_dl.main:cli

spotify_auto_dl-0.1.0/spotify_auto_dl.egg-info/requires.txt

@@ -0,0 +1,7 @@
+spotdl>=4.0.0
+click>=8.0.0
+pydantic>=2.0.0
+pyyaml>=6.0.0
+python-dotenv>=1.0.0
+rich>=13.0.0
+spotipy>=2.23.0

spotify_auto_dl-0.1.0/spotify_auto_dl.egg-info/top_level.txt

@@ -0,0 +1 @@
+spotify_auto_dl