Audio Streams

An Audio Element responsible for acquiring of audio data and then sending the data out after processing, is called the Audio Stream.

The following stream types are supported:

To set the stream type, use provided structure, e.g. i2s_stream_cfg_t for I2S stream, together with audio_stream_type_t enumerator.

See description below for the API details.

I2S Stream

When the I2S stream type is “writer”, the data may be sent either to a codec chip or to the internal DAC of ESP32. To simplify configuration, two macros are provided to cover each case:

  • I2S_STREAM_CFG_DEFAULT - the I2S stream is communicating with a codec chip
  • I2S_STREAM_INTERNAL_DAC_CFG_DEFAULT - the stream data are sent to the DAC

Each macro configures several other stream parameters such as sample rate, bits per sample, DMA buffer length, etc.

Functions

audio_element_handle_t i2s_stream_init(i2s_stream_cfg_t *config)

Create a handle to an Audio Element to stream data from I2S to another Element or get data from other elements sent to I2S, depending on the configuration of stream type is AUDIO_STREAM_READER or AUDIO_STREAM_WRITER.

Note
If I2S stream is enabled with built-in DAC mode, please don’t use I2S_NUM_1. The built-in DAC functions are only supported on I2S0 for the current ESP32 chip.
Return
The Audio Element handle
Parameters
  • config: The configuration

esp_err_t i2s_stream_set_clk(audio_element_handle_t i2s_stream, int rate, int bits, int ch)

Setup clock for I2S Stream, this function is only used with handle created by i2s_stream_init

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • i2s_stream: The i2s element handle
  • rate: Clock rate (in Hz)
  • bits: Audio bit width (8, 16, 24, 32)
  • ch: Number of Audio channels (1: Mono, 2: Stereo)

esp_err_t i2s_alc_volume_set(audio_element_handle_t i2s_stream, int volume)

Setup volume of stream by using ALC.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • i2s_stream: The i2s element handle
  • volume: The volume of stream will be set.

esp_err_t i2s_alc_volume_get(audio_element_handle_t i2s_stream, int *volume)

Get volume of stream.

Return
  • ESP_OK
  • ESP_FAIL
Parameters
  • i2s_stream: The i2s element handle
  • volume: The volume of stream

Structures

struct i2s_stream_cfg_t

I2S Stream configurations Default value will be used if any entry is zero.

Public Members

audio_stream_type_t type

Type of stream

i2s_config_t i2s_config

I2S driver configurations

i2s_port_t i2s_port

I2S driver hardware port

bool use_alc

It is a flag for ALC. If use ALC, the value is true. Or the value is false

int volume

The volume of audio input data will be set.

int out_rb_size

Size of output ringbuffer

int task_stack

Task stack size

int task_core

Task running in core (0 or 1)

int task_prio

Task priority (based on freeRTOS priority)

int multi_out_num

The number of multiple output

bool uninstall_drv

whether uninstall the i2s driver when stream destroyed

Macros

I2S_STREAM_TASK_STACK
I2S_STREAM_BUF_SIZE
I2S_STREAM_TASK_PRIO
I2S_STREAM_TASK_CORE
I2S_STREAM_RINGBUFFER_SIZE
I2S_STREAM_CFG_DEFAULT()
I2S_STREAM_INTERNAL_DAC_CFG_DEFAULT()

HTTP Stream

Functions

audio_element_handle_t http_stream_init(http_stream_cfg_t *config)

Create a handle to an Audio Element to stream data from HTTP to another Element or get data from other elements sent to HTTP, depending on the configuration the stream type, either AUDIO_STREAM_READER or AUDIO_STREAM_WRITER.

Return
The Audio Element handle
Parameters
  • config: The configuration

esp_err_t http_stream_next_track(audio_element_handle_t el)

Connect to next track in the playlist.

This function can be used in event_handler of http_stream. User can call this function to connect to next track in playlist when he/she gets HTTP_STREAM_FINISH_TRACK event

Return
  • ESP_OK on success
  • ESP_FAIL on errors
Parameters
  • el: The http_stream element handle

esp_err_t http_stream_restart(audio_element_handle_t el)
esp_err_t http_stream_fetch_again(audio_element_handle_t el)

Try to fetch the tracks again.

If this is live stream we will need to keep fetching URIs.

Return
  • ESP_OK on success
  • ESP_ERR_NOT_SUPPORTED if playlist is finished
Parameters
  • el: The http_stream element handle

Structures

struct http_stream_event_msg_t

Stream event message.

Public Members

http_stream_event_id_t event_id

Event ID

void *http_client

Reference to HTTP Client using by this HTTP Stream

void *buffer

Reference to Buffer using by the Audio Element

int buffer_len

Length of buffer

void *user_data

User data context, from http_stream_cfg_t

audio_element_handle_t el

Audio element context

struct http_stream_cfg_t

HTTP Stream configurations Default value will be used if any entry is zero.

Public Members

audio_stream_type_t type

Type of stream

int out_rb_size

Size of output ringbuffer

int task_stack

Task stack size

int task_core

Task running in core (0 or 1)

int task_prio

Task priority (based on freeRTOS priority)

http_stream_event_handle_t event_handle

The hook function for HTTP Stream

void *user_data

User data context

bool auto_connect_next_track

connect next track without open/close

bool enable_playlist_parser

Enable playlist parser

int multi_out_num

The number of multiple output

