🎧 Spotify AI - Intelligent Music Discovery

Your personal AI DJ

🌟 What is Spotify AI?

Spotify AI transforms how you discover music by combining the power of LLMs with Spotify's vast music catalog and your personal listening history. Simply describe what you need in plain language, and AI curates the perfect playlist tailored to your taste.

"I need focus music for coding" → 🎵 10 perfectly matched tracks "Ethiopian chill vibes" → 🎵 Authentic Amharic music "Energetic workout mix" → 🎵 High-energy tracks that match your style

🚀 AI Features

🎯 Natural Language Generation

Describe your mood, activity, or feeling in plain language - no complex filters or searches needed.

Examples:

"Relaxing evening music for reading"
"Upbeat French rap for my morning run"
"Melancholic indie for a rainy day"
"K-pop dance tracks for a party"

🧠 Intelligent Mood Analysis

The AI understands context beyond just keywords:

⏰ Time of Day - Morning energy vs. evening calm
📅 Day of Week - Weekend vibes vs. weekday focus
🌤️ Weather Conditions - Rainy day moods, sunny energy
💭 Emotional State - Detected from your description
🎵 Music Psychology - Energy levels (0-1), Valence (-1 to 1)

🎨 Personalized to YOUR Taste

Unlike generic playlists, Spotify AI learns from your unique listening history:

✨ Taste Profile Analysis

Your top 50 artists
Favorite genres and sub-genres
Recent listening patterns
Energy/valence preferences
Preferred musical eras (2010s, 2020s, etc.)

✨ Smart Balancing

60% Familiar - Artists and genres you love
40% Discovery - New tracks aligned with your taste
Adjustable discovery level (familiar/balanced/discovery)

✨ Continuous Learning

Updates preferences after each generation
Learns your favorite vibes and genres
Adapts to your evolving taste

🔄 Instant Regeneration

Not satisfied? Get a completely different playlist with the same vibe in one click:

Same mood and style
Fresh track selection
New AI ranking
Same personalization

🎭 Transparent Explanations

Every track comes with detailed reasoning:

Track: "Yedi Gosh" by Aster Aweke
Overall Match: 98%

Why selected:
• Authentic Ethiopian/Amharic artist matching your request
• Soft, contemplative energy perfect for the mood
• Artist appears in your recent listening history
• High popularity ensures quality

Taste Alignment: 95% - "Matches your Ethiopian music taste"
Mood Fit: 92% - "Perfect for cloudy day introspection"

💾 Smart Preferences Management

Your AI assistant remembers and learns:

🎵 Saved Vibes - Keep your last 5 favorite moods
🎸 Genre Preferences - Top 10 genres you enjoy
⚡ Energy Levels - Your preferred intensity (0-1)
🎭 Mood Preferences - Valence from melancholic to uplifting
📏 Playlist Length - 5-50 tracks (default: 10)
🔍 Discovery Level - How adventurous you want to be
📊 Generation History - Total playlists created

🎵 Spotify Web Client Features

Built on top of a Spotify Web Client with:

Core Features

▶️ Real-time Playback - Spotify Playback SDK integration
🎛️ Full Controls - Play, pause, skip, shuffle, repeat
🔍 Search & Browse - Explore millions of tracks, artists, albums
📝 Playlist Management - Create, edit, delete playlists
❤️ Liked Songs - Save and access your favorites
📱 Multi-Device - Switch between devices seamlessly
👤 Artist Pages - Full discography and related artists
💿 Album Views - Track listings and details

Note: Premium Spotify account required for playback features

🛠 Technology Stack

AI & Intelligence

🤖 OpenAI - Natural language understanding and curation
🧠 Custom Generation Service - Intelligent playlist creation
📊 Taste Profiling - User listening history analysis
🎯 Smart Ranking - Multi-factor track scoring

Frontend

⚛️ React 19 - Modern UI framework
📘 TypeScript - Type-safe development
🎨 Ant Design - Professional UI components
🔄 Redux - State management
💾 Redux Persist - Persistent storage

Spotify Integration

🎵 Spotify Web API - Music data and user info
🔊 Spotify Playback SDK - Real-time playback control

📸 AI Feature Showcase

Natural Language Input	AI Processing	Curated Playlist
Selection Reasoning	Emotion Mapping	Save & Play

⚙️ Installation & Setup

Prerequisites

Node.js 16+ and Yarn
Spotify Premium account
Spotify Developer App credentials
OpenAI API key

Quick Start (Local Development)

Clone the repository

git clone https://github.com/yeabwang/spotify_ai.git
cd spotify_ai

Install dependencies
```
yarn install
```

Configure environment variables

Copy .env.dist to .env and fill in the required values:

cp .env.dist .env

Edit .env with your credentials:

# Required: Spotify API Configuration
REACT_APP_SPOTIFY_CLIENT_ID=<your_spotify_client_id>
REACT_APP_SPOTIFY_REDIRECT_URL=http://localhost:3000

# Optional: OpenAI API Key (can also be entered in Settings page)
REACT_APP_OPENAI_API_KEY=<your_openai_api_key>

