Audio Pipeline

Dynamic combination of a group of linked Elements is done using the Audio Pipeline. You do not deal with the individual elements but with just one audio pipeline. Every element is connected by a ringbuffer. The Audio Pipeline also takes care of forwarding messages from the element tasks to an application.

A diagram below presents organization of three elements, HTTP reader stream, MP3 decoder and I2S writer stream, in the Audio Pipeline, that has been used in player/pipeline_http_mp3 example.

Sample Organization of Elements in Audio Pipeline

API Reference

Header File

Functions

audio_pipeline_handle_t audio_pipeline_init(audio_pipeline_cfg_t *config)

Initialize audio_pipeline_handle_t object audio_pipeline is responsible for controlling the audio data stream and connecting the audio elements with the ringbuffer It will connect and start the audio element in order, responsible for retrieving the data from the previous element and passing it to the element after it. Also get events from each element, process events or pass it to a higher layer.

Return

  • audio_pipeline_handle_t on success

  • NULL when any errors

Parameters

  • config: The configuration - audio_pipeline_cfg_t

esp_err_t audio_pipeline_deinit(audio_pipeline_handle_t pipeline)

This function removes all of the element’s links in audio_pipeline, cancels the registration of all events, invokes the destroy functions of the registered elements, and frees the memory allocated by the init function. Briefly, frees all memory.

Return

ESP_OK

Parameters

  • [in] pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_register(audio_pipeline_handle_t pipeline, audio_element_handle_t el, const char *name)

Registering an element for audio_pipeline, each element can be registered multiple times, but name (as String) must be unique in audio_pipeline, which is used to identify the element for link creation mentioned in the audio_pipeline_link

Note

Because of stop pipeline or pause pipeline depend much on register order. Please register element strictly in the following order: input element first, process middle, output element last.

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

  • [in] el: The Audio Element Handle

  • [in] name: The name identifier of the audio_element in this audio_pipeline

esp_err_t audio_pipeline_unregister(audio_pipeline_handle_t pipeline, audio_element_handle_t el)

Unregister the audio_element in audio_pipeline, remove it from the list.

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

  • [in] el: The Audio Element Handle

esp_err_t audio_pipeline_run(audio_pipeline_handle_t pipeline)

Start Audio Pipeline. 

      With this function audio_pipeline will create tasks for all elements,
      that have been linked using the linking functions.

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_terminate(audio_pipeline_handle_t pipeline)

Stop Audio Pipeline. 

      With this function audio_pipeline will destroy tasks of all elements,
      that have been linked using the linking functions.

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_terminate_with_ticks(audio_pipeline_handle_t pipeline, TickType_t ticks_to_wait)

Stop Audio Pipeline with specific ticks for timeout. 

      With this function audio_pipeline will destroy tasks of all elements,
      that have been linked using the linking functions.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] pipeline: The Audio Pipeline Handle

  • [in] ticks_to_wait: The maximum amount of time to block wait for element destroy

esp_err_t audio_pipeline_resume(audio_pipeline_handle_t pipeline)

This function will set all the elements to the RUNNING state and process the audio data as an inherent feature of audio_pipeline.

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_pause(audio_pipeline_handle_t pipeline)

This function will set all the elements to the PAUSED state. Everything remains the same except the data processing is stopped.

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_stop(audio_pipeline_handle_t pipeline)

Stop all of the linked elements. Used with audio_pipeline_wait_for_stop to keep in sync. The link state of the elements in the pipeline is kept, events are still registered. The stopped audio_pipeline restart by audio_pipeline_resume.

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_wait_for_stop(audio_pipeline_handle_t pipeline)

The audio_pipeline_stop function sends requests to the elements and exits. But they need time to get rid of time-blocking tasks. This function will wait portMAX_DELAY until all the Elements in the pipeline actually stop.

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_wait_for_stop_with_ticks(audio_pipeline_handle_t pipeline, TickType_t ticks_to_wait)

