Inherits from NSObject
Conforms to AVAudioPlayerDelegate
OALSuspendManager
Declared in OALAudioTrack.h

Overview

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

Tasks

  •   currentlyLoadedUrl

    The URL of the currently loaded audio data.

         property
  •   delegate

    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.

         property
  •   gain

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

         property
  •   volume

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

         property
  •   pan

    Pan value (-1.0 = far left, 1.0 = far right). Note: This will have no effect on iOS versions prior to 4.0.

         property
  •   muted

    If true, audio track is muted

         property
  •   autoPreload

    If true, automatically preload again when playback stops

         property
  •   preloaded

    If true, audio track is in preloaded state

         property
  •   numberOfLoops

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

         property
  •   paused

    If true, pause playback.

         property
  •   player

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

         property
  •   playing

    If true, background music is currently playing.

         property
  •   currentTime

    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.

         property
  •   deviceCurrentTime

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

    property
  •   duration

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

         property
  •   numberOfChannels

    The number of channels in the currently loaded sound.

         property
  • + track

    Create a new audio track.
  • – preloadUrl:

    Preload the contents of a URL for playback. Once the audio data is preloaded, you can call “play” to play it.

  • – preloadUrl:seekTime:

    Preload the contents of a URL for playback. Once the audio data is preloaded, you can call “play” to play it.

  • – preloadFile:

    Preload the contents of a file for playback. Once the audio data is preloaded, you can call “play” to play it.

  • – preloadFile:seekTime:

    Preload the contents of a file for playback. Once the audio data is preloaded, you can call “play” to play it.

  • – preloadUrlAsync:target:selector:

    Asynchronously preload the contents of a URL for playback. Once the audio data is preloaded, you can call “play” to play it.

  • – preloadUrlAsync:seekTime:target:selector:

    Asynchronously preload the contents of a URL for playback. Once the audio data is preloaded, you can call “play” to play it.

  • – preloadFileAsync:target:selector:

    Asynchronously preload the contents of a file for playback. Once the audio data is preloaded, you can call “play” to play it.

  • – preloadFileAsync:seekTime:target:selector:

    Asynchronously preload the contents of a file for playback. Once the audio data is preloaded, you can call “play” to play it.

  • – playUrl:

    Play the contents of a URL once.
  • – playUrl:loops:

    Play the contents of a URL and loop the specified number of times.
  • – playFile:

    Play the contents of a file once.
  • – playFile:loops:

    Play the contents of a file and loop the specified number of times.
  • – playUrlAsync:target:selector:

    Play the contents of a URL asynchronously once.
  • – playUrlAsync:loops:target:selector:

    Play the contents of a URL asynchronously and loop the specified number of times.
  • – playFileAsync:target:selector:

    Play the contents of a file asynchronously once.
  • – playFileAsync:loops:target:selector:

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

    Play the currently loaded audio track.
  • – playAtTime:

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

    Plays the currently preloaded track asynchronously when the specified track completes.
  • – playAfterTrack:timeAdjust:

    Plays the currently preloaded track asynchronously when the specified track completes.
  • – stop

    Stop playing and stop all operations.
  • – fadeTo:duration:target:selector:

    Fade to the specified gain value.
  • – stopFade

    Stop the currently running fade operation, if any.
  • – panTo:duration:target:selector:

    Pan to the specified pan value.
  • – stopPan

    Stop the currently running pan operation, if any.
  • – stopActions

    Stop any internal fade or pan actions.
  • – clear

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

    If true, metering is enabled.

         property
  • – updateMeters

    Updates the metering system to give current values. You must call this method before calling averagePowerForChannel or peakPowerForChannel in order to get current values.
  • – averagePowerForChannel:

    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.

  • – peakPowerForChannel:

    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.

Properties

autoPreload

If true, automatically preload again when playback stops

@property (nonatomic, readwrite, assign) bool autoPreload

Declared In

OALAudioTrack.h

currentTime

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.

@property (readwrite, assign) NSTimeInterval currentTime

Declared In

OALAudioTrack.h

currentlyLoadedUrl

The URL of the currently loaded audio data.

@property (nonatomic, readonly) NSURL *currentlyLoadedUrl

Declared In

OALAudioTrack.h

delegate

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.

@property (readwrite, assign) id<AVAudioPlayerDelegate> delegate

Declared In

OALAudioTrack.h

deviceCurrentTime

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

@property (readonly) NSTimeInterval deviceCurrentTime