Macros

HTTP_STREAM_TASK_STACK
HTTP_STREAM_TASK_CORE
HTTP_STREAM_TASK_PRIO
HTTP_STREAM_RINGBUFFER_SIZE
HTTP_STREAM_CFG_DEFAULT()

Type Definitions

typedef int (*http_stream_event_handle_t)(http_stream_event_msg_t *msg)

Enumerations

enum http_stream_event_id_t

HTTP Stream hook type.

Values:

HTTP_STREAM_PRE_REQUEST = 0x01

The event handler will be called before HTTP Client making the connection to the server

HTTP_STREAM_ON_REQUEST

The event handler will be called when HTTP Client is requesting data, If the fucntion return the value (-1: ESP_FAIL), HTTP Client will be stopped If the fucntion return the value > 0, HTTP Stream will ignore the post_field If the fucntion return the value = 0, HTTP Stream continue send data from post_field (if any)

HTTP_STREAM_ON_RESPONSE

The event handler will be called when HTTP Client is receiving data If the fucntion return the value (-1: ESP_FAIL), HTTP Client will be stopped If the fucntion return the value > 0, HTTP Stream will ignore the read function If the fucntion return the value = 0, HTTP Stream continue read data from HTTP Server

HTTP_STREAM_POST_REQUEST

The event handler will be called after HTTP Client send header and body to the server, before fetching the headers

HTTP_STREAM_FINISH_REQUEST

The event handler will be called after HTTP Client fetch the header and ready to read HTTP body

HTTP_STREAM_RESOLVE_ALL_TRACKS
HTTP_STREAM_FINISH_TRACK
HTTP_STREAM_FINISH_PLAYLIST

FatFs Stream

Functions

audio_element_handle_t fatfs_stream_init(fatfs_stream_cfg_t *config)

Create a handle to an Audio Element to stream data from FatFs to another Element or get data from other elements written to FatFs, depending on the configuration the stream type, either AUDIO_STREAM_READER or AUDIO_STREAM_WRITER.

Return
The Audio Element handle
Parameters
  • config: The configuration

Structures

struct fatfs_stream_cfg_t

FATFS Stream configurations, if any entry is zero then the configuration will be set to default values.

Public Members

audio_stream_type_t type

Stream type

int buf_sz

Audio Element Buffer size

int out_rb_size

Size of output ringbuffer

int task_stack

Task stack size

int task_core

Task running in core (0 or 1)

int task_prio

Task priority (based on freeRTOS priority)

Macros

FATFS_STREAM_BUF_SIZE
FATFS_STREAM_TASK_STACK
FATFS_STREAM_TASK_CORE
FATFS_STREAM_TASK_PRIO
FATFS_STREAM_RINGBUFFER_SIZE
FATFS_STREAM_CFG_DEFAULT()

Raw Stream

Functions

audio_element_handle_t raw_stream_init(raw_stream_cfg_t *cfg)

Initialize RAW stream.

Return
The audio element handle
Parameters
  • cfg: The RAW Stream configuration

int raw_stream_read(audio_element_handle_t pipeline, char *buffer, int buf_size)

Read data from Stream.

Return
Number of bytes actually read.
Parameters
  • pipeline: The audio pipeline handle
  • buffer: The buffer
  • buf_size: Maximum number of bytes to be read.

int raw_stream_write(audio_element_handle_t pipeline, char *buffer, int buf_size)

Write data to Stream.

Return
Number of bytes written
Parameters
  • pipeline: The audio pipeline handle
  • buffer: The buffer
  • buf_size: Number of bytes to write

Structures

struct raw_stream_cfg_t

Raw stream provides APIs to obtain the pipeline data without output stream or fill the pipeline data without input stream. The stream has two types / modes, reader and writer:

  • AUDIO_STREAM_READER, e.g. [i2s]->[filter]->[raw],[i2s]->[codec-amr]->[raw]
  • AUDIO_STREAM_WRITER, e.g. [raw]->[codec-mp3]->[i2s] Raw Stream configurations

Public Members

audio_stream_type_t type

Type of stream

int out_rb_size

Size of output ringbuffer

Macros

RAW_STREAM_RINGBUFFER_SIZE
RAW_STREAM_CFG_DEFAULT()

Spiffs Stream

Functions

audio_element_handle_t spiffs_stream_init(spiffs_stream_cfg_t *config)

Create a handle to an Audio Element to stream data from SPIFFS to another Element or get data from other elements written to SPIFFS, depending on the configuration the stream type, either AUDIO_STREAM_READER or AUDIO_STREAM_WRITER.

Return
The Audio Element handle
Parameters
  • config: The configuration

Structures

struct spiffs_stream_cfg_t

SPIFFS Stream configuration, if any entry is zero then the configuration will be set to default values.

Public Members

audio_stream_type_t type

Stream type

int buf_sz

Audio Element Buffer size

int out_rb_size

Size of output ringbuffer

int task_stack

Task stack size

int task_core

Task running in core (0 or 1)

int task_prio

Task priority (based on freeRTOS priority)

Macros

SPIFFS_STREAM_BUF_SIZE
SPIFFS_STREAM_TASK_STACK
SPIFFS_STREAM_TASK_CORE
SPIFFS_STREAM_TASK_PRIO
SPIFFS_STREAM_RINGBUFFER_SIZE
SPIFFS_STREAM_CFG_DEFAULT()