A class that handles complex playback of a streaming sound source. More...

#include <omSoundStreamPlayer.h>

Inheritance diagram for om::sound::filters::StreamPlayer:

Public Member Functions
	StreamPlayer ()
	Create a default sound stream player without any stream to play. More...

	StreamPlayer (const Shared< SoundInputStream > &newStream)
	Create a sound stream player which plays from the specified sound input stream. More...

	StreamPlayer (const StreamPlayer &other)
	Create a copy of this stream player and its state. More...

	~StreamPlayer ()
	Destroy a sound stream player and release all resources associated with it. More...

StreamPlayer &	operator= (const StreamPlayer &other)
	Assign the state of one sound stream player to another. More...

const SoundInputStream *	getStream () const
	Return a const pointer to the SoundInputStream that is being used as a sound source. More...

void	setStream (const Shared< SoundInputStream > &newStream)
	Set the SoundInputStream which this player should use as a sound source. More...

Bool	isPlaying () const
	Return whether or not this sound player is current playing. More...

Bool	setIsPlaying (Bool newIsPlaying)
	Set whether or not this sound player should be playing sound. More...

Bool	play ()
	Tell the sound player to start playing the sound from the current position. More...

void	stop ()
	Stop playing the sound and keep the playhead at the last position. More...

Bool	rewind ()
	Reset the playback position to the first position within the stream. More...

Bool	isLooping () const
	Return whether or not this sound player is currently looping. More...

Bool	setIsLooping (Bool newIsLooping)
	Set whether or not this sound player should try to loop its sound source. More...

virtual Bool	canSeek () const
	Return whether or not seeking is allowed in this input stream. More...

virtual Bool	canSeek (Int64 relativeSampleOffset) const
	Return whether or not this input stream's current position can be moved by the specified signed sample offset. More...

virtual Int64	seek (Int64 relativeSampleOffset)
	Move the current sample frame position in the stream by the specified signed amount. More...

virtual SoundSize	getSamplesRemaining () const
	Return the number of samples remaining in the sound input stream. More...

virtual SampleIndex	getPosition () const
	Return the current position of the stream in samples relative to the start of the stream. More...

virtual Size	getChannelCount () const
	Return the number of channels that are in the sound input stream. More...

virtual SampleRate	getSampleRate () const
	Return the sample rate of the sound input stream's source audio data. More...

virtual SampleType	getNativeSampleType () const
	Return the actual sample type used in the stream. More...

virtual Bool	isValid () const
	Return whether or not the stream has a valid source of sound data. More...

virtual UTF8String	getName () const
	Return a human-readable name for this stream player. More...

virtual UTF8String	getManufacturer () const
	Return the manufacturer name of this stream player. More...

virtual FilterVersion	getVersion () const
	Return an object representing the version of this stream player. More...

virtual FilterCategory	getCategory () const
	Return an object that describes the category of effect that this filter implements. More...

virtual Bool	allowsInPlaceProcessing () const
	Return whether or not this stream player can process audio data in-place. More...

Public Member Functions inherited from om::sound::filters::SoundFilter
virtual	~SoundFilter ()
	Destroy this sound filter object. More...

SoundResult	read (SoundBuffer &outputBuffer, Size numSamples)
	Fill the specified output buffer with the requested number of samples, based on internal filter state. More...

SoundResult	read (SoundFrame &outputFrame, Size numSamples)
	Fill the specified output frame with the requested number of samples, based on internal filter state. More...

SoundResult	write (const SoundBuffer &inputBuffer, Size numSamples)
	Process the specified input buffer samples and do something with them. More...

SoundResult	write (const SoundFrame &inputFrame, Size numSamples)
	Process the specified input frame samples and do something with them. More...

SoundResult	process (const SoundBuffer &inputBuffer, SoundBuffer &outputBuffer, Size numSamples)
	Apply this filter to the specified input buffer data, placing the result in the output buffer. More...

SoundResult	process (const SoundBuffer &inputBuffer, SoundFrame &outputFrame, Size numSamples)
	Apply this filter to the specified input buffer data, placing the result in the output frame. More...

SoundResult	process (const SoundFrame &inputFrame, SoundFrame &outputFrame, Size numSamples)
	Apply this filter to the specified input frame data, placing the result in the output frame. More...

