[audio] Add clear_buffered_data method to RingBufferAudioSource (#16594)

esphome/components/audio/audio_transfer_buffer.cpp

@@ -252,6 +252,22 @@ void RingBufferAudioSource::consume(size_t bytes) {
   }
 }
 
+void RingBufferAudioSource::clear_buffered_data() {
+  // Release the held item before reset() so the source no longer references memory the reset will reclaim.
+  if (this->acquired_item_ != nullptr) {
+    this->ring_buffer_->receive_release(this->acquired_item_);
+    this->acquired_item_ = nullptr;
+  }
+  this->current_data_ = nullptr;
+  this->current_available_ = 0;
+  this->queued_data_ = nullptr;
+  this->queued_length_ = 0;
+  this->item_trailing_ptr_ = nullptr;
+  this->item_trailing_length_ = 0;
+  this->splice_length_ = 0;
+  this->ring_buffer_->reset();
+}
+
 bool RingBufferAudioSource::has_buffered_data() const {
   // splice_length_ is deliberately not considered here. It holds an incomplete frame whose completion
   // bytes must still arrive through the ring buffer, which ring_buffer_->available() already reports.

esphome/components/audio/audio_transfer_buffer.h

@@ -250,6 +250,10 @@ class RingBufferAudioSource : public AudioReadableBuffer {
   /// exposure stays in place and fill() returns 0 until it is fully consumed.
   size_t fill(TickType_t ticks_to_wait, bool pre_shift) override;
 
+  /// @brief 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.
+  void clear_buffered_data();
+
   /// @brief 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