Update README pertaining to spotify playlist import

README.md

@@ -291,41 +291,130 @@ Subsonic__EnableExternalPlaylists=false
 
 ### Spotify Playlist Injection (Jellyfin Only)
 
-Allstarr can intercept Spotify Import plugin playlists (Release Radar, Discover Weekly) and fill them with tracks automatically matched from your configured streaming provider (SquidWTF, Deezer, or Qobuz).
+Allstarr can automatically fill your Spotify playlists (like Release Radar and Discover Weekly) with tracks from your configured streaming provider (SquidWTF, Deezer, or Qobuz). This feature works by intercepting playlists created by the Jellyfin Spotify Import plugin and matching missing tracks with your streaming service.
 
-**Requirements:**
+#### Prerequisites
-- [Jellyfin Spotify Import Plugin](https://github.com/Viperinius/jellyfin-plugin-spotify-import) installed and configured
-- Plugin must run on a daily schedule (e.g., 4:15 PM daily)
-- Jellyfin URL and API key configured (uses existing JELLYFIN_URL and JELLYFIN_API_KEY settings)
 
-**Configuration:**
+1. **Install the Jellyfin Spotify Import Plugin**
+   - Navigate to Jellyfin Dashboard → Plugins → Catalog
+   - Search for "Spotify Import" by Viperinius
+   - Install and restart Jellyfin
+   - Plugin repository: [Viperinius/jellyfin-plugin-spotify-import](https://github.com/Viperinius/jellyfin-plugin-spotify-import)
+
+2. **Configure the Spotify Import Plugin**
+   - Go to Jellyfin Dashboard → Plugins → Spotify Import
+   - Connect your Spotify account
+   - Select which playlists to sync (e.g., Release Radar, Discover Weekly)
+   - Set a daily sync schedule (e.g., 4:15 PM daily)
+   - The plugin will create playlists in Jellyfin and generate "missing tracks" files for songs not in your library
+
+3. **Configure Allstarr**
+   - Allstarr needs to know when the plugin runs and which playlists to intercept
+   - Uses your existing `JELLYFIN_URL` and `JELLYFIN_API_KEY` settings (no additional credentials needed)
+
+#### Configuration
 
 | Setting | Description |
 |---------|-------------|
 | `SpotifyImport:Enabled` | Enable Spotify playlist injection (default: `false`) |
-| `SpotifyImport:SyncStartHour` | Hour when plugin runs (24-hour format, 0-23) |
+| `SpotifyImport:SyncStartHour` | Hour when the Spotify Import plugin runs (24-hour format, 0-23) |
-| `SpotifyImport:SyncStartMinute` | Minute when plugin runs (0-59) |
+| `SpotifyImport:SyncStartMinute` | Minute when the plugin runs (0-59) |
-| `SpotifyImport:SyncWindowHours` | Hours to search for missing tracks files after sync time |
+| `SpotifyImport:SyncWindowHours` | Hours to search for missing tracks files after sync time (default: 2) |
-| `SpotifyImport:Playlists` | Array of playlists to inject (Name, SpotifyName, Enabled) |
+| `SpotifyImport:PlaylistIds` | Comma-separated Jellyfin playlist IDs to intercept |
+| `SpotifyImport:PlaylistNames` | Comma-separated playlist names (must match order of IDs) |
 
-**How it works:**
+**Environment variables example:**
-1. Jellyfin Spotify Import plugin runs daily and creates playlists + missing tracks files
-2. Allstarr fetches these missing tracks files within the configured time window
-3. For each missing track, Allstarr searches your streaming provider (SquidWTF, Deezer, or Qobuz)
-4. When you open the playlist in Jellyfin, Allstarr intercepts the request and returns matched tracks
-5. Tracks are downloaded on-demand when played
-6. On startup, Allstarr will fetch missing tracks if it hasn't run in the last 24 hours
-
-**Environment variables:**
 ```bash
+# Enable the feature
 SPOTIFY_IMPORT_ENABLED=true
+
+# Match your Spotify Import plugin schedule (e.g., 4:15 PM daily)
 SPOTIFY_IMPORT_SYNC_START_HOUR=16
 SPOTIFY_IMPORT_SYNC_START_MINUTE=15
 SPOTIFY_IMPORT_SYNC_WINDOW_HOURS=2
-SPOTIFY_IMPORT_PLAYLISTS=Release Radar,Discover Weekly
+
+# Get playlist IDs from Jellyfin URLs: https://jellyfin.example.com/web/#/details?id=PLAYLIST_ID
+SPOTIFY_IMPORT_PLAYLIST_IDS=ba50e26c867ec9d57ab2f7bf24cfd6b0,4383a46d8bcac3be2ef9385053ea18df
+
+# Names must match exactly as they appear in Jellyfin (used to find missing tracks files)
+SPOTIFY_IMPORT_PLAYLIST_NAMES=Release Radar,Discover Weekly
 ```
 
-> **Note**: This feature uses your existing JELLYFIN_URL and JELLYFIN_API_KEY settings. The plugin must be configured to run on a schedule, and the sync window should cover the plugin's execution time.
+#### How It Works
+
+1. **Spotify Import Plugin Runs** (e.g., daily at 4:15 PM)
+   - Plugin fetches your Spotify playlists
+   - Creates/updates playlists in Jellyfin with tracks already in your library
+   - Generates "missing tracks" JSON files for songs not found locally
+   - Files are named like: `Release Radar_missing_2026-02-01_16-15.json`
+
+2. **Allstarr Fetches Missing Tracks** (within sync window)
+   - Searches for missing tracks files from the Jellyfin plugin
+   - Caches the list of missing tracks in Redis + file cache
+   - Runs automatically on startup and every 5 minutes during the sync window
+
+3. **Allstarr Matches Tracks** (2 minutes after startup, then every 30 minutes)
+   - For each missing track, searches your streaming provider (SquidWTF, Deezer, or Qobuz)
+   - Uses fuzzy matching to find the best match (title + artist similarity)
+   - Rate-limited to avoid overwhelming the service (150ms delay between searches)
+   - Caches matched results for 1 hour
+
+4. **You Open the Playlist in Jellyfin**
+   - Allstarr intercepts the request
+   - Returns a merged list: local tracks + matched streaming tracks
+   - Loads instantly from cache (no searching needed!)
+
+5. **You Play a Track**
+   - If it's a local track, streams from Jellyfin normally
+   - If it's a matched track, downloads from streaming provider on-demand
+   - Downloaded tracks are saved to your library for future use
+
+#### Manual Triggers
+
+You can manually trigger syncing and matching via API:
+
+```bash
+# Fetch missing tracks from Jellyfin plugin
+curl "https://your-jellyfin-proxy.com/spotify/sync?api_key=YOUR_API_KEY"
+
+# Trigger track matching (searches streaming provider)
+curl "https://your-jellyfin-proxy.com/spotify/match?api_key=YOUR_API_KEY"
+
+# Clear cache to force re-matching
+curl "https://your-jellyfin-proxy.com/spotify/clear-cache?api_key=YOUR_API_KEY"
+```
+
+#### Startup Behavior
+
+When Allstarr starts with Spotify Import enabled:
+- **T+0s**: Fetches missing tracks from Jellyfin plugin (if configured)
+- **T+2min**: Matches tracks with streaming provider (with rate limiting)
+- **Result**: Playlists load instantly when you open them!
+
+#### Troubleshooting
+
+**Playlists are empty:**
+- Check that the Spotify Import plugin is running and creating playlists
+- Verify `SPOTIFY_IMPORT_PLAYLIST_IDS` match your Jellyfin playlist IDs
+- Check logs: `docker-compose logs -f allstarr | grep -i spotify`
+
+**Tracks aren't matching:**
+- Ensure your streaming provider is configured (`MUSIC_SERVICE`, credentials)
+- Check that playlist names in `SPOTIFY_IMPORT_PLAYLIST_NAMES` match exactly
+- Manually trigger matching: `curl "https://your-proxy.com/spotify/match?api_key=KEY"`
+
+**Sync timing issues:**
+- Set `SPOTIFY_IMPORT_SYNC_START_HOUR/MINUTE` to match your plugin schedule
+- Increase `SPOTIFY_IMPORT_SYNC_WINDOW_HOURS` if files aren't being found
+- Check Jellyfin plugin logs to confirm when it runs
+
+#### Notes
+
+- This feature uses your existing `JELLYFIN_URL` and `JELLYFIN_API_KEY` settings
+- Matched tracks are cached for 1 hour to avoid repeated searches
+- Missing tracks cache persists across restarts (stored in Redis + file cache)
+- Rate limiting prevents overwhelming your streaming provider (150ms between searches)
+- Only works with Jellyfin backend (not Subsonic/Navidrome)
 
 ### Getting Credentials