ESP Audio

This component provides several simple high level APIs. It is intended for quick implementation of audio applications based on typical interconnections of standardized audio elements.

API Reference

Structures

struct esp_audio_state_t

esp_audio status information parameters

Public Members

esp_audio_status_t status

Status of esp_audio

audio_err_t err_msg

Status is AUDIO_STATUS_ERROR,err_msg will be setup

Macros

ESP_ERR_AUDIO_BASE

Starting number of ESP audio error codes

Type Definitions

typedef enum audio_err_t audio_err_t
typedef enum esp_audio_status_t esp_audio_status_t

Enumerations

enum audio_err_t

Values:

ESP_ERR_AUDIO_NO_ERROR = ESP_OK
ESP_ERR_AUDIO_FAIL = ESP_FAIL
ESP_ERR_AUDIO_NO_INPUT_STREAM = ESP_ERR_AUDIO_BASE + 1
ESP_ERR_AUDIO_NO_OUTPUT_STREAM = ESP_ERR_AUDIO_BASE + 2
ESP_ERR_AUDIO_NO_CODEC = ESP_ERR_AUDIO_BASE + 3
ESP_ERR_AUDIO_HAL_FAIL = ESP_ERR_AUDIO_BASE + 4
ESP_ERR_AUDIO_MEMORY_LACK = ESP_ERR_AUDIO_BASE + 5
ESP_ERR_AUDIO_INVALID_URI = ESP_ERR_AUDIO_BASE + 6
ESP_ERR_AUDIO_INVALID_PATH = ESP_ERR_AUDIO_BASE + 7
ESP_ERR_AUDIO_INVALID_PARAMETER = ESP_ERR_AUDIO_BASE + 8
ESP_ERR_AUDIO_NOT_READY = ESP_ERR_AUDIO_BASE + 9
ESP_ERR_AUDIO_NOT_SUPPORT = ESP_ERR_AUDIO_BASE + 10
ESP_ERR_AUDIO_TIMEOUT = ESP_ERR_AUDIO_BASE + 11
ESP_ERR_AUDIO_ALREADY_EXISTS = ESP_ERR_AUDIO_BASE + 12
ESP_ERR_AUDIO_UNKNOWN = ESP_ERR_AUDIO_BASE + 13
ESP_ERR_AUDIO_OPEN = ESP_ERR_AUDIO_BASE + 0x100
ESP_ERR_AUDIO_INPUT = ESP_ERR_AUDIO_BASE + 0x101
ESP_ERR_AUDIO_PROCESS = ESP_ERR_AUDIO_BASE + 0x102
ESP_ERR_AUDIO_OUTPUT = ESP_ERR_AUDIO_BASE + 0x103
ESP_ERR_AUDIO_CLOSE = ESP_ERR_AUDIO_BASE + 0x104
enum esp_audio_status_t

Values:

AUDIO_STATUS_UNKNOWN = 0
AUDIO_STATUS_RUNNING = 1
AUDIO_STATUS_PAUSED = 2
AUDIO_STATUS_STOPED = 3
AUDIO_STATUS_ERROR = 4
enum audio_termination_type_t

Values:

TERMINATION_TYPE_NOW = 0

Audio operation will be terminated immediately

TERMINATION_TYPE_DONE = 1

Audio operation will be stopped untill is finished

TERMINATION_TYPE_MAX

Functions

esp_audio_handle_t esp_audio_create(const esp_audio_cfg_t *cfg)

Create esp_audio instance according to ‘cfg’ parameter.

This function create an esp_audio instance, at the specified configuration.

Return
  • NULL: Error
  • Others: esp_audio instance fully certifying
Parameters
  • cfg: Provide esp_audio initialization configuration

audio_err_t esp_audio_destroy(esp_audio_handle_t handle)

Specific esp_audio instance will be destroyed.

Return
  • ESP_ERR_AUDIO_NO_ERROR: on success
  • ESP_ERR_AUDIO_INVALID_PARAMETER: no instance to free, call esp_audio_init first
Parameters
  • handle: The esp_audio instance

audio_err_t esp_audio_input_stream_add(esp_audio_handle_t handle, audio_element_handle_t in_stream)

Add audio input stream to specific esp_audio instance.

Return
  • ESP_ERR_AUDIO_NO_ERROR: on success
  • ESP_ERR_AUDIO_INVALID_PARAMETER: invalid arguments
  • ESP_ERR_AUDIO_ALREADY_EXISTS: in_stream has already exist or have the same stream tag.
