CUGL 2.1
Cornell University Game Library
Public Types | Public Member Functions | Static Public Member Functions | List of all members
cugl::AudioEngine Class Reference

#include <CUAudioEngine.h>

Public Types

enum  State { State::INACTIVE, State::PLAYING, State::PAUSED }
 

Public Member Functions

std::shared_ptr< AudioQueuegetMusicQueue () const
 
std::shared_ptr< AudioQueueallocQueue ()
 
void freeQueue (const std::shared_ptr< AudioQueue > &queue)
 
bool play (const std::string key, const std::shared_ptr< Sound > &sound, bool loop=false, float volume=1.0f, bool force=false)
 
bool play (const std::string key, const std::shared_ptr< audio::AudioNode > &graph, bool loop=false, float volume=1.0f, bool force=false)
 
size_t getAvailableSlots () const
 
State getState (const std::string key) const
 
bool isActive (const std::string key) const
 
const std::string getSource (const std::string key) const
 
bool isLoop (const std::string key) const
 
void setLoop (const std::string key, bool loop)
 
float getVolume (const std::string key) const
 
void setVolume (const std::string key, float volume)
 
float getPanFactor (const std::string &key) const
 
void setPanFactor (const std::string key, float pan)
 
float getDuration (const std::string key) const
 
float getTimeElapsed (const std::string key) const
 
void setTimeElapsed (const std::string key, float time)
 
float geTimeRemaining (const std::string key) const
 
void setTimeRemaining (const std::string key, float time)
 
void clear (const std::string key, float fade=DEFAULT_FADE)
 
void pause (const std::string key, float fade=DEFAULT_FADE)
 
void resume (std::string key)
 
void setListener (std::function< void(const std::string key, bool)> callback)
 
std::function< void(const std::string key, bool)> getListener () const
 
void clearEffects (float fade=DEFAULT_FADE)
 
void pauseEffects (float fade=DEFAULT_FADE)
 
void resumeEffects ()
 
void clear (float fade=DEFAULT_FADE)
 
void pause (float fade=DEFAULT_FADE)
 
void resume ()
 

Static Public Member Functions

static AudioEngineget ()
 
static bool start (Uint32 slots=DEFAULT_SLOTSIZE)
 
static bool start (const std::shared_ptr< audio::AudioOutput > &device, Uint32 slots=DEFAULT_SLOTSIZE)
 
static void stop ()
 

Detailed Description

Class provides a singleton audio engine

This module is an attempt to combine the power of a modern DSP mixer graph with a simple 2000-era interface. Like the legacy engines, it provides a a flat slot-based structure for playing sounds, and controlling the fade and pan of each slot. However, you are not limited to playing samples in the slots. You can also add arbitrary audio nodes as well.

This class is primarily designed for the playing of sound effects. These are short sound effects that are often happening in parallel. The engine has a fixed number of slots for these sounds (historically 24) and it can only play as many sounds simultaneously as it has slots. Slots are assigned automatically by the engine. However, when you play an effect, you must assign it a unique key so that you can access it later (for volume changes, panning, early termination, etc.). This key eliminates any need for tracking the slot assigned to an effect.

Music is treated separately because seamless playback requires the ability to queue up audio assets in order. As a result, this is supported through the AudioQueue interface. However, queues are owned by and acquired from this engine. There is always one music queue available, though you do have the ability to acquire more.

You cannot create new instances of this class. Instead, you should access the singleton through the three static methods: start(), stop(), and get(). Calling these methods will initialize the AudioDevices singleton, if it is not already initialized.

IMPORTANT: Like the OpenGL context, this class is not thread-safe. It is only safe to access this class in the main application thread. This means it should never be called in a call-back function as those are typically executed in the host thread. If you need to access the AudioEngine in a callback function, you should use the Application#schedule method to delay until the main thread is next available.

Member Enumeration Documentation

◆ State

This enumeration provides a way to determine the state of a slot

Enumerator
INACTIVE 

This sound channel is not actually active

PLAYING 

This sound is active and currently playing

PAUSED 

This sound is active but is currently paused

Member Function Documentation

◆ allocQueue()

std::shared_ptr<AudioQueue> cugl::AudioEngine::allocQueue ( )

Allocates a new queue for managing audio.

Music is handled differently from sound effects. You can only play one music asset at a time. However, it is possible to queue music assets for immediate playback once the active asset is finished. Proper queue management is the keep for smooth, uninterrupted playback that responds to the user's actions.

