ArSoundsQueue Class Reference

This class manages a queue of items to play as WAV files or as text to speak using a speech synthesizer. More...

#include <ArSoundsQueue.h>

Inheritance diagram for ArSoundsQueue:


Public Types
typedef ArFunctor	InterruptItemFunctor
enum	ItemType { SPEECH, SOUND_FILE, SOUND_DATA, OTHER }
typedef ArRetFunctor2< bool, const char , const char >	PlayItemFunctor
Public Member Functions
void	addInitCallback (ArRetFunctor< bool > *cb)
void	addItem (ItemType type, const char data, std::list< PlayItemFunctor > callbacks, int priority=0, const char *params=0)
void	addItem (ArSoundsQueue::Item item)
void	addQueueEmptyCallback (ArFunctor *f)
void	addQueueNonemptyCallback (ArFunctor *f)
void	addSoundFinishedCallback (ArFunctor *f)
void	addSoundStartedCallback (ArFunctor *f)
	ArSoundsQueue (ArSpeechSynth speechSynthesizer, ArRetFunctor< bool > playInitCB=0, PlayItemFunctor playFileCB=0, InterruptItemFunctor interruptFileCB=0)
	ArSoundsQueue (ArRetFunctor< bool > speakInitCB, PlayItemFunctor speakCB=0, InterruptItemFunctor interruptSpeechCB=0, ArRetFunctor< bool > playInitCB=0, PlayItemFunctor playFileCB=0, InterruptItemFunctor interruptFileCB=0)
void	clearQueue ()
std::set< int >	findPendingItems (const char *item)
size_t	getCurrentQueueSize ()
	Get the current size of the speech/sound playback queue.
ArFunctor *	getPauseCallback ()
ArFunctor *	getResumeCallback ()
void	interrupt ()
	If sound is currently being played or speech is being spoken, interrupt it. (but continue processing the queue). SoundFinished callbacks will not be called.
bool	isInitialized ()
bool	isPaused ()
bool	isPlaying ()
	Returns true if an item is currently being played.
bool	isSpeaking ()
bool	isSpeakingOrPlaying (void)
std::string	nextItem (ItemType type, int priority)
std::string	nextItem (int priority)
std::string	nextItem (ItemType type)
void	pause ()
void	removePendingItems (ItemType type)
void	removePendingItems (int priority, ItemType type)
void	removePendingItems (int priority)
void	removePendingItems (const char *data)
void	removePendingItems (const char *item, ItemType type)
void	remQueueEmptyCallback (ArFunctor *f)
void	remQueueNonemptyCallback (ArFunctor *f)
void	remSoundFinishedCallback (ArFunctor *f)
void	remSoundStartedCallback (ArFunctor *f)
void	resume ()
	Resume processing the sounds queue.
void	run (void)
	Begin processing the sounds queue synchronously (in this thread; does not return).
void	runAsync (void)
	Begin processing the sounds queue in a background thread.
virtual void *	runThread (void *arg)
	The main run loop.
void	setSpeakInitCallback (ArRetFunctor< bool > *cb)
void	stop ()

ArSoundsQueue::Item	createDefaultFileItem (const char *filename=0)
ArSoundsQueue::Item	createDefaultSpeechItem (const char *speech=0)
void	play (const char *filename_fmt,...)
void	setInterruptFileCallback (InterruptItemFunctor *cb)
void	setInterruptSpeechCallback (InterruptItemFunctor *cb)
void	setInterruptWavFileCallback (InterruptItemFunctor *cb)
void	setPlayFileCallback (PlayItemFunctor *cb)
void	setPlayWavFileCallback (PlayItemFunctor *cb)
void	setSpeakCallback (PlayItemFunctor *cb)
void	speak (const char *fmt,...)
void	speakWithPriority (int priority, const char *fmt,...)
void	speakWithVoice (const char voice, const char fmt,...)
Protected Member Functions
void	invokeCallbacks (const std::list< ArRetFunctor< bool > * > &lst)
	Invoke each functor in a list, but stop if any of them return false.
void	invokeCallbacks (const std::list< ArFunctor * > &lst)
	Invoke each functor in a list.
