av audio player

AVAudioPlayer Class Reference

Contents

AVAudioPlayer Class Reference 4Overview 4Tasks 5

Initializing an AVAudioPlayer Object 5Configuring and Controlling Playback 6Managing Information About a Sound 6Using Audio Level Metering 7

Properties 7channelAssignments 7currentTime 8data 8delegate 9deviceCurrentTime 9duration 10enableRate 10meteringEnabled 11numberOfChannels 11numberOfLoops 12pan 12playing 12rate 13settings 13url 14volume 14

Instance Methods 15averagePowerForChannel: 15initWithContentsOfURL:error: 16initWithContentsOfURL:fileTypeHint:error: 16initWithData:error: 17initWithData:fileTypeHint:error: 18pause 19peakPowerForChannel: 19play 20playAtTime: 21

2014-02-11 | Copyright © 2014 Apple Inc. All Rights Reserved.

2

prepareToPlay 22stop 23updateMeters 23

Document Revision History 25


3

Contents

Inherits from NSObject

Conforms to NSObject (NSObject)

Framework /System/Library/Frameworks/AVFoundation.framework

Availability Available in iOS 2.2 and later.

Declared in AVAudioPlayer.h

Related sample code AddMusic

AQOfflineRenderTest

AVCaptureAudioDataOutput To AudioUnit iOS

Breadcrumb

oalTouch

OverviewAn instance of the AVAudioPlayer class, called an audio player, provides playback of audio data from a fileor memory.

Apple recommends that you use this class for audio playback unless you are playing audio captured from anetwork stream or require very low I/O latency. For an overview of audio technologies, see Audio & VideoStarting Point and “Using Audio” in Multimedia Programming Guide .

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, with precise synchronization

● Control relative playback level, stereo positioning, and playback rate for each sound you are playing


4

AVAudioPlayer Class Reference

● Seek to a particular point in a sound file, which supports such application features as fast forward andrewind

● Obtain data you can use for playback-level metering

The AVAudioPlayer class lets you play sound in any audio format available in iOS and OS X. You implementa delegate to handle interruptions (such as an incoming phone call on iOS) and to update the user interfacewhen a sound has finished playing. The delegate methods are described in AVAudioPlayerDelegate ProtocolReference .

To play, pause, or stop an audio player, call one of its playback control methods, described in “Configuring andControlling Playback” (page 6).

This class uses the Objective-C declared properties feature for managing information about a sound—such asthe playback point within the sound’s timeline, and for accessing playback options—such as volume andlooping.

To configure an appropriate audio session for playback on iOS, refer to AVAudioSession Class Reference andAVAudioSessionDelegate Protocol Reference . To learn how your choice of file formats impacts the simultaneousplayback of multiple sounds, refer to “iOS Hardware and Software Audio Codecs” in Multimedia ProgrammingGuide .

Tasks

Initializing an AVAudioPlayer Object

– initWithContentsOfURL:error: (page 16)Initializes and returns an audio player for playing a designated sound file.

– initWithData:error: (page 17)Initializes and returns an audio player for playing a designated memory buffer.

– initWithContentsOfURL:fileTypeHint:error: (page 16)Initializes and returns an audio player using the specified URL and file type hint.

– initWithData:fileTypeHint:error: (page 18)Initializes and returns an audio player using the specified data and file type hint.

AVAudioPlayer Class ReferenceTasks


5

Configuring and Controlling Playback

– play (page 20)Plays a sound asynchronously.

– playAtTime: (page 21)Plays a sound asynchronously, starting at a specified point in the audio output device’s timeline.

– pause (page 19)Pauses playback; sound remains ready to resume playback from where it left off.

– stop (page 23)Stops playback and undoes the setup needed for playback.

– prepareToPlay (page 22)Prepares the audio player for playback by preloading its buffers.

playing (page 12) propertyA Boolean value that indicates whether the audio player is playing (YES) or not (NO). (read-only)

volume (page 14) propertyThe playback volume for the audio player, ranging from 0.0 through 1.0 on a linear scale.

pan (page 12) propertyThe audio player’s stereo pan position.

rate (page 13) propertyThe audio player’s playback rate.

enableRate (page 10) propertyA Boolean value that specifies whether playback rate adjustment is enabled for an audio player.

numberOfLoops (page 12) propertyThe number of times a sound will return to the beginning, upon reaching the end, to repeat playback.