Get your Spotify credentials:

Go to Spotify Developer Dashboard
Create a new app
Copy the Client ID
Add http://localhost:3000 as a Redirect URI in your app settings

Start the development server
```
yarn start
```
Open your browser

Navigate to http://localhost:3000
Configure your OpenAI API key

If you didn't set it in .env, go to Settings (⚙️) in the app and enter your OpenAI API key.

Get your API key:
- OpenAI: Get your API key from OpenAI Platform

Self-Hosting / Production Deployment

For self-hosted deployments, the following environment variables are required:

Variable	Required	Description
`REACT_APP_SPOTIFY_CLIENT_ID`	Yes	Your Spotify app's Client ID
`REACT_APP_SPOTIFY_REDIRECT_URL`	Yes	Must match your deployment URL exactly
`REACT_APP_OPENAI_API_KEY`	No	Optional; users can enter in Settings
`REACT_APP_OPENAI_MODEL`	No	Defaults to `gpt-5.2-chat-latest`

Important: The REACT_APP_SPOTIFY_REDIRECT_URL must exactly match:

The URL where your app is deployed (e.g., https://your-domain.com)
A Redirect URI configured in your Spotify Developer Dashboard

Customize AI behavior (optional): Modify src/config/ai.config.ts to adjust:

Model selection and parameters
Scoring weights (taste, mood, popularity, play frequency)
Generation defaults (track count, discovery level)
Preference storage settings

Production Build

yarn build

The build files will be in the build/ directory.

🎯 How to Use AI Features

1. Describe Your Need

Simply type what you want in natural language:

"Chill music for studying"
"Upbeat workout tracks"
"Relaxing Ethiopian music"

2. AI Analyzes

The system:

Loads your Spotify listening history
Analyzes your taste profile
Understands the mood and context
Creates a personalized music plan

3. Get Your Playlist

Receive 10 perfectly curated tracks with:

Overall match scores
Detailed explanations
Play/Save options

4. Refine (Optional)

Regenerate for different tracks
Adjust discovery level
Update preferences
Save favorite vibes

📚 Documentation

Generation Service API - Detailed API documentation for developers
Spotify Web API Docs - Official Spotify API reference
OpenAI API Docs - OpenAI API documentation

🤝 Shout out

This project is built upon the excellent Spotify React Web Client created by Franco Borrelli.

🙏 Original Project: francoborrelli/spotify-react-web-client

🤝 Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Important Notes

Spotify Premium Required

Playback features require a Spotify Premium subscription
Free accounts can browse but cannot play music

OpenAI API Costs

AI features use OpenAI's API (configurable model)
Each playlist generation makes 3-4 API calls
Estimated cost varies by model
Configure model and timeouts in src/config/ai.config.ts
Consider implementing rate limiting for production

API Rate Limits

Spotify API: 180 requests per minute
OpenAI API: Depends on your tier
Built-in delays to prevent rate limiting

💬 Support

If you encounter any issues or have questions:

AI Features (Generation, OpenAI, Preferences)

Check the AI Documentation
Review existing Issues
Open a new issue in this repository

Web Client Features (Playback, UI, Spotify Integration)

Check the original repository
Review existing Issues
Open a new issue in Franco's repository

🌟 Show Your Support

If you find this project useful, please consider:

⭐ Starring the repository
🐛 Reporting bugs
💡 Suggesting new features
🤝 Contributing code
📢 Sharing with others

Made with ❤️

Name		Name	Last commit message	Last commit date
Latest commit History 396 Commits
.github/workflows		.github/workflows
docker/nginx		docker/nginx
images		images
public		public
src		src
.env.dist		.env.dist
.gitignore		.gitignore
.nvmrc		.nvmrc
Dockerfile		Dockerfile
GENERATION_SERVICE_README.md		GENERATION_SERVICE_README.md
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
render.yaml		render.yaml
setup.sh		setup.sh
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

🎧 Spotify AI - Intelligent Music Discovery

🌟 What is Spotify AI?

🚀 AI Features

🎯 Natural Language Generation

🧠 Intelligent Mood Analysis

🎨 Personalized to YOUR Taste

🔄 Instant Regeneration

🎭 Transparent Explanations

💾 Smart Preferences Management

🎵 Spotify Web Client Features

Core Features

🛠 Technology Stack

AI & Intelligence

Frontend

Spotify Integration

📸 AI Feature Showcase

⚙️ Installation & Setup

Prerequisites

Quick Start (Local Development)

Self-Hosting / Production Deployment

Production Build

🎯 How to Use AI Features

1. Describe Your Need

2. AI Analyzes

3. Get Your Playlist

4. Refine (Optional)

📚 Documentation

🤝 Shout out

🤝 Contributing

📝 License

⚠️ Important Notes

Spotify Premium Required

OpenAI API Costs

API Rate Limits

💬 Support

AI Features (Generation, OpenAI, Preferences)

Web Client Features (Playback, UI, Spotify Integration)

🌟 Show Your Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages