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

#import <OALSimpleAudio.h>

Collaboration diagram for OALSimpleAudio:

Public Member Functions
(id)	- initWithSources:
	(INTERNAL USE) Initialize with the specified number of reserved sources.
(id)	- initWithReservedSources:monoSources:stereoSources:
	(INTERNAL USE) Initialize with the specified parameters.
(bool)	- preloadBg:
	Preload background music.
(bool)	- preloadBg:seekTime:
	Preload background music.
(bool)	- playBg
	Play whatever background music is preloaded.
(bool)	- playBgWithLoop:
	Play whatever background music is preloaded.
(bool)	- playBg:
	Play the background music at the specified path.
(bool)	- playBg:loop:
	Play the background music at the specified path.
(bool)	- playBg:volume:pan:loop:
	Play the background music at the specified path.
(void)	- stopBg
	Stop the background music playback and rewind.
(ALBuffer *)	- preloadEffect:
	Preload and cache a sound effect for later playback.
(ALBuffer *)	- preloadEffect:reduceToMono:
	Preload and cache a sound effect for later playback.
(BOOL)	- preloadEffect:reduceToMono:completionBlock:
	Asynchronous preload and cache sound effect for later playback.
(void)	- preloadEffects:reduceToMono:progressBlock:
	Asynchronous preload and cache multiple sound effects for later playback.
(void)	- unloadEffect:
	Unload a preloaded effect.
(void)	- unloadAllEffects
	Unload all preloaded effects.
(id< ALSoundSource >)	- playEffect:
	Play a sound effect with volume 1.0, pitch 1.0, pan 0.0, loop NO.
(id< ALSoundSource >)	- playEffect:loop:
	Play a sound effect with volume 1.0, pitch 1.0, pan 0.0.
(id< ALSoundSource >)	- playEffect:volume:pitch:pan:loop:
	Play a sound effect.
(id< ALSoundSource >)	- playBuffer:volume:pitch:pan:loop:
	Play a sound effect from a user-supplied buffer.
(void)	- stopAllEffects
	Stop ALL sound effect playback.
(void)	- stopEverything
	Stop all effects and bg music.
(void)	- resetToDefault
	Reset everything in this object to its default state.
Static Public Member Functions
(OALSimpleAudio *)	+ sharedInstanceWithSources:
	Start OALSimpleAudio with the specified number of reserved sources.
(OALSimpleAudio *)	+ sharedInstanceWithReservedSources:monoSources:stereoSources:
	Start OALSimpleAudio with the specified parameters.
Protected Member Functions
()	- SYNTHESIZE_SINGLETON_FOR_CLASS_HEADER
	Singleton implementation providing "sharedInstance" and "purgeSharedInstance" methods.
Protected Attributes
ALDevice *	device
	The device we are using.
ALContext *	context
	The context we are using.
NSMutableDictionary *	preloadCache
	Cache for preloaded sound samples.
dispatch_queue_t	oal_dispatch_queue
	Queue for preloading and async operations that use blocks.
uint	pendingLoadCount
	keeping track of how many effects remain to be loaded
Properties
bool	allowIpod
	If YES, allow ipod music to continue playing (NOT SUPPORTED ON THE SIMULATOR).
bool	useHardwareIfAvailable
	Determines what to do if no other application is playing audio and allowIpod = YES (NOT SUPPORTED ON THE SIMULATOR).
bool	honorSilentSwitch
	If true, mute when backgrounded, screen locked, or the ringer switch is turned off (NOT SUPPORTED ON THE SIMULATOR).
int	reservedSources
	The number of sources OALSimpleAudio is using (max 32 on current iOS devices).
ALChannelSource *	channel
	The sound channel used by this object.
NSURL *	backgroundTrackURL
	Background audio URL.
OALAudioTrack *	backgroundTrack
	Audio track to play background music.
bool	bgPaused
	Pauses BG music playback.
bool	bgMuted
	Mutes BG music playback.
bool	bgPlaying
	If true, BG music is currently playing.
float	bgVolume
	Background music playback gain/volume (0.0 - 1.0)
bool	effectsPaused
	Pauses effects playback.
bool	effectsMuted
	Mutes effects playback.
float	effectsVolume
	Master effects gain/volume (0.0 - 1.0)
