Getting Started
===============

:link_to_translation:`zh_CN:[中文]`

This document helps developers set up a multimedia application development environment based on Espressif ESP32 series chips and demonstrates how to use ESP-GMF (Espressif General Multimedia Framework) through an example project.

After reading this document, you will be able to:

- Install and configure a supported version of ESP-IDF
- Obtain an ESP-GMF example project
- Build and flash the project, and monitor its output via serial port

About ESP-GMF
-------------

`ESP-GMF <https://github.com/espressif/esp-gmf>`__ is a collection of multimedia components built on ESP-IDF, extending its capabilities in audio, video, image, and generic streaming data processing. The core module (GMF-Core) and various elements and packages are published to the `IDF Component Manager <https://components.espressif.com/>`__ and can be automatically fetched and version-tracked by it.

Developers typically only need to declare dependencies in the project's ``idf_component.yml``. The component manager fetches them automatically at build time without any additional environment variables. This document provides two methods to obtain an example project: cloning the repository or using the component manager.

.. note::

   The currently supported ESP-IDF versions for ESP-GMF are ``>= v5.4.3`` (``release/v5.4`` branch), ``>= v5.5.2`` (``release/v5.5`` branch), or ``>= v6.0``.

.. _get-started-setup-idf:

Step 1. Install ESP-IDF
-----------------------

Follow the "Get Started" section in the `ESP-IDF Programming Guide <https://docs.espressif.com/projects/esp-idf/en/latest/index.html>`__ for your operating system (Windows, Linux, or macOS) to install the ESP-IDF toolchain and dependencies.

After installation and environment activation, confirm that the following command runs successfully in the terminal:

.. code-block:: bash

   idf.py --version

and outputs a supported version number (see the version note in `About ESP-GMF`_).

.. note::

   If ESP-IDF is already installed but the version is not in the supported range, see `ESP-IDF Versions <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/versions.html>`__ to switch branches.

.. _get-started-get-gmf:

Step 2. Get an ESP-GMF Example Project
--------------------------------------

GMF example projects are stored in the ``gmf_examples`` directory of the repository. This document uses ``pipeline_play_embed_music`` as an example to demonstrate the complete build and run workflow. This example reads an embedded MP3 audio file from flash, decodes it, applies audio effects, and plays it through the codec to a speaker.

Two methods are available to obtain the example project. Use either method below.

- Method A (Clone Repository): Download the complete ESP-GMF source code and all examples. Suitable for in-depth framework study, comparing examples, or contributing to ESP-GMF.
- Method B (Component Manager): Download only one example project; required component dependencies are fetched automatically by the component manager at build time. This matches real product project development and is suitable for quick evaluation or integration.

**Method A (Clone Repository):**

Run the following command in the terminal to clone the complete ESP-GMF source repository:

.. code-block:: bash

   git clone https://github.com/espressif/esp-gmf.git

.. note::

   ``$GMF_PATH`` used below is a placeholder for documentation purposes only, representing the root directory of the cloned ``esp-gmf`` repository. Replace it with the actual local clone path when running commands.

**Method B (Download Example via IDF Component Manager):**

Run the following command in the target directory to fetch the example project directly via the IDF Component Manager:

.. code-block:: bash

   idf.py create-project-from-example "espressif/gmf_examples=0.8.0:pipeline_play_embed_music"

After execution, a ``pipeline_play_embed_music`` project folder is created in the current directory without cloning the entire ESP-GMF repository.

.. _get-started-start-project:

Step 3. Open the Example Project
--------------------------------

Navigate to the example project directory:

**Method A (Clone Repository): Linux / macOS**

.. code-block:: bash

   cd $GMF_PATH/gmf_examples/basic_examples/pipeline_play_embed_music

**Method A (Clone Repository): Windows**

.. code-block:: batch

   cd %GMF_PATH%\gmf_examples\basic_examples\pipeline_play_embed_music

**Method B (Component Manager):**

.. code-block:: bash

   cd pipeline_play_embed_music

.. note::

   The ESP-IDF build system does not support spaces in paths. Ensure that the full paths to both ESP-IDF and the project contain no spaces.

.. _get-started-connect:

Step 4. Connect the Development Board
-------------------------------------

Connect an audio development board (``pipeline_play_embed_music`` supports ESP32-S3-Korvo V3 and other ESP audio development boards by default) to the PC via USB cable, and identify the serial port using `ESP-IDF: Establish Serial Connection <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/get-started/establish-serial-connection.html>`__:

- On Linux, typically ``/dev/ttyUSB0`` or ``/dev/ttyACM0``
- On macOS, typically ``/dev/cu.usbserial-*`` or ``/dev/cu.SLAB_USBtoUART``
- On Windows, typically ``COM3``, ``COM4``, etc.

.. note::

   Note the serial port for the board; it is needed in the :ref:`get-started-flash` and :ref:`get-started-monitor` steps.

.. _get-started-board-manager:

Step 5. Configure Hardware
--------------------------

ESP-GMF example projects use `ESP Board Manager <https://github.com/espressif/esp-board-manager>`__ to manage peripheral descriptions and board-level initialization code. Installing the helper tool ``esp-bmgr-assist`` as the default tool is recommended.

Install in the activated ESP-IDF Python environment (only needed once per environment):

.. code-block:: bash

   pip install esp-bmgr-assist

To upgrade to the latest version:

.. code-block:: bash

   pip install --upgrade esp-bmgr-assist

List supported development boards:

.. code-block:: bash

   idf.py bmgr -l

Example output:

.. code-block:: none

    [1] esp32_c3_lyra
    [2] esp32_lyrat_mini_1_1
    [3] esp32_p4_function_ev_board
    [4] esp32_s31_function_coreboard_1
    [5] esp32_s31_korvo_1
    [6] esp32_s3_box_3
    [7] esp32_s3_box_lite
    [8] esp32_s3_korvo_2_3
    [9] esp32_s3_lcd_ev_board
    [10] esp_vocat_1_0
    [11] esp_vocat_1_2

Select a development board:

.. code-block:: bash

   idf.py bmgr -b <board_index|board_name>

For example, to select ``esp32_s3_korvo_2_3``:

.. code-block:: bash

   idf.py bmgr -b 8
   # or
   idf.py bmgr -b esp32_s3_korvo_2_3

On the first run of ``idf.py bmgr``, the component is automatically downloaded based on the ``espressif/esp_board_manager`` dependency declared in the project's ``main/idf_component.yml``.

.. note::

   - To switch to another board supported by ``esp_board_manager``, follow the same steps with a different board name or index.
   - To use a custom board not in the list, see the `Custom Board Guide <https://github.com/espressif/esp-board-manager/blob/main/esp_board_manager/docs/how_to_customize_board.md>`__.
   - For more information on ``esp_board_manager``, see the `ESP Board Manager Getting Started Guide <https://github.com/espressif/esp-board-manager/blob/main/esp_board_manager/README.md>`__.

.. _get-started-configure:

Step 6. Configure the Project
-----------------------------

Open the project configuration menu:

.. code-block:: bash

   idf.py menuconfig

For the ``pipeline_play_embed_music`` example, the default configuration can be built and run directly. To adjust other project options, see the ``README`` in the example project directory.

After making changes, press ``S`` to save and ``Q`` to exit the menu.

.. _get-started-build:

Step 7. Build the Project
-------------------------

Run the following command to start building:

.. code-block:: bash

   idf.py build

This command builds all components involved in ESP-IDF and ESP-GMF in dependency order, generating the bootloader, partition table, and application binary files. The first build takes longer; subsequent incremental builds are significantly faster.

After a successful build, the terminal outputs a message similar to the following and shows the corresponding flash command:

.. code-block:: none

   Project build complete. To flash, run:
    idf.py flash
   or
    idf.py -p PORT flash

If build errors occur, check the ESP-IDF version, whether the board configuration in :ref:`get-started-board-manager` was completed successfully, and whether dependencies were fetched correctly.

.. _get-started-flash:

Step 8. Flash the Firmware
--------------------------

Replace ``PORT`` with the serial port noted in :ref:`get-started-connect`, then run the following command to flash and open the serial monitor:

.. code-block:: bash

   idf.py -p PORT flash monitor

.. note::

   - ``idf.py flash`` automatically rebuilds before flashing, so running ``idf.py build`` separately is not necessary.
   - The default baud rate is ``460800``; adjust it with the ``-b BAUD`` parameter.
   - If the board has no auto-reset circuit, hold the **Boot** button, press and release the **Reset** button once, then release the **Boot** button to enter download mode before flashing.
   - If the board uses USB Serial JTAG and the serial port is not found, try entering download mode manually as described above and then check for the serial port.

.. _get-started-monitor:

Step 9. Monitor the Output
--------------------------

After flashing, the board resets automatically and runs the example program. The serial monitor outputs a log similar to the following (key steps shown):

.. code-block:: none

   I (912)  main_task: Calling app_main()
   I (922)  PLAY_EMBED_MUSIC: [ 1 ] Mount peripheral
   I (1067) PLAY_EMBED_MUSIC: [ 2 ] Register all the elements and set audio information to play codec device
   I (1067) PLAY_EMBED_MUSIC: [ 3 ] Create audio pipeline
   I (1110) PLAY_EMBED_MUSIC: [ 4 ] Start audio_pipeline
   I (1223) PLAY_EMBED_MUSIC: [ 5 ] Wait stop event to the pipeline and stop all the pipeline
   I (23448) PLAY_EMBED_MUSIC: [ 6 ] Destroy all the resources

If everything is working correctly, the speaker or headphones connected to the board play an embedded MP3 test audio clip lasting approximately 20 seconds. After playback ends, the example releases all resources and exits.

Press ``Ctrl+]`` to exit the serial monitor.

Next Steps
----------

Having completed this example, you now understand the basic workflow for an ESP-GMF project. Suggested next steps:

- Follow :doc:`../gmf-best-practices/index` to systematically learn the ESP-GMF development workflow and typical usage in product-level solutions using ``gmf_examples``.
- Read :doc:`../gmf-framework/index` to understand the overall architecture and working mechanisms of GMF-Core, Elements, and Packages.
- See the resource links in :doc:`../resources`, term definitions in :doc:`../glossary`, and contribution process in :doc:`../contributions-guide`.

Related Documents
-----------------

- `ESP-IDF Programming Guide <https://docs.espressif.com/projects/esp-idf/en/latest/index.html>`__
- `ESP Component Manager <https://components.espressif.com/>`__
- `ESP Component Manager Documentation <https://docs.espressif.com/projects/idf-component-manager/en/latest/>`__
- `ESP Board Manager Getting Started Guide <https://github.com/espressif/esp-board-manager/blob/main/esp_board_manager/README.md>`__
- `ESP Board Manager Troubleshooting <https://github.com/espressif/esp-board-manager/blob/main/esp_board_manager/README.md#troubleshooting>`__
- `ESP-GMF GitHub Repository <https://github.com/espressif/esp-gmf>`__
- `ESP-GMF Example Collection <https://github.com/espressif/esp-gmf/tree/main/gmf_examples>`__