The audio_pipeline_stop function sends requests to the elements and exits. But they need time to get rid of time-blocking tasks. This function will wait ticks_to_wait until all the Elements in the pipeline actually stop.

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

  • [in] ticks_to_wait: The maximum amount of time to block wait for stop

esp_err_t audio_pipeline_link(audio_pipeline_handle_t pipeline, const char *link_tag[], int link_num)

The audio_element added to audio_pipeline will be unconnected before it is called by this function. Based on element’s name already registered by audio_pipeline_register, the path of the data will be linked in the order of the link_tag. Element at index 0 is first, and index link_num -1 is final. As well as audio_pipeline will subscribe all element’s events.

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

  • link_tag: Array of element name was registered by audio_pipeline_register

  • [in] link_num: Total number of elements of the link_tag array

esp_err_t audio_pipeline_unlink(audio_pipeline_handle_t pipeline)

Removes the connection of the elements, as well as unsubscribe events.

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

audio_element_handle_t audio_pipeline_get_el_by_tag(audio_pipeline_handle_t pipeline, const char *tag)

Find un-kept element from registered pipeline by tag.

Return

  • NULL when any errors

  • Others on success

Parameters

  • [in] pipeline: The Audio Pipeline Handle

  • [in] tag: A char pointer

audio_element_handle_t audio_pipeline_get_el_once(audio_pipeline_handle_t pipeline, const audio_element_handle_t start_el, const char *tag)

Based on beginning element to find un-kept element from registered pipeline by tag.

Return

  • NULL when any errors

  • Others on success

Parameters

  • [in] pipeline: The Audio Pipeline Handle

  • [in] start_el: Specific beginning element

  • [in] tag: A char pointer

esp_err_t audio_pipeline_remove_listener(audio_pipeline_handle_t pipeline)

Remove event listener from this audio_pipeline.

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_set_listener(audio_pipeline_handle_t pipeline, audio_event_iface_handle_t evt)

Set event listner for this audio_pipeline, any event from this pipeline can be listen to by evt

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

  • [in] evt: The Event Handle

audio_event_iface_handle_t audio_pipeline_get_event_iface(audio_pipeline_handle_t pipeline)

Get the event iface using by this pipeline.

Return

The Event Handle

Parameters

  • [in] pipeline: The pipeline

esp_err_t audio_pipeline_link_insert(audio_pipeline_handle_t pipeline, bool first, audio_element_handle_t prev, ringbuf_handle_t conect_rb, audio_element_handle_t next)

Insert the specific audio_element to audio_pipeline, previous element connect to the next element by ring buffer.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] pipeline: The audio pipeline handle

  • [in] first: Previous element is first input element, need to set true

  • [in] prev: Previous element

  • [in] conect_rb: Connect ring buffer

  • [in] next: Next element

esp_err_t audio_pipeline_register_more(audio_pipeline_handle_t pipeline, audio_element_handle_t element_1, ...)

Register a NULL-terminated list of elements to audio_pipeline.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] pipeline: The audio pipeline handle

  • [in] element_1: The element to add to the audio_pipeline.

  • [in] ...: Additional elements to add to the audio_pipeline.

esp_err_t audio_pipeline_unregister_more(audio_pipeline_handle_t pipeline, audio_element_handle_t element_1, ...)

Unregister a NULL-terminated list of elements to audio_pipeline.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] pipeline: The audio pipeline handle

  • [in] element_1: The element to add to the audio_pipeline.

  • [in] ...: Additional elements to add to the audio_pipeline.

esp_err_t audio_pipeline_link_more(audio_pipeline_handle_t pipeline, audio_element_handle_t element_1, ...)

Adds a NULL-terminated list of elements to audio_pipeline.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] pipeline: The audio pipeline handle

  • [in] element_1: The element to add to the audio_pipeline.

  • [in] ...: Additional elements to add to the audio_pipeline.

esp_err_t audio_pipeline_listen_more(audio_pipeline_handle_t pipeline, audio_element_handle_t element_1, ...)

Subscribe a NULL-terminated list of element’s events to audio_pipeline.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] pipeline: The audio pipeline handle

  • [in] element_1: The element event to subscribe to the audio_pipeline.

  • [in] ...: Additional elements event to subscribe to the audio_pipeline.

