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 you are playing audio captured from a network stream or require very low I/O latency. For an overview of audio technologies, see Audio & Video Starting 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

  • Seek to a particular point in a sound file, which supports such application features as fast forward and rewind

  • Obtain data you can use for playback-level metering

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

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.

To configure an appropriate audio session for playback on iOS, refer to AVAudioSession and AVAudioSessionDelegate. To learn how your choice of file formats impacts the simultaneous playback of multiple sounds, refer to iOS Hardware and Software Audio Codecs in Multimedia Programming Guide.


Initializing an AVAudioPlayer Object

init(contentsOf: URL)

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

init(data: Data)

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

init(contentsOf: URL, fileTypeHint: String?)

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

init(data: Data, fileTypeHint: String?)

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

Configuring and Controlling Playback

func play()

Plays a sound asynchronously.

func play(atTime: TimeInterval)

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

func pause()

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

func stop()

Stops playback and undoes the setup needed for playback.

func prepareToPlay()

Prepares the audio player for playback by preloading its buffers.

var isPlaying: Bool

A Boolean value that indicates whether the audio player is playing (true) or not (false).

var volume: Float

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

var pan: Float

The audio player’s stereo pan position.

var rate: Float

The audio player’s playback rate.

var enableRate: Bool

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

var numberOfLoops: Int

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

var delegate: AVAudioPlayerDelegate?

The delegate object for the audio player.

protocol AVAudioPlayerDelegate

The delegate of an AVAudioPlayer object must adopt the AVAudioPlayerDelegate protocol. All of the methods in this protocol are optional. They allow a delegate to respond to audio interruptions and audio decoding errors, and to the completion of a sound’s playback.

var settings: [String : Any]

The audio player’s settings dictionary, containing information about the sound associated with the player.

Managing Information About a Sound

var numberOfChannels: Int

The number of audio channels in the sound associated with the audio player.

var duration: TimeInterval

Returns the total duration, in seconds, of the sound associated with the audio player.

var currentTime: TimeInterval

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

var deviceCurrentTime: TimeInterval

The time value, in seconds, of the audio output device.

var url: URL?

The URL for the sound associated with the audio player.

var data: Data?

The data object containing the sound associated with the audio player.

Using Audio Level Metering

var isMeteringEnabled: Bool

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

func averagePower(forChannel: Int)

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

func peakPower(forChannel: Int)

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

func updateMeters()

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


General Audio Format Settings

Audio settings that apply to all audio formats handled by the AVAudioPlayer and AVAudioRecorder classes.


Inherits From

Conforms To

See Also

Simple Playback and Recording

class AVAudioRecorder

An instance of the AVAudioRecorder class, called an audio recorder, provides audio recording capability in your application.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software