This method allocates a secondary music queue that can be played in tandem with the primary music queue. This allows for slightly more complex music mixing. However, for true vertical layering, you should use audio::AudioMixer.

It is the programmer's responsibility to free all secondary music queues with freeQueue. However, all queues are automatically freed when this audio engine is stopped.

Calling this method will briefly pause the audio engine, if it is actively playing.

Returns
a newly allocated audio queue

◆ clear() [1/2]

void cugl::AudioEngine::clear ( const std::string  key,
float  fade = DEFAULT_FADE 
)

Removes the sound effect for the given key, stopping it immediately

The effect will be removed from the audio engine entirely. You will need to add it again if you wish to replay it.

Before the effect is stopped, this method gives the user an option to fade out the effect. If the argument is 0, it will halt the sound immediately. Otherwise it will fade to completion over the given number of seconds (or until the end of the effect). Only by fading can you guarantee no audible clicks.

If the key does not correspond to an active sound effect, this method does nothing.

Parameters
keythe reference key for the sound effect
fadethe number of seconds to fade out

◆ clear() [2/2]

void cugl::AudioEngine::clear ( float  fade = DEFAULT_FADE)

Clears all active playing sounds, both music and sound effects.

Before the sounds are stopped, this method gives the user an option to fade out the effect. If the argument is 0, it will halt all sounds immediately. Otherwise it will fade the to completion over the given number of seconds (or until the end of the effect). Only by fading can you guarantee no audible clicks.

Parameters
fadethe number of seconds to fade out

◆ clearEffects()

void cugl::AudioEngine::clearEffects ( float  fade = DEFAULT_FADE)

Removes all sound effects from the engine, stopping them immediately.

Before the effects are stopped, this method gives the user an option to fade out the effect. If the argument is 0, it will halt all effects immediately. Otherwise it will fade the to completion over the given number of seconds (or until the end of the effect). Only by fading can you guarantee no audible clicks.

You will need to add the effects again if you wish to replay them. This method has no effect on the music queues.

Parameters
fadethe number of seconds to fade out

◆ freeQueue()

void cugl::AudioEngine::freeQueue ( const std::shared_ptr< AudioQueue > &  queue)

Frees a previously allocated audio queue.

This method should be called to free any audio queue created by allocQueue. It is the programmer's responsibility to free all secondary music queues. However, all queues are automatically freed when this audio engine is stopped.

This method cannot be used to free the default music queue.

Parameters
queueThe audio queue to free

◆ get()

static AudioEngine* cugl::AudioEngine::get ( )
inlinestatic

Returns the singleton instance of the audio engine.

If the audio engine has not been started, then this method will return nullptr.

Returns
the singleton instance of the audio engine.

◆ getAvailableSlots()

size_t cugl::AudioEngine::getAvailableSlots ( ) const
inline

Returns the number of slots available for sound effects.

There are a limited number of slots available for sound effects. If all slots are in use, this method will return 0. If you go over the number available, you cannot play another sound unless you force it. In that case, it will grab the slot from the longest playing sound effect.

Returns
the number of slots available for sound effects.

◆ getDuration()

float cugl::AudioEngine::getDuration ( const std::string  key) const

Returns the duration of the sound effect, in seconds.

Because most sound effects are fully decompressed at load time, the result of this method is reasonably accurate.

If the key does not correspond to an active sound effect, this method returns -1.

Parameters
keythe reference key for the sound effect
Returns
the duration of the sound effect, in seconds.

◆ geTimeRemaining()

float cugl::AudioEngine::geTimeRemaining ( const std::string  key) const

Returns the time remaining for the sound effect, in seconds

The time remaining is just duration-elapsed. This method does not take into account whether the sound is on a loop. Because most sound effects are fully decompressed at load time, the result of this method is reasonably accurate, though it is affected by device latency.

If the key does not correspond to an active sound effect, or if the sound effect is an audio node with undefined duration, this method method returns -1.

Parameters
keythe reference key for the sound effect
Returns
the time remaining for the sound effect, in seconds

◆ getListener()

std::function<void(const std::string key,bool)> cugl::AudioEngine::getListener ( ) const
inline

Returns the callback for sound effects

This callback function is called whenever a sound effect completes. It is called whether or not the sound completed normally or if it was terminated manually. However, the second parameter can be used to distinguish the two cases.

