OALSimpleAudio Class Reference

A simpler interface to the ObjectAL sound library. More...

#import <OALSimpleAudio.h>

Inheritance diagram for OALSimpleAudio:

Instance Methods
(bool)	- preloadBg:
	Preload background music. More...
(bool)	- preloadBg:seekTime:
	Preload background music. More...
(bool)	- playBg
	Play whatever background music is preloaded. More...
(bool)	- playBgWithLoop:
	Play whatever background music is preloaded. More...
(bool)	- playBg:
	Play the background music at the specified path. More...
(bool)	- playBg:loop:
	Play the background music at the specified path. More...
(bool)	- playBg:volume:pan:loop:
	Play the background music at the specified path. More...
(void)	- stopBg
	Stop the background music playback and rewind. More...
(ALBuffer *)	- preloadEffect:
	Preload and cache a sound effect for later playback. More...
(ALBuffer *)	- preloadEffect:reduceToMono:
	Preload and cache a sound effect for later playback. More...
(bool)	- unloadEffect:
	Unload a preloaded effect. More...
(void)	- unloadAllEffects
	Unload all preloaded effects that are not currently being played (paused or not). More...
(id< ALSoundSource >)	- playEffect:
	Play a sound effect with volume 1.0, pitch 1.0, pan 0.0, loop NO. More...
(id< ALSoundSource >)	- playEffect:loop:
	Play a sound effect with volume 1.0, pitch 1.0, pan 0.0. More...
(id< ALSoundSource >)	- playEffect:volume:pitch:pan:loop:
	Play a sound effect. More...
(id< ALSoundSource >)	- playBuffer:volume:pitch:pan:loop:
	Play a sound effect from a user-supplied buffer. More...
(void)	- stopAllEffects
	Stop ALL sound effect playback. More...
(void)	- stopEverything
	Stop all effects and bg music. More...
(void)	- resetToDefault
	Reset everything in this object to its default state. More...

Class Methods
(OALSimpleAudio *)	+ sharedInstanceWithSources:
	Start OALSimpleAudio with the specified number of reserved sources. More...
(OALSimpleAudio *)	+ sharedInstanceWithReservedSources:monoSources:stereoSources:
	Start OALSimpleAudio with the specified parameters. More...

Protected Member Functions
()	- SYNTHESIZE_SINGLETON_FOR_CLASS_HEADER
	Singleton implementation providing "sharedInstance" and "purgeSharedInstance" methods. More...

Protected Attributes
NSMutableDictionary *	preloadCache
	Cache for preloaded sound samples. More...
uint	pendingLoadCount
	keeping track of how many effects remain to be loaded More...

Properties
bool	allowIpod
	If YES, allow ipod music to continue playing (NOT SUPPORTED ON THE SIMULATOR). More...
bool	useHardwareIfAvailable
	Determines what to do if no other application is playing audio and allowIpod = YES (NOT SUPPORTED ON THE SIMULATOR). More...
bool	honorSilentSwitch
	If true, mute when backgrounded, screen locked, or the ringer switch is turned off (NOT SUPPORTED ON THE SIMULATOR). More...
int	reservedSources
	The number of sources OALSimpleAudio is using (max 32 on current iOS devices). More...
ALDevice *	device
	The device we are using. More...
ALContext *	context
	The context we are using. More...
ALChannelSource *	channel
	The sound channel used by this object. More...
NSURL *	backgroundTrackURL
	Background audio URL. More...
OALAudioTrack *	backgroundTrack
	Audio track to play background music. More...
bool	bgPaused
	Pauses BG music playback. More...
bool	bgMuted
	Mutes BG music playback. More...
bool	bgPlaying
	If true, BG music is currently playing. More...
float	bgVolume
	Background music playback gain/volume (0.0 - 1.0) More...
bool	effectsPaused
	Pauses effects playback. More...
bool	effectsMuted
	Mutes effects playback. More...
float	effectsVolume
	Master effects gain/volume (0.0 - 1.0) More...
bool	paused
	Pauses everything. More...
bool	muted
	Mutes all audio. More...
bool	preloadCacheEnabled
	Enables/disables the preload cache. More...
