High-level audio playback pipeline and controller. More...

#include <AudioPlayer.h>

Inheritance diagram for AudioPlayer:

Public Member Functions
	AudioPlayer ()
	Default constructor.

	AudioPlayer (AudioPlayer const &)=delete
	Non-copyable: copy constructor is deleted.

	AudioPlayer (AudioSource &source, AudioOutput &output, AudioDecoder &decoder)
	Construct a new Audio Player object. The processing chain is AudioSource -> Stream-copy -> EncodedAudioStream -> VolumeStream -> FadeStream -> Print.

	AudioPlayer (AudioSource &source, AudioStream &output, AudioDecoder &decoder)
	Construct a new Audio Player object. The processing chain is AudioSource -> Stream-copy -> EncodedAudioStream -> VolumeStream -> FadeStream -> Print.

	AudioPlayer (AudioSource &source, Print &output, AudioDecoder &decoder, AudioInfoSupport *notify=nullptr)
	Construct a new Audio Player object. The processing chain is AudioSource -> Stream-copy -> EncodedAudioStream -> VolumeStream -> FadeStream -> Print.

void	addNotifyAudioChange (AudioInfoSupport *notify)
	Adds/updates a listener notified on audio info changes.

AudioInfo	audioInfo () override
	Returns the current AudioInfo of the playback chain.

virtual AudioInfo	audioInfoOut ()

AudioSource &	audioSource ()
	Returns the active AudioSource.

bool	begin (int index=0, bool isActive=true)
	Starts or restarts playback from the first or given stream index.

void	clearBuffers (bool drainSource=false)

size_t	copy ()

size_t	copy (size_t bytes)
	Copies the requested bytes from source to decoder (call in loop)

size_t	copyAll ()
	Copies until source is exhausted (blocking)

void	end ()
	Ends playback and resets decoder/intermediate stages.

Stream *	getStream ()
	Returns the currently active input Stream (e.g., file)

StreamCopy &	getStreamCopy ()

VolumeStream &	getVolumeStream ()
	Returns the VolumeStream used by the player.

bool	isActive ()
	Checks whether playback is active.

bool	isAutoFade ()
	Checks whether automatic fade in/out is enabled.

bool	isMuted ()
	Returns true if the player is currently muted.

bool	isSilenceOnInactive ()
	Returns whether silence-on-inactive is enabled.

bool	next (int offset=1)
	Moves to the next/previous stream by offset (negative supported)

	operator bool ()
	Boolean conversion returns isActive()

AudioPlayer &	operator= (AudioPlayer const &)=delete
	Non-assignable: assignment operator is deleted.

void	play ()

bool	playFile (const char *path)
	Obsolete: use PlayPath!

bool	playPath (const char *path)

bool	previous (int offset=1)
	Moves back by offset streams (defaults to 1)

void	setActive (bool isActive)
	Toggles playback activity; triggers fade and optional silence.

void	setAudioInfo (AudioInfo info) override
	Receives and forwards updated AudioInfo to the chain.

void	setAudioSource (AudioSource &source)
	Sets or replaces the AudioSource.

void	setAutoFade (bool active)
	Enables/disables automatic fade in/out to prevent pops.

void	setAutoNext (bool next)
	Enables/disables auto-advance at end/timeout (overrides AudioSource)

void	setBufferSize (int size)
	Sets the internal copy buffer size (bytes)

void	setDecoder (AudioDecoder &decoder)
	Sets or replaces the AudioDecoder.

void	setDelayIfOutputFull (int delayMs)
	Sets delay (ms) to wait when output is full.

bool	setIndex (int idx)
	Selects stream by absolute index in the source.

void	setMetadataCallback (void(callback)(MetaDataType type, const char str, int len), ID3TypeSelection sel=SELECT_ID3)
	Defines the metadata callback.

void	setMetaDataSize (int size)
	Sets the maximum ID3 metadata buffer size (default 256)

bool	setMuted (bool muted)
	Mutes or unmutes the audio player.

void	setOnEOFCallback (void(*callback)(AudioPlayer &player))

void	setOnStreamChangeCallback (void(callback)(Stream stream_ptr, void *reference))
	Defines a callback that is called when the stream is changed.

void	setOutput (AudioOutput &output)
	Sets the final output to an AudioOutput (adds Volume/Fade for PCM)

