ESP32-S3-LCD-1.47 Sound & Picture Player

This repository contains a responsive, dual-core firmware application developed for the Waveshare ESP32-S3-LCD-1.47 development board.

The application reads PNG images and compressed MP3 / uncompressed WAV audio files from a microSD card, renders the images on the onboard ST7789 LCD display, and plays matching soundbites over an external I2S audio DAC.

🚀 Key Features

Alpha-Numeric Media Pairing: Scans the root of the microSD card for PNG images and audio files (.wav or .mp3), sorting and matching them alphabetically (e.g., 01_image.png pairs with 01_sound.mp3).
Dual-Core Software Decoding: Spawns a background task pinned to Core 0 running the ESP32-audioI2S decoding loop. This prevents audio dropouts or stutters during heavy display updates on Core 1.
Interactive Multi-Click Gestures: You can control slide progression, audio status, and volume from the board's single physical button:
- Single Click: Next photo/audio pair.
- Double Click: Toggle Pause / Resume audio playback.
- Triple Click: Previous photo/audio pair.
- Quadruple Click: Cycle volume through levels 4, 8, 12, 16, and 20 (on a 0-21 scale).
- Long Press (>1.5s): Toggle Autoplay slideshow mode.
WS2812 RGB LED Status Feedback: Utilizes the onboard RGB LED to output real-time visual feedback:
- 🔵 Solid Blue: Idle, waiting for manual trigger.
- 🟢 Pulsing Green: Audio is playing.
- 🟣 Pulsing Purple: Autoplay/Slideshow mode is active.
- ⚪ White Flashing: Confirms a volume change has been triggered.
- 🔴 Blinking Red: Error state (microSD card failed to initialize, or no media files were found).

🔌 Hardware Connections (External I2S DAC)

Because the Waveshare ESP32-S3-LCD-1.47 does not have built-in audio amplification or a speaker, you must connect an external I2S DAC/Amplifier (e.g., MAX98357A or PCM5102) to the exposed headers.

Configure the pin connections as follows:

Board Pin (Header)	ESP32-S3 GPIO	Function
GPIO 1	1	I2S BCLK (Bit Clock)
GPIO 2	2	I2S LRCK / WS (Frame Clock)
GPIO 4	4	I2S DIN / SD (Data Out from ESP)
3V3 / VBUS (5V)	VCC	Power Supply
GND	GND	Ground Reference

Note: The physical BOOT button is permanently connected to GPIO 9 and acts as the input control.

📁 Repository Structure

├── sound_picture_app/         # Custom Application Source
│   ├── sound_picture_app.ino  # Main coordinator, button click gesture parser, state machine
│   ├── Display_ST7789.h/.cpp  # Waveshare display initialization & backlight control
│   ├── Display_PNG.h/.cpp     # PNGdec utility for decoding and drawing images
│   ├── SD_Card.h/.cpp         # SD_MMC mount and folder retrieval helpers
│   └── Audio_Player.h/.cpp    # background ESP32-audioI2S player task wrapper
├── ESP32-S3-LCD-1.47-Demo/    # Waveshare Official Reference Demos
└── README.md                  # This file

💾 microSD Card Setup

Format a microSD card to FAT32.
Place your images in the root directory:
- Extension: .png
- Resolution: Sized to 172 x 320 pixels.
Place your sound files in the root directory:
- Extension: .mp3 or .wav
- Format: Compressed MP3 or uncompressed PCM WAV.
Ensure file names map alphabetically:
- photo1.png <--> sound1.mp3
- photo2.png <--> sound2.wav

🛠️ Software Setup & Flashing (Arduino IDE)

1. Board Package Installation

Make sure you have the official Espressif board package installed:

Go to File > Preferences > Additional Boards Manager URLs and add: https://espressif.github.io/arduino-esp32/package_esp32_index.json
Go to Tools > Board > Boards Manager, search for esp32 (by Espressif Systems), and install version 3.0.2 or higher.

2. Install Required Libraries

You need to install the following two libraries in the IDE via Sketch > Include Library > Manage Libraries...:

PNGdec (by Larry Bank): Decoding and drawing PNGs.
ESP32-audioI2S (by Wolle / schreibfaul1): Asynchronous MP3/WAV decoding.

3. Select Board Configurations

Go to the Tools menu and set the following variables:

Board: ESP32S3 Dev Module
USB CDC On Boot: Enabled (Required to see print logs over the native USB port)
Upload Speed: 921600
Flash Size: 16MB (128Mb)
Partition Scheme: 16MB Flash (3MB APP/9.9MB FATFS)

4. Upload

Connect your board to your computer via USB.
Select the corresponding COM Port under Tools > Port.
Click Upload (or press Ctrl+U).