ESP-ADF: Espressif's audio framework for ESP32, read from the repository

An audio framework that assumes a speaker and a microphone

ESP-ADF sits above ESP-IDF and treats audio as a data path problem rather than a driver problem. The repository describes itself as the Advanced Development Framework for the ESP32, ESP32-S2, ESP32-C3, ESP32-C6, ESP32-C5, ESP32-S3 and ESP32-P4, which is a much wider chip list than the audio-first parts alone would suggest. A 2,313 star repository with 880 forks is substantial for a framework that most people meet only through the getting-started guide.

The stated scope is broader than playback. The README lists music player and recorder support for MP3, AAC, FLAC, WAV, OGG, OPUS, AMR and TS, then names processing elements such as EQ, downmixer, Sonic, ALC and G.711. Those are not codecs in the strict sense but stream transforms, which tells you the framework models audio as a pipeline of stages rather than as one call into one library.

The sources list is where the design becomes clear. HTTP, HLS, SPIFFS, SDCARD, A2DP-Source, A2DP-Sink and HFP all appear as inputs, and the protocol list adds DLNA, VoIP, RMTP and ESP-RTC, which the README breaks out as SIP, RTSP and RTCP. On top of that sit application-level features: video calling, video recording, live video streaming, internet radio, and voice recognition wired to Alexa and DuerOS.

The repository root shows the same scope in its layout. There is a `components/` tree, a `micropython_adf/` directory for MicroPython bindings, an `idf_patches/` directory, a `tools/` directory, and both `project.mk` and `CMakeLists.txt`, so the build is supported through both the older make path and CMake. The `esp-idf` entry in the tree is a submodule, which is the reason the branch and version rules below matter so much.

Building from release/v2.x, not from master

The single most consequential line in the README is a warning that ESP-ADF v2.8 and later only receive updates on the `release/v2.x` branch, and that `master` is not compatible with it anymore. The default branch is `release/v2.x`, pushed on 2026-09-23, so a plain clone lands you in the right place, but anyone following a v3.0-era blog post or an old fork will find that master tracks ADF v3.0 development and will not build v2.x examples. The hardware section repeats the instruction, which suggests how often people get it wrong.

The second rule concerns the framework underneath. A compatibility table maps ESP-IDF release branches v5.1 through v5.5 against both `release/v2.x` and tag v2.8, and every cell in those five columns reads supported. The ESP-IDF master column reads not supported, and the README explains why: major feature changes on master may conflict with ESP-ADF, though examples unaffected by those changes can still run there. That is an unusually honest annotation of an unsupported configuration, and it is the difference between a policy statement and a real caveat.

The same paragraph notes that end-of-life IDF branches are removed from the table entirely. So the framework does not accumulate stale version combinations; it prunes them, which means an IDF version disappearing from ESP-ADF is a signal to migrate rather than to hunt for a fix. The tree's `idf_patches/` directory suggests the maintainers also carry local adjustments rather than requiring a patched ESP-IDF fork.

Cloning the framework and its pinned IDF takes four commands. Nothing here depends on a hosted package registry; the submodule is part of the repository.

git clone https://github.com/espressif/esp-adf.git
cd esp-adf
./install.sh
source export.sh

The README states the quick start needs one of the ESP-IDF versions listed in the releases, one of the supported audio boards, and headphones. It also points first-time ESP-IDF users at the per-chip getting started guides for ESP32, ESP32-S2, ESP32-S3 and ESP32-P4, which is a fair signal that ESP-ADF is not the place to learn the toolchain.

The board list is short on purpose

Five boards get named in the hardware table: ESP32-LyraT-Mini, ESP32-S3-Korvo-2, ESP32-C3-Lyra, the ESP32-S3-Box series and the ESP32-P4-Function-EV-Board. Each links to a board-specific getting-started or user guide page. That is a short list for a framework that claims support for seven SoC families, and the reason is that the framework's hard part is the codec path: amplifier enable lines, microphone channels, codec chips and board-specific routing are what actually decide whether a project works.

Two of those entries are worth separating. The Korvo-2 sits on the speech side of the house, with ESP-SR integration arriving in v2.7, which lines up with the voice recognition and Alexa work in the README. The P4-Function-EV-Board is the newest addition, referenced in v2.7 and again in v2.8 where it appears as a sub-board for the AEC stream. The P4 has no integrated audio of its own, so it is the board that shows where ESP-ADF is heading: more of the audio intelligence in the framework, less in the silicon.

The S3-Box series is the outlier, since it is maintained in a separate repository rather than as a dev kit. Anyone setting up from a Box will spend their first hour finding out that board support and framework support are two different things, which is worth knowing before the first build fails.

Headphones appear in the quick-start requirement list, which sounds fussy until you remember that several of these boards route audio through a codec that needs a real load. It also hints that the first thing the framework proves out is the output path, not a full duplex call.

What v2.6, v2.7 and v2.8 actually changed

No release notes file exists in the repository, so the three most recent releases are the changelog. Reading them in order is the fastest way to understand where the framework is spending its effort.

