spots-cli 0.1.0__py3-none-any.whl

spots_cli/setup_env.py

@@ -0,0 +1,118 @@
+from os.path import exists
+from typing import Literal
+
+from spots_cli.utils import get_config_path, create_config_dir
+
+FILENAME = get_config_path() / ".env"
+
+
+def save_env(variables: dict[str, str]):
+    file_data = ""
+
+    for k, v in variables.items():
+        file_data += f"{k}={v}\n"
+
+    with open(FILENAME, "w") as f:
+        f.write(file_data)
+
+
+def required_input(prompt: str):
+    value = ""
+
+    while not value:
+        value = input(f"[REQUIRED] {prompt}: ").strip()
+
+    return value
+
+
+def optional_input(prompt: str, default: str | None = None):
+    value = input(
+        f"[OPTIONAL] {prompt}" + (f" [{default}]" if default else "") + ": "
+    ).strip()
+    return value or default
+
+
+def main():
+    if exists(FILENAME):
+        setup_again = input(
+            "Environment variables already exist.\n"
+            "Would you like to reconfigure them? (press Enter to cancel): "
+        ).strip()
+
+        if not setup_again:
+            print("Setup cancelled.\n")
+            return
+
+    print("\n=== Environment Configuration ===\n")
+
+    create_config_dir()
+
+    static_cover_name = "https://i.postimg.cc/VvZTvvMV/single-cover.jpg"
+    static_playlist_cover_name = "https://i.postimg.cc/m2XzZsnq/youtube-playlist.jpg"
+    flask_port = 5000
+    main_provider: Literal["deezer", "spotify"] = "deezer"
+    spotify_features_available = "False"
+    youtube_account_access = "False"
+    avatar_icon = "https://i.postimg.cc/HnpL9ZrZ/avatar.jpg"
+    environment_mode = "PRODUCTION"
+
+    variables_map = {
+        "flask_port": flask_port,
+        "static_cover_name": static_cover_name,
+        "static_playlist_cover_name": static_playlist_cover_name,
+        "spotify_features_available": spotify_features_available,
+        "youtube_account_access": youtube_account_access,
+        "main_provider": main_provider,
+        "avatar_icon": avatar_icon,
+        "environment_mode": environment_mode,
+    }
+
+    print("---- Spotify Configuration ----")
+    has_spotify_membership = (
+        input(
+            "Do you have a paid Spotify API membership? (required for Spotify features) [y/N]: "
+        )
+        .strip()
+        .lower()
+    )
+
+    if has_spotify_membership == "y":
+        spotify_username = required_input("Spotify username")
+        spotify_client_id = required_input("Spotify client ID")
+        spotify_client_secret = required_input("Spotify client secret")
+
+        default_redirect = "https://open.spotify.com/?"
+        spotify_redirect_uri = optional_input("Spotify redirect URI", default_redirect)
+
+        variables_map["username"] = spotify_username
+        variables_map["SPOTIPY_CLIENT_ID"] = spotify_client_id
+        variables_map["SPOTIPY_CLIENT_SECRET"] = spotify_client_secret
+        variables_map["SPOTIPY_REDIRECT_URI"] = spotify_redirect_uri
+
+        variables_map["spotify_features_available"] = "True"
+        variables_map["main_provider"] = "spotify"
+
+    print("\n---- Genius (Lyrics) Configuration ----")
+    has_genius_key = (
+        input("Do you have a Genius API key? (optional, for lyrics) [y/N]: ")
+        .strip()
+        .lower()
+    )
+
+    if has_genius_key == "y":
+        genius_key = required_input("Genius API key")
+        variables_map["lyricsgenius_key"] = genius_key
+
+    print("\n---- YouTube Configuration ----")
+    use_youtube_features = (
+        input("Enable YouTube account features (likes, library access)? [y/N]: ")
+        .strip()
+        .lower()
+    )
+
+    if use_youtube_features == "y":
+        variables_map["youtube_account_access"] = "True"
+
+    save_env(variables_map)
+
+    print("\n✅ Environment variables have been successfully configured.\n")

