Allstarr

A media server proxy that integrates music streaming providers with your local library. Works with Jellyfin servers. When a song isn't in your local library, it gets fetched from your configured provider, downloaded, and served to your client. The downloaded song then lives in your library for next time.

Quick Start

Using Docker (recommended):

# 1. Download the docker-compose.yml file and the .env.example file to a folder on the machine you have Docker

curl -O https://raw.githubusercontent.com/SoPat712/allstarr/refs/heads/main/docker-compose.yml \
     -O https://raw.githubusercontent.com/SoPat712/allstarr/refs/heads/main/.env.example

# 2. Configure environment
cp .env.example .env
vi .env  # Edit with your settings

# 3. Pull the latest image
docker-compose pull

# 4. Start services
docker-compose up -d

# 5. Check status
docker-compose ps
docker-compose logs -f

The proxy will be available at http://localhost:5274.

Web Dashboard

Allstarr includes a web UI for easy configuration and playlist management, accessible at http://localhost:5275 <img width="1664" height="1101" alt="image" src="https://github.com/user-attachments/assets/9159100b-7e11-449e-8530-517d336d6bd2" />

Features

• Playlist Management: Link Jellyfin playlists to Spotify playlists with just a few clicks
• Provider Matching: It should fill in the gaps of your Jellyfin library with tracks from your selected provider
• WebUI: Update settings without manually editing .env files
• Music: Using multiple sources for music (optimized for SquidWTF right now, though)
• Lyrics: Using multiple sources for lyrics - Jellyfin local, Spotify Lyrics API, LyricsPlus (multi-source), and LRCLib
• Scrobbling: Track your listening history to Last.fm and ListenBrainz with automatic scrobbling
• Downloads Management: View, download, and manage your kept files through the web UI
• Diagnostics: Monitor system performance, memory usage, cache statistics, and endpoint usage

Quick Setup with Web UI

1. Access the dashboard at http://localhost:5275
2. Configure Spotify (Configuration tab):
   • Enable Spotify API
   • Add your sp_dc cookie from Spotify (see instructions in UI)
   • The cookie age is automatically tracked
3. Link playlists (Link Playlists tab):
   • View all your Jellyfin playlists
   • Click "Link to Spotify" on any playlist
   • Paste the Spotify playlist ID, URL, or spotify:playlist: URI
   • Accepts formats like:
     • 37i9dQZF1DXcBWIGoYBM5M (just the ID)
     • spotify:playlist:37i9dQZF1DXcBWIGoYBM5M (Spotify URI)
     • https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M (full URL)
4. Restart Allstarr to apply changes (should be a banner)

Then, proceeed to Active Playlists, which shows you which Spotify playlists are currently being monitored and filled with tracks, and lets you do a bunch of useful operations on them.

Configuration Persistence

The web UI updates your .env file directly. Allstarr reloads that file on startup, so a normal container restart is enough for UI changes to take effect. In development mode, the .env file is in your project root. In Docker, it's at /app/.env.

There's an environment variable to modify this.

Recommended workflow: Use the sp_dc cookie method alongside the Spotify Import Plugin.

Nginx Proxy Setup (Optional)