delegate (page 9) propertyThe delegate object for the audio player.

settings (page 13) propertyThe audio player’s settings dictionary, containing information about the sound associated with the player.(read-only)

Managing Information About a Sound

numberOfChannels (page 11) propertyThe number of audio channels in the sound associated with the audio player. (read-only)

AVAudioPlayer Class ReferenceTasks


6

channelAssignments (page 7) propertyAn array of AVAudioSessionChannelDescription objects associated with the audio player

duration (page 10) propertyReturns the total duration, in seconds, of the sound associated with the audio player. (read-only)

currentTime (page 8) propertyThe playback point, in seconds, within the timeline of the sound associated with the audio player.

deviceCurrentTime (page 9) propertyThe time value, in seconds, of the audio output device. (read-only)

url (page 14) propertyThe URL for the sound associated with the audio player. (read-only)

data (page 8) propertyThe data object containing the sound associated with the audio player. (read-only)

Using Audio Level Metering

meteringEnabled (page 11) propertyA Boolean value that specifies the audio-level metering on/off state for the audio player.

– averagePowerForChannel: (page 15)Returns the average power for a given channel, in decibels, for the sound being played.

– peakPowerForChannel: (page 19)Returns the peak power for a given channel, in decibels, for the sound being played.

– updateMeters (page 23)Refreshes the average and peak power values for all channels of an audio player.

Properties

channelAssignments

An array of AVAudioSessionChannelDescription objects associated with the audio player

AVAudioPlayer Class ReferenceProperties


7

@property(nonatomic, copy) NSArray *channelAssignments

DiscussionThe default value for this property is nil. When non-nil, this array must have the same number of elementsas returned by the numberOfChannels (page 11) property. You can use this property to help you assign outputto play to different channels.

AvailabilityAvailable in iOS 7.0 and later.

Declared inAVAudioPlayer.h

currentTime

The playback point, in seconds, within the timeline of the sound associated with the audio player.

@property NSTimeInterval currentTime

DiscussionIf the sound is playing, currentTime is the offset of the current playback position, measured in seconds fromthe start of the sound. If the sound is not playing, currentTime is the offset of where playing starts uponcalling the play (page 20) 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 andrewind functions.


See Also @property deviceCurrentTime (page 9) @property duration (page 10)


data

The data object containing the sound associated with the audio player. (read-only)



8

@property(readonly) NSData *data

DiscussionReturns nil if the audio player has no data (that is, if it was not initialized with an NSData object).


See Also @property url (page 14)


delegate

The delegate object for the audio player.

@property(assign) id<AVAudioPlayerDelegate> delegate

DiscussionThe object that you assign to be an audio player’s delegate becomes the target of the notifications describedin AVAudioPlayerDelegate Protocol Reference . These notifications let you respond to decoding errors, audiointerruptions (such as an incoming phone call), and playback completion.



deviceCurrentTime

The time value, in seconds, of the audio output device. (read-only)

@property(readonly) NSTimeInterval deviceCurrentTime

DiscussionThe 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 incrementingas long as at least one of the players is playing or paused.



9

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

Use this property to indicate “now” when calling the playAtTime: (page 21) instance method. By configuringmultiple audio players to play at a specified offset from deviceCurrentTime, you can perform precisesynchronization—as described in the discussion for that method.


See Also @property currentTime (page 8)– playAtTime: (page 21)


duration

Returns the total duration, in seconds, of the sound associated with the audio player. (read-only)

@property(readonly) NSTimeInterval duration


See Also @property currentTime (page 8)


enableRate

A Boolean value that specifies whether playback rate adjustment is enabled for an audio player.

@property BOOL enableRate

DiscussionTo enable adjustable playback rate for an audio player, set this property to YES after you initialize the playerand before you call the prepareToPlay (page 22) instance method for the player.



10



meteringEnabled

A Boolean value that specifies the audio-level metering on/off state for the audio player.

@property(getter=isMeteringEnabled) BOOL meteringEnabled

DiscussionThe default value for the meteringEnabled property is off (Boolean NO). Before using metering for an audioplayer, you need to enable it by setting this property to YES. If player is an audio player instance variable ofyour controller class, you enable metering as shown here:

[self.player setMeteringEnabled: YES];


See Also– averagePowerForChannel: (page 15)– peakPowerForChannel: (page 19)– updateMeters (page 23)


