SFBAudioPlayer


@interface SFBAudioPlayer : NSObject <SFBAudioPlayerNodeDelegate>

An audio player wrapping an \c AVAudioEngine processing graph supplied by \c SFBAudioPlayerNode

\c SFBAudioPlayer supports gapless playback for audio with the same sample rate and number of channels. For audio with different sample rates or channels, the audio processing graph is automatically reconfigured.

An \c SFBAudioPlayer may be in one of three playback states: playing, paused, or stopped. These states are based on whether the underlying \c AVAudioEngine is running (\c SFBAudioPlayer.engineIsRunning) and the \c SFBAudioPlayerNode is playing (\c SFBAudioPlayer.playerNodeIsPlaying).

\c SFBAudioPlayer 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. Now playing changed
  8. Playback state changed
  9. AVAudioEngineConfigurationChange notification received
  10. End of audio
  11. Asynchronous error encountered

The dispatch queue on which callbacks are performed is not specified.

Playlist Management

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

    Note

    This is equivalent to \c -enqueueURL:forImmediatePlayback:error: with \c YES for \c forImmediatePlayback followed by \c -playReturningError:

    Declaration

    Objective-C

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

    Parameters

    url

    The URL to play
    error

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

    Return Value

    \c YES if a decoder was created and enqueued and playback started successfully

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

    Note

    This is equivalent to \c -enqueueDecoder:forImmediatePlayback:error: with \c YES for \c forImmediatePlayback followed by \c -playReturningError:

    Declaration

    Objective-C

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

    Parameters

    decoder

    The decoder to play
    error

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

    Return Value

    \c YES if the decoder was enqueued and playback started successfully

  • Creates and enqueues a decoder for subsequent playback

    Note

    This is equivalent to \c -enqueueURL:forImmediatePlayback:error: with \c NO for \c forImmediatePlayback

    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

  • Creates and enqueues a decoder for subsequent playback, optionally canceling the current decoder and clearing any queued decoders

    Note

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

    Declaration

    Objective-C

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

    Parameters

    url

    The URL to enqueue
    forImmediatePlayback

    If \c YES the current decoder is canceled and any queued decoders are cleared before enqueuing
    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

    Note

    This is equivalent to \c -enqueueDecoder:forImmediatePlayback:error: with \c NO for \c forImmediatePlayback

    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

  • Enqueues a decoder for subsequent playback, optionally canceling the current decoder and clearing any queued decoders

    Note

    If \c forImmediatePlayback is \c YES, the audio processing graph is reconfigured for \c decoder.processingFormat if necessary

    Declaration

    Objective-C

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

    Parameters

    decoder

    The decoder to enqueue
    forImmediatePlayback

    If \c YES the current decoder is canceled and any queued decoders are cleared before enqueuing
    error

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

    Return Value

    \c YES if the decoder was enqueued successfully

  • Returns \c YES if audio with \c format will be played gaplessly

    Declaration

    Objective-C

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

  • 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;

Playback Control

  • Starts the underlying \c AVAudioEngine and plays the \c SFBAudioPlayerNode

    Note

    If the current \c playbackState is \c SFBAudioPlayerPlaybackStatePlaying this method has no effect

    Declaration

    Objective-C

    - (BOOL)playReturningError:(NSError *_Nullable *_Nullable)error;

    Parameters

    error

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

    Return Value

    \c YES if the underlying \c AVAudioEngine was successfully started

  • Pauses the \c SFBAudioPlayerNode

    Note

    If the current \c playbackState is not \c SFBAudioPlayerPlaybackStatePlaying this method has no effect

    Declaration

    Objective-C

    - (void)pause;

  • Plays the \c SFBAudioPlayerNode

    Note

    If the current \c playbackState is not \c SFBAudioPlayerPlaybackStatePaused this method has no effect

    Declaration

    Objective-C

    - (void)resume;

  • Stops both the underlying \c AVAudioEngine and \c SFBAudioPlayerNode

    Note

    This method cancels the current decoder and clears any queued decoders

    Note

    If the current \c playbackState is \c SFBAudioPlayerPlaybackStateStopped this method has no effect

    Declaration

    Objective-C

    - (void)stop;

  • Toggles the player between playing and paused states, starting playback if stopped

    If the current \c playbackState is \c SFBAudioPlayerPlaybackStateStopped this method sends \c -playReturningError: If the current \c playbackState is \c SFBAudioPlayerPlaybackStatePlaying this method sends \c -pause If the current \c playbackState is \c SFBAudioPlayerPlaybackStatePaused this method sends \c -resume

    Declaration

    Objective-C

    - (BOOL)togglePlayPauseReturningError:(NSError *_Nullable *_Nullable)error;

  • Resets both the underlying \c AVAudioEngine and \c SFBAudioPlayerNode

    Note

    This method cancels the current decoder and clears any queued decoders

    Declaration

    Objective-C

    - (void)reset;

Player State

  • Returns \c YES if the \c AVAudioEngine is running

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL engineIsRunning;

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

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL playerNodeIsPlaying;

  • Returns the current playback state

    Declaration

    Objective-C

    @property (nonatomic, readonly) SFBAudioPlayerPlaybackState playbackState;

  • Returns \c YES if \c engineIsRunning and \c playerNodeIsPlaying

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isPlaying;

  • Returns \c YES if \c engineIsRunning and \c !playerNodeIsPlaying

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isPaused;

  • Returns \c NO if \c engineIsRunning

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isStopped;

  • 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;

  • Returns the decoder approximating what a user would expect to see as the “now playing” item- the decoder that is currently rendering audio.

    Warning

    Do not change any properties of the returned object

    Declaration

    Objective-C

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

