syncify-py 1.0.0__py3-none-any.whl

syncify/__init__.py

@@ -0,0 +1,6 @@
+"""Syncify - Spotify track and playlist metadata library."""
+
+from syncify.spotify.Spotify_playlist_info import PlaylistDetails, get_playlist
+from syncify.spotify.Spotify_track_info import TrackDetails, get_track
+
+__all__ = ["get_track", "get_playlist", "TrackDetails", "PlaylistDetails"]

syncify/__main__.py

@@ -0,0 +1,79 @@
+"""CLI entry point for python -m syncify."""
+
+import argparse
+import sys
+
+from syncify.spotify.Spotify_playlist_info import PlaylistDetails, get_playlist
+from syncify.spotify.Spotify_track_info import TrackDetails, get_track
+from syncify.spotify.utils import get_link_type
+
+
+def _print_track(details: TrackDetails) -> None:
+    print("Track:")
+    print(f"  URL    : {details.spotify_url or '(empty)'}")
+    print(f"  ID     : {details.track_id or '(empty)'}")
+    print(f"  Title  : {details.track_title or '(empty)'}")
+    print(f"  Artist : {details.artist_title or '(empty)'}")
+    print(f"  Image  : {details.track_image_url or '(empty)'}")
+
+
+def _print_playlist(details: PlaylistDetails) -> None:
+    print("Playlist:")
+    print(f"  URL    : {details.playlist_url or '(empty)'}")
+    print(f"  ID     : {details.playlist_id or '(empty)'}")
+    print(f"  Title  : {details.title or '(empty)'}")
+    print(f"  Tracks : {len(details.track_urls)}")
+    print(f"  Image  : {details.playlist_image_url or '(empty)'}")
+    for i, url in enumerate(details.track_urls, 1):
+        print(f"    {i:>3}. {url}")
+
+
+def _run(urls: list[str]) -> int:
+    for i, url in enumerate(urls, 1):
+        link_type = get_link_type(url)
+        print("=" * 60)
+        print(f"[{i}] {url}")
+        print(f"Type: {link_type or 'Invalid'}")
+
+        if link_type == "Track":
+            try:
+                _print_track(get_track(url))
+            except Exception as e:
+                print(f"Error: {e}")
+                return 1
+        elif link_type == "Playlist":
+            try:
+                _print_playlist(get_playlist(url))
+            except Exception as e:
+                print(f"Error: {e}")
+                return 1
+        else:
+            print("Invalid Spotify URL. Use track or playlist links.")
+            return 1
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Fetch Spotify track or playlist details.")
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("--track", metavar="URL", help="Fetch track details")
+    group.add_argument("--playlist", metavar="URL", help="Fetch playlist details")
+    parser.add_argument("urls", nargs="*", metavar="URL", help="Spotify URLs (auto-detect)")
+    args = parser.parse_args()
+
+    if args.track:
+        urls = [args.track]
+    elif args.playlist:
+        urls = [args.playlist]
+    elif args.urls:
+        urls = args.urls
+    else:
+        print("Usage: python -m syncify <url> [url ...]")
+        print("       python -m syncify --track <url>")
+        print("       python -m syncify --playlist <url>")
+        return 1
+    return _run(urls)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

syncify/spotify/Spotify_playlist_info.py