spots_cli/utils/__init__.py

@@ -0,0 +1,4 @@
+from spots_cli.utils.config_dir import get_config_path, create_config_dir
+from spots_cli.utils.detect_browser import detect_browser
+from spots_cli.utils.fetch import fetch_data, FetchResponseFailure, FetchResponseSuccess
+from spots_cli.utils.search_fallbacks import search_fallbacks

spots_cli/utils/config_dir.py

@@ -0,0 +1,17 @@
+import os
+from pathlib import Path
+import sys
+
+
+def get_config_path() -> Path:
+    if sys.platform == "win32":
+        return Path(os.getenv("APPDATA", Path.home() / "AppData/Roaming")) / "spots_cli"
+    elif sys.platform == "darwin":
+        return Path.home() / "Library/Application Support" / "spots_cli"
+    else:
+        return Path(os.getenv("XDG_CONFIG_HOME", Path.home() / ".config")) / "spots_cli"
+
+
+def create_config_dir():
+    config_dir = get_config_path()
+    config_dir.mkdir(parents=True, exist_ok=True)

spots_cli/utils/detect_browser.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import shutil
+from typing import Optional, Tuple
+
+
+def detect_browser() -> Optional[Tuple[str, ...]]:
+    """
+    Detect an installed browser and return a yt-dlp compatible
+    cookiesfrombrowser tuple.
+
+    Returns:
+        Tuple usable in yt-dlp options, e.g. ("firefox",)
+        or ("chrome",), or None if nothing found.
+    """
+
+    # Order matters: prefer Firefox (more reliable on Linux)
+    browsers = [
+        ("firefox", ["firefox"]),
+        ("chrome", ["google-chrome", "chrome", "chromium", "chromium-browser"]),
+        ("edge", ["microsoft-edge"]),
+        ("brave", ["brave-browser"]),
+    ]
+
+    for browser_name, executables in browsers:
+        for exe in executables:
+            if shutil.which(exe):
+                return (browser_name,)
+
+    return None

spots_cli/utils/fetch.py

@@ -0,0 +1,73 @@
+from dataclasses import dataclass, field
+from requests import get
+from requests.exceptions import Timeout, ConnectionError, RequestException, HTTPError
+from typing import Any, Literal
+
+
+@dataclass
+class FetchResponseFailure:
+    error: str
+    status_code: int = field(default=500)
+    success: Literal[False] = False
+    data: None = None
+    fallback: Any = None
+
+
+@dataclass
+class FetchResponseSuccess:
+    data: dict[str, Any] | str
+    status_code: int = field(default=200)
+    success: Literal[True] = True
+    error: None = None
+    fallback: Any = None
+
+
+def fetch_data(
+    url: str,
+    *,
+    params: dict[str, Any] | None = None,
+    headers: dict[str, Any] | None = None,
+    timeout: int = 5,
+) -> FetchResponseFailure | FetchResponseSuccess:
+    try:
+        response = get(url, params=params, headers=headers, timeout=timeout)
+
+        # Check for HTTP errors (4xx, 5xx)
+        response.raise_for_status()
+
+        # Try to parse JSON (optional, adjust if expecting text)
+        try:
+            res_data = response.json()
+
+            if res_data.get("error"):
+                error_data = res_data["error"]
+                return FetchResponseFailure(
+                    status_code=error_data.get("code"), error=error_data["message"]
+                )
+
+            return FetchResponseSuccess(status_code=response.status_code, data=res_data)
+        except ValueError:
+            return FetchResponseSuccess(
+                status_code=response.status_code,
+                data=response.text,  # fallback if not JSON
+            )
+
+    except Timeout:
+        return FetchResponseFailure(
+            error="Request timed out",
+            fallback=None,  # you can plug in cached data here
+        )
+
+    except ConnectionError:
+        return FetchResponseFailure(error="Connection error", fallback=None)
+
+    except HTTPError as e:
+        return FetchResponseFailure(
+            error=f"HTTP error: {e}",
+            status_code=getattr(e.response, "status_code", 500),
+            fallback=None,
+        )
+
+    except RequestException as e:
+        # Catch-all for other request issues
+        return FetchResponseFailure(error=f"Unexpected error: {e}", fallback=None)

