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.

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	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)

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.

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].

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

FadeStream	fade

AudioInfo	info

bool	is_auto_fade = true

bool	meta_active = false

MetaDataID3	meta_out

CopyDecoder	no_decoder {true}

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/3]

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() [2/3]

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() [3/3]

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

Member Function Documentation

◆ 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 PureDataStream, PWMAudioOutput, ChannelFormatConverterStreamT< T >, ChannelFormatConverterStream, NumberFormatConverterStreamT< TFrom, TTo >, NumberFormatConverterStream, FormatConverterStream, Pipeline, ResampleStream, and ResampleStreamT< TInterpolator >.

◆ copy()

size_t copy ( )

inline

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

◆ getStreamCopy()

StreamCopy & getStreamCopy ( )

inline

Provides access to StreamCopy to register additional callbacks callbacks

◆ play()

void play ( )

inline

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

◆ 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

◆ setAudioInfo()

void setAudioInfo ( AudioInfo info )

inlineoverridevirtual

Receives and forwards updated AudioInfo to the chain.

Implements AudioInfoSupport.

◆ setVolume()

bool setVolume ( float volume )

inlineoverridevirtual

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

Reimplemented from VolumeSupport.

◆ volume()

float volume ( )

inlineoverridevirtual

Returns the current volume [0.0, 1.0].

Reimplemented from VolumeSupport.

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/3]

◆ AudioPlayer() [2/3]

◆ AudioPlayer() [3/3]

Member Function Documentation

◆ audioInfo()

◆ audioInfoOut()

◆ copy()

◆ getStreamCopy()

◆ play()

◆ playPath()

◆ setAudioInfo()

◆ setVolume()

◆ volume()