EZOutput

@interface EZOutput : NSObject

The EZOutput component provides a generic output to glue all the other EZAudio components together and push whatever sound you’ve created to the default output device (think opposite of the microphone). The EZOutputDataSource provides the required AudioBufferList needed to populate the output buffer while the EZOutputDelegate provides the same kind of mechanism as the EZMicrophoneDelegate or EZAudioFileDelegate in that you will receive a callback that provides non-interleaved, float data for visualizing the output (done using an internal float converter). As of 0.4.0 the EZOutput has been simplified to a single EZOutputDataSource method and now uses an AUGraph to provide format conversion from the inputFormat to the playback graph’s clientFormat linear PCM formats, mixer controls for setting volume and pan settings, hooks to add in any number of effect audio units (see the connectOutputOfSourceNode:sourceNodeOutputBus:toDestinationNode:destinationNodeInputBus:inGraph: subclass method), and hardware device toggling (via EZAudioDevice).

Initializers

  • Creates a new instance of the EZOutput and allows the caller to specify an EZOutputDataSource. - parameter: dataSource The EZOutputDataSource that will be used to pull the audio data for the output callback. - returns: A newly created instance of the EZOutput class.

    Declaration

    Objective-C

    - (instancetype)initWithDataSource:(id<EZOutputDataSource>)dataSource;

    Swift

    init!(dataSource: EZOutputDataSource!)

    Parameters

    dataSource

    The EZOutputDataSource that will be used to pull the audio data for the output callback.

    Return Value

    A newly created instance of the EZOutput class.

  • Creates a new instance of the EZOutput and allows the caller to specify an EZOutputDataSource. - parameter: dataSource The EZOutputDataSource that will be used to pull the audio data for the output callback. - parameter: inputFormat The AudioStreamBasicDescription of the EZOutput. - warning: AudioStreamBasicDescription input formats must be linear PCM! - returns: A newly created instance of the EZOutput class.

    Declaration

    Objective-C

    - (instancetype)initWithDataSource:(id<EZOutputDataSource>)dataSource
                       inputFormat:(AudioStreamBasicDescription)inputFormat;

    Swift

    init!(dataSource: EZOutputDataSource!, inputFormat: AudioStreamBasicDescription)

    Parameters

    dataSource

    The EZOutputDataSource that will be used to pull the audio data for the output callback.
    inputFormat

    The AudioStreamBasicDescription of the EZOutput.

    Return Value

    A newly created instance of the EZOutput class.

Class Initializers

  • Class method to create a new instance of the EZOutput - returns: A newly created instance of the EZOutput class.

    Declaration

    Objective-C

    + (instancetype)output;

    Return Value

    A newly created instance of the EZOutput class.

  • Class method to create a new instance of the EZOutput and allows the caller to specify an EZOutputDataSource. - parameter: dataSource The EZOutputDataSource that will be used to pull the audio data for the output callback. - returns: A newly created instance of the EZOutput class.

    Declaration

    Objective-C

    + (instancetype)outputWithDataSource:(id<EZOutputDataSource>)dataSource;

    Parameters

    dataSource

    The EZOutputDataSource that will be used to pull the audio data for the output callback.

    Return Value

    A newly created instance of the EZOutput class.

  • Class method to create a new instance of the EZOutput and allows the caller to specify an EZOutputDataSource. - parameter: dataSource The EZOutputDataSource that will be used to pull the audio data for the output callback. - parameter: audioStreamBasicDescription The AudioStreamBasicDescription of the EZOutput. - warning: AudioStreamBasicDescriptions that are invalid will cause the EZOutput to fail to initialize - returns: A newly created instance of the EZOutput class.

    Declaration

    Objective-C

    + (instancetype)outputWithDataSource:(id<EZOutputDataSource>)dataSource
                         inputFormat:(AudioStreamBasicDescription)inputFormat;

    Parameters

    dataSource

    The EZOutputDataSource that will be used to pull the audio data for the output callback.
    audioStreamBasicDescription

    The AudioStreamBasicDescription of the EZOutput.

    Return Value

    A newly created instance of the EZOutput class.