spots_cli/utils/search_fallbacks.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from spots_cli.models import SongNotFound
+
+if TYPE_CHECKING:
+    from spots_cli.models import Metadata, SearchProvider
+
+
+def search_fallbacks(*, query: str, providers: list[SearchProvider]) -> Metadata:
+    index = 0
+    while index < len(providers):
+        provider = providers[index]
+        try:
+            return provider.search_track(query)
+        except SongNotFound:
+            index += 1
+            continue
+
+    raise SongNotFound(query)

spots_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: spots_cli
+Version: 0.1.0
+Summary: Spots is a modular music coordination library that unifies multiple providers (e.g. Deezer, Spotify, YouTube) into a single, consistent interface.
+Project-URL: Homepage, https://github.com/mdesignscode/spots_flask
+Project-URL: Issues, https://github.com/mdesignscode/spots_flask
+Author-email: Marlon Baatjes <marlonbaatjes62@gmail.com>
+License-Expression: GPL-3.0-or-later
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Requires-Dist: beautifulsoup4
+Requires-Dist: google-api-python-client
+Requires-Dist: google-auth-oauthlib
+Requires-Dist: lyricsgenius
+Requires-Dist: moviepy
+Requires-Dist: mutagen
+Requires-Dist: python-dotenv
+Requires-Dist: requests
+Requires-Dist: spotipy
+Requires-Dist: tenacity
+Requires-Dist: typer
+Requires-Dist: yt-dlp
+Description-Content-Type: text/markdown
+
+# 🎧 Spots
+
+Spots is a modular music coordination library that unifies multiple providers (e.g. Deezer, Spotify, YouTube) into a single, consistent interface.
+
+It resolves tracks across platforms, matches metadata intelligently, and enables downloading, playlist handling, and media conversion — all through a clean, configurable API.
+
+---
+
+## ✨ Features
+
+- 🔍 **Multi-provider search**
+  - Supports multiple metadata providers with fallback resolution
+
+- 🧠 **Intelligent track matching**
+  - Matches tracks across platforms using pattern-based scoring
+
+- 🎵 **Unified media resolution**
+  - Seamlessly map metadata → YouTube → downloadable media
+
+- ⚡ **Provider fallback system**
+  - Automatically falls back when a provider fails
+
+- 🗂️ **Built-in caching**
+  - Reduces redundant API calls and speeds up repeated queries
+
+- ⚙️ **Config-driven architecture**
+  - Enable/disable integrations (Spotify, YouTube, etc.)
+
+- 📦 **Download + conversion pipeline**
+  - Handles media extraction and conversion (via yt-dlp)
+
+---
+
+## 📦 Installation
+
+```bash
+pip install spots
+```
+
+---
+
+## ⚙️ Setup
+
+### Run the setup script:
+
+```bash
+spots setup
+```
+
+* follow the prompts to generate the config folder
+
+
+---
+
+## 🚀 Usage
+```bash
+# search a title
+# required search format: `Artist - Title`
+spots download "Kelsey Lynn - Modern Day Marilyn Monroe"
+
+# download a direct url
+spots download "https://www.youtube.com/watch?v=UmZPa5Qudtw"
+```
+
+Spots will:
+
+* Resolve the track via metadata providers
+* Match it to a YouTube video
+* Download and convert it
+* Store results locally
+
+---
+
+## 🎮 Available commands
+
+* download - downloads a direct url or a search query
+  ```bash
+  spots download "Kelsey Lynn - Modern Day Marilyn Monroe"
+  ```
+* migrate-likes - transfers likes from Spotify to YouTube (more providers coming soon...)
+  ```bash
+  spots migrate-likes
+  ```
+* add-to-history - adds a user's downloaded songs to the Spots history. Avoids duplicate downloads.
+  ```bash
+  spots add-to-history path-to-music
+  ```
+* remove-duplicates - removes duplicate songs in a given folder.
+  ```bash
+  spots remove-duplicates path-to-music
+  ```
+
+---
+
+## ⚠️ Important
+
+    The Spotify API content may not be downloaded using this project. This project is created for personal use only and is intended for educational purposes. Any use of this project to download or distribute copyrighted material without proper authorization is against the terms of service of Spotify and other involved platforms. The project's author and contributors are not responsible for any misuse of this software.
+
+## 🤝 Contributing
+
+Contributions are welcome.
+
+If you're adding a provider or improving matching logic, open a PR with a clear description of changes.
+
+---
+
+## 📄 License
+
+GPL-3.0-or-later
+
+---
+
+## 💬 Summary
+
+Spots is designed to make cross-platform music workflows simple:
+
+Give it a track — it figures out the rest.