numberOfChannels

The number of audio channels in the sound associated with the audio player. (read-only)

@property(readonly) NSUInteger numberOfChannels





11

numberOfLoops

The number of times a sound will return to the beginning, upon reaching the end, to repeat playback.

@property NSInteger numberOfLoops

DiscussionA value of 0, which is the default, means to play the sound once. Set a positive integer value to specify thenumber of times to return to the start and play again. For example, specifying a value of 1 results in a total oftwo plays of the sound. Set any negative integer value to loop the sound indefinitely until you call the stop (page23) method.



pan

The audio player’s stereo pan position.

@property float pan

DiscussionBy setting this property you can position a sound in the stereo field. A value of –1.0 is full left, 0.0 is center,and 1.0 is full right.



playing

A Boolean value that indicates whether the audio player is playing (YES) or not (NO). (read-only)

@property(readonly, getter=isPlaying) BOOL playing

DiscussionTo find out when playback has stopped implement the audioPlayerDidFinishPlaying:successfully:delegate method.



12

Important: Do not poll this property to determine when playback has completed, instead implement thespecified delegate method.


Related Sample CodeAddMusic


rate

The audio player’s playback rate.

@property float rate

DiscussionThis property’s default value of 1.0 provides normal playback rate. The available range is from 0.5 for half-speedplayback through 2.0 for double-speed playback.

To set an audio player’s playback rate, you must first enable rate adjustment as described in theenableRate (page 10) property description.



settings

The audio player’s settings dictionary, containing information about the sound associated with the player.(read-only)

@property(readonly) NSDictionary *settings

DiscussionAn audio player’s settings dictionary contains keys for the following information about the player’s associatedsound:

● Channel layout (AVChannelLayoutKey)



13

● Encoder bit rate (AVEncoderBitRateKey)

● Audio data format (AVFormatIDKey)

● Channel count (AVNumberOfChannelsKey)

● Sample rate (AVSampleRateKey)

The settings keys are described in AV Foundation Audio Settings Constants .



url

The URL for the sound associated with the audio player. (read-only)

@property(readonly) NSURL *url

DiscussionReturns nil if the audio player was not initialized with a URL.


See Also @property data (page 8)


volume

The playback volume for the audio player, ranging from 0.0 through 1.0 on a linear scale.

@property float volume

DiscussionA value of 0.0 indicates silence; a value of 1.0 (the default) indicates full volume for the audio player instance.

Use this property to control an audio player’s volume relative to other audio output.



14

To provide UI in iOS for adjusting system audio playback volume, use the MPVolumeView class, which providesmedia playback controls that users expect and whose appearance you can customize.



Instance Methods

averagePowerForChannel:

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

- (float)averagePowerForChannel:(NSUInteger)channelNumber

ParameterschannelNumber

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.

Return ValueA floating-point representation, in decibels, of a given audio channel’s current average power. A return valueof 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, itmay enter the positive range).

DiscussionTo obtain a current average power value, you must call the updateMeters (page 23) method before callingthis method.


See Also @property meteringEnabled (page 11)– peakPowerForChannel: (page 19)

AVAudioPlayer Class ReferenceInstance Methods


15


initWithContentsOfURL:error:

Initializes and returns an audio player for playing a designated sound file.

- (id)initWithContentsOfURL:(NSURL *)url error:(NSError **)outError

Parametersurl

A URL identifying the sound file to play. The audio data must be in a format supported by Core Audio.For a list of supported formats, see “Using Audio” in Multimedia Programming Guide .

outErrorIf an error occurs, upon return the NSError object describes the error. Set to NULL to ignore errors.

Return ValueOn success, an initialized AVAudioPlayer object. If nil, the outError parameter contains an NSErrorinstance describing the problem.


See Also– initWithData:error: (page 17)– initWithData:fileTypeHint:error: (page 18)– initWithContentsOfURL:fileTypeHint:error: (page 16)

Related Sample CodeAddMusicAQOfflineRenderTestAVCaptureAudioDataOutput To AudioUnit iOSBreadcrumboalTouch


initWithContentsOfURL:fileTypeHint:error:

Initializes and returns an audio player using the specified URL and file type hint.



16

- (id)initWithContentsOfURL:(NSURL *)url fileTypeHint:(NSString *)utiStringerror:(NSError **)outError

Parametersurl

