AudioPlayer

@interface AudioPlayer
    : NSObject <EZAudioFileDelegate, EZOutputDataSource, EZOutputDelegate>
  • @brief The AudioPlayer plays audio files using Core Audio services.

@discussion To play audio files, the AudioPlayer uses the EZAudioFile and EZOutput objects. To play a file, the AudioPlayer creates an EZAudioFile instance to read audio data from the file. For playback of the audio data, it uses an EZOutput instance - this object makes use of AudioUnit to convert the audio data coming into a playback graph of audio processing units.

This class acts as the master delegate (the EZAudioFileDelegate) over whatever EZAudioFile instance, the audioFile property, it is using for playback as well as the EZOutputDelegate and EZOutputDataSource over whatever EZOutput instance is set as the output. Classes that want to get the EZAudioFileDelegate callbacks should implement the AudioPlayer’s AudioPlayerDelegate on the AudioPlayer instance.

Properties

  • An offset by which the audio playback can be moved forward or back. This is used typically to callibrate the playback so that currentTime reports the time when the sound actually reaches the speakers. There is no need take into account for the time it takes for the sound to travel to the listener’s ears.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSTimeInterval offset;

    Swift

    var offset: TimeInterval { get set }

  • A BOOL indicating whether the player should loop the file

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) BOOL shouldLoop;

    Swift

    var shouldLoop: Bool { get set }

  • An AudioPlayerState value representing the current internal playback and file state of the AudioPlayer instance.

    Declaration

    Objective-C

    @property (readonly, assign, nonatomic) AudioPlayerState state;

    Swift

    var state: AudioPlayerState { get }

  • Audio file URL. A file in the app’s file system

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) NSString *audioFileURL;

    Swift

    var audioFileURL: String! { get set }

  • The EZAudioFile representing the currently selected audio file

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) EZAudioFile *audioFile;

    Swift

    var audioFile: EZAudioFile! { get set }

  • The AudioPlayerDelegate that will handle the audio player callbacks

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) id<AudioPlayerDelegate> delegate;

    Swift

    var delegate: AudioPlayerDelegate! { get set }

  • Provides the current offset in the audio file as an NSTimeInterval (i.e. in seconds). When setting this it will determine the correct frame offset and perform a seekToFrame to the new time offset. - warning: Make sure the new current time offset is less than the duration or you will receive an invalid seek assertion.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSTimeInterval currentTime;

    Swift

    var currentTime: TimeInterval { get set }

  • The EZAudioDevice instance that is being used by the output. Similarly, setting this just sets the device property of the output.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) EZAudioDevice *device;

    Swift

    var device: EZAudioDevice! { get set }

  • Provides the duration of the audio file in seconds.

    Declaration

    Objective-C

    @property (readonly, atomic) NSTimeInterval duration;

    Swift

    var duration: TimeInterval { get }

  • Provides the current time as an NSString with the time format MM:SS.

    Declaration

    Objective-C

    @property (readonly, atomic) NSString *formattedCurrentTime;

    Swift

    var formattedCurrentTime: String! { get }

  • Provides the duration as an NSString with the time format MM:SS.

    Declaration

    Objective-C

    @property (readonly, atomic) NSString *formattedDuration;

    Swift

    var formattedDuration: String! { get }

  • Provides the EZOutput that is being used to handle the actual playback of the audio data. This property is also settable, but note that the AudioPlayer will become the output’s EZOutputDataSource and EZOutputDelegate. To listen for the EZOutput’s delegate methods your view should implement the AudioPlayerDelegate and set itself as the AudioPlayer’s delegate.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) EZOutput *output;

    Swift

    var output: EZOutput! { get set }

  • Provides the frame index (a.k.a the seek positon) within the audio file being used for playback. This can be helpful when seeking through the audio file. - returns: An SInt64 representing the current frame index within the audio file used for playback.

    Declaration

    Objective-C

    @property (readonly, atomic) SInt64 frameIndex;

    Swift

    var frameIndex: Int64 { get }

    Return Value

    An SInt64 representing the current frame index within the audio file used for playback.

  • Provides a flag indicating whether the AudioPlayer is currently playing back any audio. - returns: A BOOL indicating whether or not the AudioPlayer is performing playback,

    Declaration

    Objective-C

    @property (readonly, atomic) BOOL isPlaying;

    Swift

    var isPlaying: Bool { get }

    Return Value

    A BOOL indicating whether or not the AudioPlayer is performing playback,

  • pan

    Provides the current pan from the audio player’s internal output component. Setting the pan adjusts the direction of the audio signal from left (0) to right (1). Default is 0.5 (middle).

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) float pan;

    Swift

    var pan: Float { get set }

  • Provides the total amount of frames in the current audio file being used for playback. - returns: A SInt64 representing the total amount of frames in the current audio file being used for playback.

    Declaration

    Objective-C

    @property (readonly, atomic) SInt64 totalFrames;

    Swift

    var totalFrames: Int64 { get }

    Return Value

    A SInt64 representing the total amount of frames in the current audio file being used for playback.

  • url

    Provides the file path that’s currently being used by the player for playback. - returns: The NSURL representing the file path of the audio file being used for playback.

    Declaration

    Objective-C

    @property (readonly, copy, nonatomic) NSURL *url;

    Swift

    var url: URL! { get }

    Return Value

    The NSURL representing the file path of the audio file being used for playback.

  • Provides the current volume from the audio player’s internal output component. Setting the volume adjusts the gain of the output between 0 and 1. Default is 1.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) float volume;

    Swift

    var volume: Float { get set }

