一、背景

ESP-ADF 的 API 提供了一种使用编解码器（解码器和编码器）、流或音频处理功能等元素开发音频应用程序的方法。

该框架是通过将Elements组合成一个Pipeline来开发音频应用程序。如下图所示：

将MP3解码器和I2S流两个元素添加进管道，解码器的输入是MP3文件数据流，I2S流将解码后的音频数据输出到片外，各应用程序之间通过事件接口通信。

二、API说明

以下音频 HAL 接口位于 audio_hal/include/audio_hal.h。

2.1 audio_hal_init

2.2 audio_hal_ctrl_codec

2.3 audio_hal_set_volume

2.4 audio_hal_get_volume

以下音频元素接口位于 audio_pipeline/include/audio_element.h。

2.5 audio_element_set_read_cb

2.6 audio_element_setinfo

2.7 audio_element_getinfo

2.8 audio_element_get_state

以下音频管道接口位于 audio_pipeline/include/audio_pipeline.h。

2.9 audio_pipeline_init

2.10 audio_pipeline_register

2.11 audio_pipeline_link

2.12 audio_pipeline_set_listener

2.13 audio_pipeline_run

2.14 audio_pipeline_pause

2.15 audio_pipeline_resume

2.16 audio_pipeline_reset_ringbuffer

2.17 audio_pipeline_reset_elements

2.18 audio_pipeline_change_state

以下音频事件接口位于 audio_pipeline/include/audio_event_iface.h。

2.19 audio_event_iface_init

2.20 audio_event_iface_set_listener

2.21 audio_event_iface_listen

以下 I2S 流接口位于 audio_stream/include/i2s_stream.h。

2.22 i2s_stream_init

2.23 i2s_stream_set_clk

以下 MP3 解码器接口位于 esp-adf-libs/esp_codec/include/codec/mp3_decoder.h。

2.24 mp3_decoder_init

三、音频播放一般步骤

启动音频编解码芯片
↓
创建音频管道pipeline，将所有元素elements添加入管道，并关联管内元素

• 创建MP3解码器去解码MP3文件并设置用户读文件回调函数
• 创建写入到编解码芯片的I2S数据流
• 注册所有元素elements到音频管道pipeline
• 将所有元素链接起来，创建管道元素环缓冲区ringbuffer

↓
设置事件监听器

• 监听来自管道中所有元素的事件

↓
启动音频管道
↓
关闭音频管道

四、代码分析

使用 esp-adf\examples\get-started\play_mp3_control 中的例程

4.1 启动音频编解码芯片

音频板硬件的抽象层，用作用户应用程序和特定音频板（如ESP32 LyraT）的硬件驱动程序之间的接口。

API 提供数据结构来配置 ADC 和 DAC 信号转换的采样率、数据位宽、I2C 流参数以及连接到 ADC 和 DAC 的信号通道的选择。它还包含几个特定的功能，例如初始化音频板audio_hal_init()、控制音量audio_hal_get_volume()和audio_hal_set_volume()。

void app_main(void)
{
    ···
    ESP_LOGI(TAG, "[ 1 ] Start audio codec chip");
    //根据不同硬件版本进行硬件初始化
    audio_board_handle_t board_handle = audio_board_init();
    audio_hal_ctrl_codec(board_handle->audio_hal, AUDIO_HAL_CODEC_MODE_BOTH, AUDIO_HAL_CTRL_START);

    int player_volume;
    audio_hal_get_volume(board_handle->audio_hal, &player_volume);
    ···
}

在 audio_board_init() 中对编解码器芯片（如ES8388）进行配置包括ADC、DAC通道、编解码模式、i2s接口配置(如I2S从模式、标准模式、采样率48k、位宽16bit)。

#define AUDIO_CODEC_DEFAULT_CONFIG(){                   \
        .adc_input  = AUDIO_HAL_ADC_INPUT_LINE1,        \
        .dac_output = AUDIO_HAL_DAC_OUTPUT_ALL,         \
        .codec_mode = AUDIO_HAL_CODEC_MODE_BOTH,        \
        .i2s_iface = {                                  \
            .mode = AUDIO_HAL_MODE_SLAVE,               \
            .fmt = AUDIO_HAL_I2S_NORMAL,                \
            .samples = AUDIO_HAL_48K_SAMPLES,           \
            .bits = AUDIO_HAL_BIT_LENGTH_16BITS,        \
        },                                              \
};