void	setOutput (AudioStream &output)
	Sets the final output to an AudioStream (adds Volume/Fade for PCM)

void	setOutput (Print &output)
	Sets the final output to a Print (adds Volume/Fade for PCM)

bool	setPath (const char *path)
	Selects stream by path without changing the source iterator.

void	setReference (void *ref)
	Sets a user reference passed to the stream-change callback.

void	setSilenceOnInactive (bool active)
	When enabled, writes zeros while inactive to keep sinks alive.

bool	setStream (Stream *input)
	Activates the provided Stream as current input.

bool	setVolume (float volume) override
	Sets volume in range [0.0, 1.0]; updates VolumeStream.

bool	setVolume (float volume, int channel)
	Defines the volume for the indicated channel.

void	setVolumeControl (VolumeControl &vc)
	Sets a custom VolumeControl implementation.

void	stop ()
	Halts playback; equivalent to setActive(false)

float	volume () override
	Returns the current volume [0.0, 1.0].

float	volume (int channel)
	Returns the current volume for the indicated channel.

void	writeSilence (size_t bytes)
	Writes the requested number of zero bytes to the output.

Protected Member Functions
void	moveToNextFileOnTimeout ()

void	setupFade ()

void	writeEnd ()

Static Protected Member Functions
static void	decodeMetaData (void obj, void data, size_t len)
	Callback implementation which writes to metadata.

Protected Attributes
bool	active = false

bool	autonext = true

StreamCopy	copier

float	current_volume = -1.0f

int	delay_if_full = 100

bool	eof_called = false

FadeStream	fade

AudioInfo	info

bool	is_auto_fade = true

bool	meta_active = false

MetaDataID3	meta_out

float	muted_volume = 0.0f

CopyDecoder	no_decoder {true}

void(*	on_eof_callback )(AudioPlayer &player) = nullptr

void(*	on_stream_change_callback )(Stream stream_ptr, void reference) = nullptr

EncodedAudioOutput	out_decoding

AudioDecoder *	p_decoder = &no_decoder

AudioInfoSupport *	p_final_notify = nullptr

AudioOutput *	p_final_print = nullptr

AudioStream *	p_final_stream = nullptr

Stream *	p_input_stream = nullptr

void *	p_reference = nullptr

AudioSource *	p_source = nullptr

bool	silence_on_inactive = false

int	stream_increment = 1

uint32_t	timeout = 0

VolumeStream	volume_out

float	volume_value = 1.0f

Detailed Description

High-level audio playback pipeline and controller.

Provides pull-driven playback from an AudioSource through optional decoding, volume control and click-free fades to an AudioOutput/AudioStream/Print.

Features:

Playback control: begin, play, stop, next, previous, setIndex
PCM and encoded formats via AudioDecoder with dynamic audio info updates
Volume management (0.0–1.0) with pluggable VolumeControl
Auto-fade in/out to avoid pops; optional silence while inactive
Auto-advance on timeout with forward/backward navigation
Metadata: ICY (via source) or ID3 (internal MetaDataID3)
Callbacks: metadata updates and stream-change notification
Flow control: adjustable copy buffer and optional delay when output is full

Pipeline: AudioSource → StreamCopy → EncodedAudioOutput → VolumeStream → FadeStream → Output.

Operation model: call copy() regularly (non-blocking) or copyAll() for blocking end-to-end playback.

Author: Phil Schatzmann

Copyright: GPLv3

Constructor & Destructor Documentation

◆ AudioPlayer() [1/5]

AudioPlayer ( )

inline

Default constructor.

◆ AudioPlayer() [2/5]

AudioPlayer	(	AudioSource &	source,
		AudioOutput &	output,
		AudioDecoder &	decoder
	)

inline

Construct a new Audio Player object. The processing chain is AudioSource -> Stream-copy -> EncodedAudioStream -> VolumeStream -> FadeStream -> Print.

Parameters

source
output
decoder

◆ AudioPlayer() [3/5]

AudioPlayer	(	AudioSource &	source,
		Print &	output,
		AudioDecoder &	decoder,
		AudioInfoSupport *	notify = `nullptr`
	)

inline

Construct a new Audio Player object. The processing chain is AudioSource -> Stream-copy -> EncodedAudioStream -> VolumeStream -> FadeStream -> Print.

Parameters

source
output
decoder
notify

◆ AudioPlayer() [4/5]

