| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AVFoundation.framework |
| Availability | Available in iPhone OS 2.2 and later. |
| Declared in | AVAudioPlayer.h |
| Related sample code |
An instance of the AVAudioPlayer class, called an audio player, provides playback of audio data from a file or memory.
Apple recommends that you use this class for audio playback unless your application requires stereo positioning or precise synchronization, or you are playing audio captured from a network stream. For an overview of audio technologies, see Getting Started with Audio & Video.
Using an audio player you can:
Play sounds of any duration
Play sounds from files or memory buffers
Loop sounds
Play multiple sounds simultaneously, one sound per audio player
Control relative playback level for each sound you are playing
Seek to a particular point in a sound file, which supports such application features as fast forward and rewind
Obtain data that you can use for playback-level metering
The AVAudioPlayer class lets you play sound in any audio format available in iPhone OS. You use a delegate to handle interruptions (such as an incoming phone call) and to update the user interface when a sound has finished playing. The delegate methods for the AVAudioPlayer class are described in AVAudioPlayerDelegate Protocol Reference.
To play, pause, or stop an audio player, call one of its playback control methods, described in “Configuring and Controlling Playback.”
This class uses the Objective-C declared properties feature for managing information about a sound—such as the playback point within the sound’s timeline, and for accessing playback options—such as volume and looping. You also use a property (playing) to test whether or not playback is in progress.
To configure an appropriate audio session for playback, refer to AVAudioSession Class Reference and AVAudioSessionDelegate Protocol Reference. To learn how your choice of file formats impacts the simultaneous playback of multiple sounds, refer to “Playing Multiple Sounds Simultaneously” in iPhone Application Programming Guide.
– play
– pause
– stop
– prepareToPlay
playing property
volume property
numberOfLoops property
delegate property
numberOfChannels property
duration property
currentTime property
url property
data property
For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.
The playback point, in seconds, within the timeline of the sound associated with the audio player.
@property NSTimeInterval currentTime;
If the sound is playing, currentTime is the offset of the current playback position, measured in seconds from the start of the sound. If the sound is not playing, currentTime is the offset of where playing starts upon calling the play method, measured in seconds from the start of the sound.
By setting this property you can seek to a specific point in a sound file or implement audio fast-forward and rewind functions.
AVAudioPlayer.hThe data object containing the sound associated with the audio player. (read-only)
@property (readonly) NSData *data;
Returns nil if the audio player has no data (that is, if it was not initialized with an NSData object).
AVAudioPlayer.hThe delegate object for the audio player.
@property (assign) id <AVAudioPlayerDelegate> delegate;
The object that you assign to be an audio player’s delegate becomes the target of the notifications described in AVAudioPlayerDelegate Protocol Reference. These notifications let you respond to decoding errors, audio interruptions (such as an incoming phone call), and playback completion.
AVAudioPlayer.hReturns the total duration, in seconds, of the sound associated with the audio player. (read-only)
@property (readonly) NSTimeInterval duration;
AVAudioPlayer.hA Boolean value that indicates the audio-level metering on/off state for the audio player.
@property (getter=isMeteringEnabled) BOOL meteringEnabled;
The default value for the meteringEnabled property is off (Boolean NO). Before using metering for an audio player, you need to enable it by setting this property to YES. If player is an audio player instance variable of your controller class, you enable metering as shown here:
[self.player setMeteringEnabled: YES]; |
AVAudioPlayer.hThe number of audio channels in the sound associated with the audio player. (read-only)
@property (readonly) NSUInteger numberOfChannels;
AVAudioPlayer.hThe number of times a sound will return to the beginning, upon reaching the end, to repeat playback.
@property NSInteger numberOfLoops;
A value of 0, which is the default, means to play the sound once. Set a positive integer value to specify the number of times to return to the start and play again. For example, specifying a value of 1 results in a total of two plays of the sound. Set any negative integer value to loop the sound indefinitely until you call the stop method.
AVAudioPlayer.hA Boolean value that indicates whether the audio player is playing (YES) or not (NO). (read-only)
@property (readonly, getter=isPlaying) BOOL playing;
To find out when playback has stopped, use the audioPlayerDidFinishPlaying:successfully: delegate method.
Important: Do not poll this property (that is, do not use it inside of a loop) in an attempt to discover when playback has stopped.
AVAudioPlayer.hThe URL for the sound associated with the audio player. (read-only)
@property (readonly) NSURL *url;
Returns nil if the audio player was not initialized with a URL.
AVAudioPlayer.hThe playback gain for the audio player, ranging from 0.0 through 1.0.
@property float volume;
AVAudioPlayer.hReturns the average power for a given channel, in decibels, for the sound being played.
- (float)averagePowerForChannel:(NSUInteger)channelNumber
The audio channel whose average power value you want to obtain. Channel numbers are zero-indexed. A monaural signal, or the left channel of a stereo signal, has channel number 0.
A floating-point representation, in decibels, of a given audio channel’s current average power. A return value of 0 dB indicates full scale, or maximum power; a return value of -160 dB indicates minimum power (that is, near silence).
If the signal provided to the audio player exceeds ±full scale, then the return value may exceed 0 (that is, it may enter the positive range).
To obtain a current average power value, you must call the updateMeters method before calling this method.
AVAudioPlayer.hInitializes and returns an audio player for playing a designated sound file.
- (id)initWithContentsOfURL:(NSURL *)url error:(NSError **)outError
A URL identifying the sound file to play. The audio data must be in a format supported by Core Audio. See “Using Sound in iPhone OS” in iPhone Application Programming Guide.
On success, contains nil. On failure, contains an error code.
On success, an initialized AVAudioPlayer object. If nil, the outError parameter contains a code that describes the problem.
AVAudioPlayer.hInitializes and returns an audio player for playing a designated memory buffer.
- (id)initWithData:(NSData *)data error:(NSError **)outError
A block of data containing a sound to play. The audio data must be in a format supported by Core Audio. See “Using Sound in iPhone OS” in iPhone Application Programming Guide.
On success, contains nil. On failure, contains an error code.
On success, an initialized AVAudioPlayer object. If nil, the outError parameter contains a code that describes the problem.
AVAudioPlayer.hPauses playback; sound remains ready to resume playback from where it left off.
- (void)pause
Calling pause leaves the audio player prepared to play; it does not release the audio hardware that was acquired upon calling play or prepareToPlay.
AVAudioPlayer.hReturns the peak power for a given channel, in decibels, for the sound being played.
- (float)peakPowerForChannel:(NSUInteger)channelNumber
The audio channel whose peak power value you want to obtain. Channel numbers are zero-indexed. A monaural signal, or the left channel of a stereo signal, has channel number 0.
A floating-point representation, in decibels, of a given audio channel’s current peak power. A return value of 0 dB indicates full scale, or maximum power; a return value of -160 dB indicates minimum power (that is, near silence).
If the signal provided to the audio player exceeds ±full scale, then the return value may exceed 0 (that is, it may enter the positive range).
To obtain a current peak power value, you must call the updateMeters method before calling this method.
AVAudioPlayer.hPlays a sound asynchronously.
- (BOOL)play
Returns YES on success, or NO on failure.
Calling this method implicitly calls the prepareToPlay method if the audio player is not already prepared to play.
AVAudioPlayer.hPrepares the audio player for playback by preloading its buffers.
- (BOOL)prepareToPlay
Returns YES on success, or NO on failure.
Calling this method preloads buffers and acquires the audio hardware needed for playback, which minimizes the lag between calling the play method and the start of sound output.
Calling the stop method, or allowing a sound to finish playing, undoes this setup.
AVAudioPlayer.hStops playback and undoes the setup needed for playback.
- (void)stop
Calling this method, or allowing a sound to finish playing, undoes the setup performed upon calling the play or prepareToPlay methods.
The stop method does not reset the value of the currentTime property to 0. In other words, if you call stop during playback and then call play, playback resumes at the point where it left off.
AVAudioPlayer.hRefreshes the average and peak power values for all channels of an audio player.
- (void)updateMeters
To obtain current audio power values, you must call this method before calling averagePowerForChannel: or peakPowerForChannel:.
AVAudioPlayer.hLast updated: 2009-10-19