void	lock ()
	Lock the thread instance.
bool	tryLock ()
	Try to lock the thread instance without blocking.
void	unlock ()
	Unlock the thread instance.

Item	popQueueItem ()
Item	popQueueItem_NoLock ()

void	pushQueueItem (Item item)
void	pushQueueItem_NoLock (Item item)
Protected Attributes
std::list< ArRetFunctor< bool > * >	myInitCallbacks
	Functors to invoke when we start running in our thread.
bool	myInitialized
Item	myLastItem
	The current or most recent item played.
ArCondition	myPausedCondition
	Condition variable used by the thread to pause.
int	myPauseRequestCount
	Semaphore for doing pausing and resuming of the queue.
bool	myPlayingSomething
std::list< Item >	myQueue
ArMutex	myQueueMutex

InterruptItemFunctor *	myDefaultInterruptFileCB
InterruptItemFunctor *	myDefaultInterruptSpeechCB
PlayItemFunctor *	myDefaultPlayFileCB
PlayItemFunctor *	myDefaultSpeakCB

std::list< ArFunctor * >	myEndPlaybackCBList
std::list< ArFunctor * >	myQueueEmptyCallbacks
std::list< ArFunctor * >	myQueueNonemptyCallbacks
std::list< ArFunctor * >	myStartPlaybackCBList
Classes
class	Item

Detailed Description

This class manages a queue of items to play as WAV files or as text to speak using a speech synthesizer.

The actual playback of sound and speech is done through callbacks (which you can supply in the constructor or afterwards). Some callbacks you can use are provided by classes like ArSoundPlayer (for sound file playback) and ArFestival (from the ArSpeechSynth_Festival library) and ArCepstral (from the ArSpeechSynth_Cepstral librrary) for speech synthesis.

Add sound files to the queue with play(), and text to speak with speak(). Use runAsync() to run the processing thread in the background, or run() to run synchronously in the current thread.

See also:: ArSoundPlayer
examples/soundQueue.cpp

Definition at line 79 of file ArSoundsQueue.h.

Member Typedef Documentation

typedef ArRetFunctor2<bool, const char*, const char*> ArSoundsQueue::PlayItemFunctor

Callback for playing a queue item. First argument is the "data", second is item type-specific "parameters". Return true to continue processing more callbacks in a list, false to cancel processing.
Definition at line 91 of file ArSoundsQueue.h.

Member Enumeration Documentation

enum ArSoundsQueue::ItemType

Opaque identifier for the type of an item in the sound queue. Not used during processing, but may be used to search for items in the queue.
Definition at line 85 of file ArSoundsQueue.h.

Constructor & Destructor Documentation

ArSoundsQueue::ArSoundsQueue ( ArRetFunctor< bool > * speakInitCB,

PlayItemFunctor * speakCB = 0,

InterruptItemFunctor * interruptSpeechCB = 0,

ArRetFunctor< bool > * playInitCB = 0,

PlayItemFunctor * playFileCB = 0,

InterruptItemFunctor * interruptFileCB = 0

)

Deprecated:

See also:
addInitCallback()
setSpeakCallback()
setInterruptSpeechCallback()
setPlayFileCallback
setInterruptFileCallback

Definition at line 185 of file ArSoundsQueue.cpp.
References ArSoundPlayer::getPlayWavFileCallback(), ArSoundPlayer::getStopPlayingCallback(), myInitCallbacks, myPauseRequestCount, and ArThread::setThreadName().

ArSoundsQueue::ArSoundsQueue ( ArSpeechSynth * speechSynthesizer,

ArRetFunctor< bool > * playInitCB = 0,

PlayItemFunctor * playFileCB = 0,

InterruptItemFunctor * interruptFileCB = 0

)

Set default speech and WAV file callbacks for use by the convenience methods speak() and play(). Omit the last three arguments to use callbacks into ArSoundPlayer.
Definition at line 207 of file ArSoundsQueue.cpp.
References myInitCallbacks, and ArThread::setThreadName().

Member Function Documentation

