Configuration Parameters

These are the parameters accepted for this script. You can pass them as environment variables using, for example, /deployment/deployment.yaml in this repository.

How to find jellyfin userid: * Log into Jellyfin from your browser as an admin * Go to Dashboard > “admin panel” > Users. * Click on the user’s name that you are interested * The User ID is visible in the URL (is the part just after = ): * http://your-jellyfin-server/web/index.html#!/useredit.html?userId=xxxxx

How to create an the jellyfin's API token: * The API Token, still as admin you can go to Dashboard > “Admin panel” > API Key and create a new one.

The mandatory parameter that you need to change from the example are this:

Parameter	Description	Default Value
JELLYFIN_URL	(Required) Your Jellyfin server's full URL	http://YOUR_JELLYFIN_IP:8096
JELLYFIN_USER_ID	(Required) Jellyfin User ID.	(N/A - from Secret)
JELLYFIN_TOKEN	(Required) Jellyfin API Token.	(N/A - from Secret)
EMBY_URL	(Required) Your Emby server's full URL	http://YOUR_EMBY_IP:8096
EMBY_USER_ID	(Required) Emby User ID.	(N/A - from Secret)
EMBY_TOKEN	(Required) Emby API Token.	(N/A - from Secret)
NAVIDROME_URL	(Required) Your Navidrome server's full URL	http://YOUR_JELLYFIN_IP:4553
NAVIDROME_USER	(Required) Navidrome User ID.	(N/A - from Secret)
NAVIDROME_PASSWORD	(Required) Navidrome user Password.	(N/A - from Secret)
LYRION_URL	(Required) Your Lyrion server's full URL	http://YOUR_LYRION_IP:9000
POSTGRES_USER	(Required) PostgreSQL username.	(N/A - from Secret)
POSTGRES_PASSWORD	(Required) PostgreSQL password.	(N/A - from Secret)
POSTGRES_DB	(Required) PostgreSQL database name.	(N/A - from Secret)
POSTGRES_HOST	(Required) PostgreSQL host.	postgres-service.playlist
POSTGRES_PORT	(Required) PostgreSQL port.	5432
REDIS_URL	(Required) URL for Redis.	redis://localhost:6379/0
GEMINI_API_KEY	(Required if AI_MODEL_PROVIDER is GEMINI) Your Google Gemini API Key.	(N/A - from Secret)
MISTRAL_API_KEY	(Required if AI_MODEL_PROVIDER is MISTRAL) Your Mistral API Key.	(N/A - from Secret)
OPENAI_API_KEY	(Required if AI_MODEL_PROVIDER is OPENAI) Your OpenAI / OpenRouter API Key.	(N/A - from Secret)

These parameters can be left as-is:

