The AVAudioPlayerNode class plays buffers or segments of audio files.


AVAudioPlayerNode supports scheduling the playback of AVAudioBuffer instances, or segments of audio files opened via AVAudioFile. Buffers and segments may be scheduled at specific points in time, or to play immediately following preceding segments.

Normally, you will want to configure the node’s output format with the same number of channels as are in the files and buffers to be played. Otherwise, channels will be dropped or added as required. It is usually better to use an AVAudioMixerNode to do this.

Similarly, when playing file segments, the node will sample rate convert if necessary, but it is often preferable to configure the node’s output sample rate to match that of the file(s) and use a mixer to perform the rate conversion.

When playing buffers, there is an implicit assumption that the buffers are at the same sample rate as the node’s output format.

This class overrides the AVAudioNode method reset() and unschedules all previously scheduled buffers and file segments, and also returns the player timeline to sample time 0.

Player Timeline

The usual AVAudioNode sample times (as observed by lastRenderTime ) have an arbitrary zero point. AVAudioPlayerNode superimposes a second “player timeline” on top of this, to reflect when the player was started, and intervals during which it was paused. The methods nodeTime(forPlayerTime:) and playerTime(forNodeTime:) convert between the two.

Scheduling Playback Time

The scheduleBuffer(_:at:options:completionHandler:), scheduleFile(_:at:completionHandler:), and scheduleSegment(_:startingFrame:frameCount:at:completionHandler:)methods take an AVAudioTime when parameter. This is interpreted as follows:

  • If the when parameter is nil:

    • If there have been previous commands, the new one is played immediately following the last one.

    • Otherwise, if the node is playing, the event is played in the very near future.

    • Otherwise, the command is played at sample time 0.

  • If the when parameter is a sample time, the parameter is interpreted as such.

  • If the when parameter is a host time it is ignored unless sample time not valid.

The scheduling methods will fail if:

  • A buffer's channel count does not match that of the node's output format.

  • A file can't be accessed.

  • An AVAudioTime specifies neither a valid sample time or host time.

  • A segment's start frame or frame count is negative.


Converting Node and Player Times

func nodeTime(forPlayerTime: AVAudioTime)

Convert from player time to node time.

func playerTime(forNodeTime: AVAudioTime)

Convert from node time to player time.

Controlling Playback

func prepare(withFrameCount: AVAudioFrameCount)

Prepares previously scheduled file regions or buffers for playback.

func play()

Start or resume playback immediately.

func play(at: AVAudioTime?)

Start or resume playback at a specific time.

var isPlaying: Bool

Indicates whether or not the player is playing.

func pause()

Pause playback.

func stop()

Clear all of the node's previously scheduled events and stop playback.


struct AVAudioPlayerNodeBufferOptions

Options controlling buffer scheduling.



Inherits From

Conforms To

See Also


class AVAudioInputNode

The AVAudioInputNode class represents a node that connects to the system's audio input.

class AVAudioIONode

The AVAudioIONode class is the base class for nodes that connects to the system's audio input or output.

class AVAudioUnitGenerator

The AVAudioUnitGenerator is an AVAudioUnit subclass that generates audio output.

class AVAudioUnitMIDIInstrument

The AVAudioUnitMIDIInstrument class is an abstract class representing music devices or remote instruments.

class AVAudioUnitSampler

The AVAudioUnitSampler class encapsulates Apple's Sampler Audio Unit. The sampler audio unit can be configured by loading different types of instruments such as an “.aupreset” file, a DLS or SF2 sound bank, an EXS24 instrument, a single audio file or with an array of audio files. The output is a single stereo bus.

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