"Nostalgia — it's delicate, but potent."
A time machine for 90s kids.
Inspiration • Features • Quick Start • Spotify Setup • Troubleshooting
Nostalgia is a powerful emotion. It can transport you back in time, make you feel things you haven't felt in years, and remind you of who you once were.
I was watching Mad Men when I stumbled upon The Carousel scene — and it hit me. That's exactly what I wanted to build. A time machine for 90s kids.
This project is an ode to that era — dial-up modems, burned CDs, and carefully curated MP3 collections. Winamp wasn't just software. It was a ritual. The green LED glow illuminating your face at 2 AM. The spectrum analyzer dancing to your favorite songs. The skins you spent hours customizing instead of doing homework.
For those of us who grew up in that era, music wasn't just something you streamed — it was something you collected, organized, and cherished. Every track had a story. Every playlist was a time capsule.
This project exists because some of us still feel that twinge — that ache to go back. Not to relive the past, but to feel it again, just for a moment.
| Feature | Description |
|---|---|
| Classic Aesthetic | Pixel-perfect Winamp 2.x recreation with LED displays, spectrum analyzer, and metallic buttons |
| Album Art | See album artwork alongside the time display |
| Full Playback Control | Play, pause, next, previous, seek, volume, shuffle, repeat |
| Library Tabs | Browse your Playlists, Liked Songs, Recently Played, or Search |
| Visual Equalizer | Decorative 10-band EQ for that authentic look |
| Device Selector | Control Spotify on any of your connected devices |
| Mini Mode | Compact view showing just the player |
| Desktop App | Runs as a native macOS app via Electron |
- Node.js 18+
- Spotify Premium account (required for playback)
- Spotify Developer App (create one here)
# Clone the repository
git clone https://github.com/YOUR_USERNAME/winamp-spotify.git
cd winamp-spotify
# Install dependencies
npm install
# Create environment file
echo "NEXT_PUBLIC_SPOTIFY_CLIENT_ID=your_client_id_here" > .env.local
# Run in browser
npm run dev
# Or run as desktop app
npm run electron:devThen open http://127.0.0.1:3000 in your browser.
Step-by-step guide (click to expand)
- Go to the Spotify Developer Dashboard
- Click "Create App"
- Fill in the details:
| Field | Value |
|---|---|
| App name | Winamp Spotify |
| App description | Retro music player |
| Redirect URI | http://127.0.0.1:3000/callback |
| APIs used | ✓ Web API, ✓ Web Playback SDK |
- Click "Save"
- Go to Settings → copy your Client ID
Create a .env.local file in the project root:
NEXT_PUBLIC_SPOTIFY_CLIENT_ID=paste_your_client_id_herenpm run electron:devnpm run dev
# Open http://127.0.0.1:3000npm run electron:dev# Web build
npm run build && npm run start
# macOS DMG
npm run electron:buildThe app operates in two modes depending on your setup:
| Access URL | Mode | Description |
|---|---|---|
127.0.0.1 |
Spotify Connect | Controls playback on your other Spotify devices |
localhost |
Web Playback SDK | Plays directly in browser (requires localhost in redirect URIs) |
winamp-spotify/
├── src/
│ ├── app/
│ │ ├── page.tsx # Main page
│ │ ├── callback/ # OAuth callback
│ │ ├── layout.tsx # App layout
│ │ └── globals.css # Winamp styles
│ ├── components/
│ │ └── WinampPlayer.tsx # Player UI (700+ lines of nostalgia)
│ ├── hooks/
│ │ └── useSpotify.ts # Spotify state & SDK
│ └── lib/
│ └── spotify.ts # API functions
├── electron/
│ ├── main.js # Electron main process
│ └── preload.js # Preload script
└── package.json
INVALID_CLIENT: Invalid redirect URI
Ensure your Spotify Dashboard redirect URI exactly matches:
http://127.0.0.1:3000/callback
No trailing slash. Case-sensitive.
No code verifier found
This happens when you start auth on one origin (localhost) and finish on another (127.0.0.1).
Solution: Always use http://127.0.0.1:3000 consistently.
Failed to initialize player
The Web Playback SDK only works on localhost or HTTPS. When accessing via 127.0.0.1, the app automatically falls back to Spotify Connect mode—make sure you have Spotify open on another device.
Playback not working
- Verify you have Spotify Premium
- Have Spotify open on another device (for Connect mode)
- Try logging out and back in
- Check browser console for errors
| Layer | Technology |
|---|---|
| Framework | Next.js 16 |
| Styling | Tailwind CSS 4 |
| Desktop | Electron 39 |
| Font | JetBrains Mono |
| API | Spotify Web API |
| SDK | Spotify Web Playback SDK |
MIT
Original Winamp by Nullsoft • Spotify is a trademark of Spotify AB
For the 90s kids. For the memories. For the music.