ZTM Music Player

A modern, Spotify-style local music player built with React, TypeScript, and Vite. Upload your MP3 files, organize them into playlists, and enjoy a beautiful music experience with offline-first functionality.

✨ Features

🎵 Core Music Features

• MP3 Upload & Parsing: Drag-and-drop or click to upload MP3 files
• ID3 Metadata Extraction: Automatically extracts title, artist, album, artwork, duration, year, and genre
• Album Artwork: Displays embedded album art or generates beautiful placeholder SVGs
• Audio Playback: Native HTML5 audio with Media Session API integration
• Queue Management: Add tracks to queue, reorder with drag-and-drop, remove tracks
• Playlist Support: Create, edit, delete, and organize playlists
• Play Modes: Shuffle, repeat (off/one/all), and normal playback

🎨 Modern UI/UX

• Dark Theme: Beautiful Spotify-inspired dark interface
• Responsive Design: Works perfectly on desktop, tablet, and mobile
• Progressive Web App (PWA): Installable with offline functionality
• Audio Visualizers: Multiple visualizer options (bars, radial, soft wavefield)
• Smooth Animations: Polished interactions and transitions
• Touch-Friendly: Optimized for mobile with touch gestures

💾 Offline-First Architecture

• IndexedDB Storage: All data stored locally in the browser
• Service Worker: Caches app shell and assets for offline use
• Export/Import: Backup and restore your music library
• No Server Required: Runs entirely in the browser

🔧 Advanced Features

• Media Session API: Lock screen controls, hardware media keys
• Content Deduplication: SHA-256 hashing prevents duplicate uploads
• Drag & Drop: Reorder queue and playlist items
• Search & Filter: Find tracks quickly across your library
• Real-time Updates: Live sync between components and database

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn

Installation

# Clone the repository
git clone <repository-url>
cd ztm-music-player

# Install dependencies
npm install

# Start development server
npm run dev

# Open http://localhost:5173 in your browser

Building for Production

# Build for production
npm run build

# Preview production build
npm run preview

📁 Project Structure

ztm-music-player/
├── public/
│   ├── icons/           # PWA icons (192x192, 512x512)
│   ├── manifest.webmanifest
│   └── sw.js           # Service worker
├── src/
│   ├── components/     # React components
│   │   ├── Artwork.tsx
│   │   ├── PlayerBar.tsx
│   │   ├── PlaylistCard.tsx
│   │   ├── QueueDrawer.tsx
│   │   ├── SearchBar.tsx
│   │   ├── SongList.tsx
│   │   ├── TopBar.tsx
│   │   ├── UploadDropzone.tsx
│   │   └── Visualizer.tsx
│   ├── hooks/          # Custom React hooks
│   │   ├── useIndexedDb.ts
│   │   └── usePlayer.tsx
│   ├── lib/            # Utility libraries
│   │   ├── audio.ts
│   │   └── id3.ts
│   ├── pages/          # Route components
│   │   ├── NowPlaying.tsx
│   │   ├── PlaylistDetail.tsx
│   │   ├── Playlists.tsx
│   │   ├── Songs.tsx
│   │   └── Upload.tsx
│   ├── db/             # Database layer
│   │   └── indexedDb.ts
│   ├── styles/         # Styling
│   │   └── tailwind.css
│   ├── types.ts        # TypeScript definitions
│   ├── App.tsx         # Main app component
│   └── main.tsx        # App entry point
├── package.json
├── tailwind.config.ts
├── tsconfig.json
└── vite.config.ts

🛠️ Tech Stack

Frontend

• React 18.3.1 - UI library with hooks and concurrent features
• TypeScript 5.2.2 - Type-safe JavaScript
• Vite 5.3.4 - Fast build tool and dev server
• Tailwind CSS 3.4.6 - Utility-first CSS framework
• React Router 6.25.1 - Client-side routing

Data & Storage

