mp3-cyberdeck

KO | EN

gitlite — search

#self-hosted #golang #gpt #list #animation #ios #deep-learning #postgresql #go #kotlin

(★ 9)

No description available.

File Explorer

ZIP Download

- - CMakeLists.txt
  - library.json
  - library.properties
  - LICENSE
  - README.md
- esp_lcd_spd2010.c
- esp_lcd_spd2010.h
- main.cpp
- rainyhearts14.h
- Touch_SPD2010.cpp
- Touch_SPD2010.h
- ui_pause.h
- ui_play.h
.gitignore
FIXES.md
mp3-display-pause.png
mp3-display-play.png
pio.sh
platformio.ini
rainyhearts.ttf
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A pocket MP3 player on a **Waveshare ESP32-S3-Touch-LCD-1.46B** -- a 1.46" round
412x412 touchscreen. It plays MP3s from a microSD card through the onboard
speaker and shows a pixel-art "now playing" skin with the song title and artist,
a tap-to-toggle play/pause button, and swipe-to-change-track gestures. Runs off
USB or a LiPo battery.

![play skin](https://raw.githubusercontent.com/cupidbity/mp3-cyberdeck/main/mp3-display-play.png)

## Features

- MP3 playback from microSD (SD_MMC 1-bit) through the PCM5101 I2S DAC + speaker
- 412x412 round SPD2010 QSPI display with a custom pixel-art skin
- Title + artist shown separately, read from a `playlist.json` on the card
- Long titles/artists **marquee scroll** (start centered, single line)
- **Tap** the center button -> play/pause - **swipe** left/right -> next/previous
- **BOOT** button -> reload the SD card/playlist - **hold PWR ~2s** -> power off (battery)
- Battery powered with a soft-power latch; auto-dims the backlight on battery

## Hardware

| Part | Detail |
|------|--------|
| Board | Waveshare **ESP32-S3-Touch-LCD-1.46B** (ESP32-S3R8, 8 MB PSRAM, 16 MB flash) |
| Display | SPD2010, 412x412 round IPS, **QSPI** |
| Touch | SPD2010 capacitive, shared **I2C** bus (SCL 10 / SDA 11) |
| Audio | PCM5101 I2S DAC -> amp -> onboard speaker |
| Storage | microSD in the onboard slot, **FAT32** |
| Power | USB-C, or a 3.7 V LiPo on the MX1.25 header (built with a **320 mAh** cell) |

### Bill of materials

- **1x Waveshare ESP32-S3-Touch-LCD-1.46B** board
- **1x microSD card** (FAT32) for the music
- **1x 3.7 V LiPo** on the MX1.25 header -- optional, for battery use (built with a **320 mAh** cell)

That's the entire parts list. **No external components and no wiring.** The
display, touch panel, PCM5101 audio + speaker, battery charger, and the TCA9554
I/O expander are all **integrated on the board** -- the firmware drives them over
the board's internal buses. The "expander" the code refers to is that onboard
TCA9554 (controlled over the shared I2C bus for LCD reset / SD mode / touch
reset); you don't add or wire anything.

**Board docs / drivers:** <https://docs.waveshare.com/ESP32-S3-Touch-LCD-1.46>

---

## Reproduce from scratch

### 1. Toolchain

This board needs **Arduino-ESP32 core 3.1.1 / ESP-IDF 5.3**, delivered by the
[pioarduino](https://github.com/pioarduino/platform-espressif32) fork of the
PlatformIO espressif32 platform. That fork needs **Python >= 3.10**.

The load-bearing line is already pinned in `platformio.ini`:

```ini
platform = https://github.com/pioarduino/platform-espressif32/releases/download/53.03.11/platform-espressif32.zip
```

> **Do not bump this.** Newer IDF (5.5) makes the SPD2010 shimmer, and Arduino
> core >= 3.1.2 breaks the I2S DMA on PSRAM (`user context not in internal RAM`).
> 3.1.1 / IDF 5.3 is the only version clear of both. See `FIXES.md`.

**macOS setup used here** (a dedicated PlatformIO on Python 3.12, leaving the
system one untouched):

```bash
brew install expat                                   # Python 3.12's pyexpat needs it
python3.12 -m venv --without-pip ~/.pio-py312
DYLD_LIBRARY_PATH=/opt/homebrew/opt/expat/lib ~/.pio-py312/bin/python -m ensurepip
~/.pio-py312/bin/python -m pip install platformio
```

Any standard PlatformIO on Python >= 3.10 works too; the `pio.sh` wrapper just
points at the venv above and sets `DYLD_LIBRARY_PATH` for the expat fix.

### 2. Build & flash

```bash
git clone https://github.com/cupidbity/mp3-cyberdeck.git
cd mp3-cyberdeck

./pio.sh run                                              # build
./pio.sh run -t upload --upload-port /dev/cu.usbmodem1101 # flash (adjust the port)
./pio.sh device monitor                                   # 115200 baud serial
```

`pio.sh` is a thin wrapper (`exec ~/.pio-py312/bin/pio "$@"` with the DYLD var).
With a normal PlatformIO install you can just use `pio` directly.

The `ESP32-audioI2S` audio library is vendored in `lib/` at the exact snapshot
that compiles on core 3.1.x (git-master needs a newer core).

### 3. Prepare the SD card

1. Format a microSD as **FAT32**.
2. Copy `.mp3` files to the **root**.
3. Add a **`playlist.json`** in the root mapping each file to its metadata:

```json
[
  { "file": "Lovers Rock.mp3", "title": "Lovers Rock", "artist": "TV Girl" },
  { "file": "Pluto Projector.mp3", "title": "Pluto Projector", "artist": "Rex Orange County" }
]
```

- `file` must match the on-disk filename **exactly**.
- Files not in the JSON fall back to a `Title - Artist.mp3` filename convention.
- macOS `._*` AppleDouble files are ignored automatically.

Insert the card into the board and power on (press **BOOT** to reload if the
card was swapped after boot).

---

## Controls

| Input | Action |
|-------|--------|
| Tap the center button | Play / pause |
| Swipe left / right | Next / previous track |
| BOOT button | Reload SD card + playlist |
| Hold PWR ~2 s (on battery) | Power off |
| Press PWR (on battery) | Power on |

## Repo layout

```
platformio.ini          toolchain pin + board config
pio.sh                  build/flash wrapper (isolated PlatformIO)
src/
  main.cpp              the player (display, audio, touch, playlist, power)
  esp_lcd_spd2010.*     Waveshare's SPD2010 QSPI panel driver
  Touch_SPD2010.*       Waveshare's SPD2010 touch driver
  ui_play.h / ui_pause.h  412x412 RGB565 skins (generated from the PNGs)
  rainyhearts14.h       bitmap font (converted from rainyhearts.ttf)
lib/ESP32-audioI2S/     vendored audio library (core-3.1.x compatible)
mp3-display-*.png       source art for the skins
rainyhearts.ttf         source font
FIXES.md                the debugging story: every gotcha and why the fixes work
```

## Regenerating the assets

Skins (nearest-neighbor keeps the pixels crisp; **RGB565 big-endian** is this
panel's byte order; saturation is boosted because the backlight washes pastels):

```bash
ffmpeg -i mp3-display-play.png \
  -vf "scale=412:412:flags=neighbor,eq=saturation=1.7:contrast=1.08" \
  -pix_fmt rgb565be -f rawvideo ui.raw
# then pack ui.raw into a `static const uint8_t ui_play[...]` header
```

Font (Adafruit GFX `fontconvert`, needs freetype):

```bash
fontconvert rainyhearts.ttf 14 > src/rainyhearts14.h
```

## Common problems (full details in `FIXES.md`)

- **Toolchain version is everything** -- IDF 5.3 / core 3.1.1 (pin above).
- **Display color** is RGB565 **big-endian**, and this panel is **native
  orientation** (no rotation); a color test bar screen was used to prove it.
- **Backlight washout** -- full brightness desaturates the pastels, so it runs at
  ~40% on battery / ~55% on USB, chosen from the PWR-button boot state. A small
  cell (the 320 mAh one used here) sags under the display + audio load, which is
  part of why the battery brightness is turned down.
- **Battery** -- the PWR button is soft-power; the firmware latches `BAT_Control`
  (GPIO7) high only on a battery boot (driving it on USB perturbs the LCD rail).
- **Display + audio** run on separate cores (SPI2 panel refresh on core 0, I2S
  audio on core 1) so continuous refresh doesn't starve the audio.

## References

- Waveshare board docs (drivers, schematic, examples): <https://docs.waveshare.com/ESP32-S3-Touch-LCD-1.46>
- Waveshare example repo: <https://github.com/waveshareteam/ESP32-S3-Touch-LCD-1.46>
- pioarduino platform (Arduino-ESP32 core 3.x for PlatformIO): <https://github.com/pioarduino/platform-espressif32>
- ESP32-audioI2S: <https://github.com/schreibfaul1/ESP32-audioI2S>

mp3-cyberdeck

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

mp3-cyberdeck

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README