EZMicrophone

@interface EZMicrophone : NSObject <EZOutputDataSource>

The EZMicrophone provides a component to get audio data from the default device microphone. On OSX this is the default selected input device in the system preferences while on iOS this defaults to use the default RemoteIO audio unit. The microphone data is converted to a float buffer array and returned back to the caller via the EZMicrophoneDelegate protocol.

  • The EZMicrophoneDelegate for which to handle the microphone callbacks

    Declaration

    Objective-C

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

    Swift

    weak var delegate: EZMicrophoneDelegate! { get set }

  • The EZAudioDevice being used to pull the microphone data. - On iOS this can be any of the available microphones on the iPhone/iPad devices (usually there are 3). Defaults to the first microphone found (bottom mic) - On OSX this can be any of the plugged in devices that Core Audio can detect (see kAudioUnitSubType_HALOutput for more information) System Preferences -> Sound for the available inputs)

    Declaration

    Objective-C

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

    Swift

    var device: EZAudioDevice! { get set }

  • A BOOL describing whether the microphone is on and passing back audio data to its delegate.

    Declaration

    Objective-C

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

    Swift

    var microphoneOn: Bool { get set }

  • An EZOutput to use for porting the microphone input out (passthrough).

    Declaration

    Objective-C

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

    Swift

    var output: EZOutput! { get set }

Initializers

  • Creates an instance of the EZMicrophone with a delegate to respond to the audioReceived callback. This will not start fetching the audio until startFetchingAudio has been called. Use initWithMicrophoneDelegate:startsImmediately: to instantiate this class and immediately start fetching audio data. - parameter: delegate A EZMicrophoneDelegate delegate that will receive the audioReceived callback. @return An instance of the EZMicrophone class. This should be strongly retained.

    Declaration

    Objective-C

    - (EZMicrophone *)initWithMicrophoneDelegate:(id<EZMicrophoneDelegate>)delegate;

    Swift

    init!(microphoneDelegate delegate: EZMicrophoneDelegate!)

    Parameters

    delegate

    A EZMicrophoneDelegate delegate that will receive the audioReceived callback.

    Return Value

    An instance of the EZMicrophone class. This should be strongly retained.

  • Creates an instance of the EZMicrophone with a custom AudioStreamBasicDescription and provides the caller to specify a delegate to respond to the audioReceived callback. This will not start fetching the audio until startFetchingAudio has been called. Use initWithMicrophoneDelegate:startsImmediately: to instantiate this class and immediately start fetching audio data. - parameter: microphoneDelegate A EZMicrophoneDelegate delegate that will receive the audioReceived callback. - parameter: audioStreamBasicDescription A custom AudioStreamBasicFormat for the microphone input. @return An instance of the EZMicrophone class. This should be strongly retained.

    Declaration

    Objective-C

    - (EZMicrophone *)initWithMicrophoneDelegate:(id<EZMicrophoneDelegate>)delegate
             withAudioStreamBasicDescription:
                 (AudioStreamBasicDescription)audioStreamBasicDescription;

    Swift

    init!(microphoneDelegate delegate: EZMicrophoneDelegate!, with audioStreamBasicDescription: AudioStreamBasicDescription)

    Parameters

    microphoneDelegate

    A EZMicrophoneDelegate delegate that will receive the audioReceived callback.
    audioStreamBasicDescription

    A custom AudioStreamBasicFormat for the microphone input.

    Return Value

    An instance of the EZMicrophone class. This should be strongly retained.

  • Creates an instance of the EZMicrophone with a delegate to respond to the audioReceived callback and allows the caller to specify whether they’d immediately like to start fetching the audio data. - parameter: delegate A EZMicrophoneDelegate delegate that will receive the audioReceived callback. - parameter: startsImmediately A boolean indicating whether to start fetching the data immediately. IF YES, the delegate’s audioReceived callback will immediately start getting called. @return An instance of the EZMicrophone class. This should be strongly retained.

    Declaration

    Objective-C

    - (EZMicrophone *)initWithMicrophoneDelegate:(id<EZMicrophoneDelegate>)delegate
                           startsImmediately:(BOOL)startsImmediately;

    Swift

    init!(microphoneDelegate delegate: EZMicrophoneDelegate!, startsImmediately: Bool)

    Parameters

    delegate

    A EZMicrophoneDelegate delegate that will receive the audioReceived callback.
    startsImmediately

    A boolean indicating whether to start fetching the data immediately. IF YES, the delegate’s audioReceived callback will immediately start getting called.

    Return Value

    An instance of the EZMicrophone class. This should be strongly retained.

  • Creates an instance of the EZMicrophone with a custom AudioStreamBasicDescription and provides the caller with a delegate to respond to the audioReceived callback and allows the caller to specify whether they’d immediately like to start fetching the audio data. - parameter: delegate A EZMicrophoneDelegate delegate that will receive the audioReceived callback. - parameter: audioStreamBasicDescription A custom AudioStreamBasicFormat for the microphone input. - parameter: startsImmediately A boolean indicating whether to start fetching the data immediately. IF YES, the delegate’s audioReceived callback will immediately start getting called. @return An instance of the EZMicrophone class. This should be strongly retained.

    Declaration

    Objective-C

    - (EZMicrophone *)initWithMicrophoneDelegate:(id<EZMicrophoneDelegate>)delegate
             withAudioStreamBasicDescription:
                 (AudioStreamBasicDescription)audioStreamBasicDescription
                           startsImmediately:(BOOL)startsImmediately;

    Swift

    init!(microphoneDelegate delegate: EZMicrophoneDelegate!, with audioStreamBasicDescription: AudioStreamBasicDescription, startsImmediately: Bool)

    Parameters

    delegate

    A EZMicrophoneDelegate delegate that will receive the audioReceived callback.
    audioStreamBasicDescription

    A custom AudioStreamBasicFormat for the microphone input.
    startsImmediately

    A boolean indicating whether to start fetching the data immediately. IF YES, the delegate’s audioReceived callback will immediately start getting called.

    Return Value

    An instance of the EZMicrophone class. This should be strongly retained.

