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

media_source_type_t media_src

Media source type

Macros

ESP_ERR_AUDIO_BASE

Starting number of ESP audio error codes

Type Definitions

typedef void (*esp_audio_event_callback)(esp_audio_state_t *audio, void *ctx)
typedef esp_err_t (*audio_volume_set)(void *hd, int vol)
typedef esp_err_t (*audio_volume_get)(void *hd, int *vol)

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_LINK_FAIL = ESP_ERR_AUDIO_BASE + 13
ESP_ERR_AUDIO_UNKNOWN = ESP_ERR_AUDIO_BASE + 14
ESP_ERR_AUDIO_OUT_OF_RANGE = ESP_ERR_AUDIO_BASE + 15
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_STOPPED = 3
AUDIO_STATUS_FINISHED = 4
AUDIO_STATUS_ERROR = 5
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 when finished

TERMINATION_TYPE_MAX
enum esp_audio_prefer_t

Values:

ESP_AUDIO_PREFER_MEM = 0
ESP_AUDIO_PREFER_SPEED = 1
enum media_source_type_t

Values:

MEDIA_SRC_TYPE_NULL = 0
MEDIA_SRC_TYPE_MUSIC_BASE = 0x100
MEDIA_SRC_TYPE_MUSIC_SD = MEDIA_SRC_TYPE_MUSIC_BASE + 1
MEDIA_SRC_TYPE_MUSIC_HTTP = MEDIA_SRC_TYPE_MUSIC_BASE + 2
MEDIA_SRC_TYPE_MUSIC_FLASH = MEDIA_SRC_TYPE_MUSIC_BASE + 3
MEDIA_SRC_TYPE_MUSIC_A2DP = MEDIA_SRC_TYPE_MUSIC_BASE + 4
MEDIA_SRC_TYPE_MUSIC_DLNA = MEDIA_SRC_TYPE_MUSIC_BASE + 5
MEDIA_SRC_TYPE_MUSIC_RAW = MEDIA_SRC_TYPE_MUSIC_BASE + 6
MEDIA_SRC_TYPE_MUSIC_MAX = 0x1FF
MEDIA_SRC_TYPE_TONE_BASE = 0x200
MEDIA_SRC_TYPE_TONE_SD = MEDIA_SRC_TYPE_TONE_BASE + 1
MEDIA_SRC_TYPE_TONE_HTTP = MEDIA_SRC_TYPE_TONE_BASE + 2
MEDIA_SRC_TYPE_TONE_FLASH = MEDIA_SRC_TYPE_TONE_BASE + 3
MEDIA_SRC_TYPE_TONE_MAX = 0x2FF
MEDIA_SRC_TYPE_RESERVE_BASE = 0x800
MEDIA_SRC_TYPE_RESERVE_MAX = 0xFFF

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_MEMORY_LACK: allocate memory fail
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_MEMORY_LACK: allocate memory fail
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_MEMORY_LACK: allocate memory fail
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”
  • ”aadp://44100:2@bt/sink/stream.pcm”

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.
  • Enabled CONFIG_FATFS_API_ENCODING_UTF_8, the URI can be support Chinese characters.
  • Asynchronous interface
  • The maximum of block time can be modify by esp_audio_play_timeout_set, default value is 25 seconds.
Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_TIMEOUT: timeout the play activity
  • ESP_ERR_AUDIO_NOT_SUPPORT: Currently status is AUDIO_STATUS_RUNNING
  • 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”. If NULL to be set, the uri setup byesp_audio_setup will used.
  • type: Specific handle type decoder or encoder
  • pos: Specific starting position by bytes

audio_err_t esp_audio_sync_play(esp_audio_handle_t handle, const char *uri, int pos)

Play the given uri until music finished or error occured.

Note
  • All features are same with esp_audio_play
  • Synchronous interface
  • Support decoder mode only
  • No any events post during playing
Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_TIMEOUT: timeout(8000ms) the play activity
  • ESP_ERR_AUDIO_NOT_SUPPORT: Currently status is AUDIO_STATUS_RUNNING
  • 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”,
  • pos: Specific starting position by bytes

audio_err_t esp_audio_stop(esp_audio_handle_t handle, audio_termination_type_t type)

A synchronous interface for stop the esp_audio. The maximum of block time is 8000ms.

