OALSimpleAudio Class Reference

Inherits from NSObject
Declared in OALSimpleAudio.h

Overview

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

  allowIpod

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.

@property (nonatomic, readwrite, assign) bool allowIpod

Discussion

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

iOS Only.

See Also

Declared In

OALSimpleAudio.h

  useHardwareIfAvailable

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

@property (nonatomic, readwrite, assign) bool useHardwareIfAvailable

Discussion

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

Declared In

OALSimpleAudio.h

  honorSilentSwitch

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

@property (nonatomic, readwrite, assign) bool honorSilentSwitch

Discussion

iOS Only.

Default value: YES

Declared In

OALSimpleAudio.h

  reservedSources

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

@property (nonatomic, readwrite, assign) int reservedSources

Declared In

OALSimpleAudio.h

  channel

The channel source used by OALSimpleAudio. Only mess with this if you know what you are doing!

@property (nonatomic, readonly, retain) ALChannelSource *channel

Declared In

OALSimpleAudio.h

  backgroundTrackURL

Background audio URL

@property (nonatomic, readonly, retain) NSURL *backgroundTrackURL

Declared In

OALSimpleAudio.h

  backgroundTrack

Background audio track

@property (nonatomic, readonly, retain) OALAudioTrack *backgroundTrack

Declared In

OALSimpleAudio.h

  bgPaused

Pauses BG music playback

@property (nonatomic, readwrite, assign) bool bgPaused

Declared In

OALSimpleAudio.h

  bgMuted

Mutes BG music playback

@property (nonatomic, readwrite, assign) bool bgMuted

Declared In

OALSimpleAudio.h

  bgPlaying

If true, BG music is currently playing

@property (nonatomic, readonly, assign) bool bgPlaying

Declared In

OALSimpleAudio.h

  bgVolume

Background music playback gain/volume (0.0 - 1.0)

@property (nonatomic, readwrite, assign) float bgVolume

Declared In

OALSimpleAudio.h

  effectsPaused

Pauses effects playback

@property (nonatomic, readwrite, assign) bool effectsPaused

Declared In

OALSimpleAudio.h

  effectsMuted

Mutes effects playback

@property (nonatomic, readwrite, assign) bool effectsMuted

Declared In

OALSimpleAudio.h

  effectsVolume

Master effects gain/volume (0.0 - 1.0)

@property (nonatomic, readwrite, assign) float effectsVolume

Declared In

OALSimpleAudio.h

  paused

Pauses everything

@property (nonatomic, readwrite, assign) bool paused

Declared In

OALSimpleAudio.h

  muted

Mutes all audio

@property (nonatomic, readwrite, assign) bool muted

Declared In

OALSimpleAudio.h

  preloadCacheEnabled

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

@property (nonatomic, readwrite, assign) bool preloadCacheEnabled

Declared In

OALSimpleAudio.h

  preloadCacheCount

The number of items currently in the preload cache.

@property (nonatomic, readonly, assign) NSUInteger preloadCacheCount

Declared In

OALSimpleAudio.h

  manuallySuspended

Set to YES to manually suspend the sound system.

@property (nonatomic, readwrite, assign) bool manuallySuspended

Declared In

OALSimpleAudio.h

  interrupted

If YES, the sound system is interrupted. iOS Only.

@property (nonatomic, readonly, assign) bool interrupted

Declared In

OALSimpleAudio.h

  suspended

If YES, the sound system is suspended.

@property (nonatomic, readonly, assign) bool suspended

Declared In

OALSimpleAudio.h

+ sharedInstanceWithSources:

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.

+ (OALSimpleAudio *)sharedInstanceWithSources:(int)sources

Parameters

sources

the number of sources OALSimpleAudio will reserve for itself.

Return Value

The shared instance.

Declared In

OALSimpleAudio.h

+ sharedInstanceWithReservedSources:monoSources:stereoSources:

Start OALSimpleAudio with the specified parameters.

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

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

Return Value

The shared instance.

Discussion

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.

Declared In

OALSimpleAudio.h

