<!--
{
  "availability" : [
    "iOS: 8.0.0 -",
    "iPadOS: 8.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.10.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "AVFAudio",
  "identifier" : "/documentation/AVFAudio/AVAudioPlayerNode",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "AVFAudio"
    ],
    "preciseIdentifier" : "c:objc(cs)AVAudioPlayerNode"
  },
  "title" : "AVAudioPlayerNode"
}
-->

# AVAudioPlayerNode

An object for scheduling the playback of buffers or segments of audio files.

```
class AVAudioPlayerNode
```

## Overview

This audio node supports scheduling the playback of [`AVAudioPCMBuffer`](/documentation/AVFAudio/AVAudioPCMBuffer) instances, or segments of audio files that you open through [`AVAudioFile`](/documentation/AVFAudio/AVAudioFile). You can schedule buffers and segments to play at specific points in time or to play immediately following preceding segments.

Generally, you want to configure the node’s output format with the same number of channels as in the files and buffers. Otherwise, the node drops or adds channels as necessary. It’s usually preferable to use an [`AVAudioMixerNode`](/documentation/AVFAudio/AVAudioMixerNode) for this configuration.

Similarly, when playing file segments, the node makes sample rate conversions, if necessary. It’s preferable to configure the node’s output sample rate to match that of the files, and to 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.

The [`stop()`](/documentation/AVFAudio/AVAudioPlayerNode/stop()) method unschedules all previously scheduled buffers and file segments, and returns the player timeline to sample time `0`.

> Note:
> The `AVAudioPlayerNode` class isn’t key-value observing compliant, and may indicate that Combine publishers are available. Don’t use them for monitoring changes.

### Player Timeline

The usual [`AVAudioNode`](/documentation/AVFAudio/AVAudioNode) sample times, which [`lastRenderTime`](/documentation/AVFAudio/AVAudioNode/lastRenderTime) observes, have an arbitrary zero point. The `AVAudioPlayerNode` class superimposes a second player timeline on top of this to reflect when the player starts and intervals when it pauses. The methods [`nodeTime(forPlayerTime:)`](/documentation/AVFAudio/AVAudioPlayerNode/nodeTime(forPlayerTime:)) and [`playerTime(forNodeTime:)`](/documentation/AVFAudio/AVAudioPlayerNode/playerTime(forNodeTime:)) convert between the two.

### Scheduling Playback Time

The [`scheduleBuffer(_:at:options:completionHandler:)`](/documentation/AVFAudio/AVAudioPlayerNode/scheduleBuffer(_:at:options:completionHandler:)), [`scheduleFile(_:at:completionHandler:)`](/documentation/AVFAudio/AVAudioPlayerNode/scheduleFile(_:at:completionHandler:)), and [`scheduleSegment(_:startingFrame:frameCount:at:completionHandler:)`](/documentation/AVFAudio/AVAudioPlayerNode/scheduleSegment(_:startingFrame:frameCount:at:completionHandler:)) methods take an [`AVAudioTime`](/documentation/AVFAudio/AVAudioTime) `when` parameter, and you interpret it as follows:

- If the `when` parameter is `nil`:
- If there are previous commands, the new one plays immediately following the last one.
- Otherwise, if the node is in a playing state, the event plays in the very near future.
- Otherwise, the command plays at sample time `0`.
- If the `when` parameter is a sample time, the parameter interprets it as such.
- If the `when` parameter is a host time, the system ignores it unless the sample time is invalid when the engine is rendering to an audio device.

The scheduling methods fail if:

- A buffer’s channel count doesn’t match that of the node’s output format.
- The system can’t access a file.
- An [`AVAudioTime`](/documentation/AVFAudio/AVAudioTime) doesn’t specify a valid sample time or a host time.
- A segment’s start frame or frame count is a negative value.

### Handling Buffer or File Completion

The buffer of file completion handlers are a means to schedule more data if available on the player node. For more information on the different completion callback types, see [`AVAudioPlayerNodeCompletionCallbackType`](/documentation/AVFAudio/AVAudioPlayerNodeCompletionCallbackType).

> Important:
> Don’t stop a player within a completion handler callback because it can deadlock while trying to unschedule already scheduled buffers.

### Rendering Offline

When you use a player node with the engine operating in manual rendering mode, you use the buffer or file completion handlers — [`lastRenderTime`](/documentation/AVFAudio/AVAudioNode/lastRenderTime), [`latency`](/documentation/AVFAudio/AVAudioNode/latency), and [`outputPresentationLatency`](/documentation/AVFAudio/AVAudioNode/outputPresentationLatency) — to track how much data the player rendered and how much remains to render.

