{"id":22402744,"url":"https://github.com/bniladridas/melody","last_synced_at":"2025-07-31T16:31:13.713Z","repository":{"id":264283968,"uuid":"892657129","full_name":"bniladridas/melody","owner":"bniladridas","description":"🎵 Melodify - AI-Powered Spotify Playlists","archived":false,"fork":false,"pushed_at":"2024-12-04T22:34:36.000Z","size":8647,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-04T23:26:03.897Z","etag":null,"topics":["node-js","rest-api","system-design"],"latest_commit_sha":null,"homepage":"https://melody-three.vercel.app","language":"HTML","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/bniladridas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","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-11-22T14:25:14.000Z","updated_at":"2024-12-04T22:34:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"8de9ea94-3fbf-463b-a5c2-e4b0c0f7a25f","html_url":"https://github.com/bniladridas/melody","commit_stats":null,"previous_names":["bniladridas/melody"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bniladridas%2Fmelody","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bniladridas%2Fmelody/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bniladridas%2Fmelody/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bniladridas%2Fmelody/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bniladridas","download_url":"https://codeload.github.com/bniladridas/melody/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228267835,"owners_count":17893841,"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":["node-js","rest-api","system-design"],"created_at":"2024-12-05T09:14:09.422Z","updated_at":"2024-12-05T09:14:10.107Z","avatar_url":"https://github.com/bniladridas.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎵 Melodify\n\n\u003e A sophisticated toolkit for enhancing your Spotify experience through AI-powered music discovery and playlist management.\n\n[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)\n[![npm version](https://badge.fury.io/js/melodify.svg)](https://badge.fury.io/js/melodify)\n[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/bniladridas/melodify/graphs/commit-activity)\n[![Play](https://img.shields.io/badge/Play-Visit%20Project-blue.svg)](https://melody-three.vercel.app)\n\n![Preview 1](/img/Spotify%20Preview%201.png)\n![Preview 2](/img/Spotify%20Preview%202.png)\n\n## 📋 Table of Contents\n- [🎵 Melodify](#-melodify)\n  - [📋 Table of Contents](#-table-of-contents)\n  - [🚀 Overview](#-overview)\n  - [✨ Features](#-features)\n    - [🎧 Smart Track Analysis](#-smart-track-analysis)\n    - [🤖 Intelligent Music Recommendations](#-intelligent-music-recommendations)\n    - [📝 Playlist Management](#-playlist-management)\n  - [🏗 System Architecture](#-system-architecture)\n    - [Component Architecture](#component-architecture)\n    - [Sequence Flow](#sequence-flow)\n    - [Technical Stack](#technical-stack)\n  - [🛠️ Prerequisites](#️-prerequisites)\n  - [🛠️ Installation](#️-installation)\n  - [📖 Usage](#-usage)\n    - [Initialize Top Tracks Analysis](#initialize-top-tracks-analysis)\n    - [Generate Recommendations](#generate-recommendations)\n    - [Create a New Playlist](#create-a-new-playlist)\n    - [Example Output](#example-output)\n  - [🔑 API Authentication](#-api-authentication)\n  - [🤝 Contributing](#-contributing)\n  - [🔨 Development](#-development)\n    - [Prerequisites](#prerequisites)\n    - [Setting up the development environment](#setting-up-the-development-environment)\n  - [🛠️ Troubleshooting](#️-troubleshooting)\n    - [Common Issues](#common-issues)\n  - [📄 License](#-license)\n  - [🙏 Acknowledgments](#-acknowledgments)\n\n## 🚀 Overview\n\nMelodify is an advanced Node.js application that leverages the Spotify Web API to transform how you discover and organize music. By combining machine learning with Spotify's extensive music library, Melodify provides personalized music recommendations and seamless playlist management capabilities.\n\n## ✨ Features\n\n### 🎧 Smart Track Analysis\n- Extract your top tracks across different time ranges:\n  - Short-term (last 4 weeks)\n  - Medium-term (last 6 months)\n  - Long-term (all time)\n- Detailed audio feature analysis for each track\n\n### 🤖 Intelligent Music Recommendations\n- Hybrid recommendation engine combining:\n  - Collaborative filtering based on user listening patterns\n  - Content-based filtering using audio features\n  - Contextual awareness for time-of-day appropriate suggestions\n- Personalized song suggestions based on your unique taste profile\n\n### 📝 Playlist Management\n- Create and manage Spotify playlists programmatically\n- Smart playlist generation based on:\n  - Mood and energy levels\n  - Genre combinations\n  - Tempo and rhythm patterns\n- Bulk track operations with error handling\n\n## 🏗 System Architecture\n\n### Component Architecture\nThe system is built using a modern, scalable architecture with clear separation of concerns:\n\n```mermaid\ngraph TB\n    subgraph \"Client Layer\"\n        FE[Frontend HTML/Player]\n    end\n\n    subgraph \"Server Layer\"\n        API[Express API Server]\n        AUTH[Authentication Module]\n        CACHE[Token Cache]\n    end\n\n    subgraph \"Core Services\"\n        TT[Top Tracks Service]\n        RS[Recommendation Service]\n        PS[Playlist Service]\n        WA[Web API Client]\n    end\n\n    subgraph \"External Services\"\n        SPOT[Spotify Web API]\n    end\n\n    subgraph \"Environment\"\n        ENV[.env Configuration]\n    end\n\n    %% Connection Flow\n    FE --\u003e|HTTP Requests| API\n    API --\u003e|Token Validation| AUTH\n    ENV --\u003e|Load Config| AUTH\n    AUTH --\u003e|Store Token| CACHE\n    CACHE --\u003e|Provide Token| WA\n\n    %% Service Flow\n    API --\u003e|Get Top Tracks| TT\n    API --\u003e|Get Recommendations| RS\n    API --\u003e|Create Playlist| PS\n    \n    TT --\u003e|Fetch Data| WA\n    RS --\u003e|Fetch Data| WA\n    PS --\u003e|Fetch/Create| WA\n    \n    WA --\u003e|API Requests| SPOT\n    SPOT --\u003e|JSON Response| WA\n\n    classDef external fill:#f96,stroke:#333,stroke-width:2px\n    classDef service fill:#58a6ff,stroke:#333,stroke-width:2px\n    classDef infrastructure fill:#87CEEB,stroke:#333,stroke-width:2px\n    \n    class SPOT external\n    class TT,RS,PS,WA service\n    class API,AUTH,CACHE,ENV infrastructure\n```\n\n### Sequence Flow\nThis diagram illustrates the interaction flow between different components:\n\n```mermaid\nsequenceDiagram\n    participant C as Client\n    participant S as Express Server\n    participant A as Auth Service\n    participant W as Web API Client\n    participant SP as Spotify API\n\n    C-\u003e\u003eS: Request Top Tracks\n    S-\u003e\u003eA: Validate Token\n    A-\u003e\u003eS: Token Valid\n    S-\u003e\u003eW: Fetch Top Tracks\n    W-\u003e\u003eSP: GET /v1/me/top/tracks\n    SP-\u003e\u003eW: Return Tracks\n    W-\u003e\u003eS: Process Response\n    S-\u003e\u003eC: Return Top Tracks\n\n    Note over C,SP: Playlist Creation Flow\n\n    C-\u003e\u003eS: Create Playlist\n    S-\u003e\u003eW: Get User Profile\n    W-\u003e\u003eSP: GET /v1/me\n    SP-\u003e\u003eW: Return User ID\n    W-\u003e\u003eSP: POST /v1/users/{id}/playlists\n    SP-\u003e\u003eW: Return Playlist ID\n    W-\u003e\u003eSP: POST /v1/playlists/{id}/tracks\n    SP-\u003e\u003eW: Confirm Addition\n    W-\u003e\u003eS: Return Success\n    S-\u003e\u003eC: Return Playlist Details\n```\n\n### Technical Stack\n- **Frontend**: HTML5, CSS3, JavaScript\n- **Backend**: Node.js, Express.js\n- **Authentication**: OAuth 2.0\n- **API Integration**: Spotify Web API\n- **Caching**: In-memory cache for tokens\n- **Error Handling**: Global error middleware\n\n## 🛠️ Prerequisites\n\n- Node.js \u003e= 14.x\n- npm \u003e= 6.x\n- Spotify Developer Account\n\n## 🛠️ Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/bniladridas/melodify.git\n```\n\n2. Navigate to the project directory:\n```bash\ncd melodify\n```\n\n3. Install dependencies:\n```bash\nnpm install\n```\n\n4. Configure environment variables:\n```bash\ncp .env.example .env\n# Edit .env with your Spotify API credentials\n```\n\n## 📖 Usage\n\n### Initialize Top Tracks Analysis\n```javascript\nconst melodify = require('melodify');\nawait melodify.analyzeTopTracks('short_term');\n```\n\n### Generate Recommendations\n```javascript\nconst recommendations = await melodify.recommendSongs({\n  limit: 20,\n  seedTracks: ['trackId1', 'trackId2'],\n  targetEnergy: 0.8\n});\n```\n\n### Create a New Playlist\n```javascript\nconst playlist = await melodify.createPlaylist({\n  name: 'My Awesome Mix',\n  description: 'Generated using Melodify',\n  public: true\n});\n```\n### Example Output\n```\n➜  spotify git:(main) ✗ node [spotifyProject.js](http://_vscodecontentref_/0)\nTop Tracks: [\n  'Under The Influence by Chris Brown',\n  'Perfect by Ed Sheeran',\n  'TiK ToK by Kesha',\n  'Energy (Lucky Me) by Morgan St. Jean',\n  'Way down We Go by KALEO'\n]\nRecommended Tracks: [\n  'Collide (Sped Up Remix) by Justine Skye, Tyga',\n  'Sensational (feat. Davido \u0026 Lojay) by Chris Brown, Davido, Lojay',\n  \"I'm a Mess by Ed Sheeran\",\n  'Time N Affection by Rema, Chris Brown',\n  'golden hour by JVKE'\n`\nCreated Playlist: My recommendation playlist, ID: 38yPvgmiuCUEzf8Qm3unYo\n```\n## 🔑 API Authentication\n\n1. **Create a Spotify Developer Account**\n   - Visit the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/)\n   - Sign up for a developer account\n\n2. **Register Your Application**\n   - Create a new application in the Spotify Developer Dashboard\n   - Note down the Client ID, Client Secret, and Redirect URI\n\n3. **Set Environment Variables**\n   - Add the following to your `.env` file:\n   ```bash\n   SPOTIFY_CLIENT_ID=your_client_id\n   SPOTIFY_CLIENT_SECRET=your_client_secret\n   SPOTIFY_REDIRECT_URI=your_redirect_uri\n   ```\n\n## 🤝 Contributing\n\nPlease read our [Contributing Guide](docs/CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.\n\n## 🔨 Development\n\n### Prerequisites\n- Node.js \u003e= 14.x\n- npm \u003e= 6.x\n- Spotify Developer Account\n\n### Setting up the development environment\n1. Install dependencies: `npm install`\n2. Start development server: `npm run dev`\n3. Run tests: `npm test`\n\n## 🛠️ Troubleshooting\n\n### Common Issues\n\n1. **Invalid Token Error**\n   - Ensure your Spotify API credentials are correct\n   - Check if the token has expired and refresh it if necessary\n\n2. **Network Issues**\n   - Verify your internet connection\n   - Check if the Spotify API is reachable\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Spotify Web API team for providing excellent documentation\n- Our amazing contributors and the open-source community\n- All the music lovers who inspire us to keep improving\n\n---\n\nMade with ♥️ by the Melodify Team\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbniladridas%2Fmelody","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbniladridas%2Fmelody","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbniladridas%2Fmelody/lists"}