Tekkotsu: SoundManager Class Reference

Provides easy methods for playing back sounds, either from files on the memory stick, or from dynamically generated buffers. You can chain playback commands so that when one sound finishes, another picks up automatically. This might be handy if, say, someone wants to write an MP3 player ;) The sounds would be too large to load into memory all at once, but you could load a block at a time and chain them so it seamlessly moves from one to the other.

You can also preload sounds (loadFile()) before playing them (play() / playFile()) so there's no delay between requesting a sound and having it start playing while it is loaded from disk/memory stick. Just be sure to release the file (releaseFile()) again when you're done with it ;)

All functions will attempt to lock the SoundManager. Remember, this is running in a shared memory region, accessible by the SoundPlay process and both the Main and Motion processes (so MotionCommands can play sounds!)

One could be tempted to draw parallels to the MotionManager, and envision a system with SoundCommands that are handed over and can dynamically compute sound buffers as needed. If you have the time and inclination, the job's all yours... (Midi players, speech synthesizer, ...?)

Definition at line 58 of file SoundManager.h.


Public Types
typedef SoundManagerMsg::Snd_ID	Snd_ID
	This is used for referring to sound data so you can start playing it or release it.
typedef unsigned short	Play_ID
	This is for referring to instances of the play command so you can stop, pause, or monitor progress (later versions will send events upon completion).
	Fast
	uses real division to maintain volume level, without increasing intermediary precision, which causes low-order bit error in exchange for less CPU usage
	Quality
	uses real division to maintain volume level, using an intermediary higher precision buffer for mixing
	Enqueue
	newer sounds are played when a channel opens up (when old sound finishes)
	Pause
	newer sounds pause oldest sound, which continues when a channel opens
	Stop
	newer sounds stop oldest sound
	Override
	older sounds have play heads advanced, but don't get mixed until a channel opens
enum	MixMode_t { Fast, Quality }
	Used to set the mode for mixing multiple sound channels. More...
enum	QueueMode_t { Enqueue, Pause, Stop, Override }
	indicates how to handle channel overflow (trying to play more sounds than maximum number of mixing channels). See queue_mode More...
Public Member Functions
virtual	~SoundManager ()
	destructor
	SoundManager ()
	constructor, should only be called by the receiving process (SoundPlay)
void	InitAccess (OSubject *subj)
	Each process needs to call this before it can send sounds to the SoundPlay process.
