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:

• I2S Stream
• HTTP Stream
• FatFs Stream
• Raw Stream
• Spiffs Stream

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.

Header File

• audio_stream/include/i2s_stream.h

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)

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_pin_config_t i2s_pin_config

I2S driver hardware pin configurations

i2s_port_t i2s_port

I2S driver hardware port

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

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

Header File

• audio_stream/include/http_stream.h

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)

esp_err_t http_stream_restart(audio_element_handle_t el)

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 enable_playlist_parser

Enable playlist parser

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

Header File

• audio_stream/include/fatfs_stream.h

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

Header File

• audio_stream/include/raw_stream.h

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

Header File

• audio_stream/include/spiffs_stream.h

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