– initWithSources:

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

- (id)initWithSources:(int)reservedSources

Parameters

reservedSources

the number of sources to reserve when initializing.

Return Value

The shared instance.

Declared In

OALSimpleAudio.h

– initWithReservedSources:monoSources:stereoSources:

(INTERNAL USE) Initialize with the specified parameters.

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

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

Return Value

The shared instance.

Declared In

OALSimpleAudio.h

– preloadBg:

Preload background music.

- (bool)preloadBg:(NSString *)path

Parameters

path

The path containing the background music.

Return Value

TRUE if the operation was successful.

Discussion

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.

Declared In

OALSimpleAudio.h

– preloadBg:seekTime:

Preload background music.

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

Parameters

path

The path containing the background music.
seekTime

the position in the file to start playing at.

Return Value

TRUE if the operation was successful.

Discussion

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.

Declared In

OALSimpleAudio.h

– playBg

Play whatever background music is preloaded.

- (bool)playBg

Return Value

TRUE if the operation was successful.

Declared In

OALSimpleAudio.h

– playBgWithLoop:

Play whatever background music is preloaded.

- (bool)playBgWithLoop:(bool)loop

Parameters

loop

If true, loop the bg track.

Return Value

TRUE if the operation was successful.

Declared In

OALSimpleAudio.h

– playBg:

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.

- (bool)playBg:(NSString *)path

Parameters

path

The path containing the background music.

Return Value

TRUE if the operation was successful.

Discussion

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.

Declared In

OALSimpleAudio.h

– playBg: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.

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

Parameters

path

The path containing the background music.
loop

If true, loop the bg track.

Return Value

TRUE if the operation was successful.

Discussion

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.

Declared In

OALSimpleAudio.h

– playBg:volume:pan: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.

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

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

Return Value

TRUE if the operation was successful.

Discussion

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.

Declared In

OALSimpleAudio.h

– stopBg

Stop the background music playback and rewind.

- (void)stopBg

Declared In

OALSimpleAudio.h

– preloadEffect:

Preload and cache a sound effect for later playback.

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

Parameters

filePath

The path containing the sound data.

Declared In

OALSimpleAudio.h

– preloadEffect:reduceToMono:

Preload and cache a sound effect for later playback.

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

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

Declared In

OALSimpleAudio.h

– preloadEffect:reduceToMono:completionBlock:

Asynchronous preload and cache sound effect for later playback.

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

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.

Declared In

OALSimpleAudio.h

– preloadEffects:reduceToMono:progressBlock:

Asynchronous preload and cache multiple sound effects for later playback.

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

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.

Declared In

OALSimpleAudio.h

– unloadEffect:

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

- (bool)unloadEffect:(NSString *)filePath

Parameters

filePath

The path containing the sound data that was previously loaded.

Return Value

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

Declared In

OALSimpleAudio.h

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

- (void)unloadAllEffects

Declared In

OALSimpleAudio.h

– playEffect:

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.

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

Parameters

filePath

The path containing the sound data.

Return Value

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

Declared In

OALSimpleAudio.h

– playEffect: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.

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

Parameters

filePath

The path containing the sound data.
loop

If TRUE, the sound will loop until you call “stop” on the returned sound source.

Return Value

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

Declared In

OALSimpleAudio.h

– playEffect:volume:pitch:pan:loop:

Play a sound effect. The sound will be loaded and cached if it wasn’t already.

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

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.

Return Value

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

Declared In

OALSimpleAudio.h

– playBuffer:volume:pitch:pan:loop:

Play a sound effect from a user-supplied buffer.

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

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.

Return Value

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

Declared In

OALSimpleAudio.h

– stopAllEffects

Stop ALL sound effect playback.

- (void)stopAllEffects

Declared In

OALSimpleAudio.h

– stopEverything

Stop all effects and bg music.

- (void)stopEverything

Declared In

OALSimpleAudio.h

– resetToDefault

Reset everything in this object to its default state.

- (void)resetToDefault

Declared In

OALSimpleAudio.h