media_source.h

Go to the documentation of this file.

#pragma once
 
#include "esphome/components/audio/audio.h"
#include "esphome/core/helpers.h"
 
#include <cstdint>
#include <string>
 
namespace esphome::media_source {
 
enum class MediaSourceState : uint8_t {
  IDLE,     // Not playing, ready to accept play_uri
  PLAYING,  // Currently playing media
  PAUSED,   // Playback paused, can be resumed
  ERROR,    // Error occurred during playback; sources are responsible for logging their own error details
};
 
enum class MediaSourceCommand : uint8_t {
  // All sources should support these basic commands.
  PLAY,
  PAUSE,
  STOP,
 
  // Only sources with internal playlists will handle these; simple sources should ignore them.
  NEXT,
  PREVIOUS,
  CLEAR_PLAYLIST,
  REPEAT_ALL,
  REPEAT_ONE,
  REPEAT_OFF,
  SHUFFLE,
  UNSHUFFLE,
};
 
class MediaSourceListener {
 public:
  virtual ~MediaSourceListener() = default;
 
  // Callbacks that all sources use to send data and state changes to the orchestrator.
  virtual size_t write_audio(const uint8_t *data, size_t length, uint32_t timeout_ms,
                             const audio::AudioStreamInfo &stream_info) = 0;
  virtual void report_state(MediaSourceState state) = 0;
 
  // Callbacks from smart sources requesting the orchestrator to change volume, mute, or start a new URI.
  // Simple sources never invoke these.
  virtual void request_volume(float volume) {}
  virtual void request_mute(bool is_muted) {}
  virtual void request_play_uri(const std::string &uri) {}
};
 
class MediaSource {
 public:
  virtual ~MediaSource() = default;
 
  // === Playback Control ===
 
  virtual bool play_uri(const std::string &uri) = 0;
 
  virtual void handle_command(MediaSourceCommand command) = 0;
 
  virtual bool has_internal_playlist() const { return false; }
 
  // === State Access ===
 
  MediaSourceState get_state() const { return this->state_; }
 
  // === URI Matching ===
 
  virtual bool can_handle(const std::string &uri) const = 0;
 
  // === Listener: Source -> Orchestrator ===
 
  void set_listener(MediaSourceListener *listener) { this->listener_ = listener; }
 
  bool has_listener() const { return this->listener_ != nullptr; }
 
  size_t write_output(const uint8_t *data, size_t length, uint32_t timeout_ms,
                      const audio::AudioStreamInfo &stream_info) {
    if (this->listener_ != nullptr) {
      return this->listener_->write_audio(data, length, timeout_ms, stream_info);
    }
    return 0;
  }
 
  // === Callbacks: Orchestrator -> Source ===
 
  virtual void notify_volume_changed(float volume) {}
 
  virtual void notify_mute_changed(bool is_muted) {}
 
  virtual void notify_audio_played(uint32_t frames, int64_t timestamp) {}
 
 protected:
  void set_state_(MediaSourceState state) {
    if (this->state_ != state) {
      this->state_ = state;
      if (this->listener_ != nullptr) {
        this->listener_->report_state(state);
      }
    }
  }
 
 private:
  // Private to enforce the invariant that listener notifications always fire on state changes.
  // All state transitions must go through set_state_() which couples the update with notification.
  MediaSourceState state_{MediaSourceState::IDLE};
  MediaSourceListener *listener_{nullptr};
};
 
}  // namespace esphome::media_source