Class Initializers

  • Creates an instance of the EZMicrophone with a delegate to respond to the audioReceived callback. This will not start fetching the audio until startFetchingAudio has been called. Use microphoneWithDelegate:startsImmediately: to instantiate this class and immediately start fetching audio data. - parameter: delegate A EZMicrophoneDelegate delegate that will receive the audioReceived callback. @return An instance of the EZMicrophone class. This should be declared as a strong property!

    Declaration

    Objective-C

    + (EZMicrophone *)microphoneWithDelegate:(id<EZMicrophoneDelegate>)delegate;

    Swift

    /*not inherited*/ init!(delegate: EZMicrophoneDelegate!)

    Parameters

    delegate

    A EZMicrophoneDelegate delegate that will receive the audioReceived callback.

    Return Value

    An instance of the EZMicrophone class. This should be declared as a strong property!

  • Creates an instance of the EZMicrophone with a delegate to respond to the audioReceived callback. This will not start fetching the audio until startFetchingAudio has been called. Use microphoneWithDelegate:startsImmediately: to instantiate this class and immediately start fetching audio data. - parameter: delegate A EZMicrophoneDelegate delegate that will receive the audioReceived callback. - parameter: audioStreamBasicDescription A custom AudioStreamBasicFormat for the microphone input. @return An instance of the EZMicrophone class. This should be declared as a strong property!

    Declaration

    Objective-C

    + (EZMicrophone *)microphoneWithDelegate:(id<EZMicrophoneDelegate>)delegate
         withAudioStreamBasicDescription:
             (AudioStreamBasicDescription)audioStreamBasicDescription;

    Swift

    /*not inherited*/ init!(delegate: EZMicrophoneDelegate!, with audioStreamBasicDescription: AudioStreamBasicDescription)

    Parameters

    delegate

    A EZMicrophoneDelegate delegate that will receive the audioReceived callback.
    audioStreamBasicDescription

    A custom AudioStreamBasicFormat for the microphone input.

    Return Value

    An instance of the EZMicrophone class. This should be declared as a strong property!

  • Creates an instance of the EZMicrophone with a delegate to respond to the audioReceived callback and allows the caller to specify whether they’d immediately like to start fetching the audio data.

    Declaration

    Objective-C

    + (EZMicrophone *)microphoneWithDelegate:(id<EZMicrophoneDelegate>)delegate
                       startsImmediately:(BOOL)startsImmediately;

    Swift

    /*not inherited*/ init!(delegate: EZMicrophoneDelegate!, startsImmediately: Bool)

    Parameters

    microphoneDelegate

    A EZMicrophoneDelegate delegate that will receive the audioReceived callback.
    startsImmediately

    A boolean indicating whether to start fetching the data immediately. IF YES, the delegate’s audioReceived callback will immediately start getting called.

    Return Value

    An instance of the EZMicrophone class. This should be strongly retained.

  • Creates an instance of the EZMicrophone with a delegate to respond to the audioReceived callback and allows the caller to specify whether they’d immediately like to start fetching the audio data.

    Declaration

    Objective-C

    + (EZMicrophone *)microphoneWithDelegate:(id<EZMicrophoneDelegate>)delegate
         withAudioStreamBasicDescription:
             (AudioStreamBasicDescription)audioStreamBasicDescription
                       startsImmediately:(BOOL)startsImmediately;

    Swift

    /*not inherited*/ init!(delegate: EZMicrophoneDelegate!, with audioStreamBasicDescription: AudioStreamBasicDescription, startsImmediately: Bool)

    Parameters

    microphoneDelegate

    A EZMicrophoneDelegate delegate that will receive the audioReceived callback.
    audioStreamBasicDescription

    A custom AudioStreamBasicFormat for the microphone input.
    startsImmediately

    A boolean indicating whether to start fetching the data immediately. IF YES, the delegate’s audioReceived callback will immediately start getting called.

    Return Value

    An instance of the EZMicrophone class. This should be strongly retained.

