OALAudioTrack Class Reference

Plays an audio track via AVAudioPlayer. More...

#include <OALAudioTrack.h>

Inheritance diagram for OALAudioTrack:

Collaboration diagram for OALAudioTrack:

List of all members.

Public Member Functions
bool	preloadUrl: (NSURL *url)
	Preload the contents of a URL for playback.
bool	preloadUrl:seekTime: (NSURL *url,[seekTime] NSTimeInterval seekTime)
	Preload the contents of a URL for playback.
bool	preloadFile: (NSString *path)
	Preload the contents of a file for playback.
bool	preloadFile:seekTime: (NSString *path,[seekTime] NSTimeInterval seekTime)
	Preload the contents of a file for playback.
bool	preloadUrlAsync:target:selector: (NSURL *url,[target] id target,[selector] SEL selector)
	Asynchronously preload the contents of a URL for playback.
bool	preloadUrlAsync:seekTime:target:selector: (NSURL *url,[seekTime] NSTimeInterval seekTime,[target] id target,[selector] SEL selector)
	Asynchronously preload the contents of a URL for playback.
bool	preloadFileAsync:target:selector: (NSString *path,[target] id target,[selector] SEL selector)
	Asynchronously preload the contents of a file for playback.
bool	preloadFileAsync:seekTime:target:selector: (NSString *path,[seekTime] NSTimeInterval seekTime,[target] id target,[selector] SEL selector)
	Asynchronously preload the contents of a file for playback.
bool	playUrl: (NSURL *url)
	Play the contents of a URL once.
bool	playUrl:loops: (NSURL *url,[loops] NSInteger loops)
	Play the contents of a URL and loop the specified number of times.
bool	playFile: (NSString *path)
	Play the contents of a file once.
bool	playFile:loops: (NSString *path,[loops] NSInteger loops)
	Play the contents of a file and loop the specified number of times.
void	playUrlAsync:target:selector: (NSURL *url,[target] id target,[selector] SEL selector)
	Play the contents of a URL asynchronously once.
void	playUrlAsync:loops:target:selector: (NSURL *url,[loops] NSInteger loops,[target] id target,[selector] SEL selector)
	Play the contents of a URL asynchronously and loop the specified number of times.
void	playFileAsync:target:selector: (NSString *path,[target] id target,[selector] SEL selector)
	Play the contents of a file asynchronously once.
void	playFileAsync:loops:target:selector: (NSString *path,[loops] NSInteger loops,[target] id target,[selector] SEL selector)
	Play the contents of a file asynchronously and loop the specified number of times.
bool	play ()
	Play the currently loaded audio track.
bool	playAtTime: (NSTimeInterval time)
	Plays a sound asynchronously, starting at a specified point in the audio output device’s timeline.
bool	playAfterTrack: (OALAudioTrack *track)
	Plays the currently preloaded track asynchronously when the specified track completes.
bool	playAfterTrack:timeAdjust: (OALAudioTrack *track,[timeAdjust] NSTimeInterval timeAdjust)
	Plays the currently preloaded track asynchronously when the specified track completes.
void	stop ()
	Stop playing and stop all operations.
void	fadeTo:duration:target:selector: (float gain,[duration] float duration,[target] id target,[selector] SEL selector)
	Fade to the specified gain value.
void	stopFade ()
	Stop the currently running fade operation, if any.
void	panTo:duration:target:selector: (float pan,[duration] float duration,[target] id target,[selector] SEL selector)
	Pan to the specified pan value.
void	stopPan ()
	Stop the currently running pan operation, if any.
void	stopActions ()
	Stop any internal fade or pan actions.
void	clear ()
	Unload and clear all audio data, stop playing, and stop all operations.
void	updateMeters ()
	Updates the metering system to give current values.
float	averagePowerForChannel: (NSUInteger channelNumber)
	Gives the average power for a given channel, in decibels, for the sound being played.
float	peakPowerForChannel: (NSUInteger channelNumber)
	Gives the peak power for a given channel, in decibels, for the sound being played.
Static Public Member Functions
id	track ()
	Create a new audio track.
