SFBAudioPlayerNode


@interface SFBAudioPlayerNode : AVAudioSourceNode

An \c AVAudioSourceNode supporting gapless playback for PCM formats

The output format of \c SFBAudioPlayerNode is specified at object initialization and cannot be changed. The output format must be the standard format, deinterleaved native-endian 32-bit floating point PCM, at any sample rate with any number of channels.

\c SFBAudioPlayerNode is supplied by objects implementing \c SFBPCMDecoding (decoders) and supports audio at the same sample rate and with the same number of channels as the output format. \c SFBAudioPlayerNode supports seeking when supported by the decoder.

\c SFBAudioPlayerNode maintains a current decoder and a queue of pending decoders. The current decoder is the decoder that will supply the earliest audio frame in the next render cycle when playing. Pending decoders are automatically dequeued and become current when the final frame of the current decoder is pushed in the render block.

\c SFBAudioPlayerNode decodes audio in a high priority (non-realtime) thread into a ring buffer and renders on demand. Rendering occurs in a realtime thread when the render block is called; the render block always supplies audio. When playback is paused or insufficient audio is available the render block outputs silence.

Since decoding and rendering are distinct operations performed in separate threads, a GCD timer on the background queue is used for garbage collection. This is necessary because state data created in the decoding thread needs to live until rendering is complete, which cannot occur until after decoding is complete.

\c SFBAudioPlayerNode supports delegate-based callbacks for the following events:

  1. Decoding started
  2. Decoding complete
  3. Decoding canceled
  4. Rendering will start
  5. Rendering started
  6. Rendering complete
  7. End of audio

All callbacks are performed on a dedicated notification queue.

  • Returns an initialized \c SFBAudioPlayerNode object for stereo audio at 44,100 Hz

    Declaration

    Objective-C

    - (nonnull instancetype)init;

  • Returns an initialized \c SFBAudioPlayerNode object for audio with a specified number of channels and sample rate

    Declaration

    Objective-C

    - (nonnull instancetype)initWithSampleRate:(double)sampleRate
                                  channels:(AVAudioChannelCount)channels;

    Parameters

    sampleRate

    The sample rate supplied by the render block
    channels

    The number of channels supplied by the render block

    Return Value

    An initialized \c SFBAudioPlayerNode object or \c nil if memory or resource allocation failed

  • Returns an initialized \c SFBAudioPlayerNode object

    Note

    \c format must be standard

    Declaration

    Objective-C

    - (nonnull instancetype)initWithFormat:(nonnull AVAudioFormat *)format;

    Parameters

    format

    The format supplied by the render block

    Return Value

    An initialized \c SFBAudioPlayerNode object or \c nil if memory or resource allocation failed

  • Unavailable

    Undocumented

    Declaration

    Objective-C

    - (instancetype)initWithRenderBlock:(AVAudioSourceNodeRenderBlock)block NS_UNAVAILABLE;

  • Unavailable

    Undocumented

    Declaration

    Objective-C

    - (instancetype)initWithFormat:(AVAudioFormat *)format renderBlock:(AVAudioSourceNodeRenderBlock)block NS_UNAVAILABLE;

Format Information

  • Returns the format supplied by this object’s render block

    Declaration

    Objective-C

    @property (nonatomic, readonly) AVAudioFormat *_Nonnull renderingFormat;

  • Returns \c YES if audio with \c format can be played

    Declaration

    Objective-C

    - (BOOL)supportsFormat:(nonnull AVAudioFormat *)format;

    Parameters

    format

    A format to test for support

    Return Value

    \c YES if \c format has the same number of channels and sample rate as the rendering format

Queue Management

  • Cancels the current decoder, clears any queued decoders, and creates and enqueues a decoder for subsequent playback

    Note

    This is equivalent to \c -reset followed by \c -enqueueURL:error:

    Declaration

    Objective-C

    - (BOOL)resetAndEnqueueURL:(nonnull NSURL *)url
                     error:(NSError *_Nullable *_Nullable)error;

    Parameters

    url

    The URL to enqueue
    error

    An optional pointer to an \c NSError object to receive error information

    Return Value

    \c YES if a decoder was created and enqueued successfully

  • Cancels the current decoder, clears any queued decoders, and enqueues a decoder for subsequent playback

    Note

    This is equivalent to \c -reset followed by \c -enqueueDecoder:error:

    Declaration

    Objective-C

    - (BOOL)resetAndEnqueueDecoder:(nonnull id<SFBPCMDecoding>)decoder
                         error:(NSError *_Nullable *_Nullable)error;

    Parameters

    decoder

    The decoder to enqueue
    error

    An optional pointer to an \c NSError object to receive error information

    Return Value

    \c YES if the decoder was enqueued successfully

  • Creates and enqueues a decoder for subsequent playback

    Note

    This is equivalent to creating an \c SFBAudioDecoder object for \c url and passing that object to \c -enqueueDecoder:error:

    Declaration

    Objective-C

    - (BOOL)enqueueURL:(nonnull NSURL *)url
             error:(NSError *_Nullable *_Nullable)error;

    Parameters

    url

    The URL to enqueue
    error

    An optional pointer to an \c NSError object to receive error information

    Return Value

    \c YES if a decoder was created and enqueued successfully

  • Enqueues a decoder for subsequent playback

    Declaration

    Objective-C

    - (BOOL)enqueueDecoder:(nonnull id<SFBPCMDecoding>)decoder
                 error:(NSError *_Nullable *_Nullable)error;

    Parameters

    decoder

    The decoder to enqueue
    error

    An optional pointer to an \c NSError object to receive error information

    Return Value

    \c YES if the decoder was enqueued successfully

  • Cancels the current decoder

    Declaration

    Objective-C

    - (void)cancelCurrentDecoder;

  • Empties the decoder queue

    Declaration

    Objective-C

    - (void)clearQueue;

  • Returns \c YES if the decoder queue is empty

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL queueIsEmpty;

  • Removes and returns the next decoder from the decoder queue

    Declaration

    Objective-C

    - (nullable id<SFBPCMDecoding>)dequeueDecoder;

    Return Value

    The next decoder from the decoder queue or \c nil if none