NSUInteger	preloadCacheCount
	The number of items currently in the preload cache. More...
bool	manuallySuspended
	Set to YES to manually suspend the sound system. More...
bool	interrupted
	If YES, the sound system is interrupted. More...
bool	suspended
	If YES, the sound system is suspended. More...

Detailed Description

A simpler interface to the ObjectAL sound library.

This singleton can be used alone for simpler audio needs, or in conjunction with user-created audio objects for more advanced needs (as is done in many of the demos).

For sound effects, it initializes OpenAL with the default ALDevice, an ALContext, and an ALChannelSource consisting of all 32 interruptible ALSource objects (the maximum currently allowed for iOS). If you want to create your own sources as well, change the reservedSources property.

For background audio, it creates a single OALAudioTrack, which will not reserve resources unless used. (you can create more OALAudioTrack objects for your own use if you want).

This singleton also provides access to the more common configuration options available in OALAudioSupport.

All audio playback commands are delegated either to the ALChannelSource (for sound effects), or to the OALAudioTrack (for BG music).

Method Documentation

- (bool) playBg

Play whatever background music is preloaded.

Returns

TRUE if the operation was successful.

- (bool) playBg:

(NSString*)

path

Play the background music at the specified path.

If the music has not been preloaded, this method will load the music and then play, incurring a slight delay.

Note: only ONE background music file may be played or preloaded at a time via OALSimpleAudio. If you play or preload another file, the one currently playing will stop.

Parameters

path	The path containing the background music.

Returns

TRUE if the operation was successful.

- (bool) playBg:		(NSString*)	path
loop:		(bool)	loop

Play the background music at the specified path.

If the music has not been preloaded, this method will load the music and then play, incurring a slight delay.

Note: only ONE background music file may be played or preloaded at a time via OALSimpleAudio. If you play or preload another file, the one currently playing will stop.

Parameters

path	The path containing the background music.
loop	If true, loop the bg track.

Returns

TRUE if the operation was successful.

- (bool) playBg:		(NSString*)	filePath
volume:		(float)	volume
pan:		(float)	pan
loop:		(bool)	loop

Play the background music at the specified path.

If the music has not been preloaded, this method will load the music and then play, incurring a slight delay.

Note: only ONE background music file may be played or preloaded at a time via OALSimpleAudio. If you play or preload another file, the one currently playing will stop. To play multiple audio tracks, create an OALAudioTrack.

Note: pan will have no effect when running on iOS versions prior to 4.0.

Parameters

filePath	The path containing the sound data.
volume	The volume (gain) to play at (0.0 - 1.0).
pan	Left-right panning (-1.0 = far left, 1.0 = far right) (Only on iOS 4.0+).
loop	If TRUE, the sound will loop until you call "stopBg".

Returns

TRUE if the operation was successful.

- (bool) playBgWithLoop:

(bool)

loop

Play whatever background music is preloaded.

Parameters

loop	If true, loop the bg track.

Returns

TRUE if the operation was successful.

- (id< ALSoundSource >) playBuffer:		(ALBuffer*)	buffer
volume:		(float)	volume
pitch:		(float)	pitch
pan:		(float)	pan
loop:		(bool)	loop

Play a sound effect from a user-supplied buffer.

Parameters

buffer	The buffer containing the sound data.
volume	The volume (gain) to play at (0.0 - 1.0).
pitch	The pitch to play at (1.0 = normal pitch).
pan	Left-right panning (-1.0 = far left, 1.0 = far right).
loop	If TRUE, the sound will loop until you call "stop" on the returned sound source.

Returns

