Spaces:
Build error
Build error
| title: Spotify Web Player | |
| emoji: 🎵 | |
| colorFrom: gray | |
| colorTo: indigo | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| license: mit | |
| short_description: 'Complete Spotify Web Player for mobile & e-ink displays' | |
| # Spotify Web Player | |
| A modern Spotify Web Player application designed for deployment on Hugging Face Spaces, optimized for mobile Android browsers and e-ink displays. | |
| ## ✨ Current Features | |
| ### 🎵 Core Functionality | |
| - **Complete Spotify OAuth Integration**: Secure authentication flow | |
| - **Playlist Browser**: View and browse all user playlists with pagination support | |
| - **Track Selection**: Click-to-play functionality for individual tracks | |
| - **Web Playback Controls**: Play, pause, previous, next controls via Spotify Web Playback SDK | |
| - **Device Management**: Transfer playback between available Spotify devices | |
| - **Real-time State Updates**: Live track information and playback status | |
| ### 🎨 UI/UX Design | |
| - **E-ink Optimized**: Black and white color scheme for e-ink displays | |
| - **Mobile-first Responsive**: Optimized for Android phone browsers | |
| - **Modern Typography**: Roboto font family with system fallbacks | |
| - **Rounded Design**: Smooth borders and rounded edges for aesthetic appeal | |
| - **Persistent Navigation**: Home and Logout buttons across all pages | |
| - **Fixed Bottom Controls**: Always-visible playback controls at bottom of screen | |
| - **Improved Button Icons**: Distinct play/pause (⏯/⏸), previous (⏮), and next (⏭) buttons | |
| - **Smart Playlist Filtering**: Two-category system (My Playlists vs Others) | |
| - **Clean Minimal Interface**: Streamlined header without redundant text | |
| - **Error Handling**: User-friendly error messages with auto-clearing | |
| ### 🔧 Technical Features | |
| - **Session Management**: Secure token storage and management | |
| - **Multiple API Fallbacks**: Robust playback strategies for reliability | |
| - **Progressive Web App**: Mobile-optimized meta tags and touch targets | |
| - **Comprehensive Scopes**: Full playlist and playback permissions | |
| ## 🚀 Setup | |
| ### Environment Variables | |
| The following environment variables are required: | |
| - `SPOTIFY_CLIENT_ID`: Your Spotify app's client ID | |
| - `SPOTIFY_CLIENT_SECRET`: Your Spotify app's client secret | |
| ### Required Spotify Scopes | |
| The application requests these Spotify permissions: | |
| - `streaming`: Web Playback SDK access | |
| - `user-read-email`: User profile information | |
| - `user-read-private`: User profile information | |
| - `playlist-read-private`: Access to private playlists | |
| - `playlist-read-collaborative`: Access to collaborative playlists | |
| - `user-read-playback-state`: Current playback information | |
| - `user-modify-playback-state`: Control playback | |
| - `user-read-currently-playing`: Currently playing track | |
| ### Installation | |
| ```bash | |
| npm install | |
| ``` | |
| ## 🛠️ Local Development | |
| ### 1. Create Environment File | |
| ```bash | |
| cp .env.example .env | |
| ``` | |
| Edit `.env` and add your Spotify credentials: | |
| ```env | |
| SPOTIFY_CLIENT_ID=your_actual_client_id | |
| SPOTIFY_CLIENT_SECRET=your_actual_client_secret | |
| PORT=7860 | |
| NODE_ENV=development | |
| ``` | |
| ### 2. Configure Spotify App | |
| In your [Spotify Developer Dashboard](https://developer.spotify.com/dashboard): | |
| 1. Go to your app settings | |
| 2. Add this redirect URI: `http://127.0.0.1:7860/callback` | |
| 3. Ensure your app has all required scopes enabled | |
| 4. Save the changes | |
| **Important**: You need a **Spotify Premium account** for Web Playback SDK functionality. | |
| ### 3. Run Locally | |
| ```bash | |
| npm run local | |
| ``` | |
| This will start the server on port 7860 with local development settings. | |
| Open your browser to: `http://127.0.0.1:7860` | |
| ### 4. Test the Complete Flow | |
| 1. Click "Login with Spotify" | |
| 2. Authorize the app in the Spotify popup | |
| 3. Browse your playlists on the main interface | |
| 4. Click on any track to start playback | |
| 5. Use playback controls (play/pause/previous/next) | |
| 6. Test device transfer functionality | |
| ## 📱 User Journey | |
| ``` | |
| 🏠 Home Page → 🔐 Spotify Login → ✅ Authorization → | |
| 📋 Playlist Browser → 🎵 Track Selection → ▶️ Automatic Playback | |
| ``` | |
| ### Key Interactions: | |
| - **Track Selection**: Click any track to immediately start playback | |
| - **Fixed Controls**: Always-visible playback controls at bottom of screen | |
| - **Playlist Filtering**: Toggle between "My Playlists" and "Others" for organized browsing | |
| - **Improved Icons**: Distinct button symbols for better usability | |
| - **Device Transfer**: Switch playback between different Spotify devices | |
| - **Navigation**: Persistent home/logout buttons for easy navigation | |
| ## 🏗️ Architecture | |
| ### Backend (`server.js`) | |
| - **Express.js** server with RESTful API endpoints | |
| - **OAuth 2.0** authorization code flow implementation | |
| - **Session management** with in-memory token storage | |
| - **Spotify API integration** for playlists, tracks, and devices | |
| ### Frontend | |
| - **Vanilla JavaScript** with modern ES6+ features | |
| - **Spotify Web Playback SDK** for browser-based music playback | |
| - **Mobile-first CSS** with responsive breakpoints | |
| - **Progressive enhancement** for better user experience | |
| ### API Endpoints | |
| - `GET /`: Home page | |
| - `GET /auth/login`: Initiate Spotify OAuth flow | |
| - `GET /callback`: Handle OAuth callback | |
| - `GET /api/token/:sessionId`: Get access token | |
| - `GET /api/playlists/:sessionId`: Fetch user playlists | |
| - `GET /api/playlist/:playlistId/:sessionId`: Get playlist tracks | |
| - `GET /api/devices/:sessionId`: List available devices | |
| - `PUT /api/transfer/:sessionId`: Transfer playback to device | |
| ## 🎨 Design System | |
| ### Color Scheme | |
| - **Background**: Pure white (`#ffffff`) | |
| - **Text/Borders**: Pure black (`#000000`) | |
| - **Optimized for**: E-ink displays and high contrast | |
| ### Typography | |
| - **Primary Font**: Roboto | |
| - **Fallbacks**: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif | |
| - **Responsive sizing**: Scales from mobile to desktop | |
| ### Layout | |
| - **Mobile-first**: 320px+ breakpoints | |
| - **Touch-friendly**: 48px minimum touch targets | |
| - **Grid system**: Flexible responsive containers | |
| ## 🚢 Production Deployment | |
| ### Hugging Face Spaces | |
| This app is configured as a **Docker Space** to support environment variables. | |
| #### 1. Set Environment Variables (Secrets) | |
| In your Hugging Face Space settings, add these secrets: | |
| - `SPOTIFY_CLIENT_ID`: Your Spotify app client ID | |
| - `SPOTIFY_CLIENT_SECRET`: Your Spotify app client secret | |
| #### 2. Update Spotify App Settings | |
| In your [Spotify Developer Dashboard](https://developer.spotify.com/dashboard), add this redirect URI: | |
| ``` | |
| https://findethics-spotify-web-app.hf.space/callback | |
| ``` | |
| **Important**: Make sure this exact URI is added to your Spotify app's redirect URIs list. | |
| #### 3. Deployment | |
| The application automatically: | |
| - Runs on port 7860 (required for HF Spaces) | |
| - Detects Hugging Face environment | |
| - Uses space URL for redirect URI | |
| - Builds and runs via Docker | |
| ### Environment Detection | |
| The app automatically detects deployment environment: | |
| - **Local**: Uses `127.0.0.1:7860` for redirect URI | |
| - **Hugging Face**: Uses space URL for redirect URI | |
| ## 📁 File Structure | |
| ``` | |
| ├── server.js # Express server with full API | |
| ├── package.json # Dependencies and scripts | |
| ├── .env.example # Environment template | |
| ├── .gitignore # Git ignore configuration | |
| ├── public/ | |
| │ ├── index.html # Home page with login | |
| │ ├── success.html # OAuth success page | |
| │ └── playlist.html # Main app interface | |
| ├── README.md # This documentation | |
| └── docs/ # Additional documentation | |
| ``` | |
| ## 🔄 Application Flow | |
| ### Authentication | |
| 1. User visits home page | |
| 2. Clicks "Login with Spotify" | |
| 3. Redirected to Spotify OAuth | |
| 4. Grants permissions to app | |
| 5. Returns with authorization code | |
| 6. Server exchanges code for access token | |
| 7. User redirected to playlist interface | |
| ### Music Playback | |
| 1. App loads user's playlists | |
| 2. User selects a playlist | |
| 3. Playlist tracks are displayed | |
| 4. User clicks on any track | |
| 5. **Automatic playback begins immediately** | |
| 6. Playback controls become available | |
| 7. User can control music and switch devices | |
| ## 🐛 Known Issues & Solutions | |
| ### First-Time Track Selection | |
| - **Issue**: First track selection after login may not start playback immediately | |
| - **Workaround**: Click the play button after track selection | |
| - **Root Cause**: Web Player device activation timing | |
| - **Status**: Improved with device transfer logic | |
| ### Session Management | |
| - **Issue**: Sessions lost on server restart during development | |
| - **Solution**: Re-authenticate after server restart | |
| - **Status**: Expected behavior for development | |
| ### Device List Updates | |
| - **Issue**: Device list may show "Failed to load devices" after server restart | |
| - **Solution**: Refresh browser page and re-login to get fresh session | |
| - **Root Cause**: Session tokens become invalid after server restart | |
| - **Status**: Fixed with server restart detection | |
| ### Device Compatibility | |
| - **Requirement**: Spotify Premium account needed for Web Playback SDK | |
| - **Fallback**: Basic API controls available for non-Premium | |
| ## 🔮 Future Enhancements | |
| ### Planned Features | |
| - [ ] **Offline Queue**: Local track queueing | |
| - [ ] **Search Functionality**: Search tracks, artists, albums | |
| - [ ] **Recently Played**: Display recent listening history | |
| - [ ] **Volume Control**: SDK-based volume management | |
| - [ ] **Shuffle/Repeat**: Advanced playback modes | |
| - [ ] **Cross-fade**: Smooth track transitions | |
| ### Technical Improvements | |
| - [ ] **Persistent Sessions**: Database-backed session storage | |
| - [ ] **Real-time Sync**: WebSocket-based state synchronization | |
| - [ ] **Progressive Loading**: Lazy-load playlists and tracks | |
| - [ ] **Caching Strategy**: Optimize API calls and loading | |
| - [ ] **Error Recovery**: Advanced retry mechanisms | |
| ## 🤝 Contributing | |
| ### Development Setup | |
| 1. Fork the repository | |
| 2. Create a feature branch | |
| 3. Follow the local development setup | |
| 4. Test thoroughly on mobile browsers | |
| 5. Submit a pull request | |
| ### Code Style | |
| - Use modern ES6+ JavaScript | |
| - Follow mobile-first responsive design | |
| - Maintain e-ink display compatibility | |
| - Write descriptive commit messages | |
| ## 📄 License | |
| This project is licensed under the MIT License - see the LICENSE file for details. | |
| ## 🙏 Acknowledgments | |
| - **Spotify Web API**: Core music data and playback | |
| - **Spotify Web Playback SDK**: Browser-based music streaming | |
| - **Hugging Face Spaces**: Hosting and deployment platform | |
| - **Express.js**: Server framework | |
| - **Android System Fonts**: Typography foundation | |
| --- | |
| **Last Updated**: January 2025 | |
| **Version**: 2.2.0 | |
| **Status**: Production Ready 🚀 | |