8000 GitHub - dargor0/espmpd: An MPD (Music Player Daemon) server running on an ESP32 microcontroller. · GitHub
[go: up one dir, main page]

Skip to content
dargor0Public

About

An MPD (Music Player Daemon) server running on an ESP32 microcontroller.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ESP32 MPD Server

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.

Features

  • MPD protocol -- 46 commands implemented (see COMMANDS.md)
  • Search -- find, search, and list with 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)

Hardware Requirements

  • 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)

Building

This project uses ESP-IDF v5.5.4.

idf.py set-target esp32s3
idf.py build
idf.py flash
idf.py monitor

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

Running Tests

Host-based unit tests (no device needed):

cmake -S test -B build/test
cmake --build build/test
cd build/test && ctest --output-on-failure

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

Linting

# 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).

Architecture

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

License

GNU General Public License v3.0. See LICENSE.

Author

Oscar Diaz odiaz@ieee.org

About

An MPD (Music Player Daemon) server running on an ESP32 microcontroller.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0