Discussion

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.

Declared In

OALAudioTrack.h

duration

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

@property (readonly) NSTimeInterval duration

Declared In

OALAudioTrack.h

gain

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

@property (readwrite, assign) float gain

Declared In

OALAudioTrack.h

meteringEnabled

If true, metering is enabled.

@property (readwrite, assign) bool meteringEnabled

Declared In

OALAudioTrack.h

muted

If true, audio track is muted

@property (readwrite, assign) bool muted

Declared In

OALAudioTrack.h

numberOfChannels

The number of channels in the currently loaded sound.

@property (readonly) NSUInteger numberOfChannels

Declared In

OALAudioTrack.h

numberOfLoops

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

@property (readwrite, assign) NSInteger numberOfLoops

Declared In

OALAudioTrack.h

pan

Pan value (-1.0 = far left, 1.0 = far right). Note: This will have no effect on iOS versions prior to 4.0.

@property (readwrite, assign) float pan

Declared In

OALAudioTrack.h

paused

If true, pause playback.

@property (readwrite, assign) bool paused

Declared In

OALAudioTrack.h

player

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

@property (nonatomic, readonly) AVAudioPlayer *player

Declared In

OALAudioTrack.h

playing

If true, background music is currently playing.

@property (nonatomic, readonly) bool playing

Declared In

OALAudioTrack.h

preloaded

If true, audio track is in preloaded state

@property (nonatomic, readonly) bool preloaded

Declared In

OALAudioTrack.h

volume

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

@property (readwrite, assign) float volume

Declared In

OALAudioTrack.h

Class Methods

track

Create a new audio track.

+ (id)track

Return Value

A new audio track.

Declared In

OALAudioTrack.h

Instance Methods

averagePowerForChannel:

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.

- (float)averagePowerForChannel:(NSUInteger)channelNumber

Parameters

channelNumber

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

Return Value

the average power for the channel.

Discussion

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.

Declared In

OALAudioTrack.h

clear

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

- (void)clear

Declared In

OALAudioTrack.h

fadeTo:duration:target:selector:

Fade to the specified gain value.

- (void)fadeTo:(float)gain duration:(float)duration target:(id)target selector:(SEL)selector

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.

Declared In

OALAudioTrack.h

panTo:duration:target:selector:

Pan to the specified pan value.

- (void)panTo:(float)pan duration:(float)duration target:(id)target selector:(SEL)selector

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.

Discussion

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

Declared In

OALAudioTrack.h

peakPowerForChannel:

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.

- (float)peakPowerForChannel:(NSUInteger)channelNumber

Parameters

channelNumber

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

Return Value

the average power for the channel.

Discussion

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.

Declared In

OALAudioTrack.h

play

Play the currently loaded audio track.

- (bool)play

Return Value

TRUE if the operation was successful.

Declared In

OALAudioTrack.h

playAfterTrack:

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

- (bool)playAfterTrack:(OALAudioTrack *)track

Parameters

track

The track to play after

Return Value

YES if the playback was successfully scheduled.

Discussion

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

Declared In

OALAudioTrack.h

playAfterTrack:timeAdjust:

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

- (bool)playAfterTrack:(OALAudioTrack *)track timeAdjust:(NSTimeInterval)timeAdjust

Parameters

track

The track to play after

timeAdjust

fine-tune value added to the time start offset.

Return Value

YES if the playback was successfully scheduled.

Discussion

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

Declared In

OALAudioTrack.h

playAtTime:

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

- (bool)playAtTime:(NSTimeInterval)time

Parameters

time

The time (device time) to start playing at.

Return Value

YES if the playback was successfully scheduled.

Discussion

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

Declared In

OALAudioTrack.h

playFile:

Play the contents of a file once.

- (bool)playFile:(NSString *)path

Parameters

path

The file containing the sound data.

Return Value

TRUE if the operation was successful.

Declared In

OALAudioTrack.h

playFile:loops:

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

- (bool)playFile:(NSString *)path loops:(NSInteger)loops

Parameters

path

The file containing the sound data.

loops

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

Return Value

TRUE if the operation was successful.

Declared In

OALAudioTrack.h

playFileAsync:loops:target:selector:

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

- (void)playFileAsync:(NSString *)path loops:(NSInteger)loops target:(id)target selector:(SEL)selector

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.

Declared In

OALAudioTrack.h

playFileAsync:target:selector:

Play the contents of a file asynchronously once.

