{"id":19548068,"url":"https://github.com/mauroluzzatto/music-flow-api","last_synced_at":"2026-05-04T20:33:06.685Z","repository":{"id":153216024,"uuid":"524755547","full_name":"MauroLuzzatto/music-flow-api","owner":"MauroLuzzatto","description":"MusicFlow is an music recommender API that use the Spotify's API to predict the number of future streams of song using the Spotify audio features and track metadata","archived":false,"fork":false,"pushed_at":"2024-05-05T12:55:56.000Z","size":5412,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-26T06:26:56.731Z","etag":null,"topics":["aws","aws-lambda","aws-sam","fastapi","machine-learning","mlops","spotify-api"],"latest_commit_sha":null,"homepage":"https://musicflow.link/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MauroLuzzatto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-14T18:58:35.000Z","updated_at":"2023-11-11T16:00:42.000Z","dependencies_parsed_at":"2024-01-27T19:39:11.798Z","dependency_job_id":"de3d821a-7062-4458-bc3b-b954fd59e171","html_url":"https://github.com/MauroLuzzatto/music-flow-api","commit_stats":{"total_commits":115,"total_committers":2,"mean_commits":57.5,"dds":0.008695652173912993,"last_synced_commit":"fc7f69ec35e588272dd75d3a0bbc4dabfd05de01"},"previous_names":["mauroluzzatto/music-flow-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MauroLuzzatto/music-flow-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MauroLuzzatto%2Fmusic-flow-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MauroLuzzatto%2Fmusic-flow-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MauroLuzzatto%2Fmusic-flow-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MauroLuzzatto%2Fmusic-flow-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MauroLuzzatto","download_url":"https://codeload.github.com/MauroLuzzatto/music-flow-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MauroLuzzatto%2Fmusic-flow-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266801492,"owners_count":23986372,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-24T02:00:09.469Z","response_time":99,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-lambda","aws-sam","fastapi","machine-learning","mlops","spotify-api"],"created_at":"2024-11-11T03:54:37.161Z","updated_at":"2026-05-04T20:33:06.613Z","avatar_url":"https://github.com/MauroLuzzatto.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n[![Tests](https://github.com/MauroLuzzatto/music-flow-api/workflows/Tests/badge.svg)](https://github.com/MauroLuzzatto/music-flow-api/actions?workflow=Tests)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\n\n# MusicFlow API\n\nMusicFlow is an API that use the Spotify's API to predict the number of song streams using the Spotify audio features and track metadata.\n\nThe MusicFlow API uses the personal Spotify streaming history to train a machine learning model that predicts the number of streams for a given song. The training dataset uses number of stream values between 0 and 30.\n\nThe MusicFlow API is built using the FastAPI framework, which makes it fast, easy to use, and well-documented.\n\n\n\n## Available Endpoints\n\nThe MusicFlow API provides the following endpoints:\n\n- `musicflow.link/` - The root page of the MusicFlow API.\n- `musicflow.link/api/health` - Returns the health status of the API.\n- `musicflow.link/api/raw_features/?song={song}\u0026artist={artist}` - Returns the unprocessed audio features of a song using the Spotify API.\n- `musicflow.link/api/features/?song={song}\u0026artist={artist}` - Returns the unprocessed audio features of a song.\n- `musicflow.link/api/prediction/?song={song}\u0026artist={artist}` - Predicts the number of streams for a given song based on the Spotify audio features and track metadata.\n\n\n## Examples\n\n### root\n\n\n[https://musicflow.link/](https://musicflow.link)\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/MauroLuzzatto/mlops-music-flow/raw/main/static/ui.png\"/\u003e\n\u003c/p\u003e\n\n### `/prediction`\n\nLet's predict the number of streams for \"The Less I know the better\" from \"Tame Impala\":\n\n[https://musicflow.link/api/prediction/?song=The Less I know the better\u0026artist=Tame Impala](https://musicflow.link/api/prediction/?song=The%20Less%20I%20know%20the%20better\u0026artist=Tame%20Impala)\n\n\nResponse:\n```\n{\n    \"song\": \"The Less I Know The Better\",\n    \"artist\": \"Tame Impala\",\n    \"prediction\": 5.35,\n    \"description\": (\n        \"The predicted number of future streams of the song based on the Spotify\"\n        \" API audio features.\"\n    ),\n    \"song_metadata\": {\n        \"song\": \"The Less I Know The Better\",\n        \"artist\": [\"Tame Impala\"],\n        \"album\": \"Currents\",\n    },\n    \"message\": {\"emoji\": \"😍\", \"text\": \"What a banger!\"},\n}\n```\n\n\n### `/features`\n\n[https://musicflow.link/api/features/?song=The Less I know the better\u0026artist=Tame Impala](https://musicflow.link/api/features/?song=The%20Less%20I%20know%20the%20better\u0026artist=Tame%20Impala)\n\n\nResponse:\n```\n{\n  \"track\":{\n    \"track_name\":\"The less I know the better\",\n    \"artist_name\":\"Tame Impala\",\n    \"number_of_available_markets\":183,\n    \"num_artists\":1,\n    \"duration_ms\":216320,\n    \"explicit\":true,\n    \"popularity\":83,\n    \"isrc\":\"AUUM71500303\"\n  },\n  \"album\":{\n    \"release_date_precision\":\"day\",\n    \"release_year\":2015,\n    \"release_month\":7,\n    \"release_day\":17,\n    \"date_is_complete\":true,\n    \"album\":\"Currents\"\n  },\n  \"audio_features\":{\n    \"danceability\":0.64,\n    \"energy\":0.74,\n    \"key\":4,\n    \"loudness\":-4.083,\n    \"mode\":1,\n    \"speechiness\":0.0284,\n    \"acousticness\":0.0115,\n    \"instrumentalness\":0.00678,\n    \"liveness\":0.167,\n    \"valence\":0.785,\n    \"tempo\":116.879,\n    \"id\":\"6K4t31amVTZDgR3sKmwUJJ\",\n    \"time_signature\":4\n  }\n}\n```\n\n## Get Spotify API Access Client ID and Client Secret\n\nTo access the Spotify API, you need to create a Spotify Developer account and obtain a Client ID and Client Secret. Follow these steps:\n\n- Go to the Spotify Developer Dashboard and log in with your Spotify account.\n- Click on \"Create an app\" and fill out the required information.\n- Once you have created the app, you will see your Client ID and Client Secret on the app dashboard.\n- Add them to your `env` file\n\n\n## Model Features derived from the Spotify API\n\n### Used Spotify API endpoints\n\nThe model features are created based on the responses from the endpoints below.\n\n- `tracks`\n- `audio_features`\n- `audio_anaysis` (currenly not used)\n\n### Model Features\n\n| Column Name | Description | Data Type | Allowed Value Ranges |\n|-------------|-------------|----------|----------------------|\n| number_of_available_markets | The number of markets in which the track can be played | integer | 0-79 |\n| release_year | The year the track was released | integer | 0 \u003c= year \u003c= current year |\n| release_month | The month the track was released | integer | 1 \u003c= month \u003c= 12 |\n| release_day | The day the track was released | integer | 1 \u003c= day \u003c= 31 |\n| date_is_complete | Indicates if the release date is completely known | boolean | true/false |\n| num_artists | The number of artists credited on the track | integer | n/a |\n| duration_ms | The duration of the track in milliseconds | integer | n/a |\n| explicit | Indicates if the track contains explicit content | boolean | true/false |\n| popularity | The popularity of the track | integer | 0 \u003c= popularity \u003c= 100 |\n| danceability | The danceability of the track | float | 0 \u003c= danceability \u003c= 1 |\n| energy | The energy of the track | float | 0 \u003c= energy \u003c= 1 |\n| loudness | The loudness of the track in decibels (dB) | float | -60 \u003c= loudness \u003c= 0 |\n| mode | The modality (major or minor) of the track | integer | 0 = minor, 1 = major |\n| speechiness | The presence of spoken words in the track | float | 0 \u003c= speechiness \u003c= 1 |\n| acousticness | The acousticness of the track | float | 0 \u003c= acousticness \u003c= 1 |\n| instrumentalness | The instrumentalness of the track | float | 0 \u003c= instrumentalness \u003c= 1 |\n| liveness | The liveness of the track | float | 0 \u003c= liveness \u003c= 1 |\n| valence | The valence of the track | float | 0 \u003c= valence \u003c= 1 |\n| tempo | The tempo of the track in beats per minute (BPM) | float | 0 \u003c= tempo \u003c= 500 |\n| time_signature | The time signature of the track | integer | 0 \u003c= time_signature \u003c= 7 |\n| A | The key of the track with pitch class A | integer | 0 = not present, 1 = present |\n| A#/Bb | The key of the track with pitch class A#/Bb | integer | 0 = not present, 1 = present |\n| B | The key of the track with pitch class B | integer | 0 = not present, 1 = present |\n| C | The key of the track with pitch class C | integer | 0 = not present, 1 = present |\n| C#/Db | The key of the track with pitch class C#/Db | integer | 0 = not present, 1 = present |\n| D | The key of the track with pitch class D | integer | 0 = not present, 1 = present |\n| D#/Eb | The key of the track with pitch class D#/Eb | integer | 0 = not present, 1 = present |\n| E | The key of the track with pitch class E | integer | 0 = not present, 1 = present |\n| F | The key of the track with pitch class F | integer | 0 = not present, 1 = present |\n| F#/Gb | The key of the track with pitch class F#/Gb | integer | 0 = not present, 1 = present |\n| G | The key of the track with pitch class G | integer | 0 = not present, 1 = present |\n| G#/Ab | The key of the track with pitch class G#/Ab | integer | 0 = not present, 1 = present |\n| Unknown | The key of the track is unknown | integer | 0 = not present, 1 = present |\n\n\u003c!--\n\n## How to create your own musicflow API?\n\nThis repository provides instructions on how to request Spotify streaming history data, download it and create a dataset using music_flow, train a machine learning model, and set up an API using an AWS account.\n\n### Get Spotify API Access Client ID and Client Secret\n\nTo access the Spotify API, you need to create a Spotify Developer account and obtain a Client ID and Client Secret. Follow these steps:\n\n- Go to the Spotify Developer Dashboard and log in with your Spotify account.\n- Click on \"Create an app\" and fill out the required information.\n- Once you have created the app, you will see your Client ID and Client Secret on the app dashboard.\n\n### Request Spotify Streaming History\n\nTo request your Spotify streaming history, you need to follow these steps:\n\n- Go to Spotify's Privacy Settings and log in with your Spotify account.\n- Scroll down to \"Download your data\" and click on \"Request\".\n- You will receive an email from Spotify when your data is ready to be downloaded.\n\n### Download the Data and Creating a Dataset Using `music_flow`\n\nOnce you have received the email from Spotify, you can download your data and create a dataset using music_flow by following these steps:\n\n- Download your data from Spotify and unzip the file.\n- Install music_flow by running pip install music-flow.\n- Create a Python script and use the music_flow library to load the data and create a dataset. Refer to the music_flow documentation for more information on how to do this.\n\n### Train a Machine Learning Model\n\nOnce you have created your dataset, you can train a machine learning model by following these steps:\n\n- Import your dataset into your machine learning environment.\n- Preprocess the data as needed.\n- Choose a machine learning algorithm and train the model.\n- Test the model and evaluate its performance.\n\n### Set Up API Using an AWS Account\n\nTo set up an API with AWS SAM, follow these steps:\n\n- Install AWS SAM CLI by following the instructions provided here.\n- Create a new SAM project using the sam init command.\n- Write the code for your Lambda function and API gateway in the appropriate files (e.g., app.py and template.yaml).\n- Build and package your SAM application using the sam build and sam package commands.\n- Deploy your SAM application using the sam deploy command.\n --\u003e\n\n\n\n## Next steps and ongoing work\n\n- Version model\n- Add logging\n- Allow for continous training\n\u003c!-- - Use data classes for sample --\u003e\n- Improve feature processing pipeline\n\u003c!-- - Improve api reponse for formatted feature --\u003e\n- [x] upload the request to S3 (add metadata from request IP, etc.)\n- [] Move all configrations outside of code into a yaml file and settings classes\n- Add Deep learning models\n- [] add model baseline\n- [] version the data\n- [] add model versioning\n\n\u003c!--\n\nTODO: make info graphics of the application\n- use excalidraw\n\n\n## Plan\n- request streaming history from spotify\n- find some random tracks (e.g kaggle datasets)\n- calculate the numer of streams per track (=target values)\n- download features for the tracks\n- create the dataset containg the features and the number of streams\n- train model using GridSearch\n- save different model versions\n- use API to serve model\n- use API to predict number of streams per track\n\n\nUsing lifespan event on APIRoute() instead in FastAPI() #9664\nhttps://github.com/tiangolo/fastapi/discussions/9664\n\nhttps://github.com/ipinfo/python\nhttps://github.com/shon/httpagentparser\n--\u003e\n\n\n\n\u003c!-- curl -XPOST \"http://localhost:8080/2015-03-31/functions/function/invocations\" -d '{}'\n\ncurl: (52) Empty reply from server --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmauroluzzatto%2Fmusic-flow-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmauroluzzatto%2Fmusic-flow-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmauroluzzatto%2Fmusic-flow-api/lists"}