Playback Properties

  • Returns the frame position in the current decoder or \c SFBUnknownFramePosition if the current decoder is \c nil

    Declaration

    Objective-C

    @property (nonatomic, readonly) AVAudioFramePosition framePosition;

  • Returns the frame length of the current decoder or \c SFBUnknownFrameLength if the current decoder is \c nil

    Declaration

    Objective-C

    @property (nonatomic, readonly) AVAudioFramePosition frameLength;

  • 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) SFBAudioPlayerPlaybackPosition playbackPosition;

  • Returns the current time in the current decoder or \c SFBUnknownTime if the current decoder is \c nil

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSTimeInterval currentTime;

  • Returns the total time of the current decoder or \c SFBUnknownTime if the current decoder is \c nil

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSTimeInterval totalTime;

  • 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) SFBAudioPlayerPlaybackTime playbackTime;

  • Retrieves the playback position and time

    Declaration

    Objective-C

    - (BOOL)getPlaybackPosition:
            (nullable SFBAudioPlayerPlaybackPosition *)playbackPosition
                    andTime:(nullable SFBAudioPlayerPlaybackTime *)playbackTime;

    Parameters

    playbackPosition

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

    An optional pointer to an \c SFBAudioPlayerPlaybackTime 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 \c 3 seconds

    Declaration

    Objective-C

    - (BOOL)seekForward;

    Return Value

    \c NO if the current decoder is \c nil

  • Seeks backward in the current decoder by \c 3 seconds

    Declaration

    Objective-C

    - (BOOL)seekBackward;

    Return Value

    \c NO if the current decoder is \c nil

  • 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;

Volume Control

  • Returns \c kHALOutputParam_Volume on channel \c 0 for \c AVAudioEngine.outputNode.audioUnit or \c NaN on error

    Declaration

    Objective-C

    @property (nonatomic, readonly) float volume;

  • Sets \c kHALOutputParam_Volume on channel \c 0 for \c AVAudioEngine.outputNode.audioUnit

    Declaration

    Objective-C

    - (BOOL)setVolume:(float)volume error:(NSError *_Nullable *_Nullable)error;

    Parameters

    volume

    The desired volume
    error

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

    Return Value

    \c YES if the volume was successfully set

  • Returns \c kHALOutputParam_Volume on \c channel for \c AVAudioEngine.outputNode.audioUnit or \c NaN on error

    Declaration

    Objective-C

    - (float)volumeForChannel:(AudioObjectPropertyElement)channel;

  • Sets \c kHALOutputParam_Volume on channel \c 0 for \c AVAudioEngine.outputNode.audioUnit

    Declaration

    Objective-C

    - (BOOL)setVolume:(float)volume
       forChannel:(AudioObjectPropertyElement)channel
            error:(NSError *_Nullable *_Nullable)error;

    Parameters

    volume

    The desired volume
    channel

    The channel to adjust
    error

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

    Return Value

    \c YES if the volume was successfully set

Output Device

  • Returns the output device object ID for \c AVAudioEngine.outputNode

    Declaration

    Objective-C

    @property (nonatomic, readonly) AUAudioObjectID outputDeviceID;

  • Sets the output device for \c AVAudioEngine.outputNode

    Declaration

    Objective-C

    - (BOOL)setOutputDeviceID:(AUAudioObjectID)outputDeviceID
                    error:(NSError *_Nullable *_Nullable)error;

    Parameters

    outputDeviceID

    The audio object ID of the desired output device
    error

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

    Return Value

    \c YES if the output device was successfully set

Delegate

AVAudioEngine Access

  • Peforms an operation on the underlying \c AVAudioEngine

    Note

    Graph modifications may only be made between \c playerNode and \c engine.mainMixerNode

    Declaration

    Objective-C

    - (void)withEngine:(nonnull SFBAudioPlayerAVAudioEngineBlock)block;

    Parameters

    block

    A block performing operations on the underlying \c AVAudioEngine

  • Returns the \c SFBAudioPlayerNode that is the source of the audio processing graph

    Declaration

    Objective-C

    @property (nonatomic, readonly, nonnull) SFBAudioPlayerNode *playerNode;

  • Undocumented

    Declaration

    Swift

    public typealias PlaybackPosition = AudioPlayerNode.PlaybackPosition

  • Undocumented

    Declaration

    Swift

    public typealias PlaybackTime = AudioPlayerNode.PlaybackTime

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

    Declaration

    Swift

    public var framePosition: AVAudioFramePosition? { get }

  • Returns the frame length of the current decoder or nil if the current decoder is nil

    Declaration

    Swift

    public var frameLength: AVAudioFramePosition? { get }

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

    Declaration

    Swift

    public var position: PlaybackPosition? { get }

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

    Declaration

    Swift

    public var currentTime: TimeInterval? { get }

  • Returns the total time of the current decoder or nil if the current decoder is nil

    Declaration

    Swift

    public var totalTime: TimeInterval? { get }

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

    Declaration

    Swift

    public var time: PlaybackTime? { get }

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

    Declaration

    Swift

    public var positionAndTime: (position: PlaybackPosition, time: PlaybackTime)? { get }
  • See more

    Declaration

    Swift

    extension AudioPlayer.PlaybackState: CustomDebugStringConvertible