@@ -0,0 +1,299 @@
+"""
+spotify_playlist_info.py
+------------------------
+Standalone Python library to fetch Spotify playlist/track details.
+
+Dependencies:
+    pip install selenium beautifulsoup4 requests webdriver-manager
+
+Usage:
+    from spotify_playlist_info import SpotifyPlaylistInfo
+
+    info = SpotifyPlaylistInfo()
+    details = info.get_playlist_details("https://open.spotify.com/playlist/...")
+    print(details.title)
+    print(details.track_urls)
+"""
+
+import re
+import time
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+import requests
+from bs4 import BeautifulSoup
+from selenium import webdriver
+from selenium.webdriver.chrome.options import Options
+from selenium.webdriver.common.by import By
+from selenium.webdriver.support import expected_conditions as EC
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.common.exceptions import WebDriverException
+from selenium.webdriver.chrome.service import Service
+from webdriver_manager.chrome import ChromeDriverManager
+
+
+# ---------------------------------------------------------------------------
+# Regex constants (from shared utils)
+# ---------------------------------------------------------------------------
+from syncify.spotify.utils import (
+    get_link_type,
+    is_valid_link,
+    PLAYLIST_REGEX,
+    TRACK_REGEX,
+    canonicalize_spotify_url,
+)
+
+
+# ---------------------------------------------------------------------------
+# Data class
+# ---------------------------------------------------------------------------
+@dataclass
+class PlaylistDetails:
+    """Holds the result of a playlist scrape."""
+    # Use empty defaults so missing data is represented by empty fields.
+    playlist_url: str = ""
+    playlist_id: str = ""
+    title: str = ""
+    playlist_image_url: str = ""
+    track_urls: List[str] = field(default_factory=list)
+
+    def __repr__(self) -> str:
+        return f"PlaylistDetails(title={self.title!r}, tracks={len(self.track_urls)})"
+
+
+def get_song_name_from_url(url: str) -> str:
+    """
+    Fetch a Spotify track page and extract the song title from the
+    og:title meta tag.
+
+    Args:
+        url: A Spotify track URL.
+
+    Returns:
+        The song title string, or 'Song title not found.' on failure.
+    """
+    headers = {
+        "User-Agent": (
+            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+            "AppleWebKit/537.36 (KHTML, like Gecko) "
+            "Chrome/114.0.0.0 Safari/537.36"
+        )
+    }
+    resp = requests.get(url, headers=headers, timeout=15)
+    resp.raise_for_status()
+    soup = BeautifulSoup(resp.text, "html.parser")
+    tag = soup.find("meta", property="og:title")
+    if tag and tag.get("content"):
+        return tag["content"]
+    return "Song title not found."
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+def get_playlist(url: str) -> PlaylistDetails:
+    """
+    Fetch playlist details from a Spotify playlist URL.
+
+    Args:
+        url: Full Spotify playlist URL (e.g. https://open.spotify.com/playlist/...).
+
+    Returns:
+        PlaylistDetails with title, track_urls, playlist_image_url.
+    """
+    return SpotifyPlaylistInfo().get_playlist(url)
+
+
+# ---------------------------------------------------------------------------
+# Main class
+# ---------------------------------------------------------------------------
+class SpotifyPlaylistInfo:
+    """
+    Scrapes a Spotify playlist page using Selenium (headless Chrome) and
+    returns all track URLs along with the playlist title.
+    Uses webdriver-manager to manage ChromeDriver automatically.
+
+    Args:
+        page_load_timeout:  Seconds to wait for the page to load (default 30).
+        scroll_pause:       Seconds to pause between scroll steps (default 2).
+        initial_wait:       Seconds to wait after first page load (default 10).
+    """
+
+    def __init__(
+        self,
+        page_load_timeout: int = 30,
+        scroll_pause: float = 2.0,
+        initial_wait: float = 10.0,
+    ) -> None:
+        self.page_load_timeout  = page_load_timeout
+        self.scroll_pause       = scroll_pause
+        self.initial_wait       = initial_wait
+        self.playlist_title: str = ""
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+    def get_playlist(self, url: str) -> PlaylistDetails:
+        """
+        Scrape all track URLs and the title from a Spotify playlist page.
+
+        Args:
+            url: Full Spotify playlist URL.
+
+        Returns:
+            A :class:`PlaylistDetails` instance.
+
+        Raises:
+            ValueError: If *url* is not a Spotify playlist link.
+            Exception:  On any Selenium / network error.
+        """
+        if get_link_type(url) != "Playlist":
+            raise ValueError(f"{url!r} is not a Spotify playlist link.")
+
+        # Initialise details with URL and (if possible) playlist ID extracted from it.
+        details = PlaylistDetails(playlist_url=url)
+        canonical = canonicalize_spotify_url(url)
+        match = re.match(PLAYLIST_REGEX, canonical)
+        if match:
+            details.playlist_id = match.group(1)
+
+        driver = self._build_driver()
+        links_found: List[str] = []
+
+        try:
+            driver.set_page_load_timeout(self.page_load_timeout)
+            driver.get(url)
+            time.sleep(self.initial_wait)
+
+            # ---- grab playlist title ----
+            title_el = driver.find_element(
+                By.CSS_SELECTOR, 'span[data-testid="entityTitle"]'
+            )
+            self.playlist_title = title_el.text
+
+            # ---- grab playlist image URL (mosaic cover) ----
+            # The main playlist image is rendered inside a container with
+            # data-testid="playlist-image", which holds an <img> whose src is
+            # the mosaic URL like the one you provided.
+            playlist_image_url = ""
+            try:
+                image_el = driver.find_element(
+                    By.CSS_SELECTOR, 'div[data-testid="playlist-image"] img'
+                )
+                playlist_image_url = image_el.get_attribute("src") or ""
+            except Exception:
+                # If we fail to locate the image, keep the field empty.
+                playlist_image_url = ""
+
+            # ---- scroll and collect track links, accounting for virtualized rows ----
+            # The Spotify UI virtualizes the tracklist, so the number of DOM rows can
+            # stay roughly constant while the actual songs change as you scroll.
+            # To handle this, we:
+            #   1) repeatedly scroll to the last visible row
+            #   2) on each iteration, collect any new track URLs we see
+            #   3) stop when we stop discovering new links for several iterations
+            stable_loops = 0
+            max_stable_loops = 5
+            max_scrolls = 200
+            prev_count = 0
+
+            for _ in range(max_scrolls):
+                # collect links currently in the DOM, but only from the main
+                # playlist tracklist (exclude the separate "Recommended" list).
+                rows = driver.find_elements(
+                    By.CSS_SELECTOR,
+                    'div[data-testid="playlist-tracklist"] div[data-testid="tracklist-row"]',
+                )
+                for row in rows:
+                    try:
+                        anchor = row.find_element(
+                            By.CSS_SELECTOR, 'a[data-testid="internal-track-link"]'
+                        )
+                        href = anchor.get_attribute("href") or ""
+                        if is_valid_link(href) and href not in links_found:
+                            links_found.append(href)
+                    except Exception:
+                        # Some rows may be ads or separators – skip them silently.
+                        pass
+
+                current_count = len(links_found)
+                if current_count == prev_count:
+                    stable_loops += 1
+                    if stable_loops >= max_stable_loops:
+                        break
+                else:
+                    stable_loops = 0
+                    prev_count = current_count
+
+                # scroll to the last visible row in the main playlist tracklist
+                # to trigger loading more items (and not the recommended rows)
+                driver.execute_script(
+                    """
+                    const rows = document.querySelectorAll(
+                        "div[data-testid='playlist-tracklist'] div[data-testid='tracklist-row']"
+                    );
+                    if (rows.length) {
+                        rows[rows.length - 1].scrollIntoView({ behavior: 'smooth', block: 'end' });
+                    }
+                    """
+                )
+                time.sleep(self.scroll_pause)
+
+        finally:
+            driver.quit()
+
+        details.title = self.playlist_title
+        details.playlist_image_url = playlist_image_url
+        details.track_urls = links_found
+
+        return details
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+    def _build_driver(self) -> webdriver.Chrome:
+        """Construct and return a headless Chrome WebDriver.
+
+        We rely on Selenium Manager to locate a matching ChromeDriver
+        for the locally installed Chrome (no webdriver-manager needed).
+        """
+        chrome_options = Options()
+        chrome_options.add_argument("--headless")
+        chrome_options.add_argument("--disable-gpu")
+        chrome_options.add_argument("--no-sandbox")
+        chrome_options.add_argument("--incognito")
+        chrome_options.add_argument(
+            "user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+            "AppleWebKit/537.36 (KHTML, like Gecko) "
+            "Chrome/114.0.0.0 Safari/537.36"
+        )
+        chrome_options.add_argument("--remote-allow-origins=*")
+        chrome_options.add_argument("--disable-blink-features=AutomationControlled")
+
+        # Prefer Selenium Manager (Selenium 4+) but fallback to webdriver-manager
+        # for environments where Selenium Manager isn't available / can't resolve.
+        try:
+            return webdriver.Chrome(options=chrome_options)
+        except WebDriverException:
+            service = Service(ChromeDriverManager().install())
+            return webdriver.Chrome(service=service, options=chrome_options)
+
+
+# ---------------------------------------------------------------------------
+# Quick CLI test
+# ---------------------------------------------------------------------------
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) < 2:
+        print("Usage: python spotify_playlist_info.py <spotify_playlist_url>")
+        sys.exit(1)
+
+    playlist_url = sys.argv[1]
+    scraper = SpotifyPlaylistInfo()
+    result = scraper.get_playlist(playlist_url)
+
+    print(f"Playlist : {result.title}")
+    print(f"Tracks   : {len(result.track_urls)}")
+    for i, t in enumerate(result.track_urls, 1):
+        print(f"  {i:>3}. {t}")