Initializers

  • Initializes the AudioPlayer with an EZAudioFile instance. This does not use the EZAudioFile by reference, but instead creates a separate EZAudioFile instance with the same file at the given file path provided by the internal NSURL to use for internal seeking so it doesn’t cause any locking between the caller’s instance of the EZAudioFile. - parameter: audioFile The instance of the EZAudioFile to use for initializing the AudioPlayer - returns: The newly created instance of the AudioPlayer

    Declaration

    Objective-C

    - (instancetype)initWithAudioFile:(EZAudioFile *)audioFile;

    Swift

    init!(audioFile: EZAudioFile!)

    Parameters

    audioFile

    The instance of the EZAudioFile to use for initializing the AudioPlayer

    Return Value

    The newly created instance of the AudioPlayer

  • Initializes the AudioPlayer with an EZAudioFile instance and provides a way to assign the AudioPlayerDelegate on instantiation. This does not use the EZAudioFile by reference, but instead creates a separate EZAudioFile instance with the same file at the given file path provided by the internal NSURL to use for internal seeking so it doesn’t cause any locking between the caller’s instance of the EZAudioFile. - parameter: audioFile The instance of the EZAudioFile to use for initializing the AudioPlayer - parameter: delegate The receiver that will act as the AudioPlayerDelegate. Set to nil if it should have no delegate or use the initWithAudioFile: function instead. - returns: The newly created instance of the AudioPlayer

    Declaration

    Objective-C

    - (instancetype)initWithAudioFile:(EZAudioFile *)audioFile
                         delegate:(id<AudioPlayerDelegate>)delegate;

    Swift

    init!(audioFile: EZAudioFile!, delegate: AudioPlayerDelegate!)

    Parameters

    audioFile

    The instance of the EZAudioFile to use for initializing the AudioPlayer
    delegate

    The receiver that will act as the AudioPlayerDelegate. Set to nil if it should have no delegate or use the initWithAudioFile: function instead.

    Return Value

    The newly created instance of the AudioPlayer

  • Initializes the AudioPlayer with an AudioPlayerDelegate. - parameter: delegate The receiver that will act as the AudioPlayerDelegate. Set to nil if it should have no delegate or use the initWithAudioFile: function instead. - returns: The newly created instance of the AudioPlayer

    Declaration

    Objective-C

    - (instancetype)initWithDelegate:(id<AudioPlayerDelegate>)delegate;

    Swift

    init!(delegate: AudioPlayerDelegate!)

    Parameters

    delegate

    The receiver that will act as the AudioPlayerDelegate. Set to nil if it should have no delegate or use the initWithAudioFile: function instead.

    Return Value

    The newly created instance of the AudioPlayer

  • Initializes the AudioPlayer with an NSURL instance representing the file path of the audio file. - parameter: url The NSURL instance representing the file path of the audio file. - returns: The newly created instance of the AudioPlayer

    Declaration

    Objective-C

    - (instancetype)initWithURL:(NSURL *)url;

    Swift

    init!(url: URL!)

    Parameters

    url

    The NSURL instance representing the file path of the audio file.

    Return Value

    The newly created instance of the AudioPlayer

  • Initializes the AudioPlayer with an NSURL instance representing the file path of the audio file and a caller to assign as the AudioPlayerDelegate on instantiation. - parameter: url The NSURL instance representing the file path of the audio file. - parameter: delegate The receiver that will act as the AudioPlayerDelegate. Set to nil if it should have no delegate or use the initWithAudioFile: function instead. - returns: The newly created instance of the AudioPlayer

    Declaration

    Objective-C

    - (instancetype)initWithURL:(NSURL *)url
                   delegate:(id<AudioPlayerDelegate>)delegate;

    Swift

    init!(url: URL!, delegate: AudioPlayerDelegate!)

    Parameters

    url

    The NSURL instance representing the file path of the audio file.
    delegate

    The receiver that will act as the AudioPlayerDelegate. Set to nil if it should have no delegate or use the initWithAudioFile: function instead.

    Return Value

    The newly created instance of the AudioPlayer

