# 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

*   **WiFi Web Upload Interface:** Hosts a local WiFi network and web server so you can upload pictures and audio files directly to the microSD card from your phone or computer.
*   **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.
*   **Visual Status Indicators:** Disabled on this Touch board version to prevent SCLK (GPIO 38) line contention.

---

## 🌐 WiFi Upload Interface Setup

To upload new files to your photo frame over WiFi:
1.  Connect your phone, tablet, or computer to the WiFi network hosted by the board:
    *   **SSID:** `love`
    *   **Password:** `love1234`
2.  Open your browser and navigate to: **`http://192.168.4.1`**
3.  Choose a file (`.png`, `.mp3`, or `.wav`) and click **Upload to Frame**.
4.  The file will be saved directly to the microSD card. The board will automatically re-scan the card, and the new files will be indexed and ready to play!

---

## 🔌 Hardware Connections (External I2S DAC)

Because the Waveshare ESP32-S3-Touch-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 0** and acts as the input control.*

---

## 📁 Repository Structure

```text
├── 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
│   └── Web_Server.h/.cpp      # local SoftAP WiFi file upload panel
├── ESP32-S3-LCD-1.47-Demo/    # Waveshare Official Reference Demos
└── README.md                  # This file
```

---

## 💾 microSD Card Setup

1.  Format a microSD card to **FAT32**.
2.  Place your images in the root directory:
    *   **Extension:** `.png`
    *   **Resolution:** Sized to **172 x 320** pixels.
3.  Place your sound files in the root directory:
    *   **Extension:** `.mp3` or `.wav`
    *   **Format:** Compressed MP3 or uncompressed PCM WAV.
4.  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...**:
1.  **`PNGdec`** (by Larry Bank): Decoding and drawing PNGs.
2.  **`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
1.  Connect your board to your computer via USB.
2.  Select the corresponding COM Port under **Tools > Port**.
3.  Click **Upload** (or press `Ctrl+U`).