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, bool pre_shift) override
	pre_shift is ignored: there is no intermediate transfer buffer to compact, so an unconsumed exposure stays in place and fill() returns 0 until it is fully consumed.

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.

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}

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 227 of file audio_transfer_buffer.h.

Constructor & Destructor Documentation

◆ ~RingBufferAudioSource()

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

override

Definition at line 219 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 263 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 246 of file audio_transfer_buffer.h.

◆ consume()

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

overridevirtual

Implements esphome::audio::AudioReadableBuffer.

Definition at line 242 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 210 of file audio_transfer_buffer.cpp.

◆ data()

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

inlineoverridevirtual

Implements esphome::audio::AudioReadableBuffer.

Definition at line 245 of file audio_transfer_buffer.h.

◆ fill()

size_t esphome::audio::RingBufferAudioSource::fill	(	TickType_t	ticks_to_wait,
		bool	pre_shift )

overridevirtual

pre_shift is ignored: there is no intermediate transfer buffer to compact, so an unconsumed exposure stays in place and fill() returns 0 until it is fully consumed.

Reimplemented from esphome::audio::AudioReadableBuffer.

Definition at line 263 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 255 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 258 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 226 of file audio_transfer_buffer.cpp.

Field Documentation

◆ acquired_item_

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

protected

Definition at line 274 of file audio_transfer_buffer.h.

◆ alignment_bytes_

uint8_t esphome::audio::RingBufferAudioSource::alignment_bytes_

protected

Definition at line 292 of file audio_transfer_buffer.h.

◆ current_available_

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

protected

Definition at line 288 of file audio_transfer_buffer.h.

◆ current_data_

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

protected

Definition at line 275 of file audio_transfer_buffer.h.

◆ item_trailing_length_

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

protected

Definition at line 293 of file audio_transfer_buffer.h.

◆ item_trailing_ptr_

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

protected

Definition at line 278 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 230 of file audio_transfer_buffer.h.

◆ max_fill_bytes_

size_t esphome::audio::RingBufferAudioSource::max_fill_bytes_

protected

Definition at line 272 of file audio_transfer_buffer.h.

◆ queued_data_

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

protected

Definition at line 282 of file audio_transfer_buffer.h.

◆ queued_length_

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

protected

Definition at line 289 of file audio_transfer_buffer.h.

◆ ring_buffer_

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

protected

Definition at line 271 of file audio_transfer_buffer.h.

◆ splice_buffer_

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

protected

Definition at line 286 of file audio_transfer_buffer.h.

◆ splice_length_

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

protected

Definition at line 294 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

Detailed Description

Constructor & Destructor Documentation

◆ ~RingBufferAudioSource()

◆ RingBufferAudioSource()

Member Function Documentation

◆ available()

◆ consume()

◆ create()

◆ data()

◆ 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_