🎵 Spotify React Player

A modern and fully customizable React MP3 player component inspired by Spotify's design. Built with TypeScript and styled with Tailwind CSS.

✨ Features

• 🎵 MP3 file playback
• ⏯️ Play/Pause controls
• ⏭️ Next/Previous track navigation
• 🔊 Volume control with visual feedback
• 📊 Interactive progress bar
• ⏱️ Time display
• ❤️ Like/Unlike functionality
• 🔀 Shuffle mode
• 🔁 Repeat mode
• ✨ Blur effects and glow animations
• 🎨 Fully customizable theme
• 📱 Responsive design
• 🔧 TypeScript support
• 🎭 Loading states with animations
• 🌟 Spotify-like glass morphism UI
• 🚫 Advanced error handling
• 🔄 Automatic track transitions

📦 Installation

npm install spotify-react-player-local

or

yarn add spotify-react-player-local

🚀 Usage

Basic Usage

import React from 'react';
import { SpotifyPlayer, Track } from 'spotify-react-player-local';

const tracks: Track[] = [
  {
    id: '1',
    title: 'Song Title',
    artist: 'Artist Name',
    album: 'Album Name',
    duration: 180,
    src: 'path/to/audio.mp3',
    cover: 'path/to/cover.jpg'
  }
];

function App() {
  return (
    <SpotifyPlayer
      tracks={tracks}
      config={{
        autoPlay: false,
        showVolumeControl: true,
        showProgressBar: true,
        volume: 0.7
      }}
      onTrackChange={(track) => console.log('Track changed:', track)}
      onPlayStateChange={(isPlaying) => console.log('Playing:', isPlaying)}
      onTimeUpdate={(current, duration) => console.log('Time:', current, duration)}
    />
  );
}

Advanced Usage

import React, { useState } from 'react';
import { SpotifyPlayer, Track, PlayerConfig } from 'spotify-react-player-local';

const MyMusicPlayer = () => {
  const [currentTrack, setCurrentTrack] = useState<Track | null>(null);
  const [isPlaying, setIsPlaying] = useState(false);

  const config: PlayerConfig = {
    autoPlay: false,
    loop: false,
    shuffle: false,
    volume: 0.8,
    showPlaylist: true,
    showVolumeControl: true,
    showProgressBar: true,
    showTimeDisplay: true,
    showLikeButton: true,
    showShuffleRepeat: true,
    theme: {
      primary: '#1db954',
      secondary: '#191414',
      background: '#121212',
      text: '#ffffff',
      accent: '#1ed760'
    },
    className: 'my-custom-player'
  };

  const handleTrackChange = (track: Track) => {
    setCurrentTrack(track);
    console.log('New track:', track.title);
  };

  const handlePlayStateChange = (playing: boolean) => {
    setIsPlaying(playing);
  };

  const handleError = (error: string) => {
    console.error('Player error:', error);
  };

  return (
    <div className="min-h-screen bg-gray-900 p-8">
      <h1 className="text-white text-3xl mb-8">My Music Player</h1>
      
      <SpotifyPlayer
        tracks={myTracks}
        config={config}
        onTrackChange={handleTrackChange}
        onPlayStateChange={handlePlayStateChange}
        onError={handleError}
        onTimeUpdate={(current, duration) => {
          console.log(`${Math.floor(current)}s / ${Math.floor(duration)}s`);
        }}
      />
      
      {currentTrack && (
        <div className="mt-4 text-white">
          <p>Now playing: {currentTrack.title} - {currentTrack.artist}</p>
          <p>Status: {isPlaying ? 'Playing' : 'Paused'}</p>
        </div>
      )}
    </div>
  );
};

🔧 Configuration Options

PlayerConfig