Protected Attributes
bool	interrupted
	If YES, this object is interrupted.
AVAudioPlayer *	simulatorPlayerRef
	When the simulator is running (and the playback fix is in use), player will be copied to here, and then player set to nil.
NSOperationQueue *	operationQueue
	Operation queue for running asynchronous operations.
OALAction *	gainAction
	The current action being applied to gain.
OALAction *	panAction
	The current action being applied to pan.
OALSuspendHandler *	suspendHandler
	Handles suspending and interrupting for this object.
Properties
NSURL *	currentlyLoadedUrl
	The URL of the currently loaded audio data.
id< AVAudioPlayerDelegate >	delegate
	Optional object that will receive notifications for decoding errors, audio interruptions (such as an incoming phone call), and playback completion.
float	gain
	The gain (volume) for playback (0.0 - 1.0, where 1.0 = no attenuation).
float	volume
	The volume (alias to gain) for playback (0.0 - 1.0, where 1.0 = no attenuation).
float	pan
	Pan value (-1.0 = far left, 1.0 = far right).
bool	muted
	If true, audio track is muted.
bool	autoPreload
	If true, automatically preload again when playback stops.
bool	preloaded
	If true, audio track is in preloaded state.
NSInteger	numberOfLoops
	The number of times to loop playback (-1 = forever).
bool	paused
	If true, pause playback.
AVAudioPlayer *	player
	Access to the underlying AVAudioPlayer object.
bool	playing
	If true, the audio player is currently playing.
NSTimeInterval	currentTime
	The current playback position in seconds from the start of the sound.
NSTimeInterval	deviceCurrentTime
	The value of this property increases monotonically while an audio player is playing or paused.
NSTimeInterval	duration
	The duration, in seconds, of the currently loaded sound.
NSUInteger	numberOfChannels
	The number of channels in the currently loaded sound.
bool	meteringEnabled
	If true, this track is recording metering data.

---

Detailed Description

Plays an audio track via AVAudioPlayer.

Unlike AVAudioPlayer, however, it can be re-used to play another file. Interruptions can be handled by OALAudioSupport (enabled by default).

---

Member Function Documentation

float OALAudioTrack::averagePowerForChannel:

(

NSUInteger

channelNumber

)

[virtual]

Gives the average power for a given channel, in decibels, for the sound being played.

0 dB indicates maximum power (full scale).
-160 dB indicates minimum power (near silence).
If the signal provided to the audio player exceeds full scale, then the value may be > 0.

Note: The value returned is in reference to when updateMeters was last called. You must call updateMeters again before calling this method to get a current value.

Parameters:

channelNumber

The channel to get the value from. For mono or left, use 0. For right, use 1.

Returns:

the average power for the channel.

void OALAudioTrack::clear

(

)

[virtual]

Unload and clear all audio data, stop playing, and stop all operations.

void OALAudioTrack::fadeTo:duration:target:selector:	(	float	gain,
		[duration] float	duration,
		[target] id	target,
		[selector] SEL	selector
	)		[virtual]

Fade to the specified gain value.

Parameters:

gain	The gain to fade to.
duration	The duration of the fade operation in seconds.
target	The target to notify when the fade completes (can be nil).
selector	The selector to call when the fade completes. The selector must accept a single parameter, which will be the object that performed the fade.

void OALAudioTrack::panTo:duration:target:selector:	(	float	pan,
		[duration] float	duration,
		[target] id	target,
		[selector] SEL	selector
	)		[virtual]

Pan to the specified pan value.

Note: This will have no effect on iOS versions prior to 4.0.

Parameters:

pan	The value to pan to.
duration	The duration of the pan operation in seconds.
target	The target to notify when the pan completes (can be nil).
selector	The selector to call when the pan completes. The selector must accept a single parameter, which will be the object that performed the pan.

float OALAudioTrack::peakPowerForChannel:

(

NSUInteger

channelNumber

)

[virtual]

Gives the peak power for a given channel, in decibels, for the sound being played.

0 dB indicates maximum power (full scale).
-160 dB indicates minimum power (near silence).
If the signal provided to the audio player exceeds full scale, then the value may be > 0.