AudioPlayer	(	AudioSource &	source,
		AudioStream &	output,
		AudioDecoder &	decoder
	)

inline

Construct a new Audio Player object. The processing chain is AudioSource -> Stream-copy -> EncodedAudioStream -> VolumeStream -> FadeStream -> Print.

Parameters

source
output
decoder

◆ AudioPlayer() [5/5]

AudioPlayer ( AudioPlayer const & )

delete

Non-copyable: copy constructor is deleted.

Member Function Documentation

◆ addNotifyAudioChange()

void addNotifyAudioChange ( AudioInfoSupport * notify )

inline

Adds/updates a listener notified on audio info changes.

◆ audioInfo()

AudioInfo audioInfo ( )

inlineoverridevirtual

Returns the current AudioInfo of the playback chain.

Implements AudioInfoSupport.

◆ audioInfoOut()

virtual AudioInfo audioInfoOut ( )

inlinevirtualinherited

provides the actual output AudioInfo: this is usually the same as audioInfo() unless we use a transforming stream

Reimplemented in MP3EncoderShine, PureDataStream, PWMAudioOutput< PWMDriverT >, ChannelFormatConverterStreamT< T >, ChannelFormatConverterStream, NumberFormatConverterStreamT< TFrom, TTo >, NumberFormatConverterStream, FormatConverterStream, Pipeline, ResampleStream, ResampleStreamT< TInterpolator >, and SupportedRatesStream.

◆ audioSource()

AudioSource & audioSource ( )

inline

Returns the active AudioSource.

◆ begin()

bool begin	(	int	index = `0`,
		bool	isActive = `true`
	)

inline

Starts or restarts playback from the first or given stream index.

◆ clearBuffers()

void clearBuffers ( bool drainSource = false )

inline

Resets the decoder's internal state (bit reservoir, frame buffers, etc.) without touching the current AudioSource/stream or its read position. Optionally also discards audio bytes that piled up in the input stream while paused (drainSource=true).

Use this between stop() and play() for a streaming source (internet radio, HTTP, ICY) where resuming should mean "continue from now", not "replay whatever arrived while paused". Call it either right after stop() (drains what came in during the pause) or right before play() (drains what accumulated since) - both work, since nothing is being actively read while inactive anyway.

Not needed for a local file: the default stop()/play() behavior (freeze position, resume exactly where you left off) is what you normally want there, and drainSource=true would just throw away audio you'd otherwise still hear.

Parameters

