{"id":31794238,"url":"https://github.com/devtakkekar/music_recommender_algorithm","last_synced_at":"2026-04-12T11:47:18.312Z","repository":{"id":317832334,"uuid":"1069012472","full_name":"devtakkekar/music_recommender_algorithm","owner":"devtakkekar","description":"a simple and minimal ai music recommender ","archived":false,"fork":false,"pushed_at":"2025-10-03T09:19:47.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-03T11:33:26.565Z","etag":null,"topics":["academic-project","ai","cosine-similarity","css","deep-learning","html","js","learning","music","python"],"latest_commit_sha":null,"homepage":"","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/devtakkekar.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-03T09:07:59.000Z","updated_at":"2025-10-03T09:22:02.000Z","dependencies_parsed_at":"2025-10-03T11:33:27.634Z","dependency_job_id":"df9db8c8-c85a-42b7-b541-8835851f6886","html_url":"https://github.com/devtakkekar/music_recommender_algorithm","commit_stats":null,"previous_names":["devtakkekar/music_recommender_algorithm"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/devtakkekar/music_recommender_algorithm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devtakkekar%2Fmusic_recommender_algorithm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devtakkekar%2Fmusic_recommender_algorithm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devtakkekar%2Fmusic_recommender_algorithm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devtakkekar%2Fmusic_recommender_algorithm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devtakkekar","download_url":"https://codeload.github.com/devtakkekar/music_recommender_algorithm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devtakkekar%2Fmusic_recommender_algorithm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005034,"owners_count":26083827,"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-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","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":["academic-project","ai","cosine-similarity","css","deep-learning","html","js","learning","music","python"],"created_at":"2025-10-10T19:21:06.669Z","updated_at":"2025-10-10T19:21:10.916Z","avatar_url":"https://github.com/devtakkekar.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Collect · AI Music Recommender\n\nA small, fully transparent content‑based music recommender. The system exposes a tiny HTTP API using Python’s standard library and a minimal frontend (HTML/CSS/JS) to explore recommendations by either seeding a track or setting preference sliders.\n\n\u003e [!NOTE]\n\u003e This project is designed for educational use: easy to read, easy to run, and easy to explain in an academic context.\n\n---\n\n### Key Features\n\n- **Content-based recommendations** using cosine similarity\n- **Two modes**: by seed track or by user preference vector\n- **Zero dependencies** on the backend (Python stdlib HTTP server)\n- **Tiny curated dataset** for clarity and reproducibility\n- **No build step** on the frontend (pure HTML/CSS/JS)\n\n---\n\n### Tech Stack\n\n- **Backend**: Python (stdlib `http.server`)\n- **Frontend**: HTML, CSS, vanilla JavaScript\n- **Data**: In-repo sample dataset (`backend/data.py`)\n\n---\n\n### Project Structure\n\n- `backend/`\n  - `server.py`: Minimal HTTP server that serves the frontend and exposes the API (`/api/tracks`, `/api/recommend`)\n  - `recommender.py`: Cosine similarity, preference vector construction, top‑K retrieval\n  - `data.py`: Small curated dataset and feature extraction\n- `frontend/`\n  - `index.html`: UI to select a seed track or tune preferences\n  - `app.js`: Fetches data, calls the API, renders recommendations\n  - `styles.css`: Basic styling\n\n---\n\n### Quickstart\n\n- Prerequisites: Python 3.8+ (tested with standard library only)\n- OS: Works on Windows/macOS/Linux. Example commands below use Windows PowerShell.\n\n1) From the project root:\n```\nin powershell\npy backend/server.py\n      OR\nin terminal\npython -m backend.server\n```\n\n2) Open the app:\n- `http://127.0.0.1:8000`\n\n3) Interact:\n- Click “Recommend similar” on any track to get seed‑based recommendations.\n- Or adjust “Danceability”, “Energy”, “Valence”, and “Tempo” sliders, then click “Recommend from preferences”.\n\nTo stop the server: Ctrl+C in the terminal.\n\n---\n\n### API Reference\n\nBase URL: `http://127.0.0.1:8000`\n\n- **GET** `/api/tracks`\n  - Returns the catalog.\n  - Response:\n    ```json\n    {\n      \"tracks\": [\n        { \"id\": \"t001\", \"title\": \"...\", \"artist\": \"...\", \"genre\": \"...\", \"year\": 2021, \"danceability\": 0.78, \"energy\": 0.72, \"valence\": 0.65, \"tempo_bpm\": 118 }\n        // ...\n      ]\n    }\n    ```\n\n- **GET** `/api/recommend`\n  - Two modes:\n    - Seed track mode: `?seed=\u003ctrack_id\u003e\u0026k=\u003cint\u003e`\n    - Preference mode: `?danceability=\u003c0..1\u003e\u0026energy=\u003c0..1\u003e\u0026valence=\u003c0..1\u003e\u0026tempo=\u003c0..1\u003e\u0026k=\u003cint\u003e`\n  - Parameters:\n    - `seed` (optional): track ID from `/api/tracks`\n    - `danceability`, `energy`, `valence`, `tempo` (optional floats 0..1). Missing values default to 0.5\n    - `k` (optional int): number of results (default 5)\n  - Response:\n    ```json\n    {\n      \"recommendations\": [\n        { \"id\": \"t005\", \"title\": \"...\", \"artist\": \"...\", \"genre\": \"...\", \"year\": 2022, \"danceability\": 0.90, \"energy\": 0.77, \"valence\": 0.62, \"tempo_bpm\": 124 }\n        // ...\n      ]\n    }\n    ```\n\nExample calls:\n```bash\n# Seed-based\ncurl \"http://127.0.0.1:8000/api/recommend?seed=t001\u0026k=5\"\n\n# Preference-based\ncurl \"http://127.0.0.1:8000/api/recommend?danceability=0.7\u0026energy=0.6\u0026valence=0.8\u0026tempo=0.5\u0026k=5\"\n```\n\n---\n\n### How It Works (Methodology)\n\nEach track is represented by a feature vector:\n- `danceability` (0..1)\n- `energy` (0..1)\n- `valence` (0..1)\n- `tempo` (scaled 0..1 from BPM assuming 60–160 BPM)\n\nFor preference mode, a user vector is constructed with defaults of 0.5 for any missing dimensions. For seed mode, we extract the feature vector of the chosen track. We then compute cosine similarity between the query vector and every track vector and return the top‑K by similarity.\n\nCosine similarity:\n\\[\n\\text{cosine}(a, b) = \\frac{\\sum_i a_i b_i}{\\sqrt{\\sum_i a_i^2}\\sqrt{\\sum_i b_i^2}}\n\\]\n\n---\n\n### Dataset\n\nFound in `backend/data.py`. It’s intentionally small and balanced across a few genres and moods to keep the example transparent and readable. Tempo is normalized to 0..1 by a simple min‑max scaling over an assumed 60–160 BPM range.\n\n---\n\n### Reproducibility\n\n- No randomness in the model; results are deterministic given the dataset and parameters.\n- The entire pipeline is in this repo; no external services, databases, or model files.\n\n---\n\n### Limitations\n\n- Small toy dataset; results demonstrate mechanism, not production quality.\n- Content features are hand‑crafted and minimal; no learned embeddings.\n- No user history, no collaborative filtering, no personalization beyond the input vector.\n\n---\n\n### Ethical Considerations\n\n- Transparent by design (no opaque models).\n- Extend responsibly if integrating user data; consider privacy, consent, and bias amplification.\n\n---\n\n### Future Expandability\n\n- Add more features (e.g., acousticness, instrumentalness, loudness).\n- Swap in learned embeddings (e.g., from audio or metadata encoders).\n- Hybrid recommenders (content + collaborative signals).\n- Pagination and filtering (genre/year constraints).\n- Persisted user profiles and A/B experiments.\n- Evaluation with larger datasets and offline metrics (MAP@K, NDCG).\n\n---\n\n### License\n\nThis project is licensed under the MIT License.  \nCan only be used for educational and research purposes.\n\n---\n\n### Acknowledgements\n\nBuilt with Python stdlib and a minimal web frontend to keep the focus on recommendation fundamentals.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevtakkekar%2Fmusic_recommender_algorithm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevtakkekar%2Fmusic_recommender_algorithm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevtakkekar%2Fmusic_recommender_algorithm/lists"}