syncify/spotify/Spotify_track_info.py

@@ -0,0 +1,177 @@
+"""
+Spotify_track_info.py
+---------------------
+Lightweight helpers for working with Spotify track / playlist URLs and for
+extracting metadata for a single Spotify track.
+
+This module is **Spotify‑only**: it does not download audio or touch yt-dlp.
+Downloading and further processing are handled in a separate `youtube` module.
+"""
+
+import logging
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+from selenium import webdriver
+from selenium.common.exceptions import WebDriverException
+from selenium.webdriver.common.by import By
+from selenium.webdriver.chrome.options import Options
+from selenium.webdriver.chrome.service import Service
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.webdriver.support import expected_conditions as EC
+from webdriver_manager.chrome import ChromeDriverManager
+
+from syncify.spotify.utils import (
+    PLAYLIST_REGEX,
+    TRACK_REGEX,
+    canonicalize_spotify_url,
+)
+
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+# Use a module-specific logger and keep external driver logs quiet.
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s - %(message)s",
+)
+LOG = logging.getLogger("SpotifyTrackInfo")
+logging.getLogger("WDM").setLevel(logging.WARNING)
+logging.getLogger("urllib3").setLevel(logging.WARNING)
+
+
+# ---------------------------------------------------------------------------
+# Regex helpers  (ported 1-to-1 from Java)
+# ---------------------------------------------------------------------------
+YOUTUBE_URL_REGEX = (
+    r"^(?:https?://)?(?:www\.|m\.)?(?:youtube\.com/watch\?v=|youtu\.be/)"
+    r"([a-zA-Z0-9_-]{11})"
+)
+YOUTUBE_URL_PATTERN = re.compile(YOUTUBE_URL_REGEX)
+
+# ---------------------------------------------------------------------------
+# Data model for track details
+# ---------------------------------------------------------------------------
+@dataclass
+class TrackDetails:
+    """
+    Holds all gathered information for a single Spotify track.
+
+    All string fields default to the empty string so that missing data
+    is represented as empty fields instead of None.
+    """
+
+    spotify_url: str = ""
+    track_id: str = ""
+    track_title: str = ""
+    artist_title: str = ""
+    track_image_url: str = ""
+
+
+def is_spotify_link(url: str) -> bool:
+    """Return True if *url* is a Spotify track or playlist URL."""
+    canonical = canonicalize_spotify_url(url)
+    return bool(re.match(TRACK_REGEX, canonical) or re.match(PLAYLIST_REGEX, canonical))
+
+
+def extract_youtube_video_id(url: str) -> Optional[str]:
+    """Return the 11‑char YouTube video ID from a full URL, or None."""
+    match = YOUTUBE_URL_PATTERN.match(url)
+    return match.group(1) if match else None
+
+
+def is_valid_youtube_url(url: str) -> bool:
+    """Quick validation that a URL looks like a YouTube watch / short link."""
+    return extract_youtube_video_id(url) is not None
+
+
+# ---------------------------------------------------------------------------
+# Selenium-based scraping
+# ---------------------------------------------------------------------------
+def _build_chrome_driver() -> webdriver.Chrome:
+    """
+    Create a headless Chrome WebDriver.
+
+    We rely on Selenium Manager to locate a matching ChromeDriver for
+    the locally installed Chrome (no webdriver-manager needed).
+    """
+    options = Options()
+    options.add_argument("--headless")
+    options.add_argument("--disable-gpu")
+    options.add_argument("--no-sandbox")
+    options.add_argument("--incognito")
+    options.add_argument(
+        "user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36"
+    )
+    options.add_argument("--remote-allow-origins=*")
+    options.add_argument("--disable-dev-shm-usage")
+
+    # Prefer Selenium Manager (Selenium 4+) but fallback to webdriver-manager
+    # for environments where Selenium Manager isn't available / can't resolve.
+    try:
+        return webdriver.Chrome(options=options)
+    except WebDriverException:
+        service = Service(ChromeDriverManager().install())
+        return webdriver.Chrome(service=service, options=options)
+
+
+def get_track(url: str) -> TrackDetails:
+    """
+    Fetch track metadata from a Spotify track URL.
+
+    Args:
+        url: Full Spotify track URL (e.g. https://open.spotify.com/track/...).
+
+    Returns:
+        TrackDetails with track_id, track_title, artist_title, track_image_url.
+    """
+    driver = _build_chrome_driver()
+    details = TrackDetails(spotify_url=url)
+
+    # Try to extract the track ID directly from the URL using TRACK_REGEX.
+    canonical = canonicalize_spotify_url(url)
+    match = re.match(TRACK_REGEX, canonical)
+    if match:
+        details.track_id = match.group(1)
+
+    try:
+        wait = WebDriverWait(driver, 30)
+
+        # ── Step 1: Spotify page ──────────────────────────────────────────
+        driver.get(url)
+        track_name_el = wait.until(
+            EC.presence_of_element_located(
+                (By.CSS_SELECTOR, 'span[data-testid="entityTitle"]')
+            )
+        )
+        track_artist_el = driver.find_element(
+            By.CSS_SELECTOR, 'a[data-testid="creator-link"]'
+        )
+        # Try to grab the main track artwork image from the header section.
+        # Avoid relying on the dynamic class name (e.g. "fNnrSm2k2IonbI9c");
+        # instead, use the stable "contentSpacing" class and Spotify image URL.
+        try:
+            track_img_el = driver.find_element(
+                By.CSS_SELECTOR,
+                "div.contentSpacing img[loading='lazy'][src^='https://i.scdn.co/image/']",
+            )
+            details.track_image_url = track_img_el.get_attribute("src") or ""
+        except Exception:
+            # Image URL is optional; keep it empty if not found.
+            details.track_image_url = ""
+
+        details.track_title = track_name_el.text.strip()
+        details.artist_title = track_artist_el.text.strip()
+        LOG.debug(
+            "Spotify track: '%s' by '%s'", details.track_title, details.artist_title
+        )
+
+    except Exception as exc:
+        LOG.debug("Error in get_track: %s", exc)
+    finally:
+        driver.quit()
+
+    return details

