A physical music controller for your Home Assistant smart home — built on a ~12€ ESP32 display, the infamous Cheap Yellow Display. Stick it on the wall, tap to play.
CYD Jukebox turns a Cheap Yellow Display into a always-on, wall-mounted music controller for any media_player entity in Home Assistant. No app, no phone, no voice commands — just a physical button on your wall.
It's cheap, open, and built entirely on ESPHome. Works with any HA media player out of the box, and pairs especially well with Music Assistant.
- Album art — displays the current song's cover art in a cozy pixel art style (because more pixels would not fit into the ram)
- Playback controls — only what you really need. play/pause, skip, stop
- Volume control — tap the volume button to reveal a slider
- Quick-play buttons — have the best at your fingertips: Two configurable shortcuts to instantly start a favourite playlist
- Playlist browser — a fine selection: Open a scrollable page with playlists defined by you
- State sync — surprisingly responsive: Reflects changes made from any other device in real time
- Auto-dim & sleep — designed to not annoy you. Dims after a short idle period; turns off completely when the player is inactive. A tap wakes everything back up
- Burn-in prevention — runs pixel training automatically during the night so your display stays healthy
The CYD is an ESP32-based 2.8" resistive touchscreen module — everything on a single PCB, no soldering required. It's popular in the ESPHome community for being a complete, capable package at a very low price. (The PCB is yellow. Hence the name.)
What to buy: look for the model number ESP32-2432S028 to make sure you get the right variant.
- Recommended listing: Tenstar Robot on AliExpress (~12€)
- No 3D printer? Some listings include a basic case for a little extra
The firmware is designed for portrait (vertical) orientation.
There's no official CYD Jukebox case yet — a custom retro-styled one is in the works. In the meantime, this case from Printables works great: ESP32-2432S028 USB-C Module Case
For mounting, a wall mount is recommended. Double-sided tape works fine. The community is welcome to share their own solutions.
- Home Assistant with a configured
media_playerentity - ESPHome — either the ESPHome Device Builder add-on (recommended) or the CLI
- AppDaemon HA add-on — for album art generation
cyd-jukebox/
├── esphome/
│ ├── cyd-jukebox.yaml # Main ESPHome config — start here
│ ├── cyd-playlists-page.yaml # Playlist browser UI (included by main config)
│ ├── cyd-gradient-overlay.yaml # Gradient overlay widget (included by main config)
│ ├── config.yaml.example # Template for your personal config — copy to config.yaml
│ ├── secrets.yaml.example # Template for your secrets file
│ └── fonts/
│ ├── MemoryIcons-Regular.otf # Pixel icon font (Apache 2.0)
│ └── LICENSE
└── appdeamon/
├── cyd-jukebox-album-art-generator.py # AppDaemon app — fetches & processes album art
└── apps.py # AppDaemon config template
Full step-by-step guide coming soon.
Short version:
- Copy
esphome/config.yaml.example→esphome/config.yamland fill in yourmedia_playerentity and HA URL - Copy
esphome/secrets.yaml.example→esphome/secrets.yamland fill in your credentials and secrets - Flash
esphome/cyd-jukebox.yamlto your CYD via ESPHome - Add the device in Home Assistant and allow it to perform actions
- Set up the AppDaemon app for album art (see
appdeamon/)
Things actively being worked on or planned:
- Media player switching — select a different speaker from the device itself, with optional queue transfer
- Better pixel/retro aesthetics — sharper icons, more retro UI elements
- Custom case design — a purpose-built retro case to be published on Printables
- Landscape orientation support
- Dynamic media browsing — replace the static playlist page with live browsing
- Loading UI While Connecting to Wifi
PRs, issues, suggestions, and case designs are all welcome. If you build one, show it off.
CYD Jukebox is MIT licensed — see LICENSE.
Uses MemoryIcons by Pictogrammers, licensed under Apache License 2.0.