allstarr/.env.example

# ===== BACKEND SELECTION =====
# Choose which media server backend to use: Subsonic or Jellyfin
BACKEND_TYPE=Jellyfin

# ===== ADMIN NETWORK ACCESS (PORT 5275) =====
# Keep false to bind admin UI to localhost only (recommended)
# Set true only if you need LAN access from another device
ADMIN_BIND_ANY_IP=false

# Comma-separated trusted CIDR ranges allowed to access admin port when bind is enabled
# Examples: 192.168.1.0/24,10.0.0.0/8
ADMIN_TRUSTED_SUBNETS=

# ===== CORS POLICY =====
# Cross-origin requests are disabled by default.
# Set explicit origins if you need browser access from another host.
# Example: https://my-jellyfin.example.com,http://localhost:3000
CORS_ALLOWED_ORIGINS=

# Explicit allowed methods and headers for CORS preflight.
# Keep these restrictive unless you have a concrete requirement.
CORS_ALLOWED_METHODS=GET,POST,PUT,PATCH,DELETE,OPTIONS,HEAD
CORS_ALLOWED_HEADERS=Accept,Authorization,Content-Type,Range,X-Requested-With,X-Emby-Authorization,X-MediaBrowser-Token

# Set true only when your allowed origins require cookies/auth credentials.
CORS_ALLOW_CREDENTIALS=false

# ===== REDIS CACHE (REQUIRED) =====
# Redis is the primary cache for all runtime data (search results, playlists, lyrics, etc.)
# File cache (/app/cache) acts as a persistence layer for cold starts
# Redis snapshots to disk every 60 seconds + AOF for durability

# Redis data persistence directory (default: ./redis-data)
# Contains Redis RDB snapshots and AOF logs for crash recovery
REDIS_DATA_PATH=./redis-data

# ===== CACHE TTL SETTINGS =====
# Configure how long different types of data are cached
# Longer durations reduce API calls but may show stale data
# All values are configurable via Web UI (Configuration tab > Cache Settings)
# Changes require container restart to apply

# Search results cache duration in minutes (default: 120 = 2 hours)
CACHE_SEARCH_RESULTS_MINUTES=120

# Playlist cover images cache duration in hours (default: 168 = 1 week)
CACHE_PLAYLIST_IMAGES_HOURS=168

# Spotify playlist items cache duration in hours (default: 168 = 1 week)
CACHE_SPOTIFY_PLAYLIST_ITEMS_HOURS=168

# Spotify matched tracks cache duration in days (default: 30 days)
# This is the mapping of Spotify IDs to local/external tracks
CACHE_SPOTIFY_MATCHED_TRACKS_DAYS=30

# Lyrics cache duration in days (default: 14 = 2 weeks)
CACHE_LYRICS_DAYS=14

# Genre data cache duration in days (default: 30 days)
CACHE_GENRE_DAYS=30

# External metadata (SquidWTF/Deezer/Qobuz) cache duration in days (default: 7 days)
CACHE_METADATA_DAYS=7

# Odesli URL conversion cache duration in days (default: 60 days)
CACHE_ODESLI_LOOKUP_DAYS=60

# Jellyfin proxy images cache duration in days (default: 14 = 2 weeks)
CACHE_PROXY_IMAGES_DAYS=14


# ===== SUBSONIC/NAVIDROME CONFIGURATION =====
# Server URL (required if using Subsonic backend)
SUBSONIC_URL=http://localhost:4533

# ===== JELLYFIN CONFIGURATION =====
# Server URL (required if using Jellyfin backend)
JELLYFIN_URL=http://localhost:8096

# API key for SERVER-SIDE operations only (get from Jellyfin Dashboard > API Keys)
# This is used by Allstarr to query Jellyfin's library on behalf of the server
# CLIENT authentication is handled transparently - clients authenticate directly with Jellyfin
JELLYFIN_API_KEY=

