spots-cli 0.1.0__py3-none-any.whl

spots_cli/core/pattern_matcher.py

@@ -0,0 +1,226 @@
+from __future__ import unicode_literals, annotations
+
+from logging import getLogger
+from re import compile, sub, IGNORECASE, VERBOSE
+from typing import TYPE_CHECKING
+
+from spots_cli.engine import storage
+from spots_cli.models import SongNotFound, Sentinel, YTVideoInfo, Metadata
+
+if TYPE_CHECKING:
+    from spots_cli.core import YouTubeExtractor
+
+# -----------------------------
+# logging setup
+# -----------------------------
+
+logger = getLogger(__name__)
+
+# -----------------------------
+# regex
+# -----------------------------
+
+FEAT_PATTERN = compile(
+    r"""
+    (\(|\[)?
+    \b(feat|ft|featuring)\b
+    [\s\.:,-]*.*
+    (\)|\])?
+    """,
+    flags=IGNORECASE | VERBOSE,
+)
+
+NON_WORD_PATTERN = compile(r"\W+")
+
+# -----------------------------
+# constants
+# -----------------------------
+
+STOPWORDS = {
+    "official",
+    "audio",
+    "video",
+    "lyrics",
+    "lyric",
+    "visualizer",
+    "remix",
+    "version",
+    "edit",
+    "hd",
+    "explicit",
+    "clean",
+    "topic",
+}
+
+BAD_UPLOADER_KEYWORDS = {
+    "karaoke",
+    "lyrics",
+    "remastered",
+    "mashup",
+    "nightcore",
+    "slowed",
+    "reverb",
+    "8d",
+    "cover",
+}
+
+# -----------------------------
+# helpers
+# -----------------------------
+
+
+def strip_features(text: str) -> str:
+    cleaned = sub(FEAT_PATTERN, "", text)
+    logger.debug("strip_features: '%s' -> '%s'", text, cleaned)
+    return cleaned
+
+
+def tokenize(text: str) -> set[str]:
+    original = text
+    text = text.lower()
+    text = strip_features(text)
+    tokens = NON_WORD_PATTERN.sub(" ", text).split()
+    filtered = {t for t in tokens if t not in STOPWORDS}
+
+    logger.debug(
+        "tokenize: original='%s', tokens=%s, filtered=%s",
+        original,
+        tokens,
+        filtered,
+    )
+
+    return filtered
+
+
+def token_similarity(a: set[str], b: set[str]) -> float:
+    if not a or not b:
+        logger.debug("token_similarity: empty tokens -> 0.0")
+        return 0.0
+
+    score = len(a & b) / max(len(a), len(b))
+    logger.debug("token_similarity: %s vs %s -> %.3f", a, b, score)
+    return score
+
+
+def uploader_penalty(uploader: str) -> float:
+    uploader_lower = uploader.lower()
+    penalty = 0.35 if any(k in uploader_lower for k in BAD_UPLOADER_KEYWORDS) else 0.0
+
+    logger.debug("uploader_penalty: '%s' -> %.2f", uploader, penalty)
+    return penalty
+
+
+def artist_in_title_or_uploader(
+    sp_artist: str, yt_title: str, yt_uploader: str
+) -> bool:
+    sp_tokens = tokenize(sp_artist)
+    yt_tokens = tokenize(yt_title) | tokenize(yt_uploader)
+    result = bool(sp_tokens & yt_tokens)
+
+    logger.debug(
+        "artist_in_title_or_uploader: sp=%s, yt=%s -> %s",
+        sp_tokens,
+        yt_tokens,
+        result,
+    )
+
+    return result
+
+
+# -----------------------------
+# matcher
+# -----------------------------
+
+
+class PatternMatcher:
+    TITLE_THRESHOLD = 0.50
+    ARTIST_THRESHOLD = 0.40
+    FINAL_THRESHOLD = 0.60
+
+    def __init__(self, *, extractor: YouTubeExtractor):
+        self.extractor = extractor
+
+    def match_tracks(self, *, video_info: YTVideoInfo, metadata: Metadata) -> bool:
+        yt_artist = video_info.uploader or ""
+        yt_title = video_info.title or ""
+
+        sp_artist = metadata.artist or ""
+        sp_title = metadata.title or ""
+
+        logger.debug(
+            "Matching track: YT(title='%s', uploader='%s') vs SP(title='%s', artist='%s')",
+            yt_title,
+            yt_artist,
+            sp_title,
+            sp_artist,
+        )
+
+        yt_title_tokens = tokenize(yt_title)
+        sp_title_tokens = tokenize(sp_title)
+
+        yt_artist_tokens = tokenize(yt_artist)
+        sp_artist_tokens = tokenize(sp_artist)
+
+        title_score = token_similarity(yt_title_tokens, sp_title_tokens)
+        artist_score = token_similarity(yt_artist_tokens, sp_artist_tokens)
+
+        penalty = uploader_penalty(yt_artist)
+
+        final_score = 0.6 * title_score + 0.3 * artist_score - penalty
+
+        logger.debug(
+            "Scores -> title: %.3f, artist: %.3f, penalty: %.2f, final: %.3f",
+            title_score,
+            artist_score,
+            penalty,
+            final_score,
+        )
+
+        title_dominant_match = title_score >= 0.60 and artist_in_title_or_uploader(
+            sp_artist, yt_title, yt_artist
+        )
+
+        score_based_match = final_score >= self.FINAL_THRESHOLD and (
+            title_score >= self.TITLE_THRESHOLD or artist_score >= self.ARTIST_THRESHOLD
+        )
+
+        is_match = title_dominant_match or score_based_match
+
+        logger.debug(
+            "Decision -> title_dominant: %s, score_based: %s, final_match: %s",
+            title_dominant_match,
+            score_based_match,
+            is_match,
+        )
+
+        return is_match
+
+    def find_best_match(
+        self, *, search_results: list[YTVideoInfo], metadata: Metadata
+    ) -> YTVideoInfo:
+        query = f"{metadata.artist} - {metadata.title}"
+        logger.debug("Searching best match for query: '%s'", query)
+
+        cache = storage.get(query=query, query_type="youtube")
+        if cache:
+            logger.debug("Cache hit for query: '%s'", query)
+            return cache
+
+        for idx, result in enumerate(search_results):
+            logger.debug("#" * 50)
+            logger.debug("Evaluating result #%d: %s", idx + 1, result.title)
+
+            title_and_artist = self.extractor.extract_artist_and_title(
+                video_info=result, metadata=metadata
+            )
+            result.full_title = title_and_artist
+
+            if self.match_tracks(video_info=result, metadata=metadata):
+                logger.debug("Match found: '%s'", result.title)
+                storage.new(query=query, result=result, query_type="youtube")
+                logger.debug("#" * 50)
+                return result
+
+        logger.warning("No match found for query: '%s'", query)
+        storage.new(query=query, result=Sentinel(), query_type="youtube")
+        raise SongNotFound(query)