Parameter	Description	Default Value
TEMP_DIR	Temp directory for audio files	/app/temp_audio
CLEANING_SAFETY_LIMIT	Max number of albums deleted during cleaning	100
MUSIC_LIBRARIES	Comma-separated list of music libraries/folders for analysis. If empty, all libraries/folders are scanned. For Lyrion: Use folder paths like "/music/myfolder". For Jellyfin/Navidrome: Use library/folder names.	"" (empty - scan all)
ENABLE_PROXY_FIX	Enable Proxy Fix for Flask when behind a reverse proxy. Example Nginx configuration: config.py	false
WORKER_URL	This is the Url your worker instance runs on. The server instance uses this parameter to call the worker. Make sure to include /worker at the end of the url (e.g. http://worker.example.com:8029/worker)	false
WORKER_POSTGRES_HOST	This is the Url of your the postgres service on your server. The worker uses this to connect the postgres service the flask app uses too. Make sure to not include a protocol (like "http") (e.g. 100.000.00.00)	false
WORKER_REDIS_URL	This is the Url of your the redis service on your server. The worker uses this to connect to the redis service the flask app uses too. Make sure to include the protocol "redis://" and the dbindex "/0" (e.g. redis://100.000.00.00:6379/0)	false
TZ	Set the time zone of Flask and worker container	UTC

These are the default parameters used when launching analysis or clustering tasks. You can change them directly in the front-end.

Parameter	Description	Default Value
CLAP - TEXT SEARCH AND MUSICNN MODEL
CLAP_ENABLED	If false disable CLAP model during the analysis and the use of Text Search functionality.	true
CLAP_PYTHON_MULTITHREADS	CPU threading for CLAP analysis. False (default) = Use ONNX internal threading (recommended). True = Use Python ThreadPoolExecutor	false
PER_SONG_MODEL_RELOAD	Model reloading strategy. true (default) = Unload MusiCNN and CLAP after each song (stable VRAM, slower). false = MusiCNN reloads every 20 songs, CLAP at album end (faster but may accumulate VRAM)	true
Analysis General
NUM_RECENT_ALBUMS	Number of recent albums to scan (0 for all).	0
TOP_N_MOODS	Number of top moods per track for feature vector.	5
CLAP_ENABLED	Enable or disable CLAP model for text-to-audio search capabilities.	true
MULAN_ENABLED	Enable or disable MuLan (MuQ) model for text-to-audio search capabilities. STILL IN DEVELOPING	false
CLAP_PYTHON_MULTITHREADS	CPU threading for CLAP analysis. False (default) = Use ONNX internal threading (recommended). True = Use Python ThreadPoolExecutor	false
Clustering General
ENABLE_CLUSTERING_EMBEDDINGS	Whether to use audio embeddings (True) or score-based features (False) for clustering.	true
CLUSTER_ALGORITHM	Default clustering: kmeans, dbscan, gmm, spectral.	kmeans
MAX_SONGS_PER_CLUSTER	Max songs per generated playlist segment.	0
MAX_SONGS_PER_ARTIST	Max songs from one artist per cluster.	3
MAX_DISTANCE	Normalized distance threshold for tracks in a cluster.	0.5
CLUSTERING_RUNS	Iterations for Monte Carlo evolutionary search.	1000
TOP_N_PLAYLISTS	POST Clustering it keep only the top N diverse playlist.	8
USE_GPU_CLUSTERING	When true enalbe the use of GPU on K-Means, DBSCAN and PCA	false
Similarity General
INDEX_NAME	Name of the index, no need to change.	music_library
VOYAGER_EF_CONSTRUCTION	Number of element analyzed to create the neighbor list in the index.	1024
VOYAGER_M	Number of neighbore More = higher accuracy.	64
VOYAGER_QUERY_EF	Number neighbor analyzed during the query.	1024
VOYAGER_METRIC	Different tipe of distance metrics: angular, euclidean,dot	angular
SIMILARITY_ELIMINATE_DUPLICATES_DEFAULT	It enable the possibility of use the MAX_SONGS_PER_ARTIST also in similar song	true
SIMILARITY_RADIUS_DEFAULT	Default behavior for radius similarity mode. When true, similarity results may be re-ordered using the radius (bucketed) algorithm for better listening paths.	true
Sonic Fingerprint General
SONIC_FINGERPRINT_NEIGHBORS	Default number of track for the sonic fingerprint	100
Song Alchemy General
ALCHEMY_DEFAULT_N_RESULTS	Number of similar songs to return when creating the Alchemy result (default).	100
ALCHEMY_MAX_N_RESULTS	Maximum number of similar songs to return for Alchemy results.	200
ALCHEMY_TEMPERATURE	Temperature for probabilistic sampling in Song Alchemy (softmax temperature). Use 0.0 for deterministic selection.	1.0
ALCHEMY_SUBTRACT_DISTANCE	Minimum distance from the subtract-centroid to keep a candidate (metric-dependent).	0.2
Similar Song and Song Path Duplicate filtering General
DUPLICATE_DISTANCE_THRESHOLD_COSINE	Less than this cosine distance the track is a duplicate.	0.01
DUPLICATE_DISTANCE_THRESHOLD_EUCLIDEAN	Less than this euclidean distance the track is a duplicate.	0.15
DUPLICATE_DISTANCE_CHECK_LOOKBACK	How many previous song need to be checked for duplicate.	1
MOOD_SIMILARITY_THRESHOLD	Maximum normalized distance for mood similarity filtering. Lower value will give more importance to mood	0.15
Song Path General
PATH_DISTANCE_METRIC	The distance metric to use for pathfinding. Options: 'angular', 'euclidean'	angular
PATH_DEFAULT_LENGTH	Default number of songs in the path if not specified in the API request	25
PATH_AVG_JUMP_SAMPLE_SIZE	Number of random songs to sample for calculating the average jump distance	200
PATH_CANDIDATES_PER_STEP	Number of candidate songs to retrieve from Voyager for each step in the path	25
PATH_LCORE_MULTIPLIER	It multiply the number of centroid created based on the distance. Higher is better for distant song and worst for nearest.	3
PATH_FIX_SIZE	When true, path generation will attempt to produce exactly the requested path length using centroid merging and backfilling. When false, the algorithm will perform a single best pick per centroid and may return a shorter path. Can be overridden per-request via the path_fix_size query parameter.	false
Evolutionary Clustering & Scoring
ITERATIONS_PER_BATCH_JOB	Number of clustering iterations processed per RQ batch job.	20
MAX_CONCURRENT_BATCH_JOBS	Maximum number of clustering batch jobs to run simultaneously.	10
CLUSTERING_BATCH_TIMEOUT_MINUTES	Max time a batch can run before being considered failed (prevents infinite hangs).	60
CLUSTERING_MAX_FAILED_BATCHES	Max number of failed batches before stopping new launches and forcing completion.	10
CLUSTERING_BATCH_CHECK_INTERVAL_SECONDS	How often to check batch status for timeout detection.	30
TOP_K_MOODS_FOR_PURITY_CALCULATION	Number of centroid's top moods to consider when calculating playlist purity.	3
EXPLOITATION_START_FRACTION	Fraction of runs before starting to use elites.	0.2
EXPLOITATION_PROBABILITY_CONFIG	Probability of mutating an elite vs. random generation.	0.7
MUTATION_INT_ABS_DELTA	Max absolute change for integer parameter mutation.	3
MUTATION_FLOAT_ABS_DELTA	Max absolute change for float parameter mutation.	0.05
MUTATION_KMEANS_COORD_FRACTION	Fractional change for KMeans centroid coordinates.	0.05
K-Means Ranges
NUM_CLUSTERS_MIN	Min $K$ for K-Means.	40
NUM_CLUSTERS_MAX	Max $K$ for K-Means.	100
USE_MINIBATCH_KMEANS	Whether to use MiniBatchKMeans (True) or standard KMeans (False) when clustering embeddings.	false
DBSCAN Ranges
DBSCAN_EPS_MIN	Min epsilon for DBSCAN.	0.1
DBSCAN_EPS_MAX	Max epsilon for DBSCAN.	0.5
DBSCAN_MIN_SAMPLES_MIN	Min min_samples for DBSCAN.	5
DBSCAN_MIN_SAMPLES_MAX	Max min_samples for DBSCAN.	20
GMM Ranges
GMM_N_COMPONENTS_MIN	Min components for GMM.	40
GMM_N_COMPONENTS_MAX	Max components for GMM.	100
GMM_COVARIANCE_TYPE	Covariance type for GMM (task uses full).	full
Spectral Ranges
SPECTRAL_N_CLUSTERS_MIN	Min components for Spectral clustering.	40
SPECTRAL_N_CLUSTERS_MAX	Max components for Spectral clustering.	100
SPECTRAL_N_NEIGHBORS	Number of Neighbors on which do clustering. Higher is better but slower	20
PCA Ranges
PCA_COMPONENTS_MIN	Min PCA components (0 to disable).	0
PCA_COMPONENTS_MAX	Max PCA components (e.g., 8 for feature vectors, 199 for embeddings).	199
AI Naming (*)
AI_MODEL_PROVIDER	AI provider: OLLAMA, GEMINI, MISTRAL, OpenAI or NONE.	NONE
AI_REQUEST_TIMEOUT_SECONDS	Timeout (in seconds) for AI API requests. Increase for slower hardware or larger models.	300
TOP_N_ELITES	Number of best solutions kept as elites.	10
SAMPLING_PERCENTAGE_CHANGE_PER_RUN	Percentage of songs to swap out in the stratified sample between runs (0.0 to 1.0).	0.2
MIN_SONGS_PER_GENRE_FOR_STRATIFICATION	Minimum number of songs to target per stratified genre during sampling.	100
STRATIFIED_SAMPLING_TARGET_PERCENTILE	Percentile of genre song counts to use for target songs per stratified genre.	50
OLLAMA_SERVER_URL	URL for your Ollama instance (if AI_MODEL_PROVIDER is OLLAMA).	http://<your-ip>:11434/api/generate
OLLAMA_MODEL_NAME	Ollama model to use (if AI_MODEL_PROVIDER is OLLAMA).	mistral:7b
GEMINI_MODEL_NAME	Gemini model to use (if AI_MODEL_PROVIDER is GEMINI).	gemini-2.5-pro
MISTRAL_MODEL_NAME	Mistral model to use (if AI_MODEL_PROVIDER is MISTRAL).	ministral-3b-latest
OPENAI_MODEL_NAME	OpenAI or OpenRouter model to use (if AI_MODEL_PROVIDER is OPENAI).	openai/gpt-4
OPENAI_SERVER_URL	URL for OpenAI / OpenRouter (if AI_MODEL_PROVIDER is OPENAI).	https://openrouter.ai/api/v1/chat/completions
Scoring Weights
SCORE_WEIGHT_DIVERSITY	Weight for inter-playlist mood diversity.	2.0
SCORE_WEIGHT_PURITY	Weight for playlist purity (intra-playlist mood consistency).	1.0
SCORE_WEIGHT_OTHER_FEATURE_DIVERSITY	Weight for inter-playlist 'other feature' diversity.	0.0
SCORE_WEIGHT_OTHER_FEATURE_PURITY	Weight for intra-playlist 'other feature' consistency.	0.0
SCORE_WEIGHT_SILHOUETTE	Weight for Silhouette Score (cluster separation).	0.0
SCORE_WEIGHT_DAVIES_BOULDIN	Weight for Davies-Bouldin Index (cluster separation).	0.0
SCORE_WEIGHT_CALINSKI_HARABASZ	Weight for Calinski-Harabasz Index (cluster separation).	0.0

The AI model tested for Clustering naming and for the instant playlist functionality are: * mistral:7b * llama3.1:8b * gemini-2.5-pro * gemini-1.5-flash-latest

different model could have different parameter and don't work.

For selhosting we suggest llama, instead for cloud genini.

(*) For using GEMINI API you need to have a Google account, a free account can be used if needed. Same goes for Mistral. Instead if you want to self-host Ollama here you can find a deployment example:

• https://github.com/NeptuneHub/k3s-supreme-waffle/tree/main/ollama