SoundResult	process (const SoundFrame &inputBuffer, SoundBuffer &outputBuffer, Size numSamples)
	Apply this filter to the specified input frame data, placing the result in the output buffer. More...

void	reset ()
	Signal to the filter that the audio stream is restarting. More...

UInt64	getFrameIndex () const
	Return the index of the next frame to be processed (or the current one if currently processing). More...

Size	getInputCount () const
	Return the current number of audio inputs that this filter has. More...

virtual UTF8String	getInputName (Index inputIndex) const
	Return a human-readable name of the filter audio input at the specified index. More...

Size	getOutputCount () const
	Return the current number of audio outputs that this filter has. More...

virtual UTF8String	getOutputName (Index outputIndex) const
	Return a human-readable name of the filter audio output at the specified index. More...

Size	getMIDIInputCount () const
	Return the current number of MIDI inputs that this filter has. More...

virtual UTF8String	getMIDIInputName (Index inputIndex) const
	Return a human-readable name of the filter MIDI input at the specified index. More...

Size	getMIDIOutputCount () const
	Return the current number of MIDI outputs that this filter has. More...

virtual UTF8String	getMIDIOutputName (Index outputIndex) const
	Return a human-readable name of the filter MIDI output at the specified index. More...

virtual Time	getLatency () const
	Return a Time value indicating the latency of this sound filter in seconds. More...

virtual Size	getParameterCount () const
	Return the total number of generic accessible parameters this filter has. More...

virtual Bool	getParameterIndex (const UTF8String &parameterName, Index &parameterIndex) const
	Query the index of the parameter with the specified name. More...

virtual Bool	getParameterInfo (Index parameterIndex, FilterParameterInfo &info) const
	Get information about the filter parameter at the specified index. More...

virtual Bool	getParameterValueName (Index parameterIndex, const FilterParameter &value, UTF8String &name) const
	Get any special name associated with the specified value of an indexed parameter. More...

Bool	getParameter (Index parameterIndex, FilterParameter &value) const
	Place the value of the parameter at the specified index in the output parameter. More...

Bool	getParameter (Index parameterIndex, Bool &value) const
	Place the value of the parameter at the specified index in the output parameter. More...

Bool	getParameter (Index parameterIndex, Int64 &value) const
	Place the value of the parameter at the specified index in the output parameter. More...

Bool	getParameter (Index parameterIndex, Float32 &value) const
	Place the value of the parameter at the specified index in the output parameter. More...

Bool	getParameter (Index parameterIndex, Float64 &value) const
	Place the value of the parameter at the specified index in the output parameter. More...

template<typename ParameterType >
Bool	getParameter (const UTF8String &name, ParameterType &value) const
	Place the value of the parameter with the specified name in the output parameter. More...

template<typename ParameterType >
Bool	getParameter (const char *name, ParameterType &value) const
	Place the value of the parameter with the specified name in the output parameter. More...

Bool	setParameter (Index parameterIndex, const FilterParameter &value)
	Attempt to set the parameter value at the specified index. More...

Bool	setParameter (Index parameterIndex, Bool value)
	Attempt to set the parameter value at the specified index. More...

Bool	setParameter (Index parameterIndex, Int64 value)
	Attempt to set the parameter value at the specified index. More...

Bool	setParameter (Index parameterIndex, Float32 value)
	Attempt to set the parameter value at the specified index. More...

Bool	setParameter (Index parameterIndex, Float64 value)
	Attempt to set the parameter value at the specified index. More...

template<typename ParameterType >
Bool	setParameter (const UTF8String &name, ParameterType value)
	Attempt to set the parameter value with the specified name. More...

template<typename ParameterType >
Bool	setParameter (const char *name, ParameterType value)
	Attempt to set the parameter value with the specified name. More...

virtual Bool	writeState (DataOutputStream &stream) const
	Write the current state of this sound filter to a data output stream. More...

virtual Bool	readState (DataInputStream &stream)
	Read a previously saved filter state from the specified data input stream and replace the filter's state. More...

virtual Size	getPresetCount () const
	Return the number of standard configuration presets that this sound filter has. More...

virtual Bool	getPreset (Index presetIndex, FilterPreset &preset) const
	Get the standard preset for this sound filter with the specified index. More...

Bool	getIsSynchronized () const
	Return whether or not this sound filter performs thread synchronization. More...

