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.
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.
- 参数
config – The configuration - audio_pipeline_cfg_t
- 返回
audio_pipeline_handle_t on success
NULL when any errors
-
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.
- 参数
pipeline – [in] The Audio Pipeline Handle
- 返回
ESP_OK
-
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 theaudio_pipeline_link
备注
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.
- 参数
pipeline – [in] The Audio Pipeline Handle
el – [in] The Audio Element Handle
name – [in] The name identifier of the audio_element in this audio_pipeline
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
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.
- 参数
pipeline – [in] The Audio Pipeline Handle
el – [in] The Audio Element Handle
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
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.
- 参数
pipeline – [in] The Audio Pipeline Handle
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
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.
- 参数
pipeline – [in] The Audio Pipeline Handle
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
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.
- 参数
pipeline – [in] The Audio Pipeline Handle
ticks_to_wait – [in] The maximum amount of time to block wait for element destroy
- 返回
ESP_OK
ESP_FAIL
-
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.- 参数
pipeline – [in] The Audio Pipeline Handle
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
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.- 参数
pipeline – [in] The Audio Pipeline Handle
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
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 byaudio_pipeline_resume
.- 参数
pipeline – [in] The Audio Pipeline Handle
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
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 waitportMAX_DELAY
until all the Elements in the pipeline actually stop.- 参数
pipeline – [in] The Audio Pipeline Handle
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
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 waitticks_to_wait
until all the Elements in the pipeline actually stop.- 参数
pipeline – [in] The Audio Pipeline Handle
ticks_to_wait – [in] The maximum amount of time to block wait for stop
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
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 byaudio_pipeline_register
, the path of the data will be linked in the order of the link_tag. Element at index 0 is first, and indexlink_num -1
is final. As well as audio_pipeline will subscribe all element’s events.- 参数
pipeline – [in] The Audio Pipeline Handle
link_tag – Array of element
name
was registered byaudio_pipeline_register
link_num – [in] Total number of elements of the
link_tag
array
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
esp_err_t audio_pipeline_unlink(audio_pipeline_handle_t pipeline)
Removes the connection of the elements, as well as unsubscribe events.
- 参数
pipeline – [in] The Audio Pipeline Handle
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
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.
- 参数
pipeline – [in] The Audio Pipeline Handle
tag – [in] A char pointer
- 返回
NULL when any errors
Others on success
-
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.
- 参数
pipeline – [in] The Audio Pipeline Handle
start_el – [in] Specific beginning element
tag – [in] A char pointer
- 返回
NULL when any errors
Others on success
-
esp_err_t audio_pipeline_remove_listener(audio_pipeline_handle_t pipeline)
Remove event listener from this audio_pipeline.
- 参数
pipeline – [in] The Audio Pipeline Handle
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
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
- 参数
pipeline – [in] The Audio Pipeline Handle
evt – [in] The Event Handle
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
audio_event_iface_handle_t audio_pipeline_get_event_iface(audio_pipeline_handle_t pipeline)
Get the event iface using by this pipeline.
- 参数
pipeline – [in] The pipeline
- 返回
The Event Handle
-
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.
- 参数
pipeline – [in] The audio pipeline handle
first – [in] Previous element is first input element, need to set
true
prev – [in] Previous element
conect_rb – [in] Connect ring buffer
next – [in] Next element
- 返回
ESP_OK
ESP_FAIL
-
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.
- 参数
pipeline – [in] The audio pipeline handle
element_1 – [in] The element to add to the audio_pipeline.
... – [in] Additional elements to add to the audio_pipeline.
- 返回
ESP_OK
ESP_FAIL
-
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.
- 参数
pipeline – [in] The audio pipeline handle
element_1 – [in] The element to add to the audio_pipeline.
... – [in] Additional elements to add to the audio_pipeline.
- 返回
ESP_OK
ESP_FAIL
-
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.
- 参数
pipeline – [in] The audio pipeline handle
element_1 – [in] The element to add to the audio_pipeline.
... – [in] Additional elements to add to the audio_pipeline.
- 返回
ESP_OK
ESP_FAIL
-
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.
- 参数
pipeline – [in] The audio pipeline handle
element_1 – [in] The element event to subscribe to the audio_pipeline.
... – [in] Additional elements event to subscribe to the audio_pipeline.
- 返回
ESP_OK
ESP_FAIL
-
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.
- 参数
pipeline – [in] The audio pipeline handle
dest_el – [in] Destination element
status – [in] The new status
- 返回
ESP_OK All linked elements state are same.
ESP_FAIL All linked elements state are not same.
-
esp_err_t audio_pipeline_reset_items_state(audio_pipeline_handle_t pipeline)
Reset pipeline element items state to
AEL_STATUS_NONE
- 参数
pipeline – [in] The Audio Pipeline Handle
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
esp_err_t audio_pipeline_reset_ringbuffer(audio_pipeline_handle_t pipeline)
Reset pipeline element ringbuffer.
- 参数
pipeline – [in] The Audio Pipeline Handle
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
esp_err_t audio_pipeline_reset_elements(audio_pipeline_handle_t pipeline)
Reset Pipeline linked elements state.
- 参数
pipeline – [in] The Audio Pipeline Handle
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
esp_err_t audio_pipeline_reset_kept_state(audio_pipeline_handle_t pipeline, audio_element_handle_t el)
Reset the specific element kept state.
- 参数
pipeline – [in] The Audio Pipeline Handle
el – [in] The Audio element Handle
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
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 beforekept_ctx_el
working (AEL_STATE_RUNNING or AEL_STATE_PAUSED) elements and connected ringbuffer will be reserved.备注
There is no element reserved when
kept_ctx_el
is NULL. This function will unsubscribe all element’s events.- 参数
pipeline – [in] The audio pipeline handle
kept_ctx_el – [in] Destination keep elements
- 返回
ESP_OK All linked elements state are same.
ESP_ERR_INVALID_ARG Invalid parameters.
-
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 byaudio_pipeline_register
, relink the pipeline following the order ofnames
in the `link_tag.备注
If the ringbuffer is not enough to connect the new pipeline will create new ringbuffer.
- 参数
pipeline – [in] The Audio Pipeline Handle
link_tag – Array of elements
name
that was registered byaudio_pipeline_register
link_num – [in] Total number of elements of the
link_tag
array
- 返回
ESP_OK All linked elements state are same.
ESP_FAIL Error.
ESP_ERR_INVALID_ARG Invalid parameters.
-
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.
备注
If the ringbuffer is not enough to connect the new pipeline will create new ringbuffer.
- 参数
pipeline – [in] The Audio Pipeline Handle
element_1 – [in] The element to add to the audio_pipeline.
... – [in] Additional elements to add to the audio_pipeline.
- 返回
ESP_OK All linked elements state are same.
ESP_FAIL Error.
ESP_ERR_INVALID_ARG Invalid parameters.
-
esp_err_t audio_pipeline_change_state(audio_pipeline_handle_t pipeline, audio_element_state_t new_state)
Set the pipeline state.
- 参数
pipeline – [in] The Audio Pipeline Handle
new_state – [in] The new state will be set
- 返回
ESP_OK All linked elements state are same.
ESP_FAIL Error.
Structures
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.