spots_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,65 @@
+spots_cli/__init__.py,sha256=zABCq2Zh8M51aFrieVzvlCaLB6ra3nwW29RtU2vCrog,4381
+spots_cli/cli.py,sha256=j85SwJKe3w6E8uBJ7zVgAhd2afiKkeFJ-JLgzT9Wl0A,700
+spots_cli/setup_env.py,sha256=ITcUDM4r2OFgro3D6rNds5PBEITjh4yAynGpbJ6GR9I,3647
+spots_cli/app/__init__.py,sha256=gZwcWMaPOMY152WWvX6d4SOxKXxb1qTQEvaN9seXi1c,310
+spots_cli/app/domain_resolver.py,sha256=V7EdvDQYepC7fO8bxQ3Kcm1aizGbyxKM7_kXitv9228,5709
+spots_cli/app/downloader.py,sha256=CFtYsHJ1giGl9er1iqNK__fjumgn5pskji4hmm_pL9E,2651
+spots_cli/app/media_resolver.py,sha256=AqXQ4h6eY9sNrUifG6kHi2ML1-4XWpM9tkQvs0OFLUQ,6635
+spots_cli/app/spotify_playlist_compilation.py,sha256=Ud1lpsikoTEUw-hXsNmEqBqMJnMSSC18jAkyTT3gCzA,8514
+spots_cli/app/youtube_user_playlist.py,sha256=Z6UNxvOG8h_gjNw1Oi4mprt2sG6A-0VI8IfYfguM8ek,7320
+spots_cli/bootstrap/__init__.py,sha256=CXvBouMV7Yx9TZMWU4BpY2Ccw0PFh1X6sBeDauYLJhA,52
+spots_cli/bootstrap/container.py,sha256=pTDnH56u5x1NDDZThADaZP8hwFaC8REj0YQHr3ENyCY,6989
+spots_cli/clients/__init__.py,sha256=MM4DLhZoZXxqAVys3VDn9XGRC_1M4NY0Qq6yOQpcVB4,265
+spots_cli/clients/deezer.py,sha256=EZ8z6tiHin2W3syDjh80fx7z95-kSVmviWLg1a31ZWQ,2866
+spots_cli/clients/secrets_manager.py,sha256=zLBziF24mHvxN6rII2iMZHQbrNsYLQKs9vGPswP5Qiw,579
+spots_cli/clients/spotify.py,sha256=JFyscB27sD7gIH5dzM1XVN1dl_6YQOxtTe5r_7ZfpVA,2178
+spots_cli/clients/youtube.py,sha256=SKrUGj27DI9_rbYwj8rDzZtzS1z0jEGOgQDpj0bQGUU,1886
+spots_cli/clients/ytdl.py,sha256=BvdHr9g90z16PrtQn7NP8YG9_TMIfhEMTT9VjSKaCPY,2097
+spots_cli/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+spots_cli/core/__init__.py,sha256=JywasH_HkZlJyNsp3BZEYONcaYCrk_ud15yomxRpPUc,340
+spots_cli/core/history_manager.py,sha256=qkHUZ-tLWCVYg9yyCyOmYHMArmdCihyLMpb-cCap4mA,1071
+spots_cli/core/lyrics_finder.py,sha256=UFBbUjn8elNmbg8cy1O-CQNNzIbbNJwOG7BM_PtMLvw,1886
+spots_cli/core/pattern_matcher.py,sha256=AjTdYd2mwIe-aUtNtq__CnLDxBDC1-SrQkZ5CDB8H4U,5943
+spots_cli/core/video_converter.py,sha256=ynmdoFeVSUncab60WCiUFTEpOaOV5JsBXvSZwfLyKrw,4333
+spots_cli/core/web_scraper.py,sha256=gPyYeazP9x1jS2B_KhNmNyKtd3izU2uhXgBNy8qrnIc,2782
+spots_cli/core/youtube_extractor.py,sha256=kmLzRD14aFY0FjgmQ3Nl3ZRPWHnPorEjobT4zh7dhWk,6131
+spots_cli/engine/__init__.py,sha256=egIAqQuK5X1ZH-X4beRwiO00BkfRpJmsZ5YUyS_UTqg,150
+spots_cli/engine/file_storage.py,sha256=UDUmCJiHCHiPSPqXkYpPhemNyBSZ_Opdhfk_0oWwEJc,10567
+spots_cli/engine/persistence_model.py,sha256=LOII__m_4cjHrxQ7Ncrw7-4e-T0b9uAZf2B4jFjoIU4,69
+spots_cli/engine/retry.py,sha256=8iydX-FaapYi8zC6Fe4yb0YKyiXcn8W8LvMuAq5Ge7g,811
+spots_cli/integrations/__init__.py,sha256=f9qlGiEZlUhO59Ed2PborXklmhEYjqmHNCSBfCd6hkU,90
+spots_cli/integrations/spotify_user_playlist_modify.py,sha256=AxNeCrX5djfJx01PnPRk19uFC6jm2crT1GQ2ky6p7Cc,1520
+spots_cli/models/__init__.py,sha256=5LHfh4tRk4h9guPFK7n9LhiS-jIV6eFYwb0izphFrwA,857
+spots_cli/models/artist_metadata.py,sha256=JzuYFBUVnAf_PJXD69_WrTWmdWH0mQFKOWJVH6zMYM8,490
+spots_cli/models/errors.py,sha256=XzLO-cGOHEGSc_OxgnQPX2WEl24L-OfkhZZlBl4lTD8,1737
+spots_cli/models/helper_models.py,sha256=5y6vaQvbCH7DeXGVjaFUft2O4UYzqb4SO8_NlLZcl_k,411
+spots_cli/models/media_resource.py,sha256=DgPlIHWaKmANL3vvglUAv6nBaw5jrVpPvXTxYgvgZC8,441
+spots_cli/models/metadata.py,sha256=Gb55kH1SekX_RTN-KaQ3c3GIVDa0N7OGjNqXymLS4TQ,1300
+spots_cli/models/metadata_provider.py,sha256=PJbxy9eV2B5CWkP1dzoSKXElHYNVKAPJm7GXNr0oEmg,1372
+spots_cli/models/playlist_info.py,sha256=ntWoXYXclISoBdF5uFvc4Zg1GdzZzfrdBNt-qXrK1PU,762
+spots_cli/models/search_provider.py,sha256=0WPr58HjW5abG-T_18eJNjQ5VE117P_-xpYhzPBCikY,1597
+spots_cli/models/sentinel.py,sha256=IayHOg7yErybvgEkzV9eExpTg0szoks7O6T9HnWNbng,71
+spots_cli/models/yt_video_info.py,sha256=COkhWuZTRlyqi0k_0TlR_kNhEhRHeySdt8jNf918S-g,647
+spots_cli/scripts/__init__.py,sha256=sSiavjYeJ1rIA6Fp9B3gaoL-51Do85j97JarXdfj8rY,153
+spots_cli/scripts/add_to_history.py,sha256=PW7uOh6FAa-mx4Adzs13Clt5AQFmQYIHkLyxDG4h5_g,1419
+spots_cli/scripts/bootstrap.py,sha256=OHvtqMHoFy1Ztxe5K2jxZkikU3-ZV5-0xHM_bclZHz4,2609
+spots_cli/scripts/duplicate_songs_remover.py,sha256=0kZWmp6pZT-Z4W7hUkcxZAWqC3tHW0tIdBc6iQcNGEs,1526
+spots_cli/services/__init__.py,sha256=7M_Touz-BuV0ggEI1Zj67aJLe2WBaJJSvWYWELETRDw,607
+spots_cli/services/deezer_metadata_service.py,sha256=sOxmxDCLC_zhC_8yiTTfk28futJcwyTGeEzswehuL-Y,3491
+spots_cli/services/deezer_search_service.py,sha256=6v402oGtOuCc4Xq8wa3yTWypqui3oegB3psigdBX8-4,4167
+spots_cli/services/provider_search_container.py,sha256=hNlVowitTrCNNp0VudIe1SSTxm0C8CrAkCXVrceHONc,2261
+spots_cli/services/providers_metadata.py,sha256=vjTCGYTqNEeMm68HMh28rdz8POAQmdrV6D1Rn-PJh_k,736
+spots_cli/services/spotify_metadata_service.py,sha256=UlVyLkNtBwDGjSyzPFNy68pk62uEIldEW9hiRiPO-cw,4681
+spots_cli/services/spotify_search_service.py,sha256=Ayf3Tljuon_-BZ8ueO7FLPT2K3FD0HWLF7IFg2pzGrc,7312
+spots_cli/services/youtube_metadata_service.py,sha256=Yti_9MViJhY5e4G5mKvXpsHBsOUEgh9cJUyaetSFQNg,2164
+spots_cli/services/youtube_search_service.py,sha256=YEkDuls0m5mKEyl8XpnhfC1A10h810sVzG0wddKrCs4,7013
+spots_cli/utils/__init__.py,sha256=UjTFuPmsWvnduES7r_Y-Mx0TmJn4KW-N_-x_xUTHS-M,283
+spots_cli/utils/config_dir.py,sha256=H7TvwPTThXYHIBJ_jDB1jNR0ISeDTUIfrYGO553I2lQ,519
+spots_cli/utils/detect_browser.py,sha256=qxs-a6WZCJaGq9d6OphASM817UzdUhuek8KPk3H4XmI,815
+spots_cli/utils/fetch.py,sha256=usqFnMFuF0sMLTYSsageOvKIULagMTvlzxT4KhwCCd0,2200
+spots_cli/utils/search_fallbacks.py,sha256=TH8Nfkomh-ad_e5sG8ccLhjfSx-MmBoRC0dr_xH8ONo,522
+spots_cli-0.1.0.dist-info/METADATA,sha256=2eToqgcJYJu5-RPl_1r8-suRe7gii0pBGkkQTLBGISU,4028
+spots_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+spots_cli-0.1.0.dist-info/entry_points.txt,sha256=Sqau0y_5RbvwCSLU7vpGnPLIMg5CUETmgEIk-sqPpvI,49
+spots_cli-0.1.0.dist-info/licenses/LICENSE,sha256=EeUxX9Af6TyAbyaTWp-HaboYttd8zzXfXmvxM471Evc,35158
+spots_cli-0.1.0.dist-info/RECORD,,

spots_cli-0.1.0.dist-info/WHEEL

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

spots_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spots_cli = spots_cli.cli:main