esp_err_t audio_pipeline_check_items_state(audio_pipeline_handle_t pipeline, audio_element_handle_t dest_el, audio_element_status_t status)

Update the destination element state and check the all of linked elements state are same.

Return

  • ESP_OK All linked elements state are same.

  • ESP_FAIL All linked elements state are not same.

Parameters

  • [in] pipeline: The audio pipeline handle

  • [in] dest_el: Destination element

  • [in] status: The new status

esp_err_t audio_pipeline_reset_items_state(audio_pipeline_handle_t pipeline)

Reset pipeline element items state to AEL_STATUS_NONE

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_reset_ringbuffer(audio_pipeline_handle_t pipeline)

Reset pipeline element ringbuffer.

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_reset_elements(audio_pipeline_handle_t pipeline)

Reset Pipeline linked elements state.

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_reset_kept_state(audio_pipeline_handle_t pipeline, audio_element_handle_t el)

Reset the specific element kept state.

Return

  • ESP_OK on success

  • ESP_FAIL when any errors

Parameters

  • [in] pipeline: The Audio Pipeline Handle

  • [in] el: The Audio element Handle

esp_err_t audio_pipeline_breakup_elements(audio_pipeline_handle_t pipeline, audio_element_handle_t kept_ctx_el)

Break up all the linked elements of specific pipeline. The include and before kept_ctx_el working (AEL_STATE_RUNNING or AEL_STATE_PAUSED) elements and connected ringbuffer will be reserved.

Note

There is no element reserved when kept_ctx_el is NULL. This function will unsubscribe all element’s events.

Return

  • ESP_OK All linked elements state are same.

  • ESP_ERR_INVALID_ARG Invalid parameters.

Parameters

  • [in] pipeline: The audio pipeline handle

  • [in] kept_ctx_el: Destination keep elements

esp_err_t audio_pipeline_relink(audio_pipeline_handle_t pipeline, const char *link_tag[], int link_num)

Basing on element’s name already registered by audio_pipeline_register, relink the pipeline following the order of names in the `link_tag.

Note

If the ringbuffer is not enough to connect the new pipeline will create new ringbuffer.

Return

  • ESP_OK All linked elements state are same.

  • ESP_FAIL Error.

  • ESP_ERR_INVALID_ARG Invalid parameters.

Parameters

  • [in] pipeline: The Audio Pipeline Handle

  • link_tag: Array of elements name that was registered by audio_pipeline_register

  • [in] link_num: Total number of elements of the link_tag array

esp_err_t audio_pipeline_relink_more(audio_pipeline_handle_t pipeline, audio_element_handle_t element_1, ...)

Adds a NULL-terminated list of elements to audio_pipeline.

Note

If the ringbuffer is not enough to connect the new pipeline will create new ringbuffer.

Return

  • ESP_OK All linked elements state are same.

  • ESP_FAIL Error.

  • ESP_ERR_INVALID_ARG Invalid parameters.

Parameters

  • [in] pipeline: The Audio Pipeline Handle

  • [in] element_1: The element to add to the audio_pipeline.

  • [in] ...: Additional elements to add to the audio_pipeline.

esp_err_t audio_pipeline_change_state(audio_pipeline_handle_t pipeline, audio_element_state_t new_state)

Set the pipeline state.

Return

  • ESP_OK All linked elements state are same.

  • ESP_FAIL Error.

Parameters

  • [in] pipeline: The Audio Pipeline Handle

  • [in] new_state: The new state will be set

Structures

struct audio_pipeline_cfg

Audio Pipeline configurations.

Public Members

int rb_size

Audio Pipeline ringbuffer size

Macros

DEFAULT_PIPELINE_RINGBUF_SIZE
DEFAULT_AUDIO_PIPELINE_CONFIG()

Type Definitions

typedef struct audio_pipeline *audio_pipeline_handle_t
typedef struct audio_pipeline_cfg audio_pipeline_cfg_t

Audio Pipeline configurations.

Provide feedback about this document