bool	paused
	Pauses everything.
bool	muted
	Mutes all audio.
bool	preloadCacheEnabled
	Enables/disables the preload cache.
NSUInteger	preloadCacheCount
	The number of items currently in the preload cache.
bool	manuallySuspended
	Set to YES to manually suspend the sound system.
bool	interrupted
	If YES, the sound system is interrupted.
bool	suspended
	If YES, the sound system is suspended.

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).

Member Function Documentation

- (id) initWithReservedSources:	(int)	reservedSources
monoSources:	(int)	monoSources
stereoSources:	(int)	stereoSources

(INTERNAL USE) Initialize with the specified parameters.

Parameters:

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

Returns:: The shared instance.

- (id) initWithSources: (int) reservedSources

(INTERNAL USE) Initialize with the specified number of reserved sources.

Parameters:

reservedSources the number of sources to reserve when initializing.

Returns:: The shared instance.

- (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).

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

Asynchronous preload and cache sound effect for later playback.

Parameters:

filePath	an NSString with the path containing the sound data.
reduceToMono	If true, reduce the sample to mono (stereo samples don't support panning or positional audio).
completionBlock	Executed when loading is complete.

- (void) preloadEffects:	(NSArray*)	filePaths
reduceToMono:	(bool)	reduceToMono
progressBlock:	(uint progress, uint successCount, uint total)	progressBlock

Asynchronous preload and cache multiple sound effects for later playback.

Parameters:

filePaths	An NSArray of NSStrings with the paths containing the sound data.
reduceToMono	If true, reduce the samples to mono (stereo samples don't support panning or positional audio).
progressBlock	Executed regularly while file loading is in progress.

- (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.

It is useful to put a call to this method in "applicationDidReceiveMemoryWarning" in your app delegate.

- (void) unloadEffect: (NSString*) filePath

Unload a preloaded effect.

Parameters:

filePath The path containing the sound data that was previously loaded.

Member Data Documentation

- (ALContext*) context [protected]

The context we are using.

- (ALDevice*) device [protected]

The device we are using.

- (dispatch_queue_t) oal_dispatch_queue [protected]

Queue for preloading and async operations that use blocks.

This ensures all operations are safe because they are guaranteed to run in order.

- (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 [read, write, assign]

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.

See also:: useHardwareIfAvailable

Default value: YES

- (OALAudioTrack *) backgroundTrack [read, assign]

Audio track to play background music.

Background audio track.

- (NSURL *) backgroundTrackURL [read, assign]

Background audio URL.

- (bool) bgMuted [read, write, assign]

Mutes BG music playback.

- (bool) bgPaused [read, write, assign]

Pauses BG music playback.

- (bool) bgPlaying [read, assign]

If true, BG music is currently playing.

- (float) bgVolume [read, write, assign]

Background music playback gain/volume (0.0 - 1.0)

- (ALChannelSource *) channel [read, assign]

The sound channel used by this object.

The channel source used by OALSimpleAudio.

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

- (bool) effectsMuted [read, write, assign]

Mutes effects playback.

- (bool) effectsPaused [read, write, assign]

Pauses effects playback.

- (float) effectsVolume [read, write, assign]

Master effects gain/volume (0.0 - 1.0)

- (bool) honorSilentSwitch [read, write, assign]

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

Default value: YES

- (bool) interrupted [read, assign]

If YES, the sound system is interrupted.

- (bool) manuallySuspended [read, write, assign]

Set to YES to manually suspend the sound system.

- (bool) muted [read, write, assign]

Mutes all audio.

- (bool) paused [read, write, assign]

Pauses everything.

- (NSUInteger) preloadCacheCount [read, assign]

The number of items currently in the preload cache.

- (bool) preloadCacheEnabled [read, write, assign]

Enables/disables the preload cache.

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

- (int) reservedSources [read, write, assign]

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

- (bool) suspended [read, assign]

If YES, the sound system is suspended.

- (bool) useHardwareIfAvailable [read, write, assign]

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.

See also:: allowIpod

Default value: YES

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

OALSimpleAudio.h
OALSimpleAudio.m

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Properties

Detailed Description

Member Function Documentation

Member Data Documentation

Property Documentation