A Stream handles playback for audio produced by a Decoder. More...

#include <Stream.h>

Public Types
using	Callback = std::function< void(Stream &)>

Public Member Functions
	Stream (const std::string &filename, std::unique_ptr< Decoder > decoder, std::unique_ptr< Resampler > resampler)
	Constructs an audio stream from the given file name, decoder and resampler. More...

	Stream (const std::string &filename, std::unique_ptr< Decoder > decoder)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

	Stream (SDL_RWops *rwops, std::unique_ptr< Decoder > decoder, std::unique_ptr< Resampler > resampler, bool closeRw)
	Constructs an audio stream from the given SDL_RWops, decoder and resampler. More...

	Stream (SDL_RWops *rwops, std::unique_ptr< Decoder > decoder, bool closeRw)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

virtual	~Stream ()

	Stream (const Stream &)=delete

auto	operator= (const Stream &) -> Stream &=delete

virtual auto	open () -> bool
	Open the stream and prepare it for playback. More...

virtual auto	play (int iterations=1, std::chrono::microseconds fadeTime={}) -> bool
	Start playback. More...

virtual void	stop (std::chrono::microseconds fadeTime={})
	Stop playback. More...

virtual void	pause (std::chrono::microseconds fadeTime={})
	Pause playback. More...

virtual void	resume (std::chrono::microseconds fadeTime={})
	Resume playback. More...

virtual auto	rewind () -> bool
	Rewind stream to the beginning. More...

virtual void	setVolume (float volume)
	Change playback volume. More...

virtual auto	volume () const -> float
	Get current playback volume. More...

virtual void	setStereoPosition (float position)
	Set stereo position. More...

virtual auto	getStereoPosition () const -> float
	Returns the currently set stereo position. More...

virtual void	mute ()
	Mute the stream. More...

virtual void	unmute ()
	Unmute the stream. More...

virtual auto	isMuted () const -> bool
	Returns true if the stream is muted, false otherwise. More...

virtual auto	isPlaying () const -> bool
	Get current playback state. More...

virtual auto	isPaused () const -> bool
	Get current pause state. More...

virtual auto	duration () const -> std::chrono::microseconds
	Get stream duration. More...

virtual auto	seekToTime (std::chrono::microseconds pos) -> bool
	Seek to a time position in the stream. More...

void	setFinishCallback (Callback func)
	Set a callback for when the stream finishes playback. More...

void	unsetFinishCallback ()
	Removes any finish-playback callback that was previously set. More...

void	setLoopCallback (Callback func)
	Set a callback for when the stream loops. More...

void	unsetLoopCallback ()
	Removes any loop callback that was previously set. More...

void	addProcessor (std::shared_ptr< Processor > processor)
	Add an audio processor to the bottom of the processor list. More...

void	removeProcessor (Processor *processor)
	Remove a processor from the stream. More...

void	clearProcessors ()
	Remove all processors from the stream. More...

Protected Member Functions
void	invokeFinishCallback ()
	Invokes the finish-playback callback, if there is one. More...

void	invokeLoopCallback ()
	Invokes the loop callback, if there is one. More...

Friends
auto	Aulib::init (int, AudioFormat, int, int, const std::string &) -> bool

Detailed Description

A Stream handles playback for audio produced by a Decoder.

All public functions of this class will lock the SDL audio device when they are called, and unlock it when they return. Therefore, it is safe to manipulate a Stream that is currently playing without having to manually lock the SDL audio device.

This class is re-entrant but not thread-safe. You can call functions of this class from different threads only if those calls operate on different objects. If you need to control the same Stream object from multiple threads, you need to synchronize access to that object. This includes Stream destruction, meaning you should not create a Stream in one thread and destroy it in another without synchronization.

Member Typedef Documentation

◆ Callback

using Aulib::Stream::Callback = std::function<void(Stream&)>

Constructor & Destructor Documentation

◆ Stream() [1/5]

Aulib::Stream::Stream	(	const std::string &	filename,
		std::unique_ptr< Decoder >	decoder,
		std::unique_ptr< Resampler >	resampler
	)

explicit

Constructs an audio stream from the given file name, decoder and resampler.

Parameters

filename	File name from which to feed data to the decoder. Must not be null.
decoder	Decoder to use for decoding the contents of the file. Must not be null.
resampler	Resampler to use for converting the sample rate of the audio we get from the decoder. If this is null, then no resampling will be performed.

◆ Stream() [2/5]

Aulib::Stream::Stream	(	const std::string &	filename,
		std::unique_ptr< Decoder >	decoder
	)

explicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ Stream() [3/5]

Aulib::Stream::Stream	(	SDL_RWops *	rwops,
		std::unique_ptr< Decoder >	decoder,
		std::unique_ptr< Resampler >	resampler,
		bool	closeRw
	)

explicit

Constructs an audio stream from the given SDL_RWops, decoder and resampler.

Parameters

rwops	SDL_RWops from which to feed data to the decoder. Must not be null.
decoder	Decoder to use for decoding the contents of the SDL_RWops. Must not be null.
resampler	Resampler to use for converting the sample rate of the audio we get from the decoder. If this is null, then no resampling will be performed.
closeRw	Specifies whether 'rwops' should be automatically closed when the stream is destroyed.

◆ Stream() [4/5]

Aulib::Stream::Stream	(	SDL_RWops *	rwops,
		std::unique_ptr< Decoder >	decoder,
		bool	closeRw
	)

explicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ ~Stream()

virtual Aulib::Stream::~Stream ( )

virtual

◆ Stream() [5/5]

Aulib::Stream::Stream ( const Stream & )

delete

Member Function Documentation

◆ addProcessor()

void Aulib::Stream::addProcessor ( std::shared_ptr< Processor > processor )

Add an audio processor to the bottom of the processor list.

You can add multiple processors. They will be run in the order they were added, each one using the previous processor's output as input. If the processor instance already exists in the processor list, or is a nullptr, the function does nothing.

Parameters

processor The processor to add.

◆ clearProcessors()

void Aulib::Stream::clearProcessors ( )

Remove all processors from the stream.

◆ duration()

virtual auto Aulib::Stream::duration ( ) const -> std::chrono::microseconds

virtual

Get stream duration.

It is possible that for some streams (for example MOD files and some MP3 files), the reported duration can be wrong. For some streams, it might not even be possible to get a duration at all (MIDI files, for example.)

Returns: Stream duration. If the stream does not provide duration information, a zero duration is returned.

◆ getStereoPosition()

virtual auto Aulib::Stream::getStereoPosition ( ) const -> float

virtual

Returns the currently set stereo position.

◆ invokeFinishCallback()

void Aulib::Stream::invokeFinishCallback ( )

protected

Invokes the finish-playback callback, if there is one.

In your subclass, you must call this function whenever your stream stops playing.

◆ invokeLoopCallback()

void Aulib::Stream::invokeLoopCallback ( )

protected

Invokes the loop callback, if there is one.

In your subclass, you must call this function whenever your stream loops.

◆ isMuted()

virtual auto Aulib::Stream::isMuted ( ) const -> bool

virtual

Returns true if the stream is muted, false otherwise.

◆ isPaused()

virtual auto Aulib::Stream::isPaused ( ) const -> bool

virtual

Get current pause state.

Note that a stream that is not in playback state is not considered paused. This will return false even for streams where playback is stopped.

Returns

Return values

true	The stream is currently paused.
false	The stream is currently not paused.

◆ isPlaying()

virtual auto Aulib::Stream::isPlaying ( ) const -> bool

virtual

Get current playback state.

Note that a paused stream is still considered as being in the playback state.

Returns

Return values

true	Playback has been started.
false	Playback has not been started yet, or was stopped.

◆ mute()

virtual void Aulib::Stream::mute ( )

virtual

Mute the stream.

A muted stream still accepts volume changes, but it will stay inaudible until it is unmuted.

◆ open()

virtual auto Aulib::Stream::open ( ) -> bool

virtual

Open the stream and prepare it for playback.

Although calling this function is not required, you can use it in order to determine whether the stream can be loaded successfully prior to starting playback.

Returns

Return values

true	Stream was opened successfully.
false	The stream could not be opened.

◆ operator=()

auto Aulib::Stream::operator= ( const Stream & ) -> Stream &=delete

delete

◆ pause()

virtual void Aulib::Stream::pause ( std::chrono::microseconds fadeTime = {} )

virtual

Pause playback.

Parameters

fadeTime Fade-out over the specified amount of time.

◆ play()

virtual auto Aulib::Stream::play	(	int	iterations = `1`,
		std::chrono::microseconds	fadeTime = `{}`
	)		-> bool

virtual

Start playback.

Parameters

iterations	The amount of times the stream should be played. If zero, the stream will loop forever.
fadeTime	Fade-in over the specified amount of time.

Returns

Return values

true	Playback was started successfully, or it was already started.
false	Playback could not be started.

◆ removeProcessor()

