OALSimpleAudio Class Reference

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

#include <OALSimpleAudio.h>

Collaboration diagram for OALSimpleAudio:

List of all members.

Public Member Functions
id	initWithSources: (int reservedSources)
	(INTERNAL USE) Initialize with the specified number of reserved sources.
id	initWithReservedSources:monoSources:stereoSources: (int reservedSources,[monoSources] int monoSources,[stereoSources] int stereoSources)
	(INTERNAL USE) Initialize with the specified parameters.
bool	preloadBg: (NSString *path)
	Preload background music.
bool	preloadBg:seekTime: (NSString *path,[seekTime] NSTimeInterval seekTime)
	Preload background music.
bool	playBg ()
	Play whatever background music is preloaded.
bool	playBgWithLoop: (bool loop)
	Play whatever background music is preloaded.
bool	playBg: (NSString *path)
	Play the background music at the specified path.
bool	playBg:loop: (NSString *path,[loop] bool loop)
	Play the background music at the specified path.
bool	playBg:volume:pan:loop: (NSString *filePath,[volume] float volume,[pan] float pan,[loop] bool loop)
	Play the background music at the specified path.
void	stopBg ()
	Stop the background music playback and rewind.
ALBuffer *	preloadEffect: (NSString *filePath)
	Preload and cache a sound effect for later playback.
ALBuffer *	preloadEffect:reduceToMono: (NSString *filePath,[reduceToMono] bool reduceToMono)
	Preload and cache a sound effect for later playback.
BOOL	preloadEffect:reduceToMono:completionBlock: (NSString *filePath,[reduceToMono] bool reduceToMono,[completionBlock] ALBuffer *completionBlock)
	Asynchronous preload and cache sound effect for later playback.
void	preloadEffects:reduceToMono:progressBlock: (NSArray *filePaths,[reduceToMono] bool reduceToMono,[progressBlock] uint progress, uint successCount, uint total progressBlock)
	Asynchronous preload and cache multiple sound effects for later playback.
void	unloadEffect: (NSString *filePath)
	Unload a preloaded effect.
void	unloadAllEffects ()
	Unload all preloaded effects.
id< ALSoundSource >	playEffect: (NSString *filePath)
	Play a sound effect with volume 1.0, pitch 1.0, pan 0.0, loop NO.
id< ALSoundSource >	playEffect:loop: (NSString *filePath,[loop] bool loop)
	Play a sound effect with volume 1.0, pitch 1.0, pan 0.0.
id< ALSoundSource >	playEffect:volume:pitch:pan:loop: (NSString *filePath,[volume] float volume,[pitch] float pitch,[pan] float pan,[loop] bool loop)
	Play a sound effect.
id< ALSoundSource >	playBuffer:volume:pitch:pan:loop: (ALBuffer *buffer,[volume] float volume,[pitch] float pitch,[pan] float pan,[loop] bool 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: (int sources)
	Start OALSimpleAudio with the specified number of reserved sources.
OALSimpleAudio *	sharedInstanceWithReservedSources:monoSources:stereoSources: (int reservedSources,[monoSources] int monoSources,[stereoSources] int stereoSources)
	Start OALSimpleAudio with the specified parameters.
Protected Member Functions
	SYNTHESIZE_SINGLETON_FOR_CLASS_HEADER (OALSimpleAudio)
	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 OALSimpleAudio::initWithReservedSources:monoSources:stereoSources:	(	int	reservedSources,
		[monoSources] int	monoSources,
		[stereoSources] int	stereoSources
	)		[virtual]

(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 OALSimpleAudio::initWithSources:

(

int

reservedSources

)

[virtual]

(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 OALSimpleAudio::playBg

(

)

[virtual]

Play whatever background music is preloaded.

Returns:

TRUE if the operation was successful.

bool OALSimpleAudio::playBg:

(

NSString*

path

)

[virtual]

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 OALSimpleAudio::playBg:loop:	(	NSString*	path,
		[loop] bool	loop
	)		[virtual]

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 OALSimpleAudio::playBg:volume:pan:loop:	(	NSString*	filePath,
		[volume] float	volume,
		[pan] float	pan,
		[loop] bool	loop
	)		[virtual]

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 OALSimpleAudio::playBgWithLoop:

(

bool

loop

)

[virtual]

Play whatever background music is preloaded.

Parameters:

loop	If true, loop the bg track.

Returns:

TRUE if the operation was successful.

id< ALSoundSource > OALSimpleAudio::playBuffer:volume:pitch:pan:loop:	(	ALBuffer*	buffer,
		[volume] float	volume,
		[pitch] float	pitch,
		[pan] float	pan,
		[loop] bool	loop
	)		[virtual]

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 > OALSimpleAudio::playEffect:

(

NSString*

filePath

)

[virtual]

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 > OALSimpleAudio::playEffect:loop:	(	NSString*	filePath,
		[loop] bool	loop
	)		[virtual]

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 > OALSimpleAudio::playEffect:volume:pitch:pan:loop:	(	NSString*	filePath,
		[volume] float	volume,
		[pitch] float	pitch,
		[pan] float	pan,
		[loop] bool	loop
	)		[virtual]

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 OALSimpleAudio::preloadBg:

(

NSString*

path

)

[virtual]

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 OALSimpleAudio::preloadBg:seekTime:	(	NSString*	path,
		[seekTime] NSTimeInterval	seekTime
	)		[virtual]

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 * OALSimpleAudio::preloadEffect:

(

NSString*

filePath

)

[virtual]

Preload and cache a sound effect for later playback.

Parameters:

filePath

The path containing the sound data.

ALBuffer * OALSimpleAudio::preloadEffect:reduceToMono:	(	NSString*	filePath,
		[reduceToMono] bool	reduceToMono
	)		[virtual]

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 OALSimpleAudio::preloadEffect:reduceToMono:completionBlock:	(	NSString*	filePath,
		[reduceToMono] bool	reduceToMono,
		[completionBlock] ALBuffer *	completionBlock
	)		[virtual]

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 OALSimpleAudio::preloadEffects:reduceToMono:progressBlock:	(	NSArray*	filePaths,
		[reduceToMono] bool	reduceToMono,
		[progressBlock] uint progress, uint successCount, uint total	progressBlock
	)		[virtual]

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 OALSimpleAudio::resetToDefault

(

)

[virtual]

Reset everything in this object to its default state.

OALSimpleAudio * OALSimpleAudio::sharedInstanceWithReservedSources:monoSources:stereoSources:	(	int	reservedSources,
		[monoSources] int	monoSources,
		[stereoSources] int	stereoSources
	)		[static, virtual]

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 * OALSimpleAudio::sharedInstanceWithSources:

(

int

sources

)

[static, virtual]

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 OALSimpleAudio::stopAllEffects

(

)

[virtual]

Stop ALL sound effect playback.

void OALSimpleAudio::stopBg

(

)

[virtual]

Stop the background music playback and rewind.

void OALSimpleAudio::stopEverything

(

)

[virtual]

Stop all effects and bg music.

OALSimpleAudio::SYNTHESIZE_SINGLETON_FOR_CLASS_HEADER

(

OALSimpleAudio

)

[protected]

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

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

void OALSimpleAudio::unloadAllEffects

(

)

[virtual]

Unload all preloaded effects.

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

void OALSimpleAudio::unloadEffect:

(

NSString*

filePath

)

[virtual]

Unload a preloaded effect.

Parameters:

filePath

The path containing the sound data that was previously loaded.

---

Member Data Documentation

ALContext* OALSimpleAudio::context [protected]

The context we are using.

ALDevice* OALSimpleAudio::device [protected]

The device we are using.

dispatch_queue_t OALSimpleAudio::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 OALSimpleAudio::pendingLoadCount [protected]

keeping track of how many effects remain to be loaded

NSMutableDictionary* OALSimpleAudio::preloadCache [protected]

Cache for preloaded sound samples.

---

Property Documentation

bool OALSimpleAudio::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 * OALSimpleAudio::backgroundTrack [read, assign]

Audio track to play background music.

Background audio track.

NSURL * OALSimpleAudio::backgroundTrackURL [read, assign]

Background audio URL.

bool OALSimpleAudio::bgMuted [read, write, assign]

Mutes BG music playback.

bool OALSimpleAudio::bgPaused [read, write, assign]

Pauses BG music playback.

bool OALSimpleAudio::bgPlaying [read, assign]

If true, BG music is currently playing.

float OALSimpleAudio::bgVolume [read, write, assign]

Background music playback gain/volume (0.0 - 1.0)

ALChannelSource * OALSimpleAudio::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 OALSimpleAudio::effectsMuted [read, write, assign]

Mutes effects playback.

bool OALSimpleAudio::effectsPaused [read, write, assign]

Pauses effects playback.

float OALSimpleAudio::effectsVolume [read, write, assign]

Master effects gain/volume (0.0 - 1.0)

bool OALSimpleAudio::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 OALSimpleAudio::interrupted [read, assign]

If YES, the sound system is interrupted.

bool OALSimpleAudio::manuallySuspended [read, write, assign]

Set to YES to manually suspend the sound system.

bool OALSimpleAudio::muted [read, write, assign]

Mutes all audio.

bool OALSimpleAudio::paused [read, write, assign]

Pauses everything.

NSUInteger OALSimpleAudio::preloadCacheCount [read, assign]

The number of items currently in the preload cache.

bool OALSimpleAudio::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 OALSimpleAudio::reservedSources [read, write, assign]

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

bool OALSimpleAudio::suspended [read, assign]

If YES, the sound system is suspended.

bool OALSimpleAudio::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