Hugging Face's logo

Spaces:
findEthics
/
spotify-web-app
Build error

App Files Community
spotify-web-app / README.md
findEthics
Add smart playlist filtering and clean minimal UI
5baeff7
preview code
|
Raw
History Blame Contribute Delete
10.6 kB
metadata 
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 

npm install

🛠️ Local Development

1. Create Environment File 

cp .env.example .env

Edit .env and add your Spotify credentials:

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:

  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 

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, 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 🚀