Class

AVAudioPlayerNode

A class that plays buffers or segments of audio files.

Overview

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

Normally, you'll 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's usually preferable to use an AVAudioMixerNode to do this configuration.

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

When playing buffers, there's 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(), unschedules all previously scheduled buffers and file segments, and 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 parameter 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's ignored unless the sample time is invalid.

The scheduling methods fail if:

  • A buffer's channel count doesn't match that of the node's output format.

  • A file can't be accessed.

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

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

Topics

Creating a Player Node

init()

Initializes a player node instance.

Scheduling Playback

func scheduleBuffer(AVAudioPCMBuffer, at: AVAudioTime?, options: AVAudioPlayerNodeBufferOptions = [], completionHandler: AVAudioNodeCompletionHandler? = nil)

Schedule playing samples from an audio buffer at the specified time and with the specified playback options.

enum AVAudioPlayerNodeCompletionCallbackType

These constants specify when the completion handler must be invoked.

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

A Boolean value that 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.

Constants

struct AVAudioPlayerNodeBufferOptions

Options controlling buffer scheduling.

Relationships

Inherits From

Conforms To

See Also

Source Node Types

class AVAudioInputNode

A node that connects to the system's audio input.

class AVAudioIONode

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

typealias AVAudioIONodeInputBlock

A block to get input data, when called by a render operation in the manual rendering mode.

typealias AVAudioNodeCompletionHandler

A general callback handler.

typealias AVAudioPlayerNodeCompletionHandler

The callback handler for buffer or file completion.

class AVAudioUnitGenerator

An audio unit subclass that generates audio output.

class AVAudioUnitMIDIInstrument

An abstract class representing music devices or remote instruments.

class AVAudioUnitSampler

A class that encapsulates Apple's Sampler Audio Unit.

class AVAudioSequencer

A collection of MIDI events organized into multiple music tracks, plus a player to play back the events.