EZAudioFile

@interface EZAudioFile : NSObject <NSCopying>

The EZAudioFile provides a lightweight and intuitive way to asynchronously interact with audio files. These interactions included reading audio data, seeking within an audio file, getting information about the file, and pulling the waveform data for visualizing the contents of the audio file. The EZAudioFileDelegate provides event callbacks for when reads, seeks, and various updates happen within the audio file to allow the caller to interact with the action in meaningful ways. Common use cases here could be to read the audio file’s data as AudioBufferList structures for output (see EZOutput) and visualizing the audio file’s data as a float array using an audio plot (see EZAudioPlot).

Properties

  • A EZAudioFileDelegate for the audio file that is used to return events such as new seek positions within the file and the read audio data as a float array.

    Declaration

    Objective-C

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

    Swift

    weak var delegate: EZAudioFileDelegate! { get set }

Initialization

  • Creates a new instance of the EZAudioFile using a file path URL. - parameter: url The file path reference of the audio file as an NSURL. - returns: The newly created EZAudioFile instance. nil if the file path does not exist.

    Declaration

    Objective-C

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

    Swift

    init!(url: URL!)

    Parameters

    url

    The file path reference of the audio file as an NSURL.

    Return Value

    The newly created EZAudioFile instance. nil if the file path does not exist.

  • Creates a new instance of the EZAudioFile using a file path URL with a delegate conforming to the EZAudioFileDelegate protocol. - parameter: delegate The audio file delegate that receives events specified by the EZAudioFileDelegate protocol - parameter: url The file path reference of the audio file as an NSURL. - returns: The newly created EZAudioFile instance.

    Declaration

    Objective-C

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

    Swift

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

    Parameters

    delegate

    The audio file delegate that receives events specified by the EZAudioFileDelegate protocol
    url

    The file path reference of the audio file as an NSURL.

    Return Value

    The newly created EZAudioFile instance.

  • Creates a new instance of the EZAudioFile using a file path URL with a delegate conforming to the EZAudioFileDelegate protocol and a client format. - parameter: url The file path reference of the audio file as an NSURL. - parameter: delegate The audio file delegate that receives events specified by the EZAudioFileDelegate protocol - parameter: clientFormat An AudioStreamBasicDescription that will be used as the client format on the audio file. For instance, the audio file might be in a 22.5 kHz sample rate format in its file format, but your app wants to read the samples at a sample rate of 44.1 kHz so it can iterate with other components (like a audio processing graph) without any weird playback effects. If this initializer is not used then a non-interleaved float format will be assumed. - returns: The newly created EZAudioFile instance.

    Declaration

    Objective-C

    - (instancetype)initWithURL:(NSURL *)url
                   delegate:(id<EZAudioFileDelegate>)delegate
               clientFormat:(AudioStreamBasicDescription)clientFormat;

    Swift

    init!(url: URL!, delegate: EZAudioFileDelegate!, clientFormat: AudioStreamBasicDescription)

    Parameters

    url

    The file path reference of the audio file as an NSURL.
    delegate

    The audio file delegate that receives events specified by the EZAudioFileDelegate protocol
    clientFormat

    An AudioStreamBasicDescription that will be used as the client format on the audio file. For instance, the audio file might be in a 22.5 kHz sample rate format in its file format, but your app wants to read the samples at a sample rate of 44.1 kHz so it can iterate with other components (like a audio processing graph) without any weird playback effects. If this initializer is not used then a non-interleaved float format will be assumed.

    Return Value

    The newly created EZAudioFile instance.