/**
 * @brief Configure media hal for initialization of audio codec chip
 */
typedef struct {
    audio_hal_adc_input_t adc_input;       /*!< set adc channel */
    audio_hal_dac_output_t dac_output;     /*!< set dac channel */
    audio_hal_codec_mode_t codec_mode;     /*!< select codec mode: adc, dac or both */
    audio_hal_codec_i2s_iface_t i2s_iface; /*!< set I2S interface configuration */
} audio_hal_codec_config_t;

audio_hal_handle_t audio_board_codec_init(void)
{
    audio_hal_codec_config_t audio_codec_cfg = AUDIO_CODEC_DEFAULT_CONFIG();
    audio_hal_handle_t codec_hal = audio_hal_init(&audio_codec_cfg, &AUDIO_NEW_CODEC_DEFAULT_HANDLE);
    AUDIO_NULL_CHECK(TAG, codec_hal, return NULL);
    return codec_hal;
}

4.2 创建音频管道，将所有元素添加入管道，并关联管内元素

使用 ADF 进行开发的应用程序的基本构建块是audio_element对象。每个解码器、编码器、过滤器、输入流或输出流实际上都是一个音频元素。

一组链接元素的动态组合是使用音频管道完成的。您不处理单个元素，而只处理一个音频管道。每个元素都由一个环形缓冲区连接。音频管道还负责将消息从元素任务转发到应用程序。

void app_main(void)
{
    //定义一个音频处理管道
    audio_pipeline_handle_t pipeline;
    //因为是实现本地播放，只需定义i2s流和MP3解码两个元件
    audio_element_handle_t i2s_stream_writer, mp3_decoder;
    ···
    ESP_LOGI(TAG, "[ 2 ] Create audio pipeline, add all elements to pipeline, and subscribe pipeline event");
    audio_pipeline_cfg_t pipeline_cfg = DEFAULT_AUDIO_PIPELINE_CONFIG();
    //初始化管道
    pipeline = audio_pipeline_init(&pipeline_cfg);
    mem_assert(pipeline);

    ESP_LOGI(TAG, "[2.1] Create mp3 decoder to decode mp3 file and set custom read callback");
    mp3_decoder_cfg_t mp3_cfg = DEFAULT_MP3_DECODER_CONFIG();
    //初始化MP3解码器元素
    mp3_decoder = mp3_decoder_init(&mp3_cfg);
    //设置解码回调函数
    audio_element_set_read_cb(mp3_decoder, mp3_music_read_cb, NULL);

    ESP_LOGI(TAG, "[2.2] Create i2s stream to write data to codec chip");
    i2s_stream_cfg_t i2s_cfg = I2S_STREAM_CFG_DEFAULT();
    i2s_cfg.type = AUDIO_STREAM_WRITER;
    //初始化I2S流元素
    i2s_stream_writer = i2s_stream_init(&i2s_cfg);

    ESP_LOGI(TAG, "[2.3] Register all elements to audio pipeline");
    //注册元素到管道中去
    audio_pipeline_register(pipeline, mp3_decoder, "mp3");
    audio_pipeline_register(pipeline, i2s_stream_writer, "i2s");

    ESP_LOGI(TAG, "[2.4] Link it together [mp3_music_read_cb]-->mp3_decoder-->i2s_stream-->[codec_chip]");
    const char *link_tag[2] = {"mp3", "i2s"};
    //关联管内元素
    audio_pipeline_link(pipeline, &link_tag[0], 2);
    ···
}

audio_element_set_read_cb() 这个接口必不可少。这个API接口允许应用程序为管道中的第一个audio_element设置一个读回调，这个读回调提供和其他系统相联系的接口。当每次音频元素需要待处理的数据，这个函数被调用。

MP3解码回调函数如下所示：

int mp3_music_read_cb(audio_element_handle_t el, char *buf, int len, TickType_t wait_time, void *ctx)
{
    int read_size = file_marker.end - file_marker.start - file_marker.pos;
    if (read_size == 0) {
        return AEL_IO_DONE;
    } else if (len < read_size) {
        read_size = len;
    }
    memcpy(buf, file_marker.start + file_marker.pos, read_size);
    file_marker.pos += read_size;
    return read_size;
}

4.3 初始化按键