Returns
the callback for sound effects

◆ getMusicQueue()

std::shared_ptr<AudioQueue> cugl::AudioEngine::getMusicQueue ( ) const

Returns the default music queue for this audio engine

Music is managed through audio queues.The audio engine has one by default, though you can allocate more with allocQueue.

Music is handled differently from sound effects. You can only play one music asset at a time. However, it is possible to queue music assets for immediate playback once the active asset is finished. Proper queue management is the keep for smooth, uninterrupted playback that responds to the user's actions.

◆ getPanFactor()

float cugl::AudioEngine::getPanFactor ( const std::string &  key) const

Returns the stereo pan of the sound effect.

This audio engine provides limited (e.g. not full 3D) stereo panning for simple effects. The pan value is a float from -1 to 1. A value of 0 (default) plays to both channels (regardless of whether the current effect is mono or stereo). A value of -1 will play to the left channel only, while the right will play to the right channel only. Channels beyond the first two are unaffected.

In the case of stereo assets, panning to the left or right will mix the audio feed; this process will never lose audio.

If the key does not correspond to an active sound effect, this method returns 0.

Parameters
keythe reference key for the sound effect
Returns
the stereo pan of the sound effect

◆ getSource()

const std::string cugl::AudioEngine::getSource ( const std::string  key) const

Returns the identifier for the asset attached to the given key.

If the current playing track is an Sound asset, then the identifier is the file name. Otherwise, it is the name of the root of the audio graph. See audio::AudioNode#getName.

Parameters
keythe reference key for the sound effect
Returns
the identifier for the asset attached to the given key.

◆ getState()

State cugl::AudioEngine::getState ( const std::string  key) const

Returns the current state of the sound effect for the given key.

If there is no sound effect for the given key, it returns State::INACTIVE.

Parameters
keythe reference key for the sound effect
Returns
the current state of the sound effect for the given key.

◆ getTimeElapsed()

float cugl::AudioEngine::getTimeElapsed ( const std::string  key) const

Returns the elapsed time of the sound effect, in seconds

The elapsed time is the current position of the sound from the beginning. It does not include any time spent on a continuous loop. Because most sound effects are fully decompressed at load time, the result of this method is reasonably accurate, though it is affected by device latency.

If the key does not correspond to an active sound effect, or if the sound effect is an audio node with undefined duration, this method returns -1.

Parameters
keythe reference key for the sound effect
Returns
the elapsed time of the sound effect, in seconds

◆ getVolume()

float cugl::AudioEngine::getVolume ( const std::string  key) const

Returns the current volume of the sound effect.

The volume is a value 0 to 1, where 1 is maximum volume and 0 is complete silence. If the key does not correspond to an active sound effect, this method returns 0.

Note that this is the playback volume. If the asset or audio graph had its own initial volume setting, this is independent of this setting. Indeed, this value can be though of as the percentage of the default volume.

Parameters
keythe reference key for the sound effect
Returns
the current volume of the sound effect

◆ isActive()

bool cugl::AudioEngine::isActive ( const std::string  key) const
inline

Returns true if the key is associated with an active sound.

Parameters
keythe reference key for the sound effect
Returns
true if the key is associated with an active sound.

◆ isLoop()

bool cugl::AudioEngine::isLoop ( const std::string  key) const

Returns true if the sound effect is in a continuous loop.

If the key does not correspond to an active sound effect, this method returns false.

Parameters
keythe reference key for the sound effect
Returns
true if the sound effect is in a continuous loop.

◆ pause() [1/2]

void cugl::AudioEngine::pause ( const std::string  key,
float  fade = DEFAULT_FADE 
)

Pauses the sound effect for the given key.

Before the effect is paused, this method gives the user an option to fade out the effect. If the argument is 0, it will pause the sound immediately. Otherwise it will fade to completion over the given number of seconds (or until the end of the effect). Only by fading can you guarantee no audible clicks.

If the key does not correspond to an active sound effect, this method does nothing.

Parameters
keythe reference key for the sound effect
fadethe number of seconds to fade out

◆ pause() [2/2]

void cugl::AudioEngine::pause ( float  fade = DEFAULT_FADE)

Pauses all sounds, both music and sound effects.

Before the sounds are paused, this method gives the user an option to fade out everything. If the argument is 0, it will pause the sounds immediately. Otherwise it will fade everythign to completion over the given number of seconds (or until the end of each sound). Only by fading can you guarantee no audible clicks.