void ArSoundsQueue::addInitCallback ( ArRetFunctor< bool > * cb ) [inline]

Add a callback to be called when the sound queue begins to run in its thread. (For example, the speech synthesizers must be initialized in the same thread as they are used.)
Definition at line 158 of file ArSoundsQueue.h.
References myInitCallbacks.
Referenced by setSpeakInitCallback().

void ArSoundsQueue::addItem ( ItemType type,

const char * data,

std::list< PlayItemFunctor * > callbacks,

int priority = 0,

const char * params = 0

)

Create a new queue item with the given data and add to the queue.
Definition at line 254 of file ArSoundsQueue.cpp.
References pushQueueItem().

void ArSoundsQueue::addItem ( ArSoundsQueue::Item item )

Add (a copy of) the given item to the queue.
Definition at line 262 of file ArSoundsQueue.cpp.
References pushQueueItem().

void ArSoundsQueue::addQueueEmptyCallback ( ArFunctor * f ) [inline]

Add a callback functor to be invoked when the sound queue becomes empty and the last sound has finished playing, that is, when a block of sounds/speech utterances ends. This will not be called when the sound queue first begins running.
Definition at line 297 of file ArSoundsQueue.h.

void ArSoundsQueue::addQueueNonemptyCallback ( ArFunctor * f ) [inline]

Add a callback functor to be invoked when a the sound queue becomes non-empty, that is, when a block of sounds/speech utterances begins.
Definition at line 281 of file ArSoundsQueue.h.

void ArSoundsQueue::addSoundFinishedCallback ( ArFunctor * f ) [inline]

Add a callback functor to be invoked when plackback of one sound or speech utterance begins.
Definition at line 266 of file ArSoundsQueue.h.

void ArSoundsQueue::addSoundStartedCallback ( ArFunctor * f ) [inline]

Add a callback functor to be invoked when playback of one sound or speech utterance starts.
Definition at line 253 of file ArSoundsQueue.h.

void ArSoundsQueue::clearQueue ( )

Empty the queue. If a sound is currently playing, it will not be interrupted. QueueEmpty callbacks will be called. SoundFinished callbacks will not be called.
Definition at line 519 of file ArSoundsQueue.cpp.
References invokeCallbacks(), lock(), and unlock().

ArSoundsQueue::Item ArSoundsQueue::createDefaultFileItem ( const char * filename = 0 )

Return an item set up for sound file playback with previously set default play callbacks.
Parameters:

Filename to set (optional)

See also:
setPlayFileCallback()
addItem()

Definition at line 382 of file ArSoundsQueue.cpp.
References ArSoundsQueue::Item::data, ArSoundsQueue::Item::interruptCallbacks, ArLog::log(), ArSoundsQueue::Item::playCallbacks, and ArSoundsQueue::Item::type.
Referenced by play().

ArSoundsQueue::Item ArSoundsQueue::createDefaultSpeechItem ( const char * speech = 0 )

Return an item set up for speech with previously set default speech callbacks.
Parameters:

Text to speak (optional)

See also:
setSpeechCallback()
addItem()

Definition at line 299 of file ArSoundsQueue.cpp.
References ArSoundsQueue::Item::data, ArSoundsQueue::Item::interruptCallbacks, ArSoundsQueue::Item::playCallbacks, and ArSoundsQueue::Item::type.
Referenced by speak(), speakWithPriority(), and speakWithVoice().

set< int > ArSoundsQueue::findPendingItems ( const char * item )

Find items waiting in the queue. This is mainly useful in finding speech text.
Parameters:

item Item to search for.

Returns:
A set of positions in the queue. 1 indicates the next sound that will play, followed by 2, etc.

Note:
You have a potential race condition if an item is removed from the queue after this method returns, but before you on the information returned. For best results, pause the sound queue while using this information.

Definition at line 527 of file ArSoundsQueue.cpp.
References lock(), and unlock().

ArFunctor* ArSoundsQueue::getPauseCallback ( ) [inline]

Create and return a new a functor for pause(), which other modules can use to pause this sounds queue.
Definition at line 229 of file ArSoundsQueue.h.
References pause().