A URL identifying the sound file to play. The audio data must be in a format supported by Core Audio.For a list of supported formats, see “Using Audio” in Multimedia Programming Guide .

utiStringA UTI that is used as a file type hint. The supported UTIs are defined in File Format UTIs.



DiscussionThe utiString file type hint tells the parser what kind of sound data to expect so that files which are not selfidentifying, or possibly even corrupt, can be successfully parsed.


See Also– initWithData:error: (page 17)– initWithData:fileTypeHint:error: (page 18)– initWithContentsOfURL:error: (page 16)


initWithData:error:

Initializes and returns an audio player for playing a designated memory buffer.

- (id)initWithData:(NSData *)data error:(NSError **)outError

Parametersdata

A block of data containing a sound to play. The audio data must be in a format supported by Core Audio.For a list of supported formats, see “Using Audio” in Multimedia Programming Guide .



17




See Also– initWithData:fileTypeHint:error: (page 18)– initWithContentsOfURL:error: (page 16)– initWithContentsOfURL:fileTypeHint:error: (page 16)


initWithData:fileTypeHint:error:

Initializes and returns an audio player using the specified data and file type hint.

- (id)initWithData:(NSData *)data fileTypeHint:(NSString *)utiString error:(NSError**)outError

Parametersdata

The data object containing the audio.

utiStringA UTI that is used as a file type hint. The supported UTIs are defined in File Format UTIs.



DiscussionThe utiString file type hint tells the parser what kind of sound data to expect so that data that may possiblybe corrupt, can be successfully parsed.



18


See Also– initWithData:error: (page 17)– initWithContentsOfURL:error: (page 16)– initWithContentsOfURL:fileTypeHint:error: (page 16)


pause

Pauses playback; sound remains ready to resume playback from where it left off.

- (void)pause

DiscussionCalling pause leaves the audio player prepared to play; it does not release the audio hardware that was acquiredupon calling play or prepareToPlay.


See Also– play (page 20)– prepareToPlay (page 22)– stop (page 23)


peakPowerForChannel:

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

- (float)peakPowerForChannel:(NSUInteger)channelNumber

ParameterschannelNumber

The audio channel whose peak power value you want to obtain. Channel numbers are zero-indexed. Amonaural signal, or the left channel of a stereo signal, has channel number 0.



19

Return ValueA floating-point representation, in decibels, of a given audio channel’s current peak power. A return value of0 dB indicates full scale, or maximum power; a return value of –160 dB indicates minimum power (that is, nearsilence).

If the signal provided to the audio player exceeds ±full scale, then the return value may exceed 0 (that is, itmay enter the positive range).

DiscussionTo obtain a current peak power value, you must call the updateMeters (page 23) method before calling thismethod.


See Also @property meteringEnabled (page 11)– averagePowerForChannel: (page 15)


play

Plays a sound asynchronously.

- (BOOL)play

Return ValueReturns YES on success, or NO on failure.

DiscussionCalling this method implicitly calls the prepareToPlay method if the audio player is not already prepared toplay.


See Also– pause (page 19)– playAtTime: (page 21)– prepareToPlay (page 22)– stop (page 23)



20

Related Sample CodeAddMusicAQOfflineRenderTestAVCaptureAudioDataOutput To AudioUnit iOSoalTouch


playAtTime:

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

- (BOOL)playAtTime:(NSTimeInterval)time

Parameterstime

The number of seconds to delay playback, relative to the audio output device’s current time. For example,to start playback three seconds into the future from the time you call this method, use code like this:

NSTimeInterval playbackDelay = 3.0; // must be ≥ 0

[myAudioPlayer playAtTime: myAudioPlayer.deviceCurrentTime + playbackDelay];

Important: The value that you provide to the time parameter must be greater than or equal to the value of theaudio player’s deviceCurrentTime (page 9) property.

Return ValueYES on success, or NO on failure.

DiscussionUse this method to precisely synchronize the playback of two or more AVAudioPlayer objects. This codesnippet shows the recommended way to do this:

// Before calling this method, instantiate two AVAudioPlayer objects and

// assign each of them a sound.

- (void) startSynchronizedPlayback {

NSTimeInterval shortStartDelay = 0.01; // seconds

NSTimeInterval now = player.deviceCurrentTime;



21

[player playAtTime: now + shortStartDelay];

[secondPlayer playAtTime: now + shortStartDelay];

// Here, update state and user interface for each player, as appropriate

}

