🎧 Universal Music Finder Player

A modern, portfolio-ready music player that lets you search for any song, artist or album and play it legally — using official preview APIs, your own local files, and royalty-free audio. No piracy, no stream ripping, no DRM bypass.

Spotify / Apple Music–inspired UI, built from scratch with React, TypeScript, Tailwind and a clean provider-based architecture.

📸 Add a screenshot to docs/screenshot-search.png to show it off here.

---

✨ Features

🔎 Search

• Search by song title, artist, album or keyword
• Debounced input with loading (skeletons), empty, and error states
• Results show cover art, title, artist, album, duration and a source badge
• Per-provider failures are isolated — one source going down never breaks the search

🌐 Legal music sources (provider architecture)

• iTunes Search API — broad multi-storefront catalog search, official previews, and Apple/iTunes link lookup (no API key required)
• Royalty-free catalog — license-free tracks so the player always works offline
• Local files — play your own audio straight from your device (File API)
• Designed to plug in official Spotify / YouTube metadata + embeds when credentials are available
• If full playback isn't legal or no preview is available, the app shows "Preview" or "Open on platform"

▶️ Real player

• Play / pause, previous / next, seek bar with current & total time
• Volume control + mute
• Repeat (off / all / one) and shuffle
• Full queue system with "now playing" + "up next" and drag-and-drop reordering
• Currently-playing section with cover art and an animated equalizer
• Media Session support for OS/browser media controls and lock-screen metadata
• Fully responsive desktop ↔ mobile layout

📚 Playlists & library

• Create, rename and delete playlists
• Add / remove tracks via the track menu
• Liked songs and recently played in Your Library
• Everything persists to localStorage (playlists, favorites, last queue, volume, etc.)

💾 Local MP3 player

• Drag-and-drop or browse to upload audio files
• Reads ID3 title / artist / album / cover art, with filename fallback (Artist - Title.mp3)
• Reads duration from the browser audio metadata
• Local tracks are clearly separated from online previews and kept session-only

🎁 Extra polish

• Toast notifications
• Keyboard shortcuts: Space = play/pause · → / ← = seek · M = mute
• Skeleton loading cards, smooth hover/transition effects
• Generated gradient cover art when no artwork is available

---

🧱 Tech stack

Area	Choice
Framework	React 18 + TypeScript
Build tool	Vite 5
Styling	Tailwind CSS 3
State	Zustand (with persist middleware)
Audio	HTMLAudioElement (single shared engine)
Icons	lucide-react
Persistence	localStorage

---

📁 Project structure

src/
  components/      UI: PlayerBar, SearchBar, TrackCard, Sidebar, PlaylistView,
                   LocalFileUploader, Queue, Toaster, CoverArt, Slider, ...
  providers/       Provider architecture
    musicProvider.ts   provider interface + parallel aggregator
    itunesProvider.ts  iTunes Search API
    mockProvider.ts    royalty-free catalog
    localProvider.ts   local files (File API)
  store/           Zustand stores
    playerStore.ts     playback engine + queue
    playlistStore.ts   playlists, favorites, recent
    localStore.ts      session-only local tracks
    uiStore.ts         navigation + toasts
  types/           Track.ts, Playlist.ts
  utils/           formatTime, storage, cover (gradients), cn
  hooks/           useDebounce, useClickOutside, useKeyboardShortcuts
  App.tsx
  main.tsx

Data model

interface Track {
  id: string;
  title: string;
  artist: string;
  album: string;
  artworkUrl: string;
  previewUrl: string | null;      // streamable audio, null when embed-only
  source: 'itunes' | 'local' | 'free' | 'spotify' | 'youtube';
  duration: number;               // seconds
  type: 'preview' | 'local' | 'embed';
  externalUrl: string | null;     // official platform link
}

interface Playlist {
  id: string;
  name: string;
  tracks: Track[];
  createdAt: number;
  updatedAt: number;
}

---

🚀 Getting started

Requirements: Node.js 18+ (built and tested on Node 20/24).

# 1. Install dependencies
npm install

# 2. Start the dev server
npm run dev
# → open http://localhost:5173

# 3. Production build
npm run build

# 4. Preview the production build
npm run preview

There is no required configuration — iTunes search and the royalty-free catalog work out of the box. (Optional Spotify/YouTube integrations would read their keys from environment variables when implemented.)

---

⚖️ Legal note

This app does not download copyrighted music or bypass streaming restrictions. It only plays legal previews, local files provided by the user, or official embedded sources.

• ✅ Official iTunes 30-second previews
• ✅ Royalty-free / public-domain audio
• ✅ User-provided local files (never uploaded anywhere)
• ❌ No YouTube-to-MP3, stream ripping, scraping, or DRM circumvention

---

⌨️ Keyboard shortcuts

Key	Action
Space	Play / pause
→	Seek forward 5s
←	Seek backward 5s
M	Mute / unmute

(Shortcuts are ignored while typing in the search box.)

---

🖼️ Screenshots

Add your own screenshots to the docs/ folder:

• docs/screenshot-search.png — search results
• docs/screenshot-player.png — player + queue
• docs/screenshot-library.png — library / playlists

---

🔭 Future improvements

• Official Spotify Web Playback SDK and YouTube IFrame embeds (full-track playback where licensed)
• Lyrics panel and audio visualizer (Web Audio API)
• PWA / offline support
• Account sync for playlists across devices

---

Built with ♥ as a front-end portfolio project.