A modern music discovery app built with React and TypeScript.
Browse tracks, albums, and artists with intelligent search and audio playback.
- Smart Search: Advanced search algorithm with genre-based filtering, year-based queries, and popularity scoring
- Command Palette: Press
Cmd+K(Mac) orCtrl+K(Windows) for instant search across tracks, albums, and artists - Latest Hits: Curated collection of 2024-2025 chart-topping tracks from Spotify's top charts
- Popular Tracks: Classic hits and timeless favorites with verified metadata
- Mini Player: Full-featured audio player with play/pause, seek, volume control, and shuffle/repeat modes
- Preview Playback: Real-time audio previews from Spotify's CDN when available
- Visual Feedback: Audio visualizer and progress indicators for enhanced user experience
- Responsive Controls: Touch-friendly controls optimized for mobile and desktop
- Modern Design: Clean, responsive interface with dark/light theme support
- Grid & List Views: Toggle between detailed grid view and compact list view
- Smooth Animations: Framer Motion powered transitions and micro-interactions
- Mobile Optimized: Fully responsive design that works on all screen sizes
- Multi-term Search: Intelligent search across track names, artists, albums, and genres
- Genre Aliases: Smart genre matching (e.g., "hip hop" matches "rap", "latin trap")
- Year-based Queries: Search by release year (e.g., "2024", "2023")
- Popularity Filtering: Results ranked by Spotify popularity scores
- Lazy Loading: Code splitting and lazy-loaded components for faster initial load
- Caching: Intelligent caching with RTK Query for optimal performance
- Offline Support: Graceful fallback to cached content when offline
- Error Handling: Comprehensive error boundaries and user-friendly error messages
Podbeat runs in two modes depending on your setup:
Without API credentials:
- Curated collection of 2024-2025 chart toppers with verified Spotify metadata
- Works immediately after
git cloneandnpm install - Real album artwork and track metadata from Spotify CDN
- Features artists like Billie Eilish, Harry Styles, Morgan Wallen, Taylor Swift, and more
- Enhanced search functionality with mock data
Benefits:
- Perfect for trying out the app quickly
- No API setup required
- Images load from Spotify CDN
- Shows off the full UI and search capabilities
If you have Spotify API credentials:
- Real-time access to Spotify's music catalog
- Search across millions of tracks, albums, and artists
- Latest trending songs and new releases
- All features available with live data
Requires:
- Spotify API credentials in
.envfile - Backend server running for CORS handling
Podbeat automatically detects which mode to use and provides seamless fallback.
You need Node.js 18+ and npm.
# Clone and install
git clone https://github.com/karadHub/podbeat.git
cd podbeat
npm install
# Start the app
npm run devOpen http://localhost:5173 - Podbeat works immediately with demo data and full functionality.
- Search: Use the search bar or press
Cmd+K/Ctrl+Kto open the command palette - Browse: Explore the Latest Hits section with curated 2024-2025 tracks
- Play: Click any track to start the mini player with audio previews
- Navigate: Use the sidebar and header navigation for seamless browsing
- Create a Spotify Developer Account and create a new app
- Get your Client ID and Client Secret from the app dashboard
- Create a
.envfile in the root directory:touch .env
- Add your credentials to
.env:VITE_SPOTIFY_CLIENT_ID=your_client_id_here VITE_SPOTIFY_CLIENT_SECRET=your_client_secret_here VITE_USE_BACKEND_PROXY=true
- Start with the backend server:
npm run dev:full
This will start both the backend server (port 3001) and frontend (port 5173) simultaneously.
src/
├── components/ # Reusable UI components
│ └── ui/ # Core UI components (CommandPalette, MiniPlayer, etc.)
├── pages/ # Route-based page components
│ ├── Home/ # Landing page with hero and sections
│ ├── Catalog/ # Browse tracks, albums, artists
│ └── Detail/ # Individual track/album/artist pages
├── services/ # API services and data management
│ ├── MusicAPI.ts # Unified music data API
│ ├── SpotifyAPI.ts # Spotify Web API integration
│ └── MCPAudioService.ts # Audio enhancement service
├── hooks/ # Custom React hooks
│ ├── useAudioPlayer.ts # Audio playback management
│ └── useCommandPalette.ts # Search and navigation
├── data/ # Mock data and constants
│ └── mockMusicData.ts # Curated 2024-2025 track data
├── common/ # Shared components and utilities
└── utils/ # Helper functions and configuration
- CommandPalette: Global search with keyboard shortcuts (
Cmd+K/Ctrl+K) - MiniPlayer: Full-featured audio player with controls
- TrackCard/AlbumCard: Responsive music item displays
- Hero: Dynamic landing section with featured tracks
- Search: Advanced search with filtering and sorting
# Run tests
npm test
# Run with coverage
npm run test:coveragenpm run build
npm run preview- React 18 with TypeScript for type-safe development
- Vite for fast development and optimized builds
- Tailwind CSS for utility-first styling
- Framer Motion for smooth animations and transitions
- React Router v6 for client-side routing
- Redux Toolkit with RTK Query for efficient state management
- Intelligent Caching with content-aware cache durations
- Offline Support with graceful fallback to cached content
- HTML5 Audio API for preview playback
- MCP Audio Service for enhanced track metadata
- Spotify CDN for high-quality album artwork and previews
- Node.js with Express.js for CORS proxy server
- Spotify Web API integration with retry logic and error handling
- Client Credentials Flow for secure API authentication
- Vitest for unit testing with React Testing Library
- Playwright for end-to-end testing
- ESLint with TypeScript support for code quality
- MSW (Mock Service Worker) for API mocking in tests
- Radix UI for accessible component primitives
- React Aria Components for advanced accessibility
- Lucide React for consistent iconography
- Swiper.js for touch-friendly carousels
CORS Errors with Spotify API
- Problem: API requests fail due to CORS restrictions
- Solution: Ensure the backend server is running (
npm run dev:fullornpm run server:dev) - Details: Spotify Web API cannot be called directly from browsers due to CORS policy
Missing Environment Variables
- Problem: Podbeat shows "No music data available" or API errors
- Solution: Check that
.envfile exists with valid Spotify credentials - Note: Podbeat works perfectly in demo mode without API credentials
Port Conflicts
- Frontend (Port 5173): Check if another Vite/dev server is running
- Backend (Port 3001): Check if another Express server is using the port
- Solution: Kill existing processes or modify port configuration
Audio Playback Issues
- Problem: Tracks don't play or show "No preview available"
- Solution: This is normal - not all tracks have preview URLs. Podbeat will show a simulation for tracks without previews
- Details: Preview availability depends on Spotify's licensing agreements
Build/TypeScript Errors
- Problem: TypeScript compilation errors during build
- Solution: Run
npm run buildto see specific error details - Common fix: Ensure all dependencies are installed (
npm install)
Search Not Working
- Problem: Command palette or search returns no results
- Solution: Try different search terms, check if you're in demo mode (which has limited but high-quality data)
- Details: Demo mode includes 20+ verified tracks from 2024-2025 charts
- Check the GitHub Issues for known problems
- Podbeat includes comprehensive error handling and user-friendly error messages
- Demo mode provides full functionality without requiring API setup
Built with ❤️ for music lovers everywhere
Discover your next favorite track with Podbeat