playlist-bridge 0.2.0__tar.gz

playlist_bridge-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Basar Tuncay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

playlist_bridge-0.2.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: playlist-bridge
+Version: 0.2.0
+Summary: Migrate YouTube Music playlists into Spotify Liked Songs, with fuzzy matching and resumable runs.
+Author: Basar Tuncay
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/basartuncay/PlaylistBridge
+Project-URL: Issues, https://github.com/basartuncay/PlaylistBridge/issues
+Keywords: spotify,youtube-music,playlist,migration,cli
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: spotipy>=2.23
+Requires-Dist: rapidfuzz>=3.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: ytmusicapi>=1.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# PlaylistBridge
+
+[![CI](https://github.com/basartuncay/PlaylistBridge/actions/workflows/ci.yml/badge.svg)](https://github.com/basartuncay/PlaylistBridge/actions/workflows/ci.yml)
+
+A command-line tool that reads a YouTube Music playlist — straight from its public
+URL, or from a copy-pasted page dump — and adds the matching tracks to Spotify Liked Songs. Built with an
+extensible architecture so that other source/target platform pairs can be
+added later without touching the core matching or checkpointing logic.
+
+## Architecture
+
+The domain model is deliberately kept platform-agnostic (`src/models.py`):
+`SourceTrack`, `SearchCandidate`, `MatchResult`, and `MigrationSummary` don't
+know anything about YouTube Music or Spotify specifically. Every other module
+only talks to these shared types, not to each other's internals.
+
+- **`parser/ytmusic_playlist.py`** reads a public playlist by URL via
+  `ytmusicapi` (no login) and produces the same `SourceTrack` entries.
+- **`parser/ytmusic_parser.py`** turns the raw page dump into `SourceTrack`
+  entries and builds an ordered list of `SearchCandidate` guesses per entry.
+- **`spotify_client/client.py`** wraps `spotipy`: OAuth setup, rate-limit
+  backoff, search, and adding to Liked Songs.
+- **`matcher/track_matcher.py`** scores a Spotify search hit against the
+  source entry and flags low-confidence matches.
+- **`state/checkpoint.py`** tracks which entries have already been migrated
+  so re-running the tool is safe and cheap.
+- **`cli.py`** wires all of the above together and prints an end-of-run
+  summary.
+
+## Design Decisions
+
+**Platform-agnostic shared models.** `SourceTrack` and `SearchCandidate` don't
+reference YouTube Music by name, and `MatchResult` doesn't reference Spotify.
+The parser is the only thing that needs to know about YouTube Music's page
+format, and the client is the only thing that needs to know about Spotify's
+API shape. Adding, say, an Apple Music target later means writing a new
+client module that consumes `SearchCandidate` and produces `MatchResult` — no
+changes to the matching or checkpointing logic.
+
+**Incremental checkpoint with atomic writes.** A migration run can touch
+hundreds of tracks and take a long time once rate-limit backoff kicks in.
+`CheckpointStore` flushes to disk every few entries (not just once at the
+end), and each flush writes to a temp file and `os.replace()`s it over the
+real file, so a crash or Ctrl+C mid-write never corrupts the checkpoint —
+worst case you lose the last few *unflushed* entries, not the whole file.
+
+**Fuzzy matching with suspicious-match flagging.** Spotify's search endpoint
+returns its own idea of the best match, which is frequently wrong for
+non-official uploads, remixes, or channels named after the artist rather than
+the artist's own page. Instead of trusting the top result blindly, every
+match is scored against the original entry (title-weighted, since artist
+data is sometimes just a channel name) and anything below
+`SUSPICIOUS_SCORE_THRESHOLD` is flagged for manual review rather than
+silently trusted.
+
+**Dry-run mode.** Because the tool mutates a real Spotify library, `--dry-run`
+lets you see exactly what would be searched for — without creating a Spotify
+client, without any network calls, and without touching checkpoint state —
+before committing to a real run.
+
+## Testing & Lessons Learned
+
+65/65 tests pass (`pytest -v`). Two real bugs were caught during development
+and are worth calling out because they weren't obvious from the code alone:
+
+1. **Empty `source.artist` silently tanked otherwise-perfect matches.**
+   `score_match` already handled an empty *candidate* artist (the
+   title-only search fallback) by scoring on title alone. But when the
+   *source* entry's own artist field was empty — which happens whenever
+   `build_candidates`'s title-only fallback is what actually finds a hit —
+   the fuzzy ratio between `""` and a real artist name scores `0`, dragging
+   a 100%-title-match down to ~60% overall. Fixed by falling back to
+   title-only scoring whenever *either* side's artist is empty, with a
+   regression test (`test_score_match_uses_title_only_when_source_artist_is_empty`).
+
+2. **`suspicious_tracks.txt` was opened in append mode.** Since the
+   suspicious-duration check runs before the checkpoint lookup, a track
+   that's suspiciously long gets logged on every single run, whether or not
+   it was already migrated. Opening the log in `"a"` mode meant every run
+   added another copy of the same entries on top of the last run's. Fixed
+   by overwriting the file every run instead
+   (`test_run_migration_overwrites_suspicious_log_instead_of_appending`
+   calls `run_migration` twice and asserts the log contains exactly one
+   copy of the entry, not two).
+
+## Setup & Usage
+
+### Install
+
+```bash
+pipx install playlist-bridge        # or: pip install playlist-bridge
+```
+
+From source (for development): `pip install -e ".[dev]"`.
+
+### Configure Spotify credentials
+
+1. Go to the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
+   and create an app.
+2. Copy its **Client ID** and **Client Secret**.
+3. Add a Redirect URI in the app settings that matches what you'll use
+   locally, e.g. `http://127.0.0.1:8888/callback`.
+4. Create a `.env` file in the folder you'll run the command from (or export the
+   variables in your shell) with the three values:
+
+   ```
+   SPOTIPY_CLIENT_ID=your-client-id
+   SPOTIPY_CLIENT_SECRET=your-client-secret
+   SPOTIPY_REDIRECT_URI=http://127.0.0.1:8888/callback
+   ```
+
+Each user brings their own Spotify app. That keeps every run inside your own app's
+development-mode quota instead of a shared one.
+
+### Pick a source
+
+**Option A: a public playlist URL (recommended).** Copy the playlist's share link from
+YouTube Music or YouTube — no YouTube login or copy-paste needed. Private playlists and
+your Liked Music aren't reachable this way; use option B for those.
+
+**Option B: a page dump.** Open your YouTube Music playlist or library page in a browser, select all
+(Ctrl+A / Cmd+A), copy, and paste the result into `ytmusic_paste.txt` in the
+project root (or any path you pass to `--input`).
+
+> **Copy the whole page, not just the track list.** Include the header/menu
+> text above the tracks — the parser locates the line mentioning both
+> "views" and "tracks" and skips everything up to and including it, so any
+> nav/menu text above the tracks is discarded cleanly. If you paste only the
+> track list itself, that header line won't be there, and the parser has no
+> reliable anchor for where the real entries start.
+
+### Run
+
+```bash
+# Report what would happen, without touching Spotify or checkpoint state
+playlist-bridge --playlist "https://music.youtube.com/playlist?list=PL..." --dry-run
+
+# Actually migrate
+playlist-bridge --playlist "https://music.youtube.com/playlist?list=PL..."
+
+# Or from a page dump
+playlist-bridge --input ytmusic_paste.txt
+```
+
+The first real run opens a browser window for Spotify OAuth consent. Progress
+is checkpointed to `processed_tracks.json`, so an interrupted run can simply
+be re-run — already-migrated tracks are skipped. Suspiciously long entries
+(over 10 minutes) are written to `suspicious_tracks.txt` for manual review.
+
+### Run the checks
+
+```bash
+ruff check . && mypy playlist_bridge && pytest -v
+```
+
+### Releasing
+
+Bump `version` in `pyproject.toml`, then push a matching tag (`git tag v0.2.0 && git push --tags`).
+`.github/workflows/publish.yml` builds and uploads to PyPI via trusted publishing (no token
+stored in the repo); it refuses to publish if the tag and the package version differ.
+
+## Tech Stack
+
+- **Python** 3.10+
+- **[spotipy](https://spotipy.readthedocs.io/)** — Spotify Web API client and OAuth
+- **[rapidfuzz](https://github.com/rapidfuzz/RapidFuzz)** — fuzzy string matching for track scoring
+- **[ytmusicapi](https://github.com/sigma67/ytmusicapi)** — reading public YouTube Music playlists (unofficial API)
+- **[python-dotenv](https://github.com/theskumar/python-dotenv)** — loading Spotify credentials from `.env`
+- **[pytest](https://docs.pytest.org/)** — test suite
+
+## Future Work
+
+The platform-agnostic model design leaves room to grow in a few directions:
+
+* **Private playlists and Liked Music.** Public playlists are read via
+  `ytmusicapi` without login; private ones still need the page-dump path.
+  `ytmusicapi`'s browser-auth mode could cover them.
+* **Reverse migration (Spotify → YouTube Music).** The shared model types
+  were designed with this in mind — it would mainly require a YouTube
+  Music *write* client alongside the existing Spotify one.
+* **Other platforms.** Apple Music, Tidal, and others could be added as
+  either a source or a target without touching the core matching or
+  checkpointing logic.

playlist_bridge-0.2.0/README.md

@@ -0,0 +1,183 @@
+# PlaylistBridge
+
+[![CI](https://github.com/basartuncay/PlaylistBridge/actions/workflows/ci.yml/badge.svg)](https://github.com/basartuncay/PlaylistBridge/actions/workflows/ci.yml)
+
+A command-line tool that reads a YouTube Music playlist — straight from its public
+URL, or from a copy-pasted page dump — and adds the matching tracks to Spotify Liked Songs. Built with an
+extensible architecture so that other source/target platform pairs can be
+added later without touching the core matching or checkpointing logic.
+
+## Architecture
+
+The domain model is deliberately kept platform-agnostic (`src/models.py`):
+`SourceTrack`, `SearchCandidate`, `MatchResult`, and `MigrationSummary` don't
+know anything about YouTube Music or Spotify specifically. Every other module
+only talks to these shared types, not to each other's internals.
+
+- **`parser/ytmusic_playlist.py`** reads a public playlist by URL via
+  `ytmusicapi` (no login) and produces the same `SourceTrack` entries.
+- **`parser/ytmusic_parser.py`** turns the raw page dump into `SourceTrack`
+  entries and builds an ordered list of `SearchCandidate` guesses per entry.
+- **`spotify_client/client.py`** wraps `spotipy`: OAuth setup, rate-limit
+  backoff, search, and adding to Liked Songs.
+- **`matcher/track_matcher.py`** scores a Spotify search hit against the
+  source entry and flags low-confidence matches.
+- **`state/checkpoint.py`** tracks which entries have already been migrated
+  so re-running the tool is safe and cheap.
+- **`cli.py`** wires all of the above together and prints an end-of-run
+  summary.
+
+## Design Decisions
+
+**Platform-agnostic shared models.** `SourceTrack` and `SearchCandidate` don't
+reference YouTube Music by name, and `MatchResult` doesn't reference Spotify.
+The parser is the only thing that needs to know about YouTube Music's page
+format, and the client is the only thing that needs to know about Spotify's
+API shape. Adding, say, an Apple Music target later means writing a new
+client module that consumes `SearchCandidate` and produces `MatchResult` — no
+changes to the matching or checkpointing logic.
+
+**Incremental checkpoint with atomic writes.** A migration run can touch
+hundreds of tracks and take a long time once rate-limit backoff kicks in.
+`CheckpointStore` flushes to disk every few entries (not just once at the
+end), and each flush writes to a temp file and `os.replace()`s it over the
+real file, so a crash or Ctrl+C mid-write never corrupts the checkpoint —
+worst case you lose the last few *unflushed* entries, not the whole file.
+
+**Fuzzy matching with suspicious-match flagging.** Spotify's search endpoint
+returns its own idea of the best match, which is frequently wrong for
+non-official uploads, remixes, or channels named after the artist rather than
+the artist's own page. Instead of trusting the top result blindly, every
+match is scored against the original entry (title-weighted, since artist
+data is sometimes just a channel name) and anything below
+`SUSPICIOUS_SCORE_THRESHOLD` is flagged for manual review rather than
+silently trusted.
+
+**Dry-run mode.** Because the tool mutates a real Spotify library, `--dry-run`
+lets you see exactly what would be searched for — without creating a Spotify
+client, without any network calls, and without touching checkpoint state —
+before committing to a real run.
+
+## Testing & Lessons Learned
+
+65/65 tests pass (`pytest -v`). Two real bugs were caught during development
+and are worth calling out because they weren't obvious from the code alone:
+
+1. **Empty `source.artist` silently tanked otherwise-perfect matches.**
+   `score_match` already handled an empty *candidate* artist (the
+   title-only search fallback) by scoring on title alone. But when the
+   *source* entry's own artist field was empty — which happens whenever
+   `build_candidates`'s title-only fallback is what actually finds a hit —
+   the fuzzy ratio between `""` and a real artist name scores `0`, dragging
+   a 100%-title-match down to ~60% overall. Fixed by falling back to
+   title-only scoring whenever *either* side's artist is empty, with a
+   regression test (`test_score_match_uses_title_only_when_source_artist_is_empty`).
+
+2. **`suspicious_tracks.txt` was opened in append mode.** Since the
+   suspicious-duration check runs before the checkpoint lookup, a track
+   that's suspiciously long gets logged on every single run, whether or not
+   it was already migrated. Opening the log in `"a"` mode meant every run
+   added another copy of the same entries on top of the last run's. Fixed
+   by overwriting the file every run instead
+   (`test_run_migration_overwrites_suspicious_log_instead_of_appending`
+   calls `run_migration` twice and asserts the log contains exactly one
+   copy of the entry, not two).
+
+## Setup & Usage
+
+### Install
+
+```bash
+pipx install playlist-bridge        # or: pip install playlist-bridge
+```
+
+From source (for development): `pip install -e ".[dev]"`.
+
+### Configure Spotify credentials
+
+1. Go to the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
+   and create an app.
+2. Copy its **Client ID** and **Client Secret**.
+3. Add a Redirect URI in the app settings that matches what you'll use
+   locally, e.g. `http://127.0.0.1:8888/callback`.
+4. Create a `.env` file in the folder you'll run the command from (or export the
+   variables in your shell) with the three values:
+
+   ```
+   SPOTIPY_CLIENT_ID=your-client-id
+   SPOTIPY_CLIENT_SECRET=your-client-secret
+   SPOTIPY_REDIRECT_URI=http://127.0.0.1:8888/callback
+   ```
+
+Each user brings their own Spotify app. That keeps every run inside your own app's
+development-mode quota instead of a shared one.
+
+### Pick a source
+
+**Option A: a public playlist URL (recommended).** Copy the playlist's share link from
+YouTube Music or YouTube — no YouTube login or copy-paste needed. Private playlists and
+your Liked Music aren't reachable this way; use option B for those.
+
+**Option B: a page dump.** Open your YouTube Music playlist or library page in a browser, select all
+(Ctrl+A / Cmd+A), copy, and paste the result into `ytmusic_paste.txt` in the
+project root (or any path you pass to `--input`).
+
+> **Copy the whole page, not just the track list.** Include the header/menu
+> text above the tracks — the parser locates the line mentioning both
+> "views" and "tracks" and skips everything up to and including it, so any
+> nav/menu text above the tracks is discarded cleanly. If you paste only the
+> track list itself, that header line won't be there, and the parser has no
+> reliable anchor for where the real entries start.
+
+### Run
+
+```bash
+# Report what would happen, without touching Spotify or checkpoint state
+playlist-bridge --playlist "https://music.youtube.com/playlist?list=PL..." --dry-run
+
+# Actually migrate
+playlist-bridge --playlist "https://music.youtube.com/playlist?list=PL..."
+
+# Or from a page dump
+playlist-bridge --input ytmusic_paste.txt
+```
+
+The first real run opens a browser window for Spotify OAuth consent. Progress
+is checkpointed to `processed_tracks.json`, so an interrupted run can simply
+be re-run — already-migrated tracks are skipped. Suspiciously long entries
+(over 10 minutes) are written to `suspicious_tracks.txt` for manual review.
+
+### Run the checks
+
+```bash
+ruff check . && mypy playlist_bridge && pytest -v
+```
+
+### Releasing
+
+Bump `version` in `pyproject.toml`, then push a matching tag (`git tag v0.2.0 && git push --tags`).
+`.github/workflows/publish.yml` builds and uploads to PyPI via trusted publishing (no token
+stored in the repo); it refuses to publish if the tag and the package version differ.
+
+## Tech Stack
+
+- **Python** 3.10+
+- **[spotipy](https://spotipy.readthedocs.io/)** — Spotify Web API client and OAuth
+- **[rapidfuzz](https://github.com/rapidfuzz/RapidFuzz)** — fuzzy string matching for track scoring
+- **[ytmusicapi](https://github.com/sigma67/ytmusicapi)** — reading public YouTube Music playlists (unofficial API)
+- **[python-dotenv](https://github.com/theskumar/python-dotenv)** — loading Spotify credentials from `.env`
+- **[pytest](https://docs.pytest.org/)** — test suite
+
+## Future Work
+
+The platform-agnostic model design leaves room to grow in a few directions:
+
+* **Private playlists and Liked Music.** Public playlists are read via
+  `ytmusicapi` without login; private ones still need the page-dump path.
+  `ytmusicapi`'s browser-auth mode could cover them.
+* **Reverse migration (Spotify → YouTube Music).** The shared model types
+  were designed with this in mind — it would mainly require a YouTube
+  Music *write* client alongside the existing Spotify one.
+* **Other platforms.** Apple Music, Tidal, and others could be added as
+  either a source or a target without touching the core matching or
+  checkpointing logic.

playlist_bridge-0.2.0/playlist_bridge/__init__.py

@@ -0,0 +1 @@
+"""PlaylistBridge: migrate playlists between music platforms."""

playlist_bridge-0.2.0/playlist_bridge/cli.py

@@ -0,0 +1,160 @@
+"""Command-line entry point for PlaylistBridge.
+
+Wires together the source (a public playlist URL or a YouTube Music page dump), matcher,
+Spotify client, and checkpoint store to migrate tracks into Spotify Liked Songs, and prints
+an end-of-run summary.
+"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from playlist_bridge.matcher.track_matcher import build_match_result
+from playlist_bridge.models import MigrationSummary
+from playlist_bridge.parser.ytmusic_parser import build_candidates, parse_ytmusic_page
+from playlist_bridge.parser.ytmusic_playlist import fetch_playlist_tracks
+from playlist_bridge.spotify_client.client import SpotifyClient
+from playlist_bridge.state.checkpoint import CheckpointStore
+
+DEFAULT_INPUT_PATH = Path("ytmusic_paste.txt")
+DEFAULT_STATE_PATH = Path("processed_tracks.json")
+DEFAULT_SUSPICIOUS_LOG_PATH = Path("suspicious_tracks.txt")
+
+# A track longer than this is more likely to be a full album/mix mislabeled as a
+# single entry than a genuinely long song, and is worth a human's second look.
+SUSPICIOUS_DURATION_THRESHOLD_SECONDS = 600
+
+
+def build_arg_parser() -> argparse.ArgumentParser:
+    """Build the CLI argument parser, including --input and --dry-run."""
+    parser = argparse.ArgumentParser(
+        description="Migrate a YouTube Music playlist into Spotify Liked Songs."
+    )
+    source = parser.add_mutually_exclusive_group()
+    source.add_argument(
+        "--playlist",
+        metavar="URL_OR_ID",
+        help="Public YouTube Music / YouTube playlist URL or id (no YouTube login needed).",
+    )
+    source.add_argument(
+        "--input",
+        type=Path,
+        default=DEFAULT_INPUT_PATH,
+        help="Path to the YouTube Music page dump text file (default: %(default)s).",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help=(
+            "Report what would happen without actually adding anything to Spotify "
+            "or writing checkpoint state."
+        ),
+    )
+    return parser
+
+
+def run_migration(
+    input_path: Path, dry_run: bool, playlist: str | None = None
+) -> MigrationSummary:
+    """Run the full YouTube Music -> Spotify migration and return a summary of the results.
+
+    In --dry-run mode, only the input is parsed: no Spotify client or checkpoint store
+    is created, nothing is searched for on Spotify, and nothing is added to Liked Songs
+    or written to checkpoint state. Instead, the searches that would have been tried
+    for each entry are printed.
+    """
+    if playlist:
+        entries = fetch_playlist_tracks(playlist)
+    else:
+        entries = parse_ytmusic_page(input_path.read_text(encoding="utf-8"))
+
+    client: SpotifyClient | None = None
+    checkpoint: CheckpointStore | None = None
+    if not dry_run:
+        client = SpotifyClient.from_env()
+        checkpoint = CheckpointStore(DEFAULT_STATE_PATH)
+
+    summary = MigrationSummary()
+    suspicious_lines: list[str] = []
+
+    for entry in entries:
+        if entry.duration_seconds > SUSPICIOUS_DURATION_THRESHOLD_SECONDS:
+            summary.suspicious_duration_count += 1
+            suspicious_lines.append(
+                f"{entry.artist} - {entry.title} ({entry.duration_seconds}s)"
+            )
+
+        if checkpoint is not None and checkpoint.is_processed(entry.key()):
+            summary.skipped_already_processed += 1
+            continue
+
+        found_track = None
+        for candidate in build_candidates(entry):
+            if dry_run:
+                label = (
+                    f"{candidate.artist} - {candidate.title}"
+                    if candidate.artist
+                    else candidate.title
+                )
+                print(f"Would search for: {label}")
+                continue
+
+            assert client is not None
+            found_track = client.search_track(candidate.artist, candidate.title)
+            if found_track:
+                break
+
+        if client is None or checkpoint is None:  # dry run
+            continue
+
+        if found_track is None:
+            summary.not_found += 1
+            continue
+
+        match_result = build_match_result(entry, found_track)
+        client.add_to_liked_songs(match_result.track_id)
+        checkpoint.mark_processed(entry.key())
+
+        summary.added += 1
+        summary.match_scores.append(match_result.score)
+        if match_result.is_suspicious:
+            summary.suspicious_match_count += 1
+
+    if checkpoint is not None:
+        checkpoint.flush()
+
+    # Overwritten (not appended) on every run: a track that's no longer suspicious,
+    # or was already migrated, would otherwise linger here as a stale duplicate.
+    with DEFAULT_SUSPICIOUS_LOG_PATH.open("w", encoding="utf-8") as f:
+        if suspicious_lines:
+            f.write("\n".join(suspicious_lines) + "\n")
+
+    return summary
+
+
+def print_summary(summary: MigrationSummary) -> None:
+    """Print the end-of-run report: added / not-found / suspicious counts and the
+    average fuzzy match score.
+    """
+    print("Migration summary")
+    print(f"  Added: {summary.added}")
+    print(f"  Not found: {summary.not_found}")
+    print(f"  Skipped (already processed): {summary.skipped_already_processed}")
+    print(f"  Suspicious duration: {summary.suspicious_duration_count}")
+    print(f"  Suspicious match: {summary.suspicious_match_count}")
+    print(f"  Average match score: {summary.average_match_score:.1f}")
+
+
+def main() -> None:
+    """CLI entry point: parse arguments and run the migration."""
+    parser = build_arg_parser()
+    args = parser.parse_args()
+    try:
+        summary = run_migration(args.input, args.dry_run, playlist=args.playlist)
+    except (ValueError, RuntimeError, FileNotFoundError) as exc:
+        parser.exit(2, f"playlist-bridge: error: {exc}\n")
+    print_summary(summary)
+
+
+if __name__ == "__main__":
+    main()

playlist_bridge-0.2.0/playlist_bridge/matcher/__init__.py

@@ -0,0 +1 @@
+"""Fuzzy matching between parsed source tracks and target-platform search results."""

playlist_bridge-0.2.0/playlist_bridge/matcher/track_matcher.py

@@ -0,0 +1,52 @@
+"""Fuzzy matching between a parsed source track and a candidate Spotify search result.
+
+Uses rapidfuzz to score how well a Spotify search hit actually matches the original
+source entry, and flags low-confidence matches as suspicious instead of blindly
+trusting Spotify's top search result.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from rapidfuzz import fuzz
+
+from playlist_bridge.models import MatchResult, SourceTrack
+
+SUSPICIOUS_SCORE_THRESHOLD = 60.0
+
+# Title carries more signal than artist: artist is sometimes empty or just a channel
+# name (see build_candidates' fallbacks), while the title is usually intact.
+TITLE_WEIGHT = 0.6
+ARTIST_WEIGHT = 0.4
+
+
+def score_match(source: SourceTrack, candidate_artist: str, candidate_title: str) -> float:
+    """Compute a 0-100 similarity score between the source entry and a Spotify candidate,
+    combining fuzzy ratios on both artist and title (not title alone).
+    """
+    title_score = fuzz.token_sort_ratio(source.title, candidate_title)
+
+    if not candidate_artist.strip() or not source.artist.strip():
+        return title_score
+
+    artist_score = fuzz.token_sort_ratio(source.artist, candidate_artist)
+    return TITLE_WEIGHT * title_score + ARTIST_WEIGHT * artist_score
+
+
+def build_match_result(source: SourceTrack, spotify_track: dict[str, Any]) -> MatchResult:
+    """Score a raw Spotify track object against the source entry and package the result,
+    flagging it as suspicious when the combined similarity score is below
+    SUSPICIOUS_SCORE_THRESHOLD.
+    """
+    matched_title = spotify_track["name"]
+    matched_artist = spotify_track["artists"][0]["name"]
+
+    score = score_match(source, matched_artist, matched_title)
+
+    return MatchResult(
+        track_id=spotify_track["id"],
+        matched_artist=matched_artist,
+        matched_title=matched_title,
+        score=score,
+        is_suspicious=score < SUSPICIOUS_SCORE_THRESHOLD,
+    )