flacfetch 0.34.0__tar.gz → 0.35.0__tar.gz

{flacfetch-0.34.0/flacfetch.egg-info → flacfetch-0.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flacfetch
-Version: 0.34.0
+Version: 0.35.0
 Summary: Search and download high-quality audio from multiple sources
 Home-page: https://github.com/yourusername/flacfetch
 Author: Your Name

{flacfetch-0.34.0 → flacfetch-0.35.0}/flacfetch/api/main.py

@@ -33,6 +33,7 @@ from .routes import (
     download_router,
     health_router,
     search_router,
+    spotify_router,
     torrents_router,
 )
 from .services import get_disk_manager, get_download_manager, get_search_cache_service, set_server_started_at
@@ -167,6 +168,7 @@ def create_app() -> FastAPI:
     app.include_router(config_router)
     app.include_router(credentials_router)
     app.include_router(cache_router)
+    app.include_router(spotify_router)
 
     return app
 

{flacfetch-0.34.0 → flacfetch-0.35.0}/flacfetch/api/models.py

@@ -7,6 +7,7 @@ from typing import (
     Any,
     Dict,
     List,
+    Literal,
     Optional,
 )
 
@@ -158,6 +159,32 @@ class DownloadByIdRequest(BaseModel):
         description="Torrents only: abort after this many seconds with no progress "
                     "(overrides FLACFETCH_MAX_STALL_SECONDS; capped at 3600).",
     )
+    priority: Literal["interactive", "batch"] = Field(
+        "interactive",
+        description="Spotify only. 'batch' downloads are gated by the rolling listening budget "
+                    "(429 with Retry-After when refused); 'interactive' are never refused.",
+    )
+    expected_duration_s: Optional[int] = Field(
+        None, gt=0, le=1200,
+        description="Spotify: expected track length in seconds. Required for priority='batch'.",
+    )
+    delete_local_after_upload: bool = Field(
+        False,
+        description="Delete the local file after a successful GCS upload (always on for batch).",
+    )
+
+
+class SpotifyBudgetResponse(BaseModel):
+    """Rolling-window Spotify listening usage."""
+    window_s: int
+    total_s: float
+    batch_s: float
+    batch_budget_s: int
+    hard_cap_s: int
+    batch_in_flight: int
+    interactive_in_flight: int
+    batch_allowed_now: bool
+    retry_after_s: int
 
 
 class DownloadStatus(str, Enum):

{flacfetch-0.34.0 → flacfetch-0.35.0}/flacfetch/api/routes/__init__.py

@@ -7,6 +7,7 @@ from .credentials import router as credentials_router
 from .download import router as download_router
 from .health import router as health_router
 from .search import router as search_router
