AudioMuse AI v0.1.4-alpha

Release Date: May 27, 2025

Summary

AudioMuse AI v0.1.4-alpha is here, bringing significant advancements to our music analysis and playlist generation engine!

This release introduces a sophisticated Monte Carlo evolutionary approach to clustering. The system now intelligently searches for optimal clustering parameters by running multiple iterations with varying configurations (for KMeans, DBSCAN, and PCA). Each iteration is evaluated using a "weighted diversity score," ensuring that the generated playlists are not only well-structured but also offer a richer variety of musical moods and tempos.

We've also enhanced user control by adding the ability to configure the maximum number of songs per cluster directly from the frontend. This gives users more flexibility in tailoring the length and composition of their automatically generated playlists.

These improvements are focused on delivering more robust, diverse, and user-customizable playlist generation, leading to a more refined and personalized music discovery experience.

Key Features

• Monte Carlo Evolutionary Clustering:
  • Implemented an evolutionary search for optimal clustering parameters (KMeans: number of clusters; DBSCAN: epsilon and min_samples; PCA: number of components).
  • The system runs multiple clustering iterations with randomly sampled parameters within defined ranges.
  • A "weighted diversity score" is calculated for each run to select the best-performing parameter set.
• Configurable Max Songs Per Cluster:
  • Users can now specify the MAX_SONGS_PER_CLUSTER via a new input field in the frontend.
  • The backend respects this user-defined value for playlist generation.

Detailed File Changes & Function Modifications

app.py (Backend Logic & API)

• run_clustering_task (Celery Task):
  • Evolutionary Clustering Implementation:
    • Accepts new parameters for parameter ranges (e.g., num_clusters_min/_max, dbscan_eps_min/_max, pca_components_min/_max), total num_clustering_runs, and max_songs_per_cluster.
    • Iterates num_clustering_runs times, randomly sampling clustering parameters (KMeans current_num_clusters, DBSCAN current_dbscan_eps & current_dbscan_min_samples, PCA current_pca_components) in each run.
    • Conditionally applies PCA based on sampled current_pca_components.
    • Calculates a diversity_score for each parameter set.
    • Tracks and applies the best_diversity_score and corresponding best_clustering_results.
  • Max Songs Per Cluster Usage:
    • Utilizes the passed max_songs_per_cluster when filtering tracks for filtered_clusters.
    • Passes this value (final_max_songs_per_cluster) to create_or_update_playlists_on_jellyfin.
• create_or_update_playlists_on_jellyfin:
  • Modified to accept and use the max_songs_per_cluster parameter for chunking playlists sent to Jellyfin.
• /api/clustering/start (API Endpoint):
  • Updated to receive new range parameters for KMeans, DBSCAN, PCA, clustering_runs, and max_songs_per_cluster from the frontend.
  • Passes these parameters to the run_clustering_task.delay() Celery call.
• /api/config (API Endpoint):
  • Response now includes the default max_songs_per_cluster value (from config.MAX_SONGS_PER_CLUSTER).

index.html (Frontend User Interface)

• "Generate Playlists" Form (playlistForm):
  • New Input Fields: Added for user configuration of:
    • KMeans ranges: num_clusters_min, num_clusters_max.
    • DBSCAN ranges: dbscan_eps_min, dbscan_eps_max, dbscan_min_samples_min, dbscan_min_samples_max.
    • PCA ranges: pca_components_min, pca_components_max.
    • max_songs_per_cluster.
    • clustering_runs.
  • Dynamic UI: JavaScript now shows/hides KMeans/DBSCAN specific options based on clustering_method selection.
• JavaScript Logic:
  • populateConfig(): Fetches and sets default values for all new clustering parameter inputs from /api/config.
  • playlistForm submit event listener: Collects values from all new input fields and sends them in the JSON payload to /api/clustering/start.

config.py (Configuration)

• This file remains the source for default values for parameters like MAX_SONGS_PER_CLUSTER, NUM_CLUSTERS_MIN/_MAX, DBSCAN_EPS_MIN/_MAX, etc. These defaults are used if not overridden by environment variables or user input via the UI.