5avis/playlist-a-live

Purpose and Entry Points

playlist-a-live is a Python automation pipeline that gathers trending music, enriches tracks with features, clusters them, makes playlist decisions, and updates a Spotify playlist. The main orchestrator is run_pipeline.py; scheduled execution is configured in .github/workflows/daily.yml.

Pipeline Orchestration

run_pipeline.py coordinates the end-to-end stages and their file-based handoffs. The repository uses CSV artifacts as durable boundaries between collection, analysis, decisioning, and playlist mutation:

• trending_tracks.csv

• tracks_with_features.csv

• tracks_clustered.csv

• decisions.csv

Trend Collection

fetch_trending.py obtains the source set of trending tracks and writes the initial track dataset. This is the ingestion boundary: downstream code operates on persisted track records rather than directly on the trend source.

• fetch_trending.py

• trending_tracks.csv

Feature Enrichment

fetch_with_features.py augments collected tracks with music metadata/features needed for analysis. It consumes the trending-track output and produces the feature-bearing dataset used by clustering.

• fetch_with_features.py

• trending_tracks.csv

• tracks_with_features.csv

Analysis and Decisioning

clustering.py groups enriched tracks, likely creating the analytical representation for playlist selection. decision.py converts clustered results into explicit add/remove or selection decisions, persisted for the playlist-update stage.

• clustering.py

• tracks_with_features.csv

• tracks_clustered.csv

• decision.py

• decisions.csv

Spotify Authentication and Playlist Mutation

Spotify access is separated from the pipeline’s data stages. spotify_login.py, login_fresh.py, and reauth.py handle authentication/session recovery; update_playlist.py is the external side-effect boundary that applies decisions.csv to Spotify. This separation allows analysis to complete before mutating the live playlist.

• spotify_login.py

• login_fresh.py

• reauth.py

• update_playlist.py

Operational State and Runtime

The project is Python-script based, with local CSV files serving as both pipeline outputs and operational history. activity_log.py and activity_log.csv provide an execution/activity record. GitHub Actions supplies the scheduled runtime, so credentials for Spotify and any trend/feature providers must be available to the workflow environment.

• activity_log.py

• activity_log.csv

• .github/workflows/daily.yml