• IndexedDB - Browser database for offline storage
• idb - Promise-based IndexedDB wrapper
• music-metadata-browser - ID3 tag parsing for MP3 files

PWA & Performance

• Service Worker - Offline functionality and caching
• Web App Manifest - PWA installation support
• Font Awesome 6 - Icon library
• Web Audio API - Audio visualization

🎵 How to Use

1. Upload Music

• Go to the Upload page
• Drag and drop MP3 files or click to select
• Files are automatically parsed for metadata and stored

2. Browse Your Library

• Songs page shows all uploaded tracks
• Search and filter your music library
• Click any song to play it

3. Create Playlists

• Go to Playlists page
• Click "New Playlist" to create one
• Add tracks from your library to playlists
• Reorder tracks with drag-and-drop

4. Play Music

• Use the mini player at the bottom
• Open the queue drawer to see upcoming tracks
• Visit Now Playing for full-screen experience with visualizers

5. Manage Your Library

• Export your library as JSON for backup
• Import libraries from other devices
• Delete tracks and they're automatically removed from playlists

🔧 Configuration

Environment Variables

No environment variables required - the app runs entirely client-side.

PWA Configuration

The app is configured as a PWA with:

• Manifest: public/manifest.webmanifest
• Service Worker: public/sw.js
• Icons: public/icons/ (192x192 and 512x512 PNG files)

Customization

• Theme: Modify CSS variables in src/styles/tailwind.css
• Visualizers: Add new visualizer variants in src/components/Visualizer.tsx
• Database Schema: Update types in src/types.ts

🚀 Deployment

Vercel (Recommended)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Or connect your GitHub repo to Vercel for automatic deployments

Other Platforms

The app can be deployed to any static hosting service:

• Netlify: Drag and drop the dist folder
• GitHub Pages: Use GitHub Actions
• AWS S3: Upload the dist folder
• Firebase Hosting: Use Firebase CLI

Vercel Configuration

The project includes vercel.json for proper SPA routing:

{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

🧪 Development

Available Scripts

npm run dev      # Start development server
npm run build    # Build for production
npm run preview  # Preview production build
npm run lint     # Run ESLint

Code Style

• ESLint: Configured with React and TypeScript rules
• Prettier: Code formatting with Tailwind plugin
• TypeScript: Strict mode enabled

Database Schema

The app uses IndexedDB with the following stores:

• tracks: Music track metadata
• blobs: Audio files and artwork (stored as Blobs)
• playlists: Playlist definitions
• app: Application settings and queue state

🐛 Troubleshooting

Common Issues

Audio not playing:

• Check browser console for errors
• Ensure MP3 files are valid and not corrupted
• Try refreshing the page

PWA not installing:

• Ensure you're using HTTPS (or localhost)
• Check that manifest.webmanifest is accessible
• Verify service worker is registered

Tracks not showing after upload:

• Check browser console for IndexedDB errors
• Try refreshing the page
• Clear browser storage if needed

Visualizer not working:

• Ensure Web Audio API is supported
• Check that audio is actually playing
• Try switching between visualizer modes

Browser Support

• Chrome/Edge: Full support
• Firefox: Full support
• Safari: Full support (iOS 14.5+)
• Mobile: Full support on modern browsers

🤝 Contributing

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

Development Guidelines

• Follow TypeScript strict mode
• Use functional components with hooks
• Maintain responsive design
• Test on multiple browsers
• Update documentation for new features

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Zero To Mastery - For the inspiration and learning platform
• React Team - For the amazing framework
• Tailwind CSS - For the utility-first CSS approach
• Vite Team - For the lightning-fast build tool
• music-metadata-browser - For ID3 tag parsing capabilities

📞 Support

If you encounter any issues or have questions:

1. Check the Troubleshooting section
2. Search existing Issues
3. Create a new issue with detailed information
4. Join the community discussions

---

Made with ❤️ for music lovers everywhere