ArSoundsQueue Class Reference

#include <ArSoundsQueue.h>

Inheritance diagram for ArSoundsQueue:

ArASyncTask ArThread List of all members.

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

soundsQueueExample::cpp

Examples:

soundsQueueExample.cpp.

Definition at line 60 of file ArSoundsQueue.h.

Public Types

typedef ArFunctor InterruptItemFunctor
enum  ItemType { SPEECH, SOUND_FILE, SOUND_DATA, OTHER }
 OTHER
typedef ArRetFunctor< bool > PlaybackConditionFunctor
typedef ArRetFunctor2< bool,
const char *, const char * > 
PlayItemFunctor
 SOUND_DATA
 SOUND_FILE
 SPEECH

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)
 ArSoundsQueue ()
void clearQueue ()
ArSoundsQueue::Item createDefaultFileItem (const char *filename=0)
ArSoundsQueue::Item createDefaultSpeechItem (const char *speech=0)
std::set< int > findPendingItems (const char *item)
size_t getCurrentQueueSize ()
 Get the current size of the speech/sound playback queue.
ArFunctorgetPauseCallback ()
ArFunctorgetResumeCallback ()
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 play (const char *filename_fmt,...)
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)
 main function for thread
void setDefaultPlayConditionCB (PlaybackConditionFunctor *f)
void setSpeakInitCallback (ArRetFunctor< bool > *cb)
void speak (const char *fmt,...)
void speakWithPriority (int priority, const char *fmt,...)
void speakWithVoice (const char *voice, const char *fmt,...)
void stop ()
virtual ~ArSoundsQueue ()
void setInterruptFileCallback (InterruptItemFunctor *cb)
void setInterruptSpeechCallback (InterruptItemFunctor *cb)
void setInterruptWavFileCallback (InterruptItemFunctor *cb)
void setPlayFileCallback (PlayItemFunctor *cb)
void setPlayWavFileCallback (PlayItemFunctor *cb)
void setSpeakCallback (PlayItemFunctor *cb)
 Convenience methods for special speech synthesis and WAV file queue items:.

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 ()
bool tryLock ()
void unlock ()
Item popQueueItem ()
Item popQueueItem_NoLock ()
void pushQueueItem (Item item)
void pushQueueItem_NoLock (Item item)

Protected Attributes

PlaybackConditionFunctormyDefaultPlayConditionCB
 Used when creating default configured speech and sound file items.
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< ItemmyQueue
ArMutex myQueueMutex
InterruptItemFunctormyDefaultInterruptFileCB
InterruptItemFunctormyDefaultInterruptSpeechCB
PlayItemFunctormyDefaultPlayFileCB
PlayItemFunctormyDefaultSpeakCB
 Used by speak() and play() convenience methods:.
std::list< ArFunctor * > myEndPlaybackCBList
std::list< ArFunctor * > myQueueEmptyCallbacks
std::list< ArFunctor * > myQueueNonemptyCallbacks
std::list< ArFunctor * > myStartPlaybackCBList
 Functors to invoke during queue processing.

Classes

class  Item


Member Typedef Documentation

typedef ArRetFunctor<bool> ArSoundsQueue::PlaybackConditionFunctor

Callback types for determining whether to commence playing an item, or skipping it.

Definition at line 78 of file ArSoundsQueue.h.

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 72 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 66 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 208 of file ArSoundsQueue.cpp.

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 230 of file ArSoundsQueue.cpp.


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 151 of file ArSoundsQueue.h.

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 277 of file ArSoundsQueue.cpp.

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

Add (a copy of) the given item to the queue.

Examples:
soundsQueueExample.cpp.

Definition at line 285 of file ArSoundsQueue.cpp.

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.

Examples:
soundsQueueExample.cpp.

Definition at line 295 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.

Examples:
soundsQueueExample.cpp.

Definition at line 279 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 264 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 251 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.

Examples:
soundsQueueExample.cpp.

Definition at line 589 of file ArSoundsQueue.cpp.

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 Filename to set (optional)
See also:
setPlayFileCallback()

addItem()

Examples:
soundsQueueExample.cpp.

Definition at line 432 of file ArSoundsQueue.cpp.

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

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

Parameters:
speech Text to speak (optional)
See also:
setSpeechCallback()

addItem()

Definition at line 322 of file ArSoundsQueue.cpp.

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 597 of file ArSoundsQueue.cpp.

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 227 of file ArSoundsQueue.h.

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 234 of file ArSoundsQueue.h.

bool ArSoundsQueue::isInitialized (  )  [inline]

Return true if all initialization callbacks have completed, false otherwise.

