feat: add Missing Track System with external tracks, Spotify import, and wishlist

- Add ExternalTrack model for tracks not in local library
- Playlists now support mixed local + external tracks
- Add external track matching service (ISRC, exact, fuzzy)
- Add Spotify playlist import with local/external splitting
- Add LLM tools for Spotify playlist operations
- Add "Add to Wishlist" action in Discovery views
- Add preview playback support for external tracks
- Auto-match external tracks when new local tracks added

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: jeffcrouse

CHANGELOG.md

@@ -7,8 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.0-alpha.14] - 2026-01-25
+
 ### Added
 
+- **Missing Track System** - first-class support for "missing tracks" (tracks you want but don't have locally)
+  - **External Tracks model** - new `ExternalTrack` table to store metadata for tracks not in your library
+  - **Mixed playlists** - playlists can now contain both local tracks and external track placeholders
+  - **Visual distinction** - external tracks appear at 75% opacity with "Not in library" label
+  - **Preview playback** - 30-second previews from Spotify/Deezer for external tracks (amber Radio icon)
+  - **Purchase links** - external link pills to find tracks on Bandcamp, Spotify, Last.fm
+  - **Auto-matching** - when you add tracks to library, they automatically link to matching external tracks
+  - **Wishlist playlist** - special system playlist for tracks you're interested in
+  - **Add to Wishlist** - purple "+" button on discovery items to save tracks you want
+- **Spotify playlist import** - import Spotify playlists with automatic local/external track splitting
+  - `GET /spotify/playlists` - list your Spotify playlists
+  - `GET /spotify/playlists/{id}/tracks` - preview tracks with local match status
+  - `POST /spotify/playlists/{id}/import` - import playlist with local matches + external placeholders
+- **External track matching service** - intelligent matching algorithm
+  - ISRC exact match (highest confidence)
+  - Exact artist + title match
+  - Partial match with title/artist contains
+  - Fuzzy match with 85% threshold using rapidfuzz
+  - Background re-matching after library scans
+- **LLM tools for Spotify playlists** - Claude can now work with your Spotify playlists
+  - `list_spotify_playlists` - "What Spotify playlists do I have?"
+  - `get_spotify_playlist_tracks` - "What's in my Spotify workout playlist?" (shows match rate)
+  - `import_spotify_playlist` - "Import my Spotify chill playlist"
 - **Downloads view** - dedicated section for browsing all downloaded/offline tracks
   - New "Downloads" button in Playlists tab (below Favorites) with green gradient styling
   - Shows total track count and storage size used
@@ -21,6 +46,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Filter state persists in URL for Library view (`?downloadedOnly=true`)
 - **useDownloadedTracks hook** - returns downloaded tracks with metadata, total count, and storage size
 
+### Changed
+
+- **Playlist API responses** - now include `is_wishlist`, `local_track_count`, `external_track_count` fields
+- **Playlist tracks** - unified `PlaylistTrackItem` type with `type: 'local' | 'external'` discriminator
+- **Discovery components** - all discovery views now support "Add to Wishlist" action for non-library items
+
 ## [0.1.0-alpha.13] - 2026-01-23
 
 ### Added

backend/app/api/routes/external_tracks.py

@@ -0,0 +1,316 @@
+"""External track management endpoints.
+
+External tracks are tracks the user wants but doesn't have locally.
+They appear in playlists alongside local tracks with visual distinction.
+"""
+
+from uuid import UUID
+
+from fastapi import APIRouter, BackgroundTasks, HTTPException, Query, status
+from pydantic import BaseModel, Field
+from sqlalchemy import func, select
+
+from app.api.deps import DbSession, RequiredProfile
+from app.db.models import ExternalTrack, ExternalTrackSource
+from app.services.external_track_matcher import ExternalTrackMatcher
+
+router = APIRouter(prefix="/external-tracks", tags=["external-tracks"])
+
+
+class ExternalTrackCreate(BaseModel):
+    """Request to create an external track."""
+
+    title: str = Field(..., min_length=1, max_length=500)
+    artist: str = Field(..., min_length=1, max_length=500)
+    album: str | None = Field(None, max_length=500)
+    duration_seconds: float | None = None
+    year: int | None = None
+    isrc: str | None = Field(None, max_length=12)
+    spotify_id: str | None = Field(None, max_length=50)
+    preview_url: str | None = Field(None, max_length=500)
+    preview_source: str | None = Field(None, max_length=20)
+    external_data: dict | None = None
+
+
+class ExternalTrackResponse(BaseModel):
+    """External track response."""
+
+    id: str
+    title: str
+    artist: str
+    album: str | None
+    duration_seconds: float | None
+    track_number: int | None
+    year: int | None
+    source: str
+    preview_url: str | None
+    preview_source: str | None
+    external_data: dict
+
+    # Matching status
+    is_matched: bool
+    matched_track_id: str | None
+    matched_at: str | None
+    match_confidence: float | None
+    match_method: str | None
+
+    # External IDs
+    spotify_id: str | None
+    isrc: str | None
+
+    created_at: str
+
+
+class ManualMatchRequest(BaseModel):
+    """Request to manually match an external track."""
+
+    track_id: str = Field(..., description="ID of local track to match to")
+
+
+class RematchResponse(BaseModel):
+    """Response from rematch operation."""
+
+    processed: int
+    matched: int
+    task_id: str | None = None
+
+
+@router.get("", response_model=list[ExternalTrackResponse])
+async def list_external_tracks(
+    db: DbSession,
+    profile: RequiredProfile,
+    matched: bool | None = Query(None, description="Filter by matched status"),
+    source: str | None = Query(None, description="Filter by source"),
+    limit: int = Query(100, ge=1, le=500),
+    offset: int = Query(0, ge=0),
+) -> list[ExternalTrackResponse]:
+    """List external tracks with optional filtering."""
+    query = select(ExternalTrack)
+
+    if matched is not None:
+        if matched:
+            query = query.where(ExternalTrack.matched_track_id.isnot(None))
+        else:
+            query = query.where(ExternalTrack.matched_track_id.is_(None))
+
+    if source:
+        try:
+            source_enum = ExternalTrackSource(source)
+            query = query.where(ExternalTrack.source == source_enum)
+        except ValueError:
+            pass  # Invalid source, ignore filter
+
+    query = query.order_by(ExternalTrack.created_at.desc()).limit(limit).offset(offset)
+
+    result = await db.execute(query)
+    tracks = result.scalars().all()
+
+    return [_external_track_to_response(t) for t in tracks]
+
+
+@router.get("/stats")
+async def get_external_track_stats(
+    db: DbSession,
+    profile: RequiredProfile,
+) -> dict:
+    """Get statistics about external tracks."""
+    # Total count
+    total = await db.scalar(select(func.count(ExternalTrack.id))) or 0
+
+    # Matched count
+    matched = await db.scalar(
+        select(func.count(ExternalTrack.id)).where(
+            ExternalTrack.matched_track_id.isnot(None)
+        )
+    ) or 0
+
+    # Count by source
+    source_counts = {}
+    for source in ExternalTrackSource:
+        count = await db.scalar(
+            select(func.count(ExternalTrack.id)).where(
+                ExternalTrack.source == source
+            )
+        ) or 0
+        source_counts[source.value] = count
+
+    return {
+        "total": total,
+        "matched": matched,
+        "unmatched": total - matched,
+        "match_rate": round(matched / total * 100, 1) if total > 0 else 0,
+        "by_source": source_counts,
+    }
+
+
+@router.post("", response_model=ExternalTrackResponse, status_code=status.HTTP_201_CREATED)
+async def create_external_track(
+    request: ExternalTrackCreate,
+    db: DbSession,
+    profile: RequiredProfile,
+) -> ExternalTrackResponse:
+    """Create a new external track (manually added)."""
+    matcher = ExternalTrackMatcher(db)
+
+    external_track = await matcher.create_external_track(
+        title=request.title,
+        artist=request.artist,
+        album=request.album,
+        source=ExternalTrackSource.MANUAL,
+        spotify_id=request.spotify_id,
+        isrc=request.isrc,
+        duration_seconds=request.duration_seconds,
+        preview_url=request.preview_url,
+        preview_source=request.preview_source,
+        external_data=request.external_data,
+        try_match=True,
+    )
+
+    return _external_track_to_response(external_track)
+
+
+@router.get("/{external_track_id}", response_model=ExternalTrackResponse)
+async def get_external_track(
+    external_track_id: UUID,
+    db: DbSession,
+    profile: RequiredProfile,
+) -> ExternalTrackResponse:
+    """Get an external track by ID."""
+    external_track = await db.get(ExternalTrack, external_track_id)
+
+    if not external_track:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="External track not found",
+        )
+
+    return _external_track_to_response(external_track)
+
+
+@router.delete("/{external_track_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_external_track(
+    external_track_id: UUID,
+    db: DbSession,
+    profile: RequiredProfile,
+) -> None:
+    """Delete an external track."""
+    external_track = await db.get(ExternalTrack, external_track_id)
+
+    if not external_track:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="External track not found",
+        )
+
+    await db.delete(external_track)
+    await db.commit()
+
+
+@router.post("/{external_track_id}/match", response_model=ExternalTrackResponse)
+async def manual_match(
+    external_track_id: UUID,
+    request: ManualMatchRequest,
+    db: DbSession,
+    profile: RequiredProfile,
+) -> ExternalTrackResponse:
+    """Manually match an external track to a local track."""
+    matcher = ExternalTrackMatcher(db)
+
+    try:
+        track_id = UUID(request.track_id)
+    except ValueError:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid track_id format",
+        )
+
+    try:
+        external_track = await matcher.manual_match(external_track_id, track_id)
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(e),
+        )
+
+    if not external_track:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="External track not found",
+        )
+
+    return _external_track_to_response(external_track)
+
+
+@router.delete("/{external_track_id}/match", response_model=ExternalTrackResponse)
+async def remove_match(
+    external_track_id: UUID,
+    db: DbSession,
+    profile: RequiredProfile,
+) -> ExternalTrackResponse:
+    """Remove the match from an external track."""
+    matcher = ExternalTrackMatcher(db)
+    external_track = await matcher.remove_match(external_track_id)
+
+    if not external_track:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="External track not found",
+        )
+
+    return _external_track_to_response(external_track)
+
+
+@router.post("/rematch", response_model=RematchResponse)
+async def rematch_all(
+    db: DbSession,
+    profile: RequiredProfile,
+    background_tasks: BackgroundTasks,
+    run_in_background: bool = Query(False, description="Run in background"),
+) -> RematchResponse:
+    """Re-run matching for all unmatched external tracks.
+
+    If run_in_background=True, returns immediately with task_id.
+    Otherwise, runs synchronously and returns results.
+    """
+    matcher = ExternalTrackMatcher(db)
+
+    if run_in_background:
+        # For now, just run synchronously but return task structure
+        # TODO: Implement proper background task tracking
+        stats = await matcher.rematch_all_unmatched()
+        return RematchResponse(
+            processed=stats["processed"],
+            matched=stats["matched"],
+            task_id=None,
+        )
+    else:
+        stats = await matcher.rematch_all_unmatched()
+        return RematchResponse(
+            processed=stats["processed"],
+            matched=stats["matched"],
+        )
+
+
+def _external_track_to_response(track: ExternalTrack) -> ExternalTrackResponse:
+    """Convert ExternalTrack model to response."""
+    return ExternalTrackResponse(
+        id=str(track.id),
+        title=track.title,
+        artist=track.artist,
+        album=track.album,
+        duration_seconds=track.duration_seconds,
+        track_number=track.track_number,
+        year=track.year,
+        source=track.source.value,
+        preview_url=track.preview_url,
+        preview_source=track.preview_source,
+        external_data=track.external_data or {},
+        is_matched=track.matched_track_id is not None,
+        matched_track_id=str(track.matched_track_id) if track.matched_track_id else None,
+        matched_at=track.matched_at.isoformat() if track.matched_at else None,
+        match_confidence=track.match_confidence,
+        match_method=track.match_method,
+        spotify_id=track.spotify_id,
+        isrc=track.isrc,
+        created_at=track.created_at.isoformat(),
+    )