A nostalgic and functional desktop MP3 player built with Electron + Vite + React, featuring a classic iPod-inspired interface, clickable wheel controls, and a complete music library system.
iPod MP3 Player is a cross-platform desktop application that recreates the iconic iPod experience with modern technology. It combines the beloved iPod navigation system with powerful music playback features, automatic metadata extraction, and customizable themes.
Classic iPod Navigation: Authentic click wheel interface with center button, menu, play/pause, and skip controls
Music Library Management: Browse by Artists, Albums, or Songs with automatic organization
Automatic Metadata Extraction: Reads ID3 tags from MP3 files including title, artist, album, year, genre, and album art
Now Playing Screen: Beautiful display with album artwork, progress bar, and track information
Shuffle Mode: Random playback with smart track management to avoid repeats
Volume Control: Adjustable volume with visual feedback in settings
Theme Support: Switch between default pink and blue themes with matching button icons
Clock Screen: Real-time clock display in the Extras menu
Progress Tracking: Real-time playback progress with formatted time display
Multiple Navigation Screens: Main Menu, Music Menu, Artists, Albums, Songs, Now Playing, Settings, Themes, Extras, and Clock
Main Menu: Access Music, Extras, Settings, Shuffle toggle, or Now Playing
Music Menu: Browse by Artists, Albums, or All Songs
Library Navigation: Select an artist or album to view filtered song lists
Song Selection: Choose a song to start playback and view Now Playing screen
Now Playing: View album art, track info, progress bar, and control playback
Settings: Adjust volume and toggle shuffle mode
Themes: Switch between pink and blue color schemes
Extras: Access Clock screen and Theme selector
Frontend: React 19 with modern hooks and context API
Audio Engine: Howler.js for cross-platform audio playback
Metadata: music-metadata library for ID3 tag extraction
Framework: Electron with electron-vite for hot reloading
Build Tool: Vite for fast development and optimized builds
Styling: CSS Modules for component-scoped styles
- Node.js 20.19.0 or higher
- npm package manager
git clone https://github.com/caglaozbb/mp3-player.git
cd mp3-player
npm installnpm run devRun with hot reloading and development tools enabled.
npm startPreview the production build locally.
Development:
npm run devRun with hot reloading
Preview Production Build:
npm startBuild Production:
npm run buildPlatform-specific Builds:
npm run build:win # Windows
npm run build:mac # macOS
npm run build:linux # LinuxCenter Button: Select/confirm navigation or play selected song
Menu Button: Go back to previous screen
Play/Pause Button: Toggle playback of current song
Left/Previous Button:
- Navigate up in lists
- Previous track when in Now Playing
- Decrease volume in Settings
Right/Next Button:
- Navigate down in lists
- Next track when in Now Playing
- Increase volume in Settings
Place your MP3 files in src/renderer/src/assets/songs/
The app automatically:
- Extracts metadata (title, artist, album, year, genre)
- Reads embedded album artwork
- Organizes songs by artist and album
- Displays all information in the library
To add songs programmatically, edit MusicContext.jsx:
const songFiles = [
{ file: 'your-song.mp3' },
// Add more songs here
]Developed and tested on macOS. Cross-platform compatibility expected thanks to Electron.
mp3-player/
├── src/
│ ├── main/ # Electron main process
│ ├── preload/ # Preload scripts
│ └── renderer/ # React application
│ └── src/
│ ├── assets/ # Images, songs, styles
│ ├── components/ # Reusable components
│ ├── context/ # React Context providers
│ ├── screens/ # Screen components
│ └── styles/ # CSS Modules
├── build/ # Build assets
└── out/ # Compiled output
- Create new screen components in
screens/folder - Add screen case to
ScreenManager.jsx - Use
NavigationContextfor navigation - Use
MusicContextfor music operations
Built with ❤️ using Electron, React, Howler.js, and music-metadata