hannabox/MEMORY_OPTIMIZATIONS.md

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

// 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:

// 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:

// 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:

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:

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:

   ./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:

   // 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.