Shared Instance

  • Creates a shared instance of the EZOutput (one app will usually only need one output and share the role of the EZOutputDataSource). - returns: The shared instance of the EZOutput class.

    Declaration

    Objective-C

    + (instancetype)sharedOutput;

    Swift

    class func shared() -> Self!

    Return Value

    The shared instance of the EZOutput class.

Setting/Getting The Stream Formats

  • Provides the AudioStreamBasicDescription structure used at the beginning of the playback graph which is then converted into the clientFormat using the AUConverter audio unit. - warning: The AudioStreamBasicDescription set here must be linear PCM. Compressed formats are not supported…the EZAudioFile’s clientFormat performs the audio conversion on the fly from compressed to linear PCM so there is no additional work to be done there. - returns: An AudioStreamBasicDescription structure describing

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) AudioStreamBasicDescription inputFormat;

    Swift

    var inputFormat: AudioStreamBasicDescription { get set }

    Return Value

    An AudioStreamBasicDescription structure describing

  • Provides the AudioStreamBasicDescription structure that serves as the common format used throughout the playback graph (similar to how the EZAudioFile as a clientFormat that is linear PCM to be shared amongst other components). The inputFormat is converted into this format at the beginning of the playback graph using an AUConverter audio unit. Defaults to the whatever the defaultClientFormat method returns is if a custom one isn’t explicitly set. - warning: The AudioStreamBasicDescription set here must be linear PCM. Compressed formats are not supported by Audio Units. - returns: An AudioStreamBasicDescription structure describing the common client format for the playback graph.

    Declaration

    Objective-C

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

    Swift

    var clientFormat: AudioStreamBasicDescription { get set }

    Return Value

    An AudioStreamBasicDescription structure describing the common client format for the playback graph.

Setting/Getting The Data Source and Delegate

  • The EZOutputDataSource that provides the audio data in the inputFormat for the EZOutput to play. If an EZOutputDataSource is not specified then the EZOutput will just output silence.

    Declaration

    Objective-C

    @property (readwrite, nonatomic) id<EZOutputDataSource> dataSource;

    Swift

    weak var dataSource: EZOutputDataSource! { get set }

  • The EZOutputDelegate for which to handle the output callbacks

    Declaration

    Objective-C

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

    Swift

    weak var delegate: EZOutputDelegate! { get set }

  • Provides a flag indicating whether the EZOutput is pulling audio data from the EZOutputDataSource for playback. - returns: YES if the EZOutput is running, NO if it is stopped

    Declaration

    Objective-C

    @property (readonly, atomic) BOOL isPlaying;

    Swift

    var isPlaying: Bool { get }

    Return Value

    YES if the EZOutput is running, NO if it is stopped

  • pan

    Provides the current pan from the audio player’s mixer audio unit in the playback graph. 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 current volume from the audio player’s mixer audio unit in the playback graph. 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 }

Core Audio Properties

  • The AUGraph used to chain together the converter, mixer, and output audio units.

    Declaration

    Objective-C

    @property (readonly, atomic) AUGraph graph;

    Swift

    var graph: AUGraph! { get }

  • The AudioUnit that is being used to convert the audio data coming into the output’s playback graph.

    Declaration

    Objective-C

    @property (readonly, atomic) AudioUnit converterAudioUnit;

    Swift

    var converterAudioUnit: AudioUnit! { get }

  • The AudioUnit that is being used as the mixer to adjust the volume on the output’s playback graph.

    Declaration

    Objective-C

    @property (readonly, atomic) AudioUnit mixerAudioUnit;

    Swift

    var mixerAudioUnit: AudioUnit! { get }

  • The AudioUnit that is being used as the hardware output for the output’s playback graph.

    Declaration

    Objective-C

    @property (readonly, atomic) AudioUnit outputAudioUnit;

    Swift

    var outputAudioUnit: AudioUnit! { get }

Getting/Setting The Output's Hardware Device

  • An EZAudioDevice instance that is used to route the audio data out to the speaker. To find a list of available output devices see the EZAudioDevice outputDevices method.

    Declaration

    Objective-C

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

    Swift

    var device: EZAudioDevice! { get set }

