An MPD (Music Player Daemon) server running on an ESP32-S3 microcontroller. Accepts standard MPD client connections over TCP (port 6600) and provides an optional web UI for service inspection and board-level control.
This project also serves as a proof of concept for an embedded MPD server. It can run without proper audio output, allowing you to explore the MPD protocol, test client connectivity, or use the web UI for state monitoring even without physical audio hardware.
- MPD protocol -- 46 commands implemented (see COMMANDS.md)
- Search --
find,search, andlistwith case-insensitive substring matching - Streaming responses -- Large result sets streamed per-entry, no buffer truncation
- Command timeout -- Configurable 500 ms timeout prevents hung commands
- Audio playback -- I2S, DAC, and PWM output with MP3, OGG, WAV codecs (FLAC and AAC optional)
- Filesystem browsing -- Browse SD card and internal audio partition via unified VFS wrapper
- WiFi provisioning -- BLE-based WiFi setup with persistent credential storage
- Playlist management -- Named playlists, binary persistence to LittleFS, shuffle
- Web UI (optional) -- Built-in HTTP server for service inspection, raw MPD command injection, and board-level controls (WiFi re-provisioning, reboot)
- ESP32-S3 development board (N16R8 recommended, N8R2 minimum; requires PSRAM)
The default sdkconfig.defaults targets N16R8 (16 MB flash, 8 MB octal PSRAM). For N8R2 (8 MB flash, 2 MB quad PSRAM), change the following in your sdkconfig.defaults:
# CONFIG_SPIRAM_MODE_OCT=y → CONFIG_SPIRAM_MODE_QUAD=y
# CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y → CONFIG_ESPTOOLPY_FLASHSIZE_8MB=y
Audio output (one of the following, optional):
- A speaker via internal DAC (mono, requires external amplifier)
- A speaker via PWM output (mono, requires external amplifier)
- An I2S audio codec board
Storage (optional):
- SD card module (SPI mode) with audio files
- Internal flash partition for demo audio files (LittleFS, read-only fallback)
This project uses ESP-IDF v5.5.4.
idf.py set-target esp32s3
idf.py build
idf.py flash
idf.py monitorConfiguration options are set via sdkconfig.defaults. Use idf.py menuconfig to adjust:
- Audio output backend, WiFi provisioning method, max clients
- Queue size, playlist limits, filesystem scan path
- Command timeout, web UI credentials
See CONFIG.md for the full list of Kconfig parameters.
Host-based unit tests (no device needed):
cmake -S test -B build/test
cmake --build build/test
cd build/test && ctest --output-on-failureTests use the Unity framework with mock implementations for all ESP-IDF APIs and component dependencies. Frontend tests run via Python unittest (HTML/CSS validation) and Node.js node:test (JavaScript logic).
See test/README.md for details on the mock-based approach.
# Code style (check)
find . -not -path '*/build/*' -not -path '*/managed_components/*' \
\( -name '*.c' -o -name '*.h' \) -print0 \
| xargs -0 clang-format --dry-run -Werror -style=file
# Code style (fix in place)
find . -not -path '*/build/*' -not -path '*/managed_components/*' \
\( -name '*.c' -o -name '*.h' \) -print0 \
| xargs -0 clang-format -i -style=file
# Cyclomatic complexity (CCN <= 10)
lizard -l c -w -C 10 -x '*/build/*' -x '*/managed_components/*' .
# Test coverage (>= 70% per file)
gcovr --root . --exclude 'build/' --exclude 'test/' \
--print-summary --fail-under-line 70
# Source file length (<= 1000 lines)
find . -not -path '*/build/*' -not -path '*/managed_components/*' \
\( -name '*.c' -o -name '*.h' \) -exec wc -l {} + \
| awk '$1 > 1000 { print $2 " " $1 " lines (limit 1000)" }'GNU Static Analyzer (idf.py clang-check) runs during firmware builds when CONFIG_COMPILER_STATIC_ANALYZER=y is set (enabled by default).
| Component | Description |
|---|---|
mainapp |
Boot sequence orchestrator (board_init → sd_card → storage → queue_manager → wifi_prov → audio_player → protocol_manager → web_ui) |
protocol_manager |
TCP listener on port 6600, MPD command parsing and dispatch |
queue_manager |
Audio file index, playlist management, search, binary persistence |
audio_player |
Playback engine with I2S/DAC/PWM output backends |
audio_decoder |
MP3, OGG, WAV format detection, seeking, and decoding |
storage |
LittleFS partition mounts and VFS-level file listing |
sd_card |
SD card interface via SPI (LittleFS/FAT detection, file iterator) |
web_ui (optional) |
HTTP server, REST API for MPD inspection and board control (WiFi re-provisioning, reboot, raw command injection), mDNS discovery |
wifi_prov |
BLE/hardcoded WiFi provisioning with NVS credential storage |
board_init |
NVS, netif, and event-loop initialization |
GNU General Public License v3.0. See LICENSE.
Oscar Diaz odiaz@ieee.org