Parameters
  • handle: The esp_audio instance
  • in_stream: Audio stream instance

audio_err_t esp_audio_output_stream_add(esp_audio_handle_t handle, audio_element_handle_t out_stream)

Add audio output stream to specific esp_audio instance.

Return
  • ESP_ERR_AUDIO_NO_ERROR: on success
  • ESP_ERR_AUDIO_INVALID_PARAMETER: invalid arguments
  • ESP_ERR_AUDIO_ALREADY_EXISTS: out_stream has already exist or have the same stream tag.
Parameters
  • handle: The esp_audio instance
  • out_stream: The audio stream element instance

audio_err_t esp_audio_codec_lib_add(esp_audio_handle_t handle, audio_codec_type_t type, audio_element_handle_t lib)

Add a new codec lib that can decode or encode a music file.

Return
  • ESP_ERR_AUDIO_NO_ERROR: on success
  • ESP_ERR_AUDIO_INVALID_PARAMETER: invalid arguments
  • ESP_ERR_AUDIO_ALREADY_EXISTS: lib has already exist or have the same extension.
Parameters
  • handle: The esp_audio instance
  • type: The audio codec type(encoder or decoder)
  • lib: To provide audio stream element

audio_err_t esp_audio_codec_lib_query(esp_audio_handle_t handle, audio_codec_type_t type, const char *extension)

Check if this kind of music extension is supported or not.

Note
This function just query the codec which has already add by esp_audio_codec_lib_add. The max length of extension is 6.
Return
  • ESP_ERR_AUDIO_NO_ERROR: supported
  • ESP_ERR_AUDIO_NOT_SUPPORT: not support
  • ESP_ERR_AUDIO_INVALID_PARAMETER: invalid arguments
Parameters
  • handle: The esp_audio instance
  • type: The CODEC_ENCODER or CODEC_DECODER
  • extension: Such as “mp3”, “wav”, “aac”

audio_err_t esp_audio_play(esp_audio_handle_t handle, audio_codec_type_t type, const char *uri, int pos)

Play the given uri.

The esp_audio_play have follow activity, setup inputstream, outputstream and codec by uri, start all of them. There is a rule that esp_audio will select input stream, codec and output stream by URI field.

Rule of URI field are as follow.

  • UF_SCHEMA field of URI for choose input stream from existing streams. e.g:”http”,”file”
  • UF_PATH field of URI for choose codec from existing codecs. e.g:”/audio/mp3_music.mp3”
  • UF_FRAGMENT field of URI for choose output stream from existing streams, output stream is I2S by default.
  • UF_USERINFO field of URI for specific sample rate and channels at encode mode.

The format “user:password” in the userinfo field, “user” is sample rate, “password” is channels.

Now esp_audio_play support follow URIs.

  • ”https://dl.espressif.com/dl/audio/mp3_music.mp3”
  • ”http://media-ice.musicradio.com/ClassicFMMP3”
  • ”file://sdcard/test.mp3”
  • ”iis://16000:2@from.pcm/rec.wav#file”
  • ”iis://16000:1@record.pcm/record.wav#raw”

Note
  • The URI parse by http_parser_parse_url,any illegal string will be return ESP_ERR_AUDIO_INVALID_URI.
  • If the esp_decoder codec is added to handle, then the handle of esp_decoder will be set as the default decoder, even if other decoders are added.
Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_TIMEOUT: timeout the play activity.
  • ESP_ERR_AUDIO_INVALID_URI: URI is illegal
  • ESP_ERR_AUDIO_INVALID_PARAMETER: invalid arguments
Parameters
  • handle: The esp_audio_handle_t instance
  • uri: Such as “file://sdcard/test.wav” or “http://iot.espressif.com/file/example.mp3”,
  • type: Specific handle type decoder or encoder
  • pos: Specific starting position by bytes

audio_err_t esp_audio_stop(esp_audio_handle_t handle, audio_termination_type_t type)

Stop the esp_audio.

Note
If user queue has been registered by evt_que, AUDIO_STATUS_STOPED event for success or AUDIO_STATUS_ERROR event for error will be received. TERMINATION_TYPE_DONE only works with input stream which can’t stoped by itself, e.g. raw read/write stream, others streams are no effect.
Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_INVALID_PARAMETER: invalid arguments
  • ESP_ERR_AUDIO_TIMEOUT: timeout the stop activity.
Parameters
  • handle: The esp_audio instance
  • type: Stop immediately or done