void app_main(void)
{
    ···
    ESP_LOGI(TAG, "[ 3 ] Initialize peripherals");
    esp_periph_config_t periph_cfg = DEFAULT_ESP_PERIPH_SET_CONFIG();
    esp_periph_set_handle_t set = esp_periph_set_init(&periph_cfg);

    ESP_LOGI(TAG, "[3.1] Initialize keys on board");
    audio_board_key_init(set);
    ···
}

4.4 设置事件监听器

ADF 提供事件接口 API 以在管道中的音频元素之间建立通信。API 是围绕 FreeRTOS 队列构建的。它实现了“侦听器”来监视传入的消息并通过回调函数通知它们。

void app_main(void)
{
    ···
    ESP_LOGI(TAG, "[ 4 ] Set up  event listener");
    //音频解码事件初始化
    audio_event_iface_cfg_t evt_cfg = AUDIO_EVENT_IFACE_DEFAULT_CFG();
    audio_event_iface_handle_t evt = audio_event_iface_init(&evt_cfg);

    ESP_LOGI(TAG, "[4.1] Listening event from all elements of pipeline");
    //监听管道事件
    audio_pipeline_set_listener(pipeline, evt);

    ESP_LOGI(TAG, "[4.2] Listening event from peripherals");
    //设置外设监听事件
    audio_event_iface_set_listener(esp_periph_set_get_event_iface(set), evt);
    ···
    while (1) {
        //获取事件消息，如果事件定义过了，就去读取事件消息
        audio_event_iface_msg_t msg;
        esp_err_t ret = audio_event_iface_listen(evt, &msg, portMAX_DELAY);
        if (ret != ESP_OK) {
            continue;
        }
        ···
    }
    ···  
}

4.5 启动音频管道

启动音频管道。调用 audio_pipeline_run() 这个函数后，就会为管道中的所有Elements创建Tasks。

void app_main(void)
{
    ···
    ESP_LOGW(TAG, "[ 5 ] Tap touch buttons to control music player:");
    ESP_LOGW(TAG, "      [Play] to start, pause and resume, [Set] to stop.");
    ESP_LOGW(TAG, "      [Vol-] or [Vol+] to adjust volume.");

    ESP_LOGI(TAG, "[ 5.1 ] Start audio_pipeline");
    set_next_file_marker();
    //运行管道
    audio_pipeline_run(pipeline);
    ···
}

4.6 关闭音频管道

void app_main(void)
{
    ···
    ESP_LOGI(TAG, "[ 6 ] Stop audio_pipeline");
    //停止所有链接的元素
    audio_pipeline_stop(pipeline);
    audio_pipeline_wait_for_stop(pipeline);
    //停止音频管道
    audio_pipeline_terminate(pipeline);
    //注销元素
    audio_pipeline_unregister(pipeline, mp3_decoder);
    audio_pipeline_unregister(pipeline, i2s_stream_writer);

    //移除监听
    /* Terminate the pipeline before removing the listener */
    audio_pipeline_remove_listener(pipeline);

    /* Make sure audio_pipeline_remove_listener is called before destroying event_iface */
    //打断事件
    audio_event_iface_destroy(evt);
    /* Release all resources */
    //释放所有资源
    audio_pipeline_deinit(pipeline);
    audio_element_deinit(i2s_stream_writer);
    audio_element_deinit(mp3_decoder);
}

4.7 主循环