Class Initializers

  • Class initializer that creates a default EZAudioPlayer. - returns: The newly created instance of the EZAudioPlayer

    Declaration

    Objective-C

    + (instancetype)audioPlayer;

    Return Value

    The newly created instance of the EZAudioPlayer

  • Class initializer that creates the EZAudioPlayer with an EZAudioFile instance. This does not use the EZAudioFile by reference, but instead creates a separate EZAudioFile instance with the same file at the given file path provided by the internal NSURL to use for internal seeking so it doesn’t cause any locking between the caller’s instance of the EZAudioFile. - parameter: audioFile The instance of the EZAudioFile to use for initializing the EZAudioPlayer - returns: The newly created instance of the EZAudioPlayer

    Declaration

    Objective-C

    + (instancetype)audioPlayerWithAudioFile:(EZAudioFile *)audioFile;

    Parameters

    audioFile

    The instance of the EZAudioFile to use for initializing the EZAudioPlayer

    Return Value

    The newly created instance of the EZAudioPlayer

  • Class initializer that creates the EZAudioPlayer with an EZAudioFile instance and provides a way to assign the EZAudioPlayerDelegate on instantiation. This does not use the EZAudioFile by reference, but instead creates a separate EZAudioFile instance with the same file at the given file path provided by the internal NSURL to use for internal seeking so it doesn’t cause any locking between the caller’s instance of the EZAudioFile. - parameter: audioFile The instance of the EZAudioFile to use for initializing the EZAudioPlayer - parameter: delegate The receiver that will act as the EZAudioPlayerDelegate. Set to nil if it should have no delegate or use the audioPlayerWithAudioFile: function instead. - returns: The newly created instance of the EZAudioPlayer

    Declaration

    Objective-C

    + (instancetype)audioPlayerWithAudioFile:(EZAudioFile *)audioFile
                                delegate:(id<AudioPlayerDelegate>)delegate;

    Parameters

    audioFile

    The instance of the EZAudioFile to use for initializing the EZAudioPlayer
    delegate

    The receiver that will act as the EZAudioPlayerDelegate. Set to nil if it should have no delegate or use the audioPlayerWithAudioFile: function instead.

    Return Value

    The newly created instance of the EZAudioPlayer

  • Class initializer that creates a default EZAudioPlayer with an EZAudioPlayerDelegate.. - returns: The newly created instance of the EZAudioPlayer

    Declaration

    Objective-C

    + (instancetype)audioPlayerWithDelegate:(id<AudioPlayerDelegate>)delegate;

    Return Value

    The newly created instance of the EZAudioPlayer

  • Class initializer that creates the EZAudioPlayer with an NSURL instance representing the file path of the audio file. - parameter: url The NSURL instance representing the file path of the audio file. - returns: The newly created instance of the EZAudioPlayer

    Declaration

    Objective-C

    + (instancetype)audioPlayerWithURL:(NSURL *)url;

    Parameters

    url

    The NSURL instance representing the file path of the audio file.

    Return Value

    The newly created instance of the EZAudioPlayer

  • Class initializer that creates the EZAudioPlayer with an NSURL instance representing the file path of the audio file and a caller to assign as the EZAudioPlayerDelegate on instantiation. - parameter: url The NSURL instance representing the file path of the audio file. - parameter: delegate The receiver that will act as the EZAudioPlayerDelegate. Set to nil if it should have no delegate or use the audioPlayerWithURL: function instead. - returns: The newly created instance of the EZAudioPlayer

    Declaration

    Objective-C

    + (instancetype)audioPlayerWithURL:(NSURL *)url
                          delegate:(id<AudioPlayerDelegate>)delegate;

    Parameters

    url

    The NSURL instance representing the file path of the audio file.
    delegate

    The receiver that will act as the EZAudioPlayerDelegate. Set to nil if it should have no delegate or use the audioPlayerWithURL: function instead.

    Return Value

    The newly created instance of the EZAudioPlayer

Shared Instance

  • The shared instance (singleton) of the audio player. Most applications will only have one instance of the EZAudioPlayer that can be reused with multiple different audio files. * - returns: The shared instance of the EZAudioPlayer.

    Declaration

    Objective-C

    + (instancetype)sharedAudioPlayer;

    Swift

    class func shared() -> Self!

    Return Value

    The shared instance of the EZAudioPlayer.

Controlling Playback

  • Starts playback.

    Declaration

    Objective-C

    - (void)play;

    Swift

    func play()

  • Loads an EZAudioFile and immediately starts playing it. - parameter: audioFile An EZAudioFile to use for immediate playback.

    Declaration

    Objective-C

    - (void)playAudioFile:(EZAudioFile *)audioFile;

    Swift

    func playAudioFile(_ audioFile: EZAudioFile!)

    Parameters

    audioFile

    An EZAudioFile to use for immediate playback.

  • Pauses playback.

    Declaration

    Objective-C

    - (void)pause;

    Swift

    func pause()

  • Seeks playback to a specified frame within the internal EZAudioFile. This will notify the EZAudioFileDelegate (if specified) with the audioPlayer:updatedPosition:inAudioFile: function. - parameter: frame The new frame position to seek to as a SInt64.

    Declaration

    Objective-C

    - (void)seekToFrame:(SInt64)frame;

    Swift

    func seek(toFrame frame: Int64)

    Parameters

    frame

    The new frame position to seek to as a SInt64.

  • Seek to time position in milliseconds - parameter: timeInMS time in milliseconds

    Declaration

    Objective-C

    - (void)seekToTime:(Float64)timeInMS;

    Swift

    func seek(toTime timeInMS: Float64)

    Parameters

    timeInMS

    time in milliseconds