spots_cli/core/video_converter.py

@@ -0,0 +1,146 @@
+from logging import getLogger
+from moviepy.audio.io.AudioFileClip import AudioFileClip
+from mutagen.id3 import ID3
+from mutagen.id3._frames import APIC, TIT2, TPE1, TRCK, TALB, USLT, TDRL
+from mutagen.mp3 import MP3
+from os import remove
+from requests import get
+
+from spots_cli.models.metadata import Metadata
+
+logger = getLogger(__name__)
+
+
+class VideoConverter:
+    """
+    Service responsible for converting audio files to MP3 format
+    and updating their metadata.
+
+    Attributes:
+        @add_to_history (AddToHistoryService): Service for adding downloaded songs to history.
+
+    Methods:
+        @update_metadata
+
+        @convert_to_mp3
+
+    This service handles:
+    - Converting audio files to MP3
+    - Updating ID3 metadata (title, artist, album, cover art, lyrics, etc.)
+    - Removing the original file after conversion
+    - Adding successful downloads to the download history
+    """
+
+    def update_metadata(self, *, audio_path: str, metadata: Metadata) -> bool:
+        """
+        Update the ID3 metadata of an MP3 file.
+
+        Existing ID3 tags are removed and replaced with new ones
+        based on the provided metadata.
+
+        Args:
+            audio_path (str): Path to the MP3 file whose metadata will be updated.
+            metadata (Metadata): Metadata object containing song information.
+
+        Raises:
+            FileNotFoundError: If the audio file does not exist.
+        """
+        logger.debug("Updating metadata")
+
+        try:
+            audio = MP3(audio_path, ID3=ID3)
+
+            # Remove existing ID3 tags
+            audio.tags = None
+
+            # Create new ID3 tags
+            audio.tags = ID3()
+
+            # Set basic metadata
+            audio.tags.add(TIT2(encoding=3, text=metadata.title))
+            audio.tags.add(TPE1(encoding=3, text=metadata.artist))
+            audio.tags.add(TRCK(encoding=3, text=metadata.tracknumber))
+            audio.tags.add(TALB(encoding=3, text=metadata.album))
+
+            # Handle cover art
+            cover = metadata.cover
+            if cover:
+                audio.tags.add(
+                    APIC(
+                        encoding=3,
+                        mime="image/jpeg",
+                        type=3,
+                        desc="Cover",
+                        data=get(cover).content,
+                    )
+                )
+
+            # Add lyrics if provided
+            if metadata.lyrics:
+                audio.tags.add(
+                    USLT(
+                        encoding=3,
+                        lang="eng",
+                        desc="",
+                        text=metadata.lyrics,
+                    )
+                )
+
+            # Add release date if provided
+            if metadata.release_date:
+                audio.tags.add(
+                    TDRL(
+                        encoding=3,
+                        text=metadata.release_date,
+                    )
+                )
+
+            # Save changes
+            audio.save(audio_path)
+
+            return True
+
+        except FileNotFoundError as exc:
+            logger.error(f"{audio_path} not found...")
+            raise exc
+
+    def convert_to_mp3(
+        self,
+        *,
+        old_file: str,
+        new_file: str,
+    ) -> bool:
+        """
+        Convert an audio file to MP3 format and update its metadata.
+
+        This method:
+        - Converts the input audio file to MP3
+        - Deletes the original file
+        - Updates the MP3 metadata
+        - Adds the song to the download history on success
+
+        Args:
+            old_file (str): Path to the source audio file.
+            new_file (str): Path where the converted MP3 file will be saved.
+            song_title (str): Song title to be added to the download history.
+            metadata (Metadata): Metadata to apply to the converted MP3 file.
+
+        Returns:
+            bool: True indicates a successful download
+        """
+        try:
+            # Load the audio clip
+            clip = AudioFileClip(old_file)
+
+            # Convert and save as MP3
+            clip.write_audiofile(new_file, codec="mp3")
+
+            # Clean up resources
+            clip.close()
+            remove(old_file)
+
+            return True
+
+        except FileNotFoundError:
+            logger.error(f"{old_file} not found...")
+            return False