Note: The value returned is in reference to when updateMeters was last called. You must call updateMeters again before calling this method to get a current value.

Parameters:

channelNumber

The channel to get the value from. For mono or left, use 0. For right, use 1.

Returns:

the average power for the channel.

bool OALAudioTrack::play

(

)

[virtual]

Play the currently loaded audio track.

Returns:

TRUE if the operation was successful.

bool OALAudioTrack::playAfterTrack:

(

OALAudioTrack*

track

)

[virtual]

Plays the currently preloaded track asynchronously when the specified track completes.

Note: This will have no effect on iOS versions prior to 4.0.

Parameters:

track

The track to play after

Returns:

YES if the playback was successfully scheduled.

bool OALAudioTrack::playAfterTrack:timeAdjust:	(	OALAudioTrack*	track,
		[timeAdjust] NSTimeInterval	timeAdjust
	)		[virtual]

Plays the currently preloaded track asynchronously when the specified track completes.

Note: This will have no effect on iOS versions prior to 4.0.

Parameters:

track	The track to play after
timeAdjust	fine-tune value added to the time start offset.

Returns:

YES if the playback was successfully scheduled.

bool OALAudioTrack::playAtTime:

(

NSTimeInterval

time

)

[virtual]

Plays a sound asynchronously, starting at a specified point in the audio output device’s timeline.

Note: This will have no effect on iOS versions prior to 4.0.

Parameters:

time	The time (device time) to start playing at.

Returns:

YES if the playback was successfully scheduled.

bool OALAudioTrack::playFile:

(

NSString*

path

)

[virtual]

Play the contents of a file once.

Parameters:

path	The file containing the sound data.

Returns:

TRUE if the operation was successful.

bool OALAudioTrack::playFile:loops:	(	NSString*	path,
		[loops] NSInteger	loops
	)		[virtual]

Play the contents of a file and loop the specified number of times.

Parameters:

path	The file containing the sound data.
loops	The number of times to loop playback (-1 = forever)

Returns:

TRUE if the operation was successful.

void OALAudioTrack::playFileAsync:loops:target:selector:	(	NSString*	path,
		[loops] NSInteger	loops,
		[target] id	target,
		[selector] SEL	selector
	)		[virtual]

Play the contents of a file asynchronously and loop the specified number of times.

Parameters:

path	The file containing the sound data.
loops	The number of times to loop playback (-1 = forever)
target	the target to inform when playing has started.
selector	the selector to call when playing has started.

void OALAudioTrack::playFileAsync:target:selector:	(	NSString*	path,
		[target] id	target,
		[selector] SEL	selector
	)		[virtual]

Play the contents of a file asynchronously once.

Parameters:

path	The file containing the sound data.
target	the target to inform when playing has started.
selector	the selector to call when playing has started.

bool OALAudioTrack::playUrl:

(

NSURL*

url

)

[virtual]

Play the contents of a URL once.

Parameters:

url	The URL containing the sound data.

Returns:

TRUE if the operation was successful.

bool OALAudioTrack::playUrl:loops:	(	NSURL*	url,
		[loops] NSInteger	loops
	)		[virtual]

Play the contents of a URL and loop the specified number of times.

Parameters:

url	The URL containing the sound data.
loops	The number of times to loop playback (-1 = forever)

Returns:

TRUE if the operation was successful.

void OALAudioTrack::playUrlAsync:loops:target:selector:	(	NSURL*	url,
		[loops] NSInteger	loops,
		[target] id	target,
		[selector] SEL	selector
	)		[virtual]

Play the contents of a URL asynchronously and loop the specified number of times.

Parameters:

url	The URL containing the sound data.
loops	The number of times to loop playback (-1 = forever)
target	the target to inform when playing has started.
selector	the selector to call when playing has started.

void OALAudioTrack::playUrlAsync:target:selector:	(	NSURL*	url,
		[target] id	target,
		[selector] SEL	selector
	)		[virtual]

Play the contents of a URL asynchronously once.

Parameters:

url	The URL containing the sound data.
target	the target to inform when playing has started.
selector	the selector to call when playing has started.

bool OALAudioTrack::preloadFile:

(

NSString*

path

)

[virtual]

Preload the contents of a file for playback.

Once the audio data is preloaded, you can call "play" to play it.

Parameters:

path	The file containing the sound data.

Returns:

TRUE if the operation was successful.

bool OALAudioTrack::preloadFile:seekTime:	(	NSString*	path,
		[seekTime] NSTimeInterval	seekTime
	)		[virtual]

Preload the contents of a file for playback.

Once the audio data is preloaded, you can call "play" to play it.

Parameters:

path	The file containing the sound data.
seekTime	The position in the file to start playing at.

Returns:

TRUE if the operation was successful.

bool OALAudioTrack::preloadFileAsync:seekTime:target:selector:	(	NSString*	path,
		[seekTime] NSTimeInterval	seekTime,
		[target] id	target,
		[selector] SEL	selector
	)		[virtual]

Asynchronously preload the contents of a file for playback.

Once the audio data is preloaded, you can call "play" to play it.

Parameters:

path	The file containing the sound data.
seekTime	The position in the file to start playing at.
target	the target to inform when preparation is complete.
selector	the selector to call when preparation is complete.

Returns:

TRUE if the operation was successfully queued.

bool OALAudioTrack::preloadFileAsync:target:selector:	(	NSString*	path,
		[target] id	target,
		[selector] SEL	selector
	)		[virtual]

Asynchronously preload the contents of a file for playback.

Once the audio data is preloaded, you can call "play" to play it.

Parameters:

path	The file containing the sound data.
target	the target to inform when preparation is complete.
selector	the selector to call when preparation is complete.

Returns:

TRUE if the operation was successfully queued.

bool OALAudioTrack::preloadUrl:

(

NSURL*

url

)

[virtual]

Preload the contents of a URL for playback.

Once the audio data is preloaded, you can call "play" to play it.

Parameters:

url	The URL containing the sound data.

Returns:

TRUE if the operation was successful.

bool OALAudioTrack::preloadUrl:seekTime:	(	NSURL*	url,
		[seekTime] NSTimeInterval	seekTime
	)		[virtual]

Preload the contents of a URL for playback.

Once the audio data is preloaded, you can call "play" to play it.

Parameters:

url	The URL containing the sound data.
seekTime	The position in the file to start playing at.

Returns:

TRUE if the operation was successful.

bool OALAudioTrack::preloadUrlAsync:seekTime:target:selector:	(	NSURL*	url,
		[seekTime] NSTimeInterval	seekTime,
		[target] id	target,
		[selector] SEL	selector
	)		[virtual]

Asynchronously preload the contents of a URL for playback.

Once the audio data is preloaded, you can call "play" to play it.

Parameters:

url	The URL containing the sound data.
seekTime	The position in the file to start playing at.
target	the target to inform when preparation is complete.
selector	the selector to call when preparation is complete.

Returns:

TRUE if the operation was successfully queued.

bool OALAudioTrack::preloadUrlAsync:target:selector:	(	NSURL*	url,
		[target] id	target,
		[selector] SEL	selector
	)		[virtual]

Asynchronously preload the contents of a URL for playback.

Once the audio data is preloaded, you can call "play" to play it.

Parameters:

url	The URL containing the sound data.
target	the target to inform when preparation is complete.
selector	the selector to call when preparation is complete.

Returns:

TRUE if the operation was successfully queued.

void OALAudioTrack::stop

(

)

[virtual]

Stop playing and stop all operations.

void OALAudioTrack::stopActions

(

)

[virtual]

Stop any internal fade or pan actions.

void OALAudioTrack::stopFade

(

)

[virtual]

Stop the currently running fade operation, if any.

void OALAudioTrack::stopPan

(

)

[virtual]

Stop the currently running pan operation, if any.

Note: This will have no effect on iOS versions prior to 4.0.

id OALAudioTrack::track

(

)

[static, virtual]

Create a new audio track.

Returns:

A new audio track.

void OALAudioTrack::updateMeters

(

)

[virtual]