# User ID for SERVER-SIDE library queries (get from Jellyfin Dashboard > Users > click user > check URL)
# This determines which user's library Allstarr queries when searching/browsing
JELLYFIN_USER_ID=

# Music library ID (optional, auto-detected if not set)
# If you have multiple libraries, set this to filter to music only
JELLYFIN_LIBRARY_ID=

# ===== MUSIC SOURCE SELECTION =====
# Music service to use: SquidWTF, Deezer, or Qobuz (default: SquidWTF)
MUSIC_SERVICE=SquidWTF

# Base directory for all downloads (default: ./downloads)
# This creates three subdirectories:
# - downloads/permanent/ - Permanently downloaded tracks (STORAGE_MODE=Permanent)
# - downloads/cache/ - Temporarily cached tracks (STORAGE_MODE=Cache)
# - downloads/kept/ - Favorited external tracks (always permanent)
Library__DownloadPath=./downloads

# ===== SQUIDWTF CONFIGURATION =====
# Preferred audio quality (optional, default: LOSSLESS)
# - HI_RES or HI_RES_LOSSLESS: 24-bit/192kHz FLAC (highest quality)
# - FLAC or LOSSLESS: 16-bit/44.1kHz FLAC (CD quality, recommended)
# - HIGH: 320kbps AAC (high quality, smaller files)
# - LOW: 96kbps AAC (low quality, smallest files)
# If not specified, LOSSLESS (16-bit FLAC) will be used
SQUIDWTF_QUALITY=LOSSLESS

# ===== DEEZER CONFIGURATION =====
# Deezer ARL token (required if using Deezer)
# See README.md for instructions on how to get this token
DEEZER_ARL=your-deezer-arl-token

# Fallback ARL token (optional)
DEEZER_ARL_FALLBACK=

# Preferred audio quality: FLAC, MP3_320, MP3_128 (optional)
# If not specified, the highest available quality for your account will be used
DEEZER_QUALITY=

# ===== QOBUZ CONFIGURATION =====
# Qobuz user authentication token (required if using Qobuz)
# Get this from your browser after logging into play.qobuz.com
# See README.md for detailed instructions
QOBUZ_USER_AUTH_TOKEN=

# Qobuz user ID (required if using Qobuz)
# Get this from your browser after logging into play.qobuz.com
QOBUZ_USER_ID=

# Preferred audio quality: FLAC, FLAC_24_HIGH, FLAC_24_LOW, FLAC_16, MP3_320 (optional)
# If not specified, the highest available quality will be used
QOBUZ_QUALITY=

# ===== MUSICBRAINZ CONFIGURATION =====
# Enable MusicBrainz metadata lookups (optional, default: true)
MUSICBRAINZ_ENABLED=true

# Optional MusicBrainz account credentials for authenticated requests
MUSICBRAINZ_USERNAME=
MUSICBRAINZ_PASSWORD=

# ===== GENERAL SETTINGS =====
# External playlists support (optional, default: true)
# When enabled, allows searching and downloading playlists from Deezer/Qobuz
# Starring a playlist triggers automatic download of all tracks and creates an M3U file
ENABLE_EXTERNAL_PLAYLISTS=true

# Playlists directory name (optional, default: playlists)
# M3U playlist files will be created in {DOWNLOAD_PATH}/{PLAYLISTS_DIRECTORY}/
PLAYLISTS_DIRECTORY=playlists

# Explicit content filter (optional, default: All)
# - All: Show all tracks (no filtering)
# - ExplicitOnly: Exclude clean/edited versions, keep original explicit content
# - CleanOnly: Only show clean content (naturally clean or edited versions)
# Note: This only works with Deezer, Qobuz doesn't expose explicit content flags
EXPLICIT_FILTER=All

# Download mode (optional, default: Track)
# - Track: Download only the played track
# - Album: When playing a track, download the entire album in background
#          The played track is downloaded first, remaining tracks are queued
DOWNLOAD_MODE=Track