syncify/spotify/__init__.py

@@ -0,0 +1 @@
+# Syncify Spotify package

syncify/spotify/utils.py

@@ -0,0 +1,36 @@
+"""Shared Spotify URL helpers."""
+
+import re
+from urllib.parse import urlparse
+from typing import Optional
+
+_ID = r"([a-zA-Z0-9]+)"
+TRACK_REGEX = rf"^https?://open\.spotify\.com/track/{_ID}/?$"
+PLAYLIST_REGEX = rf"^https?://open\.spotify\.com/playlist/{_ID}/?$"
+
+
+def canonicalize_spotify_url(url: str) -> str:
+    """
+    Strip query/fragment and normalize for matching.
+
+    Spotify links often include tracking params like '?si=...'.
+    """
+    parsed = urlparse(url.strip())
+    if not parsed.scheme or not parsed.netloc:
+        return url.strip()
+    return f"{parsed.scheme}://{parsed.netloc}{parsed.path}"
+
+
+def get_link_type(url: str) -> Optional[str]:
+    """Return 'Track', 'Playlist', or None for invalid URLs."""
+    canonical = canonicalize_spotify_url(url)
+    if re.match(TRACK_REGEX, canonical):
+        return "Track"
+    if re.match(PLAYLIST_REGEX, canonical):
+        return "Playlist"
+    return None
+
+
+def is_valid_link(url: str) -> bool:
+    """Return True if url is a valid Spotify track or playlist URL."""
+    return get_link_type(url) is not None