ArFunctor* ArSoundsQueue::getResumeCallback ( ) [inline]

Create and return a new functor for resume(), which other modules can use to resume this sounds queue.
Definition at line 236 of file ArSoundsQueue.h.
References resume().

bool ArSoundsQueue::isInitialized ( ) [inline]

Return true if all initialization callbacks have completed, false otherwise.
Definition at line 176 of file ArSoundsQueue.h.

bool ArSoundsQueue::isPaused ( )

Returns:
true if the queue is paused

Definition at line 502 of file ArSoundsQueue.cpp.
References myPauseRequestCount.

bool ArSoundsQueue::isSpeaking ( ) [inline]

Deprecated:

Returns:
true if any queue item is being played.

See also:
isPlaying()

Definition at line 194 of file ArSoundsQueue.h.

bool ArSoundsQueue::isSpeakingOrPlaying ( void ) [inline]

Deprecated:

See also:
isPlaying()

Definition at line 184 of file ArSoundsQueue.h.

void ArSoundsQueue::pause ( )

Temporarily stop processing the sounds queue. (Any currently playing sound or speech utterance will finish. The sound device may remain open.)
Definition at line 475 of file ArSoundsQueue.cpp.
References lock(), myPauseRequestCount, and unlock().
Referenced by getPauseCallback().

void ArSoundsQueue::play ( const char * filename_fmt,

...

)

Add a sound file to the queue for playback.

Parameters:

filename_fmt Format string for determining the filename of the WAV file, same as printf().

... If given, arguments to format into the format string.

Definition at line 397 of file ArSoundsQueue.cpp.
References createDefaultFileItem(), ArSoundsQueue::Item::data, invokeCallbacks(), lock(), pushQueueItem(), and unlock().

ArSoundsQueue::Item ArSoundsQueue::popQueueItem ( ) [protected]

Pop item from queue and return it
Definition at line 283 of file ArSoundsQueue.cpp.
References lock(), and unlock().

void ArSoundsQueue::pushQueueItem ( Item item ) [protected]

push item onto queue
See also:
addItem()

Definition at line 268 of file ArSoundsQueue.cpp.
References lock(), and unlock().
Referenced by addItem(), and play().

void ArSoundsQueue::removePendingItems ( ItemType type )

Remove pending items with the given type.
Definition at line 571 of file ArSoundsQueue.cpp.
References lock(), and unlock().

void ArSoundsQueue::removePendingItems ( int priority,

ItemType type

)

Remove pending items with priority less the given priority and with the given type.
Definition at line 564 of file ArSoundsQueue.cpp.
References lock(), and unlock().

void ArSoundsQueue::removePendingItems ( int priority )

Remove pending items with a priority less than that given.
Definition at line 557 of file ArSoundsQueue.cpp.
References lock(), and unlock().

void ArSoundsQueue::removePendingItems ( const char * data )

Remove pending items with the given data.
Definition at line 550 of file ArSoundsQueue.cpp.
References lock(), and unlock().

void ArSoundsQueue::removePendingItems ( const char * item,

ItemType type

)

Remove pending items with the given data and type.
Definition at line 542 of file ArSoundsQueue.cpp.
References lock(), and unlock().

void ArSoundsQueue::remQueueEmptyCallback ( ArFunctor * f ) [inline]

Remove a functor added by addQueueEmptyCallback()
Definition at line 303 of file ArSoundsQueue.h.

void ArSoundsQueue::remQueueNonemptyCallback ( ArFunctor * f ) [inline]

Remove a functor added by addQueueNonemptyCallback().
Definition at line 287 of file ArSoundsQueue.h.

void ArSoundsQueue::remSoundFinishedCallback ( ArFunctor * f ) [inline]

Remove a callback functor to be invoked when plackback of one sound or speech utterance finishes.
Definition at line 273 of file ArSoundsQueue.h.

void ArSoundsQueue::remSoundStartedCallback ( ArFunctor * f ) [inline]

Remove a callback functor to be invoked when playback one sound or speech utterance starts.
Definition at line 259 of file ArSoundsQueue.h.