Playback Control

  • Begins pushing audio from the current decoder

    Declaration

    Objective-C

    - (void)play;

  • Pauses audio from the current decoder and pushes silence

    Declaration

    Objective-C

    - (void)pause;

  • Cancels the current decoder, clears any queued decoders, and pushes silence

    Declaration

    Objective-C

    - (void)stop;

  • Toggles the playback state

    Declaration

    Objective-C

    - (void)togglePlayPause;

State

  • Returns \c YES if the \c SFBAudioPlayerNode is playing

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isPlaying;

  • Returns \c YES if a decoder is available to supply audio for the next render cycle

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isReady;

  • Returns the decoder supplying the earliest audio frame for the next render cycle or \c nil if none

    Warning

    Do not change any properties of the returned object

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) id<SFBPCMDecoding> currentDecoder;

Playback Properties

  • Returns the playback position in the current decoder or \c {SFBUnknownFramePosition, \c SFBUnknownFrameLength} if the current decoder is \c nil

    Declaration

    Objective-C

    @property (nonatomic, readonly) SFBAudioPlayerNodePlaybackPosition playbackPosition;

  • Returns the playback time in the current decoder or \c {SFBUnknownTime, \c SFBUnknownTime} if the current decoder is \c nil

    Declaration

    Objective-C

    @property (nonatomic, readonly) SFBAudioPlayerNodePlaybackTime playbackTime;

  • Retrieves the playback position and time

    Declaration

    Objective-C

    - (BOOL)getPlaybackPosition:
            (nullable SFBAudioPlayerNodePlaybackPosition *)playbackPosition
                    andTime:
                        (nullable SFBAudioPlayerNodePlaybackTime *)playbackTime;

    Parameters

    playbackPosition

    An optional pointer to an \c SFBAudioPlayerNodePlaybackPosition struct to receive playback position information
    playbackTime

    An optional pointer to an \c SFBAudioPlayerNodePlaybackTime struct to receive playback time information

    Return Value

    \c NO if the current decoder is \c nil

Seeking

  • Seeks forward in the current decoder by the specified number of seconds

    Declaration

    Objective-C

    - (BOOL)seekForward:(NSTimeInterval)secondsToSkip;

    Parameters

    secondsToSkip

    The number of seconds to skip forward

    Return Value

    \c NO if the current decoder is \c nil

  • Seeks backward in the current decoder by the specified number of seconds

    Declaration

    Objective-C

    - (BOOL)seekBackward:(NSTimeInterval)secondsToSkip;

    Parameters

    secondsToSkip

    The number of seconds to skip backward

    Return Value

    \c NO if the current decoder is \c nil

  • Seeks to the specified time in the current decoder

    Declaration

    Objective-C

    - (BOOL)seekToTime:(NSTimeInterval)timeInSeconds;

    Parameters

    timeInSeconds

    The desired time in seconds

    Return Value

    \c NO if the current decoder is \c nil

  • Seeks to the specified positioni n the current decoder

    Declaration

    Objective-C

    - (BOOL)seekToPosition:(double)position;

    Parameters

    position

    The desired position in the interval \c [0, 1)

    Return Value

    \c NO if the current decoder is \c nil

  • Seeks to the specified audio frame in the current decoder

    Declaration

    Objective-C

    - (BOOL)seekToFrame:(AVAudioFramePosition)frame;

    Parameters

    frame

    The desired audio frame

    Return Value

    \c NO if the current decoder is \c nil

  • Returns \c YES if the current decoder supports seeking

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL supportsSeeking;

Delegate

  • An optional delegate

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<SFBAudioPlayerNodeDelegate> delegate;

  • Playback position information for AudioPlayerNode

    See more

    Declaration

    Swift

    public struct PlaybackPosition

  • Returns the playback position in the current decoder or nil if the current decoder is nil

    Declaration

    Swift

    public var playbackPosition: PlaybackPosition? { get }

  • Playback time information for AudioPlayerNode

    See more

    Declaration

    Swift

    public struct PlaybackTime

  • Returns the playback time in the current decoder or nil if the current decoder is nil

    Declaration

    Swift

    public var playbackTime: PlaybackTime? { get }

  • Returns the playback position and time in the current decoder or nil if the current decoder is nil

    Declaration

    Swift

    public var playbackPositionAndTime: (position: PlaybackPosition, time: PlaybackTime)? { get }