Snd_ID	loadFile (std::string const &name)
	loads a wav file (if it matches Config::sound_config settings - can't do resampling yet)
Snd_ID	loadBuffer (const char buf[], unsigned int len)
	loads raw samples from a buffer (assumes matches Config::sound_config settings)
void	releaseFile (std::string const &name)
	Marks the sound buffer to be released after the last play command completes (or right now if not being played).
void	release (Snd_ID id)
	Marks the sound buffer to be released after the last play command completes (or right now if not being played).
Play_ID	playFile (std::string const &name)
	play a wav file (if it matches Config::sound_config settings - can't do resampling yet)
Play_ID	playBuffer (const char buf[], unsigned int len)
	loads raw samples from a buffer (assumes buffer matches Config::sound_config settings)
Play_ID	play (Snd_ID id)
	plays a previously loaded buffer or file
Play_ID	chainFile (Play_ID base, std::string const &next)
	allows automatic queuing of sounds - good for dynamic sound sources!
Play_ID	chainBuffer (Play_ID base, const char buf[], unsigned int len)
	allows automatic queuing of sounds - good for dynamic sound sources!
Play_ID	chain (Play_ID base, Snd_ID next)
	allows automatic queuing of sounds - good for dynamic sound sources!
void	stopPlay ()
	Lets you stop playback of all sounds.
void	stopPlay (Play_ID id)
	Lets you stop playback of a sound.
void	pausePlay (Play_ID id)
	Lets you pause playback.
void	resumePlay (Play_ID id)
	Lets you resume playback.
void	setMode (unsigned int max_channels, MixMode_t mixer_mode, QueueMode_t queuing_mode)
	Lets you control the maximum number of channels (currently playing sounds), method for mixing (applies when max_chan>1), and queuing method (for when overflow channels).
unsigned int	getRemainTime (Play_ID id) const
	Gives the time until the sound finishes, in milliseconds. Subtract 32 to get guarranteed valid time for this ID.
unsigned int	CopyTo (OSoundVectorData *data)
	Copies the sound data to the OPENR buffer, ready to be passed to the system, only called by SoundPlay.
void	ReceivedMsg (const ONotifyEvent &event)
	updates internal data structures on the SoundPlay side - you shouldn't be calling this
unsigned int	CopyTo (void *dest, size_t destSize)
	Copies the sound data to the specified memory buffer, ready to be passed to the system.
void	ProcessMsg (RCRegion *rcr)
	updates internal data structures on the SoundPlay side - you shouldn't be calling this
unsigned int	getNumPlaying ()
	returns number of sounds currently playing
virtual unsigned int	getNextKey ()
	return the next region serial number -- doesn't actually increment it though, repeated calls will return the same value until the value is actually used
Deprecated
Snd_ID	LoadFile (std::string const &name) ATTR_deprecated
	deprecated, use loadFile() (note first letter lower case)
Snd_ID	LoadBuffer (const char buf[], unsigned int len) ATTR_deprecated
	deprecated, use loadBuffer() (note first letter lower case)
void	ReleaseFile (std::string const &name) ATTR_deprecated
	deprecated, use releaseFile() (note first letter lower case)
void	Release (Snd_ID id) ATTR_deprecated
	deprecated, use release() (note first letter lower case)
Play_ID	PlayFile (std::string const &name) ATTR_deprecated
	deprecated, use playFile() (note first letter lower case)
Play_ID	PlayBuffer (const char buf[], unsigned int len) ATTR_deprecated
	deprecated, use playBuffer() (note first letter lower case)
Play_ID	Play (Snd_ID id) ATTR_deprecated
	deprecated, use play() (note first letter lower case)
Play_ID	ChainFile (Play_ID base, std::string const &next) ATTR_deprecated
	deprecated, use chainFile() (note first letter lower case)
Play_ID	ChainBuffer (Play_ID base, const char buf[], unsigned int len) ATTR_deprecated
	deprecated, use chainBuffer() (note first letter lower case)
Play_ID	Chain (Play_ID base, Snd_ID next) ATTR_deprecated
	deprecated, use chain() (note first letter lower case)
void	StopPlay () ATTR_deprecated
	deprecated, use stopPlay() (note first letter lower case)
void	StopPlay (Play_ID id) ATTR_deprecated
	deprecated, use stopPlay() (note first letter lower case)
void	PausePlay (Play_ID id) ATTR_deprecated
	deprecated, use pausePlay() (note first letter lower case)
void	ResumePlay (Play_ID id) ATTR_deprecated
	deprecated, use resumePlay() (note first letter lower case)
void	SetMode (unsigned int max_channels, MixMode_t mixer_mode, QueueMode_t queuing_mode) ATTR_deprecated
	deprecated, use setMode() (note first letter lower case)
unsigned int	GetRemainTime (Play_ID id) const ATTR_deprecated
	deprecated, use getRemainTime() (note first letter lower case)
unsigned int	GetNumPlaying () ATTR_deprecated
	deprecated, use getNumPlaying() (note first letter lower case)
Static Public Attributes
static const Snd_ID	invalid_Snd_ID = (Snd_ID)-1
	for reporting errors
static const Snd_ID	MAX_SND = 50
	the number of sounds that can be loaded at any given time
static const Play_ID	invalid_Play_ID = (Play_ID)-1
	for reporting errors
static const Play_ID	MAX_PLAY = 256
	the number of sounds that can be enqueued at the same time (see MixMode_t)
static const unsigned int	MAX_NAME_LEN = 128
	maximum length of a path
Protected Types
typedef ListMemBuf< SoundData, MAX_SND, Snd_ID >	sndlist_t
	For convenience.
typedef ListMemBuf< PlayState, MAX_PLAY, Play_ID >	playlist_t
	For convenience.
typedef ListMemBuf< Play_ID, MAX_PLAY, Play_ID >	chanlist_t
	For convenience.
Protected Member Functions
void	mixChannel (Play_ID channelId, void *buf, size_t size)
	Mixes the channel into the buffer.
void	mixChannelAdditively (Play_ID channelId, int bitsPerSample, MixMode_t mode, short scalingFactor, void *buf, size_t size)
	Mixes the channel into the buffer additively.
RCRegion *	initRegion (unsigned int size)
	Sets up a shared region to hold a sound - rounds to nearest page size.
Snd_ID	lookupPath (std::string const &name) const
	Looks to see if name matches any of the sounds in sndlist (converts to absolute path if not already).
void	selectChannels (std::vector< Play_ID > &mix)
	selects which of the channels are actually to be mixed together, depending on queue_mode
void	updateChannels (const std::vector< Play_ID > &mixs, size_t used)
	update the offsets of sounds which weren't mixed (when needed depending on queue_mode)
bool	endPlay (Play_ID id)
	called when a buffer end is reached, may reset buffer to next in chain, or just stopPlay()
Protected Attributes
int *	mixerBuffer
	The intermediate mixer buffer used for Quality mode mixing.
size_t	mixerBufferSize
	Size (in bytes) of the intermediate mixer buffer.
sndlist_t	sndlist
	Holds a list of all currently loaded sounds.
playlist_t	playlist
	Holds a list of all sounds currently enqueued.
chanlist_t	chanlist
	Holds a list of all currently playing sounds, ordered newest (front) to oldest(back).
MixMode_t	mix_mode
	Current mixing mode, set by setMode();.
QueueMode_t	queue_mode
	Current queuing mode, set by setMode();.
unsigned int	max_chan
	Current maximum number of sounds to mix together.
MutexLock< ProcessID::NumProcesses >	lock
	Prevents multiple processes from accessing at the same time.
unsigned int	sn
	A serial number, incremented for each sound which is created.
OSubject *	subjs [ProcessID::NumProcesses]
	Storage of each process's subject object, used to internally transmit sound buffers to SoundPlay.
Static Protected Attributes
static const unsigned int	MSG_SIZE = ((sizeof(SoundManagerMsg)-1)/8+1)*8
	the size of a SoundManagerMsg, which is prefixed before each region sent/received by SoundManager (rounded up to nearest even word boundary)
Private Member Functions
	SoundManager (const SoundManager &)
	don't call
SoundManager	operator= (const SoundManager &)
	don't call
Classes
struct	PlayState
	Holds data about sounds currently being played. More...
struct	SoundData
	Holds data about the loaded sounds. More...

Member Enumeration Documentation

enum SoundManager::MixMode_t

Used to set the mode for mixing multiple sound channels.

Feel free to add a higher quality mixer if you're an audiophile - I'm pretty new to sound processing

Enumerator:

Fast	uses real division to maintain volume level, without increasing intermediary precision, which causes low-order bit error in exchange for less CPU usage
Quality	uses real division to maintain volume level, using an intermediary higher precision buffer for mixing

Definition at line 87 of file SoundManager.h.

enum SoundManager::QueueMode_t

indicates how to handle channel overflow (trying to play more sounds than maximum number of mixing channels). See queue_mode

Enumerator:

Enqueue	newer sounds are played when a channel opens up (when old sound finishes)
Pause	newer sounds pause oldest sound, which continues when a channel opens
Stop	newer sounds stop oldest sound
Override	older sounds have play heads advanced, but don't get mixed until a channel opens

Definition at line 94 of file SoundManager.h.

Member Function Documentation

Play_ID SoundManager::chain	(	Play_ID	base,
		Snd_ID	next
	)

allows automatic queuing of sounds - good for dynamic sound sources!

if you chain more than once to the same base, the new buffers are appended to the end of the chain - the new buffer doesn't replace the current chain

Returns:: base - just for convenience of multiple calls

SoundManager::Play_ID SoundManager::chainBuffer	(	Play_ID	base,
		const char	buf[],
		unsigned int	len
	)

allows automatic queuing of sounds - good for dynamic sound sources!

if you chain more than once to the same base, the new buffers are appended to the end of the chain - the new buffer doesn't replace the current chain

Returns:: base - just for convenience of multiple calls

Definition at line 291 of file SoundManager.cc.

Referenced by ChainBuffer(), and SpeakerServer::QueueFrame().

SoundManager::Play_ID SoundManager::chainFile	(	Play_ID	base,
		std::string const &	next
	)

allows automatic queuing of sounds - good for dynamic sound sources!

if you chain more than once to the same base, the new buffers are appended to the end of the chain - the new buffer doesn't replace the current chain

Returns:: base - just for convenience of multiple calls

Definition at line 271 of file SoundManager.cc.

Referenced by ChainFile().

unsigned int SoundManager::CopyTo	(	void *	dest,
		size_t	destSize
	)

Copies the sound data to the specified memory buffer, ready to be passed to the system.

Returns:: the number of active sounds

Definition at line 512 of file SoundManager.cc.

unsigned int SoundManager::CopyTo ( OSoundVectorData * data )

Copies the sound data to the OPENR buffer, ready to be passed to the system, only called by SoundPlay.

Returns:: the number of active sounds

Definition at line 499 of file SoundManager.cc.

unsigned int SoundManager::getRemainTime ( Play_ID id ) const

Gives the time until the sound finishes, in milliseconds. Subtract 32 to get guarranteed valid time for this ID.

You should be passing the beginning of a chain to get proper results...
May be slightly conservative (will report too small a time) because this does not account for delay until SoundPlay picks up the message that a sound has been added.
However, it is slighly optimistic (will report too large a time) because it processes a buffer all at one go, so it could mark the sound as finished (and cause the ID to go invalid) up to RobotInfo::SoundBufferTime (32 ms) before the sound finishes. So subtract SoundBufferTime if you want to be absolutely sure the ID will still valid.

Definition at line 387 of file SoundManager.cc.

Referenced by GetRemainTime(), and SpeakerServer::QueueFrame().

SoundManager::Snd_ID SoundManager::loadBuffer	(	const char	buf[],
		unsigned int	len
	)

loads raw samples from a buffer (assumes matches Config::sound_config settings)

The sound data will be cached until release() is called a matching number of times.
This function is useful for dynamic sound sources. A copy will be made.

Definition at line 100 of file SoundManager.cc.

Referenced by chainBuffer(), LoadBuffer(), loadFile(), and playBuffer().

SoundManager::Snd_ID SoundManager::loadFile ( std::string const & name )

loads a wav file (if it matches Config::sound_config settings - can't do resampling yet)

Since the SoundManager does the loading, if the same file is being played more than once, only once copy is stored in memory

Parameters:

name

can be either a full path, or a partial path relative to Config::sound_config::root

Returns:: ID number for future references (can also use name) The sound data will be cached until releaseFile() or release() is called a matching number of times

Definition at line 57 of file SoundManager.cc.

Referenced by chainFile(), Controller::DoStart(), LoadFile(), and playFile().

void SoundManager::mixChannelAdditively	(	Play_ID	channelId,
		int	bitsPerSample,
		MixMode_t	mode,
		short	scalingFactor,
		void *	buf,
		size_t	size
	)			`[protected]`

Mixes the channel into the buffer additively.

If mode is Quality, then the size of the buffer should be double the normal size.

Definition at line 429 of file SoundManager.cc.

Referenced by CopyTo().

SoundManager::Play_ID SoundManager::playBuffer	(	const char	buf[],
		unsigned int	len
	)

loads raw samples from a buffer (assumes buffer matches Config::sound_config settings)

The sound data will be released after done playing

Definition at line 213 of file SoundManager.cc.

Referenced by chainBuffer(), PlayBuffer(), and SpeakerServer::QueueFrame().

SoundManager::Play_ID SoundManager::playFile ( std::string const & name )

play a wav file (if it matches Config::sound_config settings - can't do resampling yet)

Will do a call to loadFile() first, and then automatically release the sound again when complete.

Parameters:

name

can be either a full path, or a partial path relative to Config::sound_config::root

Returns:: ID number for future references The sound data will not be cached after done playing unless a call to loadFile is made

Definition at line 200 of file SoundManager.cc.

Referenced by chainFile(), ControlBase::doCancel(), ControlBase::doNextItem(), ControlBase::doPrevItem(), ControlBase::doReadStdIn(), WaypointWalkControl::WaypointEditControl::doSelect(), WaypointWalkControl::doSelect(), WalkCalibration::doSelect(), SensorObserverControl::doSelect(), EventLogger::doSelect(), ControlBase::doSelect(), SoundNode::DoStart(), WalkCalibration::err(), Transition::fire(), RandomTrans::fire(), PlayFile(), WalkCalibration::processEvent(), AutoGetupBehavior::processEvent(), TorqueCalibrate::record(), WalkControllerBehavior::runCommand(), UPennWalkControllerBehavior::runCommand(), RunSequenceControl< SequenceSize >::selectedFile(), PlaySoundControl::selectedFile(), LoadPostureControl::selectedFile(), ControlBase::setHilights(), EmergencyStopMC::setStopped(), WalkCalibration::takeInput(), TorqueCalibrate::TakeMeasurementControl::takeInput(), and TorqueCalibrate::TakeMeasurementControl::transition().

Member Data Documentation

unsigned int SoundManager::sn [protected]

A serial number, incremented for each sound which is created.

This is used to verify that a sound message from a process refers to a current sound. If you imaging a pathological process, which rapidly creates and releases sounds, it would run through the sndlist ids, possibly before the sound process can process the incoming buffers. So this is used to ensure that a given message refers to the current sound, and not one that was already released and then reassigned.

Definition at line 307 of file SoundManager.h.

Referenced by getNextKey(), initRegion(), and loadBuffer().

SoundManager Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Static Protected Attributes

Private Member Functions

Classes

Member Enumeration Documentation

Member Function Documentation

Member Data Documentation