The sound source being used for playback, or nil if an error occurred (You'll need to keep this if you want to be able to stop a looped playback).

- (id< ALSoundSource >) playEffect:

(NSString*)

filePath

Play a sound effect with volume 1.0, pitch 1.0, pan 0.0, loop NO.

The sound will be loaded and cached if it wasn't already.

Parameters

filePath

The path containing the sound data.

Returns

The sound source being used for playback, or nil if an error occurred.

- (id< ALSoundSource >) playEffect:		(NSString*)	filePath
loop:		(bool)	loop

Play a sound effect with volume 1.0, pitch 1.0, pan 0.0.

The sound will be loaded and cached if it wasn't already.

Parameters

filePath	The path containing the sound data.
loop	If TRUE, the sound will loop until you call "stop" on the returned sound source.

Returns

The sound source being used for playback, or nil if an error occurred.

- (id< ALSoundSource >) playEffect:		(NSString*)	filePath
volume:		(float)	volume
pitch:		(float)	pitch
pan:		(float)	pan
loop:		(bool)	loop

Play a sound effect.

The sound will be loaded and cached if it wasn't already.

Parameters

filePath	The path containing the sound data.
volume	The volume (gain) to play at (0.0 - 1.0).
pitch	The pitch to play at (1.0 = normal pitch).
pan	Left-right panning (-1.0 = far left, 1.0 = far right).
loop	If TRUE, the sound will loop until you call "stop" on the returned sound source.

Returns

The sound source being used for playback, or nil if an error occurred (You'll need to keep this if you want to be able to stop a looped playback).

- (bool) preloadBg:

(NSString*)

path

Preload background music.

Note: only ONE background music file may be played or preloaded at a time via OALSimpleAudio. If you play or preload another file, the one currently playing will stop.

Parameters

path	The path containing the background music.

Returns

TRUE if the operation was successful.

- (bool) preloadBg:		(NSString*)	path
seekTime:		(NSTimeInterval)	seekTime

Preload background music.

Note: only ONE background music file may be played or preloaded at a time via OALSimpleAudio. If you play or preload another file, the one currently playing will stop.

Parameters

path	The path containing the background music.
seekTime	the position in the file to start playing at.

Returns

TRUE if the operation was successful.

- (ALBuffer *) preloadEffect:

(NSString*)

filePath

Preload and cache a sound effect for later playback.

Parameters

filePath

The path containing the sound data.

- (ALBuffer *) preloadEffect:		(NSString*)	filePath
reduceToMono:		(bool)	reduceToMono

Preload and cache a sound effect for later playback.

Parameters

filePath	The path containing the sound data.
reduceToMono	If true, reduce the sample to mono (stereo samples don't support panning or positional audio).

- (void) resetToDefault

Reset everything in this object to its default state.

+ (OALSimpleAudio *) sharedInstanceWithReservedSources:		(int)	reservedSources
monoSources:		(int)	monoSources
stereoSources:		(int)	stereoSources

Start OALSimpleAudio with the specified parameters.

With this initializer, you can set the total number of mono and stereo sources available, as well as how many sources are to be reserved by OALSimpleAudio.

The number of mono and stereo sources represents the GLOBAL number of sources available for EVERYONE, not just OALSimpleAudio. Their combined values must not exceed 32 (the max allowed sources in iOS).

reservedSources is independent of this; it represents how many of the above mentioned sources to reserve for OALSimpleAudio's use.

Note: This method must be called ONLY ONCE, BEFORE any attempt is made to access the shared instance.

Parameters

reservedSources	The number of sources to reserve for OALSimpleAudio's use when initializing. iOS currently supports up to 32 sources total.
monoSources	The GLOBAL number of sources supporting mono (default 28).
stereoSources	The GLOBAL number of sources supporting stereo (default 4).

Returns

The shared instance.

+ (OALSimpleAudio *) sharedInstanceWithSources:

(int)

sources

Start OALSimpleAudio with the specified number of reserved sources.

Call this initializer if you want to use OALSimpleAudio, but keep some of the device's audio sources (there are 32 in total) for your own use.
Note: This method must be called ONLY ONCE, BEFORE any attempt is made to access the shared instance. To change the reserved sources after instantiation, modify reservedSources.

Parameters

sources

the number of sources OALSimpleAudio will reserve for itself.

Returns

The shared instance.

- (void) stopAllEffects

Stop ALL sound effect playback.

- (void) stopBg

Stop the background music playback and rewind.

- (void) stopEverything

Stop all effects and bg music.

- OALSimpleAudio:

(OALSimpleAudio)

Singleton implementation providing "sharedInstance" and "purgeSharedInstance" methods.

- (OALSimpleAudio*) sharedInstance: Get the shared singleton instance.
- (void) purgeSharedInstance: Purge (deallocate) the shared instance.

- (void) unloadAllEffects

Unload all preloaded effects that are not currently being played (paused or not).

Turning on debug logging will show which effects were not unloaded. It is useful to put a call to this method in "applicationDidReceiveMemoryWarning" in your app delegate.

- (bool) unloadEffect:

(NSString*)

filePath

Unload a preloaded effect.

Only unloads if no source is currently playing that effect (or paused with the effect loaded).

Parameters

filePath

The path containing the sound data that was previously loaded.

Returns

YES if the effect was unloaded. Turn on debug logging to see why an effect was not unloaded.

Member Data Documentation

- (uint) pendingLoadCount

protected

keeping track of how many effects remain to be loaded

- (NSMutableDictionary*) preloadCache

protected

Cache for preloaded sound samples.

Property Documentation

- (bool) allowIpod

readwritenonatomicassign

If YES, allow ipod music to continue playing (NOT SUPPORTED ON THE SIMULATOR).

Note: If this is enabled, and another app is playing music, background audio playback will use the SOFTWARE codecs, NOT hardware.

If allowIpod = NO, the application will ALWAYS use hardware decoding.

iOS Only.

See Also

useHardwareIfAvailable

Default value: YES

- (OALAudioTrack *) backgroundTrack

readnonatomicretain

Audio track to play background music.

Background audio track.

- (NSURL *) backgroundTrackURL

readnonatomicretain

Background audio URL.

- (bool) bgMuted

readwritenonatomicassign

Mutes BG music playback.

- (bool) bgPaused

readwritenonatomicassign

Pauses BG music playback.

- (bool) bgPlaying

readnonatomicassign

If true, BG music is currently playing.

- (float) bgVolume

readwritenonatomicassign

Background music playback gain/volume (0.0 - 1.0)

- (ALChannelSource *) channel

readnonatomicretain

The sound channel used by this object.

The channel source used by OALSimpleAudio.

Only mess with this if you know what you are doing!

- (ALContext *) context

readnonatomicretain

The context we are using.

- (ALDevice *) device

readnonatomicretain

The device we are using.

- (bool) effectsMuted

readwritenonatomicassign

Mutes effects playback.

- (bool) effectsPaused

readwritenonatomicassign

Pauses effects playback.

- (float) effectsVolume

readwritenonatomicassign

Master effects gain/volume (0.0 - 1.0)

- (bool) honorSilentSwitch

readwritenonatomicassign

If true, mute when backgrounded, screen locked, or the ringer switch is turned off (NOT SUPPORTED ON THE SIMULATOR).

iOS Only.

Default value: YES

- (bool) interrupted

readnonatomicassign

If YES, the sound system is interrupted.

iOS Only.

- (bool) manuallySuspended

readwritenonatomicassign

Set to YES to manually suspend the sound system.

- (bool) muted

readwritenonatomicassign

Mutes all audio.

- (bool) paused

readwritenonatomicassign

Pauses everything.

- (NSUInteger) preloadCacheCount

readnonatomicassign

The number of items currently in the preload cache.

- (bool) preloadCacheEnabled

readwritenonatomicassign

Enables/disables the preload cache.

If the preload cache is disabled, effects preloading will do nothing (BG preloading will still work).

- (int) reservedSources

readwritenonatomicassign

The number of sources OALSimpleAudio is using (max 32 on current iOS devices).

- (bool) suspended

readnonatomicassign

If YES, the sound system is suspended.

- (bool) useHardwareIfAvailable

readwritenonatomicassign

Determines what to do if no other application is playing audio and allowIpod = YES (NOT SUPPORTED ON THE SIMULATOR).

If NO, the application will ALWAYS use software decoding. The advantage to this is that the user can background your application and then start audio playing from another application. If useHardwareIfAvailable = YES, the user won't be able to do this.

If this is set to YES, the application will use hardware decoding if no other application is currently playing audio. However, no other application will be able to start playing audio if it wasn't playing already.

Note: This switch has no effect if allowIpod = NO.

iOS Only.

See Also

allowIpod

Default value: YES

---

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

• OALSimpleAudio.h
• OALSimpleAudio.m