void	setIsSynchronized (Bool newIsSynchronized)
	Set whether or not this sound filter performs thread synchronization. More...

Public Member Functions inherited from om::sound::base::SoundInputStream
virtual	~SoundInputStream ()
	Destroy this sound input stream and release any resources associated with it. More...

SoundResult	read (SoundBuffer &buffer, Size numSamples)
	Read the specified number of samples from the input stream into a sound buffer. More...

Bool	hasSamplesRemaining () const
	Return whether or not this sound input stream has any samples remaining in the stream. More...

Static Public Attributes
static const UTF8String	NAME
	A string indicating the human-readable name of this stream player. More...

static const UTF8String	MANUFACTURER
	A string indicating the manufacturer name of this stream player. More...

static const FilterVersion	VERSION
	An object indicating the version of this stream player. More...

Static Public Attributes inherited from om::sound::filters::SoundFilter
static const om::resources::ResourceType	RESOURCE_TYPE
	The resource type for a sound filter. More...

Additional Inherited Members
Static Public Member Functions inherited from om::sound::filters::SoundFilter
static Size	getMaximumNumberOfInputs ()
	Return the maximum number of audio inputs that a SoundFilter can support. More...

static Size	getMaximumNumberOfOutputs ()
	Return the maximum number of audio outputs that a SoundFilter can support. More...

static Size	getMaximumNumberOfMIDIInputs ()
	Return the maximum number of MIDI inputs that a SoundFilter can support. More...

static Size	getMaximumNumberOfMIDIOutputs ()
	Return the maximum number of MIDI outputs that a SoundFilter can support. More...

Protected Member Functions inherited from om::sound::filters::SoundFilter
	SoundFilter ()
	Create a new sound filter with 1 audio input and output, and no MIDI inputs or outputs. More...

	SoundFilter (Size numInputs, Size numOutputs)
	Create a new sound filter with the specified number of audio inputs and outputs. More...

	SoundFilter (Size numInputs, Size numOutputs, Size numMIDIInputs, Size numMIDIOutputs)
	Create a new sound filter with the specified number of audio inputs and outputs. More...

virtual Bool	getParameterValue (Index parameterIndex, FilterParameter &value) const
	Place the value of the parameter at the specified index in the output parameter. More...

virtual Bool	setParameterValue (Index parameterIndex, const FilterParameter &value)
	Attempt to set the parameter value at the specified index. More...

virtual void	resetStream ()
	A method that is called whenever the filter's stream of audio is being reset. More...

void	setInputCount (Size newNumInputs)
	Set the number of inputs that this filter should have. More...

void	setOutputCount (Size newNumOutputs)
	Set the number of outputs that this filter should have. More...

void	setMIDIInputCount (Size newNumMIDIInputs)
	Set the number of MIDI inputs that this filter should have. More...

void	setMIDIOutputCount (Size newNumMIDIOutputs)
	Set the number of MIDI outputs that this filter should have. More...

Bool	isFirstFrame () const
	Return whether or not the filter's next frame to be processed is also its first frame. More...

void	lockMutex () const
	Acquire a mutex which handles subclass rendering parameter synchronization. More...

void	unlockMutex () const
	Release a mutex which handles subclass rendering parameter synchronization. More...

Detailed Description

A class that handles complex playback of a streaming sound source.

This class takes a pointer to a SoundInputStream and can then play the sound provided by that stream. The player supports basic start-to-stop playback, looping playback (if the stream allows it), and continuous playback from an infinite stream.

Constructor & Destructor Documentation

om::sound::filters::StreamPlayer::StreamPlayer ( )

Create a default sound stream player without any stream to play.

The constructed object will not produce any output until it has a valid SoundInputStream.

om::sound::filters::StreamPlayer::StreamPlayer ( const Shared< SoundInputStream > & newStream )

Create a sound stream player which plays from the specified sound input stream.

If the supplied stream is NULL or invalid, the stream player produces no output. All playback and looping occurs relative to the initial position within the stream.

om::sound::filters::StreamPlayer::StreamPlayer ( const StreamPlayer & other )

Create a copy of this stream player and its state.

om::sound::filters::StreamPlayer::~StreamPlayer ( )

Destroy a sound stream player and release all resources associated with it.

Member Function Documentation

StreamPlayer& om::sound::filters::StreamPlayer::operator= ( const StreamPlayer & other )

Assign the state of one sound stream player to another.

