Audio Element

The basic building block for the application programmer developing with ADF is the audio_element object. Every decoder, encoder, filter, input stream, or output stream is in fact an Audio Element.

This API has been designed and then used to implement Audio Elements provided by ADF.

The general functionality of an Element is to take some data on input, processes it, and output to a the next. Each Element is run as a separate task. To enable control on particular stages of the data lifecycle from the input, during processing and up to the output, the audio_element object provides possibility to trigger callbacks per stage. There are seven types of available callback functions: open, seek, process, close, destroy, read and write, and they are defined in audio_element_cfg_t. Particular Elements typically use a subset of all avialable callbacks. For instance the MP3 Decoder is using open, process, close and destroy callback functions.

The available Audio Element types intended for development with this API are listed in description of audio_common.h header file under audio_element_type_t enumerator.

API Reference

Functions

audio_element_handle_t audio_element_init(audio_element_cfg_t *config)

Initialize audio element with config.

Return
  • audio_elemenent handle object
  • NULL
Parameters
  • config: The configuration

esp_err_t audio_element_deinit(audio_element_handle_t el)

Destroy audio element handle object, stop, clear, deletel all.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

esp_err_t audio_element_setdata(audio_element_handle_t el, void *data)

Set context data to element handle object. It can be retrieved by calling audio_element_getdata.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • data: The data pointer

void *audio_element_getdata(audio_element_handle_t el)

Get context data from element handle object.

Return
data pointer
Parameters
  • el: The audio element handle

esp_err_t audio_element_set_tag(audio_element_handle_t el, const char *tag)

Set elemenet tag name, or clear if tag = NULL.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • tag: The tag name pointer

char *audio_element_get_tag(audio_element_handle_t el)

Get element tag name.

Return
Element tag name pointer
Parameters
  • el: The audio element handle

esp_err_t audio_element_setinfo(audio_element_handle_t el, audio_element_info_t *info)

Set audio element infomation.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • info: The information pointer

esp_err_t audio_element_getinfo(audio_element_handle_t el, audio_element_info_t *info)

Get audio element infomation.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • info: The information pointer

esp_err_t audio_element_set_uri(audio_element_handle_t el, const char *uri)

Set audio element URI.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • uri: The uri pointer

char *audio_element_get_uri(audio_element_handle_t el)

Get audio element URI.

Return
URI pointer
Parameters
  • el: The audio element handle

esp_err_t audio_element_run(audio_element_handle_t el)

Start Audio Element. With this function, audio_element will start as freeRTOS task, and put the task into ‘PAUSED’ state. Note: Element does not actually start when this function returns.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

esp_err_t audio_element_terminate(audio_element_handle_t el)

Terminate Audio Element. With this function, audio_element will exit the task function. Note: this API only sends request. It does not actually terminate immediately when this function returns.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

esp_err_t audio_element_stop(audio_element_handle_t el)

Request stop of the Audio Element. After receiving the stop request, the element will ignore the actions being performed (read/write, wait for the ringbuffer …) and close the task, reset the state variables. Note: this API only sends requests, Element does not actually stop when this function returns.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

esp_err_t audio_element_wait_for_stop(audio_element_handle_t el)

After the audio_element_stop function is called, the Element task will perform some abort procedures. This function will be blocked (Time is DEFAULT_MAX_WAIT_TIME) until Element Task has done and exit.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

esp_err_t audio_element_wait_for_stop_ms(audio_element_handle_t el, TickType_t ticks_to_wait)

After the audio_element_stop function is called, the Element task will perform some abort procedures. The maximum amount of time should block waiting for Element task has stopped.

Return
  • ESP_OK, Success
  • ESP_FAIL, Timeout
Parameters
  • el: The audio element handle
  • ticks_to_wait: The maximum amount of time to wait for stop

esp_err_t audio_element_pause(audio_element_handle_t el)

Request audio Element enter ‘PAUSE’ state. In this state, the task will wait for any event.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

