pirus999/magic-lists-ai-curator repository overview

AI-assisted playlists for your own music library.

MagicLists adds the kind of curated, evolving playlists you’d expect from Spotify or Apple Music—except it works entirely on your self-hosted Navidrome or Jellyfin server. No subscriptions, no renting your music back. Just smart mixes generated from the library you already own.

⁠What it does

• 🎵 This Is (Artist) — Builds a definitive playlist for any artist in your library, combining hits, deep cuts, and featured appearances without duplicates.
• 📻 Artist Radio — Automatically search for similar artists for your selected one, then create a distinctive mixed radio playlist from your selection.
• 🎸 Genre Mix — Creates curated playlists from your complete genre collections, using AI to craft the perfect mix of tracks.
• 🔄 Re-Discover — Rotates tracks you haven't played in a while, helping you fall back in love with your collection.
• ⏰ Auto-Refresh — Keep playlists fresh with daily, weekly, or monthly updates.
• 🐳 Quick Setup — Simple Docker install; get started in minutes.

⁠Why it matters

Navidrome and Jellyfin users already own their music. MagicLists brings modern curation tools into that world—so your playlists feel alive, not static, and your collection keeps surprising you.

⁠Get more Information on:

GitHub⁠

⁠Installation

⁠Recommended: Add to Your Existing Docker Compose

Why this method? Your MagicLists container will be on the same network as Navidrome, making connection simple and reliable. This also enables future features like audio analysis that require local file access. You also could use this compose to spin up a Szandalone Container.

1. Add MagicLists to your existing docker-compose.yml (the one that runs Navidrome):

   services:
     navidrome:
       # ... your existing Navidrome or Jellyfin config ...
     
     magiclists:
       image: pirus999/magic-lists-ai-curator:latest
       container_name: magiclists
       ports:
         - "4545:8000"
       environment:
         - SERVER_TYPE=navidrome # or jellyfin
         - NAVIDROME_URL=http://navidrome:4533 # for Jellyfin use: JELLYFIN_URL=http://jellyfin:8096
         - NAVIDROME_USERNAME=your_username # for Jellyfin use: JELLYFIN_USERNAME or JELLYFIN_API_KEY
         - NAVIDROME_PASSWORD=your_password # for Jellyfin use: JELLYFIN_PASSWORD or JELLYFIN_API_KEY
         - DATABASE_PATH=/app/data/magiclists.db # Required: Database location
           - AI_PROVIDER=google            # Optional: openrouter, groq, google, ollama
           - AI_API_KEY=your_google_api_key  # Optional, for OpenRouter/Groq/Google
           - AI_MODEL=gemini-3.5-flash # Select one from your AI provider
           - DESCRIPTION_AI_MODEL=gemma-4-26b-a4b-it # Optional, select a smaller model for Playlist descriptions
       volumes:
         - ./magiclists-data:/app/data          # Persist configuration
       restart: unless-stopped

1. Update the environment variables with your Navidrome credentials
2. Start the stack:

   docker-compose up -d

1. Access MagicLists at http://localhost:4545⁠

Note: The NAVIDROME_URL uses the container name (navidrome) as the hostname. If your Navidrome service has a different name in your compose file, update this accordingly.

⁠Alternative: Standalone Docker Run Container

Use this if you can't or don't want to modify your existing Docker Compose setup.

Docker Run If Navidrome is publicly accessible: Use your public Navidrome URL (e.g., https://music.yourdomain.com⁠):

   docker run -d \
      --name magiclists \
      -p 4545:8000 \
      -e NAVIDROME_URL=https://music.yourdomain.com \
      -e NAVIDROME_USERNAME=your_username \
      -e NAVIDROME_PASSWORD=your_password \
      -e DATABASE_PATH=/app/data/magiclists.db \
      -e AI_PROVIDER=openrouter \
      -e AI_API_KEY=your_openrouter_api_key \
      -e AI_MODEL=dots-studio/dots-3-note-preview:free \
      -v ./magiclists-data:/app/data \
      pirus999/magic-lists-ai-curator:latest 

⁠Environment

⁠License

MIT License

⁠Support

⁠View README⁠ on GitHub

⁠Legal Disclaimer

No Warranty: This software is provided "as is" without warranty of any kind, express or implied.

User Responsibility: You are solely responsible for:

• Ensuring you have proper rights to any music content processed through this application
• Any data transmitted to third-party AI services
• Backup of your music library before use
• Any modifications made to your playlists or library

Limitation of Liability: The developers shall not be liable for any damages including but not limited to data loss, corruption of music libraries, or any other direct or indirect damages arising from use of this software.

Third-party Services: This application integrates with external AI services. Your use of these services is subject to their respective terms of service.

By using this software, you acknowledge and accept these terms.