> ## 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.

# Introduction

> Control your Spotify playback with a custom ESP32-powered macroboard featuring RGB lighting, OLED display, and 7 dedicated macro keys

## 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.

<img src="https://i.imgur.com/VzZgObq.jpg" alt="Spotify MacroBoard" className="rounded-lg" />

## Key features

<CardGroup cols={2}>
  <Card title="7 macro keys" icon="keyboard">
    Dedicated physical buttons for shuffle, volume control, loop, back, play/pause, and skip functions
  </Card>

  <Card title="OLED display" icon="display">
    128x64 SSD1306 display shows track title, artist name, playback progress, WiFi signal strength, and volume level
  </Card>

  <Card title="RGB LED sync" icon="lightbulb">
    20 WS2812B RGB LEDs that smoothly fade to match album artwork colors with real-time color extraction
  </Card>

  <Card title="WiFi connectivity" icon="wifi">
    ESP32-powered wireless communication with secure HTTPS requests to a personal server backend
  </Card>

  <Card title="Custom PCB" icon="microchip">
    Complete PCB design files and Gerber files included for professional manufacturing
  </Card>

  <Card title="Real-time updates" icon="clock">
    Live playback progress visualization with automatic track changes and status updates every 5 seconds
  </Card>
</CardGroup>

## 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.

```cpp theme={null}
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

<Note>
  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.
</Note>

## 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

<Tip>
  Ready to get started? Check out the [quickstart guide](/quickstart) to build your own Spotify MacroBoard.
</Tip>

## 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

<CardGroup cols={2}>
  <Card title="Quick start" icon="rocket" href="/quickstart">
    Get your macroboard up and running in minutes
  </Card>

  <Card title="Hardware components" icon="microchip" href="/hardware/components">
    View the complete list of required components
  </Card>

  <Card title="PCB assembly" icon="screwdriver-wrench" href="/hardware/assembly">
    Learn how to assemble the PCB and components
  </Card>

  <Card title="API server setup" icon="server" href="/api/server-setup">
    Configure your personal Spotify API server
  </Card>
</CardGroup>