linanail/spotarr repository overview

⁠Spotarr - Spotify Playlist Downloader

Spotarr is a modern, web-based Spotify playlist downloader with a sleek dark interface inspired by the *arr family of applications (Sonarr, Radarr, Lidarr). It automatically monitors your Spotify playlists and downloads new tracks as they're added, perfect for building your personal music library while maintaining your existing Spotify workflow.

🎯 Perfect for: Home media servers, music collectors, Plex users, and anyone wanting to own their music while keeping the convenience of Spotify playlists.

⁠✨ Key Features

• 🎵 Automatic Playlist Monitoring - Continuously monitors your Spotify playlists for new tracks
• 🌐 Modern Web Interface - Dark theme UI inspired by Sonarr/Radarr with real-time updates
• 📊 Rich Discord Webhooks - Beautiful embed notifications with album art and metadata
• 🎯 Smart Downloads - Only downloads new tracks, skips existing files
• 🔄 Runtime Configuration - Update settings without container restart
• 📈 Download Statistics - Track success rates, file sizes, and download history
• 🎚️ Quality Control - Choose from Normal, High, or Very High audio quality
• 🔍 Intelligent Error Detection - Distinguishes between region blocks, premium requirements, and technical issues
• 📱 Mobile Responsive - Works perfectly on desktop and mobile devices

⁠📖 How to Use Spotarr

⁠Step 1: Get Your Spotify Playlist URLs

1. Open Spotify and navigate to your playlist
2. Click the three dots (⋯) → Share → Copy link to playlist
3. Your URL will look like: https://open.spotify.com/playlist/37i9dQZF1DX0XUsuxWHRQd
4. Repeat for all playlists you want to monitor

⁠Step 2: Set Up Discord Webhooks (Optional)