Class Initializers

  • Class method that creates a new instance of the EZAudioFile using a file path URL. - parameter: url The file path reference of the audio file as an NSURL. - returns: The newly created EZAudioFile instance.

    Declaration

    Objective-C

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

    Parameters

    url

    The file path reference of the audio file as an NSURL.

    Return Value

    The newly created EZAudioFile instance.

  • Class method that creates a new instance of the EZAudioFile using a file path URL with a delegate conforming to the EZAudioFileDelegate protocol. - parameter: url The file path reference of the audio file as an NSURL. - parameter: delegate The audio file delegate that receives events specified by the EZAudioFileDelegate protocol - returns: The newly created EZAudioFile instance.

    Declaration

    Objective-C

    + (instancetype)audioFileWithURL:(NSURL *)url
                        delegate:(id<EZAudioFileDelegate>)delegate;

    Parameters

    url

    The file path reference of the audio file as an NSURL.
    delegate

    The audio file delegate that receives events specified by the EZAudioFileDelegate protocol

    Return Value

    The newly created EZAudioFile instance.

  • Class method that creates a new instance of the EZAudioFile using a file path URL with a delegate conforming to the EZAudioFileDelegate protocol and a client format. - parameter: url The file path reference of the audio file as an NSURL. - parameter: delegate The audio file delegate that receives events specified by the EZAudioFileDelegate protocol - parameter: clientFormat An AudioStreamBasicDescription that will be used as the client format on the audio file. For instance, the audio file might be in a 22.5 kHz sample rate, interleaved MP3 file format, but your app wants to read linear PCM samples at a sample rate of 44.1 kHz so it can be read in the context of other components sharing a common stream format (like a audio processing graph). If this initializer is not used then the defaultClientFormat will be used as teh default value for the client format. - returns: The newly created EZAudioFile instance.

    Declaration

    Objective-C

    + (instancetype)audioFileWithURL:(NSURL *)url
                        delegate:(id<EZAudioFileDelegate>)delegate
                    clientFormat:(AudioStreamBasicDescription)clientFormat;

    Parameters

    url

    The file path reference of the audio file as an NSURL.
    delegate

    The audio file delegate that receives events specified by the EZAudioFileDelegate protocol
    clientFormat

    An AudioStreamBasicDescription that will be used as the client format on the audio file. For instance, the audio file might be in a 22.5 kHz sample rate, interleaved MP3 file format, but your app wants to read linear PCM samples at a sample rate of 44.1 kHz so it can be read in the context of other components sharing a common stream format (like a audio processing graph). If this initializer is not used then the defaultClientFormat will be used as teh default value for the client format.

    Return Value

    The newly created EZAudioFile instance.

Class Methods

  • A class method that subclasses can override to specify the default client format that will be used to read audio data from this file. A client format is different from the file format in that it is the format of the other components interacting with this file. For instance, the file on disk could be a 22.5 kHz, float format, but we might have an audio processing graph that has a 44.1 kHz, signed integer format that we’d like to interact with. The client format lets us set that 44.1 kHz format on the audio file to properly read samples from it with any interpolation or format conversion that must take place done automatically within the EZAudioFile readFrames:audioBufferList:bufferSize:eof: method. Default is stereo, non-interleaved, 44.1 kHz. - returns: An AudioStreamBasicDescription that serves as the audio file’s client format.

    Declaration

    Objective-C

    + (AudioStreamBasicDescription)defaultClientFormat;

    Swift

    class func defaultClientFormat() -> AudioStreamBasicDescription

    Return Value

    An AudioStreamBasicDescription that serves as the audio file’s client format.

  • A class method that subclasses can override to specify the default sample rate that will be used in the defaultClientFormat method. Default is 44100.0 (44.1 kHz). - returns: A Float64 representing the sample rate that should be used in the default client format.

    Declaration

    Objective-C

    + (Float64)defaultClientFormatSampleRate;

    Swift

    class func defaultClientFormatSampleRate() -> Float64

    Return Value

    A Float64 representing the sample rate that should be used in the default client format.

  • Provides an array of the supported audio files types. Each audio file type is provided as a string, i.e. @caf. Useful for filtering lists of files in an open panel to only the types allowed. - returns: An array of NSString objects representing the represented file types.

    Declaration

    Objective-C

    + (NSArray *)supportedAudioFileTypes;

    Swift

    class func supportedAudioFileTypes() -> [Any]!

    Return Value

    An array of NSString objects representing the represented file types.