This method allows them to be resumed later. You should generally call this method just before the app pages to the background.

Parameters
fadethe number of seconds to fade out

◆ pauseEffects()

void cugl::AudioEngine::pauseEffects ( float  fade = DEFAULT_FADE)

Pauses all sound effects, allowing them to be resumed later.

Before the effects are paused, this method gives the user an option to fade out the effect. If the argument is 0, it will pause all effects immediately. Otherwise it will fade the to completion over the given number of seconds (or until the end of the effect). Only by fading can you guarantee no audible clicks.

Sound effects already paused will remain paused. This method has no effect on the music queues.

Parameters
fadethe number of seconds to fade out

◆ play() [1/2]

bool cugl::AudioEngine::play ( const std::string  key,
const std::shared_ptr< audio::AudioNode > &  graph,
bool  loop = false,
float  volume = 1.0f,
bool  force = false 
)

Plays the given audio node, and associates it with the specified key.

This alternate version of play allows the programmer to construct custom composite audio graphs and play them as sound effects. Looping behavior is supported if the audio node has a finite duration.

As with traditional sounds, the audio node is assigned a key to allow the application to easily reference the sound state without having to internally manage pointers to the audio channel. In particular, if the audio node provided does not have a fixed duration, and can be played indefinitely, then the key must be used to stop the sound.

If the key is already associated with an active sound effect, this method will stop the existing sound and replace it with this one. It is the responsibility of the application layer to manage key usage.

There are a limited number of slots available for sounds. If you go over the number available, the sound will not play unless force is true. In that case, it will grab the channel from the longest playing sound effect.

Parameters
keyThe reference key for the sound effect
graphThe audio graph to play
loopWhether to loop the sound effect continuously
volumeThe music volume (relative to the default instance volume)
forceWhether to force another sound to stop.
Returns
true if there was an available channel for the sound

◆ play() [2/2]

bool cugl::AudioEngine::play ( const std::string  key,
const std::shared_ptr< Sound > &  sound,
bool  loop = false,
float  volume = 1.0f,
bool  force = false 
)

Plays the given sound, and associates it with the specified key.

Sounds are associated with a reference key. This allows the application to easily reference the sound state without having to internally manage pointers to the audio channel.

If the key is already associated with an active sound effect, this method will stop the existing sound and replace it with this one. It is the responsibility of the application layer to manage key usage.

There are a limited number of slots available for sounds. If you go over the number available, the sound will not play unless force is true. In that case, it will grab the channel from the longest playing sound effect.

Parameters
keyThe reference key for the sound effect
soundThe sound effect to play
loopWhether to loop the sound effect continuously
volumeThe music volume (relative to the default asset volume)
forceWhether to force another sound to stop.
Returns
true if there was an available channel for the sound

◆ resume() [1/2]

void cugl::AudioEngine::resume ( )

Resumes all paused sounds, both music and sound effects.

You should generally call this method right after the app returns from the background.

◆ resume() [2/2]

void cugl::AudioEngine::resume ( std::string  key)

Resumes the sound effect for the given key.

If the key does not correspond to a channel, this method does nothing.

Parameters
keythe reference key for the sound effect

◆ resumeEffects()

void cugl::AudioEngine::resumeEffects ( )

Resumes all paused sound effects.

This method has no effect on the music queues.

◆ setListener()

void cugl::AudioEngine::setListener ( std::function< void(const std::string key, bool)>  callback)
inline

Sets the callback for sound effects

This callback function is called whenever a sound effect completes. It is called whether or not the sound completed normally or if it was terminated manually. However, the second parameter can be used to distinguish the two cases.

Parameters
callbackThe callback for sound effects

◆ setLoop()

void cugl::AudioEngine::setLoop ( const std::string  key,
bool  loop 
)

Sets whether the sound effect is in a continuous loop.

If the key does not correspond to an active sound effect, this method does nothing.

Parameters
keythe reference key for the sound effect
loopwhether the sound effect is in a continuous loop

◆ setPanFactor()

void cugl::AudioEngine::setPanFactor ( const std::string  key,
float  pan 
)

Returns the stereo pan of the sound effect.

