audio_transfer_buffer.h

Go to the documentation of this file.

#pragma once
 
#ifdef USE_ESP32
#include "esphome/components/ring_buffer/ring_buffer.h"
#include "esphome/core/defines.h"
#include "esphome/core/helpers.h"  // for ESPDEPRECATED
 
#ifdef USE_SPEAKER
#include "esphome/components/speaker/speaker.h"
#endif
 
#include "esp_err.h"
 
#include <freertos/FreeRTOS.h>
 
namespace esphome::audio {
 
class AudioSinkCallback {
 public:
  virtual size_t audio_sink_write(uint8_t *data, size_t length, TickType_t ticks_to_wait) = 0;
};
 
class AudioTransferBuffer {
  /*
   * @brief Class that facilitates tranferring data between a buffer and an audio source or sink.
   * The transfer buffer is a typical C array that temporarily holds data for processing in other audio components.
   * Both sink and source transfer buffers can use a ring buffer as the sink/source.
   *   - The ring buffer is stored in a shared_ptr, so destroying the transfer buffer object will release ownership.
   */
 public:
  ~AudioTransferBuffer();
 
  uint8_t *get_buffer_start() const { return this->data_start_; }
 
  uint8_t *get_buffer_end() const { return this->data_start_ + this->buffer_length_; }
 
  void decrease_buffer_length(size_t bytes);
 
  void increase_buffer_length(size_t bytes);
 
  size_t available() const { return this->buffer_length_; }
 
  size_t capacity() const { return this->buffer_size_; }
 
  size_t free() const;
 
  virtual void clear_buffered_data();
 
  virtual bool has_buffered_data() const;
 
  bool reallocate(size_t new_buffer_size);
 
 protected:
  bool allocate_buffer_(size_t buffer_size);
 
  void deallocate_buffer_();
 
  // A possible source or sink for the transfer buffer
  std::shared_ptr<ring_buffer::RingBuffer> ring_buffer_;
 
  uint8_t *buffer_{nullptr};
  uint8_t *data_start_{nullptr};
 
  size_t buffer_size_{0};
  size_t buffer_length_{0};
};
 
class AudioSinkTransferBuffer : public AudioTransferBuffer {
  /*
   * @brief A class that implements a transfer buffer for audio sinks.
   * Supports writing processed data in the transfer buffer to a ring buffer or a speaker component.
   */
 public:
  static std::unique_ptr<AudioSinkTransferBuffer> create(size_t buffer_size);
 
  size_t transfer_data_to_sink(TickType_t ticks_to_wait, bool post_shift = true);
 
  void set_sink(const std::weak_ptr<ring_buffer::RingBuffer> &ring_buffer) { this->ring_buffer_ = ring_buffer.lock(); }
 
#ifdef USE_SPEAKER
  void set_sink(speaker::Speaker *speaker) { this->speaker_ = speaker; }
#endif
 
  void set_sink(AudioSinkCallback *callback) { this->sink_callback_ = callback; }
 
  void clear_buffered_data() override;
 
  bool has_buffered_data() const override;
 
 protected:
#ifdef USE_SPEAKER
  speaker::Speaker *speaker_{nullptr};
#endif
  AudioSinkCallback *sink_callback_{nullptr};
};
 
class AudioReadableBuffer {
 public:
  virtual ~AudioReadableBuffer() = default;
 
  virtual const uint8_t *data() const = 0;
 
  virtual size_t available() const = 0;
 
  virtual size_t free() const { return 0; }
 
  virtual void consume(size_t bytes) = 0;
 
  virtual bool has_buffered_data() const = 0;
 
  virtual size_t fill(TickType_t ticks_to_wait) { return 0; }
 