void * ArSoundsQueue::runThread ( void * arg ) [virtual]

The main run loop.
Override this function and put your taskes run loop here. Check the value of getRunning() or myRunning periodicly in your loop. If the value goes false, the loop should exit and runThread() should return.
Implements ArASyncTask.
Definition at line 416 of file ArSoundsQueue.cpp.
References ArThread::getRunning(), invokeCallbacks(), lock(), ArLog::log(), myInitCallbacks, myLastItem, myPausedCondition, myPauseRequestCount, ArSoundsQueue::Item::play(), ArUtil::sleep(), ArThread::threadStarted(), ArSoundsQueue::Item::type, unlock(), and ArCondition::wait().

void ArSoundsQueue::setInterruptFileCallback ( InterruptItemFunctor * cb ) [inline]

Set the "default" callback to interrupt current wav file playback, for use by the play() convenience method.
Definition at line 373 of file ArSoundsQueue.h.
Referenced by setInterruptWavFileCallback().

void ArSoundsQueue::setInterruptSpeechCallback ( InterruptItemFunctor * cb ) [inline]

Set the "default" callback to interrupt a current speech utterance, used by speak()
Definition at line 354 of file ArSoundsQueue.h.

void ArSoundsQueue::setInterruptWavFileCallback ( InterruptItemFunctor * cb ) [inline]

Deprecated:

Definition at line 378 of file ArSoundsQueue.h.
References setInterruptFileCallback().

void ArSoundsQueue::setPlayFileCallback ( PlayItemFunctor * cb ) [inline]

As a convenience, you may set a "default" WAV file playback callback, and then simply use the play() method to add the file to the queue with this callback.
Definition at line 362 of file ArSoundsQueue.h.
Referenced by setPlayWavFileCallback().

void ArSoundsQueue::setPlayWavFileCallback ( PlayItemFunctor * cb ) [inline]

Deprecated:

Definition at line 367 of file ArSoundsQueue.h.
References setPlayFileCallback().

void ArSoundsQueue::setSpeakCallback ( PlayItemFunctor * cb ) [inline]

As a convenience, you may set a "default" speech synthesis callback, and then simply use the speak() method to add a speech item to the queue with those callbacks.
Definition at line 347 of file ArSoundsQueue.h.

void ArSoundsQueue::setSpeakInitCallback ( ArRetFunctor< bool > * cb ) [inline]

Deprecated:

Definition at line 163 of file ArSoundsQueue.h.
References addInitCallback().

void ArSoundsQueue::speak ( const char * fmt,

...

)

Add a formatted text string (like printf) to the queue for speech synthesis. When reached in the queue while running, the text will be sent to the "speak" callback, if set, otherwise, the "SythesizeToSound" and "PlaySynthesizedSound" callbacks will be used (if they are set.)

Parameters:

fmt Format string.

... Arguments to format into the format string.

Definition at line 312 of file ArSoundsQueue.cpp.
References createDefaultSpeechItem(), ArSoundsQueue::Item::data, invokeCallbacks(), lock(), and unlock().

void ArSoundsQueue::speakWithPriority ( int priority,

const char * fmt,

...

)

Speak with alternate priority.
Definition at line 359 of file ArSoundsQueue.cpp.
References createDefaultSpeechItem(), ArSoundsQueue::Item::data, invokeCallbacks(), lock(), ArSoundsQueue::Item::priority, and unlock().

void ArSoundsQueue::speakWithVoice ( const char * voice,

const char * fmt,

...

)

Speak with alternate voice.
Definition at line 334 of file ArSoundsQueue.cpp.
References createDefaultSpeechItem(), ArSoundsQueue::Item::data, invokeCallbacks(), lock(), ArSoundsQueue::Item::params, and unlock().

void ArSoundsQueue::stop ( )

Stop processing the sounds queue and end the thread. QueueEmpty callbacks will be called.
Definition at line 497 of file ArSoundsQueue.cpp.
References ArASyncTask::stopRunning().

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

Generated on Wed Oct 19 12:56:55 2005 for Aria by

1.4.0

ArSoundsQueue Class Reference

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Classes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation