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¶
Header File¶
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
-
esp_audio_status_t
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¶
-
Header File¶
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 instancein_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 instanceout_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 instancetype
: 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 instancetype
: The CODEC_ENCODER or CODEC_DECODERextension
: 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 returnESP_ERR_AUDIO_INVALID_URI
. - If the esp_decoder codec is added to
handle
, then thehandle
of esp_decoder will be set as the default decoder, even if other decoders are added.
- The URI parse by
- 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 instanceuri
: Such as “file://sdcard/test.wav” or “http://iot.espressif.com/file/example.mp3”,type
: Specific handle type decoder or encoderpos
: 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 instancetype
: 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 instancevol
: 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 instancevol
: 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 instancestate
: 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 instancepos
: 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 instancetime
: 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
andout_stream
definitely, and seturi
.- Note
- This function provide a manual way to select in/out stream and codec, should be called before the
esp_audio_play
, then ignore theesp_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
handle
: The esp_audio instancesets
: A pointer to esp_audio_setup_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
-
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
-
int
-
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
-
audio_codec_type_t
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