Platforms to show: All Mac Windows Linux Cross-Platform
AVAudioPlayerNodeMBS class
Super class: AVAudioNodeMBS
Type | Topic | Plugin | Version | macOS | Windows | Linux | iOS | Targets |
class | AVFoundationNode | MBS AVFoundation Plugin | 15.3 | ✅ Yes | ❌ No | ❌ No | ✅ Yes | All |
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 nodeTimeForPlayerTime and playerTimeForNodeTime convert between the two.
Scheduling Playback Time
The scheduleBuffer, scheduleFile, and scheduleSegment 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.
- 3 events
- event scheduleBufferCompleted(callbackType as Integer, buffer as AVAudioPCMBufferMBS, time as AVAudioTimeMBS, options as Integer, tag as Variant)
- event scheduleFileCompleted(callbackType as Integer, file as AVAudioFileMBS, time as AVAudioTimeMBS, tag as Variant)
- event scheduleSegmentCompleted(callbackType as Integer, file as AVAudioFileMBS, startFrame as Int64, frameCount as Int64, time as AVAudioTimeMBS, tag as Variant)
- 9 properties
- property obstruction as Double
- property occlusion as Double
- property pan as Double
- property Playing as Boolean
- property position as AVAudio3DPointMBS
- property rate as Double
- property renderingAlgorithm as Integer
- property reverbBlend as Double
- property volume as Double
- 16 methods
- method Constructor
- method nodeTimeForPlayerTime(playerTime as AVAudioTimeMBS) as AVAudioTimeMBS
- method pause
- method play
- method playAtTime(time as AVAudioTimeMBS = nil)
- method playerTimeForNodeTime(nodeTime as AVAudioTimeMBS) as AVAudioTimeMBS
- method prepareWithFrameCount(frameCount as UInt32)
- method scheduleBuffer(buffer as AVAudioPCMBufferMBS, tag as Variant = nil)
- method scheduleBuffer(buffer as AVAudioPCMBufferMBS, time as AVAudioTimeMBS, options as Integer, tag as Variant = nil)
- method scheduleBuffer(callbackType as Integer, buffer as AVAudioPCMBufferMBS, tag as Variant = nil)
- method scheduleBuffer(callbackType as Integer, buffer as AVAudioPCMBufferMBS, time as AVAudioTimeMBS, options as Integer, tag as Variant = nil)
- method scheduleFile(callbackType as Integer, file as AVAudioFileMBS, time as AVAudioTimeMBS, tag as Variant = nil)
- method scheduleFile(file as AVAudioFileMBS, time as AVAudioTimeMBS, tag as Variant = nil)
- method scheduleSegment(callbackType as Integer, file as AVAudioFileMBS, time as AVAudioTimeMBS, startFrame as Int64, frameCount as Int64, tag as Variant = nil)
- method scheduleSegment(file as AVAudioFileMBS, time as AVAudioTimeMBS, startFrame as Int64, frameCount as Int64, tag as Variant = nil)
- method stop
- 6 constants
Options controlling buffer scheduling
Constant | Value | Description |
---|---|---|
BufferInterrupts | 2 |
The buffer interrupts any buffer already playing. |
BufferInterruptsAtLoop | 4 |
The buffer interrupts any buffer already playing, at its loop point. |
BufferLoops | 1 |
The buffer loops indefinitely. |
Completion Handler Modes
Constant | Value | Description |
---|---|---|
CompletionDataConsumed | 0 |
The buffer or file data has been consumed by the player. |
CompletionDataPlayedBack | 2 | Applicable only when the engine is rendering to/from an audio device. more |
CompletionDataRendered | 1 |
The buffer or file data has been rendered (i.e. output) by the player. This does not account for any signal processing latencies downstream of the player in the engine (see AVAudioNodeMBS.outputPresentationLatency). |
Super class AVAudioNodeMBS
- event Tap(bus as Integer, bufferSize as UInt32, format as AVAudioFormatMBS, buffer as AVAudioPCMBufferMBS, time as AVAudioTimeMBS, tag as Variant)
- 8 properties
- property AUAudioUnitHandle as Integer
- property engine as AVAudioEngineMBS
- property Handle as Integer
- property lastRenderTime as AVAudioTimeMBS
- property latency as Double
- property numberOfInputs as Integer
- property numberOfOutputs as Integer
- property outputPresentationLatency as Double
- 8 methods
- method Constructor Private
- method inputFormatForBus(busIndex as Integer) as AVAudioFormatMBS
- method installTapOnBus(busIndex as Integer, bufferSize as UInt32 = 0, format as AVAudioFormatMBS = nil, tag as Variant = nil)
- method nameForInputBus(busIndex as Integer) as string
- method nameForOutputBus(busIndex as Integer) as string
- method outputFormatForBus(busIndex as Integer) as AVAudioFormatMBS
- method removeTapOnBus(busIndex as Integer)
- method reset
- shared method available as boolean
This class has no sub classes.
Some examples using this class:
- /AVFoundation/AVAudioEngine manual rendering
- /AVFoundation/AVAudioEngine/Player
- /AVFoundation/AVAudioEngine/Player with AudioUnit for Level Meter
Blog Entries
Release notes
- Version 18.4
- Added newer methods in AVAudioPlayerNodeMBS with callBack type parameter
The items on this page are in the following plugins: MBS AVFoundation Plugin.
AVAudioPlayerMBS - AVAudioRecorderMBS