EZAudioPlayer

@interface EZAudioPlayer
    : NSObject <EZAudioFileDelegate, EZOutputDataSource, EZOutputDelegate>

The EZAudioPlayer provides an interface that combines the EZAudioFile and EZOutput to play local audio files. 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 EZAudioPlayer’s EZAudioPlayerDelegate on the EZAudioPlayer instance. Since 0.5.0 the EZAudioPlayer offers notifications over the usual delegate methods to allow multiple receivers to get the EZAudioPlayer’s state changes since one player will typically be used in one application. The EZAudioPlayerDelegate, the delegate, provides callbacks for high frequency methods that simply wrap the EZAudioFileDelegate and EZOutputDelegate callbacks for providing the audio buffer played as well as the position updating (you will typically have one scrub bar in an application).

Properties

  • The EZAudioPlayerDelegate that will handle the audio player callbacks

    Declaration

    Objective-C

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

    Swift

    weak var delegate: EZAudioPlayerDelegate! { 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 EZAudioPlayerState value representing the current internal playback and file state of the EZAudioPlayer instance.

    Declaration

    Objective-C

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

    Swift

    var state: EZAudioPlayerState { get }

Initializers

  • Initializes 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)initWithAudioFile:(EZAudioFile *)audioFile;

    Swift

    init!(audioFile: EZAudioFile!)

    Parameters

    audioFile

    The instance of the EZAudioFile to use for initializing the EZAudioPlayer

    Return Value

    The newly created instance of the EZAudioPlayer

  • Initializes 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 initWithAudioFile: function instead. - returns: The newly created instance of the EZAudioPlayer

    Declaration

    Objective-C

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

    Swift

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

    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 initWithAudioFile: function instead.

    Return Value

    The newly created instance of the EZAudioPlayer

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

    Declaration

    Objective-C

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

    Swift

    init!(delegate: EZAudioPlayerDelegate!)

    Parameters

    delegate

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

    Return Value

    The newly created instance of the EZAudioPlayer

  • Initializes 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)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 EZAudioPlayer

  • Initializes 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 initWithAudioFile: function instead. - returns: The newly created instance of the EZAudioPlayer

    Declaration

    Objective-C

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

    Swift

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

    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 initWithAudioFile: function instead.

    Return Value

    The newly created instance of the EZAudioPlayer

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<EZAudioPlayerDelegate>)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<EZAudioPlayerDelegate>)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<EZAudioPlayerDelegate>)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.

Properties

  • Provides the EZAudioFile instance that is being used as the datasource for playback. When set it creates a copy of the EZAudioFile provided for internal use. This does not use the EZAudioFile by reference, but instead creates a copy of the EZAudioFile instance provided.

    Declaration

    Objective-C

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

    Swift

    @NSCopying var audioFile: EZAudioFile! { 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, atomic) 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 EZAudioPlayer will become the output’s EZOutputDataSource and EZOutputDelegate. To listen for the EZOutput’s delegate methods your view should implement the EZAudioPlayerDelegate and set itself as the EZAudioPlayer’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 EZAudioPlayer is currently playing back any audio. - returns: A BOOL indicating whether or not the EZAudioPlayer 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 EZAudioPlayer 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 }

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.