Note
1. If user queue has been registered by evt_que, AUDIO_STATUS_STOPPED event for success or AUDIO_STATUS_ERROR event for error will be received.
  1. TERMINATION_TYPE_DONE only works with input stream which can’t stopped by itself, e.g. raw read/write stream, others streams are no effect.
  2. The synchronous interface is used to ensure that working pipeline is stopped.
Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_INVALID_PARAMETER: invalid arguments
  • ESP_ERR_AUDIO_NOT_READY: The status is not AUDIO_STATUS_RUNNING or AUDIO_STATUS_PAUSED
  • ESP_ERR_AUDIO_TIMEOUT: timeout(8000ms) 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
1. 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.
  1. The Paused music must be stoped by esp_audio_stop before new playing, otherwise got block on new play.
Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_INVALID_PARAMETER: invalid arguments
  • ESP_ERR_AUDIO_NOT_READY: the status is not running
  • ESP_ERR_AUDIO_TIMEOUT: timeout(8000ms) 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_RUNNING 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(8000ms) 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 codec element
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

audio_err_t esp_audio_media_type_set(esp_audio_handle_t handle, media_source_type_t type)
audio_err_t esp_audio_info_get(esp_audio_handle_t handle, esp_audio_info_t *info)
audio_err_t esp_audio_info_set(esp_audio_handle_t handle, esp_audio_info_t *info)
audio_err_t esp_audio_callback_set(esp_audio_handle_t handle, esp_audio_event_callback cb, void *cb_ctx)
audio_err_t esp_audio_seek(esp_audio_handle_t handle, int seek_time_sec)

Seek the position in second of currently played music.

Note
This function works only with decoding music.
Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_FAIL: codec or allocation fail
  • ESP_ERR_AUDIO_TIMEOUT: timeout for sync the element status
  • ESP_ERR_AUDIO_INVALID_PARAMETER: no esp_audio instance
  • ESP_ERR_AUDIO_NOT_SUPPORT: codec has finished
  • ESP_ERR_AUDIO_OUT_OF_RANGE: the seek_time_ms is out of the range
  • ESP_ERR_AUDIO_NOT_READY: the status is neither running nor paused
Parameters
  • handle: The esp_audio instance
  • seek_time_sec: A pointer to int that indicates esp_audio decoding position.

audio_err_t esp_audio_duration_get(esp_audio_handle_t handle, int *duration)

Get the duration in microseconds of playing 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 codec element or no in element
Parameters
  • handle: The esp_audio instance
  • duration: A pointer to int that indicates decoding total time.

audio_err_t esp_audio_play_timeout_set(esp_audio_handle_t handle, int time_ms)

Setting the maximum amount of time to waiting for esp_audio_play only.

Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_INVALID_PARAMETER: invalid arguments
Parameters
  • handle: The esp_audio instance
  • time_ms: The maximum amount of time

audio_err_t esp_audio_prefer_type_get(esp_audio_handle_t handle, esp_audio_prefer_t *type)

Get the type of esp_audio_prefer_t

Return
  • ESP_ERR_AUDIO_NO_ERROR: on succss
  • ESP_ERR_AUDIO_INVALID_PARAMETER: no esp_audio instance
Parameters
  • handle: The esp_audio instance
  • type: A pointer to esp_audio_prefer_t

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 It should be make sure same with I2S stream sample_rate

QueueHandle_t evt_que

For received esp_audio events (optional)

esp_audio_event_callback cb_func

esp_audio events callback (optional)

void *cb_ctx

esp_audio callback context (optional)

esp_audio_prefer_t prefer_type

esp_audio works on sepcific type, default memory is preferred.

  • ESP_AUDIO_PREFER_MEM mode stopped the previous linked elements before the new pipiline starting, except out stream element.
  • ESP_AUDIO_PREFER_SPEED mode kept the previous linked elements before the new pipiline starting, except out stream element.

void *vol_handle

Volume change instance

audio_volume_set vol_set

Set volume callback

audio_volume_get vol_get

Get volume callback

int task_prio

esp_audio task priority

int task_stack

Size of esp_audio task stack

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

int set_time

Set starting position of the microseconds time (optional)

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

struct esp_audio_info_t

esp_audio information

Public Members

audio_element_info_t codec_info

Codec information

audio_element_handle_t in_el

Handle of the in stream

audio_element_handle_t out_el

Handle of the out stream

audio_element_handle_t codec_el

Handle of the codec

audio_element_handle_t filter_el

Handle of the filter

esp_audio_state_t st

The state of esp_audio

int time_pos

Position of the microseconds time

Macros

DEFAULT_ESP_AUDIO_CONFIG()

Type Definitions

typedef void *esp_audio_handle_t