spots_cli/core/web_scraper.py

@@ -0,0 +1,82 @@
+from dataclasses import dataclass
+from bs4 import BeautifulSoup, Comment, Tag
+from logging import getLogger
+from re import search
+from requests import get
+
+logger = getLogger(__name__)
+
+
+@dataclass
+class ScrapedResult:
+    cover: str
+    name: str
+    ids: list[str]
+
+
+def get_element_by_comment(soup: BeautifulSoup, comment_text: str):
+    """Find the first element that follows a comment with exact `comment_text`."""
+    comments = soup.find_all(string=lambda text: isinstance(text, Comment))
+
+    for comment in comments:
+        if comment.strip() == comment_text.strip():
+            parent_el = comment.parent
+            if parent_el:
+                return parent_el
+
+    return None
+
+
+class WebScraper:
+    def scrape_azlyrics(self, *, artist: str, title: str):
+
+        logger.debug("Searching for lyrics on AZLyrics")
+        artist = artist.lower().replace(" ", "")
+        title = title.lower().replace(" ", "")
+
+        url = f"https://azlyrics.com/lyrics/{artist}/{title}.html"
+
+        response = get(url)
+        soup = BeautifulSoup(response.text, "html.parser")
+        lyrics_comment = "Usage of azlyrics.com content by any third-party lyrics provider is prohibited by our licensing agreement. Sorry about that."
+        lyrics_el = get_element_by_comment(soup, lyrics_comment)
+        return lyrics_el.text if lyrics_el else ""
+
+    def scrape_spotify_playlist(self, url: str) -> ScrapedResult:
+        if not (search("spotify", url) and search("playlist", url)):
+            raise TypeError("Please provide a valid Spotify playlist url")
+
+        logger.debug("Scraping spotify playlist")
+
+        response = get(url)
+        soup = BeautifulSoup(response.text, "html.parser")
+
+        tracklist_rows = soup.find_all(attrs={"data-encore-id": "listRowTitle"})
+
+        cover_container = soup.find(attrs={"data-testid": "entity-image"})
+        title_container = soup.find(attrs={"data-encore-id": "text"})
+
+        # Cover
+        cover_image: str = ""
+        if cover_container:
+            img_tag = cover_container.find("img")
+            if isinstance(img_tag, Tag):
+                cover_image = img_tag.get("src", "")
+
+        # Title
+        playlist_title: str = ""
+        if isinstance(title_container, Tag):
+            playlist_title = title_container.get_text(strip=True)
+
+        # Track IDs
+        playlist_ids: list[str] = []
+
+        for tag in tracklist_rows:
+            if isinstance(tag, Tag):
+                id_value = tag.get("id")
+                if isinstance(id_value, str):
+                    match = search(r"spotify:track:([a-zA-Z0-9]+)", id_value)
+                    if match:
+                        playlist_ids.append(match.group(1))
+
+        return ScrapedResult(ids=playlist_ids, cover=cover_image, name=playlist_title)

spots_cli/core/youtube_extractor.py

@@ -0,0 +1,162 @@
+from html import unescape
+from unicodedata import normalize
+from re import compile, escape, IGNORECASE, search, sub, split
+
+from spots_cli.models.yt_video_info import YTVideoInfo
+from spots_cli.models.metadata import Metadata
+from spots_cli.models.helper_models import ArtistAndTitle
+
+
+class YouTubeExtractor:
+    """A service for extracting data from a YouTubeVideoInfo"""
+
+    @staticmethod
+    def remove_odd_keywords(title: str, keywords_list: list[str] = []) -> str:
+        defined_keywords = [
+            " (Live Session) | Vevo Ctrl",
+            " [Official Audio]",
+            " (Audio Visual)",
+            " | Official Audio",
+            " | Official",
+            " (Official Audio)",
+            " (Official Video)",
+            " (Audio)",
+            " Uncut [HD]",
+            " [Video]",
+            " (HD)",
+            " (Official Music Video)",
+            " [Official Music Video]",
+            " - Topic",
+            " (Official Visualizer)",
+            " (Complete)",
+            " (Visualizer)",
+            " [Official Lyrics Video]",
+            " (Lyric Video)",
+            " (Lyrics)",
+            " (Official HD Video)",
+            " (Audio Oficial)",
+            " Official Music Video",
+            " [Official Video]",
+            " - Official Video",
+            " (Original Video)",
+            "(LYRICS+PICTURES)",
+            " [Lyrics]",
+            " HQ",
+            " - Audio",
+            " (Album Version)",
+            " (Clean Version)",
+        ]
+
+        title = title.replace("(with", "(feat.")
+
+        odd_keywords = (
+            defined_keywords + keywords_list
+            if all(isinstance(k, str) for k in keywords_list)
+            else defined_keywords
+        )
+
+        pattern = compile("|".join(escape(k) for k in odd_keywords), flags=IGNORECASE)
+        return pattern.sub("", title).strip()
+
+    @staticmethod
+    def normalize_special_chars(text: str) -> str:
+        return (
+            normalize("NFKD", text)
+            .encode("ascii", "ignore")
+            .decode("ascii")
+            .lower()
+            .replace("–", "-")
+            .strip()
+        )
+
+    def extract_artist_and_title(
+        self, *, video_info: YTVideoInfo, metadata: Metadata
+    ) -> ArtistAndTitle:
+        """Extracts the title and artist from a YouTube search result.
+
+        Args:
+            video_info (YTVideoInfo): The search result object to be processed.
+
+        Returns:
+            ArtistAndTitle: The extracted title and artist.
+        """
+        # Decode the string
+        try:
+            video_title = unescape(video_info.title)
+        except TypeError:
+            video_title = video_info.title
+
+        # normalize tokens
+        normalized_yt_artist = self.normalize_special_chars(video_info.uploader)
+        normalized_yt_title = self.normalize_special_chars(video_title)
+        normalized_sp_artist = self.normalize_special_chars(metadata.artist)
+
+        title_parts = split(r"\s*[-|:•]\s*|\s{2,}", normalized_yt_title, maxsplit=1)
+
+        ARTIST_CANDIDATES = [normalized_yt_artist.strip()] + title_parts
+
+        def recursive_artist_search(pattern: str, index: int):
+            if search(escape(pattern), normalized_sp_artist, flags=IGNORECASE):
+                return pattern, index
+            if index == (len(ARTIST_CANDIDATES) - 1):
+                return video_info.uploader, 0
+            next_index = index + 1
+            return recursive_artist_search(ARTIST_CANDIDATES[next_index], next_index)
+
+        _, uploader_index = recursive_artist_search(ARTIST_CANDIDATES[0], 0)
+
+        match uploader_index:
+            case 0:
+                # artist is uploader
+                youtube_artist, youtube_title = video_info.uploader, video_title
+
+                # check for artist repeat in title
+                if normalized_yt_artist in normalized_yt_title:
+                    artist_pattern = compile(rf"{youtube_artist}\W?", flags=IGNORECASE)
+                    youtube_title = sub(artist_pattern, "", video_title)
+
+                    # strip title
+                    youtube_title = sub(r"\W", "", youtube_title, count=1)
+                    youtube_title = youtube_title
+            case 1:
+                # different uploader, artist in title
+                pattern = rf"{escape(metadata.artist)}\W"
+                pattern_match = search(pattern, video_title)
+
+                if pattern_match:
+                    # strip artist
+                    youtube_artist = pattern_match.group(0)
+                    rev_artist = youtube_artist[::-1]
+                    youtube_artist = sub(r"\W", "", rev_artist, count=1)
+                    youtube_artist = youtube_artist[::-1]
+
+                    # strip title
+                    youtube_title = video_title[pattern_match.end() :]
+                    youtube_title = sub(r"\W", "", youtube_title, count=1)
+                else:
+                    youtube_artist, youtube_title = video_info.uploader, video_title
+            case _:
+                # different uploader, artist and title reversed
+                pattern = rf"\W{escape(self.normalize_special_chars(metadata.artist))}"
+                pattern_match = search(pattern, video_title, flags=IGNORECASE)
+
+                if pattern_match:
+                    # strip artist
+                    youtube_artist = pattern_match.group(0)
+                    youtube_artist = sub(r"\W", "", youtube_artist, count=1)
+
+                    # strip title
+                    youtube_title = video_title[: pattern_match.start()]
+                    rev_title = youtube_title[::-1]
+                    youtube_title = sub(r"\W", "", rev_title, count=1)
+                    youtube_title = youtube_title[::-1]
+                else:
+                    youtube_artist, youtube_title = video_info.uploader, video_title
+
+        youtube_title = youtube_title.rstrip(" |–-")
+        youtube_title = self.remove_odd_keywords(youtube_title)
+        youtube_artist = self.remove_odd_keywords(youtube_artist)
+
+        return ArtistAndTitle(
+            artist=youtube_artist.strip(), title=youtube_title.strip()
+        )

spots_cli/engine/__init__.py

@@ -0,0 +1,3 @@
+from spots_cli.engine.file_storage import FileStorage
+from spots_cli.engine.persistence_model import storage
+from spots_cli.engine.retry import retry