const SoundInputStream* om::sound::filters::StreamPlayer::getStream ( ) const

Return a const pointer to the SoundInputStream that is being used as a sound source.

If there is no sound input stream set or if the stream is not valid, a NULL pointer is returned, indicating the problem.

void om::sound::filters::StreamPlayer::setStream ( const Shared< SoundInputStream > & newStream )

Set the SoundInputStream which this player should use as a sound source.

If the supplied pointer is NULL, the sound player is deactivated and doesn't produce any more audio. Otherwise, the player resets its current playback position to be the start of the sound and starts playback from the current position of the stream. Thus, all playback and looping occurs relative to the initial position within the stream.

Bool om::sound::filters::StreamPlayer::isPlaying ( ) const

Return whether or not this sound player is current playing.

Bool om::sound::filters::StreamPlayer::setIsPlaying ( Bool newIsPlaying )

Set whether or not this sound player should be playing sound.

The method returns whether or not playback will occurr, based on the type of SoundInputStream which this player has and the requested playback state.

Bool om::sound::filters::StreamPlayer::play ( )

Tell the sound player to start playing the sound from the current position.

The method returns whether or not playback will occurr, based on the type of SoundInputStream that this player has.

void om::sound::filters::StreamPlayer::stop ( )

Stop playing the sound and keep the playhead at the last position.

Bool om::sound::filters::StreamPlayer::rewind ( )

Reset the playback position to the first position within the stream.

The method returns whether or not the rewind operation was successul. For SoundInputStream objects that don't allow seeking, this method will always fail. This method does not affect the playback state of the player, thus rewinding will cause the playback to jump to the beginning of the stream if the player is currently playing.

Bool om::sound::filters::StreamPlayer::isLooping ( ) const

Return whether or not this sound player is currently looping.

If the underlying SoundInputStream for the sound player does not allow seeking within the stream, looping cannot occur.

Bool om::sound::filters::StreamPlayer::setIsLooping ( Bool newIsLooping )

Set whether or not this sound player should try to loop its sound source.

If the underlying SoundInputStream for the sound player does not allow seeking within the stream, looping cannot occur. Otherwise, the sound player loops the sound if the looping flag is set to TRUE.

The method returns whether or not looping will occurr, based on the type of SoundInputStream which this player is playing. This value is independent of the current playback state of the player.

virtual Bool om::sound::filters::StreamPlayer::canSeek ( ) const

virtual

Return whether or not seeking is allowed in this input stream.

Reimplemented from om::sound::base::SoundInputStream.

virtual Bool om::sound::filters::StreamPlayer::canSeek ( Int64 relativeSampleOffset ) const

virtual

Return whether or not this input stream's current position can be moved by the specified signed sample offset.

Reimplemented from om::sound::base::SoundInputStream.

virtual Int64 om::sound::filters::StreamPlayer::seek ( Int64 relativeSampleOffset )

virtual

Move the current sample frame position in the stream by the specified signed amount.

Reimplemented from om::sound::base::SoundInputStream.

virtual SoundSize om::sound::filters::StreamPlayer::getSamplesRemaining ( ) const

virtual

Return the number of samples remaining in the sound input stream.

The value returned must only be a lower bound on the total number of sample frames in the stream. For instance, if there are samples remaining, the method should return at least 1. If there are no samples remaining, the method should return 0. This behavior is allowed in order to support never-ending streams which might not have a defined endpoint.

Implements om::sound::base::SoundInputStream.

virtual SampleIndex om::sound::filters::StreamPlayer::getPosition ( ) const

virtual

Return the current position of the stream in samples relative to the start of the stream.

The returned value indicates the sample index of the current read position within the sound stream. For unbounded streams, this indicates the number of samples that have been read by the stream since it was opened.

Implements om::sound::base::SoundInputStream.

virtual Size om::sound::filters::StreamPlayer::getChannelCount ( ) const

virtual

Return the number of channels that are in the sound input stream.

Implements om::sound::base::SoundInputStream.

virtual SampleRate om::sound::filters::StreamPlayer::getSampleRate ( ) const

virtual

Return the sample rate of the sound input stream's source audio data.

Implements om::sound::base::SoundInputStream.

virtual SampleType om::sound::filters::StreamPlayer::getNativeSampleType ( ) const

virtual

Return the actual sample type used in the stream.