Reading From The Audio File

  • Reads a specified number of frames from the audio file. In addition, this will notify the EZAudioFileDelegate (if specified) of the read data as a float array with the audioFile:readAudio:withBufferSize:withNumberOfChannels: event and the new seek position within the file with the audioFile:updatedPosition: event. - parameter: frames The number of frames to read from the file. - parameter: audioBufferList An allocated AudioBufferList structure in which to store the read audio data - parameter: bufferSize A pointer to a UInt32 in which to store the read buffersize - parameter: eof A pointer to a BOOL in which to store whether the read operation reached the end of the audio file.

    Declaration

    Objective-C

    - (void)readFrames:(UInt32)frames
    audioBufferList:(AudioBufferList *)audioBufferList
         bufferSize:(UInt32 *)bufferSize
                eof:(BOOL *)eof;

    Swift

    func readFrames(_ frames: UInt32, audioBufferList: UnsafeMutablePointer

    Parameters

    frames

    The number of frames to read from the file.
    audioBufferList

    An allocated AudioBufferList structure in which to store the read audio data
    bufferSize

    A pointer to a UInt32 in which to store the read buffersize
    eof

    A pointer to a BOOL in which to store whether the read operation reached the end of the audio file.

Seeking Through The Audio File

  • Seeks through an audio file to a specified frame. This will notify the EZAudioFileDelegate (if specified) with the audioFile:updatedPosition: 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.

  • Undocumented

    Declaration

    Objective-C

    @interface EZAudioFile : NSObject <NSCopying>

Getting Information About The Audio File

  • Provides the common AudioStreamBasicDescription that will be used for in-app interaction. The file’s format will be converted to this format and then sent back as either a float array or a AudioBufferList pointer. For instance, the file on disk could be a 22.5 kHz, float format, but we might have an audio processing graph that has a 44.1 kHz, signed integer format that we’d like to interact with. The client format lets us set that 44.1 kHz format on the audio file to properly read samples from it with any interpolation or format conversion that must take place done automatically within the EZAudioFile readFrames:audioBufferList:bufferSize:eof: method. Default is stereo, non-interleaved, 44.1 kHz. - warning: This must be a linear PCM format! - returns: An AudioStreamBasicDescription structure describing the format of the audio file.

    Declaration

    Objective-C

    @property (assign, readwrite, atomic) AudioStreamBasicDescription clientFormat;

    Swift

    var clientFormat: AudioStreamBasicDescription { get set }

    Return Value

    An AudioStreamBasicDescription structure describing the format of the audio file.

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

  • Provides the duration of the audio file in seconds.

    Declaration

    Objective-C

    @property (readonly, atomic) NSTimeInterval duration;

    Swift

    var duration: TimeInterval { get }

  • Provides the AudioStreamBasicDescription structure containing the format of the file. - returns: An AudioStreamBasicDescription structure describing the format of the audio file.

    Declaration

    Objective-C

    @property (readonly, atomic) AudioStreamBasicDescription fileFormat;

    Swift

    var fileFormat: AudioStreamBasicDescription { get }

    Return Value

    An AudioStreamBasicDescription structure describing the format of the audio file.

  • 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 frame index (a.k.a the seek positon) within the audio file as SInt64. This can be helpful when seeking through the audio file. - returns: The current frame index within the audio file as a SInt64.

    Declaration

    Objective-C

    @property (readonly, atomic) SInt64 frameIndex;

    Swift

    var frameIndex: Int64 { get }

    Return Value

    The current frame index within the audio file as a SInt64.

  • Provides a dictionary containing the metadata (ID3) tags that are included in the header for the audio file. Typically this contains stuff like artist, title, release year, etc. - returns: An NSDictionary containing the metadata for the audio file.

    Declaration

    Objective-C

    @property (readonly, atomic) NSDictionary *metadata;

    Swift

    var metadata: [AnyHashable : Any]! { get }

    Return Value

    An NSDictionary containing the metadata for the audio file.

  • Provides the total duration of the audio file in seconds. @deprecated This property is deprecated starting in version 0.3.0. - note: Please use duration property instead. - returns: The total duration of the audio file as a Float32.

    Declaration

    Objective-C

    @property (readonly, atomic) NSTimeInterval totalDuration;

    Swift

    var totalDuration: TimeInterval { get }

    Return Value

    The total duration of the audio file as a Float32.

  • Provides the total frame count of the audio file in the client format. - returns: The total number of frames in the audio file in the AudioStreamBasicDescription representing the client format as a SInt64.

    Declaration

    Objective-C

    @property (readonly, atomic) SInt64 totalClientFrames;

    Swift

    var totalClientFrames: Int64 { get }

    Return Value

    The total number of frames in the audio file in the AudioStreamBasicDescription representing the client format as a SInt64.

  • Provides the total frame count of the audio file in the file format. - returns: The total number of frames in the audio file in the AudioStreamBasicDescription representing the file format as a SInt64.

    Declaration

    Objective-C

    @property (readonly, atomic) SInt64 totalFrames;

    Swift

    var totalFrames: Int64 { get }

    Return Value

    The total number of frames in the audio file in the AudioStreamBasicDescription representing the file format as a SInt64.

  • url

    Provides the NSURL for the audio file. - returns: An NSURL representing the path of the EZAudioFile instance.

    Declaration

    Objective-C

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

    Swift

    var url: URL! { get }

    Return Value

    An NSURL representing the path of the EZAudioFile instance.

Helpers

  • Synchronously pulls the waveform amplitude data into a float array for the receiver. This returns a waveform with a default resolution of 1024, meaning there are 1024 data points to plot the waveform. - parameter: numberOfPoints A UInt32 representing the number of data points you need. The higher the number of points the more detailed the waveform will be. - returns: A EZAudioFloatData instance containing the audio data for all channels of the audio.

    Declaration

    Objective-C

    - (EZAudioFloatData *)getWaveformData;

    Swift

    func getWaveformData() -> EZAudioFloatData!

    Parameters

    numberOfPoints

    A UInt32 representing the number of data points you need. The higher the number of points the more detailed the waveform will be.

    Return Value

    A EZAudioFloatData instance containing the audio data for all channels of the audio.

  • Synchronously pulls the waveform amplitude data into a float array for the receiver. - parameter: numberOfPoints A UInt32 representing the number of data points you need. The higher the number of points the more detailed the waveform will be. - returns: A EZAudioFloatData instance containing the audio data for all channels of the audio.

    Declaration

    Objective-C

    - (EZAudioFloatData *)getWaveformDataWithNumberOfPoints:(UInt32)numberOfPoints;

    Swift

    func getWaveformData(withNumberOfPoints numberOfPoints: UInt32) -> EZAudioFloatData!

    Parameters

    numberOfPoints

    A UInt32 representing the number of data points you need. The higher the number of points the more detailed the waveform will be.

    Return Value

    A EZAudioFloatData instance containing the audio data for all channels of the audio.

  • Asynchronously pulls the waveform amplitude data into a float array for the receiver. This returns a waveform with a default resolution of 1024, meaning there are 1024 data points to plot the waveform. - parameter: completion A EZAudioWaveformDataCompletionBlock that executes when the waveform data has been extracted. Provides a EZAudioFloatData instance containing the waveform data for all audio channels.

    Declaration

    Objective-C

    - (void)getWaveformDataWithCompletionBlock:
    (EZAudioWaveformDataCompletionBlock)completion;

    Swift

    func getWaveformData(completionBlock completion: EZAudioWaveformDataCompletionBlock!)

    Parameters

    completion

    A EZAudioWaveformDataCompletionBlock that executes when the waveform data has been extracted. Provides a EZAudioFloatData instance containing the waveform data for all audio channels.

  • Asynchronously pulls the waveform amplitude data into a float array for the receiver. - parameter: numberOfPoints A UInt32 representing the number of data points you need. The higher the number of points the more detailed the waveform will be. - parameter: completion A EZAudioWaveformDataCompletionBlock that executes when the waveform data has been extracted. Provides a EZAudioFloatData instance containing the waveform data for all audio channels.

    Declaration

    Objective-C

    - (void)getWaveformDataWithNumberOfPoints:(UInt32)numberOfPoints
                               completion:(EZAudioWaveformDataCompletionBlock)
                                              completion;

    Swift

    func getWaveformData(withNumberOfPoints numberOfPoints: UInt32, completion: EZAudioWaveformDataCompletionBlock!)

    Parameters

    numberOfPoints

    A UInt32 representing the number of data points you need. The higher the number of points the more detailed the waveform will be.
    completion

    A EZAudioWaveformDataCompletionBlock that executes when the waveform data has been extracted. Provides a EZAudioFloatData instance containing the waveform data for all audio channels.