spots-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{spots_cli-0.1.0 → spots_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: spots_cli
-Version: 0.1.0
+Version: 0.2.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
@@ -24,7 +24,7 @@ Requires-Dist: requests
 Requires-Dist: spotipy
 Requires-Dist: tenacity
 Requires-Dist: typer
-Requires-Dist: yt-dlp
+Requires-Dist: yt-dlp[default]>=2026.10.26
 Description-Content-Type: text/markdown
 
 # 🎧 Spots
@@ -63,7 +63,7 @@ It resolves tracks across platforms, matches metadata intelligently, and enables
 ## 📦 Installation
 
 ```bash
-pip install spots
+pip install spots-cli
 ```
 
 ---
@@ -73,22 +73,32 @@ pip install spots
 ### Run the setup script:
 
 ```bash
-spots setup
+spots_cli setup
 ```
 
 * follow the prompts to generate the config folder
 
 
+### YouTube account features (optional)
+
+Migrating likes uses your own Google credentials. In Google Cloud Console, enable the YouTube Data API v3, create an OAuth client ID of type *Desktop app*, and save its JSON as `client_secrets.json` in the Spots config folder:
+
+* Linux: `~/.config/spots_cli/`
+* macOS: `~/Library/Application Support/spots_cli/`
+* Windows: `%APPDATA%\spots_cli\`
+
+Then answer "y" to the YouTube question in `spots_cli setup`. You'll sign in to YouTube in your browser the first time.
+
 ---
 
 ## 🚀 Usage
 ```bash
 # search a title
 # required search format: `Artist - Title`
-spots download "Kelsey Lynn - Modern Day Marilyn Monroe"
+spots_cli download "Kelsey Lynn - Modern Day Marilyn Monroe"
 
 # download a direct url
-spots download "https://www.youtube.com/watch?v=UmZPa5Qudtw"
+spots_cli download "https://www.youtube.com/watch?v=UmZPa5Qudtw"
 ```
 
 Spots will:
@@ -104,19 +114,23 @@ Spots will:
 
 * download - downloads a direct url or a search query
   ```bash
-  spots download "Kelsey Lynn - Modern Day Marilyn Monroe"
+  spots_cli download "Kelsey Lynn - Modern Day Marilyn Monroe"
+  ```
+* download-video - downloads a YouTube video (a url, or search terms) as mp4. Picks the highest resolution unless you pass `--resolution`
+  ```bash
+  spots_cli download-video "https://www.youtube.com/watch?v=UmZPa5Qudtw" --resolution 720p
   ```
 * migrate-likes - transfers likes from Spotify to YouTube (more providers coming soon...)
   ```bash
-  spots migrate-likes
+  spots_cli 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
+  spots_cli add-to-history path-to-music
   ```
 * remove-duplicates - removes duplicate songs in a given folder.
   ```bash
-  spots remove-duplicates path-to-music
+  spots_cli remove-duplicates path-to-music
   ```
 
 ---

{spots_cli-0.1.0 → spots_cli-0.2.0}/README.md

@@ -34,7 +34,7 @@ It resolves tracks across platforms, matches metadata intelligently, and enables
 ## 📦 Installation
 
 ```bash
-pip install spots
+pip install spots-cli
 ```
 
 ---
@@ -44,22 +44,32 @@ pip install spots
 ### Run the setup script:
 
 ```bash
-spots setup
+spots_cli setup
 ```
 
 * follow the prompts to generate the config folder
 
 
+### YouTube account features (optional)
+
+Migrating likes uses your own Google credentials. In Google Cloud Console, enable the YouTube Data API v3, create an OAuth client ID of type *Desktop app*, and save its JSON as `client_secrets.json` in the Spots config folder:
+
+* Linux: `~/.config/spots_cli/`
+* macOS: `~/Library/Application Support/spots_cli/`
+* Windows: `%APPDATA%\spots_cli\`
+
+Then answer "y" to the YouTube question in `spots_cli setup`. You'll sign in to YouTube in your browser the first time.
+
 ---
 
 ## 🚀 Usage
 ```bash
 # search a title
 # required search format: `Artist - Title`
-spots download "Kelsey Lynn - Modern Day Marilyn Monroe"
+spots_cli download "Kelsey Lynn - Modern Day Marilyn Monroe"
 
 # download a direct url
-spots download "https://www.youtube.com/watch?v=UmZPa5Qudtw"
+spots_cli download "https://www.youtube.com/watch?v=UmZPa5Qudtw"
 ```
 
 Spots will:
@@ -75,19 +85,23 @@ Spots will:
 
 * download - downloads a direct url or a search query
   ```bash
-  spots download "Kelsey Lynn - Modern Day Marilyn Monroe"
+  spots_cli download "Kelsey Lynn - Modern Day Marilyn Monroe"
+  ```
+* download-video - downloads a YouTube video (a url, or search terms) as mp4. Picks the highest resolution unless you pass `--resolution`
+  ```bash
+  spots_cli download-video "https://www.youtube.com/watch?v=UmZPa5Qudtw" --resolution 720p
   ```
 * migrate-likes - transfers likes from Spotify to YouTube (more providers coming soon...)
   ```bash
-  spots migrate-likes
+  spots_cli 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
+  spots_cli add-to-history path-to-music
   ```
 * remove-duplicates - removes duplicate songs in a given folder.
   ```bash
-  spots remove-duplicates path-to-music
+  spots_cli remove-duplicates path-to-music
   ```
 
 ---

{spots_cli-0.1.0 → spots_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "spots_cli"
-version = "0.1.0"
+version = "0.2.0"
 authors = [
   { name="Marlon Baatjes", email="marlonbaatjes62@gmail.com" }
 ]
@@ -30,10 +30,13 @@ dependencies = [
   "requests",
   "spotipy",
   "tenacity",
-  "yt-dlp",
+  "yt-dlp[default]>=2026.10.26",
   "typer"
 ]
 
+[dependency-groups]
+test = ["pytest"]
+
 [project.urls]
 Homepage = "https://github.com/mdesignscode/spots_flask"
 Issues = "https://github.com/mdesignscode/spots_flask"
@@ -41,6 +44,13 @@ Issues = "https://github.com/mdesignscode/spots_flask"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.hatch.build.targets.sdist]
+# only the package, its tests and docs; not the API, deploy files or local scratch files
+include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
 [tool.mypy]
 explicit_package_bases = true
 

{spots_cli-0.1.0 → spots_cli-0.2.0}/src/spots_cli/__init__.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from logging import getLogger
 from os.path import exists
 
@@ -8,6 +10,7 @@ from .models import (
     TitleExistsError,
     InvalidSearchFormat,
     InvalidURL,
+    ResolutionUnavailable,
 )
 
 logger = getLogger(__name__)
@@ -114,6 +117,41 @@ class Spots:
             )
             self.container.core.storage.save()
 
+    def download_video(
+        self, query: str, resolution: str | None = None, directory_path: str = ""
+    ) -> str | None:
+        """Downloads a YouTube video as mp4
+
+        Args:
+            query (str): A YouTube video url, or search terms (the top result is used).
+            resolution (str, Optional): e.g. "720p". Defaults to the highest available.
+            directory_path (str, Optional): sub-folder of the downloads folder.
+
+        Returns:
+            str | None: the downloaded file's path, or None if nothing was downloaded.
+        """
+        is_url = query.startswith(("http://", "https://"))
+
+        try:
+            logger.info(f"Searching for {query}...")
+            search = self.container.domain.youtube_search.video_search(
+                query=query, is_general_search=not is_url
+            )
+            video = search.result if is_url else search.result[0]
+
+            logger.info(f"Downloading {video.full_title}...")
+            path = self.downloader.download_video(
+                video_info=video, resolution=resolution, directory_path=directory_path
+            )
+        except (SongNotFound, ResolutionUnavailable) as e:
+            logger.error(e)
+            return None
+        finally:
+            self.container.core.storage.save()
+
+        logger.info(f"Saved to {path}")
+        return path
+
     def transfer_spotify_likes(self):
         """Transfers all spotify likes to YouTube library"""
         try:
@@ -121,5 +159,12 @@ class Spots:
         except SongNotFound:
             logger.info("No liked songs found.")
 
+    def download_spotify_likes(self):
+        """Downloads all Spotify likes"""
+        try:
+            self.container.app.youtube_user_playlist.transfer_spotify_likes_to_yt()
+        except SongNotFound:
+            logger.info("No liked songs found.")
+
 
 __all__ = ["Spots"]

{spots_cli-0.1.0 → spots_cli-0.2.0}/src/spots_cli/app/domain_resolver.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from logging import getLogger
 from typing import TYPE_CHECKING, Sequence, overload
 
 from spots_cli.models import Metadata, SongNotFound, Sentinel, YTVideoInfo
@@ -11,6 +12,9 @@ if TYPE_CHECKING:
     from spots_cli.services import YoutubeSearchService
 
 
+logger = getLogger(__name__)
+
+
 @dataclass
 class MatchingDomainResults:
     provider: list[Metadata]
@@ -23,6 +27,23 @@ class ResolvedDomainResult:
     youtube: YTVideoInfo
 
 
+def _fallback_metadata(video: YTVideoInfo) -> Metadata:
+    """Builds a bare-bones Metadata object straight from a YouTube result.
+
+    Used when no provider (Spotify/Deezer) has metadata for a track, or the
+    provider's result doesn't match. The provider is only used to prettify
+    the library (cover art, album, lyrics, etc) - the audio always comes
+    from YouTube, so a missing/mismatched provider entry should never cause
+    a track to be dropped as long as it exists on YouTube.
+    """
+    return Metadata(
+        title=video.title,
+        artist=video.uploader,
+        link=video.video_link,
+        artist_id="",
+    )
+
+
 class DomainResolver:
     def __init__(
         self,
@@ -71,25 +92,40 @@ class DomainResolver:
                         video_title
                     )
                 except SongNotFound:
+                    logger.debug(
+                        f"No provider metadata for '{video_title}', "
+                        "falling back to YouTube-derived metadata"
+                    )
+                    fallback = _fallback_metadata(video)
                     self.core.storage.new(
-                        query=video_title, result=Sentinel(), query_type="metadata"
+                        query=video_title, result=fallback, query_type="metadata"
                     )
                     self.core.storage.new(
-                        query=video_title, result=Sentinel(), query_type="youtube"
+                        query=video_title, result=video, query_type="youtube"
                     )
+                    provider_playlist.append(fallback)
+                    youtube_videos.append(video)
+                    if (index % 10 == 0) or index == (len(youtube_results) - 1):
+                        self.core.storage.save()
                     continue
 
                 tracks_match = self.core.matcher.match_tracks(
                     video_info=video, metadata=spotify_search_result
                 )
                 if not tracks_match:
+                    logger.debug(
+                        f"Provider metadata for '{video_title}' didn't match, "
+                        "falling back to YouTube-derived metadata"
+                    )
+                    fallback = _fallback_metadata(video)
                     self.core.storage.new(
-                        query=video_title, result=Sentinel(), query_type="metadata"
+                        query=video_title, result=fallback, query_type="metadata"
                     )
                     self.core.storage.new(
-                        query=video_title, result=Sentinel(), query_type="youtube"
+                        query=video_title, result=video, query_type="youtube"
                     )
-                    continue
+                    provider_playlist.append(fallback)
+                    youtube_videos.append(video)
                 else:
                     self.core.storage.new(
                         query=video_title,

spots_cli-0.2.0/src/spots_cli/app/downloader.py

@@ -0,0 +1,260 @@
+from __future__ import annotations
+
+from hashlib import md5
+from os.path import join, exists
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from spots_cli.models import (
+    ResolutionUnavailable,
+    TitleExistsError,
+    Metadata,
+    VideoResolution,
+    YTVideoInfo,
+)
+
+if TYPE_CHECKING:
+    from spots_cli.bootstrap.container import Core, Clients
+
+
+class Downloader:
+    """A service for interacting with YouTube."""
+
+    def __init__(self, *, core: Core, clients: Clients):
+        self.core = core
+        self.clients = clients
+
+    @staticmethod
+    def _filename(video_info: YTVideoInfo) -> str:
+        """A file-system safe name for a video: "Uploader - Title"."""
+        # '/' will read file name as folder in *nix systems
+        filename = video_info.full_title.replace("/", "|")
+        # Check if the file name length is too long, truncate if necessary
+        max_filename_length = 255  # Maximum allowed file name length on most systems
+        if len(filename) > max_filename_length:
+            filename = md5(filename.encode()).hexdigest()[:25]
+        return filename
+
+    @staticmethod
+    def _download_folder(directory_path: str) -> str:
+        """The folder downloads are saved to: ~/Downloads (or ~), plus directory_path."""
+        download_folder = Path.home() / "Downloads"
+        if not exists(download_folder):
+            download_folder = Path.home()
+        return join(download_folder, directory_path)
+
+    def download(
+        self, *, video_info: YTVideoInfo, metadata: Metadata, directory_path: str = ""
+    ) -> bool:
+        """Downloads a YouTube video as mp3
+
+        Args:
+            video_info (YTVideoInfo): the extracted info.
+            directory_path (str, Optional): the folder to be downloaded to. Defaults to the root of the Music folder.
+
+        Returns:
+            bool: True if downloaded successfully.
+        """
+        url = video_info.video_link
+        filename = self._filename(video_info)
+
+        # check if downloaded already
+        if self.core.history.read(filename):
+            raise TitleExistsError(filename)
+
+        folder = self._download_folder(directory_path)
+        download_path = join(folder, f"{filename}.{video_info.audio_ext}")
+        converted_path = join(folder, f"{filename}.mp3")
+
+        # set template for download titles
+        self.clients.ytdlp.options = {"outtmpl": download_path}
+
+        # download video
+        self.clients.ytdlp.client.download([url])
+
+        self.clients.ytdlp.reset_options()
+
+        # post download processing
+        converted = self.core.converter.convert_to_mp3(
+            old_file=download_path, new_file=converted_path
+        )
+        if converted:
+            metadata_updated = self.core.converter.update_metadata(
+                audio_path=converted_path, metadata=metadata
+            )
+            if metadata_updated:
+                self.core.history.write(filename)
+        else:
+            return False
+
+        return True
+
+    def get_available_resolutions(
+        self, *, video_info: YTVideoInfo
+    ) -> dict[str, VideoResolution]:
+        """
+        Detects all available video resolutions for a YouTube video.
+
+        Args:
+            video_info (YTVideoInfo): the extracted video info (only .id is used
+                to look up the video).
+
+        Returns:
+            dict[str, VideoResolution]: maps a resolution label (e.g. "1080p")
+                to a VideoResolution describing the best available format at
+                that resolution. filesize_mb is reported in megabytes (MB).
+                Most high-resolution formats are video-only (acodec == "none");
+                download_video automatically merges in the best available audio
+                track for those.
+        """
+        url = video_info.video_link
+
+        self.clients.ytdlp.options = {"quiet": True, "noplaylist": True}
+        try:
+            info = self.clients.ytdlp.client.extract_info(url, download=False)
+        finally:
+            self.clients.ytdlp.reset_options()
+
+        all_formats = info.get("formats", [])
+
+        # Estimate the size of the audio track yt-dlp will pick for "bestaudio",
+        # so video-only formats can report a total (video + audio) download size
+        # instead of just the video stream's size.
+        best_audio_bytes = 0
+        best_audio_abr = -1.0
+        for fmt in all_formats:
+            is_audio_only = fmt.get("vcodec") in (None, "none") and fmt.get(
+                "acodec"
+            ) not in (None, "none")
+            if not is_audio_only:
+                continue
+            abr = fmt.get("abr") or 0
+            if abr > best_audio_abr:
+                best_audio_abr = abr
+                best_audio_bytes = (
+                    fmt.get("filesize") or fmt.get("filesize_approx") or 0
+                )
+
+        resolutions: dict[str, VideoResolution] = {}
+        for fmt in all_formats:
+            height = fmt.get("height")
+            # skip audio-only formats and formats with no video track
+            if not height or fmt.get("vcodec") in (None, "none"):
+                continue
+
+            label = f"{height}p"
+            is_video_only = fmt.get("acodec") in (None, "none")
+            video_bytes = fmt.get("filesize") or fmt.get(
+                "filesize_approx") or 0
+            # video-only formats get merged with bestaudio on download, so
+            # reflect that in the reported size; progressive formats already
+            # include audio in their own filesize.
+            total_bytes = video_bytes + best_audio_bytes if is_video_only else video_bytes
+
+            existing = resolutions.get(label)
+            existing_bytes = (existing.filesize_mb or 0) * \
+                1024 * 1024 if existing else -1
+
+            # keep the best-quality format available for each resolution
+            if not existing or total_bytes > existing_bytes:
+                resolutions[label] = VideoResolution(
+                    format_id=fmt.get("format_id"),
+                    height=height,
+                    ext=fmt.get("ext"),
+                    vcodec=fmt.get("vcodec"),
+                    acodec=fmt.get("acodec"),
+                    fps=fmt.get("fps"),
+                    filesize_mb=(
+                        round(total_bytes / (1024 * 1024),
+                              2) if total_bytes else None
+                    ),
+                )
+
+        return resolutions
+
+    @staticmethod
+    def pick_resolution(
+        resolutions: dict[str, VideoResolution], label: str | None = None
+    ) -> VideoResolution:
+        """
+        Chooses one resolution from get_available_resolutions().
+
+        Args:
+            resolutions: the available resolutions, keyed by label.
+            label (str, Optional): e.g. "720p" (a bare "720" is accepted too).
+                Defaults to the highest resolution available.
+
+        Raises:
+            ResolutionUnavailable: no resolutions, or `label` is not among them.
+        """
+        by_height = sorted(resolutions.values(), key=lambda r: r.height)
+        available = [r.label for r in by_height]
+
+        if label is None:
+            if not by_height:
+                raise ResolutionUnavailable("best", available)
+            return by_height[-1]
+
+        wanted = label.strip().lower()
+        if not wanted.endswith("p"):
+            wanted += "p"
+        if wanted not in resolutions:
+            raise ResolutionUnavailable(wanted, available)
+        return resolutions[wanted]
+
+    def download_video(
+        self,
+        *,
+        video_info: YTVideoInfo,
+        resolution: VideoResolution | str | None = None,
+        directory_path: str = "",
+    ) -> str:
+        """
+        Downloads a YouTube video as mp4 at a chosen resolution.
+
+        Args:
+            video_info (YTVideoInfo): the extracted info.
+            resolution (VideoResolution | str, Optional): one of the values
+                returned by get_available_resolutions(), a label such as
+                "1080p", or None for the highest resolution available.
+            directory_path (str, Optional): the folder to be downloaded to.
+
+        Returns:
+            str: the path of the downloaded file.
+
+        Raises:
+            ResolutionUnavailable: the requested label is not offered.
+        """
+        if not isinstance(resolution, VideoResolution):
+            resolution = self.pick_resolution(
+                self.get_available_resolutions(video_info=video_info), resolution
+            )
+
+        url = video_info.video_link
+        download_path = join(
+            self._download_folder(directory_path),
+            f"{self._filename(video_info)}.%(ext)s",
+        )
+
+        # video-only formats (common at higher resolutions) need audio merged in
+        format_selector = (
+            f"{resolution.format_id}+bestaudio/best"
+            if resolution.is_video_only
+            else resolution.format_id
+        )
+
+        self.clients.ytdlp.options = {
+            "outtmpl": download_path,
+            "format": format_selector,
+            "merge_output_format": "mp4",
+            "postprocessors": [
+                {"key": "FFmpegVideoConvertor", "preferedformat": "mp4"}
+            ],
+        }
+
+        try:
+            info = self.clients.ytdlp.client.extract_info(url, download=True)
+        finally:
+            self.clients.ytdlp.reset_options()
+
+        return info["requested_downloads"][-1]["filepath"]