A tiny ambient sidecar for your Mac, because apparently the menu bar needed hardware.
AuxDeck turns an ESP32 and a 128Ă—160 SPI display into a small, glanceable Mac companion. The working reference widget shows the current Spotify track with artwork, metadata, playback state, progress, and a live audio-level waveform. The Mac prepares assets; the ESP32 validates complete frames and renders them.
The setup: “You could just look at the Spotify window.”
The engineer: “Counterpoint: tiny dedicated screen.”
Mac doing expensive desktop things ──TG2──> ESP32 doing tiny-screen things
Wi-Fi first, encrypted BLE fallback, USB when the cable wins
Click the photo for a 10-second hardware demo.
The media shows the working breadboard prototype displaying live playback. It is evidence, not enclosure glamour photography. We are still in the “wires have opinions” era.
| Capability | Status |
|---|---|
| Spotify artwork, title, artist, progress, and play/pause state | Working |
| Spotify-only output-level waveform; no audio recording | Working on macOS |
| Same-LAN Wi-Fi data path | Primary transport |
| Encrypted, bonded Bluetooth Low Energy | Setup and fallback |
| USB serial | Diagnostics and explicit wired mode |
| Torn-art prevention with bounded frames, CRC, and acknowledgement | Working |
| Standalone playback, Spotify OAuth, buttons, or multiple widgets | Not implemented |
| Firmware updates over Wi-Fi | Not implemented; flashing is required |
AuxDeck reads the locally installed Spotify app through macOS automation. It does not control playback, store audio, or pretend to be a standalone Spotify client. “Spotify” identifies compatibility only; this project is not affiliated with or endorsed by Spotify.
flowchart LR
S[Spotify for macOS] --> H[Python host bridge]
A[Core Audio level helper] --> H
H -->|Wi-Fi TCP| P[TG2 parser]
H -->|encrypted BLE| P
H -->|USB serial| P
P --> R[ESP32 renderer]
R --> D[ST7735 128Ă—160 TFT]
Artwork is committed to the screen only after the complete frame validates. One transport owns the parser at a time, which prevents interleaved bytes from producing the half-drawn artwork that inspired the project’s transport fixes. See Architecture and TG2 protocol.
You need macOS, Spotify for macOS, a classic ESP32 development board, an ST7735-compatible 128Ă—160 display, Python 3, Xcode command-line tools, and Arduino CLI. Start with Getting started, then use:
python3 -m venv .venv
.venv/bin/python -m pip install --requirement requirements.txt
arduino-cli compile --clean \
--fqbn esp32:esp32:esp32:UploadSpeed=115200 \
--warnings all \
--build-property 'compiler.cpp.extra_flags=-DAUXDECK_WIFI -DAUXDECK_BLUETOOTH' \
--build-path firmware/aux-deck/build firmware/aux-deck
AUXDECK_PORT=/dev/cu.usbserial-your-device
arduino-cli upload \
--fqbn esp32:esp32:esp32:UploadSpeed=115200 \
--port "$AUXDECK_PORT" \
--input-dir firmware/aux-deck/build firmware/aux-deckInitial setup and firmware changes require USB flashing. Once running, track data travels over Wi-Fi with Bluetooth fallback; that is data delivery, not OTA firmware updating.
firmware/aux-deck/ production firmware
firmware/display-bringup/ minimal wiring diagnostic
firmware/artwork-preview/ synthetic offline UI fixture
host/python/ bridge, provisioning, installers, diagnostics
host/macos/ native BLE relay and Spotify audio-level helper
tests/ host and native protocol/rendering tests
docs/ setup, design, hardware, protocol, and operations
- Getting started
- Hardware and wiring
- Configuration
- Architecture
- TG2 protocol
- Troubleshooting
- Contributing and security policy
MIT licensed. Build strange little objects responsibly.