esp_err_t audio_element_resume(audio_element_handle_t el, float wait_for_rb_threshold, TickType_t timeout)

Request audio Element enter ‘RUNNING’ state. In this state, the task listens to events and invokes the callback functions. At the same time it will wait until the size/total_size of the output ringbuffer is greater than or equal to wait_for_rb_threshold. If the timeout period has been exceeded and ringbuffer output has not yet reached wait_for_rb_threshold then the function will return.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • wait_for_rb_threshold: The wait for rb threshold (0 .. 1)
  • timeout: The timeout

esp_err_t audio_element_msg_set_listener(audio_element_handle_t el, audio_event_iface_handle_t listener)

This function will add a listener to listen to all events from audio element el. Any event from el->external_event will be send to the listener.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • listener: The event will be listen to

esp_err_t audio_element_set_event_callback(audio_element_handle_t el, event_cb_func cb_func, void *ctx)

This function will add a callback to be called from audio element el. Any event to caller will cause to call callback function.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • cb_func: The callback function
  • ctx: Caller context

esp_err_t audio_element_msg_remove_listener(audio_element_handle_t el, audio_event_iface_handle_t listener)

Remove listener out of el. No new events will be sent to the listener.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • listener: The listener

esp_err_t audio_element_set_input_ringbuf(audio_element_handle_t el, ringbuf_handle_t rb)

Set Element input ringbuffer.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • rb: The ringbuffer handle

ringbuf_handle_t audio_element_get_input_ringbuf(audio_element_handle_t el)

Get Element input ringbuffer.

Return
ringbuf_handle_t
Parameters
  • el: The audio element handle

esp_err_t audio_element_set_output_ringbuf(audio_element_handle_t el, ringbuf_handle_t rb)

Set Element output ringbuffer.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • rb: The ringbuffer handle

ringbuf_handle_t audio_element_get_output_ringbuf(audio_element_handle_t el)

Get Element output ringbuffer.

Return
ringbuf_handle_t
Parameters
  • el: The audio element handle

audio_element_state_t audio_element_get_state(audio_element_handle_t el)

Get current Element state.

Return
audio_element_state_t
Parameters
  • el: The audio element handle

esp_err_t audio_element_abort_input_ringbuf(audio_element_handle_t el)

If the element is requesting data from the input ringbuffer, this function forces it to abort.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

esp_err_t audio_element_abort_output_ringbuf(audio_element_handle_t el)

If the element is waiting to write data to the ringbuffer output, this function forces it to abort.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

esp_err_t audio_element_wait_for_buffer(audio_element_handle_t el, int size_expect, TickType_t timeout)

This function will wait until the sizeof the output ringbuffer is greater than or equal to size_expect. If the timeout period has been exceeded and ringbuffer output has not yet reached size_expect then the function will return ESP_FAIL

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • size_expect: The size expect
  • timeout: The timeout

esp_err_t audio_element_report_status(audio_element_handle_t el, audio_element_status_t status)

Element will sendout event (status) to event by this function.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • status: The status

esp_err_t audio_element_report_info(audio_element_handle_t el)

Element will sendout event (information) to event by this function.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

esp_err_t audio_element_report_codec_fmt(audio_element_handle_t el)

Element will sendout event (codec format) to event by this function.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

esp_err_t audio_element_report_pos(audio_element_handle_t el)

Element will sendout event with a duplicate information by this function.

Return
  • ESP_OK
  • ESP_FAIL
  • ESP_ERR_NO_MEM
Parameters
  • el: The audio element handle

esp_err_t audio_element_set_input_timeout(audio_element_handle_t el, TickType_t timeout)

Set input read timeout (default is portMAX_DELAY).

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • timeout: The timeout

esp_err_t audio_element_set_output_timeout(audio_element_handle_t el, TickType_t timeout)

Set output read timeout (default is portMAX_DELAY).

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • timeout: The timeout