Shared Instance

  • A shared instance of the microphone component. Most applications will only need to use one instance of the microphone component across multiple views. Make sure to call the startFetchingAudio method to receive the audio data in the microphone delegate. - returns: A shared instance of the EZAudioMicrophone component.

    Declaration

    Objective-C

    + (EZMicrophone *)sharedMicrophone;

    Swift

    class func shared() -> EZMicrophone!

    Return Value

    A shared instance of the EZAudioMicrophone component.

Starting/Stopping The Microphone

  • Starts fetching audio from the default microphone. Will notify delegate with audioReceived callback.

    Declaration

    Objective-C

    - (void)startFetchingAudio;

    Swift

    func startFetchingAudio()

  • Stops fetching audio. Will stop notifying the delegate’s audioReceived callback.

    Declaration

    Objective-C

    - (void)stopFetchingAudio;

    Swift

    func stopFetchingAudio()

Getting The Microphone's Audio Format

  • Provides the AudioStreamBasicDescription structure containing the format of the microphone’s audio. - returns: An AudioStreamBasicDescription structure describing the format of the microphone’s audio.

    Declaration

    Objective-C

    - (AudioStreamBasicDescription)audioStreamBasicDescription;

    Swift

    func audioStreamBasicDescription() -> AudioStreamBasicDescription

    Return Value

    An AudioStreamBasicDescription structure describing the format of the microphone’s audio.

  • Provides the underlying Audio Unit that is being used to fetch the audio. - returns: The AudioUnit used for the microphone

    Declaration

    Objective-C

    - (AudioUnit *)audioUnit;

    Swift

    func audioUnit() -> UnsafeMutablePointer

    Return Value

    The AudioUnit used for the microphone

Customizing The Microphone Stream Format

  • Sets the AudioStreamBasicDescription on the microphone input. Must be linear PCM and must be the same sample rate as the stream format coming in (check the current audioStreamBasicDescription before setting). - warning: Do not set this while fetching audio (startFetchingAudio) - parameter: asbd The new AudioStreamBasicDescription to use in place of the current audio format description.

    Declaration

    Objective-C

    - (void)setAudioStreamBasicDescription:(AudioStreamBasicDescription)asbd;

    Swift

    func setAudioStreamBasicDescription(_ asbd: AudioStreamBasicDescription)

    Parameters

    asbd

    The new AudioStreamBasicDescription to use in place of the current audio format description.

Subclass

  • The default AudioStreamBasicDescription set as the stream format of the microphone if no custom description is set. Defaults to a non-interleaved float format with the number of channels specified by the numberOfChannels method. - returns: An AudioStreamBasicDescription that will be used as the default stream format.

    Declaration

    Objective-C

    - (AudioStreamBasicDescription)defaultStreamFormat;

    Swift

    func defaultStreamFormat() -> AudioStreamBasicDescription

    Return Value

    An AudioStreamBasicDescription that will be used as the default stream format.

  • The number of channels the input microphone is expected to have. Defaults to 1 (assumes microphone is mono). - returns: A UInt32 representing the number of channels expected for the microphone.

    Declaration

    Objective-C

    - (UInt32)numberOfChannels;

    Swift

    func numberOfChannels() -> UInt32

    Return Value

    A UInt32 representing the number of channels expected for the microphone.