# Storage mode (optional, default: Cache)
# - Permanent: Files are saved to the library permanently and registered in the media server
# - Cache: Files are stored in /tmp and automatically cleaned up after CACHE_DURATION_HOURS
#          Not registered in media server, ideal for streaming without library bloat
#          Note: On Linux/Docker, you can customize cache location by setting TMPDIR environment variable
STORAGE_MODE=Cache

# Cache duration in hours (optional, default: 1)
# Files older than this duration will be automatically deleted when STORAGE_MODE=Cache
# Based on last access time (updated each time the file is streamed)
# Cache location: /tmp/allstarr-cache (or $TMPDIR/allstarr-cache if TMPDIR is set)
CACHE_DURATION_HOURS=1

# ===== SPOTIFY PLAYLIST INJECTION (JELLYFIN ONLY) =====
# REQUIRES: Jellyfin Spotify Import Plugin (https://github.com/Viperinius/jellyfin-plugin-spotify-import)
# This feature intercepts Spotify Import plugin playlists and fills them with tracks from external providers
# Uses JELLYFIN_URL and JELLYFIN_API_KEY configured above (no separate credentials needed)

# Enable Spotify playlist injection (optional, default: false)
SPOTIFY_IMPORT_ENABLED=false

# Matching interval: How often to run track matching (in hours)
# Spotify playlists like Discover Weekly update once per week, Release Radar updates weekly
# Set to 0 to only run once on startup (manual trigger via admin UI still works)
# Default: 24 hours
SPOTIFY_IMPORT_MATCHING_INTERVAL_HOURS=24

# Playlists configuration (JSON ARRAY FORMAT - managed by web UI)
# Format: [["PlaylistName","SpotifyPlaylistId","first|last"],...]
# - PlaylistName: Name as it appears in Jellyfin
# - SpotifyPlaylistId: Get from Spotify URL (e.g., 37i9dQZF1DXcBWIGoYBM5M)
#   Accepts: spotify:playlist:ID, full URL, or just the ID
# - first|last: Where to position local tracks (first=local tracks first, last=external tracks first)
#
# Example:
# SPOTIFY_IMPORT_PLAYLISTS=[["Discover Weekly","37i9dQZEVXcV6s7Dm7RXsU","first"],["Release Radar","37i9dQZEVXbng2vDHnfQlC","first"]]
#
# RECOMMENDED: Use the web UI (Link Playlists tab) to manage playlists instead of editing this manually
SPOTIFY_IMPORT_PLAYLISTS=[]

# ===== SPOTIFY DIRECT API (RECOMMENDED - ENABLES TRACK ORDERING & LYRICS) =====
# This is the preferred method for Spotify playlist integration.
# Provides: Correct track ordering, ISRC-based exact matching, synchronized lyrics
# Does NOT require the Jellyfin Spotify Import plugin (can work standalone)

# Enable direct Spotify API access (default: false)
SPOTIFY_API_ENABLED=false

# Spotify session cookie (sp_dc) - REQUIRED for editorial playlists
# Editorial playlists (Release Radar, Discover Weekly, etc.) require authentication
# via session cookie because they're not accessible through the official API.
#
# To get your sp_dc cookie:
# 1. Open https://open.spotify.com in your browser and log in
# 2. Open DevTools (F12) → Application → Cookies → https://open.spotify.com
# 3. Find the cookie named "sp_dc" and copy its value
# 4. Note: This cookie expires periodically (typically every few months)
SPOTIFY_API_SESSION_COOKIE=

# Date when the session cookie was set (ISO 8601 format)
# Automatically set by the web UI when you update the cookie
# Used to track cookie age and warn when approaching expiration (~1 year)
SPOTIFY_API_SESSION_COOKIE_SET_DATE=

# Cache duration for playlist data in minutes (default: 60)
# Release Radar updates weekly, Discover Weekly updates Mondays
SPOTIFY_API_CACHE_DURATION_MINUTES=60

# Rate limit delay between API requests in milliseconds (default: 100)
SPOTIFY_API_RATE_LIMIT_DELAY_MS=100

