Zero-copy audio source that reads directly from a ring buffer's internal storage. More...

#include <audio_transfer_buffer.h>

Inheritance diagram for esphome::audio::RingBufferAudioSource:

Public Member Functions
	~RingBufferAudioSource () override

const uint8_t *	data () const override

size_t	available () const override

void	consume (size_t bytes) override

bool	has_buffered_data () const override

size_t	fill (TickType_t ticks_to_wait) override
	An unconsumed exposure stays in place and fill() returns 0 until it is fully consumed.

void	clear_buffered_data ()
	Discards all buffered audio: releases any held ring buffer item, clears the source's in-flight state, and resets the underlying ring buffer.

size_t	expose_padded_partial (size_t frame_bytes)
	Zero-pads held whole frames short of an alignment unit and exposes them, so a stream's tail is not stranded.

uint8_t *	mutable_data ()
	Returns a mutable pointer to the currently exposed audio data.

Public Member Functions inherited from esphome::audio::AudioReadableBuffer
virtual	~AudioReadableBuffer ()=default

virtual size_t	free () const
	Returns the number of free bytes available to write. Defaults to 0 for read-only buffers.

	ESPDEPRECATED ("Use fill(ticks_to_wait) instead. Removed in 2027.5.0.", "2026.11.0") virtual size_t fill(TickType_t ticks_to_wait

Static Public Member Functions
static std::unique_ptr< RingBufferAudioSource >	create (std::shared_ptr< ring_buffer::RingBuffer > ring_buffer, size_t max_fill_bytes, uint8_t alignment_bytes=1)
	Creates a new ring-buffer-backed audio source after validating its parameters.

Static Public Attributes
static constexpr size_t	MAX_ALIGNMENT_BYTES = 8
	Maximum supported alignment. Sized to cover 32-bit samples across up to 2 channels (8 bytes).

Protected Member Functions
	RingBufferAudioSource (std::shared_ptr< ring_buffer::RingBuffer > ring_buffer, size_t max_fill_bytes, uint8_t alignment_bytes)
	Constructs a new ring-buffer-backed audio source.

void	release_item_ ()
	Releases the currently held ring buffer item, first copying any trailing sub-frame bytes into the splice buffer so they can be stitched with the next chunk.

Protected Attributes
std::shared_ptr< ring_buffer::RingBuffer >	ring_buffer_

size_t	max_fill_bytes_

void *	acquired_item_ {nullptr}

uint8_t *	current_data_ {nullptr}

uint8_t *	item_trailing_ptr_ {nullptr}

uint8_t *	queued_data_ {nullptr}

uint8_t	splice_buffer_ [MAX_ALIGNMENT_BYTES]

size_t	current_available_ {0}

size_t	queued_length_ {0}

uint8_t	alignment_bytes_

uint8_t	item_trailing_length_ {0}

uint8_t	splice_length_ {0}

Additional Inherited Members
Data Fields inherited from esphome::audio::AudioReadableBuffer
bool	pre_shift { return this->fill(ticks_to_wait)

Detailed Description

Zero-copy audio source that reads directly from a ring buffer's internal storage.

Optionally enforces a minimum read alignment (e.g. one audio frame). When alignment_bytes > 1, the source transparently stitches frames that straddle the ring buffer's wrap boundary by buffering the trailing partial frame from one chunk and joining it with the head of the next chunk in a small internal splice buffer, so callers always see frame-aligned data.

Not thread-safe. The underlying ring_buffer::RingBuffer supports one producer and one consumer running concurrently, but a given RingBufferAudioSource (its acquired item, splice buffer, and queued region) must be used by only one thread, and that thread is the ring buffer's consumer.

Definition at line 237 of file audio_transfer_buffer.h.

Constructor & Destructor Documentation

◆ ~RingBufferAudioSource()

esphome::audio::RingBufferAudioSource::~RingBufferAudioSource ( )

override

Definition at line 223 of file audio_transfer_buffer.cpp.

◆ RingBufferAudioSource()

esphome::audio::RingBufferAudioSource::RingBufferAudioSource	(	std::shared_ptr< ring_buffer::RingBuffer >	ring_buffer,
		size_t	max_fill_bytes,
		uint8_t	alignment_bytes )

inlineexplicitprotected

Constructs a new ring-buffer-backed audio source.

Use create() instead, which validates arguments before construction.

Definition at line 284 of file audio_transfer_buffer.h.

Member Function Documentation

◆ available()

size_t esphome::audio::RingBufferAudioSource::available ( ) const

inlineoverridevirtual

Implements esphome::audio::AudioReadableBuffer.

Definition at line 256 of file audio_transfer_buffer.h.

◆ clear_buffered_data()

void esphome::audio::RingBufferAudioSource::clear_buffered_data ( )

Discards all buffered audio: releases any held ring buffer item, clears the source's in-flight state, and resets the underlying ring buffer.

Must be invoked from the ring buffer's consumer thread.

Definition at line 259 of file audio_transfer_buffer.cpp.

◆ consume()

void esphome::audio::RingBufferAudioSource::consume ( size_t bytes )

overridevirtual

Implements esphome::audio::AudioReadableBuffer.

Definition at line 246 of file audio_transfer_buffer.cpp.

◆ create()

std::unique_ptr< RingBufferAudioSource > esphome::audio::RingBufferAudioSource::create	(	std::shared_ptr< ring_buffer::RingBuffer >	ring_buffer,
		size_t	max_fill_bytes,
		uint8_t	alignment_bytes = 1 )

static

Creates a new ring-buffer-backed audio source after validating its parameters.

Parameters

ring_buffer	The ring buffer to read from. Must be non-null.
max_fill_bytes	Soft cap on bytes acquired per fill() call. Must be > 0.
alignment_bytes	Minimum exposed-region alignment in bytes (defaults to 1, i.e. byte-aligned). Pass bytes_per_frame to make every exposed region a whole number of frames. Must be in [1, MAX_ALIGNMENT_BYTES].

Returns: unique_ptr if parameters are valid, nullptr otherwise

Definition at line 214 of file audio_transfer_buffer.cpp.

◆ data()

const uint8_t * esphome::audio::RingBufferAudioSource::data ( ) const

inlineoverridevirtual

Implements esphome::audio::AudioReadableBuffer.

Definition at line 255 of file audio_transfer_buffer.h.

◆ expose_padded_partial()

size_t esphome::audio::RingBufferAudioSource::expose_padded_partial ( size_t frame_bytes )

Zero-pads held whole frames short of an alignment unit and exposes them, so a stream's tail is not stranded.

A held partial frame is left to wait for its remaining bytes.

Parameters

frame_bytes Bytes per audio frame

Returns: Real (unpadded) bytes exposed, or 0 if nothing is exposable

Definition at line 275 of file audio_transfer_buffer.cpp.

◆ fill()

size_t esphome::audio::RingBufferAudioSource::fill ( TickType_t ticks_to_wait )

overridevirtual

An unconsumed exposure stays in place and fill() returns 0 until it is fully consumed.

Reimplemented from esphome::audio::AudioReadableBuffer.

Definition at line 300 of file audio_transfer_buffer.cpp.

◆ has_buffered_data()

bool esphome::audio::RingBufferAudioSource::has_buffered_data ( ) const

overridevirtual

Implements esphome::audio::AudioReadableBuffer.

Definition at line 292 of file audio_transfer_buffer.cpp.

◆ mutable_data()

uint8_t * esphome::audio::RingBufferAudioSource::mutable_data ( )

inline

Returns a mutable pointer to the currently exposed audio data.

The pointer may reference the ring buffer's internal storage or, when exposing a stitched frame across a wrap boundary, an internal splice buffer. In either case mutations are safe but data should be discarded after use, since the underlying storage will be reused on the next fill(). Use only when the caller is the sole consumer of this source.

Definition at line 279 of file audio_transfer_buffer.h.

◆ release_item_()

void esphome::audio::RingBufferAudioSource::release_item_ ( )

protected

Releases the currently held ring buffer item, first copying any trailing sub-frame bytes into the splice buffer so they can be stitched with the next chunk.

Definition at line 230 of file audio_transfer_buffer.cpp.

Field Documentation

◆ acquired_item_

void* esphome::audio::RingBufferAudioSource::acquired_item_ {nullptr}

protected

Definition at line 295 of file audio_transfer_buffer.h.

◆ alignment_bytes_

uint8_t esphome::audio::RingBufferAudioSource::alignment_bytes_

protected

Definition at line 313 of file audio_transfer_buffer.h.

◆ current_available_

size_t esphome::audio::RingBufferAudioSource::current_available_ {0}

protected

Definition at line 309 of file audio_transfer_buffer.h.

◆ current_data_

uint8_t* esphome::audio::RingBufferAudioSource::current_data_ {nullptr}

protected

Definition at line 296 of file audio_transfer_buffer.h.

◆ item_trailing_length_

uint8_t esphome::audio::RingBufferAudioSource::item_trailing_length_ {0}

protected

Definition at line 314 of file audio_transfer_buffer.h.

◆ item_trailing_ptr_

uint8_t* esphome::audio::RingBufferAudioSource::item_trailing_ptr_ {nullptr}

protected

Definition at line 299 of file audio_transfer_buffer.h.

◆ MAX_ALIGNMENT_BYTES

size_t esphome::audio::RingBufferAudioSource::MAX_ALIGNMENT_BYTES = 8

staticconstexpr

Maximum supported alignment. Sized to cover 32-bit samples across up to 2 channels (8 bytes).

Definition at line 240 of file audio_transfer_buffer.h.

◆ max_fill_bytes_

size_t esphome::audio::RingBufferAudioSource::max_fill_bytes_

protected

Definition at line 293 of file audio_transfer_buffer.h.

◆ queued_data_

uint8_t* esphome::audio::RingBufferAudioSource::queued_data_ {nullptr}

protected

Definition at line 303 of file audio_transfer_buffer.h.

◆ queued_length_

size_t esphome::audio::RingBufferAudioSource::queued_length_ {0}

protected

Definition at line 310 of file audio_transfer_buffer.h.

◆ ring_buffer_

std::shared_ptr<ring_buffer::RingBuffer> esphome::audio::RingBufferAudioSource::ring_buffer_

protected

Definition at line 292 of file audio_transfer_buffer.h.

◆ splice_buffer_

uint8_t esphome::audio::RingBufferAudioSource::splice_buffer_[MAX_ALIGNMENT_BYTES]

protected

Definition at line 307 of file audio_transfer_buffer.h.

◆ splice_length_

uint8_t esphome::audio::RingBufferAudioSource::splice_length_ {0}

protected

Definition at line 315 of file audio_transfer_buffer.h.

The documentation for this class was generated from the following files:

esphome/components/audio/audio_transfer_buffer.h
esphome/components/audio/audio_transfer_buffer.cpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ~RingBufferAudioSource()

◆ RingBufferAudioSource()

Member Function Documentation

◆ available()

◆ clear_buffered_data()

◆ consume()

◆ create()

◆ data()

◆ expose_padded_partial()

◆ fill()

◆ has_buffered_data()

◆ mutable_data()

◆ release_item_()

Field Documentation

◆ acquired_item_

◆ alignment_bytes_

◆ current_available_

◆ current_data_

◆ item_trailing_length_

◆ item_trailing_ptr_

◆ MAX_ALIGNMENT_BYTES

◆ max_fill_bytes_

◆ queued_data_

◆ queued_length_

◆ ring_buffer_

◆ splice_buffer_

◆ splice_length_