audio_err_t esp_audio_pause(esp_audio_handle_t handle)

Pause the esp_audio.

Note
Only support music and without live stream. If user queue has been registered by evt_que, AUDIO_STATUS_PAUSED event for success or AUDIO_STATUS_ERROR event for error will be received.
Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_INVALID_PARAMETER: invalid arguments
  • ESP_ERR_AUDIO_TIMEOUT: timeout the pause activity.
Parameters
  • handle: The esp_audio instance

audio_err_t esp_audio_resume(esp_audio_handle_t handle)

Resume the music paused.

Note
Only support music and without live stream. If user queue has been registered by evt_que, AUDIO_STATUS_PLAYING event for success or AUDIO_STATUS_ERROR event for error will be received.
Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_INVALID_PARAMETER: invalid arguments
  • ESP_ERR_AUDIO_TIMEOUT: timeout the resume activity.
Parameters
  • handle: The esp_audio instance

audio_err_t esp_audio_vol_set(esp_audio_handle_t handle, int vol)

Setting esp_audio volume.

Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_CTRL_HAL_FAIL: error with hardware.
  • ESP_ERR_AUDIO_INVALID_PARAMETER: invalid arguments
Parameters
  • handle: The esp_audio instance
  • vol: Specific volume will be set. 0-100 is legal. 0 will be mute.

audio_err_t esp_audio_vol_get(esp_audio_handle_t handle, int *vol)

Get esp_audio volume.

Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_CTRL_HAL_FAIL: error with hardware.
  • ESP_ERR_AUDIO_INVALID_PARAMETER: invalid arguments
Parameters
  • handle: The esp_audio instance
  • vol: A pointer to int that indicates esp_audio volume.

audio_err_t esp_audio_state_get(esp_audio_handle_t handle, esp_audio_state_t *state)

Get esp_audio status.

Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_INVALID_PARAMETER: no esp_audio instance or esp_audio does not playing
Parameters
  • handle: The esp_audio instance
  • state: A pointer to esp_audio_state_t that indicates esp_audio status.

audio_err_t esp_audio_pos_get(esp_audio_handle_t handle, int *pos)

Get the position in bytes of currently played music.

Note
This function works only with decoding music.
Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_INVALID_PARAMETER: no esp_audio instance
  • ESP_ERR_AUDIO_NOT_READY:no out stream.
Parameters
  • handle: The esp_audio instance
  • pos: A pointer to int that indicates esp_audio decoding position.

audio_err_t esp_audio_time_get(esp_audio_handle_t handle, int *time)

Get the position in microseconds of currently played music.

Note
This function works only with decoding music.
Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_INVALID_PARAMETER: no esp_audio instance
  • ESP_ERR_AUDIO_NOT_READY:no out stream.
Parameters
  • handle: The esp_audio instance
  • time: A pointer to int that indicates esp_audio decoding position.

audio_err_t esp_audio_setup(esp_audio_handle_t handle, esp_audio_setup_t *sets)

Choose the in_stream, codec and out_stream definitely, and set uri.

Note
This function provide a manual way to select in/out stream and codec, should be called before the esp_audio_play, then ignore the esp_audio_play URI parameter only one time.
Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_INVALID_PARAMETER: no esp_audio instance
  • ESP_ERR_AUDIO_MEMORY_LACK: allocate memory fail
Parameters

Structures

struct esp_audio_cfg_t

esp_audio configuration parameters

Public Members

int in_stream_buf_size

Input buffer size

int out_stream_buf_size

Output buffer size

int resample_rate

Destination sample rate,0:disable rsample;others:44.1K,48K,32K,16K,8K has supported

audio_hal_handle_t hal

Codec IC hardware handle

QueueHandle_t evt_que

For received esp_audio events (optional)

int task_prio

esp_audio task priority

struct esp_audio_setup_t

esp_audio setup parameters by manual

Public Members

audio_codec_type_t set_type

Set codec type

int set_sample_rate

Set music sample rate

int set_channel

Set music channels

int set_pos

Set starting position

char *set_path

Set out stream path

char *set_uri

Set URI

char *set_in_stream

Tag of in_stream

char *set_codec

Tag of the codec

char *set_out_stream

Tag of out_stream

Type Definitions

typedef void *esp_audio_handle_t
typedef struct esp_audio_cfg_t esp_audio_cfg_t

esp_audio configuration parameters

typedef struct esp_audio_setup_t esp_audio_setup_t

esp_audio setup parameters by manual