Updates the metering system to give current values.

You must call this method before calling averagePowerForChannel or peakPowerForChannel in order to get current values.

---

Member Data Documentation

OALAction* OALAudioTrack::gainAction [protected]

The current action being applied to gain.

bool OALAudioTrack::interrupted [protected]

If YES, this object is interrupted.

Note: This property must NOT be set by the user!

Reimplemented from <OALSuspendListener>.

NSOperationQueue* OALAudioTrack::operationQueue [protected]

Operation queue for running asynchronous operations.

Note: Only one asynchronous operation is allowed at a time.

OALAction* OALAudioTrack::panAction [protected]

The current action being applied to pan.

AVAudioPlayer* OALAudioTrack::simulatorPlayerRef [protected]

When the simulator is running (and the playback fix is in use), player will be copied to here, and then player set to nil.

This prevents other code from inadvertently raising the volume and starting playback.

OALSuspendHandler* OALAudioTrack::suspendHandler [protected]

Handles suspending and interrupting for this object.

---

Property Documentation

bool OALAudioTrack::autoPreload [read, write, assign]

If true, automatically preload again when playback stops.

NSURL * OALAudioTrack::currentlyLoadedUrl [read, assign]

The URL of the currently loaded audio data.

NSTimeInterval OALAudioTrack::currentTime [read, write, assign]

The current playback position in seconds from the start of the sound.

You can set this to change the playback position, whether it is currently playing or not.

id< AVAudioPlayerDelegate > OALAudioTrack::delegate [read, write, assign]

Optional object that will receive notifications for decoding errors, audio interruptions (such as an incoming phone call), and playback completion.

Note: OALAudioTrack keeps a WEAK reference to delegate, so make sure you clear it when your object is going to be deallocated.

NSTimeInterval OALAudioTrack::deviceCurrentTime [read, assign]

The value of this property increases monotonically while an audio player is playing or paused.

If more than one audio player is connected to the audio output device, device time continues incrementing as long as at least one of the players is playing or paused.

If the audio output device has no connected audio players that are either playing or paused, device time reverts to 0.

Use this property to indicate “now” when calling the playAtTime: instance method. By configuring multiple audio players to play at a specified offset from deviceCurrentTime, you can perform precise synchronization—as described in the discussion for that method.

Note: This will have no effect on iOS versions prior to 4.0.

NSTimeInterval OALAudioTrack::duration [read, assign]

The duration, in seconds, of the currently loaded sound.

float OALAudioTrack::gain [read, write, assign]

The gain (volume) for playback (0.0 - 1.0, where 1.0 = no attenuation).

bool OALAudioTrack::meteringEnabled [read, write, assign]

If true, this track is recording metering data.

If true, metering is enabled.

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

If true, audio track is muted.

NSUInteger OALAudioTrack::numberOfChannels [read, assign]

The number of channels in the currently loaded sound.

NSInteger OALAudioTrack::numberOfLoops [read, write, assign]

The number of times to loop playback (-1 = forever).

Note: This value will be ignored, and get changed when you call the various playXX methods. Only "play" will use the current value of "numberOfLoops".

float OALAudioTrack::pan [read, write, assign]

Pan value (-1.0 = far left, 1.0 = far right).

Note: This will have no effect on iOS versions prior to 4.0.

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

If true, pause playback.

AVAudioPlayer * OALAudioTrack::player [read, assign]

Access to the underlying AVAudioPlayer object.

WARNING: Be VERY careful when accessing this, as some methods could cause it to fall out of sync with OALAudioTrack (particularly play/pause/stop methods).

bool OALAudioTrack::playing [read, assign]

If true, the audio player is currently playing.

If true, background music is currently playing.

We need to maintain our own value because AVAudioPlayer will sometimes say it's not playing when it actually is.

bool OALAudioTrack::preloaded [read, assign]

If true, audio track is in preloaded state.

float OALAudioTrack::volume [read, write, assign]

The volume (alias to gain) for playback (0.0 - 1.0, where 1.0 = no attenuation).

---

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

• OALAudioTrack.h
• OALAudioTrack.m