ESP32 MP3 Player + Song Sync

A pocket-sized MP3 player built on an ESP32 + VS1053 hardware decoder, paired with Song Sync — a local desktop app that syncs your Spotify playlists to the player using music files you already own.

How it works

 Spotify Web API          Song Sync (your PC)                   ESP32 Player
 ───────────────          ─────────────────                     ────────────
 metadata only  ───────►  fetch playlists/liked songs
                          scan your local music library
                          fuzzy-match (artist+title, ISRC, ±3s)
                          ├─ matched ──► transcode → MP3 ──►   POST /upload (WiFi)
                          └─ unmatched ─► wishlist.csv

1. Spotify gives metadata only — playlist contents, track names, artists, albums, durations, ISRCs. No audio is ever downloaded from Spotify.
2. Song Sync matches that metadata against your own local music library (files you legally own).
3. Matched files are uploaded to the player over WiFi — the ESP32 creates its own hotspot.
4. Unmatched tracks are exported as a wishlist.csv with legal-store search links.

Project structure

├── mp3_player/              # ESP32 Arduino firmware
│   ├── config.h             #   Pin map + tunables
│   └── mp3_player.ino       #   Main firmware (player + WiFi upload server)
├── songsync/                # Desktop sync app (Python / FastAPI)
│   ├── songsync/            #   Python package
│   │   ├── app.py           #     FastAPI backend + all API routes
│   │   ├── spotify_client.py#     Spotify PKCE OAuth + metadata fetching
│   │   ├── library.py       #     Local music folder scanner (mutagen)
│   │   ├── matcher.py       #     Fuzzy matching engine (rapidfuzz)
│   │   ├── device.py        #     HTTP client for ESP32 upload endpoints
│   │   ├── transcode.py     #     Optional ffmpeg transcoding to MP3
│   │   └── config.py        #     Paths and defaults
│   ├── static/index.html    #   Single-page browser UI
│   ├── requirements.txt
│   ├── run.bat              #   One-click Windows launcher
│   └── README.md            #   Detailed Song Sync setup guide
├── DESIGN.md                # Hardware design & build guide
└── INTEGRATION.md           # HTTP contract between Song Sync ⇄ ESP32

Quick start

Hardware

See DESIGN.md for the full bill of materials, wiring diagram, and build guide. In short:

• ESP32 (WROOM or WROVER) dev board
• VS1053 hardware audio decoder (ideally the combo board with built-in microSD slot)
• microSD card formatted FAT32 — the only format the ESP32 SD library mounts (reformat exFAT cards; see DESIGN.md §6)
• SSD1306 128×64 OLED (I2C) for the display
• 3–4 push buttons for transport controls
• 3.5 mm headphone jack or small speaker

Firmware

1. Install the ESP32 board package in Arduino IDE.
2. Install libraries: ESP_VS1053_Library (baldram), Adafruit SSD1306, Adafruit GFX.
3. Open mp3_player/mp3_player.ino, select your board + COM port, and upload.
4. Put .mp3 files on the microSD card in a /music folder.

Song Sync (desktop app)

1. Python 3.11+ required. Optional: ffmpeg on PATH for transcoding.
2. Register a free Spotify app at developer.spotify.com/dashboard:
   • Redirect URI: http://127.0.0.1:8765/callback
   • Copy the Client ID (no secret needed — PKCE)
3. Run:

   cd songsync
   run.bat
   

   Or manually: pip install -r requirements.txt && python -m songsync
4. Open http://127.0.0.1:8765, paste your Client ID, connect Spotify, pick playlists, scan your library, match, and upload.

See songsync/README.md for detailed instructions.

Player controls

Button	Short press	Long press (600 ms+)
PREV	Previous track	Volume down
PLAY	Play / Pause	Enter Upload Mode (2 s hold)
NEXT	Next track	Volume up
MODE	Enter Upload Mode	—

Upload Mode: The player creates a WiFi hotspot (ESP32-MP3 / musicbox123). Connect your PC/phone and visit http://192.168.4.1 to drag-and-drop files, or use Song Sync for intelligent playlist-based syncing.

Legal boundaries

• No audio is downloaded from Spotify — only metadata (titles, artists, albums, durations).
• Audio files come only from the user's own local library.
• Unmatched songs are exported as a plain-text wishlist for the user to acquire through legal channels.
• No cloud services beyond the user's own Spotify API app registration.

Documentation

• DESIGN.md — Hardware design, wiring, firmware architecture
• INTEGRATION.md — HTTP contracts between components
• songsync/README.md — Song Sync setup and usage