A modern, local-first music player built with Next.js, React, and Tailwind CSS.
MusicPlayer is designed to turn a local music collection into a polished, cinematic listening experience — with automatic metadata extraction, album artwork, favorites, search, playback controls, and a full playback queue.
Your music stays on your machine. No cloud music library is required.
- 🎵 Automatic scanning of the local
public/songsfolder - 📝 Automatic audio metadata extraction
- 🎤 Title, artist, and album information
- 💿 Automatic duration detection
- 🖼️ Embedded album artwork support
- 🖼️ Local cover fallback support
- 🔎 Real-time library search
- 📂 Automatic playlist generation
▶️ Play / Pause- ⏮️ Previous track
- ⏭️ Next track
- ⏱️ Live progress tracking
- 🎯 Seek through tracks
- 🔀 Shuffle mode
- 🔁 Repeat modes
- 🎚️ Playback speed control
- 🔊 Volume control
- 🔇 Mute / Unmute
- ➕ Add songs to the queue
- ⏭️ Play a song next
- ⬆️ Move queued songs up
- ⬇️ Move queued songs down
- ❌ Remove songs from the queue
- 🗑️ Clear the entire queue
- 🎵 Queue playback automatically continues through queued songs
- ❤️ Favorite songs
- 💾 Persistent favorites
- 💾 Persistent volume settings
- 💾 Persistent playback speed
- 💾 Persistent repeat mode
- 💾 Persistent shuffle preference
- 🌙 Cinematic dark interface
- ✨ Framer Motion animations
- 🪟 Glassmorphism-inspired UI
- 📱 Responsive layout
- 🎛️ Component-based player architecture
- 🖼️ Animated album artwork
- 🎨 Modern Tailwind CSS styling
- Next.js 16
- React 19
- Tailwind CSS 4
- JavaScript
- Node.js
- Framer Motion — animations
- Lucide React — icons
- music-metadata — audio metadata extraction
MusicPlayer/
├── app/
│ ├── api/
│ │ └── songs/
│ │ ├── route.js
│ │ └── artwork/
│ ├── layout.tsx
│ └── page.tsx
│
├── components/
│ ├── hooks/
│ │ └── useAudio.js
│ │
│ └── Player/
│ ├── AlbumCover.jsx
│ ├── Controls.jsx
│ ├── KeyboardShortcutsHelp.jsx
│ ├── PlayerCard.jsx
│ ├── Playlist.jsx
│ ├── ProgressBar.jsx
│ ├── Queue.jsx
│ ├── SearchBar.jsx
│ └── VolumeSlider.jsx
│
├── public/
│ ├── covers/
│ │ └── default.jpg
│ │
│ └── songs/
│ └── your-music-files
│
├── next.config.ts
├── package.json
└── README.md
MusicPlayer uses a local-first architecture.
Place your music files inside:
public/
└── songs/
├── song.mp3
├── another-song.m4a
└── ...
The application automatically scans the directory and creates the music library.
You don't need to manually create a playlist JSON file.
.mp3.m4a.wav.flac.ogg.opus
MusicPlayer can automatically extract:
- Title
- Artist
- Album
- Year
- Duration
- Embedded album artwork
If a file doesn't contain metadata, MusicPlayer falls back to information derived from the filename.
MusicPlayer uses a fallback system for album artwork.
It first checks whether the audio file contains embedded artwork.
If embedded artwork isn't available, it looks for a matching image inside:
public/
└── covers/
For example:
public/
├── songs/
│ └── song.mp3
│
└── covers/
└── song.jpg
Supported cover formats include:
.jpg.jpeg.png.webp.avif
If no artwork is available, the default cover is used:
/covers/default.jpg
git clone https://github.com/Ava-91/MusicPlayer.git
cd MusicPlayernpm installCreate the music directory if it doesn't already exist:
public/
└── songs/
Then place your local music files inside it.
Music files in
public/songsare intentionally excluded from Git. Add your own music files after cloning the repository.
npm run devVisit:
http://localhost:3000
Run the development server:
npm run devRun ESLint:
npm run lintRun TypeScript checking:
npm run type-checkCreate a production build:
npm run buildCheck installed package vulnerabilities:
npm auditMusicPlayer is designed around keeping your music local.
Your audio files are read from:
public/songs/
The application doesn't require a cloud music storage service or an online music library.
This also means the repository does not contain personal music files.
The .gitignore excludes:
/public/songs/
so local music files aren't accidentally committed to Git.
- Local music library
- Automatic music scanning
- Metadata extraction
- Embedded album artwork
- Local cover fallback
- Automatic duration detection
- Play / Pause
- Previous / Next
- Progress bar
- Seeking
- Volume control
- Mute / Unmute
- Playback speed
- Shuffle
- Repeat
- Search
- Favorites
- Persistent player settings
- Playback queue
- Add to queue
- Play next
- Queue reordering
- Queue removal
- Queue clearing
- Responsive interface
- Animated UI
Possible future improvements include:
- Improved keyboard shortcut system
- Lyrics support
- Audio visualizer
- Custom playlists
- Better library organization
- Album / artist browsing
- More advanced playback controls
- Improved mobile experience
- Electron desktop version
The roadmap may change as the project evolves.
I wanted to build a real music player instead of another tutorial project.
MusicPlayer has been a way for me to explore how real applications handle:
- Browser audio APIs
- Local media files
- Audio metadata
- Album artwork
- React state management
- Custom hooks
- Component architecture
- Persistent client-side settings
- Playback queues
- Responsive UI design
- Animations
- Next.js API routes
The goal isn't just to make the player work — it's to make it feel like an actual application.
Built by Ava ✨
Turning bugs into features and CSS suffering into pretty interfaces.
This project is intended for personal and educational use.
Music files are not included in the repository. Make sure you have the necessary rights to any music you add to your local library.