esp_err_t audio_element_reset_input_ringbuf(audio_element_handle_t el)

Reset inputbuffer.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

esp_err_t audio_element_finish_state(audio_element_handle_t el)

Set element finish state.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

esp_err_t audio_element_change_cmd(audio_element_handle_t el, audio_element_msg_cmd_t cmd)

Change element running state with specific command.

Return
  • ESP_OK
  • ESP_FAIL
  • ESP_ERR_INVALID_ARG Element handle is null
Parameters
  • el: The audio element handle
  • cmd: Specific command from audio_element_msg_cmd_t

esp_err_t audio_element_reset_output_ringbuf(audio_element_handle_t el)

Reset outputbuffer.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

audio_element_err_t audio_element_input(audio_element_handle_t el, char *buffer, int wanted_size)

Call this function to provice Element input data. Depending on setup using ringbuffer or function callback, Element invokes read ringbuffer, or calls read callback funtion.

Return
  • > 0 number of bytes produced
  • <=0 audio_element_err_t
Parameters
  • el: The audio element handle
  • buffer: The buffer pointer
  • wanted_size: The wanted size

audio_element_err_t audio_element_output(audio_element_handle_t el, char *buffer, int write_size)

Call this function to sendout Element output data. Depending on setup using ringbuffer or function callback, Element will invoke write to ringbuffer, or call write callback funtion.

Return
  • > 0 number of bytes written
  • <=0 audio_element_err_t
Parameters
  • el: The audio element handle
  • buffer: The buffer pointer
  • write_size: The write size

esp_err_t audio_element_set_read_cb(audio_element_handle_t el, stream_func fn, void *context)

This API allows the application to set a read callback for the first audio_element in the pipeline for allowing the pipeline to interface with other systems. The callback is invoked every time the audio element requires data to be processed.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • fn: Callback read function. The callback function should return number of bytes read or -1 in case of error in reading. Note that the callback function may decide to block and that may block the entire pipeline.
  • context: An optional context which will be passed to callback function on every invocation

esp_err_t audio_element_set_write_cb(audio_element_handle_t el, stream_func fn, void *context)

This API allows the application to set a write callback for the last audio_element in the pipeline for allowing the pipeline to interface with other systems. The callback is invoked every time the audio element has a processed data that needs to be passed forward.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element
  • fn: Callback write function The callback function should return number of bytes written or -1 in case of error in writing. Note that the callback function may decide to block and that may block the entire pipeline.
  • context: An optional context which will be passed to callback function on every invocation

QueueHandle_t audio_element_get_event_queue(audio_element_handle_t el)

Get External queue of Emitter. We can read any event that has been send out of Element from this QueueHandle_t.

Return
QueueHandle_t
Parameters
  • el: The audio element handle

esp_err_t audio_element_set_ringbuf_done(audio_element_handle_t el)

Set inputbuffer and outputbuffer have finished.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

esp_err_t audio_element_reset_state(audio_element_handle_t el)

Enforce ‘AEL_STATE_INIT’ state.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

int audio_element_get_output_ringbuf_size(audio_element_handle_t el)

Get Element output ringbuffer size.

Return
  • =0: Parameter NULL
  • >0: Size of ringbuffer
Parameters
  • el: The audio element handle

esp_err_t audio_element_set_output_ringbuf_size(audio_element_handle_t el, int rb_size)

Set Element output ringbuffer size.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • rb_size: Size of the ringbuffer

esp_err_t audio_element_multi_input(audio_element_handle_t el, char *buffer, int wanted_size, int index, TickType_t ticks_to_wait)

Call this function to read data from multi input ringbuffer by given index.

Return
  • ESP_OK
  • ESP_ERR_INVALID_ARG
Parameters
  • el: The audio element handle
  • buffer: The buffer pointer
  • wanted_size: The wanted size
  • index: The index of multi input ringbuffer, start from 0, should be less than NUMBER_OF_MULTI_RINGBUF
  • ticks_to_wait: Timeout of ringbuffer

