Espressif Audio Development Framework Guide Choose version... Get Started API Reference Design Guide Knowledge Center Resources Copyrights English-Chinese Glossary About Espressif Audio Development Framework Guide » Espressif Audio Development Framework Guide Edit on GitHub Espressif Audio Development Framework Guide [中文] This is the documentation for Espressif Audio Development Framework (ESP-ADF). Get Started API Reference Design Guide Knowledge Center Index Provide feedback about this document Next © Copyright 2017 - 2026, Espressif Systems (Shanghai) Co., Ltd.. Built with Sphinx using a theme based on Read the Docs Sphinx Theme. Download PDF Espressif Audio Development Framework Guide Choose version... Get Started Development Board Overview About ESP-ADF Quick Start Linux and macOS Windows Installation Step by Step Setting up Development Environment Creating Your First Project Step 1. Set up ESP-IDF Step 2. Get ESP-ADF Windows Linux and macOS Step 3. Set up the environment Windows Linux and macOS Step 4. Start a Project Windows Linux and macOS Step 5. Connect Your Device Step 6. Configure Windows Linux and macOS Step 7. Build the Project Step 8. Flash onto the Device Step 9. Monitor VS Code Extension IDF Eclipse Plugin and Espressif IDE Install and Set up Environment Variables Create a New Project Import Existing Project Quick Start Update ESP-ADF API Reference Design Guide Knowledge Center Resources Copyrights English-Chinese Glossary About Espressif Audio Development Framework Guide » Get Started Edit on GitHub Get Started This document is intended to help users set up the software environment for the development of audio applications using hardware based on the ESP32 family of chips by Espressif. After that, a simple example will show you how to use ESP-ADF (Espressif Audio Development Framework). Development Board Overview For easier start with ESP-ADF, Espressif designed ESP32, ESP32-S2, and ESP32-S3 based development boards intended for audio applications. Click the links below to learn more about the available boards. ESP32-LyraT ESP32-LyraT-Mini ESP32-LyraTD-MSC ESP32-S2-Kaluga-1 ESP32-Korvo-DU1906 ESP32-S3-Korvo-2 ESP32-C3-Lyra If you do not have any of the above boards, you can still use ESP-ADF for the ESP32 and ESP32-S2 based audio applications. For this, your board needs to have a compatible audio codec or DSP chip; alternatively, you can develop a driver to support communication with your specific chip. About ESP-ADF The ESP-ADF is available as a set of components to extend the functionality already delivered by the ESP-IDF (Espressif IoT Development Framework). To use ESP-ADF you need set up the ESP-IDF first, and this is described in the next section. Note ESP-ADF provides support for specific ESP-IDF versions. If your have already set up another version, please switch to a supported ESP-IDF version, or you may not be able to compile ESP-ADF applications. In addition, the python version needs to be between 3.7 and 3.11. Quick Start This section provides quick steps to run a simple ADF sample project on an ESP device for experienced users. For beginners, please go through the complete steps from Step 1. Set up ESP-IDF to Step 9. Monitor to build a project. Note If you want to install using an IED, please refer to Section VS Code Extension VS Code or Section IDF Eclipse Plugin and Espressif IDE. If you encounter issues in the following steps, you could refer to the complete steps from Step 1. Set up ESP-IDF to Step 9. Monitor or describe them in GitHub Issues or ESP Forum. Linux and macOS The operating environment below is on Linux Ubuntu 18.04 and above. Download the full ESP-ADF repository from GitHub by running: git clone --recursive https://github.com/espressif/esp-adf.git For users located in China, it is faster to download from Gitee: git clone --recursive https://gitee.com/EspressifSystems/esp-adf.git Configure the $ESP-IDF and $ESP-ADF compilation environment by running: cd esp-adf ./install.sh . ./export.sh After completing the above environment variable configuration, you can compile the ADF sample project $ADF_PATH/examples/get-started/play_mp3_control. Switch to the project’s directory, compile, and flash it onto your ESP device by running the following command. Then, you will see the serial port of the routine is printed. cd $ADF_PATH/examples/get-started/play_mp3_control idf.py build flash monitor Windows Download the full ESP-ADF repository from GitHub by running: git clone --recursive https://github.com/espressif/esp-adf.git For users located in China, it is faster to download from Gitee: git clone --recursive https://gitee.com/EspressifSystems/esp-adf.git Install the $ESP-IDF compilation environment in the command prompt window: Using Command Prompt (cmd.exe): cd esp-adf .\install.bat **Using PowerShell:** cd esp-adf .\install.ps1 Or first download the full ESP-IDF Windows Installer from ESP-IDF Windows Installer (Please download the ESP-IDF versions supported by ESP-ADF). And then turn off the antivirus software (Because it may prevent the installation as the software writes the Windows system regedit) and install the downloaded file. After the installation is complete, open the ESP-IDF CMD shortcut icon on the desktop, the script will automatically help you download submodules, and set environment variables such as IDF_PATH. Set the ADF_PATH by running the following commands: Using Command Prompt (cmd.exe): .\export.bat echo %ADF_PATH% Using PowerShell: .\export.ps1 echo $ADF_PATH // or echo $env:ADF_PATH If your ADF_PATH variable prints correctly, it’s time to compile the ADF routines: Using Command Prompt (cmd.exe): cd %ADF_PATH%\examples\get-started\play_mp3_control idf.py build flash monitor Using PowerShell: cd $ADF_PATH\examples\get-started\play_mp3_control idf.py build flash monitor Installation Step by Step This is a detailed roadmap to walk you through the installation process. Setting up Development Environment Step 1. Set up ESP-IDF for Windows, Linux or Mac OS Step 2. Get ESP-ADF Step 3. Set up the environment Creating Your First Project Step 4. Start a Project Step 5. Connect Your Device Step 6. Configure Step 7. Build the Project Step 8. Flash onto the Device Step 9. Monitor Step 1. Set up ESP-IDF Configure your PC according to Getting Started section of ESP-IDF Programming Guide. Windows, Linux and Mac OS operating systems are supported. Please select and follow the guide specific to ESP32 or ESP32-S2 chip. The chip name is provided in the board name. Note This guide uses the directory ~/esp on Linux and macOS or %userprofile%\esp on Windows as an installation folder for ESP-ADF. You can use any directory, but you will need to adjust paths for the commands accordingly. Keep in mind that ESP-ADF does not support spaces in paths. To make the installation easier and less prone to errors, use the ~/esp default directory for the installation. If this is your first exposure to the ESP-IDF, then it is recommended to get familiar with hello_world or blink example first. After getting familiar with ESP-IDF, decide on which ESP-IDF version to use for your application depending on the Espressif chip that you have and your project type. For this, consult Versions section of ESP-IDF Programming Guide. Once you successfully build, upload, and run examples for your version of ESP-IDF, you can proceed to the next step. Step 2. Get ESP-ADF Now you can start installing audio-specific API / libraries provided in ESP-ADF repository. Windows Open Command Prompt and run the following commands: cd %userprofile%\esp git clone --recursive https://github.com/espressif/esp-adf.git Linux and macOS Open Terminal, and run the following commands: cd ~/esp git clone --recursive https://github.com/espressif/esp-adf.git Step 3. Set up the environment Before being able to compile ESP-ADF projects, on each new session, ESP-IDF tools should be added to the PATH environment variable. To make the tools usable from the command line, some environment variables must be set. ESP-ADF provides a script which does that. Windows ESP-IDF Tools Installer for Windows creates an “ESP-IDF Command Prompt” shortcut in the Start Menu. This shortcut opens the Command Prompt and sets up all the required environment variables. You can open this shortcut and proceed to the next step. Alternatively, if you want to use ESP-IDF in an existing Command Prompt window, you can run: %userprofile%\esp\esp-adf\export.bat Linux and macOS In the terminal where you have installed ESP-IDF, run: . $HOME/esp/esp-adf/export.sh Note the space between the leading dot and the path! You can also create an alias for the export script to your .profile or .bash_profile script. This way you can set up the environment in a new terminal window by typing get_idf: alias get_idf='. $HOME/esp/esp-adf/export.sh' Note that it is not recommended to source export.sh from the profile script directly. Doing so activates IDF virtual environment in every terminal session (even in those where IDF is not needed), defeating the purpose of the virtual environment and likely affecting other software. Step 4. Start a Project After initial preparation you are ready to build the first audio application. The process has already been described in ESP-IDF documentation. Now we would like to discuss remaining key steps and show how the toolchain is able to access the ESP-ADF components by using the ADF_PATH variable. To demonstrate how to build an application, we will use get-started/play_mp3_control project from examples directory in the ADF. Windows cd %userprofile%\esp xcopy /e /i %ADF_PATH%\examples\get-started\play_mp3_control play_mp3_control Linux and macOS cd ~/esp cp -r $ADF_PATH/examples/get-started/play_mp3_control . There is a range of example projects in the examples directory in ESP-ADF. You can copy any project in the same way as presented above and run it. It is also possible to build examples in-place, without copy