ES8311
======

.. seo::
    :description: Instructions for using ESPHome's ES8311 audio DAC platform to play media from your devices.
    :image: es8311.svg
    :keywords: ES8311, Audio, DAC, I2S, ESP32

The ``es8311`` platform allows your ESPHome devices to use the ES8311 low power mono audio codec.
This allows the playback of audio via the microcontroller from a range of sources via :doc:`/components/speaker/index` or
:doc:`/components/media_player/index`.

The :ref:`I²C bus <i2c>` is required in your configuration as this is used to communicate with the ES8311.

.. code-block:: yaml

    # Example configuration entry
    audio_dac:
      - platform: es8311

.. _config-es8311:

Configuration variables:
------------------------
- **bits_per_sample** (*Optional*, enum): The bit depth of the audio samples. One of ``16bit``, ``24bit``, or ``32bit``. Defaults to ``16bit``.
- **sample_rate** (*Optional*, positive integer): I2S sample rate. Defaults to ``16000``.
- **use_mclk** (*Optional*, bool): Use the MCLK signal to control the clock. Defaults to ``True``.
- **use_microphone** (*Optional*, bool): Configure the codec's ADC for microphone input. Defaults to ``False``.
- **mic_gain** (*Optional*, enum): The gain applied to the ADC microphones. One of ``MIN``, ``0DB``, ``6DB``, ``12DB``, ``18DB``, ``24DB``, ``30DB``, ``36DB``, ``42DB``, or ``MAX``. Defaults to ``42DB``.
- **address** (*Optional*, int): The I²C address of the driver. Defaults to ``0x18``.
- **i2c_id** (*Optional*): The ID of the :ref:`I²C bus <i2c>` the ES8311 is connected to.
- All other options from :ref:`Audio DAC <config-audio_dac>`.

Automations
-----------

All :ref:`Audio DAC Automations <automations-audio_dac>` are supported by this platform.

Configuration Examples
----------------------

**ESP32 S3 Box 3**:

.. code-block:: yaml

    audio_dac:
      - platform: es8311
        id: es8311_dac
        bits_per_sample: 16bit
        sample_rate: 16000

    i2s_audio:
      - id: i2s_output
        i2s_lrclk_pin: GPIO45
        i2s_bclk_pin: GPIO17
        i2s_mclk_pin: GPIO23

    speaker:
      - platform: i2s_audio
        i2s_audio_id: i2s_output
        id: speaker_id
        i2s_dout_pin: GPIO15
        dac_type: external
        sample_rate: 16000
        bits_per_sample: 16bit
        channel: stereo
        audio_dac: es8311_dac

    switch:
      - platform: gpio
        name: "Speaker Enable"
        pin: GPIO46
        restore_mode: RESTORE_DEFAULT_ON

See Also
--------

- :doc:`index`
- :apiref:`es8311/es8311.h`
- :apiref:`audio_dac/audio_dac.h`
- :ghedit:`Edit`