# Prefer ISRC matching over fuzzy title/artist matching (default: true)
# ISRC provides exact track identification across different streaming services
SPOTIFY_API_PREFER_ISRC_MATCHING=true

# Spotify Lyrics API URL (default: http://spotify-lyrics:8080)
# Uses the spotify-lyrics-api sidecar service for fetching synchronized lyrics
# This service is automatically started in docker-compose
# Leave as default unless running a custom deployment
SPOTIFY_LYRICS_API_URL=http://spotify-lyrics:8080

# ===== SCROBBLING (LAST.FM, LISTENBRAINZ) =====
# Scrobble your listening history to Last.fm and/or ListenBrainz
# Tracks are scrobbled when you listen to at least half the track or 4 minutes (whichever comes first)
# Tracks shorter than 30 seconds are not scrobbled (per Last.fm rules)

# Enable scrobbling globally (default: false)
SCROBBLING_ENABLED=false

# Enable scrobbling for local library tracks (default: false)
# RECOMMENDED: Keep this disabled and use native Jellyfin plugins instead:
# - Last.fm: https://github.com/danielfariati/jellyfin-plugin-lastfm
# - ListenBrainz: https://github.com/lyarenei/jellyfin-plugin-listenbrainz
# This ensures Allstarr only scrobbles external tracks (Spotify, Deezer, Qobuz)
SCROBBLING_LOCAL_TRACKS_ENABLED=false

# Emit synthetic local "played" events from progress when local scrobbling is disabled (default: false)
# Only enable this if you explicitly need UserPlayedItems-based plugin triggering.
# Keep false to avoid duplicate local scrobbles with Jellyfin plugins.
SCROBBLING_SYNTHETIC_LOCAL_PLAYED_SIGNAL_ENABLED=false

# ===== LAST.FM SCROBBLING =====
# Enable Last.fm scrobbling (default: false)
SCROBBLING_LASTFM_ENABLED=false

# Last.fm API credentials (OPTIONAL - uses hardcoded credentials by default)
# Only set these if you want to use your own API account
# Get from: https://www.last.fm/api/account/create
SCROBBLING_LASTFM_API_KEY=
SCROBBLING_LASTFM_SHARED_SECRET=

# Last.fm username and password (for authentication)
# Password is only used to obtain session key via Mobile Authentication
# IMPORTANT: Do NOT quote passwords in Docker Compose .env files!
# Docker Compose handles special characters correctly without quotes.
SCROBBLING_LASTFM_USERNAME=
SCROBBLING_LASTFM_PASSWORD=

# Last.fm session key (automatically obtained via authentication)
# This key never expires unless you revoke it on Last.fm
# Use the Admin UI (Scrobbling tab) to authenticate and get your session key
SCROBBLING_LASTFM_SESSION_KEY=

# ===== LISTENBRAINZ SCROBBLING =====
# Enable ListenBrainz scrobbling (default: false)
# Only scrobbles external tracks (Spotify, Deezer, Qobuz) - local library tracks are not scrobbled
SCROBBLING_LISTENBRAINZ_ENABLED=false

# ListenBrainz user token (get from https://listenbrainz.org/settings/)
# To get your token:
# 1. Sign up or log in at https://listenbrainz.org
# 2. Go to https://listenbrainz.org/settings/
# 3. Copy your User Token
SCROBBLING_LISTENBRAINZ_USER_TOKEN=

# ===== DEBUG SETTINGS =====
# Enable detailed request logging (default: false)
# When enabled, logs every incoming HTTP request with full details:
# - Method, path, query string
# - Headers
# - Response status and timing
# Useful for debugging client issues and seeing what API calls are being made
DEBUG_LOG_ALL_REQUESTS=false

# Redact auth/query sensitive values in request logs (default: false).
# Set true if you want DEBUG_LOG_ALL_REQUESTS while still masking tokens.
DEBUG_REDACT_SENSITIVE_REQUEST_VALUES=false