{"id":23248563,"url":"https://github.com/shxntanu/minima-list-ml","last_synced_at":"2026-05-07T08:38:09.916Z","repository":{"id":222468624,"uuid":"752346886","full_name":"shxntanu/minima-list-ML","owner":"shxntanu","description":"🎵 Music recommendations system based on the Spotify dataset.","archived":false,"fork":false,"pushed_at":"2024-05-02T16:59:33.000Z","size":28946,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-12T07:24:07.111Z","etag":null,"topics":["flask","machine-learning","nextjs","portfolio","spotify"],"latest_commit_sha":null,"homepage":"https://minima-list-ml.vercel.app","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shxntanu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2024-02-03T17:12:59.000Z","updated_at":"2024-08-18T09:47:49.000Z","dependencies_parsed_at":"2024-04-29T15:08:05.709Z","dependency_job_id":null,"html_url":"https://github.com/shxntanu/minima-list-ML","commit_stats":null,"previous_names":["shxntanu/minima-list-ml"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shxntanu%2Fminima-list-ML","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shxntanu%2Fminima-list-ML/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shxntanu%2Fminima-list-ML/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shxntanu%2Fminima-list-ML/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shxntanu","download_url":"https://codeload.github.com/shxntanu/minima-list-ML/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247419861,"owners_count":20936014,"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","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":["flask","machine-learning","nextjs","portfolio","spotify"],"created_at":"2024-12-19T08:14:23.303Z","updated_at":"2026-05-07T08:38:09.872Z","avatar_url":"https://github.com/shxntanu.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Minima-list\n\nA unsupervised learning model which gives recommendations based on a given song.\n\n\u003cimg width=\"300px\" src=\"https://media.giphy.com/media/tqfS3mgQU28ko/giphy.gif\" /\u003e\n\n### Why\n\nWe created this project to see if we can actually understand the musical patterns of a listener with their playlist as source and what factors are really useful in determining the taste and interest of the listener.\nAnd also to get some experience in basic ML and hosting a model.\n\n# Client\n\n## Getting Started\n\n1. Clone or download the repository.\n2. Create a .env file in the project directory:\n   Add the following lines, replacing the placeholders with your actual Spotify API credentials:\n\n    ```env\n    NEXT_PUBLIC_SPOTIFY_CLIENT_ID=YOUR_CLIENT_ID\n    NEXT_PUBLIC_SPOTIFY_CLIENT_SECRET=YOUR_CLIENT_SECRET\n    ```\n\n3. cd to client directory\n4. Run\n\n    ```bash\n    # Install dependencies\n    npm install\n\n    # Start the development server\n    npm run dev\n    ```\n\n## Output\n\n![Home Page](assets/screenshot.png)\n\n# Backend (ML + Server)\n\n## What you'll need\n\nPython 3.x (\u003chttps://www.python.org/downloads/\u003e)\n\nNecessary libraries:\n\n-   pandas\n-   numpy\n-   sklearn\n-   flask\n-   spotipy\n-   dotenv\n-   gunicorn\n-   http.server\n\n## Getting Started\n\n1. Clone or download the repository.\n2. Create a .env file in the project directory:\n   Add the following lines, replacing the placeholders with your actual Spotify API credentials:\n\n    ```env\n    SPOTIFY_CLIENT_ID=\"YOUR_CLIENT_ID\"\n    SPOTIFY_CLIENT_SECRET=\"YOUR_CLIENT_SECRET\"\n    ```\n\n3. Create a virtual environment in the project directory and activate it:\n\n    ```bash\n    python3 -m venv .venv\n    source .venv/bin/activate\n    ```\n\n4. Install the required libraries:\n\n    ```bash\n    pip install -r requirements.txt\n    ```\n\n## How to Use the Recommendation System\n\n1. Start the server\n\n   ```python\n   gunicorn app:app\n   ```\n\n2. Prepare a list of songs: Create a JSON-formatted list containing information about the songs you want recommendations for, including their names and release years:\n\n   ```JSON\n   [\n      {\n         \"name\": \"Look What You Made Me Do\",\n         \"year\": 2017\n      }\n   ]\n   ```\n\n3. Send the list to the **'/recommend'** API endpoint:\n\n   Using cURL (for command line):\n   \n   ```bash\n   curl -X POST http://\u003clink\u003e/recommend\n         -H \"Content-Type: application/json\"\n         -d '[{\"name\": \"Castle on the Hill\", \"year\": 2017}, {\"name\": \"Look What You Made Me Do\", \"year\": 2017}]'\n   ```\n\n   Using Postman or other tools:\n   \n   Set the request method to POST and the URL to \u003chttp://localhost:(port)/recommend\u003e.\n   Set the Content-Type header to application/json.\n   Paste the JSON list of songs in the request body.\n   \n   The system will respond with a JSON list of recommended songs, including their names, artists, and years.\n   \n   ```JSON\n   [\n     {\n       \"name\": \"Look What You Made Me Do\",\n       \"year\": 2017,\n       \"artists\": [\n         \"Taylor Swift\"\n       ]\n     },\n     {\n       \"name\": \"Believer\",\n       \"year\": 2017,\n       \"artists\": [\n         \"Imagine Dragons\"\n       ]\n     },\n     {\n       \"name\": \"New Rules\",\n       \"year\": 2017,\n       \"artists\": [\n         \"Dua Lipa\"\n       ]\n     },\n     {\n       \"name\": \"One Kiss (with Dua Lipa)\",\n       \"year\": 2018,\n       \"artists\": [\n         \"Calvin Harris\",\n         \"Dua Lipa\"\n       ]\n     },\n     {\n       \"name\": \"Don't Start Now\",\n       \"year\": 2019,\n       \"artists\": [\n         \"Dua Lipa\"\n       ]\n     }\n   ]\n   ```\n\nNote: To properly utilize the code, you'll need a Spotify developer account and a Spotify app created to obtain your API credentials. Please refer to Spotify's documentation for detailed instructions: \u003chttps://developer.spotify.com/documentation/web-api/\u003e\n\n## Future Scope\n\n- Implement Mood based song recommendation.\n- Implement a user-specific recommendation system.\n\n## License\n\nThis repository is licensed under the [MIT License.](LICENSE)\n\n## Contact\n\nIf you have any questions or suggestions, feel free to contact [Shantanu Wable.](https://linkedin.com/in/shxntanu)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshxntanu%2Fminima-list-ml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshxntanu%2Fminima-list-ml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshxntanu%2Fminima-list-ml/lists"}