Auto Music Player for Spotify

An intelligent, automated music player for Spotify that learns your preferences and creates personalized playlists based on your listening habits, mood, and context.

Overview

Auto Music is a web-based application that integrates with Spotify to provide:

Smart Playback Tracking: Automatically monitors what you're listening to and learns from your behavior
AI-Powered Recommendations: Generates personalized playlists based on your mood, activity, and preferences
Rating System: Like/dislike tracks to train the recommendation engine
Context-Aware Playlists: Create playlists for different moods (workout, focus, chill, etc.)
Analytics Dashboard: Visualize your listening patterns and discover trends
Seamless Integration: Works directly with your Spotify account

Key Features

🎵 Automated Playlist Generation: Create playlists that match your current mood or activity
🧠 Machine Learning: Learns from your listening habits to improve recommendations
📊 Analytics: Track your music preferences over time
🎯 Context-Aware: Different playlists for workout, focus, relaxation, and more
⚡ Real-time Updates: Syncs with Spotify in real-time
🔒 Secure: OAuth 2.0 authentication with Spotify

Architecture

┌─────────────────────────────────────────────────────────────┐
│                 Web Interface (Frontend)                     │
│                  React + TypeScript                          │
└──────────────────────┬──────────────────────────────────────┘
                       │ REST API (HTTPS)
┌──────────────────────▼──────────────────────────────────────┐
│              Python Backend (FastAPI)                        │
│  • Spotify Client    • Rating Manager                       │
│  • Smart Playback    • Recommendation Engine                │
└───────┬──────────────────────────────────┬─────────────────┘
        │                                  │
┌───────▼────────┐                  ┌──────▼──────────┐
│ Redis Cache    │                  │ Celery Workers  │
│ • Sessions     │                  │ • Metadata      │
│ • API cache    │                  │ • Updates       │
└───────┬────────┘                  └──────┬──────────┘
        │                                  │
        └──────────────┬───────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                 PostgreSQL Database                          │
│  • User Preferences  • Track History  • Ratings             │
└──────────────────────────────────────────────────────────────┘

Tech Stack

Frontend:

React 18 with TypeScript
Material-UI for components
React Query for data fetching
WebSocket for real-time updates

Backend:

FastAPI (Python 3.11+)
SQLAlchemy ORM
Alembic for migrations
Celery for background tasks
Redis for caching and message broker

Infrastructure:

PostgreSQL 15 for database
Redis 7 for caching
Docker & Docker Compose
Nginx (production)

Prerequisites

Before you begin, ensure you have the following installed:

Docker: Version 20.10 or higher
Docker Compose: Version 2.0 or higher
Git: For cloning the repository
Spotify Account: A Spotify Premium account (required for playback control)
Spotify Developer Account: To create API credentials

Get Spotify API Credentials

Go to Spotify Developer Dashboard
Log in with your Spotify account
Click "Create an App"
Fill in the app details:
- App Name: Auto Music (or your preferred name)
- App Description: Personal music automation
- Redirect URI: http://localhost:8000/auth/callback
Save your Client ID and Client Secret

Quick Start

1. Clone the Repository

git clone https://github.com/yourusername/AutoMusic.git
cd AutoMusic

2. Configure Environment Variables

# Copy the example environment file
cp .env.example .env

# Edit .env and add your Spotify credentials
nano .env  # or use your preferred editor

Required variables to set:

# Spotify API credentials (from previous step)
SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://localhost:8000/auth/callback

# Generate a secure secret key
SECRET_KEY=$(openssl rand -hex 32)

3. Start the Application

For Development (with hot reload):

docker-compose -f docker-compose.dev.yml up --build

For Production:

docker-compose up --build -d

4. Access the Application

Frontend: http://localhost:3000
Backend API: http://localhost:8000
API Documentation: http://localhost:8000/docs

5. First-Time Setup

Open http://localhost:3000 in your browser
Click "Connect to Spotify"
Authorize the application
Start playing music on Spotify
Rate tracks to train your preferences

Development Setup

Project Structure

AutoMusic/
├── backend/                 # Python FastAPI backend
│   ├── app/
│   │   ├── api/            # API routes
│   │   ├── core/           # Core configuration
│   │   ├── db/             # Database models & migrations
│   │   ├── services/       # Business logic
│   │   ├── tasks/          # Celery tasks
│   │   └── main.py         # FastAPI app entry point
│   ├── tests/              # Backend tests
│   ├── Dockerfile          # Production Dockerfile
│   ├── Dockerfile.dev      # Development Dockerfile
│   └── requirements.txt    # Python dependencies
├── frontend/               # React TypeScript frontend
│   ├── public/            # Static assets
│   ├── src/
│   │   ├── components/    # React components
│   │   ├── hooks/         # Custom React hooks
│   │   ├── services/      # API client
│   │   ├── types/         # TypeScript types
│   │   └── App.tsx        # Main app component
│   ├── Dockerfile         # Production Dockerfile
│   ├── Dockerfile.dev     # Development Dockerfile
│   └── package.json       # Node dependencies
├── docker-compose.yml      # Production compose file
├── docker-compose.dev.yml  # Development compose file
├── .env.example           # Environment variables template
├── .gitignore            # Git ignore rules
├── PLAN.md               # Detailed system plan
└── README.md             # This file

Running Development Environment

The development environment includes:

Hot reload for both frontend and backend
Debug logging enabled
Source code mounted as volumes
Exposed database and Redis ports

# Start all services
docker-compose -f docker-compose.dev.yml up

# Start specific service
docker-compose -f docker-compose.dev.yml up backend

# View logs
docker-compose -f docker-compose.dev.yml logs -f backend