drainSource if true, also discard bytes already buffered by the input stream (e.g. a live source's socket backlog)

◆ copy() [1/2]

size_t copy ( )

inline

Copies DEFAULT_BUFFER_SIZE (=1024 bytes) from the source to the decoder: Call this method in the loop.

◆ copy() [2/2]

size_t copy ( size_t bytes )

inline

Copies the requested bytes from source to decoder (call in loop)

◆ copyAll()

size_t copyAll ( )

inline

Copies until source is exhausted (blocking)

◆ decodeMetaData()

static void decodeMetaData	(	void *	obj,
		void *	data,
		size_t	len
	)

inlinestaticprotected

Callback implementation which writes to metadata.

◆ end()

void end ( )

inline

Ends playback and resets decoder/intermediate stages.

◆ getStream()

Stream * getStream ( )

inline

Returns the currently active input Stream (e.g., file)

◆ getStreamCopy()

StreamCopy & getStreamCopy ( )

inline

Provides access to StreamCopy to register additional callbacks callbacks

◆ getVolumeStream()

VolumeStream & getVolumeStream ( )

inline

Returns the VolumeStream used by the player.

◆ isActive()

bool isActive ( )

inline

Checks whether playback is active.

◆ isAutoFade()

bool isAutoFade ( )

inline

Checks whether automatic fade in/out is enabled.

◆ isMuted()

bool isMuted ( )

inline

Returns true if the player is currently muted.

◆ isSilenceOnInactive()

bool isSilenceOnInactive ( )

inline

Returns whether silence-on-inactive is enabled.

◆ moveToNextFileOnTimeout()

void moveToNextFileOnTimeout ( )

inlineprotected

◆ next()

bool next ( int offset = 1 )

inline

Moves to the next/previous stream by offset (negative supported)

◆ operator bool()

operator bool ( )

inline

Boolean conversion returns isActive()

◆ operator=()

AudioPlayer & operator= ( AudioPlayer const & )

delete

Non-assignable: assignment operator is deleted.

◆ play()

void play ( )

inline

starts / resumes the playing after calling stop(): same as setActive(true) Resumes playback after stop(); equivalent to setActive(true)

◆ playFile()

bool playFile ( const char * path )

inline

Obsolete: use PlayPath!

◆ playPath()

bool playPath ( const char * path )

inline

plays a complete audio file or url from start to finish (blocking call)

Parameters

path	path to the audio file or url to play (depending on source)

Returns: true if file was found and played successfully, false otherwise

◆ previous()

bool previous ( int offset = 1 )

inline

Moves back by offset streams (defaults to 1)

◆ setActive()

void setActive ( bool isActive )

inline

Toggles playback activity; triggers fade and optional silence.

◆ setAudioInfo()

void setAudioInfo ( AudioInfo info )

inlineoverridevirtual

Receives and forwards updated AudioInfo to the chain.

Implements AudioInfoSupport.

◆ setAudioSource()

void setAudioSource ( AudioSource & source )

inline

Sets or replaces the AudioSource.

◆ setAutoFade()

void setAutoFade ( bool active )

inline

Enables/disables automatic fade in/out to prevent pops.

◆ setAutoNext()

void setAutoNext ( bool next )

inline

Enables/disables auto-advance at end/timeout (overrides AudioSource)

◆ setBufferSize()

void setBufferSize ( int size )

inline

Sets the internal copy buffer size (bytes)

◆ setDecoder()

void setDecoder ( AudioDecoder & decoder )

inline

Sets or replaces the AudioDecoder.

◆ setDelayIfOutputFull()

void setDelayIfOutputFull ( int delayMs )

inline

Sets delay (ms) to wait when output is full.

◆ setIndex()

bool setIndex ( int idx )

inline

Selects stream by absolute index in the source.

◆ setMetadataCallback()

void setMetadataCallback	(	void()(MetaDataType type, const char str, int len)	callback,
		ID3TypeSelection	sel = `SELECT_ID3`
	)

inline

Defines the metadata callback.

◆ setMetaDataSize()

void setMetaDataSize ( int size )

inline

Sets the maximum ID3 metadata buffer size (default 256)

◆ setMuted()

bool setMuted ( bool muted )

inline

Mutes or unmutes the audio player.

◆ setOnEOFCallback()

void setOnEOFCallback ( void(*)(AudioPlayer &player) callback )

inline

Defines a callback that is invoked exactly once when the current stream reaches EOF (no more bytes can be read from the input stream). Signature: void onEOF(AudioPlayer& player)

◆ setOnStreamChangeCallback()

void setOnStreamChangeCallback ( void(*)(Stream *stream_ptr, void *reference) callback )

inline

Defines a callback that is called when the stream is changed.

◆ setOutput() [1/3]

void setOutput ( AudioOutput & output )

inline

Sets the final output to an AudioOutput (adds Volume/Fade for PCM)

◆ setOutput() [2/3]

void setOutput ( AudioStream & output )

inline

Sets the final output to an AudioStream (adds Volume/Fade for PCM)

◆ setOutput() [3/3]

void setOutput ( Print & output )

inline

Sets the final output to a Print (adds Volume/Fade for PCM)

◆ setPath()

bool setPath ( const char * path )

inline

Selects stream by path without changing the source iterator.

◆ setReference()

void setReference ( void * ref )

inline

Sets a user reference passed to the stream-change callback.

◆ setSilenceOnInactive()

void setSilenceOnInactive ( bool active )

inline

When enabled, writes zeros while inactive to keep sinks alive.

◆ setStream()

bool setStream ( Stream * input )

inline

Activates the provided Stream as current input.

◆ setupFade()

void setupFade ( )

inlineprotected

◆ setVolume() [1/2]

bool setVolume ( float volume )

inlineoverridevirtual

Sets volume in range [0.0, 1.0]; updates VolumeStream.

Reimplemented from VolumeSupport.

◆ setVolume() [2/2]

bool setVolume	(	float	volume,
		int	channel
	)

inline

Defines the volume for the indicated channel.

◆ setVolumeControl()

void setVolumeControl ( VolumeControl & vc )

inline

Sets a custom VolumeControl implementation.

◆ stop()

void stop ( )

inline

Halts playback; equivalent to setActive(false)

◆ volume() [1/2]

float volume ( )

inlineoverridevirtual

Returns the current volume [0.0, 1.0].

Reimplemented from VolumeSupport.

◆ volume() [2/2]

float volume ( int channel )

inline

Returns the current volume for the indicated channel.

◆ writeEnd()

void writeEnd ( )

inlineprotected

◆ writeSilence()

void writeSilence ( size_t bytes )

inline

Writes the requested number of zero bytes to the output.

Member Data Documentation

◆ active

bool active = false

protected

◆ autonext

bool autonext = true

protected

◆ copier

StreamCopy copier

protected

◆ current_volume

float current_volume = -1.0f

protected

◆ delay_if_full

int delay_if_full = 100

protected

◆ eof_called

bool eof_called = false

protected

◆ fade

FadeStream fade

protected

◆ info

AudioInfo info

protected

◆ is_auto_fade

bool is_auto_fade = true

protected

◆ meta_active

bool meta_active = false

protected

◆ meta_out

MetaDataID3 meta_out

protected

◆ muted_volume

float muted_volume = 0.0f

protected

◆ no_decoder

CopyDecoder no_decoder {true}

protected

◆ on_eof_callback

void(* on_eof_callback) (AudioPlayer &player) = nullptr

protected

◆ on_stream_change_callback

void(* on_stream_change_callback) (Stream *stream_ptr, void *reference) = nullptr

protected

◆ out_decoding

EncodedAudioOutput out_decoding

protected

◆ p_decoder

AudioDecoder* p_decoder = &no_decoder

protected

◆ p_final_notify

AudioInfoSupport* p_final_notify = nullptr

protected

◆ p_final_print

AudioOutput* p_final_print = nullptr

protected

◆ p_final_stream

AudioStream* p_final_stream = nullptr

protected

◆ p_input_stream

Stream* p_input_stream = nullptr

protected

◆ p_reference

void* p_reference = nullptr

protected

◆ p_source

AudioSource* p_source = nullptr

protected

◆ silence_on_inactive

bool silence_on_inactive = false

protected

◆ stream_increment

int stream_increment = 1

protected

◆ timeout

uint32_t timeout = 0

protected

◆ volume_out

VolumeStream volume_out

protected

◆ volume_value

float volume_value = 1.0f

protectedinherited

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

src/AudioTools/CoreAudio/AudioPlayer.h

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ AudioPlayer() [1/5]

◆ AudioPlayer() [2/5]

◆ AudioPlayer() [3/5]

◆ AudioPlayer() [4/5]

◆ AudioPlayer() [5/5]

Member Function Documentation

◆ addNotifyAudioChange()

◆ audioInfo()

◆ audioInfoOut()

◆ audioSource()

◆ begin()

◆ clearBuffers()

◆ copy() [1/2]

◆ copy() [2/2]

◆ copyAll()

◆ decodeMetaData()

◆ end()

◆ getStream()

◆ getStreamCopy()

◆ getVolumeStream()

◆ isActive()

◆ isAutoFade()

◆ isMuted()

◆ isSilenceOnInactive()

◆ moveToNextFileOnTimeout()

◆ next()

◆ operator bool()

◆ operator=()

◆ play()

◆ playFile()

◆ playPath()

◆ previous()

◆ setActive()

◆ setAudioInfo()

◆ setAudioSource()

◆ setAutoFade()

◆ setAutoNext()

◆ setBufferSize()

◆ setDecoder()

◆ setDelayIfOutputFull()

◆ setIndex()

◆ setMetadataCallback()

◆ setMetaDataSize()

◆ setMuted()

◆ setOnEOFCallback()

◆ setOnStreamChangeCallback()

◆ setOutput() [1/3]

◆ setOutput() [2/3]

◆ setOutput() [3/3]

◆ setPath()

◆ setReference()

◆ setSilenceOnInactive()

◆ setStream()

◆ setupFade()

◆ setVolume() [1/2]

◆ setVolume() [2/2]

◆ setVolumeControl()

◆ stop()

◆ volume() [1/2]

◆ volume() [2/2]

◆ writeEnd()

◆ writeSilence()

Member Data Documentation

◆ active

◆ autonext

◆ copier

◆ current_volume

◆ delay_if_full

◆ eof_called

◆ fade

◆ info

◆ is_auto_fade

◆ meta_active

◆ meta_out