+from .spotify import router as spotify_router
 from .torrents import router as torrents_router
 
 __all__ = [
@@ -17,5 +18,6 @@ __all__ = [
     "config_router",
     "credentials_router",
     "cache_router",
+    "spotify_router",
 ]
 

{flacfetch-0.34.0 → flacfetch-0.35.0}/flacfetch/api/routes/download.py

@@ -5,7 +5,7 @@ import logging
 import os
 
 from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
-from fastapi.responses import FileResponse
+from fastapi.responses import FileResponse, JSONResponse
 
 from ..auth import verify_api_key
 from ..models import (
@@ -18,6 +18,7 @@ from ..models import (
     DownloadStatusResponse,
 )
 from ..services import get_download_manager
+from ..services.spotify_budget import DEFAULT_INTERACTIVE_RESERVE_S, BudgetConfig, get_spotify_ledger
 
 logger = logging.getLogger(__name__)
 router = APIRouter(tags=["download"])
@@ -110,6 +111,11 @@ async def start_download_by_id(
     - download_url: For YouTube/Spotify, the direct URL (optional, constructed from source_id if missing).
       REQUIRED for source_name='URL' (any yt-dlp-supported site, e.g. Facebook, SoundCloud, TikTok).
 
+    - priority / expected_duration_s (Spotify): 'batch' downloads need expected_duration_s and are
+      refused with 429 {"detail": {"code", "retry_after_s"}} + Retry-After when the rolling Spotify
+      listening budget is exhausted or the batch gate is closed. 'interactive' is never refused.
+    - delete_local_after_upload: delete the local file after a successful GCS upload (always for batch).
+
     The download runs in the background. Use GET /download/{download_id}/status to check progress.
     """
     manager = get_download_manager()
@@ -137,6 +143,14 @@ async def start_download_by_id(
             detail="gcs_path is required when upload_to_gcs is true"
         )
 
+    is_spotify = request.source_name == "Spotify"
+    is_batch = is_spotify and request.priority == "batch"
+    if is_batch and not request.expected_duration_s:
+        raise HTTPException(
+            status_code=400,
+            detail="expected_duration_s is required for Spotify downloads with priority='batch'"
+        )
+
     logger.info(
         f"Download by ID requested: source={request.source_name}, "
         f"id={request.source_id}, target_file={request.target_file}"
@@ -152,8 +166,43 @@ async def start_download_by_id(
         upload_to_gcs=request.upload_to_gcs,
         gcs_destination=request.gcs_path,
         max_stall_seconds=request.max_stall_seconds,
+        delete_local_after_upload=request.delete_local_after_upload or is_batch,
     )
 
+    if is_spotify:
+        try:
+            ledger = get_spotify_ledger()
+            if is_batch:
+                ok, code, retry_after = ledger.try_reserve_batch(
+                    task.download_id, request.expected_duration_s, BudgetConfig.from_env()
+                )
+                if not ok:
+                    manager.discard_download(task.download_id)
+                    logger.warning(f"Spotify batch download refused: {code} (retry in {retry_after}s)")
+                    return JSONResponse(
+                        status_code=429,
+                        content={"detail": {"code": code, "retry_after_s": retry_after}},
+                        headers={"Retry-After": str(retry_after)},
+                    )
+            else:
+                ledger.reserve(
+                    task.download_id, "interactive",
+                    request.expected_duration_s or DEFAULT_INTERACTIVE_RESERVE_S,
+                )
+            task.spotify_reserved = True
+        except Exception as e:
+            if not is_batch:
+                # Interactive downloads are never refused: fail open, uncounted.
+                logger.warning(f"Spotify ledger unavailable; interactive download proceeds uncounted: {e}")
+            else:
+                manager.discard_download(task.download_id)
+                logger.warning(f"Spotify ledger unavailable; refusing batch download: {e}")
+                return JSONResponse(
+                    status_code=503,
+                    content={"detail": {"code": "budget_unavailable", "retry_after_s": 60}},
+                    headers={"Retry-After": "60"},
+                )
+
     logger.info(f"Created download-by-id task: {task.download_id} for {task.provider} ID={task.source_id}")
 
     # Start download in background

flacfetch-0.35.0/flacfetch/api/routes/spotify.py

@@ -0,0 +1,48 @@
+"""
+Spotify listening-budget endpoint.
+"""
+import logging
+import time
+
+from fastapi import APIRouter, Depends
+from fastapi.responses import JSONResponse
+
+from ..auth import verify_api_key
+from ..models import SpotifyBudgetResponse
+from ..services.spotify_budget import (
+    PROBE_BATCH_SECONDS,
+    BudgetConfig,
+    check_batch,
+    get_spotify_ledger,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["spotify"])
+
+
+@router.get("/spotify/budget", response_model=SpotifyBudgetResponse)
+async def get_spotify_budget(api_key: str = Depends(verify_api_key)) -> SpotifyBudgetResponse:
+    """Rolling-window Spotify listening usage and whether a batch download may start now."""
+    cfg = BudgetConfig.from_env()
+    now = time.time()
+    try:
+        usage = get_spotify_ledger().usage(now, cfg.window_s)
+    except Exception as e:
+        logger.warning(f"Spotify ledger unavailable for /spotify/budget: {e}")
+        return JSONResponse(
+            status_code=503,
+            content={"detail": {"code": "budget_unavailable", "retry_after_s": 60}},
+            headers={"Retry-After": "60"},
+        )
+    ok, _code, retry = check_batch(usage, PROBE_BATCH_SECONDS, cfg, now)
+    return SpotifyBudgetResponse(
+        window_s=cfg.window_s,
+        total_s=usage.total_s,
+        batch_s=usage.batch_s,
+        batch_budget_s=cfg.batch_budget_s,
+        hard_cap_s=cfg.hard_cap_s,
+        batch_in_flight=usage.batch_in_flight,
+        interactive_in_flight=usage.interactive_in_flight,
+        batch_allowed_now=ok,
+        retry_after_s=retry,
+    )

{flacfetch-0.34.0 → flacfetch-0.35.0}/flacfetch/api/services/download_manager.py

@@ -15,6 +15,7 @@ from typing import Any, Dict, List, Optional
 
 from ...downloaders.torrent import TorrentStalledError
 from ..models import DownloadStatus
+from .spotify_budget import get_spotify_ledger
 
 logger = logging.getLogger(__name__)
 
@@ -49,6 +50,8 @@ class DownloadTask:
     target_file: Optional[str] = None
     download_url: Optional[str] = None
     max_stall_seconds: Optional[float] = None  # torrents: per-request stall ceiling
+    delete_local_after_upload: bool = False
+    spotify_reserved: bool = False  # a Spotify budget ledger entry exists for this task
 
 
 @dataclass
@@ -477,6 +480,7 @@ class DownloadManager:
         upload_to_gcs: bool = False,
         gcs_destination: Optional[str] = None,
         max_stall_seconds: Optional[float] = None,
+        delete_local_after_upload: bool = False,
     ) -> DownloadTask:
         """
         Create a download task for direct download by source ID (no search required).
@@ -496,6 +500,7 @@ class DownloadManager:
             upload_to_gcs=upload_to_gcs,
             gcs_destination=gcs_destination,
             max_stall_seconds=max_stall_seconds,
+            delete_local_after_upload=delete_local_after_upload,
             started_at=datetime.now(timezone.utc),
         )
 
@@ -504,6 +509,35 @@ class DownloadManager:
 
         return task
 
+    def discard_download(self, download_id: str) -> None:
+        """Forget a task that was created but never started (e.g. refused by the budget)."""
+        with self._lock:
+            self._downloads.pop(download_id, None)
+
+    def _settle_spotify(self, task: DownloadTask, captured_s: Optional[float]) -> None:
+        """Close out the task's Spotify ledger entry (settle with captured audio, else release)."""
+        if not task.spotify_reserved:
+            return
+        task.spotify_reserved = False
+        try:
+            ledger = get_spotify_ledger()
+            if captured_s is None or captured_s > 0:
+                ledger.settle(task.download_id, captured_s)
+            else:
+                ledger.release(task.download_id)
+        except Exception as e:
+            logger.warning(f"Could not update Spotify ledger for {task.download_id}: {e}")
+
+    def _delete_local_file(self, path: str) -> None:
+        """Remove an uploaded file and its parent dir if that is now empty (never download_dir)."""
+        try:
+            os.unlink(path)
+            parent = os.path.dirname(path)
+            if os.path.abspath(parent) != os.path.abspath(self.download_dir) and not os.listdir(parent):
+                os.rmdir(parent)
+        except OSError as e:
+            logger.warning(f"Could not delete local file after upload {path}: {e}")
+
     async def execute_download_by_id(self, download_id: str) -> None:
         """
         Execute a download-by-id task (runs in background).
@@ -527,12 +561,17 @@ class DownloadManager:
             # Execute download in a thread to avoid blocking the event loop
             manager = self._get_fetch_manager()
             loop = asyncio.get_running_loop()
+            # Never delete seeding torrent data; the flag only applies to non-torrent sources.
+            delete_after_upload = task.delete_local_after_upload and task.provider not in ("RED", "OPS")
+            # Concurrent downloads with the same output_filename must not share a file:
+            # use a per-task directory when the file is deleted after upload.
+            out_dir = os.path.join(self.download_dir, task.download_id) if delete_after_upload else self.download_dir
             output_path = await loop.run_in_executor(
                 None,
                 lambda: manager.download_by_id(
                     source_name=task.provider,
                     source_id=task.source_id,
-                    output_path=self.download_dir,
+                    output_path=out_dir,
                     output_filename=task.output_filename,
                     target_file=task.target_file,
                     download_url=task.download_url,
@@ -547,6 +586,7 @@ class DownloadManager:
             )
 
             logger.info(f"Download complete: {output_path}")
+            self._settle_spotify(task, getattr(output_path, "captured_s", None))
 
             # Upload to GCS if requested
             if task.upload_to_gcs and task.gcs_destination:
@@ -554,6 +594,8 @@ class DownloadManager:
                 gcs_path = await self._upload_to_gcs(output_path, task.gcs_destination)
                 self.update_download(download_id, gcs_path=gcs_path)
                 logger.info(f"Uploaded to GCS: {gcs_path}")
+                if delete_after_upload:
+                    self._delete_local_file(output_path)
 
             # Final status depends on whether it's a torrent (seeding) or not
             if task.provider in ["RED", "OPS"] and self.keep_seeding:
@@ -565,6 +607,7 @@ class DownloadManager:
 
         except Exception as e:
             logger.error(f"Download by ID failed: {e}", exc_info=True)
+            self._settle_spotify(task, getattr(e, "captured_s", 0.0))
             self.update_download(
                 download_id,
                 status=DownloadStatus.FAILED,

flacfetch-0.35.0/flacfetch/api/services/spotify_budget.py

@@ -0,0 +1,274 @@
+"""
+Spotify listening budget for the flacfetch HTTP API.
+
+Spotify Premium accounts must not "listen" to more than 24 h of audio per
+rolling 24 h. Every Spotify download made through the API is recorded in a
+small SQLite ledger (survives restarts). Batch (background, bulk) downloads
+are gated against the ledger; interactive downloads are never refused, only
+counted.
+"""
+import logging
+import math
+import os
+import sqlite3
+import threading
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Callable, Iterator, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+# Reserved entries older than this are assumed to have crashed mid-flight and
+# are counted at their reserved length.
+STALE_RESERVED_S = 2 * 3600
+
+# Capture format used by SpotifyDownloader: 44.1 kHz, 16-bit, stereo PCM.
+PCM_BYTES_PER_SECOND = 44100 * 4
+
+# Reservation used for an interactive download that gave no expected duration.
+DEFAULT_INTERACTIVE_RESERVE_S = 300
+
+# Typical track length used by GET /spotify/budget to answer "can a batch start?".
+PROBE_BATCH_SECONDS = 240
+
+CODE_BUDGET = "spotify_budget"
+CODE_BATCH_BUSY = "batch_busy"
+CODE_INTERACTIVE_ACTIVE = "interactive_active"
+CODE_BATCH_GAP = "batch_gap"
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    if not raw:
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        logger.warning(f"Ignoring non-integer {name}={raw!r}; using {default}")
+        return default
+
+
+@dataclass
+class BudgetConfig:
+    batch_budget_s: int = 43200
+    hard_cap_s: int = 86400
+    interactive_reserve_s: int = 7200
+    max_batch_in_flight: int = 2
+    min_batch_gap_s: int = 30
+    window_s: int = 86400
+
+    @classmethod
+    def from_env(cls) -> "BudgetConfig":
+        d = cls()
+        return cls(
+            batch_budget_s=_env_int("FLACFETCH_SPOTIFY_BATCH_BUDGET_S", d.batch_budget_s),
+            hard_cap_s=_env_int("FLACFETCH_SPOTIFY_HARD_CAP_S", d.hard_cap_s),
+            interactive_reserve_s=_env_int("FLACFETCH_SPOTIFY_INTERACTIVE_RESERVE_S", d.interactive_reserve_s),
+            max_batch_in_flight=_env_int("FLACFETCH_SPOTIFY_MAX_BATCH_IN_FLIGHT", d.max_batch_in_flight),
+            min_batch_gap_s=_env_int("FLACFETCH_SPOTIFY_MIN_BATCH_GAP_S", d.min_batch_gap_s),
+            window_s=_env_int("FLACFETCH_SPOTIFY_WINDOW_S", d.window_s),
+        )
+
+
+@dataclass
+class Usage:
+    total_s: float = 0.0
+    batch_s: float = 0.0
+    batch_in_flight: int = 0
+    interactive_in_flight: int = 0
+    last_batch_start: Optional[float] = None
+    # (started_at, counted_seconds, priority) of every counted entry; used to
+    # work out when enough usage ages out of the window.
+    entries: Tuple[Tuple[float, float, str], ...] = ()
+
+
+def _age_out_delay(
+    entries: Tuple[Tuple[float, float, str], ...],
+    excess: float,
+    only_batch: bool,
+    cfg: BudgetConfig,
+    now: float,
+) -> float:
+    """Seconds until entries aging out of the window free up `excess` seconds."""
+    freed = 0.0
+    for started_at, seconds, priority in sorted(entries):
+        if only_batch and priority != "batch":
+            continue
+        freed += seconds
+        if freed >= excess:
+            return max(0.0, started_at + cfg.window_s - now)
+    return float(cfg.window_s)
+
+
+def check_batch(
+    usage: Usage, seconds: float, cfg: BudgetConfig, now: float
+) -> Tuple[bool, Optional[str], int]:
+    """Decide whether a batch download of `seconds` may start.
+
+    Returns (ok, code, retry_after_s).
+    """
+    batch_excess = usage.batch_s + seconds - cfg.batch_budget_s
+    soft_cap = cfg.hard_cap_s - cfg.interactive_reserve_s
+    total_excess = usage.total_s + seconds - soft_cap
+    if batch_excess > 0 or total_excess > 0:
+        delay = 0.0
+        if batch_excess > 0:
+            delay = max(delay, _age_out_delay(usage.entries, batch_excess, True, cfg, now))
+        if total_excess > 0:
+            delay = max(delay, _age_out_delay(usage.entries, total_excess, False, cfg, now))
+        return False, CODE_BUDGET, max(1, math.ceil(delay))
+
+    if usage.batch_in_flight >= cfg.max_batch_in_flight:
+        return False, CODE_BATCH_BUSY, cfg.min_batch_gap_s
+
+    if usage.interactive_in_flight > 0:
+        return False, CODE_INTERACTIVE_ACTIVE, 60
+
+    if usage.last_batch_start is not None:
+        since = now - usage.last_batch_start
+        if since < cfg.min_batch_gap_s:
+            return False, CODE_BATCH_GAP, max(1, math.ceil(cfg.min_batch_gap_s - since))
+
+    return True, None, 0
+
+
+class SpotifyLedger:
+    """SQLite ledger of Spotify listening time (one connection per call)."""
+
+    def __init__(self, path: str, now: Callable[[], float] = time.time):
+        self.path = path
+        self._now = now
+        directory = os.path.dirname(os.path.abspath(path))
+        os.makedirs(directory, exist_ok=True)
+        with self._tx() as conn:
+            conn.execute(
+                "CREATE TABLE IF NOT EXISTS entries ("
+                "download_id TEXT PRIMARY KEY, priority TEXT NOT NULL, "
+                "started_at REAL NOT NULL, reserved_s REAL NOT NULL, "
+                "captured_s REAL NULL, state TEXT NOT NULL)"
+            )
+
+    @contextmanager
+    def _tx(self) -> Iterator[sqlite3.Connection]:
+        conn = sqlite3.connect(self.path, timeout=30, isolation_level=None)
+        try:
+            conn.execute("BEGIN IMMEDIATE")
+            try:
+                yield conn
+            except BaseException:
+                conn.execute("ROLLBACK")
+                raise
+            else:
+                conn.execute("COMMIT")
+        finally:
+            conn.close()
+
+    def _insert(self, conn: sqlite3.Connection, download_id: str, priority: str, seconds: float) -> None:
+        conn.execute(
+            "INSERT OR REPLACE INTO entries(download_id, priority, started_at, reserved_s, captured_s, state) "
+            "VALUES (?, ?, ?, ?, NULL, 'reserved')",
+            (download_id, priority, self._now(), float(seconds)),
+        )
+
+    def reserve(self, download_id: str, priority: str, seconds: float) -> None:
+        with self._tx() as conn:
+            self._insert(conn, download_id, priority, seconds)
+
+    def try_reserve_batch(
+        self, download_id: str, seconds: float, cfg: BudgetConfig
+    ) -> Tuple[bool, Optional[str], int]:
+        """Atomically check the batch gate and, if open, reserve."""
+        with self._tx() as conn:
+            now = self._now()
+            usage = self._usage(conn, now, cfg.window_s)
+            ok, code, retry = check_batch(usage, seconds, cfg, now)
+            if ok:
+                self._insert(conn, download_id, "batch", seconds)
+            return ok, code, retry
+
+    def settle(self, download_id: str, captured_s: Optional[float]) -> None:
+        """Record the captured length (None keeps the reservation as the count)."""
+        with self._tx() as conn:
+            conn.execute(
+                "UPDATE entries SET state='done', captured_s=COALESCE(?, reserved_s) WHERE download_id=?",
+                (None if captured_s is None else float(captured_s), download_id),
+            )
+
+    def release(self, download_id: str) -> None:
+        with self._tx() as conn:
+            conn.execute("UPDATE entries SET state='released' WHERE download_id=?", (download_id,))
+
+    def settle_orphans(self) -> int:
+        """Settle every still-reserved row at its reserved size (their process is gone)."""
+        with self._tx() as conn:
+            cur = conn.execute(
+                "UPDATE entries SET state='done', captured_s=reserved_s WHERE state='reserved'"
+            )
+            return cur.rowcount
+
+    def usage(self, now: Optional[float] = None, window_s: int = 86400) -> Usage:
+        with self._tx() as conn:
+            return self._usage(conn, self._now() if now is None else now, window_s)
+
+    def _usage(self, conn: sqlite3.Connection, now: float, window_s: int) -> Usage:
+        # Crash safety: a reservation that never settled counts at its reserved size.
+        conn.execute(
+            "UPDATE entries SET state='done', captured_s=reserved_s "
+            "WHERE state='reserved' AND started_at < ?",
+            (now - STALE_RESERVED_S,),
+        )
+        rows = conn.execute(
+            "SELECT priority, started_at, reserved_s, captured_s, state FROM entries "
+            "WHERE state != 'released' AND started_at > ?",
+            (now - window_s,),
+        ).fetchall()
+        usage = Usage()
+        entries = []
+        for priority, started_at, reserved_s, captured_s, state in rows:
+            counted = captured_s if (state == "done" and captured_s is not None) else reserved_s
+            usage.total_s += counted
+            entries.append((started_at, counted, priority))
+            if priority == "batch":
+                usage.batch_s += counted
+            if state == "reserved":
+                if priority == "batch":
+                    usage.batch_in_flight += 1
+                else:
+                    usage.interactive_in_flight += 1
+        last = conn.execute(
+            "SELECT MAX(started_at) FROM entries WHERE priority='batch' AND state != 'released'"
+        ).fetchone()[0]
+        usage.last_batch_start = last
+        usage.entries = tuple(entries)
+        return usage
+
+
+_ledger: Optional[SpotifyLedger] = None
+_ledger_lock = threading.Lock()
+
+
+def default_ledger_path() -> str:
+    return os.environ.get("FLACFETCH_SPOTIFY_LEDGER") or os.path.join(
+        os.path.expanduser("~"), ".cache", "flacfetch", "spotify_ledger.sqlite"
+    )
+
+
+def get_spotify_ledger() -> SpotifyLedger:
+    global _ledger
+    with _ledger_lock:
+        if _ledger is None:
+            ledger = SpotifyLedger(default_ledger_path())
+            # A new process has no downloads in flight; rows left reserved are orphans of a restart.
+            n = ledger.settle_orphans()
+            if n:
+                logger.info(f"Settled {n} orphaned reserved Spotify ledger entries at startup")
+            _ledger = ledger
+        return _ledger
+
+
+def reset_spotify_ledger() -> None:
+    """Drop the cached singleton (tests / config changes)."""
+    global _ledger
+    with _ledger_lock:
+        _ledger = None

{flacfetch-0.34.0 → flacfetch-0.35.0}/flacfetch/core/album_match.py

@@ -36,11 +36,11 @@ POSITION_BONUS = 0.05
 
 # "06 Title", "06 - Title", "06. Title", "1-06 Title" (disc-track), "A1 Title" is ignored.
 _TRACK_NUMBER_RE = re.compile(r"^(?:\d{1,2}[-.])?(\d{1,3})(?=[\s.\-_])")
-# Bracketed suffixes that don't change which recording it is ("(feat. X)",
+# Bracketed suffixes that don't change which recording it is ("(feat. X)", "(vs. X)",
 # "[Remastered 2011]", "(Mono)"); stripped from titles and file names alike.
 # Version suffixes ("(Live)", "(Remix)") are NOT stripped: they're another recording.
 _NEUTRAL_BRACKET_RE = re.compile(
-    r"\s*[\(\[]\s*(?:feat\.?|ft\.?|featuring|with|remaster(?:ed)?|\d{4}\s+remaster(?:ed)?|"
+    r"\s*[\(\[]\s*(?:feat\.?|ft\.?|featuring|with|vs\.?|versus|remaster(?:ed)?|\d{4}\s+remaster(?:ed)?|"
     r"mono|stereo|explicit|clean|bonus track)\b[^\)\]]*[\)\]]",
     re.IGNORECASE,
 )
@@ -130,10 +130,12 @@ def title_score(title: str, path: str) -> float:
     """How well a file matches a track title (0..1), ignoring neutral suffixes such
     as "(feat. X)" on either side. 0.0 when the two disagree on version markers:
     "Song (Live)" never matches "01 Song.flac", nor "Song" "02 Song (Live).flac"."""
+    # Markers are compared on the full names: a credit bracket can also name a
+    # version ("(vs. X Remix)") and stripping it must not hide that.
+    if version_markers(title) != version_markers(_file_title(path)):
+        return 0.0
     want = _strip_neutral(title) or title
     have = _strip_neutral(_file_title(path)) or _file_title(path)
-    if version_markers(want) != version_markers(have):
-        return 0.0
     # calculate_match_score strips a file extension (everything after the last
     # dot), so give it one: "05 Mr. Brightside" must not become "05 Mr".
     return calculate_match_score(want, f"{have}.flac")