To learn about the virtual audio output device’s timeline, read the description for the deviceCurrentTime (page9) property.

Calling this method implicitly calls the prepareToPlay method if the audio player is not already prepared toplay.


See Also– pause (page 19)– play (page 20)– prepareToPlay (page 22)– stop (page 23)


prepareToPlay

Prepares the audio player for playback by preloading its buffers.

- (BOOL)prepareToPlay

Return ValueReturns YES on success, or NO on failure.

DiscussionCalling this method preloads buffers and acquires the audio hardware needed for playback, which minimizesthe 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.



22


See Also– pause (page 19)– play (page 20)– stop (page 23)


stop

Stops playback and undoes the setup needed for playback.

- (void)stop

DiscussionCalling this method, or allowing a sound to finish playing, undoes the setup performed upon calling the playor prepareToPlay methods.

The stop method does not reset the value of the currentTime (page 8) property to 0. In other words, if youcall stop during playback and then call play, playback resumes at the point where it left off.


See Also– pause (page 19)– play (page 20)– prepareToPlay (page 22)

Related Sample CodeoalTouch


updateMeters

Refreshes the average and peak power values for all channels of an audio player.

- (void)updateMeters



23

DiscussionTo obtain current audio power values, you must call this method before calling averagePowerForChannel: (page15) or peakPowerForChannel: (page 19).


See Also @property meteringEnabled (page 11)




24

This table describes the changes to AVAudioPlayer Class Reference .

NotesDate

Improved the description of the volume (page 14) property.2014-02-11

Updated for iOS 7.2013-09-18

Added new symbols for iOS 6.02012-09-19

Added descriptions for the two playback rate properties, rate (page 13)and enableRate (page 10).

2011-10-12

Corrected the descriptions of the error parameters for theinitWithContentsOfURL:error: (page 16) andinitWithData:error: (page 17) instance methods.

2010-08-31

Updated for iOS 4.0.2010-05-08

Added descriptions for three new properties: deviceCurrentTime (page9), pan (page 12), and settings (page 13).

Added a description for the new playAtTime: (page 21) instance method.

Clarified how to use the playing (page 12) property.2009-10-19

Improved the descriptions of the return values for theaveragePowerForChannel: (page 15) and peakPowerForChannel: (page19) methods.

Minor additions and corrections.2009-06-04


25

Document Revision History

NotesDate

Updated for iOS 3.0 by adding links to AVAudioSession Class Referenceand AVAudioSessionDelegate Protocol Reference .

2009-03-02

New document that describes a class for simple audio playback.2008-11-11

Document Revision History


26

Apple Inc.Copyright © 2014 Apple Inc.All rights reserved.

No part of this publication may be reproduced,stored in a retrieval system, or transmitted, in anyform or by any means, mechanical, electronic,photocopying, recording, or otherwise, withoutprior written permission of Apple Inc., with thefollowing exceptions: Any person is herebyauthorized to store documentation on a singlecomputer for personal use only and to printcopies of documentation for personal useprovided that the documentation containsApple’s copyright notice.

No licenses, express or implied, are granted withrespect to any of the technology described in thisdocument. Apple retains all intellectual propertyrights associated with the technology describedin this document. This document is intended toassist application developers to developapplications only for Apple-labeled computers.

Apple Inc.1 Infinite LoopCupertino, CA 95014408-996-1010

Apple, the Apple logo, iPhone, Objective-C, andOS X are trademarks of Apple Inc., registered inthe U.S. and other countries.

iOS is a trademark or registered trademark ofCisco in the U.S. and other countries and is usedunder license.

Even though Apple has reviewed this document,APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THISDOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED“AS IS,” AND YOU, THE READER, ARE ASSUMING THEENTIRE RISK AS TO ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIALDAMAGES RESULTING FROM ANY DEFECT ORINACCURACY IN THIS DOCUMENT, even if advised ofthe possibility of such damages.

THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,agent, or employee is authorized to make anymodification, extension, or addition to this warranty.

Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation orexclusion may not apply to you. This warranty givesyou specific legal rights, and you may also have otherrights which vary from state to state.

av audio player

Documents

audio playback

audio player

playback of audio data

playback rate

audio videostarting

audio level metering

audio format available

overview of audio technologies