  // Remove before 2027.5.0
  ESPDEPRECATED("Use fill(ticks_to_wait) instead. Removed in 2027.5.0.", "2026.11.0")
  virtual size_t fill(TickType_t ticks_to_wait, bool pre_shift) { return this->fill(ticks_to_wait); }
};
 
// Remove before 2027.5.0
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
class ESPDEPRECATED("Use RingBufferAudioSource instead. Removed in 2027.5.0.", "2026.11.0") AudioSourceTransferBuffer
    : public AudioTransferBuffer,
      public AudioReadableBuffer {
  /*
   * @brief A class that implements a transfer buffer for audio sources.
   * Supports reading audio data from a ring buffer into the transfer buffer for processing.
   * Implements AudioReadableBuffer for use by consumers that only need read access.
   */
 public:
  static std::unique_ptr<AudioSourceTransferBuffer> create(size_t buffer_size);
 
  size_t transfer_data_from_source(TickType_t ticks_to_wait, bool pre_shift = true);
 
  void set_source(const std::weak_ptr<ring_buffer::RingBuffer> &ring_buffer) {
    this->ring_buffer_ = ring_buffer.lock();
  };
 
  // AudioReadableBuffer interface
  const uint8_t *data() const override { return this->data_start_; }
  size_t available() const override { return this->buffer_length_; }
  size_t free() const override;
  void consume(size_t bytes) override { this->decrease_buffer_length(bytes); }
  bool has_buffered_data() const override;
  size_t fill(TickType_t ticks_to_wait) override { return this->transfer_data_from_source(ticks_to_wait); }
  size_t fill(TickType_t ticks_to_wait, bool pre_shift) override {
    return this->transfer_data_from_source(ticks_to_wait, pre_shift);
  }
};
#pragma GCC diagnostic pop
 
class ConstAudioSourceBuffer : public AudioReadableBuffer {
 public:
  void set_data(const uint8_t *data, size_t length);
 
  // AudioReadableBuffer interface
  const uint8_t *data() const override { return this->data_start_; }
  size_t available() const override { return this->length_; }
  void consume(size_t bytes) override;
  bool has_buffered_data() const override { return this->length_ > 0; }
 
 protected:
  const uint8_t *data_start_{nullptr};
  size_t length_{0};
};
 
class RingBufferAudioSource : public AudioReadableBuffer {
 public:
  static constexpr size_t MAX_ALIGNMENT_BYTES = 8;
 
  static std::unique_ptr<RingBufferAudioSource> create(std::shared_ptr<ring_buffer::RingBuffer> ring_buffer,
                                                       size_t max_fill_bytes, uint8_t alignment_bytes = 1);
 
  ~RingBufferAudioSource() override;
 
  // AudioReadableBuffer interface
  const uint8_t *data() const override { return this->current_data_; }
  size_t available() const override { return this->current_available_; }
  void consume(size_t bytes) override;
  bool has_buffered_data() const override;
  size_t fill(TickType_t ticks_to_wait) override;
  // Keeps the deprecated fill(ticks_to_wait, pre_shift) overload visible. Remove before 2027.5.0.
  using AudioReadableBuffer::fill;
 
  void clear_buffered_data();
 
  size_t expose_padded_partial(size_t frame_bytes);
 
  uint8_t *mutable_data() { return this->current_data_; }
 
 protected:
  explicit RingBufferAudioSource(std::shared_ptr<ring_buffer::RingBuffer> ring_buffer, size_t max_fill_bytes,
                                 uint8_t alignment_bytes)
      : ring_buffer_(std::move(ring_buffer)), max_fill_bytes_(max_fill_bytes), alignment_bytes_(alignment_bytes) {}
 
  void release_item_();
 
  std::shared_ptr<ring_buffer::RingBuffer> ring_buffer_;
  size_t max_fill_bytes_;
 
  void *acquired_item_{nullptr};
  uint8_t *current_data_{nullptr};
 
  // Sub-frame trailing bytes inside the held item that will be copied to splice_buffer_ on release.
  uint8_t *item_trailing_ptr_{nullptr};
 
  // After the currently-exposed splice frame is consumed, fill() will promote this region (the aligned
  // remainder of the new chunk) to the exposed region. queued_length_ == 0 when nothing is queued.
  uint8_t *queued_data_{nullptr};
 
  // Splice buffer holds the start of a partial frame whose remainder lives at the head of the next
  // chunk. While splice_length_ > 0, the buffer is incomplete and waiting for completion bytes.
  uint8_t splice_buffer_[MAX_ALIGNMENT_BYTES];
 
  size_t current_available_{0};
  size_t queued_length_{0};
 
  // item_trailing_length_ and splice_length_ are bounded by MAX_ALIGNMENT_BYTES.
  uint8_t alignment_bytes_;
  uint8_t item_trailing_length_{0};
  uint8_t splice_length_{0};
};
 
}  // namespace esphome::audio
 
#endif