Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/benz206/SpotifyMacroBoard/llms.txt

Use this file to discover all available pages before exploring further.

​
Welcome to Spotify MacroBoard

Spotify MacroBoard is an ESP32-based hardware controller that gives you physical, tactile control over your Spotify playback. With 7 customizable macro keys, a vibrant OLED display, and dynamic RGB LED lighting that syncs with your music, this project transforms how you interact with your favorite tracks. Spotify MacroBoard

​
Key features

7 macro keys

Dedicated physical buttons for shuffle, volume control, loop, back, play/pause, and skip functions

OLED display

128x64 SSD1306 display shows track title, artist name, playback progress, WiFi signal strength, and volume level

RGB LED sync

20 WS2812B RGB LEDs that smoothly fade to match album artwork colors with real-time color extraction

WiFi connectivity

ESP32-powered wireless communication with secure HTTPS requests to a personal server backend

Custom PCB

Complete PCB design files and Gerber files included for professional manufacturing

Real-time updates

Live playback progress visualization with automatic track changes and status updates every 5 seconds

​
How it works

The Spotify MacroBoard uses an ESP32 microcontroller to communicate with your personal server via secure HTTPS requests. When you press a button, the ESP32 sends an action request to the server, which then communicates with the Spotify API on your behalf. 
void updateState(char action, int subAction = 0) {
    String actionString = "";
    if (action == 'p') {
        actionString = "playPause";
    } else if (action == 'b') {
        actionString = "back";
    } else if (action == 's') {
        actionString = "skip";
    }
    // Send HTTPS request to server
    wifiClient.print("GET /api/manageState/" + PASSWORD + "/" + actionString +
                     " HTTP/1.1\r\n" + "Host: benzhou.tech\r\n" +
                     "Connection: Keep-Alive\r\n\r\n");
}
The display continuously updates to show current track information, while the RGB LEDs smoothly transition to colors extracted from the album artwork.

​
Hardware components

  • ESP32 DevKit V1 - Main microcontroller with WiFi capability
  • SSD1306 OLED Display - 128x64 I2C display for track information
  • WS2812B RGB LED Strip - 20 individually addressable LEDs
  • 7 Mechanical Switches - Cherry MX compatible switches
  • Custom PCB - Designed specifically for this project
  • 3D Printed Case - Custom enclosure with keycaps

​
Architecture overview

The system consists of three main components:
  1. ESP32 Client (src.ino:1) - Handles button inputs, display updates, and LED control
  2. Personal Server - Intermediary that communicates with Spotify’s API
  3. Spotify API - Official Spotify Web API for playback control
This architecture uses a personal server as a proxy to speed up API requests and handle authentication tokens securely. The ESP32 maintains a persistent HTTPS connection to reduce latency.

​
What’s included

This project provides everything you need to build your own Spotify MacroBoard:
  • Complete Arduino source code (src.ino)
  • Custom PCB design files and schematics
  • Gerber files for PCB manufacturing
  • Sample credentials configuration template
  • Hardware component list and pin definitions
Ready to get started? Check out the quickstart guide to build your own Spotify MacroBoard.

​
Technical specifications

  • Microcontroller: ESP32 (240 MHz, dual-core)
  • Memory Usage: 886,189 bytes (67%) program storage, 45,808 bytes (13%) dynamic memory
  • Display: 128x64 OLED (I2C, 0x3C address)
  • LEDs: 20x WS2812B RGB LEDs at 230 brightness
  • Buttons: 7 GPIO pins with internal pull-up resistors
  • WiFi: 2.4 GHz only (ESP32 limitation)
  • Power: 5V at 500mA max for LED strip
  • Update Rate: 5 second track updates, 1 second progress updates

​
Next steps

Quick start

Get your macroboard up and running in minutes

Hardware components

View the complete list of required components

PCB assembly

Learn how to assemble the PCB and components

API server setup

Configure your personal Spotify API server

Build docs developers (and LLMs) love

Get started for freeTalk to us