- (void)playFileAsync:(NSString *)path target:(id)target selector:(SEL)selector

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.

Declared In

OALAudioTrack.h

playUrl:

Play the contents of a URL once.

- (bool)playUrl:(NSURL *)url

Parameters

url

The URL containing the sound data.

Return Value

TRUE if the operation was successful.

Declared In

OALAudioTrack.h

playUrl:loops:

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

- (bool)playUrl:(NSURL *)url loops:(NSInteger)loops

Parameters

url

The URL containing the sound data.

loops

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

Return Value

TRUE if the operation was successful.

Declared In

OALAudioTrack.h

playUrlAsync:loops:target:selector:

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

- (void)playUrlAsync:(NSURL *)url loops:(NSInteger)loops target:(id)target selector:(SEL)selector

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.

Declared In

OALAudioTrack.h

playUrlAsync:target:selector:

Play the contents of a URL asynchronously once.

- (void)playUrlAsync:(NSURL *)url target:(id)target selector:(SEL)selector

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.

Declared In

OALAudioTrack.h

preloadFile:

Preload the contents of a file for playback. Once the audio data is preloaded, you can call “play” to play it.

- (bool)preloadFile:(NSString *)path

Parameters

path

The file containing the sound data.

Return Value

TRUE if the operation was successful.

Declared In

OALAudioTrack.h

preloadFile:seekTime:

Preload the contents of a file for playback. Once the audio data is preloaded, you can call “play” to play it.

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

Parameters

path

The file containing the sound data.

seekTime

The position in the file to start playing at.

Return Value

TRUE if the operation was successful.

Declared In

OALAudioTrack.h

preloadFileAsync:seekTime:target:selector:

Asynchronously preload the contents of a file for playback. Once the audio data is preloaded, you can call “play” to play it.

- (bool)preloadFileAsync:(NSString *)path seekTime:(NSTimeInterval)seekTime target:(id)target selector:(SEL)selector

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.

Return Value

TRUE if the operation was successfully queued.

Declared In

OALAudioTrack.h

preloadFileAsync:target:selector:

Asynchronously preload the contents of a file for playback. Once the audio data is preloaded, you can call “play” to play it.

- (bool)preloadFileAsync:(NSString *)path target:(id)target selector:(SEL)selector

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.

Return Value

TRUE if the operation was successfully queued.

Declared In

OALAudioTrack.h

preloadUrl:

Preload the contents of a URL for playback. Once the audio data is preloaded, you can call “play” to play it.

- (bool)preloadUrl:(NSURL *)url

Parameters

url

The URL containing the sound data.

Return Value

TRUE if the operation was successful.

Declared In

OALAudioTrack.h

preloadUrl:seekTime:

Preload the contents of a URL for playback. Once the audio data is preloaded, you can call “play” to play it.

- (bool)preloadUrl:(NSURL *)url seekTime:(NSTimeInterval)seekTime

Parameters

url

The URL containing the sound data.

seekTime

The position in the file to start playing at.

Return Value

TRUE if the operation was successful.

Declared In

OALAudioTrack.h

preloadUrlAsync:seekTime:target:selector:

Asynchronously preload the contents of a URL for playback. Once the audio data is preloaded, you can call “play” to play it.

- (bool)preloadUrlAsync:(NSURL *)url seekTime:(NSTimeInterval)seekTime target:(id)target selector:(SEL)selector

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.

Return Value

TRUE if the operation was successfully queued.

Declared In

OALAudioTrack.h

preloadUrlAsync:target:selector:

Asynchronously preload the contents of a URL for playback. Once the audio data is preloaded, you can call “play” to play it.

- (bool)preloadUrlAsync:(NSURL *)url target:(id)target selector:(SEL)selector

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.

Return Value

TRUE if the operation was successfully queued.

Declared In

OALAudioTrack.h

stop

Stop playing and stop all operations.

- (void)stop

Declared In

OALAudioTrack.h

stopActions

Stop any internal fade or pan actions.

- (void)stopActions

Declared In

OALAudioTrack.h

stopFade

Stop the currently running fade operation, if any.

- (void)stopFade

Declared In

OALAudioTrack.h

stopPan

Stop the currently running pan operation, if any.

- (void)stopPan

Discussion

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

Declared In

OALAudioTrack.h

updateMeters

Updates the metering system to give current values. You must call this method before calling averagePowerForChannel or peakPowerForChannel in order to get current values.

- (void)updateMeters

Declared In

OALAudioTrack.h