void Aulib::Stream::removeProcessor ( Processor * processor )

Remove a processor from the stream.

If the processor instance is not found, the function does nothing.

Parameters

processor Processor to remove.

◆ resume()

virtual void Aulib::Stream::resume ( std::chrono::microseconds fadeTime = {} )

virtual

Resume playback.

Parameters

fadeTime Fade-in over the specified amount of time.

◆ rewind()

virtual auto Aulib::Stream::rewind ( ) -> bool

virtual

Rewind stream to the beginning.

Returns

Return values

true	Stream was rewound successfully.
false	Stream could not be rewound.

◆ seekToTime()

virtual auto Aulib::Stream::seekToTime ( std::chrono::microseconds pos ) -> bool

virtual

Seek to a time position in the stream.

This will change the current playback position in the stream to the specified time.

Note that for some streams (for example MOD files and some MP3 files), it might not be possible to do an accurate seek, in which case the position that is set might be off by some margin. In some streams, seeking is not possible at all (MIDI files, for example.)

Parameters

pos	Position to seek to.

Returns

Return values

true	The playback position was changed successfully.
false	This stream does not support seeking.

◆ setFinishCallback()

void Aulib::Stream::setFinishCallback ( Callback func )

Set a callback for when the stream finishes playback.

The callback will be called when the stream finishes playing. This can happen when you manually stop it, or when it finishes playing on its own.

Parameters

func	Anything that can be wrapped by an std::function (like a function pointer, functor or lambda.)

◆ setLoopCallback()

void Aulib::Stream::setLoopCallback ( Callback func )

Set a callback for when the stream loops.

The callback will be called when the stream loops. It will be called once per loop.

Parameters

func	Anything that can be wrapped by an std::function (like a function pointer, functor or lambda.)

◆ setStereoPosition()

virtual void Aulib::Stream::setStereoPosition ( float position )

virtual

Set stereo position.

This only attenuates the left or right channel. It does not mix one into the other. For example, when setting the position of a stereo stream all the way to the right, the left channel will be completely inaudible. It will not be mixed into the right channel.

Parameters

position Must be between -1.0 (all the way to the left) and 1.0 (all the way to the right) with 0 being the center position.

◆ setVolume()

virtual void Aulib::Stream::setVolume ( float volume )

virtual

Change playback volume.

Parameters

volume 0.0 means total silence, while 1.0 means non-attenuated, 100% (0db) volume. Values above 1.0 are possible and will result in gain being applied (which might result in distortion.) For example, 3.5 would result in 350% percent volume. There is no upper limit.

◆ stop()

virtual void Aulib::Stream::stop ( std::chrono::microseconds fadeTime = {} )

virtual

Stop playback.

When calling this, the stream is reset to the beginning again.

Parameters

fadeTime Fade-out over the specified amount of time.

◆ unmute()

virtual void Aulib::Stream::unmute ( )

virtual

Unmute the stream.

◆ unsetFinishCallback()

void Aulib::Stream::unsetFinishCallback ( )

Removes any finish-playback callback that was previously set.

◆ unsetLoopCallback()

void Aulib::Stream::unsetLoopCallback ( )

Removes any loop callback that was previously set.

◆ volume()

virtual auto Aulib::Stream::volume ( ) const -> float

virtual

Get current playback volume.

Returns: Current playback volume.

Friends And Related Function Documentation

◆ Aulib::init

auto Aulib::init	(	int	,
		AudioFormat	,
		int	,
		int	,
		const std::string &
	)		-> bool

friend

Public Types

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ Callback

Constructor & Destructor Documentation

◆ Stream() [1/5]

◆ Stream() [2/5]

◆ Stream() [3/5]

◆ Stream() [4/5]

◆ ~Stream()

◆ Stream() [5/5]

Member Function Documentation

◆ addProcessor()

◆ clearProcessors()

◆ duration()

◆ getStereoPosition()

◆ invokeFinishCallback()

◆ invokeLoopCallback()

◆ isMuted()

◆ isPaused()

◆ isPlaying()

◆ mute()

◆ open()

◆ operator=()

◆ pause()

◆ play()

◆ removeProcessor()

◆ resume()

◆ rewind()

◆ seekToTime()

◆ setFinishCallback()

◆ setLoopCallback()

◆ setStereoPosition()

◆ setVolume()

◆ stop()

◆ unmute()

◆ unsetFinishCallback()

◆ unsetLoopCallback()

◆ volume()

Friends And Related Function Documentation

◆ Aulib::init