interface PlayerConfig {
  autoPlay?: boolean;          // Auto-play on load (default: false)
  loop?: boolean;              // Loop mode (default: false)
  shuffle?: boolean;           // Shuffle mode (default: false)
  volume?: number;             // Initial volume level (0-1, default: 1)
  showPlaylist?: boolean;      // Show playlist
  showVolumeControl?: boolean; // Show volume control
  showProgressBar?: boolean;   // Show progress bar
  showTimeDisplay?: boolean;   // Show time display
  showLikeButton?: boolean;    // Show like button
  showShuffleRepeat?: boolean; // Show shuffle/repeat buttons
  theme?: PlayerTheme;         // Custom theme
  className?: string;          // Custom CSS class
}

PlayerTheme

interface PlayerTheme {
  primary?: string;    // Primary color (default: '#1db954')
  secondary?: string;  // Secondary color
  background?: string; // Background color
  text?: string;       // Text color
  accent?: string;     // Accent color
}

Track

interface Track {
  id: string;          // Unique identifier
  title: string;       // Song title
  artist: string;      // Artist name
  album?: string;      // Album name (optional)
  duration: number;    // Duration in seconds
  src: string;         // Audio file path
  cover?: string;      // Cover image URL (optional)
}

📝 Event Handlers

onTrackChange

Called when track changes.

onTrackChange?: (track: Track) => void;

onPlayStateChange

Called when play/pause state changes.

onPlayStateChange?: (isPlaying: boolean) => void;

onTimeUpdate

Called during playback with current time updates.

onTimeUpdate?: (currentTime: number, duration: number) => void;

onError

Called when an error occurs.

onError?: (error: string) => void;

onLoadStart / onLoadEnd

Called when loading starts and ends.

onLoadStart?: () => void;
onLoadEnd?: () => void;

🎨 Styling

The component uses Tailwind CSS with custom Spotify-like effects:

Custom CSS Classes

.glass-effect {
  background: rgba(255, 255, 255, 0.05);
  backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.1);
}

.spotify-gradient {
  background: linear-gradient(135deg, #1db954 0%, #1ed760 100%);
}

.glow-animation {
  animation: glow 2s ease-in-out infinite;
}

Theme Customization

const customTheme = {
  primary: '#ff6b6b',      // Red theme
  secondary: '#4ecdc4',    // Teal
  background: '#2c3e50',   // Dark blue
  text: '#ecf0f1',         // Light gray
  accent: '#e74c3c'        // Red accent
};

🚨 Error Handling

The player includes automatic error handling:

• Audio loading errors: Automatically caught and displayed to user
• Playback errors: Promise-based error handling
• Network issues: Graceful degradation
• Invalid audio formats: Appropriate error messages

<SpotifyPlayer
  tracks={tracks}
  onError={(error) => {
    console.error('Player error:', error);
    // Custom error handling
    showNotification('Failed to load audio file', 'error');
  }}
/>

🔄 State Management

The player uses internal state management:

interface PlayerState {
  currentTrack: Track | null;
  isPlaying: boolean;
  currentTime: number;
  duration: number;
  volume: number;
  isLoading: boolean;
  playlist: Track[];
  currentIndex: number;
  isShuffled: boolean;
  isLooped: boolean;
  error?: string;
}

📱 Responsive Design

The player works across all screen sizes:

• Desktop: Full-featured interface
• Tablet: Optimized controls
• Mobile: Touch-friendly controls

🎯 Performance Optimizations

• Lazy loading: Audio files loaded on demand
• Memory management: Event listeners automatically cleaned up
• Efficient re-renders: React.memo and useCallback optimizations
• Preload metadata: Fast startup with metadata preloading

🛠️ Development

Local Development

git clone https://github.com/sw3do/spotify-react-player-local.git
cd spotify-react-player-local
npm install
npm run dev

Build

npm run build

Test

npm run test

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the project
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 Support

For questions and support:

• GitHub Issues

🙏 Acknowledgments

• Spotify for design inspiration
• React and TypeScript community
• Tailwind CSS team

Note: This component supports MP3 format only. Other audio formats require browser support.