Modern Spotify Playlist & Music Library Management Platform
Explore the repo »
View Demo
·
Report Bug
·
Request Feature
Table of Contents
Sputilities is a powerful, modern web application designed to enhance your Spotify experience by providing advanced playlist and music library management tools that go beyond Spotify's native capabilities. Built with React and a beautiful Spotify-inspired UI, Sputilities makes managing your music collection effortless and enjoyable.
Spotify is amazing for discovering and playing music, but it has limitations when it comes to managing large music libraries:
- Liked Songs are private - You can't easily share your entire liked songs collection
- No bulk operations - Managing hundreds of playlists manually is tedious
- Limited filtering - Can't filter by audio features like tempo, energy, or mood
- No duplicate detection - Hard to find and remove duplicate tracks
- Basic analytics - Limited insights into your music preferences
Sputilities solves all of these problems and more!
- Create, edit, and delete playlists with ease
- Bulk operations for managing multiple playlists at once
- Drag-and-drop playlist organization
- Quick playlist duplication and cloning
- Convert your private liked songs into shareable playlists
- Backup and restore your liked songs collection
- Sync liked songs across devices
- Export liked songs to various formats
- Duplicate Detection: Find and remove duplicate tracks across playlists
- Playlist Comparison: Compare two playlists to find common or unique tracks
- Smart Merging: Intelligently merge multiple playlists with conflict resolution
- Auto-sorting: Sort playlists by various criteria (artist, album, date added, etc.)
- Filter tracks by audio features (tempo, energy, danceability, mood)
- Search by genre, artist, album, or release year
- Create smart playlists based on complex criteria
- Save and reuse filter presets
- Visualize your music taste with interactive charts
- Track listening patterns and trends
- Discover your most played artists and genres
- Get personalized music recommendations
- Background task processing for large operations
- Live progress tracking with detailed status updates
- Operation history and logs
- Automatic retry on failures
- React 18 - Modern UI library with hooks and concurrent features
- Vite - Lightning-fast build tool and dev server
- Tailwind CSS - Utility-first CSS framework
- Framer Motion - Production-ready animation library
- Zustand - Lightweight state management
- React Query - Powerful data synchronization and caching
- Axios - Promise-based HTTP client with interceptors
- Radix UI - Accessible component primitives
- Headless UI - Unstyled, accessible UI components
- Lucide React - Beautiful, consistent icon set
- React Hot Toast - Lightweight notification system
- React Router v6 - Declarative routing with lazy loading
- ESLint - Code linting and quality checks
- Vitest - Fast unit testing framework
- PostCSS - CSS transformations and optimizations
- Node.js - Backend runtime environment
- Express - Web application framework
- MongoDB - NoSQL database for data persistence
- Spotify Web API - Official Spotify API integration
Before you begin, ensure you have the following installed:
- Node.js (v18.0.0 or higher) - Download
- npm (v9.0.0 or higher) - Comes with Node.js
- Git - Download
- Spotify Account - Sign up
Follow these steps to get Sputilities running on your local machine:
# Clone the repository
git clone https://github.com/yourusername/sputilities.git
# Navigate to the frontend directory
cd sputilities/Frontend/sputilities# Install all required packages
npm installThis will install all dependencies listed in package.json, including:
- React and React DOM
- Vite build tool
- Tailwind CSS
- Framer Motion
- Zustand and React Query
- And many more...
Create a .env file in the Frontend/sputilities directory:
# Copy the example environment file
cp .env.example .envEdit the .env file with your configuration:
# API Configuration
VITE_API_URL=http://localhost:3601/api/v1
# Application Environment
VITE_APP_ENV=development
# Feature Flags
VITE_ENABLE_PERFORMANCE_MONITORING=true
VITE_ENABLE_ANALYTICS=false
# Optional: Monitoring & Analytics
VITE_SENTRY_DSN=your-sentry-dsn-here
VITE_GA_TRACKING_ID=your-google-analytics-id# Start the Vite development server
npm run devThe application will be available at http://localhost:5173 🎉
In a separate terminal, start the backend server:
# Navigate to the backend directory
cd ../../Backend
# Install backend dependencies
npm install
# Start the backend server
npm startThe backend API will run on http://localhost:3601
# Development
npm run dev # Start development server (port 5173)
npm run build # Build for production
npm run preview # Preview production build locally
npm run lint # Run ESLint to check code quality
# Testing
npm run test # Run unit tests
npm run test:ui # Run tests with UI interface-
Login with Spotify
- Click "Login with Spotify" on the landing page
- Authorize Sputilities to access your Spotify account
- You'll be redirected to the dashboard
-
Explore Your Music
- View your playlists in the Playlist Manager
- Check out your liked songs collection
- Explore analytics and insights
-
Try Smart Features
- Use duplicate detection to clean up your playlists
- Compare playlists to find common tracks
- Merge playlists intelligently
1. Navigate to "Liked Songs" page
2. Click "Convert to Playlist"
3. Choose a name for your new playlist
4. Select tracks to include (or select all)
5. Click "Create Playlist"
1. Go to "Smart Features" page
2. Select "Duplicate Detection"
3. Choose playlists to scan
4. Review detected duplicates
5. Select duplicates to remove
6. Click "Remove Selected"
1. Open any playlist
2. Click "Advanced Filters"
3. Adjust sliders for tempo, energy, danceability, etc.
4. Apply filters to see matching tracks
5. Save as a new playlist or update existing
Frontend/sputilities/
├── public/ # Static assets
│ ├── _redirects # Netlify redirects for SPA routing
│ └── robots.txt # SEO robots configuration
│
├── src/
│ ├── App/ # Legacy app components
│ │ └── assets/ # Images, fonts, and static files
│ │ ├── sputilities.svg # App logo
│ │ └── fonts/ # Custom Spotify fonts
│ │
│ ├── components/ # Reusable UI components
│ │ ├── Alert.jsx # Alert/notification component
│ │ ├── Badge.jsx # Badge component
│ │ ├── Button.jsx # Custom button component
│ │ ├── Card.jsx # Card container component
│ │ ├── ErrorBoundary.jsx # Error boundary wrapper
│ │ ├── Header.jsx # Application header
│ │ ├── Input.jsx # Form input component
│ │ ├── Layout.jsx # Main layout wrapper
│ │ ├── LoadingSpinner.jsx # Loading indicator
│ │ ├── Modal.jsx # Modal dialog component
│ │ ├── PlaylistCard.jsx # Playlist display card
│ │ ├── Progress.jsx # Progress bar component
│ │ ├── ProtectedRoute.jsx # Route authentication wrapper
│ │ ├── Sidebar.jsx # Navigation sidebar
│ │ ├── Skeleton.jsx # Loading skeleton component
│ │ └── Tooltip.jsx # Tooltip component
│ │
│ ├── pages/ # Page components (routes)
│ │ ├── AuthCallback.jsx # OAuth callback handler
│ │ ├── Dashboard.jsx # Main dashboard page
│ │ ├── LandingPage.jsx # Marketing landing page
│ │ ├── LikedSongs.jsx # Liked songs management
│ │ ├── Login.jsx # Login page
│ │ ├── NotFound.jsx # 404 error page
│ │ ├── Operations.jsx # Background operations tracking
│ │ ├── PlaylistManager.jsx # Playlist CRUD operations
│ │ ├── Settings.jsx # User settings page
│ │ └── SmartFeatures.jsx # Advanced features page
│ │
│ ├── hooks/ # Custom React hooks
│ │ ├── useApiQuery.js # Enhanced React Query hooks
│ │ ├── useAuth.js # Authentication hook
│ │ ├── useKeyboardNavigation.js # Keyboard navigation
│ │ └── useResponsive.js # Responsive design hook
│ │
│ ├── services/ # API services
│ │ └── api.js # Axios API client with interceptors
│ │
│ ├── store/ # State management (Zustand)
│ │ ├── appStore.js # Global application state
│ │ └── authStore.js # Authentication state
│ │
│ ├── utils/ # Utility functions
│ │ ├── dataManager.js # Data caching and synchronization
│ │ ├── lazyLoading.jsx # Lazy loading utilities
│ │ ├── performance.js # Performance monitoring
│ │ └── testUtils.js # Testing utilities
│ │
│ ├── Router/ # Routing configuration
│ │ └── Content.jsx # Main router with lazy loading
│ │
│ ├── index.css # Global styles and Tailwind imports
│ └── main.jsx # Application entry point
│
├── .env.example # Environment variables template
├── .env.production.example # Production environment template
├── .gitignore # Git ignore rules
├── index.html # HTML template with SEO meta tags
├── netlify.toml # Netlify deployment configuration
├── package.json # Dependencies and scripts
├── postcss.config.js # PostCSS configuration
├── README.md # This file
├── tailwind.config.js # Tailwind CSS configuration
├── vercel.json # Vercel deployment configuration
└── vite.config.js # Vite build configuration
Build the application for production:
# Create optimized production build
npm run build
# Preview the production build locally
npm run previewThe build output will be in the dist/ folder, ready for deployment.
Total Bundle Size: ~515 KB (gzipped: ~166 KB)
├── Vendor chunk: 141 KB (gzipped: 45.5 KB)
├── UI chunk: 121 KB (gzipped: 38.5 KB)
├── Main app: 108 KB (gzipped: 36.8 KB)
└── Other chunks: ~145 KB (gzipped: ~45 KB)
Build Time: ~4.5 seconds
Modules: 1,956
# Install Vercel CLI
npm install -g vercel
# Deploy to production
vercel --prodEnvironment Variables in Vercel:
- Go to your project settings
- Navigate to "Environment Variables"
- Add:
VITE_API_URL=https://your-api-domain.com/api/v1
# Install Netlify CLI
npm install -g netlify-cli
# Deploy to production
netlify deploy --prodEnvironment Variables in Netlify:
- Go to Site settings → Build & deploy → Environment
- Add:
VITE_API_URL=https://your-api-domain.com/api/v1
- Build the application:
npm run build - Upload the
dist/folder to your hosting provider - Configure environment variables on your hosting platform
- Ensure your server is configured for SPA routing (all routes → index.html)
- Backend API is deployed and accessible
-
VITE_API_URLenvironment variable is set correctly - CORS is configured on the backend for your frontend domain
- SSL certificate is active (HTTPS)
- Environment variables are set in hosting platform
- Build completes without errors
- All routes work correctly (SPA routing configured)
- Assets load properly
- Test login flow end-to-end
- Spotify OAuth authentication
- Dashboard with user statistics
- Playlist CRUD operations
- Liked songs management
- Duplicate detection
- Playlist comparison
- Smart playlist merging
- Advanced filtering by audio features
- Real-time operation tracking
- Responsive design
- Error handling and retry logic
- Performance optimizations
- Collaborative Playlists: Manage collaborative playlists with friends
- Playlist Templates: Create and share playlist templates
- Music Discovery: AI-powered music recommendations
- Listening History: Track and analyze your listening history
- Social Features: Share playlists and follow other users
- Mobile App: Native iOS and Android applications
- Offline Mode: Download playlists for offline access
- Advanced Analytics: More detailed insights and visualizations
- Playlist Scheduling: Auto-update playlists based on schedules
- Integration with Other Services: Apple Music, YouTube Music, etc.
- Dark/Light theme toggle
- Customizable dashboard widgets
- Keyboard shortcuts
- Playlist versioning and history
- Export playlists to various formats (CSV, JSON, M3U)
- Bulk playlist operations
- Advanced search with regex support
- Playlist recommendations based on mood/activity
See the open issues for a full list of proposed features and known issues.
We welcome contributions from the community! Here's how you can help:
Before you start, please review the following project documents:
- Contributing Guide: CONTRIBUTING.md
- Code of Conduct: CODE_OF_CONDUCT.md
- Security Policy: SECURITY.md
-
Fork the Repository
git clone https://github.com/yourusername/sputilities.git cd sputilities -
Create a Feature Branch
git checkout -b feature/amazing-feature
-
Make Your Changes
- Write clean, readable code
- Follow the existing code style
- Add comments where necessary
- Update documentation if needed
-
Test Your Changes
npm run lint # Check code quality npm run test # Run tests npm run build # Ensure build works
-
Commit Your Changes
git add . git commit -m "Add amazing feature"
-
Push to Your Fork
git push origin feature/amazing-feature
-
Open a Pull Request
- Go to the original repository
- Click "New Pull Request"
- Describe your changes in detail
- Link any related issues
- Code Style: Follow the ESLint configuration
- Components: Use functional components with hooks
- State Management: Use Zustand for global state, React Query for server state
- Styling: Use Tailwind CSS utility classes
- Accessibility: Include ARIA labels and keyboard navigation
- Error Handling: Always include error boundaries and loading states
- Testing: Write tests for new features and bug fixes
- Documentation: Update README and add JSDoc comments
Found a bug? Please open an issue with:
- Clear description of the bug
- Steps to reproduce
- Expected vs actual behavior
- Screenshots (if applicable)
- Browser and OS information
Have an idea? Open a feature request with:
- Clear description of the feature
- Use cases and benefits
- Possible implementation approach
- Mockups or examples (if applicable)
This project is licensed under the MIT License - see the LICENSE file for details.
MIT License
Copyright (c) 2024 Sputilities
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Project Maintainer: Your Name
- GitHub: @yourusername
- Email: [email protected]
- Twitter: @yourhandle
Project Link: https://github.com/yourusername/sputilities
Live Demo: https://sputilities.vercel.app
Special thanks to:
- Spotify - For the amazing music streaming platform and API
- Spotify Web API - For comprehensive API documentation
- React Team - For the incredible React library
- Vite Team - For the blazing-fast build tool
- Tailwind CSS - For the utility-first CSS framework
- Framer Motion - For beautiful animations
- Radix UI - For accessible component primitives
- Lucide Icons - For the beautiful icon set
- TanStack Query - For powerful data synchronization
- Zustand - For simple state management
This project was inspired by the need for better playlist management tools and the limitations of Spotify's native interface. Special thanks to the open-source community for providing excellent tools and libraries that made this project possible.
- Spotify for Developers
- React Documentation
- Vite Documentation
- Tailwind CSS Documentation
- MDN Web Docs
Made with ❤️ and ☕ by the Sputilities Team