syncify_py-1.0.0.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: syncify-py
+Version: 1.0.0
+Summary: Spotify track and playlist metadata library
+Author: adelelawady
+License: MIT
+Keywords: spotify,playlist,track,metadata
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.7.0
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: selenium>=4.15.0
+Requires-Dist: webdriver-manager>=4.0.0
+Provides-Extra: dev
+Requires-Dist: mutagen>=1.47.0; extra == "dev"
+Dynamic: requires-python
+
+<!--
+NOTE:
+- This README assumes the GitHub repo will be published as: adelelawady/Syncify
+- Update REPO_NAME below if you rename the repository.
+-->
+
+<div align="center">
+
+![GitHub stars](https://img.shields.io/github/stars/adelelawady/Syncify?style=for-the-badge)
+![GitHub forks](https://img.shields.io/github/forks/adelelawady/Syncify?style=for-the-badge)
+![License](https://img.shields.io/github/license/adelelawady/Syncify?style=for-the-badge)
+![Repo size](https://img.shields.io/github/repo-size/adelelawady/Syncify?style=for-the-badge)
+![Last commit](https://img.shields.io/github/last-commit/adelelawady/Syncify?style=for-the-badge)
+![Issues](https://img.shields.io/github/issues/adelelawady/Syncify?style=for-the-badge)
+![Top language](https://img.shields.io/github/languages/top/adelelawady/Syncify?style=for-the-badge)
+![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)
+![Selenium](https://img.shields.io/badge/Selenium-43B02A?style=for-the-badge&logo=selenium&logoColor=white)
+
+</div>
+
+# 🚀 Syncify
+
+**Syncify** is a Python **library + CLI** that fetches **Spotify track and playlist metadata** directly from `open.spotify.com` pages — great for quick metadata lookups, playlist introspection, and tooling where you don’t want to wire up OAuth.
+
+> **Heads up**: Syncify scrapes Spotify’s web UI (via Selenium). Selectors can break if Spotify updates their site.
+
+## ✨ Features
+
+- **Track metadata**: title, artist, cover image URL, and track ID from a track URL
+- **Playlist metadata**: playlist title, cover image URL, playlist ID, and **all track URLs**
+- **CLI-first**: run `syncify <url>` or `python -m syncify ...`
+- **Auto-detect URLs**: mix track + playlist URLs in one command
+- **No OAuth setup**: does **not** require Spotify API keys/tokens
+
+## 🧠 How It Works
+
+- **Input**: Spotify track/playlist URLs (`https://open.spotify.com/track/...`, `https://open.spotify.com/playlist/...`)
+- **URL detection**: a lightweight regex-based detector determines whether each URL is a Track or Playlist
+- **Extraction**:
+  - **Tracks**: Selenium loads the page and extracts title/artist/image from page elements
+  - **Playlists**: Selenium loads the page, scrolls through the track list, and collects every track link
+- **Output**:
+  - **Library**: returns dataclasses (`TrackDetails`, `PlaylistDetails`)
+  - **CLI**: prints a readable summary plus playlist track URLs
+
+## 🛠 Tech Stack
+
+- **Language**: Python
+- **Automation/scraping**: Selenium (headless Chrome)
+- **Driver management**: `webdriver-manager` (fallback if Selenium driver resolution fails)
+- **HTML parsing (small helper)**: BeautifulSoup4
+- **HTTP**: `requests`
+
+## 📦 Installation
+
+### Prerequisites
+
+- **Python**: 3.9+ recommended (packaging allows older, but tested targets are 3.9–3.12)
+- **Google Chrome** installed (used by Selenium)
+
+### Install from GitHub (recommended)
+
+```bash
+pip install "git+https://github.com/adelelawady/Syncify.git"
+```
+
+### Install locally (for development)
+
+```bash
+git clone https://github.com/adelelawady/Syncify.git
+cd Syncify
+pip install -e ".[dev]"
+```
+
+### Install from source tree (non-editable)
+
+```bash
+pip install .
+```
+
+## ⚙️ Configuration
+
+Syncify has **no required environment variables**.
+
+### Runtime requirements
+
+- **Chrome available on PATH / installed normally**
+- **Chromedriver** is handled automatically via Selenium’s driver resolution, with a fallback to `webdriver-manager`.
+
+### Troubleshooting
+
+- If Selenium can’t start Chrome:
+  - Ensure Chrome is installed and up to date.
+  - Try upgrading Selenium and webdriver-manager:
+
+```bash
+pip install -U selenium webdriver-manager
+```
+
+- If playlist results are incomplete:
+  - Spotify’s UI loads tracks lazily; the scraper scrolls, but very large playlists may take longer.
+
+## 🚀 Usage
+
+## **As a library**
+
+```python
+from syncify import get_track, get_playlist
+
+track = get_track("https://open.spotify.com/track/5nJ4Zzqc2UjwSaIcv7bGjx")
+print(track.track_title, "-", track.artist_title)
+print(track.track_image_url)
+
+playlist = get_playlist("https://open.spotify.com/playlist/5YOevUTnavVClJ0hAslu0N")
+print(playlist.title)
+print("Tracks:", len(playlist.track_urls))
+print(playlist.track_urls[:5])
+```
+
+## **As a CLI**
+
+After installation, you can use either:
+
+- `syncify ...` (console script), or
+- `python -m syncify ...` (module execution)
+
+```bash
+# Auto-detect URL type (track or playlist)
+syncify https://open.spotify.com/track/5nJ4Zzqc2UjwSaIcv7bGjx
+syncify https://open.spotify.com/playlist/5YOevUTnavVClJ0hAslu0N
+
+# Explicit type
+syncify --track https://open.spotify.com/track/...
+syncify --playlist https://open.spotify.com/playlist/...
+
+# Multiple URLs (mixed types supported)
+syncify <url1> <url2> <url3>
+```
+
+CLI flags:
+
+```bash
+syncify --track <URL>
+syncify --playlist <URL>
+syncify <URL> [URL ...]
+```
+
+## 📡 API Reference
+
+### `get_track(url: str) -> TrackDetails`
+
+Fetch metadata for a Spotify track URL.
+
+| Field | Type | Description |
+|---|---:|---|
+| `spotify_url` | `str` | Original Spotify URL |
+| `track_id` | `str` | Spotify track ID |
+| `track_title` | `str` | Song title |
+| `artist_title` | `str` | Artist name |
+| `track_image_url` | `str` | Cover image URL |
+
+### `get_playlist(url: str) -> PlaylistDetails`
+
+Fetch metadata for a Spotify playlist URL.
+
+| Field | Type | Description |
+|---|---:|---|
+| `playlist_url` | `str` | Original Spotify URL |
+| `playlist_id` | `str` | Spotify playlist ID |
+| `title` | `str` | Playlist title |
+| `playlist_image_url` | `str` | Cover image URL |
+| `track_urls` | `list[str]` | Track URLs in the playlist |
+
+## 📂 Project Structure
+
+```text
+Syncify/
+├─ syncify/
+│  ├─ __init__.py              # Public API exports
+│  ├─ __main__.py              # CLI: `python -m syncify` / `syncify`
+│  └─ spotify/
+│     ├─ Spotify_track_info.py
+│     ├─ Spotify_playlist_info.py
+│     ├─ utils.py
+│     └─ __init__.py
+├─ main.py                     # Convenience script wrapper
+├─ pyproject.toml              # Modern packaging + dependencies
+├─ setup.py                    # Legacy packaging (mirrors pyproject)
+├─ requirements.txt            # Dev-friendly requirements list
+└─ README.md
+```
+
+## 🧪 Development
+
+```bash
+git clone https://github.com/adelelawady/Syncify.git
+cd Syncify
+python -m venv .venv
+
+# Windows PowerShell
+.venv\Scripts\Activate.ps1
+
+pip install -e ".[dev]"
+
+# Run the CLI against a URL
+python -m syncify https://open.spotify.com/track/<id>
+```
+
+Suggested checks:
+
+```bash
+python -c "from syncify import get_track; print(get_track('https://open.spotify.com/track/<id>').track_title)"
+```
+
+## 🤝 Contributing
+
+Contributions are welcome!
+
+- **Bugs/requests**: open an issue with a minimal repro (URL + expected vs actual output)
+- **PRs**:
+  - Keep changes focused and include a clear description
+  - Prefer small, well-scoped improvements to selectors and parsing logic
+  - Avoid committing local artifacts (`.venv/`, `build/`, `syncify.egg-info/`)
+
+If you’re adding new scraping logic, please include:
+- A sample Spotify URL (track/playlist) that the change targets
+- A note about which DOM selectors were relied on and why
+
+## 📜 License
+
+**MIT** (as declared in package metadata).
+
+> Tip: consider adding a top-level `LICENSE` file so GitHub can display the license automatically.
+
+## ⭐ Support
+
+If you find Syncify useful, please **star** the repo — it helps others discover the project and motivates continued maintenance.

syncify_py-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+syncify/__init__.py,sha256=yVpPagyNWzPs4LqVh2oOUd7W2hX-drG2ACjQmB6Oj9g,295
+syncify/__main__.py,sha256=j99TDk1bQiWrjELIwxlIjD1fUpaCW5WY2P4WOyP4jYA,2785
+syncify/spotify/Spotify_playlist_info.py,sha256=MhLB_-6f57x-kipvwmOwHnxbjfPHHUxFYgJcTL4doQk,11542
+syncify/spotify/Spotify_track_info.py,sha256=yIQ1npWmQIOcZgTkG4HouuJu1xc_OhIsIvIaD8FrXZA,6595
+syncify/spotify/__init__.py,sha256=UdIQJpYuCJGH-wMMRJwk91HCEgQwiJNQYTvtRxQbu8U,27
+syncify/spotify/utils.py,sha256=rvmcogcNjBohKEHBj9UHvkz3kMt2kJxm-GDj4HE7XAg,1111
+syncify_py-1.0.0.dist-info/METADATA,sha256=xHzZIODzzSIQeIvSacFeomvFdJThtg61gF1MjQkqaT0,8693
+syncify_py-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+syncify_py-1.0.0.dist-info/entry_points.txt,sha256=r0S2JvDU0KL-EwrqSPv1alvl6cdxoIzPPbUDoafFds8,50
+syncify_py-1.0.0.dist-info/top_level.txt,sha256=m-sjI5MAW-8H2dXkFLbn2RdKfEesrKYlwq7GHONcZew,8
+syncify_py-1.0.0.dist-info/RECORD,,

syncify_py-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

syncify_py-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+syncify = syncify.__main__:main

syncify_py-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+syncify