1. In Discord, go to Server Settings → Integrations → Webhooks
2. Click "New Webhook" and choose your channel
3. Copy the webhook URL (looks like: https://discord.com/api/webhooks/...)
4. You'll get beautiful notifications with album art for every download

⁠Step 3: Configure Your Container

Use the docker-compose example below, replacing:

• YOUR_PLAYLIST_ID with your actual playlist URLs
• your_spotify_username with your Spotify username
• your_spotify_password with your Spotify password
• YOUR_WEBHOOK_URL with your Discord webhook (optional)

⁠Step 4: Access the Web Interface

1. Open http://your-server-ip:8080 in your browser
2. Check the Dashboard for download statistics
3. Go to Configuration to update settings without restarting
4. Monitor real-time logs to see what's happening

⁠Step 5: Understanding the Process

1. First Run: Spotarr scans your playlists and downloads all tracks
2. Ongoing: Every hour (configurable), it checks for new tracks
3. Smart Detection: Only downloads tracks that aren't already in your library
4. Quality Fallback: If high quality fails, automatically tries lower quality
5. Error Handling: Clear notifications about premium requirements or region blocks

⁠🚀 Quick Start

⁠Docker Compose (Recommended)

version: "3.8"
services:
  spotarr:
    image: linanail/spotarr:latest
    container_name: spotarr
    environment:
      - PLAYLIST_URLS=https://open.spotify.com/playlist/YOUR_PLAYLIST_ID
      - SPOTIFY_USERNAME=your_spotify_username
      - SPOTIFY_PASSWORD=your_spotify_password
      - DOWNLOAD_DIRECTORY=/downloads
      - WEBHOOK_URLS=https://discord.com/api/webhooks/YOUR_WEBHOOK_URL
    volumes:
      - /path/to/music:/downloads
      - /path/to/config:/app/config
    ports:
      - "8080:8080"
    restart: unless-stopped

⁠Docker Run

docker run -d \
  --name spotarr \
  -p 8080:8080 \
  -e PLAYLIST_URLS="https://open.spotify.com/playlist/YOUR_PLAYLIST_ID" \
  -e SPOTIFY_USERNAME="your_spotify_username" \
  -e SPOTIFY_PASSWORD="your_spotify_password" \
  -e DOWNLOAD_DIRECTORY="/downloads" \
  -v /path/to/music:/downloads \
  -v /path/to/config:/app/config \
  linanail/spotarr:latest

⁠📋 Environment Variables

⁠Required

⁠Optional

⁠Infrastructure Configuration (Docker/Environment Only)

⁠User Configuration (Web Interface Only)

🎉 All user settings are now managed through the web interface!

Access the web interface at http://localhost:8080 to configure:

• Playlist URLs: Spotify playlist URLs to monitor
• Webhook URLs: Discord webhook URLs for notifications
• Check Intervals: How often to check for changes (60-86400 seconds / 1min-24hrs)
• Scrape Intervals: Lightweight check frequency (60-3600 seconds / 1min-1hr)
• Audio Quality: Download quality (NORMAL, HIGH, VERY_HIGH)
• Notification Settings: Control webhook spam for common errors
• Advanced Settings: Retry counts (0-10), cleanup options, etc.
• Sync Button: Manually trigger playlist synchronization

⁠Configuration Validation Ranges

⁠📁 Volume Mounts

⁠🌐 Using the Web Interface

Access the web interface at http://your-server:8080

⁠Dashboard Page

• Statistics Overview: See total downloads, failed attempts, and success rate
• Recent Downloads: View your last downloaded tracks with file sizes
• System Status: Check if Spotarr is running and connected to Spotify
• Quick Actions: Refresh data or restart monitoring

⁠Configuration Page

• Add Playlists: Paste Spotify playlist URLs (one per line)
• Set Quality: Choose NORMAL, HIGH, or VERY_HIGH audio quality
• Configure Webhooks: Add Discord webhook URLs for notifications
• Adjust Timing: Set how often to check for new tracks (default: 1 hour)
• Save Settings: Changes apply immediately without restart

⁠Logs Page

• Real-Time Logs: Watch downloads happen live
• Error Tracking: See why downloads fail (premium required, region blocks, etc.)
• Auto-Refresh: Logs update automatically every few seconds
• Download History: Full audit trail of all download attempts

⁠🔔 Advanced Discord Integration

⁠Rich Embed Notifications

Spotarr sends beautiful, information-rich Discord embeds that rival Sonarr/Radarr:

• Album Artwork Thumbnails - High-quality cover art from Spotify's CDN
• Comprehensive Metadata - Artist, album, track number, duration, release date
• Download Progress - Real-time status updates with progress indicators
• File Information - File sizes, quality levels, and download speeds
• Clickable Spotify Links - Direct links to tracks and albums
• Color-Coded Status - Green for success, red for failures, yellow for warnings

⁠Smart Webhook Events

• ✅ Download Started - Track begins downloading with quality and estimated time
• 🎵 Download Completed - Success notification with file details and download time
• ❌ Download Failed - Detailed error analysis with suggested solutions
• 📋 Playlist Scanned - New track discovery with batch download summaries
• 🔄 Quality Fallback - Automatic quality reduction notifications
• ⚠️ Premium Required - Clear messaging about Spotify Premium limitations

⁠Advanced Webhook Features

• Rate Limit Handling - Automatic Discord rate limit compliance
• Batch Notifications - Combine multiple events to reduce spam
• Error Categorization - Different notification styles for different error types
• Retry Notifications - Updates when failed downloads are retried
• Statistics Summaries - Daily/weekly download reports

⁠🎵 Audio Quality

⁠� Practical Usage Examples

⁠Example 1: Basic Music Collection

Monitor your main playlist and download everything in high quality:

environment:
  - PLAYLIST_URLS=https://open.spotify.com/playlist/37i9dQZF1DX0XUsuxWHRQd
  - AUDIO_QUALITY=HIGH
  - CHECK_INTERVAL=28800 # Full cache invalidation every 8 hours
  - SCRAPE_INTERVAL_MIN=180 # Lightweight checks every 3-10 minutes
  - SCRAPE_INTERVAL_MAX=600

⁠Example 2: Multiple Playlists with Discord

Monitor several playlists and get Discord notifications:

environment:
  - PLAYLIST_URLS=|
    https://open.spotify.com/playlist/37i9dQZF1DX0XUsuxWHRQd
    https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M
    https://open.spotify.com/playlist/37i9dQZEVXbMDoHDwVN2tF
  - WEBHOOK_URLS=https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE
  - AUDIO_QUALITY=VERY_HIGH

⁠Example 3: Plex Media Server Integration

Download directly to your Plex music library:

volumes:
  - /path/to/plex/music:/downloads
environment:
  - DOWNLOAD_DIRECTORY=/downloads
  - CREATE_PLAYLIST_FOLDERS=true # Organize by playlist
  - FILENAME_FORMAT={artist} - {album} - {track_number:02d} - {title}.ogg

⁠Example 4: Low-Resource Setup

For Raspberry Pi or low-power devices:

environment:
  - AUDIO_QUALITY=NORMAL # Lower quality = smaller files
  - CHECK_INTERVAL=7200 # Full check every 2 hours
  - SCRAPE_INTERVAL_MIN=300 # Lightweight checks (60-3600 seconds / 1min-1hr)
  - SCRAPE_INTERVAL_MAX=900 # Max interval (60-3600 seconds / 1min-1hr)
  - CONCURRENT_DOWNLOADS=1
  - DEBUG_LOGS=false

⁠Example 5: Debug Mode

Troubleshoot issues with detailed logging:

environment:
  - DEBUG_LOGS=true
  - LOG_LEVEL=DEBUG
  - DEBUG_REGION_DETECTION=true
  - NOTIFY_PREMIUM_ERRORS=true # Get Discord alerts for premium issues

⁠� Troubbleshooting Guide

⁠Common Issues & Solutions

⁠"Connection refused" errors

Problem: [Errno 111] Connection refused in logs Solutions:

1. This is normal: Temporary Spotify server connectivity issues
2. Web interface works: Configuration interface remains available at :8080
3. Auto-retry: Spotarr automatically retries connections every 5 minutes
4. Check network: Ensure container has internet access
5. Wait it out: Usually resolves within 10-30 minutes

⁠"Cannot get alternative track" errors

Problem: Tracks fail to download with this error Solutions:

1. Get Spotify Premium - Most high-quality downloads require Premium
2. Lower quality: Set AUDIO_QUALITY=HIGH or AUDIO_QUALITY=NORMAL
3. Check account: Ensure you're using Premium credentials
4. Wait and retry: Sometimes temporary Spotify server issues

⁠Web interface not accessible

Problem: Can't reach http://your-server:8080 Solutions:

1. Check firewall: Ensure port 8080 is open
2. Verify networking: Use network_mode: host or proper port mapping
3. Check logs: Look for "Starting React web interface" message
4. Try different port: Change WEB_INTERFACE_PORT=8081

⁠Permission errors in downloads

Problem: "Permission denied" when saving files Solutions:

1. Set PUID/PGID: Match your user ID (id command shows your IDs)
2. Check directory permissions: Ensure download folder is writable
3. Use proper paths: Avoid spaces and special characters in paths

⁠No new tracks detected

Problem: Spotarr doesn't find new tracks you added Solutions:

1. Check playlist URLs: Ensure they're public or you're the owner
2. Wait for scan: Default is 1 hour, or restart container
3. Check logs: Look for "Playlist scanned" messages
4. Verify credentials: Ensure Spotify login is working

⁠Debug Mode Setup

Enable detailed logging to diagnose issues:

environment:
  - DEBUG_LOGS=true
  - LOG_LEVEL=DEBUG
  - DEBUG_REGION_DETECTION=true
  - NOTIFY_PREMIUM_ERRORS=true

⁠Getting Help

1. Check logs first: Most issues show clear error messages
2. Enable debug mode: Get detailed information about what's happening
3. Check Discord: Error notifications often contain helpful details
4. Verify setup: Ensure all required environment variables are set

⁠📊 File Organization

Downloaded files are organized as:

/downloads/
├── Artist - Album - 01 - Track Name.ogg
├── Artist - Album - 02 - Track Name.ogg
└── ...

⁠🔒 Security Notes

• Store Spotify credentials securely
• Use Docker secrets for production deployments
• Regularly update the container image
• Consider using a reverse proxy with SSL

⁠📈 Performance

• Memory Usage: ~100-200MB typical
• CPU Usage: Low, spikes during downloads
• Storage: Depends on music library size
• Network: Moderate during active downloads

⁠� Roadmap & Future Integrations

⁠🎬 Media Server Integration (Coming Soon)

• Plex Integration - Automatic library scanning after downloads complete and sync the playlists with Lidarr and Plex
• Jellyfin Support - Native integration with Jellyfin media servers
• Emby Compatibility - Direct integration with Emby libraries

⁠📱 Enhanced Mobile Experience

• Progressive Web App (PWA) - Install Spotarr as a mobile app
• Push Notifications - Mobile notifications for download completion
• Offline Dashboard - View statistics and logs without internet connection

⁠🔧 Advanced Features

• Multi-User Support - Individual user accounts with separate playlists
• Playlist Synchronization - Two-way sync between Spotarr and Spotify
• Smart Playlists - Auto-generated playlists based on download patterns
• Metadata Enhancement - Integration with MusicBrainz and Last.fm
• Duplicate Detection - Intelligent duplicate file management

⁠🎵 Audio Processing

• Format Conversion - Convert to MP3, FLAC, AAC on-the-fly
• Metadata Tagging - Enhanced ID3 tag management and artwork embedding
• Audio Normalization - Consistent volume levels across tracks
• Quality Analysis - Audio quality verification and reporting

⁠📊 Analytics & Insights

• Listening Analytics - Track your music discovery patterns
• Genre Analysis - Automatic genre classification and statistics
• Artist Discovery - Recommendations based on download history
• Playlist Health - Monitor playlist changes and track availability

⁠📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Important Notice: This application is for personal use only. Ensure you comply with Spotify's Terms of Service and local copyright laws. Spotarr is designed to help you manage your personal music collection and does not encourage piracy or copyright infringement. Spotarr is designed to work with music you have the right to download and is intended for personal backup and offline listening purposes.