esp_err_t audio_element_multi_output(audio_element_handle_t el, char *buffer, int wanted_size, TickType_t ticks_to_wait)

Call this function write data by multi output ringbuffer.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • buffer: The buffer pointer
  • wanted_size: The wanted size
  • ticks_to_wait: Timeout of ringbuffer

esp_err_t audio_element_set_multi_input_ringbuf(audio_element_handle_t el, ringbuf_handle_t rb, int index)

Set multi input ringbuffer Element.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle
  • rb: The ringbuffer handle
  • index: Index of multi ringbuffer, starts from 0, should be less than NUMBER_OF_MULTI_RINGBUF

esp_err_t audio_element_set_multi_output_ringbuf(audio_element_handle_t el, ringbuf_handle_t rb, int index)

Set multi output ringbuffer Element.

Return
  • ESP_OK
  • ESP_ERR_INVALID_ARG
Parameters
  • el: The audio element handle
  • rb: The ringbuffer handle
  • index: Index of multi ringbuffer, starts from 0, should be less than NUMBER_OF_MULTI_RINGBUF

ringbuf_handle_t audio_element_get_multi_input_ringbuf(audio_element_handle_t el, int index)

Get handle of multi input ringbuffer Element by index.

Return
  • NULL Error
  • Others ringbuf_handle_t
Parameters
  • el: The audio element handle
  • index: Index of multi ringbuffer, starts from 0, should be less than NUMBER_OF_MULTI_RINGBUF

ringbuf_handle_t audio_element_get_multi_output_ringbuf(audio_element_handle_t el, int index)

Get handle of multi output ringbuffer Element by index.

Return
  • NULL Error
  • Others ringbuf_handle_t
Parameters
  • el: The audio element handle
  • index: Index of multi ringbuffer, starts from 0, should be less than NUMBER_OF_MULTI_RINGBUF

esp_err_t audio_element_process_init(audio_element_handle_t el)

Provides a way to call element’s open

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

esp_err_t audio_element_process_deinit(audio_element_handle_t el)

Provides a way to call element’s close

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • el: The audio element handle

esp_err_t audio_element_seek(audio_element_handle_t el, void *in_data, int in_size, void *out_data, int *out_size)

Call element’s seek

Return
  • ESP_OK
  • ESP_FAIL
  • ESP_ERR_NOT_SUPPORTED
Parameters
  • el: The audio element handle
  • in_data: A pointer to in data
  • in_size: The size of the in_data
  • out_data: A pointer to the out data
  • out_size: The size of the out_data

Structures

struct audio_element_reserve_data_t

Audio Element user reserved data.

Public Members

int user_data_0

user data 0

int user_data_1

user data 1

int user_data_2

user data 2

int user_data_3

user data 3

int user_data_4

user data 4

struct audio_element_info_t

Audio Element informations.

Public Members

int sample_rates

Sample rates in Hz

int channels

Number of audio channel, mono is 1, stereo is 2

int bits

Bit wide (8, 16, 24, 32 bits)

int bps

Bit per second

int64_t byte_pos

The current position (in bytes) being processed for an element

int64_t total_bytes

The total bytes for an element

int duration

The duration for an element (optional)

char *uri

URI (optional)

audio_codec_t codec_fmt

Music format (optional)

audio_element_reserve_data_t reserve_data

This value is reserved for user use (optional)

struct audio_element_cfg_t

Audio Element configurations. Each Element at startup will be a self-running task. These tasks will execute the callback open -> [loop: read -> process -> write] -> close. These callback functions are provided by the user corresponding to this configuration.

Public Members

io_func open

Open callback function

ctrl_func seek

Seek callback function

process_func process

Process callback function

io_func close

Close callback function

io_func destroy

Destroy callback function

stream_func read

Read callback function

stream_func write

Write callback function