void app_main(void)
{
    ···
    /*
    主循环有三个判断:
    判断1：判断事件接口是否定义成功，若成功，ret应当有效。
    判断2：判断当前是否处于解码阶段，获取解码器相关信息，并显示，然后设置i2s数据流相关参数。
    判断3：判断是否处于i2s数据流阶段，并且data已停止。退出循环。
    */
    while (1) {
        //获取事件消息，如果事件定义过了，就去读取事件消息
        audio_event_iface_msg_t msg;
        esp_err_t ret = audio_event_iface_listen(evt, &msg, portMAX_DELAY);
        if (ret != ESP_OK) {
            continue;
        }
        
        //获取MP3解码器的的消息指针，并在其后显示相关信息
        if (msg.source_type == AUDIO_ELEMENT_TYPE_ELEMENT && msg.source == (void *) mp3_decoder
            && msg.cmd == AEL_MSG_CMD_REPORT_MUSIC_INFO) {
            audio_element_info_t music_info = {0};
            audio_element_getinfo(mp3_decoder, &music_info);
            ESP_LOGI(TAG, "[ * ] Receive music info from mp3 decoder, sample_rates=%d, bits=%d, ch=%d",
                     music_info.sample_rates, music_info.bits, music_info.channels);
            //根据上面读取到的信息，设置i2s流
            audio_element_setinfo(i2s_stream_writer, &music_info);
            //设置i2s流相关参数
            i2s_stream_set_clk(i2s_stream_writer, music_info.sample_rates, music_info.bits, music_info.channels);
            continue;
        }

        if ((msg.source_type == PERIPH_ID_TOUCH || msg.source_type == PERIPH_ID_BUTTON || msg.source_type == PERIPH_ID_ADC_BTN)
            && (msg.cmd == PERIPH_TOUCH_TAP || msg.cmd == PERIPH_BUTTON_PRESSED || msg.cmd == PERIPH_ADC_BUTTON_PRESSED)) {
            if ((int) msg.data == get_input_play_id()) {
                ESP_LOGI(TAG, "[ * ] [Play] touch tap event");
                audio_element_state_t el_state = audio_element_get_state(i2s_stream_writer);
                switch (el_state) {
                    case AEL_STATE_INIT :
                        ESP_LOGI(TAG, "[ * ] Starting audio pipeline");
                        audio_pipeline_run(pipeline);
                        break;
                    case AEL_STATE_RUNNING :
                        ESP_LOGI(TAG, "[ * ] Pausing audio pipeline");
                        audio_pipeline_pause(pipeline);
                        break;
                    case AEL_STATE_PAUSED :
                        ESP_LOGI(TAG, "[ * ] Resuming audio pipeline");
                        audio_pipeline_resume(pipeline);
                        break;
                    case AEL_STATE_FINISHED :
                        ESP_LOGI(TAG, "[ * ] Rewinding audio pipeline");
                        audio_pipeline_reset_ringbuffer(pipeline);
                        audio_pipeline_reset_elements(pipeline);
                        audio_pipeline_change_state(pipeline, AEL_STATE_INIT);
                        set_next_file_marker();
                        audio_pipeline_run(pipeline);
                        break;
                    default :
                        ESP_LOGI(TAG, "[ * ] Not supported state %d", el_state);
                }
            } else if ((int) msg.data == get_input_set_id()) {
                ESP_LOGI(TAG, "[ * ] [Set] touch tap event");
                ESP_LOGI(TAG, "[ * ] Stopping audio pipeline");
                break;
            } else if ((int) msg.data == get_input_mode_id()) {
                ESP_LOGI(TAG, "[ * ] [mode] tap event");
                audio_pipeline_stop(pipeline);
                audio_pipeline_wait_for_stop(pipeline);
                audio_pipeline_terminate(pipeline);
                audio_pipeline_reset_ringbuffer(pipeline);
                audio_pipeline_reset_elements(pipeline);
                set_next_file_marker();
                audio_pipeline_run(pipeline);
            } else if ((int) msg.data == get_input_volup_id()) {
                ESP_LOGI(TAG, "[ * ] [Vol+] touch tap event");
                player_volume += 10;
                if (player_volume > 100) {
                    player_volume = 100;
                }
                audio_hal_set_volume(board_handle->audio_hal, player_volume);
                ESP_LOGI(TAG, "[ * ] Volume set to %d %%", player_volume);
            } else if ((int) msg.data == get_input_voldown_id()) {
                ESP_LOGI(TAG, "[ * ] [Vol-] touch tap event");
                player_volume -= 10;
                if (player_volume < 0) {
                    player_volume = 0;
                }
                audio_hal_set_volume(board_handle->audio_hal, player_volume);
                ESP_LOGI(TAG, "[ * ] Volume set to %d %%", player_volume);
            }
        }
    }
    ···
}

4.8 实例中mp3文件处理

/*
   To embed it in the app binary, the mp3 file is named
   in the component.mk COMPONENT_EMBED_TXTFILES variable.
*/
extern const uint8_t adf_music_mp3_start[] asm("_binary_adf_music_mp3_start");
extern const uint8_t adf_music_mp3_end[]   asm("_binary_adf_music_mp3_end");

---

• 由 Leung 写于 2021 年 7 月 24 日

• 参考：从play_mp3例程出发理解ESP32-ADF的使用方法
　　　　ESP32开发（2）esp-adf：play_mp3例程简单分析
　　　　esp32~mp3播放实例解析