A class that plays buffers or segments of audio files.
SDKs
- iOS 8.0+
- macOS 10.10+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
Framework
- AVFoundation
Declaration
class AVAudioPlayerNode : AVAudio Node
Overview
AVAudio
supports scheduling the playback of AVAudio
instances, or segments of audio files opened via AVAudio
. 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 AVAudio
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 AVAudio
method reset()
, unschedules all previously scheduled buffers and file segments, and returns the player timeline to sample time 0
.
Player Timeline
The usual AVAudio
sample times (as observed by last
) have an arbitrary zero point. AVAudio
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 node
and player
convert between the two.
Scheduling Playback Time
The schedule
, schedule
, and schedule
methods take an AVAudio
when
parameter. This parameter is interpreted as follows:
If the
when
parameter isnil
: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
AVAudio
specifies neither a valid sample time nor a host time.Time A segment's start frame or frame count is negative.