This service only exposes ports internally. You can use nginx to proxy to it, however PLEASE take significant precautions before exposing this! Everyone decides their own level of risk, but this is currently untested, potentially dangerous software, with almost unfettered access to your Jellyfin server. My recommendation is use Tailscale or something similar!

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000" always;
    add_header X-Content-Type-Options "nosniff" always;

    # Streaming settings
    proxy_buffering off;
    proxy_request_buffering off;
    proxy_read_timeout 600s;

    location / {
        proxy_pass http://allstarr:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Security: Don't trust me or my code, or anyone for that matter (Zero-trust, get it?), use Tailscale or Pangolin or Cloudflare Zero-Trust or anything like it please

Why "Allstarr"?

This project brings together all the music streaming providers into one unified library - making them all stars in your collection.

Features

• Dual Backend Support: Works with Jellyfin
• Multi-Provider Architecture: Pluggable system for streaming providers (Deezer, Qobuz, SquidWTF)
• Transparent Proxy: Sits between your music clients and media server
• Automatic Search: Searches streaming providers when songs aren't local
• On-the-Fly Downloads: Songs download and cache for future use
• Favorite to Keep: When you favorite an external track, it's automatically copied to a permanent /kept folder separate from the cache
• External Playlist Support: Search and download playlists from Deezer, Qobuz, and SquidWTF with M3U generation
• Hi-Res Audio: SquidWTF supports up to 24-bit/192kHz FLAC
• Full Metadata: Downloaded files include complete ID3 tags (title, artist, album, track number, year, genre, BPM, ISRC, etc.) and cover art
• Organized Library: Downloads save in Artist/Album/Track folder structure
• Artist Deduplication: Merges local and streaming artists to avoid duplicates
• Album Enrichment: Adds missing tracks to local albums from streaming providers
• Cover Art Proxy: Serves cover art for external content
• Spotify Playlist Injection (Jellyfin only): Intercepts Spotify Import plugin playlists (Release Radar, Discover Weekly) and fills them with tracks auto-matched from streaming providers
• Lyrics Support: Multi-source lyrics fetching from Jellyfin local files, Spotify Lyrics API (synchronized), LyricsPlus (multi-source aggregator), and LRCLib (community database)
• Scrobbling Support: Track your listening history to Last.fm and ListenBrainz

Supported Backends

Jellyfin

Jellyfin is a free and open-source media server. Allstarr connects via the Jellyfin API using your Jellyfin user login. (I plan to move this to api key if possible)

Compatible Jellyfin clients:

• Feishin (Mac/Windows/Linux) <img width="1691" height="1128" alt="image" src="https://github.com/user-attachments/assets/c602f71c-c4dd-49a9-b533-1558e24a9f45" />

• Musiver (Android/iOS/Windows/Android) <img width="523" height="1025" alt="image" src="https://github.com/user-attachments/assets/135e2721-5fd7-482f-bb06-b0736003cfe7" />

• Finamp (Android/iOS)

• Finer Player (iOS/iPadOS/macOS/tvOS)

Want to improve client compatibility? Pull requests are welcome!

Incompatible Clients

These clients are not compatible with Allstarr due to architectural limitations:

• Symfonium - Uses offline-first architecture and never queries the server for searches, making streaming provider integration impossible. See details

See CLIENTS.md for more detailed client information.

Supported Music Providers

• SquidWTF - Quality: FLAC (Hi-Res 24-bit/192kHz & CD-Lossless 16-bit/44.1kHz), AAC
• Deezer - Quality: FLAC, MP3_320, MP3_128
• Qobuz - Quality: FLAC, FLAC_24_HIGH (Hi-Res 24-bit/192kHz), FLAC_24_LOW, FLAC_16, MP3_320

Choose your preferred provider via the MUSIC_SERVICE environment variable. Additional providers may be added in future releases.

Requirements

• A running media server:
  • Jellyfin: Any recent version with API access enabled
• Docker and Docker Compose (recommended) - includes Redis and Spotify Lyrics API sidecars
  • Redis is used for caching (search results, playlists, lyrics, etc.)
  • Spotify Lyrics API provides synchronized lyrics for Spotify tracks
• Credentials for at least one music provider (IF NOT USING SQUIDWTF):
  • Deezer: ARL token from browser cookies
  • Qobuz: User ID + User Auth Token from browser localStorage (see Wiki guide)
• OR .NET 10.0 SDK for manual installation (requires separate Redis setup)

Configuration

Environment Setup

1. Create your environment file

   cp .env.example .env
   

2. Edit the .env file with your configuration:

   Server Settings:

   # Backend selection
   BACKEND_TYPE=Jellyfin