This audio engine provides limited (e.g. not full 3D) stereo panning for simple effects. The pan value is a float from -1 to 1. A value of 0 (default) plays to both channels (regardless of whether the current effect is mono or stereo). A value of -1 will play to the left channel only, while the right will play to the right channel only. Channels beyond the first two are unaffected.

In the case of stereo assets, panning to the left or right will mix the audio feed; this process will never lose audio.

If the key does not correspond to an active sound effect, this method does nothing.

Parameters
keythe reference key for the sound effect
panthe stereo pan of the sound effect

◆ setTimeElapsed()

void cugl::AudioEngine::setTimeElapsed ( const std::string  key,
float  time 
)

Sets the elapsed time of the sound effect, in seconds

The elapsed time is the current position of the sound from the beginning. It does not include any time spent on a continuous loop. Because most sound effects are fully decompressed at load time, the result of this method is reasonably accurate, though it is affected by device latency.

If the key does not correspond to an active sound effect, or if the sound effect is an audio node with undefined duration, this method does nothing.

Parameters
keythe reference key for the sound effect
timethe new position of the sound effect

◆ setTimeRemaining()

void cugl::AudioEngine::setTimeRemaining ( const std::string  key,
float  time 
)

Sets the time remaining for the sound effect, in seconds

The time remaining is just duration-elapsed. This method does not take into account whether the sound is on a loop. Because most sound effects are fully decompressed at load time, the result of this method is reasonably accurate, though it is affected by device latency.

If the key does not correspond to an active sound effect, or if the sound effect is an audio node with undefined duration, this method does nothing.

Parameters
keythe reference key for the sound effect
timethe new time remaining for the sound effect

◆ setVolume()

void cugl::AudioEngine::setVolume ( const std::string  key,
float  volume 
)

Sets the current volume of the sound effect.

The volume is a value 0 to 1, where 1 is maximum volume and 0 is complete silence. If the key does not correspond to an active sound effect, this method does nothing.

Note that this is the playback volume. If the asset or audio graph had its own initial volume setting, this is independent of this setting. Indeed, this value can be though of as the percentage of the default volume.

Parameters
keythe reference key for the sound effect
volumethe current volume of the sound effect

◆ start() [1/2]

static bool cugl::AudioEngine::start ( const std::shared_ptr< audio::AudioOutput > &  device,
Uint32  slots = DEFAULT_SLOTSIZE 
)
static

Starts the singleton audio engine on the given audio device.

Once this method is called, the method get() will no longer return nullptr. Calling the method multiple times (without calling stop) will have no effect.

This version of the method assumes that the programmer has already started the AudioDevices manager. It will not restart the manager, nor will it shutdown the audio manager when done. This version of the initializer is only for programmers that need lower-level control over buffer size and sampling rate.

The parameter slots indicates the number of simultaneously supported sounds. Attempting to play more than this number of sounds may fail, it may eject a previously playing sound, depending on the settings. The default number of slots is 16.

Parameters
deviceThe audio device to use for this engine
slotsThe maximum number of sound slots to support
Returns
true if the engine was successfully initialized

◆ start() [2/2]

static bool cugl::AudioEngine::start ( Uint32  slots = DEFAULT_SLOTSIZE)
static

Starts the singleton audio engine on the default audio device.

Once this method is called, the method get() will no longer return nullptr. Calling the method multiple times (without calling stop) will have no effect.

This convenience method will start up the AudioDevices manager, and take responsibility for shutting it down when done. As a result, it will fail if the audio device manager is already active or cannot be initialized. If you need more control of the audio devices (such as to change the audio sampling rate or the buffer size), you should use start the engine with a specific output device.

The engine initialized by this method has a uniform sampling rate of 48000 Hz. This is the standard rate for phone games. However, keep in mind that CD audio is typically sampled at 44100 Hz.

The parameter slots indicates the number of simultaneously supported sounds. Attempting to play more than this number of sounds may fail, it may eject a previously playing sound, depending on the settings. The default number of slots is 16.

Parameters
slotsThe maximum number of sound slots to support
Returns
true if the engine was successfully initialized

◆ stop()

static void cugl::AudioEngine::stop ( )
static

Shutsdown the singleton audio engine, releasing all resources.

Once this method is called, the method get() will return nullptr. Calling the method multiple times (without calling stop) will have no effect.

If the engine was started with the convenience method start(Uint32), then this method will also stop the AudioDevices manager. Otherwise, it is the responsibility of the programmer to shutdown the device manager.


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