int buffer_len

Buffer length use for an Element

int task_stack

Element task stack

int task_prio

Element task priority (based on freeRTOS priority)

int task_core

Element task running in core (0 or 1)

int out_rb_size

Output ringbuffer size

void *data

User context

const char *tag

Element tag

int multi_in_rb_num

The number of multiple input ringbuffer

int multi_out_rb_num

The number of multiple output ringbuffer

Macros

AUDIO_ELEMENT_INFO_DEFAULT()
DEFAULT_ELEMENT_RINGBUF_SIZE
DEFAULT_ELEMENT_BUFFER_LENGTH
DEFAULT_ELEMENT_STACK_SIZE
DEFAULT_ELEMENT_TASK_PRIO
DEFAULT_ELEMENT_TASK_CORE
DEFAULT_AUDIO_ELEMENT_CONFIG()

Type Definitions

typedef struct audio_element *audio_element_handle_t
typedef esp_err_t (*io_func)(audio_element_handle_t self)
typedef audio_element_err_t (*process_func)(audio_element_handle_t self, char *el_buffer, int el_buf_len)
typedef audio_element_err_t (*stream_func)(audio_element_handle_t self, char *buffer, int len, TickType_t ticks_to_wait, void *context)
typedef esp_err_t (*event_cb_func)(audio_element_handle_t el, audio_event_iface_msg_t *event, void *ctx)
typedef esp_err_t (*ctrl_func)(audio_element_handle_t self, void *in_data, int in_size, void *out_data, int *out_size)

Enumerations

enum audio_element_err_t

Values:

AEL_IO_OK = ESP_OK
AEL_IO_FAIL = ESP_FAIL
AEL_IO_DONE = -2
AEL_IO_ABORT = -3
AEL_IO_TIMEOUT = -4
AEL_PROCESS_FAIL = -5
enum audio_element_state_t

Audio element state.

Values:

AEL_STATE_NONE = 0
AEL_STATE_INIT
AEL_STATE_RUNNING
AEL_STATE_PAUSED
AEL_STATE_STOPPED
AEL_STATE_FINISHED
AEL_STATE_ERROR
enum audio_element_msg_cmd_t

Audio element action command, process on dispatcher

Values:

AEL_MSG_CMD_NONE = 0
AEL_MSG_CMD_ERROR = 1
AEL_MSG_CMD_FINISH = 2
AEL_MSG_CMD_STOP = 3
AEL_MSG_CMD_PAUSE = 4
AEL_MSG_CMD_RESUME = 5
AEL_MSG_CMD_DESTROY = 6
AEL_MSG_CMD_REPORT_STATUS = 8
AEL_MSG_CMD_REPORT_MUSIC_INFO = 9
AEL_MSG_CMD_REPORT_CODEC_FMT = 10
AEL_MSG_CMD_REPORT_POSITION = 11
enum audio_element_status_t

Audio element status report

Values:

AEL_STATUS_NONE = 0
AEL_STATUS_ERROR_OPEN = 1
AEL_STATUS_ERROR_INPUT = 2
AEL_STATUS_ERROR_PROCESS = 3
AEL_STATUS_ERROR_OUTPUT = 4
AEL_STATUS_ERROR_CLOSE = 5
AEL_STATUS_ERROR_TIMEOUT = 6
AEL_STATUS_ERROR_UNKNOWN = 7
AEL_STATUS_INPUT_DONE = 8
AEL_STATUS_INPUT_BUFFERING = 9
AEL_STATUS_OUTPUT_DONE = 10
AEL_STATUS_OUTPUT_BUFFERING = 11
AEL_STATUS_STATE_RUNNING = 12
AEL_STATUS_STATE_PAUSED = 13
AEL_STATUS_STATE_STOPPED = 14
AEL_STATUS_STATE_FINISHED = 15
AEL_STATUS_MOUNTED = 16
AEL_STATUS_UNMOUNTED = 17