Starting/Stopping The Output

  • Starts pulling audio data from the EZOutputDataSource to the default device output.

    Declaration

    Objective-C

    - (void)startPlayback;

    Swift

    func startPlayback()

  • Stops pulling audio data from the EZOutputDataSource to the default device output.

    Declaration

    Objective-C

    - (void)stopPlayback;

    Swift

    func stopPlayback()

Subclass

  • This method handles connecting the converter node to the mixer node within the AUGraph that is being used as the playback graph. Subclasses can override this method and insert their custom nodes to perform effects processing on the audio data being rendered.

    This was inspired by Daniel Kennett’s blog post on how to add a custom equalizer to a CocoaLibSpotify SPCoreAudioController’s AUGraph. For more information see Daniel’s post and example code here: http://ikennd.ac/blog/2012/04/augraph-basics-in-cocoalibspotify/. - parameter: sourceNode An AUNode representing the node the audio data is coming from. - parameter: sourceNodeOutputBus A UInt32 representing the output bus from the source node that should be connected into the next node’s input bus. - parameter: destinationNode An AUNode representing the node the audio data should be connected to. - parameter: destinationNodeInputBus A UInt32 representing the input bus the source node’s output bus should be connecting to. - parameter: graph The AUGraph that is being used to hold the playback graph. Same as from the graph property. - returns: An OSStatus code. For no error return back noErr.

    Declaration

    Objective-C

    - (OSStatus)connectOutputOfSourceNode:(AUNode)sourceNode
                  sourceNodeOutputBus:(UInt32)sourceNodeOutputBus
                    toDestinationNode:(AUNode)destinationNode
              destinationNodeInputBus:(UInt32)destinationNodeInputBus
                              inGraph:(AUGraph)graph;

    Swift

    func connect(ofSourceNode sourceNode: AUNode, sourceNodeOutputBus: UInt32, toDestinationNode destinationNode: AUNode, destinationNodeInputBus: UInt32, in graph: AUGraph!) -> OSStatus

    Parameters

    sourceNode

    An AUNode representing the node the audio data is coming from.
    sourceNodeOutputBus

    A UInt32 representing the output bus from the source node that should be connected into the next node’s input bus.
    destinationNode

    An AUNode representing the node the audio data should be connected to.
    destinationNodeInputBus

    A UInt32 representing the input bus the source node’s output bus should be connecting to.
    graph

    The AUGraph that is being used to hold the playback graph. Same as from the graph property.

    Return Value

    An OSStatus code. For no error return back noErr.

  • The default AudioStreamBasicDescription set as the client format of the output if no custom clientFormat is set. Defaults to a 44.1 kHz stereo, non-interleaved, float format. - returns: An AudioStreamBasicDescription that will be used as the default stream format.

    Declaration

    Objective-C

    - (AudioStreamBasicDescription)defaultClientFormat;

    Swift

    func defaultClientFormat() -> AudioStreamBasicDescription

    Return Value

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

  • The default AudioStreamBasicDescription set as the inputFormat of the output if no custom inputFormat is set. Defaults to a 44.1 kHz stereo, non-interleaved, float format. - returns: An AudioStreamBasicDescription that will be used as the default stream format.

    Declaration

    Objective-C

    - (AudioStreamBasicDescription)defaultInputFormat;

    Swift

    func defaultInputFormat() -> AudioStreamBasicDescription

    Return Value

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

  • The default value used as the AudioUnit subtype when creating the hardware output component. By default this is kAudioUnitSubType_RemoteIO for iOS and kAudioUnitSubType_HALOutput for OSX. - warning: If you change this to anything other than kAudioUnitSubType_HALOutput for OSX you will get a failed assertion because devices can only be set when using the HAL audio unit. - returns: An OSType that represents the AudioUnit subtype for the hardware output component.

    Declaration

    Objective-C

    - (OSType)outputAudioUnitSubType;

    Swift

    func outputAudioUnitSubType() -> OSType

    Return Value

    An OSType that represents the AudioUnit subtype for the hardware output component.