# Restart a service
docker-compose -f docker-compose.dev.yml restart backend

# Stop all services
docker-compose -f docker-compose.dev.yml down

Running Tests

# Backend tests
docker-compose -f docker-compose.dev.yml exec backend pytest

# Frontend tests
docker-compose -f docker-compose.dev.yml exec frontend npm test

# With coverage
docker-compose -f docker-compose.dev.yml exec backend pytest --cov=app

Database Migrations

# Create a new migration
docker-compose -f docker-compose.dev.yml exec backend alembic revision --autogenerate -m "description"

# Apply migrations
docker-compose -f docker-compose.dev.yml exec backend alembic upgrade head

# Rollback migration
docker-compose -f docker-compose.dev.yml exec backend alembic downgrade -1

Accessing Services

PostgreSQL:

docker-compose -f docker-compose.dev.yml exec postgres psql -U automusic -d automusic_dev

Redis CLI:

docker-compose -f docker-compose.dev.yml exec redis redis-cli

Backend Shell:

docker-compose -f docker-compose.dev.yml exec backend python

Environment Variables

Required Variables

Variable	Description	Example
`SPOTIFY_CLIENT_ID`	Spotify app client ID	`abc123...`
`SPOTIFY_CLIENT_SECRET`	Spotify app client secret	`xyz789...`
`SPOTIFY_REDIRECT_URI`	OAuth callback URL	`http://localhost:8000/auth/callback`
`SECRET_KEY`	JWT signing key	Generate with `openssl rand -hex 32`
`DATABASE_URL`	PostgreSQL connection string	`postgresql://user:pass@host:5432/db`
`REDIS_URL`	Redis connection string	`redis://localhost:6379/0`

Optional Variables

Variable	Description	Default
`ENVIRONMENT`	Environment mode	`development`
`DEBUG`	Enable debug mode	`true`
`LOG_LEVEL`	Logging level	`INFO`
`FRONTEND_URL`	Frontend URL for CORS	`http://localhost:3000`
`API_RATE_LIMIT_PER_MINUTE`	API rate limit	`60`

See .env.example for complete list of configuration options.

API Documentation

Once the backend is running, you can access:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
OpenAPI JSON: http://localhost:8000/openapi.json

Troubleshooting

Common Issues

1. Docker containers won't start

# Check logs
docker-compose -f docker-compose.dev.yml logs

# Rebuild containers
docker-compose -f docker-compose.dev.yml up --build --force-recreate

2. Database connection errors

# Wait for PostgreSQL to be ready
docker-compose -f docker-compose.dev.yml up postgres
# Wait until you see "database system is ready to accept connections"

3. Spotify authentication fails

Verify your Client ID and Secret are correct
Check that the Redirect URI in Spotify Dashboard matches .env
Ensure the redirect URI includes the protocol (http://)

4. Port conflicts

# Check what's using the port
sudo lsof -i :8000  # or :3000, :5432, :6379

# Change ports in docker-compose.dev.yml if needed

5. Frontend can't connect to backend

Check REACT_APP_API_URL in .env
Verify backend is running: curl http://localhost:8000/health
Check browser console for CORS errors

Getting Help

Check the PLAN.md for detailed system documentation
Review the QUICK_START.md for implementation guides
Open an issue on GitHub
Check application logs: docker-compose logs -f

Roadmap

Phase 1: Core Functionality (Current)

✅ Project setup and infrastructure
⏳ Spotify integration
⏳ Basic playlist generation
⏳ Rating system
⏳ Playback tracking

Phase 2: AI & Machine Learning

⏳ Advanced recommendation engine
⏳ Mood detection
⏳ Context-aware playlisting
⏳ Collaborative filtering

Phase 3: Enhanced Features

⏳ Social features
⏳ Playlist sharing
⏳ Advanced analytics
⏳ Mobile app

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting pull requests.

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Commit your changes: git commit -am 'Add new feature'
Push to the branch: git push origin feature/your-feature
Submit a pull request

License

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

Acknowledgments

Built with Spotify Web API
Powered by FastAPI
UI built with React and Material-UI

Security

Never commit .env files or credentials
Rotate your SECRET_KEY regularly in production
Use environment-specific credentials
Keep dependencies updated
Review the Security Best Practices

Support

For support, please open an issue on GitHub or contact the maintainers.

Happy Listening! 🎵

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
backend		backend
frontend		frontend
rec		rec
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
AI_RECOMMENDATIONS.md		AI_RECOMMENDATIONS.md
ENHANCED_DJ_SYSTEM.md		ENHANCED_DJ_SYSTEM.md
INTEGRATION_REPORT.md		INTEGRATION_REPORT.md
OAUTH_IMPLEMENTATION_SUMMARY.md		OAUTH_IMPLEMENTATION_SUMMARY.md
PHASE_3-4_COMPLETE.md		PHASE_3-4_COMPLETE.md
PLAN.md		PLAN.md
QUICK_START.md		QUICK_START.md
README.md		README.md
RECOMMENDATIONS_AND_MOODS_FIX.md		RECOMMENDATIONS_AND_MOODS_FIX.md
SECURITY_FIXES_SUMMARY.md		SECURITY_FIXES_SUMMARY.md
SECURITY_VULNERABILITY_REPORT.md		SECURITY_VULNERABILITY_REPORT.md
SPOTIFY_RECOMMENDATIONS_FIX.md		SPOTIFY_RECOMMENDATIONS_FIX.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
security_audit.py		security_audit.py
security_audit_report.json		security_audit_report.json
test_recommendations_debug.py		test_recommendations_debug.py
validate_integration.py		validate_integration.py

Bitwarelabscom/AutoMusic

Folders and files

Latest commit

History

Repository files navigation