stashify-cli 1.3.0__tar.gz → 1.4.0__tar.gz

{stashify_cli-1.3.0 → stashify_cli-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stashify-cli
-Version: 1.3.0
+Version: 1.4.0
 Summary: Find music from your Spotify library on YouTube and save it locally with cover art, lyrics and full metadata.
 Author: Nicolas Dwi Dharma
 License-Expression: MIT
@@ -258,6 +258,7 @@ stashify download "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M"
 - Change the output folder with `-o "D:\Music"` and the naming scheme with `-t "{album}/{track_number} {title}"`
 - Download up to 8 tracks at once with `--jobs 4` (default 2)
 - Skip cover art or lyrics with `--no-cover` / `--no-lyrics`, or re-fetch everything with `--overwrite`
+- Check the whole stack with `stashify doctor` when a download fails; it reports Python, FFmpeg, network access to Spotify, YouTube and the lyrics API
 - Preview the match without downloading with `--dry-run`
 - Keep a folder in sync with a playlist: `stashify sync "PLAYLIST_URL" -o "D:\Music\MyList"`
 - Retag files you already have: `stashify meta file1.mp3 file2.mp3 --url "ALBUM_URL"`
@@ -303,7 +304,7 @@ Stashify is online only when it resolves metadata, searches for a source or fetc
 | Track, album, playlist and artist metadata | Spotify's public embed pages (default) or the Spotify Web API (`--provider api`) |
 | Cover art | Spotify image CDN (embedded into files) |
 | Audio source | YouTube, through yt-dlp |
-| Lyrics | lyrics.ovh (no key required) |
+| Lyrics | lrclib.net (no key required), lyrics.ovh as fallback |
 
 > [!NOTE]
 > Some tracks have no usable match on YouTube. Stashify reports the best candidate it found and skips tracks whose score is too low instead of downloading the wrong song.
@@ -319,6 +320,7 @@ stashify/
 │       ├── __init__.py           # package version
 │       ├── __main__.py           # python -m stashify entry point
 │       ├── cli.py                # argument parsing and commands
+│       ├── doctor.py             # end-to-end stack health check
 │       ├── pipeline.py           # shared download pipeline
 │       ├── spotify.py            # Spotify Web API client (optional, --provider api)
 │       ├── embed.py              # public embed page resolver (default provider)
@@ -326,7 +328,7 @@ stashify/
 │       ├── sources.py            # YouTube search and scoring
 │       ├── download.py           # yt-dlp download and FFmpeg conversion
 │       ├── tagger.py             # MP3, M4A, FLAC, Opus and WAV tagging
-│       ├── lyrics.py             # lyrics.ovh client
+│       ├── lyrics.py             # lrclib.net client (lyrics.ovh fallback)
 │       ├── output.py             # path templates and file naming
 │       ├── sync.py               # playlist sync state handling
 │       ├── config.py             # config file loading
@@ -413,6 +415,13 @@ Lint rules are enforced through the `[tool.ruff]` section in `pyproject.toml`.
 
 ## FAQ
 
+<details>
+<summary><b>Something fails; how do I diagnose it?</b></summary>
+
+Run `stashify doctor`. It checks Python, FFmpeg, the downloads folder, Spotify's embed pages, YouTube search and the lyrics API, and tells you exactly which part works and which does not.
+
+</details>
+
 <details>
 <summary><b>Do I need a Spotify account, login or developer app?</b></summary>
 
@@ -479,7 +488,7 @@ Yes. `stashify sync "PLAYLIST_URL" -o "D:\Music\MyList"` downloads new tracks an
 
 ## Disclaimer
 
-Stashify is an independent open-source project and is not affiliated with or endorsed by Spotify, Google, YouTube or the operators of lyrics.ovh. The default provider parses Spotify's public embed pages; this is not a documented API and can change or break at any time. Downloading music may violate the terms of service of those platforms and may infringe copyright in your jurisdiction. Stashify is provided for personal, lawful use only; you are responsible for how you use it.
+Stashify is an independent open-source project and is not affiliated with or endorsed by Spotify, Google, YouTube, lrclib or the operators of lyrics.ovh. The default provider parses Spotify's public embed pages; this is not a documented API and can change or break at any time. Downloading music may violate the terms of service of those platforms and may infringe copyright in your jurisdiction. Stashify is provided for personal, lawful use only; you are responsible for how you use it.
 
 ---
 

{stashify_cli-1.3.0 → stashify_cli-1.4.0}/README.md

@@ -224,6 +224,7 @@ stashify download "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M"
 - Change the output folder with `-o "D:\Music"` and the naming scheme with `-t "{album}/{track_number} {title}"`
 - Download up to 8 tracks at once with `--jobs 4` (default 2)
 - Skip cover art or lyrics with `--no-cover` / `--no-lyrics`, or re-fetch everything with `--overwrite`
+- Check the whole stack with `stashify doctor` when a download fails; it reports Python, FFmpeg, network access to Spotify, YouTube and the lyrics API
 - Preview the match without downloading with `--dry-run`
 - Keep a folder in sync with a playlist: `stashify sync "PLAYLIST_URL" -o "D:\Music\MyList"`
 - Retag files you already have: `stashify meta file1.mp3 file2.mp3 --url "ALBUM_URL"`
@@ -269,7 +270,7 @@ Stashify is online only when it resolves metadata, searches for a source or fetc
 | Track, album, playlist and artist metadata | Spotify's public embed pages (default) or the Spotify Web API (`--provider api`) |
 | Cover art | Spotify image CDN (embedded into files) |
 | Audio source | YouTube, through yt-dlp |
-| Lyrics | lyrics.ovh (no key required) |
+| Lyrics | lrclib.net (no key required), lyrics.ovh as fallback |
 
 > [!NOTE]
 > Some tracks have no usable match on YouTube. Stashify reports the best candidate it found and skips tracks whose score is too low instead of downloading the wrong song.
@@ -285,6 +286,7 @@ stashify/
 │       ├── __init__.py           # package version
 │       ├── __main__.py           # python -m stashify entry point
 │       ├── cli.py                # argument parsing and commands
+│       ├── doctor.py             # end-to-end stack health check
 │       ├── pipeline.py           # shared download pipeline
 │       ├── spotify.py            # Spotify Web API client (optional, --provider api)
 │       ├── embed.py              # public embed page resolver (default provider)
@@ -292,7 +294,7 @@ stashify/
 │       ├── sources.py            # YouTube search and scoring
 │       ├── download.py           # yt-dlp download and FFmpeg conversion
 │       ├── tagger.py             # MP3, M4A, FLAC, Opus and WAV tagging
-│       ├── lyrics.py             # lyrics.ovh client
+│       ├── lyrics.py             # lrclib.net client (lyrics.ovh fallback)
 │       ├── output.py             # path templates and file naming
 │       ├── sync.py               # playlist sync state handling
 │       ├── config.py             # config file loading
@@ -379,6 +381,13 @@ Lint rules are enforced through the `[tool.ruff]` section in `pyproject.toml`.
 
 ## FAQ
 
+<details>
+<summary><b>Something fails; how do I diagnose it?</b></summary>
+
+Run `stashify doctor`. It checks Python, FFmpeg, the downloads folder, Spotify's embed pages, YouTube search and the lyrics API, and tells you exactly which part works and which does not.
+
+</details>
+
 <details>
 <summary><b>Do I need a Spotify account, login or developer app?</b></summary>
 
@@ -445,7 +454,7 @@ Yes. `stashify sync "PLAYLIST_URL" -o "D:\Music\MyList"` downloads new tracks an
 
 ## Disclaimer
 
-Stashify is an independent open-source project and is not affiliated with or endorsed by Spotify, Google, YouTube or the operators of lyrics.ovh. The default provider parses Spotify's public embed pages; this is not a documented API and can change or break at any time. Downloading music may violate the terms of service of those platforms and may infringe copyright in your jurisdiction. Stashify is provided for personal, lawful use only; you are responsible for how you use it.
+Stashify is an independent open-source project and is not affiliated with or endorsed by Spotify, Google, YouTube, lrclib or the operators of lyrics.ovh. The default provider parses Spotify's public embed pages; this is not a documented API and can change or break at any time. Downloading music may violate the terms of service of those platforms and may infringe copyright in your jurisdiction. Stashify is provided for personal, lawful use only; you are responsible for how you use it.
 
 ---
 

{stashify_cli-1.3.0 → stashify_cli-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stashify-cli"
-version = "1.3.0"
+version = "1.4.0"
 description = "Find music from your Spotify library on YouTube and save it locally with cover art, lyrics and full metadata."
 readme = "README.md"
 requires-python = ">=3.10"

{stashify_cli-1.3.0 → stashify_cli-1.4.0}/src/stashify/__init__.py

@@ -1,3 +1,3 @@
 """Stashify: find music from your Spotify library on YouTube and save it locally."""
 
-__version__ = "1.3.0"
+__version__ = "1.4.0"

{stashify_cli-1.3.0 → stashify_cli-1.4.0}/src/stashify/cli.py

@@ -19,6 +19,7 @@ from .config import (
     default_download_dir,
     load_config,
 )
+from .doctor import run_doctor
 from .download import AUDIO_FORMATS
 from .embed import EmbedResolver
 from .errors import StashifyError
@@ -55,7 +56,17 @@ def build_parser() -> argparse.ArgumentParser:
         help="two-letter market code (default: US)",
     )
 
-    output = argparse.ArgumentParser(add_help=False)
+    resolver = argparse.ArgumentParser(add_help=False)
+    resolver.add_argument(
+        "--provider", choices=["embed", "api"], default=None,
+        help="metadata provider (default: embed, no account needed)",
+    )
+    resolver.add_argument(
+        "--no-details", action="store_true", default=None,
+        help="skip per-track detail lookup (faster, fewer cover art files)",
+    )
+
+    output = argparse.ArgumentParser(add_help=False, parents=[resolver])
     output.add_argument(
         "-o", "--output", default=None,
         help="output directory (default: Downloads folder)"
@@ -77,25 +88,17 @@ def build_parser() -> argparse.ArgumentParser:
         help="re-download files that already exist",
     )
     output.add_argument(
-        "--no-cover", action="store_true", default=None,
-        help="do not embed cover art",
+        "--cover", dest="cover", default=None, action=argparse.BooleanOptionalAction,
+        help="embed cover art (default: config or on)",
     )
     output.add_argument(
-        "--no-lyrics", action="store_true", default=None,
-        help="do not embed lyrics",
+        "--lyrics", dest="lyrics", default=None, action=argparse.BooleanOptionalAction,
+        help="embed lyrics (default: config or on)",
     )
     output.add_argument(
         "--dry-run", action="store_true", default=None,
         help="print matches without downloading",
     )
-    output.add_argument(
-        "--provider", choices=["embed", "api"], default=None,
-        help="metadata provider (default: embed, no account needed)",
-    )
-    output.add_argument(
-        "--no-details", action="store_true", default=None,
-        help="skip per-track detail lookup (faster, fewer cover art files)",
-    )
     output.add_argument(
         "--jobs", type=int, default=None, metavar="N",
         help=f"download up to N tracks in parallel (default: {DEFAULT_JOBS}, max 8)",
@@ -122,7 +125,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
 
     p_url = sub.add_parser(
-        "url", parents=[credentials],
+        "url", parents=[credentials, resolver],
         help="print the matched YouTube source URL per track",
     )
     p_url.add_argument("urls", nargs="+", help="Spotify links")
@@ -136,6 +139,8 @@ def build_parser() -> argparse.ArgumentParser:
         "--url", required=True, help="Spotify link whose tracks are applied"
     )
 
+    sub.add_parser("doctor", help="check Python, FFmpeg, network and APIs")
+
     p_sync = sub.add_parser(
         "sync", parents=[credentials, output],
         help="sync a directory with a playlist",
@@ -171,13 +176,25 @@ def _resolver(args: argparse.Namespace):
     provider = getattr(args, "provider", None) or config.get("provider", "embed")
     if provider == "embed":
         no_details = bool(getattr(args, "no_details", False))
-        detailed = False if no_details else bool(config.get("detailed", True))
+        dry_run = bool(getattr(args, "dry_run", False))
+        url_only = getattr(args, "command", None) == "url"
+        skip = no_details or dry_run or url_only
+        detailed = False if skip else bool(config.get("detailed", True))
         return EmbedResolver(detailed=detailed)
     if provider == "api":
         return _client(args)
     raise StashifyError(f"Unknown provider {provider!r}. Choose from: embed, api.")
 
 
+def _pick_flag(cli: bool | None, config_value: bool | None, default: bool) -> bool:
+    """CLI flag wins when given, else config value, else default."""
+    if cli is not None:
+        return cli
+    if config_value is not None:
+        return bool(config_value)
+    return default
+
+
 def _options(args: argparse.Namespace) -> TrackOptions:
     config = load_config()
 
@@ -186,8 +203,12 @@ def _options(args: argparse.Namespace) -> TrackOptions:
             return cli
         return config.get(key, default)
 
-    no_cover = pick(getattr(args, "no_cover", None), "no_cover", False)
-    no_lyrics = pick(getattr(args, "no_lyrics", None), "no_lyrics", False)
+    cli_cover = getattr(args, "cover", None)
+    cover = _pick_flag(cli_cover, not bool(config.get("no_cover", False)), default=True)
+
+    cli_lyrics = getattr(args, "lyrics", None)
+    lyrics = _pick_flag(cli_lyrics, not bool(config.get("no_lyrics", False)), default=True)
+
     return TrackOptions(
         out_dir=Path(
             pick(getattr(args, "output", None), "output_dir", str(default_download_dir()))
@@ -197,8 +218,8 @@ def _options(args: argparse.Namespace) -> TrackOptions:
         bitrate=pick(getattr(args, "bitrate", None), "bitrate", DEFAULT_BITRATE),
         overwrite=bool(pick(getattr(args, "overwrite", None), "overwrite", False)),
         dry_run=bool(pick(getattr(args, "dry_run", None), "dry_run", False)),
-        embed_cover=not no_cover,
-        embed_lyrics=not no_lyrics,
+        embed_cover=cover,
+        embed_lyrics=lyrics,
         jobs=clamp_jobs(pick(getattr(args, "jobs", None), "jobs", DEFAULT_JOBS)),
     )
 
@@ -270,6 +291,11 @@ def _cmd_url(args: argparse.Namespace) -> int:
 
 def _cmd_meta(args: argparse.Namespace) -> int:
     config = load_config()
+    cli_cover = getattr(args, "cover", None)
+    cover = _pick_flag(cli_cover, not bool(config.get("no_cover", False)), default=True)
+    cli_lyrics = getattr(args, "lyrics", None)
+    lyrics = _pick_flag(cli_lyrics, not bool(config.get("no_lyrics", False)), default=True)
+
     tracks = _fetch(args, [args.url])
     files = [Path(f) for f in args.files]
     missing = [f for f in files if not f.is_file()]
@@ -286,8 +312,8 @@ def _cmd_meta(args: argparse.Namespace) -> int:
     failures = 0
     for path, track in zip(files, tracks, strict=False):
         try:
-            cover = fetch_cover(track) if not config.get("no_cover") else None
-            lyrics = fetch_lyrics(track) if not config.get("no_lyrics") else None
+            cover = fetch_cover(track) if cover else None
+            lyrics = fetch_lyrics(track) if lyrics else None
             tag_file(path, track, cover, lyrics)
             print(f"Tagged {path} -> {track.display()}")
         except Exception as exc:
@@ -351,6 +377,7 @@ def main(argv: list[str] | None = None) -> int:
         "url": _cmd_url,
         "meta": _cmd_meta,
         "sync": _cmd_sync,
+        "doctor": lambda args: run_doctor(),
     }
     handler = handlers[args.command]
     try:

stashify_cli-1.4.0/src/stashify/doctor.py

@@ -0,0 +1,139 @@
+"""Check that the whole Stashify stack works end to end.
+
+`stashify doctor` runs quick checks against Python, FFmpeg, the downloads
+folder, Spotify's embed pages, YouTube search and the lyrics API, and prints
+a pass/fail report. Use when a download fails and you want to know exactly
+which part of the stack is broken, without running a full download.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+
+import requests
+
+from .config import default_download_dir
+from .embed import EmbedResolver
+from .lyrics import LRCLIB_URL
+from .lyrics import USER_AGENT as LYRICS_UA
+from .models import Track
+from .sources import find_source
+
+
+def check_python() -> tuple[str, bool, str]:
+    try:
+        import sys
+
+        ok = sys.version_info >= (3, 10)
+        label = "Python 3.10 or newer"
+        return (label, ok, f"Python {sys.version_info.major}.{sys.version_info.minor}")
+    except Exception as exc:
+        return ("Python 3.10 or newer", False, f"failed: {exc}")
+
+
+def check_ffmpeg() -> tuple[str, bool, str]:
+    try:
+        ffmpeg = shutil.which("ffmpeg")
+        path = "FFmpeg on PATH"
+        return (path, bool(ffmpeg), ffmpeg or "not found (https://ffmpeg.org/download.html)")
+    except Exception as exc:
+        return ("FFmpeg on PATH", False, f"failed: {exc}")
+
+
+def check_ffprobe() -> tuple[str, bool, str]:
+    try:
+        ffprobe = shutil.which("ffprobe")
+        path = "ffprobe on PATH"
+        return (path, bool(ffprobe), ffprobe or "not found (comes with FFmpeg)")
+    except Exception as exc:
+        return ("ffprobe on PATH", False, f"failed: {exc}")
+
+
+def check_download_dir() -> tuple[str, bool, str]:
+    try:
+        folder = default_download_dir()
+    except Exception as exc:
+        return ("Downloads folder found", False, f"failed: {exc}")
+    if not folder.exists():
+        return ("Downloads folder exists", False, f"{folder} does not exist")
+    if not folder.is_dir():
+        return ("Downloads folder exists", False, f"{folder} exists but is not a directory")
+    w_ok = os.access(folder, os.W_OK)
+    return (
+        "Downloads folder writable",
+        w_ok,
+        str(folder) if w_ok else f"{folder}: not writable",
+    )
+
+
+def check_spotify_embed() -> tuple[str, bool, str]:
+    try:
+        resolver = EmbedResolver(detailed=False)
+        tracks = resolver.fetch_tracks(
+            "https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC"
+        )
+        if not tracks:
+            return ("Spotify embed pages", False, "embed resolved to no tracks")
+        summary = tracks[0].display() if tracks else ""
+        return ("Spotify embed pages", True, f"resolved: {summary}")
+    except Exception as exc:
+        return ("Spotify embed pages", False, f"failed: {exc}")
+
+
+def check_youtube() -> tuple[str, bool, str]:
+    try:
+        source = find_source(
+            Track(
+                title="Never Gonna Give You Up",
+                artists=["Rick Astley"],
+                duration_ms=213000,
+            )
+        )
+        return ("YouTube search", True, f"matched: {source.title or source.url}")
+    except Exception as exc:
+        return ("YouTube search", False, f"failed: {exc}")
+
+
+def check_lyrics_api() -> tuple[str, bool, str]:
+    try:
+        response = requests.get(
+            LRCLIB_URL,
+            params={"artist_name": "Rick Astley", "track_name": "Never Gonna Give You Up"},
+            timeout=10,
+            headers={"User-Agent": LYRICS_UA},
+        )
+    except requests.RequestException as exc:
+        return ("Lyrics API (lrclib.net)", False, f"failed: {exc}")
+    # 200 = match found, 404 = reachable but requested track not in lrclib.
+    if response.status_code in (200, 404):
+        detail = "reachable" if response.status_code == 200 else "reachable (track not found)"
+        return ("Lyrics API (lrclib.net)", True, detail)
+    return ("Lyrics API (lrclib.net)", False, f"HTTP {response.status_code}")
+
+
+def run_doctor() -> int:
+    checks = [
+        check_python,
+        check_ffmpeg,
+        check_ffprobe,
+        check_download_dir,
+        check_spotify_embed,
+        check_youtube,
+        check_lyrics_api,
+    ]
+    results = [check() for check in checks]
+
+    width = max(len(label) for label, _, _ in results)
+    failures = 0
+    for label, ok, detail in results:
+        failures += 0 if ok else 1
+        mark = "OK  " if ok else "FAIL"
+        print(f"{mark} {label:<{width}}  {detail}")
+
+    print()
+    if failures:
+        print(f"{failures} of {len(results)} checks failed. Fix the items above and try again.")
+        return 1
+    print(f"All {len(results)} checks passed. Stashify is ready to run.")
+    return 0

stashify_cli-1.4.0/src/stashify/lyrics.py

@@ -0,0 +1,79 @@
+"""Fetch plain-text lyrics, lrclib first, community fallback.
+
+Returns None on any failure; lyrics are always optional and must never block
+a download.
+"""
+
+from __future__ import annotations
+
+import requests
+
+from .models import Track
+
+LRCLIB_URL = "https://lrclib.net/api/get"
+OVH_URL = "https://api.lyrics.ovh/v1"
+TIMEOUT = 10
+MAX_LYRICS_BYTES = 256 * 1024
+USER_AGENT = "stashify/1.4 (https://github.com/nekonaru/stashify)"
+
+
+class _Instrumental(Exception):
+    """lrclib confirmed the track is instrumental; use no lyrics at all."""
+
+
+def _fetch_lrclib(track: Track) -> str | None:
+    params = {
+        "artist_name": track.artist,
+        "track_name": track.title,
+    }
+    if track.album:
+        params["album_name"] = track.album
+    if track.duration_ms:
+        params["duration"] = round(track.duration_ms / 1000)
+    try:
+        response = requests.get(
+            LRCLIB_URL, params=params, timeout=TIMEOUT,
+            headers={"User-Agent": USER_AGENT},
+        )
+    except requests.RequestException:
+        return None
+    if response.status_code != 200:
+        return None
+    if len(response.content) > MAX_LYRICS_BYTES:
+        return None
+    try:
+        payload = response.json()
+    except ValueError:
+        return None
+    if isinstance(payload, dict) and payload.get("instrumental"):
+        raise _Instrumental()
+    lyrics = (payload or {}).get("plainLyrics") or ""
+    return lyrics.strip() or None
+
+
+def _fetch_ovh(track: Track) -> str | None:
+    artist = requests.utils.quote(track.artist, safe="")
+    title = requests.utils.quote(track.title, safe="")
+    try:
+        response = requests.get(f"{OVH_URL}/{artist}/{title}", timeout=TIMEOUT)
+    except requests.RequestException:
+        return None
+    if response.status_code != 200:
+        return None
+    if len(response.content) > MAX_LYRICS_BYTES:
+        return None
+    try:
+        lyrics = (response.json() or {}).get("lyrics") or ""
+    except ValueError:
+        return None
+    return lyrics.strip() or None
+
+
+def fetch_lyrics(track: Track) -> str | None:
+    try:
+        lyrics = _fetch_lrclib(track)
+    except _Instrumental:
+        return None
+    if lyrics:
+        return lyrics
+    return _fetch_ovh(track)

{stashify_cli-1.3.0 → stashify_cli-1.4.0}/src/stashify_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stashify-cli
-Version: 1.3.0
+Version: 1.4.0
 Summary: Find music from your Spotify library on YouTube and save it locally with cover art, lyrics and full metadata.
 Author: Nicolas Dwi Dharma
 License-Expression: MIT
@@ -258,6 +258,7 @@ stashify download "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M"
 - Change the output folder with `-o "D:\Music"` and the naming scheme with `-t "{album}/{track_number} {title}"`
 - Download up to 8 tracks at once with `--jobs 4` (default 2)
 - Skip cover art or lyrics with `--no-cover` / `--no-lyrics`, or re-fetch everything with `--overwrite`
+- Check the whole stack with `stashify doctor` when a download fails; it reports Python, FFmpeg, network access to Spotify, YouTube and the lyrics API
 - Preview the match without downloading with `--dry-run`
 - Keep a folder in sync with a playlist: `stashify sync "PLAYLIST_URL" -o "D:\Music\MyList"`
 - Retag files you already have: `stashify meta file1.mp3 file2.mp3 --url "ALBUM_URL"`
@@ -303,7 +304,7 @@ Stashify is online only when it resolves metadata, searches for a source or fetc
 | Track, album, playlist and artist metadata | Spotify's public embed pages (default) or the Spotify Web API (`--provider api`) |
 | Cover art | Spotify image CDN (embedded into files) |
 | Audio source | YouTube, through yt-dlp |
-| Lyrics | lyrics.ovh (no key required) |
+| Lyrics | lrclib.net (no key required), lyrics.ovh as fallback |
 
 > [!NOTE]
 > Some tracks have no usable match on YouTube. Stashify reports the best candidate it found and skips tracks whose score is too low instead of downloading the wrong song.
@@ -319,6 +320,7 @@ stashify/
 │       ├── __init__.py           # package version
 │       ├── __main__.py           # python -m stashify entry point
 │       ├── cli.py                # argument parsing and commands
+│       ├── doctor.py             # end-to-end stack health check
 │       ├── pipeline.py           # shared download pipeline
 │       ├── spotify.py            # Spotify Web API client (optional, --provider api)
 │       ├── embed.py              # public embed page resolver (default provider)
@@ -326,7 +328,7 @@ stashify/
 │       ├── sources.py            # YouTube search and scoring
 │       ├── download.py           # yt-dlp download and FFmpeg conversion
 │       ├── tagger.py             # MP3, M4A, FLAC, Opus and WAV tagging
-│       ├── lyrics.py             # lyrics.ovh client
+│       ├── lyrics.py             # lrclib.net client (lyrics.ovh fallback)
 │       ├── output.py             # path templates and file naming
 │       ├── sync.py               # playlist sync state handling
 │       ├── config.py             # config file loading
@@ -413,6 +415,13 @@ Lint rules are enforced through the `[tool.ruff]` section in `pyproject.toml`.
 
 ## FAQ
 
+<details>
+<summary><b>Something fails; how do I diagnose it?</b></summary>
+
+Run `stashify doctor`. It checks Python, FFmpeg, the downloads folder, Spotify's embed pages, YouTube search and the lyrics API, and tells you exactly which part works and which does not.
+
+</details>
+
 <details>
 <summary><b>Do I need a Spotify account, login or developer app?</b></summary>
 
@@ -479,7 +488,7 @@ Yes. `stashify sync "PLAYLIST_URL" -o "D:\Music\MyList"` downloads new tracks an
 
 ## Disclaimer
 
-Stashify is an independent open-source project and is not affiliated with or endorsed by Spotify, Google, YouTube or the operators of lyrics.ovh. The default provider parses Spotify's public embed pages; this is not a documented API and can change or break at any time. Downloading music may violate the terms of service of those platforms and may infringe copyright in your jurisdiction. Stashify is provided for personal, lawful use only; you are responsible for how you use it.
+Stashify is an independent open-source project and is not affiliated with or endorsed by Spotify, Google, YouTube, lrclib or the operators of lyrics.ovh. The default provider parses Spotify's public embed pages; this is not a documented API and can change or break at any time. Downloading music may violate the terms of service of those platforms and may infringe copyright in your jurisdiction. Stashify is provided for personal, lawful use only; you are responsible for how you use it.
 
 ---
 

{stashify_cli-1.3.0 → stashify_cli-1.4.0}/src/stashify_cli.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ src/stashify/__init__.py
 src/stashify/__main__.py
 src/stashify/cli.py
 src/stashify/config.py
+src/stashify/doctor.py
 src/stashify/download.py
 src/stashify/embed.py
 src/stashify/errors.py
@@ -24,8 +25,10 @@ src/stashify_cli.egg-info/requires.txt
 src/stashify_cli.egg-info/top_level.txt
 tests/test_cli.py
 tests/test_config.py
+tests/test_doctor.py
 tests/test_download.py
 tests/test_embed.py
+tests/test_lyrics.py
 tests/test_models.py
 tests/test_output.py
 tests/test_pipeline.py

{stashify_cli-1.3.0 → stashify_cli-1.4.0}/tests/test_cli.py

@@ -49,6 +49,41 @@ def test_meta_api_without_credentials(monkeypatch, capsys):
     assert code == 1
 
 
+def test_dry_run_skips_detail_lookups(monkeypatch, capsys):
+    recorded = []
+
+    class FakeResolver:
+        def __init__(self, detailed=True, timeout=20):
+            recorded.append(detailed)
+
+        def fetch_tracks(self, url):
+            return []
+
+    monkeypatch.setattr("stashify.cli.EmbedResolver", FakeResolver)
+    main(["url", "https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC"])
+    main(["download", "https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC", "--dry-run"])
+    main(["save", "https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC"])
+    assert recorded == [False, False, True]
+
+
+def test_no_cover_flag_forces_off(monkeypatch, tmp_path, capsys):
+    """The --no-cover CLI flag is available and maps to --cover=false."""
+    import argparse
+
+    from stashify.cli import _options
+
+    monkeypatch.setenv("STASHIFY_DOWNLOAD_DIR", str(tmp_path))
+    monkeypatch.setattr("stashify.cli.load_config", lambda *a, **k: {})
+    base = dict(
+        output=None, template=None, audio_format=None, bitrate=None,
+        overwrite=None, dry_run=None, cover=False, lyrics=None, jobs=None,
+        provider=None, detailed=None,
+    )
+    options = _options(argparse.Namespace(**base))
+    assert options.embed_cover is False
+    assert options.embed_lyrics is True
+
+
 def test_url_output_order_preserved(monkeypatch, capsys):
     from stashify.models import Track
     from stashify.sources import Source

stashify_cli-1.4.0/tests/test_doctor.py

@@ -0,0 +1,46 @@
+from stashify import doctor
+
+
+def test_doctor_all_pass(monkeypatch, capsys):
+    monkeypatch.setattr(doctor, "check_python", lambda: ("py", True, "ok"))
+    monkeypatch.setattr(doctor, "check_ffmpeg", lambda: ("ffmpeg", True, "ok"))
+    monkeypatch.setattr(doctor, "check_ffprobe", lambda: ("ffprobe", True, "ok"))
+    monkeypatch.setattr(doctor, "check_download_dir", lambda: ("dir", True, "ok"))
+    monkeypatch.setattr(doctor, "check_spotify_embed", lambda: ("embed", True, "ok"))
+    monkeypatch.setattr(doctor, "check_youtube", lambda: ("yt", True, "ok"))
+    monkeypatch.setattr(doctor, "check_lyrics_api", lambda: ("lyrics", True, "ok"))
+    assert doctor.run_doctor() == 0
+    out = capsys.readouterr().out
+    assert "All 7 checks passed" in out
+
+
+def test_download_dir_missing(monkeypatch, tmp_path):
+    monkeypatch.setattr(
+        "stashify.doctor.default_download_dir", lambda: tmp_path / "nope"
+    )
+    _, ok, detail = doctor.check_download_dir()
+    assert ok is False
+    assert "does not exist" in detail
+
+
+def test_lyrics_api_404_is_up(monkeypatch):
+    class Resp:
+        status_code = 404
+
+    monkeypatch.setattr(doctor.requests, "get", lambda *a, **k: Resp())
+    _, ok, detail = doctor.check_lyrics_api()
+    assert ok is True
+    assert "not found" in detail
+
+
+def test_doctor_reports_failures(monkeypatch, capsys):
+    monkeypatch.setattr(doctor, "check_python", lambda: ("py", True, "ok"))
+    monkeypatch.setattr(doctor, "check_ffmpeg", lambda: ("ffmpeg", False, "missing"))
+    monkeypatch.setattr(doctor, "check_ffprobe", lambda: ("ffprobe", True, "ok"))
+    monkeypatch.setattr(doctor, "check_download_dir", lambda: ("dir", False, "read-only"))
+    monkeypatch.setattr(doctor, "check_spotify_embed", lambda: ("embed", True, "ok"))
+    monkeypatch.setattr(doctor, "check_youtube", lambda: ("yt", False, "bot check"))
+    monkeypatch.setattr(doctor, "check_lyrics_api", lambda: ("lyrics", True, "ok"))
+    assert doctor.run_doctor() == 1
+    out = capsys.readouterr().out
+    assert "3 of 7 checks failed" in out

stashify_cli-1.4.0/tests/test_lyrics.py

@@ -0,0 +1,84 @@
+import requests  # noqa: F401  (requests.exceptions used via monkeypatch)
+
+from stashify import lyrics
+from stashify.models import Track
+
+
+def _track():
+    return Track(
+        title="Never Gonna Give You Up",
+        artists=["Rick Astley"],
+        album="Whenever You Need Somebody",
+        duration_ms=213573,
+    )
+
+
+def test_lrclib_success(monkeypatch):
+    def fake_get(url, params=None, timeout=None, headers=None):
+        class Resp:
+            status_code = 200
+            content = b'{"plainLyrics": "Never gonna give you up"}'
+            def json(self):
+                return {"plainLyrics": "We're no strangers to love"}
+
+        assert "lrclib.net" in url
+        assert params["artist_name"] == "Rick Astley"
+        return Resp()
+
+    monkeypatch.setattr(lyrics.requests, "get", fake_get)
+    assert lyrics.fetch_lyrics(_track()) == "We're no strangers to love"
+
+
+def test_lrclib_404_falls_back_to_ovh(monkeypatch):
+    calls = {}
+
+    def fake_get(url, params=None, timeout=None, headers=None):
+        class Resp:
+            def __init__(self, status, body):
+                self.status_code = status
+                self.content = body
+            def json(self):
+                return {"lyrics": "fallback lyrics"}
+
+        calls["count"] = calls.get("count", 0) + 1
+        if "lrclib.net" in url:
+            return Resp(404, b"Not Found")
+        calls["ovh"] = True
+        return Resp(200, b'{"lyrics": "fallback lyrics"}')
+
+    monkeypatch.setattr(lyrics.requests, "get", fake_get)
+    assert lyrics.fetch_lyrics(_track()) == "fallback lyrics"
+    assert calls["ovh"] is True
+
+
+def test_lrclib_error_returns_fallback_none(monkeypatch):
+    def fake_get(url, params=None, timeout=None, headers=None):
+        class Resp:
+            status_code = 500
+            content = b"server error"
+            def json(self):
+                raise ValueError("bad json")
+
+        return Resp()
+
+    monkeypatch.setattr(lyrics.requests, "get", fake_get)
+    assert lyrics.fetch_lyrics(_track()) is None
+
+
+def test_lrclib_instrumental_does_not_fall_back(monkeypatch):
+    calls = {}
+
+    def fake_get(url, params=None, timeout=None, headers=None):
+        class Resp:
+            status_code = 200
+            content = b'{"instrumental": true}'
+
+            def json(self):
+                return {"instrumental": True}
+
+        calls["count"] = calls.get("count", 0) + 1
+        return Resp()
+
+    monkeypatch.setattr(lyrics.requests, "get", fake_get)
+    assert lyrics.fetch_lyrics(_track()) is None
+    assert calls["count"] == 1

stashify_cli-1.3.0/src/stashify/lyrics.py

@@ -1,36 +0,0 @@
-"""Fetch plain-text lyrics from a free community lyrics API.
-
-Returns None on any failure; lyrics are always optional and must never block
-a download.
-"""
-
-from __future__ import annotations
-
-import requests
-
-from .models import Track
-
-API_URL = "https://api.lyrics.ovh/v1"
-TIMEOUT = 10
-MAX_LYRICS_BYTES = 64 * 1024
-
-
-def fetch_lyrics(track: Track) -> str | None:
-    artist = requests.utils.quote(track.artist, safe="")
-    title = requests.utils.quote(track.title, safe="")
-    try:
-        response = requests.get(
-            f"{API_URL}/{artist}/{title}", timeout=TIMEOUT
-        )
-    except requests.RequestException:
-        return None
-    if response.status_code != 200:
-        return None
-    if len(response.content) > MAX_LYRICS_BYTES:
-        return None
-    try:
-        lyrics = (response.json() or {}).get("lyrics") or ""
-    except ValueError:
-        return None
-    lyrics = lyrics.strip()
-    return lyrics or None