Class

AVAudioPlayer

An audio player that provides playback of audio data from a file or memory.

Overview

Use this class for audio playback unless you are playing audio captured from a network stream or require very low I/O latency.

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, see AVAudioSession and AVAudioSessionDelegate.

Topics

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() -> Bool

Plays a sound asynchronously.

func play(atTime: TimeInterval) -> Bool

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() -> Bool

Prepares the audio player for playback by preloading its buffers.

func setVolume(Float, fadeDuration: TimeInterval)

Fades to a new volume over a specific duration.

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

A protocol that allows 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

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.

var currentDevice: String?

The UID of the current audio player.

var format: AVAudioFormat

The format of the audio in the buffer.

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

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

func peakPower(forChannel: Int) -> Float

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.

Formats

General Audio Format Settings

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

Relationships

Inherits From

Conforms To

See Also

Single Track Playback and Recording

class AVAudioRecorder

A class that provides audio recording capability in your application.

class AVMIDIPlayer

A player for music file formats such as MIDI and iMelody.