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

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
  • 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

Return
  • ESP_OK on success
  • ESP_FAIL when any errors
Parameters
  • pipeline: The Audio Pipeline Handle
  • el: The Audio Element Handle
  • 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
  • pipeline: The Audio Pipeline Handle
  • 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
  • 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
  • pipeline: The Audio Pipeline Handle

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
  • 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
  • pipeline: The Audio Pipeline Handle

esp_err_t audio_pipeline_stop(audio_pipeline_handle_t pipeline)

Stop all elements and clear information of items. Free up memory for all task items. The link state of the elements in the pipeline is kept, events are still registered, but the audio_pipeline_pause and audio_pipeline_resume functions have no effect. To restart audio_pipeline, use the audio_pipeline_resume function.

Return
  • ESP_OK on success
  • ESP_FAIL when any errors
Parameters
  • 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 until all the Elements in the pipeline actually stop.

Return
  • ESP_OK on success
  • ESP_FAIL when any errors
Parameters
  • pipeline: The Audio Pipeline Handle

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
  • pipeline: The Audio Pipeline Handle
  • link_tag: Array of element name was registered by audio_pipeline_register
  • 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
  • pipeline: The Audio Pipeline Handle

audio_element_handle_t audio_pipeline_get_el_by_tag(audio_pipeline_handle_t pipeline, const char *tag)

Find element from registered pipeline by tag.

Return
  • NULL when any errors
  • Others on success
Parameters
  • pipeline: The Audio Pipeline Handle
  • 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
  • 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
  • pipeline: The Audio Pipeline Handle
  • 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
  • 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
  • pipeline: The audio pipeline handle
  • first: Previous element is first input element, need to set true
  • prev: Previous element
  • conect_rb: Connect ring buffer
  • 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
  • pipeline: The audio pipeline handle
  • element_1: The element to add to the audio_pipeline.
  • ...: 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
  • pipeline: The audio pipeline handle
  • element_1: The element to add to the audio_pipeline.
  • ...: 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
  • pipeline: The audio pipeline handle
  • element_1: The element to add to the audio_pipeline.
  • ...: 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
  • pipeline: The audio pipeline handle
  • element_1: The element event to subscribe to the audio_pipeline.
  • ...: 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
  • pipeline: The audio pipeline handle
  • dest_el: Destination element
  • 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
  • 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
  • pipeline: The Audio Pipeline 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 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
  • pipeline: The audio pipeline handle
  • 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
  • pipeline: The Audio Pipeline Handle
  • link_tag: Array of elements name that was registered by audio_pipeline_register
  • link_num: Total number of elements of the link_tag array

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.