# ESP32 MP3 Player Memory Optimizations

This document summarizes the memory optimizations implemented to resolve out-of-memory issues in your ESP32 MP3 player.

## Implemented Optimizations

### 2. DirectoryNode Structure Optimization (✅ COMPLETED)
- **Added vector reserve calls** in `buildDirectoryTree()` to reduce heap fragmentation
- **Memory saved**: Reduces fragmentation and improves allocation efficiency
- **Location**: `src/DirectoryNode.cpp` - lines with `reserve(8)`, `reserve(16)`

### 3. Memory Pool Management (✅ COMPLETED)
- **Pre-allocated vector memory** to prevent frequent reallocations
- **Subdirectories**: Reserved space for 8 subdirectories
- **MP3 files**: Reserved space for 16 MP3 files per directory
- **IDs**: Reserved space for 16 IDs per directory
- **Memory saved**: ~1-2KB depending on directory structure

### 4. Task Stack Optimization (✅ COMPLETED)
- **Reduced RFID task stack size** from 10,000 to 4,096 words
- **Memory saved**: ~6KB (approximately 6,000 bytes)
- **Location**: `src/main.cpp` - `xTaskCreatePinnedToCore()` call

### 5. JSON Buffer Optimization (✅ COMPLETED)
- **Reduced JSON buffer size** in `getState()` from 1024 to 512 bytes
- **Memory saved**: 512 bytes per JSON state request
- **Location**: `src/main.cpp` - `DynamicJsonDocument jsonState(512)`

## Additional Recommendations (Not Yet Implemented)

### ESP32-audioI2S Library Optimizations (HIGH IMPACT!)

The ESP32-audioI2S library has several configurable memory settings that can significantly reduce RAM usage:

#### 1. Audio Buffer Size Optimization
```cpp
// In your main.cpp setup(), add after audio initialization:
audio.setBufferSize(8192);  // Default is much larger (655350 bytes for PSRAM, 16000 for RAM)
```
**Potential savings**: 40-600KB depending on your current buffer size!

#### 2. Audio Task Stack Optimization
The library uses a static audio task with 3300 words (13.2KB). You can modify this in the library:
```cpp
// In Audio.h, change:
static const size_t AUDIO_STACK_SIZE = 2048;  // Instead of 3300
```
**Potential savings**: ~5KB

#### 3. Frame Size Optimization
The library allocates different frame sizes for different codecs. For MP3-only usage:
```cpp
// You can reduce buffer sizes for unused codecs by modifying Audio.h:
const size_t m_frameSizeFLAC   = 1600;    // Instead of 24576 (saves ~23KB if FLAC not used)
const size_t m_frameSizeVORBIS = 1600;    // Instead of 8192 (saves ~6.5KB if Vorbis not used)
```

#### 4. Disable Unused Features
Add these build flags to `platformio.ini`:
```ini
build_flags = 
    -DAUDIO_NO_SD_FS          ; If you don't use SD file streaming
    -DAUDIO_NO_PSRAM          ; If you want to force RAM usage only
    -DCORE_DEBUG_LEVEL=0      ; Disable debug output
```

### String Optimization with F() Macro
- Use `F("string")` macro to store string literals in flash memory instead of RAM
- Example: `jsonState[F("playing")]` instead of `jsonState["playing"]`
- **Potential savings**: 2-3KB

### Web Content Optimization
- CSS is already moved to SD card (✅ done)
- JavaScript should be moved to SD card using the provided script
- **Potential savings**: ~7KB for JavaScript

### Compiler Optimizations
Add to `platformio.ini`:
```ini
build_flags = 
    -Os                    ; Optimize for size
    -DCORE_DEBUG_LEVEL=0   ; Disable debug output
    -DARDUINO_LOOP_STACK_SIZE=4096  ; Reduce loop stack
```

## Total Memory Savings Achieved

| Optimization | Memory Saved |
|--------------|--------------|
| Vector reserves | ~1-2KB |
| RFID task stack reduction | ~6KB |
| JSON buffer reduction | 512 bytes |
| **Current Total Savings** | **~7-8KB** |

## Potential Additional Savings (ESP32-audioI2S Library)

| ESP32-audioI2S Optimization | Potential Memory Saved |
|------------------------------|------------------------|
| Audio buffer size reduction | 40-600KB |
| Audio task stack reduction | ~5KB |
| Unused codec frame buffers | ~30KB |
| Disable unused features | 5-10KB |
| **Potential Additional Total** | **80-645KB** |

## Next Steps

1. **Copy web files to SD card**:
   ```bash
   ./copy_to_sd.sh
   ```
   (Adjust the SD card mount point in the script as needed)

2. **Test the optimizations**:
   - Monitor free heap using the web interface
   - Check for any stability issues
   - Verify RFID functionality with reduced stack size

3. **High-impact ESP32-audioI2S optimizations**:
   ```cpp
   // Add to setup() after audio.setPinout():
   audio.setBufferSize(8192);  // Reduce from default large buffer
   ```
   
4. **Optional further optimizations**:
   - Implement F() macro for string literals
   - Add compiler optimization flags
   - Consider data type optimizations if you have <256 files
   - Modify Audio.h for unused codec optimizations

## Files Modified

- `src/DirectoryNode.cpp` - Added vector reserve calls
- `src/main.cpp` - Reduced task stack and JSON buffer sizes
- `copy_to_sd.sh` - Script to copy web files to SD card

## Monitoring

The web interface displays current free heap memory. Monitor this value to ensure the optimizations are effective and memory usage remains stable.