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).
Tasks
-
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 -
useHardwareIfAvailable
Determines what to do if no other application is playing audio and allowIpod = YES (NOT SUPPORTED ON THE SIMULATOR).
property -
honorSilentSwitch
If true, mute when backgrounded, screen locked, or the ringer switch is turned off (NOT SUPPORTED ON THE SIMULATOR).
property -
reservedSources
The number of sources OALSimpleAudio is using (max 32 on current iOS devices).
property -
channel
The channel source used by OALSimpleAudio. Only mess with this if you know what you are doing!
property -
backgroundTrackURL
Background audio URL
property -
backgroundTrack
Background audio track
property -
bgPaused
Pauses BG music playback
property -
bgMuted
Mutes BG music playback
property -
bgPlaying
If true, BG music is currently playing
property -
bgVolume
Background music playback gain/volume (0.0 – 1.0)
property -
effectsPaused
Pauses effects playback
property -
effectsMuted
Mutes effects playback
property -
effectsVolume
Master effects gain/volume (0.0 – 1.0)
property -
paused
Pauses everything
property -
muted
Mutes all audio
property -
preloadCacheEnabled
Enables/disables the preload cache. If the preload cache is disabled, effects preloading will do nothing (BG preloading will still work).
property -
preloadCacheCount
The number of items currently in the preload cache.
property -
manuallySuspended
Set to YES to manually suspend the sound system.
property -
interrupted
If YES, the sound system is interrupted.
property -
suspended
If YES, the sound system is suspended.
property -
+ 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. -
+ sharedInstanceWithReservedSources:monoSources:stereoSources:
Start OALSimpleAudio with the specified parameters.
-
– initWithSources:
(INTERNAL USE) Initialize with the specified number of reserved sources.
-
– initWithReservedSources:monoSources:stereoSources:
(INTERNAL USE) Initialize with the specified parameters.
-
– preloadBg:
Preload background music.
-
– preloadBg:seekTime:
Preload background music.
-
– playBg
Play whatever background music is preloaded.
-
– playBgWithLoop:
Play whatever background music is preloaded.
-
– 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.
-
– 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.
-
– 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.
-
– stopBg
Stop the background music playback and rewind.
-
– preloadEffect:
Preload and cache a sound effect for later playback.
-
– preloadEffect:reduceToMono:
Preload and cache a sound effect for later playback.
-
– preloadEffect:reduceToMono:completionBlock:
Asynchronous preload and cache sound effect for later playback.
-
– preloadEffects:reduceToMono:progressBlock:
Asynchronous preload and cache multiple sound effects for later playback.
-
– unloadEffect:
Unload a preloaded effect.
-
– unloadAllEffects
Unload all preloaded effects. It is useful to put a call to this method in “applicationDidReceiveMemoryWarning” in your app delegate.
-
– 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.
-
– 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.
-
– playEffect:volume:pitch:pan:loop:
Play a sound effect. The sound will be loaded and cached if it wasn’t already.
-
– playBuffer:volume:pitch:pan:loop:
Play a sound effect from a user-supplied buffer.
-
– stopAllEffects
Stop ALL sound effect playback.
-
– stopEverything
Stop all effects and bg music.
-
– resetToDefault
Reset everything in this object to its default state.
Properties
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 (readwrite, assign) bool allowIpod
Discussion
If allowIpod = NO, the application will ALWAYS use hardware decoding.
See Also
@property useHardwareIfAvailable
Default value: YES
Declared In
OALSimpleAudio.h
backgroundTrack
Background audio track
@property (nonatomic, readonly) OALAudioTrack *backgroundTrack
Declared In
OALSimpleAudio.h
backgroundTrackURL
Background audio URL
@property (nonatomic, readonly) NSURL *backgroundTrackURL
Declared In
OALSimpleAudio.h
bgMuted
Mutes BG music playback
@property (readwrite, assign) bool bgMuted
Declared In
OALSimpleAudio.h
bgPaused
Pauses BG music playback
@property (readwrite, assign) bool bgPaused
Declared In
OALSimpleAudio.h
bgPlaying
If true, BG music is currently playing
@property (nonatomic, readonly) bool bgPlaying
Declared In
OALSimpleAudio.h
bgVolume
Background music playback gain/volume (0.0 – 1.0)
@property (readwrite, assign) float bgVolume
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) ALChannelSource *channel
Declared In
OALSimpleAudio.h
effectsMuted
Mutes effects playback
@property (readwrite, assign) bool effectsMuted
Declared In
OALSimpleAudio.h
effectsPaused
Pauses effects playback
@property (readwrite, assign) bool effectsPaused
Declared In
OALSimpleAudio.h
effectsVolume
Master effects gain/volume (0.0 – 1.0)
@property (readwrite, assign) float effectsVolume
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 (readwrite, assign) bool honorSilentSwitch
Discussion
Default value: YES
Declared In
OALSimpleAudio.h
interrupted
If YES, the sound system is interrupted.
@property (nonatomic, readonly) bool interrupted
Declared In
OALSimpleAudio.h
manuallySuspended
Set to YES to manually suspend the sound system.
@property (readwrite, assign) bool manuallySuspended
Declared In
OALSimpleAudio.h
preloadCacheCount
The number of items currently in the preload cache.
@property (nonatomic, readonly) NSUInteger preloadCacheCount
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 (readwrite, assign) bool preloadCacheEnabled
Declared In
OALSimpleAudio.h
reservedSources
The number of sources OALSimpleAudio is using (max 32 on current iOS devices).
@property (readwrite, assign) int reservedSources
Declared In
OALSimpleAudio.h
suspended
If YES, the sound system is suspended.
@property (nonatomic, readonly) bool suspended
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 (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.
See Also
Default value: YES
Declared In
OALSimpleAudio.h
Class Methods
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
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
Instance Methods
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
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
playBg
Play whatever background music is preloaded.
- (bool)playBg
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
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
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
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
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
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 ( ^ ) ( uint progress , uint successCount , uint 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
resetToDefault
Reset everything in this object to its default state.
- (void)resetToDefault
Declared In
OALSimpleAudio.h