## Topics

### Creating a Player Node

[`init()`](/documentation/AVFAudio/AVAudioPlayerNode/init())

Creates an initialized audio player node.

### Scheduling Playback

[`scheduleFile(_:at:completionHandler:)`](/documentation/AVFAudio/AVAudioPlayerNode/scheduleFile(_:at:completionHandler:))

Schedules the playing of an entire audio file.

[`scheduleFile(_:at:completionCallbackType:completionHandler:)`](/documentation/AVFAudio/AVAudioPlayerNode/scheduleFile(_:at:completionCallbackType:completionHandler:))

Schedules the playing of an entire audio file with a callback option you specify.

[`scheduleSegment(_:startingFrame:frameCount:at:completionHandler:)`](/documentation/AVFAudio/AVAudioPlayerNode/scheduleSegment(_:startingFrame:frameCount:at:completionHandler:))

Schedules the playing of an audio file segment.

[`scheduleSegment(_:startingFrame:frameCount:at:completionCallbackType:completionHandler:)`](/documentation/AVFAudio/AVAudioPlayerNode/scheduleSegment(_:startingFrame:frameCount:at:completionCallbackType:completionHandler:))

Schedules the playing of an audio file segment with a callback option you specify.

[`scheduleBuffer(_:at:options:completionHandler:)`](/documentation/AVFAudio/AVAudioPlayerNode/scheduleBuffer(_:at:options:completionHandler:))

Schedules the playing samples from an audio buffer at the time and playback options you specify.

[`scheduleBuffer(_:completionHandler:)`](/documentation/AVFAudio/AVAudioPlayerNode/scheduleBuffer(_:completionHandler:))

Schedules the playing samples from an audio buffer.

[`scheduleBuffer(_:at:options:completionCallbackType:completionHandler:)`](/documentation/AVFAudio/AVAudioPlayerNode/scheduleBuffer(_:at:options:completionCallbackType:completionHandler:))

Schedules the playing samples from an audio buffer with the playback options you specify.

[`scheduleBuffer(_:completionCallbackType:completionHandler:)`](/documentation/AVFAudio/AVAudioPlayerNode/scheduleBuffer(_:completionCallbackType:completionHandler:))

Schedules the playing samples from an audio buffer with the callback option you specify.

[`AVAudioPlayerNodeBufferOptions`](/documentation/AVFAudio/AVAudioPlayerNodeBufferOptions)

The buffer options that control the playback scheduling.

[`AVAudioPlayerNodeCompletionCallbackType`](/documentation/AVFAudio/AVAudioPlayerNodeCompletionCallbackType)

Constants that specify when the framework must invoke the completion handler.

[`AVAudioPlayerNodeCompletionHandler`](/documentation/AVFAudio/AVAudioPlayerNodeCompletionHandler)

The callback handler for buffer or file completion.

### Converting Node and Player Times

[`nodeTime(forPlayerTime:)`](/documentation/AVFAudio/AVAudioPlayerNode/nodeTime(forPlayerTime:))

Converts from player time to node time.

[`playerTime(forNodeTime:)`](/documentation/AVFAudio/AVAudioPlayerNode/playerTime(forNodeTime:))

Converts from node time to player time.

### Controlling Playback

[`prepare(withFrameCount:)`](/documentation/AVFAudio/AVAudioPlayerNode/prepare(withFrameCount:))

Prepares the file regions or buffers you schedule for playback.

[`playAudio()`](/documentation/AVFAudio/AVAudioPlayerNode/playAudio())

[`playAudio(at:)`](/documentation/AVFAudio/AVAudioPlayerNode/playAudio(at:))

[`play()`](/documentation/AVFAudio/AVAudioPlayerNode/play())

Starts or resumes playback immediately.

[`play(at:)`](/documentation/AVFAudio/AVAudioPlayerNode/play(at:))

Starts or resumes playback at a time you specify.

[`isPlaying`](/documentation/AVFAudio/AVAudioPlayerNode/isPlaying)

A Boolean value that indicates whether the player is playing.

[`pause()`](/documentation/AVFAudio/AVAudioPlayerNode/pause())

Pauses the node’s playback.

[`stop()`](/documentation/AVFAudio/AVAudioPlayerNode/stop())

Clears all of the node’s events you schedule and stops playback.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)