Definition at line 169 of file ArSoundsQueue.h.

bool ArSoundsQueue::isPaused (  ) 

Returns:
true if the queue is paused
Examples:
soundsQueueExample.cpp.

Definition at line 572 of file ArSoundsQueue.cpp.

bool ArSoundsQueue::isSpeaking (  )  [inline]

Deprecated:
Returns:
true if any queue item is being played.
See also:
isPlaying()

Definition at line 187 of file ArSoundsQueue.h.

bool ArSoundsQueue::isSpeakingOrPlaying ( void   )  [inline]

Deprecated:
See also:
isPlaying()

Definition at line 177 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.)

Examples:
soundsQueueExample.cpp.

Definition at line 545 of file ArSoundsQueue.cpp.

void ArSoundsQueue::play ( const char *  filename_fmt,
  ... 
)

Add a sound file to the queue for default sound file 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.
Examples:
soundsQueueExample.cpp.

Definition at line 411 of file ArSoundsQueue.cpp.

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

Pop item from queue and return it

Definition at line 306 of file ArSoundsQueue.cpp.

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

push item onto queue

See also:
addItem()

Definition at line 291 of file ArSoundsQueue.cpp.

void ArSoundsQueue::removePendingItems ( ItemType  type  ) 

Remove pending items with the given type.

Definition at line 641 of file ArSoundsQueue.cpp.

void ArSoundsQueue::removePendingItems ( int  priority,
ItemType  type 
)

Remove pending items with priority less the given priority and with the given type.

Definition at line 634 of file ArSoundsQueue.cpp.

void ArSoundsQueue::removePendingItems ( int  priority  ) 

Remove pending items with a priority less than that given.

Definition at line 627 of file ArSoundsQueue.cpp.

void ArSoundsQueue::removePendingItems ( const char *  data  ) 

Remove pending items with the given data.

Definition at line 620 of file ArSoundsQueue.cpp.

void ArSoundsQueue::removePendingItems ( const char *  item,
ItemType  type 
)

Remove pending items with the given data and type.

Examples:
soundsQueueExample.cpp.

Definition at line 612 of file ArSoundsQueue.cpp.

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

Remove a functor added by addQueueEmptyCallback()

Definition at line 301 of file ArSoundsQueue.h.

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

Remove a functor added by addQueueNonemptyCallback().

Definition at line 285 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 271 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 257 of file ArSoundsQueue.h.

void ArSoundsQueue::setDefaultPlayConditionCB ( PlaybackConditionFunctor f  )  [inline]

Set a playback condition functor used for default speech and sound file items

Definition at line 438 of file ArSoundsQueue.h.

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

Set the "default" callback to interrupt current wav file playback, for use by the play() convenience method.

See also:
Item

Definition at line 377 of file ArSoundsQueue.h.

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

Set the "default" callback to interrupt a current speech utterance, used by speak()

See also:
Item

Definition at line 355 of file ArSoundsQueue.h.

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

Deprecated:
use setInterruptFileCallback()
Examples:
soundsQueueExample.cpp.

Definition at line 382 of file ArSoundsQueue.h.

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.

See also:
Item

Definition at line 364 of file ArSoundsQueue.h.

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

Deprecated:
use setPlayFileCallback()
Examples:
soundsQueueExample.cpp.

Definition at line 369 of file ArSoundsQueue.h.

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

Convenience methods for special speech synthesis and WAV file queue items:.

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.

See also:
Item

Definition at line 347 of file ArSoundsQueue.h.

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

Deprecated:

Definition at line 156 of file ArSoundsQueue.h.

void ArSoundsQueue::speak ( const char *  fmt,
  ... 
)

Add a formatted text string (like printf) to the queue configured for default 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 340 of file ArSoundsQueue.cpp.

void ArSoundsQueue::speakWithPriority ( int  priority,
const char *  fmt,
  ... 
)

Speak with alternate priority.

Definition at line 387 of file ArSoundsQueue.cpp.

void ArSoundsQueue::speakWithVoice ( const char *  voice,
const char *  fmt,
  ... 
)

Speak with alternate voice.

Definition at line 362 of file ArSoundsQueue.cpp.

void ArSoundsQueue::stop (  ) 

End the processing thread. This function is deprecated. Use stopRunning() instead.

Deprecated:
This shuts down the sound queue completely. To temporarily stop the queue processing, use pause(). To interrupt the currently playing sound, use interrupt().
Examples:
soundsQueueExample.cpp.

Definition at line 567 of file ArSoundsQueue.cpp.


The documentation for this class was generated from the following files:
Generated on Fri Dec 1 10:55:19 2006 for Aria by  doxygen 1.4.7