v2.6, published 2023-08-04, is where the components registry appears: ESP-Muxer at v1.0.0, ESP-Audio-Encoder at v1.0.1 and ESP-Codec-Dev at v1.0.3. It also added ESP-IDF v5.0 and v5.1 support, 24-bit I2S, a configurable range size on http_stream, a memory trace helper in media_lib_sal, wake word support on the audio recorder, and removal of the FatFS restriction that had limited URIs to the SD card. It carries a known issue worth quoting: the I2S stream is not fully compatible with the new I2S driver, so PDM playback, DAC PDM and PDM recording need care.

v2.7, published 2024-09-14, is the breaking one. The audio recorder callback prototype changed, `periph_wifi_init` gained a `wifi_config_t` parameter, and ESP-RTC jumped to v1.2.0 with its own breaking changes. In the same release Espressif added ESP-IDF v5.3, esp-sr nsnet models, i2s_stream built on the v5.x I2S APIs, a configurable user agent, the ESP32-S3-BOX-3 and P4-FUNCTION-EV-BOARD boards, install and export scripts for Windows and Unix, an audio mixer, ring buffer element handles, an es7210 driver, and a MicroPython component pinned at 5114f2c1e.

v2.8, published 2026-03-17, moves the IDF submodule to v5.5.3 and stays additive: HLS multi-key support in http_stream, gzip in audio_stream, a C++ build, a Windows PowerShell install script, export script support for bash and zsh, an AEC stream, and the P4 sub-board. The fixes listed are the interesting part, since they cluster on i2s_stream expansion on IDF 5.x, mono I2S, a ring buffer bug, duplicate AEC start and pause, and slot_mask handling.

The shape of those three releases says something specific: the framework is spending its time on IDF migration, codec plumbing and call quality, not on new format support. Format coverage has not moved since v2.6.

The examples directory is the framework's table of contents

Sixteen example directories sit under `examples/`, and reading their names tells you which use cases Espressif expects to be common. `player/` and `recorder/` are the base cases. `audio_processing/` holds the transform stage in the pipeline. `speech_recognition/` and `ai_agent/` cover the wake-word and assistant path, while `cloud_services/` covers everything that leaves the device.

The remaining directories map cleanly onto the README's feature list. `protocols/` is DLNA, VoIP and the ESP-RTC family. `display/` pairs with video output, `ota/` with firmware update, and `dueros/` and `korvo_du1906/` are board and cloud-service specific rather than general. `cli/`, `system/` and `advanced_examples/` cover the shell and the things that only matter once a product exists. `checks/` and `get-started/` are entry points rather than features.

There is also a `micropython_adf/` directory at the root, which is unusual enough to be worth a reader's attention. It means a Python-side API to the same pipeline, pinned to a specific commit in v2.7, which is a reasonable approach for scripting a board during bring-up without writing C.

One honest limit: the repository ships no per-component API reference here. The README points at the published documentation site and at the block diagram image for architecture, and the `docs/` directory exists but the component headers are the real reference. A reader deciding between ESP-ADF and writing raw ESP-IDF audio code will find the answer faster by reading one component header than by skimming the docs index.

Licensing and the practical comparison

The repository metadata reports no standard SPDX licence identifier, and a `LICENSE` file exists at the root without the machine-readable classification the file name suggests. That is not a red flag on its own, since Espressif publishes licence text for its frameworks elsewhere, but it does mean a licence audit cannot be automated from the API metadata alone. Anyone shipping a product should read that file rather than trust the repository field.

The honest comparison is with plain ESP-IDF plus codec libraries. Raw ESP-IDF gives you an I2S driver, an audio codec component and full control over timing. It also gives you every buffer management decision, every Bluetooth profile stack, and no HLS, no AEC, no ESP-RTC. ESP-ADF hands you all of that already wired, which is exactly the value and exactly the cost: the pipeline is opinionated about where streams live and how stages hand buffers to each other.

For a voice assistant, a video call product or an internet radio build, that trade is obviously worth it. For a product that records one channel of raw PCM to a flash file, the framework is overhead, and ESP-IDF's audio recorder examples are the more honest starting point. The framework's own example split mirrors this: `player/` and `recorder/` are deliberately simple, and the complexity shows up in `protocols/` and `ai_agent/`.

Given that `release/v2.x` was pushed on 2026-09-23 and the repository is not archived, the v2.x line is the live one. A new project should pin the IDF version to the submodule that ships with the chosen ADF release rather than tracking ESP-IDF master, and a project already on v2.6 should read the v2.7 breaking changes before touching code.

Editorial conclusion

ESP-ADF earns its place when a product needs streaming audio, Bluetooth profiles and call handling on one microcontroller, and it is hard to justify as a general framework layer. The repository's most useful file is the IDF compatibility table, and its most important line is that v2.8 and later live only on release/v2.x, with master reserved for the incompatible v3.0 line.

Frequently asked questions

Official sources

1. espressif/esp-adf on GitHub
2. Issues
3. README
4. Releases