 |
CUGL 1.3
Cornell University Game Library
|
|
CUGL 1.3
Cornell University Game Library
|
#include <CUAudioChannels.h>
Public Types | |
| enum | State { State::INACTIVE, State::PLAYING, State::PAUSED } |
Public Member Functions | |
| void | playMusic (const std::shared_ptr< Sound > &music, bool loop=false, float volume=-1.0f, float fade=0.0f) |
| const Sound * | currentMusic () const |
| State | getMusicState () const |
| bool | isMusicLoop () const |
| void | setMusicLoop (bool loop) |
| float | getMusicVolume () const |
| void | setMusicVolume (float volume) |
| float | getMusicPan () const |
| void | setMusicPan (float pan) |
| float | getMusicDuration () const |
| float | getMusicElapsed () const |
| float | getMusicRemaining () const |
| void | setMusicElapsed (float time) |
| void | setMusicRemaining (float time) |
| void | stopMusic (float fade=DEFAULT_FADE) |
| void | pauseMusic (float fade=DEFAULT_FADE) |
| void | resumeMusic () |
| void | setMusicListener (std::function< void(Sound *, bool)> callback) |
| std::function< void(Sound *, bool)> | getMusicListener () const |
| void | queueMusic (const std::shared_ptr< Sound > &music, bool loop=false, float volume=-1.0f, float fade=0.0f) |
| const std::vector< Sound * > | getMusicQueue () const |
| size_t | getMusicPending () const |
| float | getOverlap () const |
| void | setOverlap (double time) |
| void | advanceMusicQueue (float fade=DEFAULT_FADE, unsigned int steps=0) |
| void | clearMusicQueue () |
| bool | playEffect (const std::string &key, const std::shared_ptr< Sound > &sound, bool loop=false, float volume=-1.0f, bool force=false) |
| bool | playEffect (const char *key, const std::shared_ptr< Sound > &sound, bool loop=false, float volume=1.0f, bool force=false) |
| size_t | getAvailableChannels () const |
| State | getEffectState (const std::string &key) const |
| State | getEffectState (const char *key) const |
| bool | isActiveEffect (const std::string &key) const |
| bool | isActiveEffect (const char *key) const |
| const Sound * | currentEffect (const std::string &key) const |
| const Sound * | currentEffect (const char *key) const |
| bool | isEffectLoop (const std::string &key) const |
| bool | isEffectLoop (const char *key) const |
| void | setEffectLoop (const std::string &key, bool loop) |
| void | setEffectLoop (const char *key, bool loop) |
| float | getEffectVolume (const std::string &key) const |
| float | getEffectVolume (const char *key) const |
| void | setEffectVolume (const std::string &key, float volume) |
| void | setEffectVolume (const char *key, float volume) |
| float | getEffectPan (const std::string &key) const |
| float | getEffectPan (const char *key) const |
| void | setEffectPan (const std::string &key, float pan) |
| void | setEffectPan (const char *key, float pan) |
| float | getEffectDuration (const std::string &key) const |
| float | getEffectDuration (const char *key) const |
| float | getEffectElapsed (const std::string &key) const |
| float | getEffectElapsed (const char *key) const |
| void | setEffectElapsed (const std::string &key, float time) |
| void | setEffectElapsed (const char *key, float time) |
| float | getEffectRemaining (const std::string &key) const |
| float | getEffectRemaining (const char *key) const |
| void | setEffectRemaining (const std::string &key, float time) |
| void | setEffectRemaining (const char *key, float time) |
| void | stopEffect (const std::string &key, float fade=DEFAULT_FADE) |
| void | stopEffect (const char *key, float fade=DEFAULT_FADE) |
| void | pauseEffect (const std::string &key, float fade=DEFAULT_FADE) |
| void | pauseEffect (const char *key, float fade=DEFAULT_FADE) |
| void | resumeEffect (std::string key) |
| void | resumeEffect (const char *key) |
| void | stopAllEffects (float fade=DEFAULT_FADE) |
| void | pauseAllEffects (float fade=DEFAULT_FADE) |
| void | resumeAllEffects () |
| void | setEffectListener (std::function< void(const std::string &key, bool)> callback) |
| std::function< void(const std::string &key, bool)> | getEffectListener () const |
| void | stopAll (float fade=DEFAULT_FADE) |
| void | pauseAll (float fade=DEFAULT_FADE) |
| void | resumeAll () |
Static Public Member Functions | |
| static AudioChannels * | get () |
| static void | start (Uint32 slots) |
| static void | start (Uint32 channels, Uint32 buffer) |
| static void | stop () |
Class provides a singleton audio engine
This class is a simple (e.g. 2000-era) audio engine. It exposes a flat channel structure and there is no (publicly available) mixer graph for advanced effects such as 3D audio. If you need these features, use AudioManager instead. In fact, you should only use one of either this class or AudioManager, not both (since this class built on top of AudioManager).
This class separates sound into two categories: music and effects. In theory, streaming assets should be used as music and non-streaming assets should be used for effects. However, this difference is not enforced and any Sound asset may be used either as a music asset or an effect asset freely at any time.
Music is treated separately because we assume that only one music asset is played at a time. Music can be queued up and there a methods to manage this queue, to allow you to play a continuous, uninterrupted stream of music that reacts to the player's actions.
Effects on the other hand are intended for short sound effects that are often happening in parallel. The engine has a fixed number of "channels" or 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 channel assigned to an effect.
Sound assets may either by mono or stereo, but must be encoded at 48000 samples per second. The output of the audio engine is always stereo, regardless of the sounds asset. Mono assets are played half volume to each (left/right) speaker.
You cannot create new instances of this class. Instead, you should access the singleton through the three static methods: start(), stop(), and get().
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.
|
strong |
| void cugl::AudioChannels::advanceMusicQueue | ( | float | fade = DEFAULT_FADE, |
| unsigned int | steps = 0 |
||
| ) |
Advances ahead in the music queue.
The value fade is the number of seconds to fade out the currently playing music assets (if any). This is to ensure a smooth transition to the next song. If the music ends naturally, before this time, the fadeout will not carry over to later entries in the queue.
The value step is the number of songs to skip over. A value of 0 will simply skip over the active music to the next element of the queue. Each value above 0 will skip over one more element in the queue. If this skipping empties the queue, no music will play.
| fade | The number of seconds to fade out the current asset |
| steps | The number of elements to skip in the queue |
| void cugl::AudioChannels::clearMusicQueue | ( | ) |
Clears the music queue, but does not release any other resources.
This method does not stop the current background music from playing. It only clears pending music assets from the queue.
|
inline |
Returns the sound asset attached to the given key.
If there is no active sound effect for the given key, this method returns nullptr.
| key | the reference key for the sound effect |
| const Sound* cugl::AudioChannels::currentEffect | ( | const std::string & | key | ) | const |
Returns the sound asset attached to the given key.
If there is no active sound effect for the given key, this method returns nullptr.
| key | the reference key for the sound effect |
| const Sound* cugl::AudioChannels::currentMusic | ( | ) | const |
Returns the music asset currently playing
If there is no active background music, this method returns nullptr.
|
inlinestatic |
Returns the singleton instance of the audio engine.
If the audio engine has not been started, then this method will return nullptr.
|
inline |
Returns the number of slots or "channels" available for sound effects.
There are a limited number of channels available for sound effects. If all channels 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 channel from the longest playing sound effect.
|
inline |
Returns the duration of the sound effect, in seconds.
Because the asset is fully decompressed at load time, the result of this method is reasonably accurate.
If the key does not correspond to a channel, this method returns -1.
| key | the reference key for the sound effect |
| float cugl::AudioChannels::getEffectDuration | ( | const std::string & | key | ) | const |
Returns the duration of the sound effect, in seconds.
Because the asset is fully decompressed at load time, the result of this method is reasonably accurate.
If the key does not correspond to a channel, this method returns -1.
| key | the reference key for the sound effect |
|
inline |
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.
If the key does not correspond to a channel, this method returns -1.
| key | the reference key for the sound effect |
| float cugl::AudioChannels::getEffectElapsed | ( | 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.
If the key does not correspond to a channel, this method returns -1.
| key | the reference key for the sound effect |
|
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.
|
inline |
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.
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 a channel, this method returns 0.
| key | the reference key for the sound effect |
| float cugl::AudioChannels::getEffectPan | ( | 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.
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 a channel, this method returns 0.
| key | the reference key for the sound effect |
|
inline |
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.
If the key does not correspond to a channel, this method returns -1.
| key | the reference key for the sound effect |
| float cugl::AudioChannels::getEffectRemaining | ( | 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.
If the key does not correspond to a channel, this method returns -1.
| key | the reference key for the sound effect |
|
inline |
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.
| key | the reference key for the sound effect |
| State cugl::AudioChannels::getEffectState | ( | 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.
| key | the reference key for the sound effect |
|
inline |
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 a channel, this method returns 0.
| key | the reference key for the sound effect |
| float cugl::AudioChannels::getEffectVolume | ( | 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 a channel, this method returns 0.
| key | the reference key for the sound effect |
| float cugl::AudioChannels::getMusicDuration | ( | ) | const |
Returns the length of background music, in seconds.
This is only the duration of the active background music. All other music in the queue is ignored. If there is no active background music, this method will return 0.
This information is retrieved from the decoder. As the file is completely decoded at load time, the result of this method is reasonably accurate.
| float cugl::AudioChannels::getMusicElapsed | ( | ) | const |
Returns the elapsed time of the background music, in seconds
The elapsed time is the current position of the music from the beginning. It does not include any time spent on a continuous loop. If there is no active background music, this method will return 0.
This information is not guaranteed to be accurate. Attempting to time the playback of streaming data (as opposed to a fully in-memory PCM buffer) is very difficult and not cross-platform. We have tried to be reasonably accurate, but from our tests we can only guarantee accuracy within a 10th of a second.
|
inline |
Returns the callback for background music
This callback function is called whenever a background music track completes. It is called whether or not the music completed normally or if it was terminated manually. However, the second parameter can be used to distinguish the two cases.
| float cugl::AudioChannels::getMusicPan | ( | ) | const |
Returns the stereo pan of the background music
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 music 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.
In the case of stereo assets, panning to the left or right will mix the audio feed; this process will never lose audio.
| size_t cugl::AudioChannels::getMusicPending | ( | ) | const |
Returns the size of the music queue
| const std::vector<Sound*> cugl::AudioChannels::getMusicQueue | ( | ) | const |
Returns the list of assets for the music queue
| float cugl::AudioChannels::getMusicRemaining | ( | ) | const |
Returns the time remaining for the background music, in seconds
The time remaining is just duration-elapsed. This method does not take into account whether the music is on a loop. It also does not include the duration of any music waiting in the queue. If there is no active background music, this method will return 0.
This information is not guaranteed to be accurate. Attempting to time the playback of streaming data (as opposed to a fully in-memory PCM buffer) is very difficult and not cross-platform. We have tried to be reasonably accurate, but from our tests we can only guarantee accuracy within a 10th of a second.
| State cugl::AudioChannels::getMusicState | ( | ) | const |
Returns the current state of the background music
| float cugl::AudioChannels::getMusicVolume | ( | ) | const |
Returns the volume of the background music
The volume is a value 0 to 1, where 1 is maximum volume and 0 is complete silence. If there is no active background music, this method will return 0.
| float cugl::AudioChannels::getOverlap | ( | ) | const |
Returns the overlap time in seconds.
The overlap time is the amount of time to cross-fade between a music asset and the next. It does not apply to looped music; music assets can never cross-fade with themselves.
By default, this value is 0. Assets play sequentially but do not overlap. However, you may get smoother transitions between musical segments if you adjust this value. The overlap should be chosen with care. If the play length of an asset is less than the overlap, the results are undefined.
|
inline |
Returns true if the key is associated with an active channel.
| key | the reference key for the sound effect |
|
inline |
Returns true if the key is associated with an active channel.
| key | the reference key for the sound effect |
|
inline |
Returns true if the sound effect is in a continuous loop.
If the key does not correspond to a channel, this method returns false.
| key | the reference key for the sound effect |
| bool cugl::AudioChannels::isEffectLoop | ( | const std::string & | key | ) | const |
Returns true if the sound effect is in a continuous loop.
If the key does not correspond to a channel, this method returns false.
| key | the reference key for the sound effect |
| bool cugl::AudioChannels::isMusicLoop | ( | ) | const |
Returns true if the background music is in a continuous loop.
If there is no active background music, this method will return false.
| void cugl::AudioChannels::pauseAll | ( | 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.
| fade | the number of seconds to fade out |
| void cugl::AudioChannels::pauseAllEffects | ( | 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.
| fade | the number of seconds to fade out |
|
inline |
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 a channel, this method does nothing.
| key | the reference key for the sound effect |
| fade | the number of seconds to fade out |
| void cugl::AudioChannels::pauseEffect | ( | 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 a channel, this method does nothing.
| key | the reference key for the sound effect |
| fade | the number of seconds to fade out |
| void cugl::AudioChannels::pauseMusic | ( | float | fade = DEFAULT_FADE | ) |
Pauses the background music, allowing it to be resumed later.
Before the music is stopped, this method gives the user an option to fade out the music. If the argument is 0, it will pause the music immediately. Otherwise it will fade to completion over the given number of seconds (or until the end of the song). Only by fading can you guarantee no audible clicks.
This method has no effect on the music queue.
| fade | The number of seconds to fade out |
|
inline |
Plays the given sound effect, and associates it with the specified key.
Sound effects 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 ("channels") available for sound effects. 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.
| key | The reference key for the sound effect |
| sound | The sound effect to play |
| loop | Whether to loop the sound effect continuously |
| volume | The sound effect (< 0 to use asset default volume) |
| force | Whether to force another sound to stop. |
| bool cugl::AudioChannels::playEffect | ( | const std::string & | key, |
| const std::shared_ptr< Sound > & | sound, | ||
| bool | loop = false, |
||
| float | volume = -1.0f, |
||
| bool | force = false |
||
| ) |
Plays the given sound effect, and associates it with the specified key.
Sound effects 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 ("channels") available for sound effects. 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.
| key | The reference key for the sound effect |
| sound | The sound effect to play |
| loop | Whether to loop the sound effect continuously |
| volume | The sound effect (< 0 to use asset default volume) |
| force | Whether to force another sound to stop. |
| void cugl::AudioChannels::playMusic | ( | const std::shared_ptr< Sound > & | music, |
| bool | loop = false, |
||
| float | volume = -1.0f, |
||
| float | fade = 0.0f |
||
| ) |
Plays given music asset as a background track.
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 immediately plays the provided asset. Hence it overrides and clears the music queue. To safely play an asset without affecting the music queue, use the method queueMusic instead.
When it begins playing, the music will start at full volume unless you provide a number of seconds to fade in. Note that looping a song will cause it to block the queue indefinitely until you turn off looping for that asset {
| music | The music asset to play |
| loop | Whether to loop the music continuously |
| volume | The music volume (< 0 to use asset default volume) |
| fade | The number of seconds to fade in |
| void cugl::AudioChannels::queueMusic | ( | const std::shared_ptr< Sound > & | music, |
| bool | loop = false, |
||
| float | volume = -1.0f, |
||
| float | fade = 0.0f |
||
| ) |
Adds the given music asset to the background music queue
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.
If the queue is empty and there is no active music, this method will play the music immediately. Otherwise, it will add the music to the queue, and it will play as soon as it is removed from the queue.
When it begins playing, the music will start at full volume unless you provide a number of seconds to fade in. Note that looping a song will cause it to block the queue indefinitely until you turn off looping for that asset {
| music | The music asset to queue |
| loop | Whether to loop the music continuously |
| volume | The music volume (< 0 to use asset default volume) |
| fade | The number of seconds to fade in |
| void cugl::AudioChannels::resumeAll | ( | ) |
Resumes all paused sounds, both music and sound effects.
You should generally call this method right after the app returns from the background.
| void cugl::AudioChannels::resumeAllEffects | ( | ) |
Resumes all paused sound effects.
|
inline |
Resumes the sound effect for the given key.
If the key does not correspond to a channel, this method does nothing.
| key | the reference key for the sound effect |
| void cugl::AudioChannels::resumeEffect | ( | std::string | key | ) |
Resumes the sound effect for the given key.
If the key does not correspond to a channel, this method does nothing.
| key | the reference key for the sound effect |
| void cugl::AudioChannels::resumeMusic | ( | ) |
Resumes the background music assuming that it was paused previously.
This method has no effect on the music queue.
|
inline |
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.
If the key does not correspond to a channel, this method does nothing.
| key | the reference key for the sound effect |
| time | the new position of the sound effect |
| void cugl::AudioChannels::setEffectElapsed | ( | 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.
If the key does not correspond to a channel, this method does nothing.
| key | the reference key for the sound effect |
| time | the new position of the sound effect |
|
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.
| callback | The callback for sound effects |
|
inline |
Sets whether the sound effect is in a continuous loop.
If the key does not correspond to a channel, this method does nothing.
| key | the reference key for the sound effect |
| loop | whether the sound effect is in a continuous loop |
| void cugl::AudioChannels::setEffectLoop | ( | const std::string & | key, |
| bool | loop | ||
| ) |
Sets whether the sound effect is in a continuous loop.
If the key does not correspond to a channel, this method does nothing.
| key | the reference key for the sound effect |
| loop | whether the sound effect is in a continuous loop |
|
inline |
Sets 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.
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 a channel, this method does nothing.
| key | the reference key for the sound effect |
| pan | the stereo pan of the sound effect |
| void cugl::AudioChannels::setEffectPan | ( | const std::string & | key, |
| float | pan | ||
| ) |
Sets 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.
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 a channel, this method does nothing.
| key | the reference key for the sound effect |
| pan | the stereo pan of the sound effect |
|
inline |
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.
If the key does not correspond to a channel, this method does nothing.
| key | the reference key for the sound effect |
| time | the new time remaining for the sound effect |
| void cugl::AudioChannels::setEffectRemaining | ( | 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.
If the key does not correspond to a channel, this method does nothing.
| key | the reference key for the sound effect |
| time | the new time remaining for the sound effect |
|
inline |
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 a channel, this method does nothing.
| key | the reference key for the sound effect |
| volume | the current volume of the sound effect |
| void cugl::AudioChannels::setEffectVolume | ( | 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 a channel, this method does nothing.
| key | the reference key for the sound effect |
| volume | the current volume of the sound effect |
| void cugl::AudioChannels::setMusicElapsed | ( | float | time | ) |
Sets the elapsed time of the background music, in seconds
The elapsed time is the current position of the music from the beginning. It does not include any time spent on a continuous loop.
This adjustment is not guaranteed to be accurate. Attempting to time the playback of streaming data (as opposed to a fully in-memory PCM buffer) is very difficult and not cross-platform. We have tried to be reasonably accurate, but from our tests we can only guarantee accuracy within a 10th of a second.
If there is no active background music, this method will have no effect.
| time | the new position of the background music |
|
inline |
Sets the callback for background music
This callback function is called whenever a background music track completes. It is called whether or not the music completed normally or if it was terminated manually. However, the second parameter can be used to distinguish the two cases.
| callback | The callback for background music |
| void cugl::AudioChannels::setMusicLoop | ( | bool | loop | ) |
Sets whether the background music is on a continuous loop.
If loop is true, this will block the queue until it is set to false again. This can be desired behavior, as it gives you a way to control the speed of the queue processing.
If there is no active background music, this method will do nothing.
| loop | whether the background music should be on a continuous loop |
| void cugl::AudioChannels::setMusicPan | ( | float | pan | ) |
Sets the stereo pan of the background music
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 music 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.
In the case of stereo assets, panning to the left or right will mix the audio feed; this process will never lose audio.
| pan | The stereo pan of the background music |
| void cugl::AudioChannels::setMusicRemaining | ( | float | time | ) |
Sets the time remaining for the background music, in seconds
The time remaining is just duration-elapsed. It does not take into account whether the music is on a loop. It also does not include the duration of any music waiting in the queue.
This adjustment is not guaranteed to be accurate. Attempting to time the playback of streaming data (as opposed to a fully in-memory PCM buffer) is very difficult and not cross-platform. We have tried to be reasonably accurate, but from our tests we can only guarantee accuracy within a 10th of a second.
If there is no active background music, this method will have no effect.
| time | the new time remaining of the background music |
| void cugl::AudioChannels::setMusicVolume | ( | float | volume | ) |
Sets the volume of the background music
The volume is a value 0 to 1, where 1 is maximum volume and 0 is complete silence. If there is no active background music, this method will have no effect.
| volume | the volume of the background music |
| void cugl::AudioChannels::setOverlap | ( | double | time | ) |
Sets the overlap time in seconds.
The overlap time is the amount of time to cross-fade between a music asset and the next. It does not apply to looped music; music assets can never cross-fade with themselves.
By default, this value is 0. Assets play sequentially but do not overlap. However, you may get smoother transitions between musical segments if you adjust this value. The overlap should be chosen with care. If the play length of an asset is less than the overlap, the results are undefined.
| time | The overlap time in seconds. |
|
static |
Starts the singleton audio engine.
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.
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.
This buffer size is the number of samples collected at each poll. Smaller buffers clearly tax the CPU, as the device is collecting data at a higher rate. Furthermore, if the value is too small, the time to collect the data may be larger than the time to play it. This will result in pops and crackles in the audio.
However, larger values increase the audio lag. For example, a buffer of 1024 for a sample rate of 48000 Hz corresponds to 21 milliseconds. This is the delay between when sound is gathered and it is played. But this gathering process is also buffered, so this means that any sound effect generated at the same time that the audio device executes must wait 42 milliseconds before it can play. A value of 512 is the perfered value for 60 fps framerate. With that said, many devices cannot handle this rate and need a buffer size of 1024 instead.
| channels | The maximum number of sound effect channels to support |
| buffer | The number of samples collected at each audio poll |
|
static |
Starts the singleton audio engine.
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.
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.
This method creates an audio buffer size of 512. This is the number of samples collected at each poll. Smaller buffers clearly tax the CPU, as the device is collecting data at a higher rate. Furthermore, if the value is too small, the time to collect the data may be larger than the time to play it. This will result in pops and crackles in the audio.
However, larger values increase the audio lag. For example, a buffer of 1024 for a sample rate of 48000 Hz corresponds to 21 milliseconds. This is the delay between when sound is gathered and it is played. But this gathering process is also buffered, so this means that any sound effect generated at the same time that the audio device executes must wait 42 milliseconds before it can play. A value of 512 is the perferred value for 60 fps framerate. With that said, many devices cannot handle this rate and need a buffer size of 1024 instead.
| slots | The maximum number of sound effect channels to support |
|
static |
Stops 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.
| void cugl::AudioChannels::stopAll | ( | float | fade = DEFAULT_FADE | ) |
Stops all sounds, both music and sound effects.
Before the sounds are stopped, this method gives the user an option to fade out everything. If the argument is 0, it will halt 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 effectively clears the sound engine.
| fade | the number of seconds to fade out |
| void cugl::AudioChannels::stopAllEffects | ( | float | fade = DEFAULT_FADE | ) |
Stops all sound effects, removing them from the engine.
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.
| fade | the number of seconds to fade out |
|
inline |
Stops the sound effect for the given key, removing it.
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 a channel, this method does nothing.
| key | the reference key for the sound effect |
| fade | the number of seconds to fade out |
| void cugl::AudioChannels::stopEffect | ( | const std::string & | key, |
| float | fade = DEFAULT_FADE |
||
| ) |
Stops the sound effect for the given key, removing it.
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 a channel, this method does nothing.
| key | the reference key for the sound effect |
| fade | the number of seconds to fade out |
| void cugl::AudioChannels::stopMusic | ( | float | fade = DEFAULT_FADE | ) |
Stops the background music and clears the entire queue.
Before the music is stopped, this method gives the user an option to fade out the music. If the argument is 0, it will halt the music immediately. Otherwise it will fade to completion over the given number of seconds (or until the end of the song). Only by fading can you guarantee no audible clicks.
This method also clears the queue of any further music.
| fade | The number of seconds to fade out |
1.8.16