Abstract base class for media sources MediaSource provides audio data to an orchestrator via the MediaSourceListener interface. More...

#include <media_source.h>

Inheritance diagram for esphome::media_source::MediaSource:

Public Member Functions
virtual	~MediaSource ()=default

virtual bool	play_uri (const std::string &uri)=0
	Start playing the given URI Sources should validate the URI and state, returning false if the source is busy.

virtual void	handle_command (MediaSourceCommand command)=0
	Handle playback commands; e.g., pause, stop, next, etc.

virtual bool	has_internal_playlist () const
	Whether this source manages its own playlist internally Smart sources that handle next/previous/repeat/shuffle should override this to return true.

MediaSourceState	get_state () const
	Get current playback state.

virtual bool	can_handle (const std::string &uri) const =0
	Check if this source can handle the given URI Each source must override this to match its supported URI scheme(s).

void	set_listener (MediaSourceListener *listener)
	Set the listener that receives callbacks from this source.

bool	has_listener () const
	Check if a listener has been registered.

size_t	write_output (const uint8_t *data, size_t length, uint32_t timeout_ms, const audio::AudioStreamInfo &stream_info)
	Write audio data to the listener.

virtual void	notify_volume_changed (float volume)
	Notify the source that volume changed Simple sources ignore this.

virtual void	notify_mute_changed (bool is_muted)
	Notify the source that mute state changed Simple sources ignore this.

virtual void	notify_audio_played (uint32_t frames, int64_t timestamp)
	Notify the source about audio that has been played Called when the speaker reports that audio frames have been written to the DAC.

Protected Member Functions
void	set_state_ (MediaSourceState state)
	Update state and notify listener This is the only way to change state_, ensuring listener notifications always fire.

Detailed Description

Abstract base class for media sources MediaSource provides audio data to an orchestrator via the MediaSourceListener interface.

It also receives commands from the orchestrator to control playback.

Definition at line 61 of file media_source.h.

Constructor & Destructor Documentation

◆ ~MediaSource()

virtual esphome::media_source::MediaSource::~MediaSource ( )

virtualdefault

Member Function Documentation

◆ can_handle()

virtual bool esphome::media_source::MediaSource::can_handle ( const std::string & uri ) const

pure virtual

Check if this source can handle the given URI Each source must override this to match its supported URI scheme(s).

Parameters

uri	URI to check

Returns: true if this source can handle the URI

Implemented in esphome::audio_file::AudioFileMediaSource.

◆ get_state()

MediaSourceState esphome::media_source::MediaSource::get_state ( ) const

inline

Get current playback state.

Note: Must only be called from the main loop.

Returns: Current state of this source

Definition at line 89 of file media_source.h.

◆ handle_command()

virtual void esphome::media_source::MediaSource::handle_command ( MediaSourceCommand command )

pure virtual

Handle playback commands; e.g., pause, stop, next, etc.

Note: Must only be called from the main loop.

Parameters

command Command to execute

Implemented in esphome::audio_file::AudioFileMediaSource.

◆ has_internal_playlist()

virtual bool esphome::media_source::MediaSource::has_internal_playlist ( ) const

inlinevirtual

Whether this source manages its own playlist internally Smart sources that handle next/previous/repeat/shuffle should override this to return true.

Definition at line 82 of file media_source.h.

◆ has_listener()

bool esphome::media_source::MediaSource::has_listener ( ) const

inline

Check if a listener has been registered.

Definition at line 106 of file media_source.h.

◆ notify_audio_played()

virtual void esphome::media_source::MediaSource::notify_audio_played	(	uint32_t	frames,
		int64_t	timestamp )

inlinevirtual

Notify the source about audio that has been played Called when the speaker reports that audio frames have been written to the DAC.

Sources can override this to track playback progress for synchronization.

Parameters

frames	Number of audio frames that were played
timestamp	System time in microseconds when the frames finished writing to the DAC

Definition at line 139 of file media_source.h.

◆ notify_mute_changed()

virtual void esphome::media_source::MediaSource::notify_mute_changed ( bool is_muted )

inlinevirtual

Notify the source that mute state changed Simple sources ignore this.

Override for smart sources that track mute state.

Parameters

is_muted New mute state

Definition at line 132 of file media_source.h.

◆ notify_volume_changed()

virtual void esphome::media_source::MediaSource::notify_volume_changed ( float volume )

inlinevirtual

Notify the source that volume changed Simple sources ignore this.

Override for smart sources that track volume state.

Parameters

volume New volume level (0.0 to 1.0)

Definition at line 127 of file media_source.h.

◆ play_uri()

virtual bool esphome::media_source::MediaSource::play_uri ( const std::string & uri )

pure virtual

Start playing the given URI Sources should validate the URI and state, returning false if the source is busy.

The orchestrator is responsible for stopping active sources before starting a new one.

Note: Must only be called from the main loop.

Parameters

uri	URI to play; e.g., "http://stream_url"

Returns: true if playback started successfully, false otherwise

Implemented in esphome::audio_file::AudioFileMediaSource.

◆ set_listener()

void esphome::media_source::MediaSource::set_listener ( MediaSourceListener * listener )

inline

Set the listener that receives callbacks from this source.

Parameters

listener Pointer to the MediaSourceListener implementation

Definition at line 103 of file media_source.h.

◆ set_state_()

void esphome::media_source::MediaSource::set_state_ ( MediaSourceState state )

inlineprotected

Update state and notify listener This is the only way to change state_, ensuring listener notifications always fire.

Sources running FreeRTOS tasks should signal via event groups and call this from loop().

Note: Must only be called from the main loop.

Parameters

state New state to set

Definition at line 147 of file media_source.h.

◆ write_output()

size_t esphome::media_source::MediaSource::write_output	(	const uint8_t *	data,
		size_t	length,
		uint32_t	timeout_ms,
		const audio::AudioStreamInfo &	stream_info )

inline

Write audio data to the listener.

Parameters

data	Pointer to audio data buffer (not modified by this method)
length	Number of bytes to write
timeout_ms	Milliseconds to wait if the listener can't accept data immediately
stream_info	Audio stream format information

Returns: Number of bytes written, or 0 if no listener is set

Definition at line 114 of file media_source.h.

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

esphome/components/media_source/media_source.h

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~MediaSource()

Member Function Documentation

◆ can_handle()

◆ get_state()

◆ handle_command()

◆ has_internal_playlist()

◆ has_listener()

◆ notify_audio_played()

◆ notify_mute_changed()

◆ notify_volume_changed()

◆ play_uri()

◆ set_listener()

◆ set_state_()

◆ write_output()