Inherits from NSObject
Declared in EZOutput.h

Overview

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

Tasks

Initializers

Class Initializers

Shared Instance

Setting/Getting The Stream Formats

  •   inputFormat

    Provides the AudioStreamBasicDescription structure used at the beginning of the playback graph which is then converted into the clientFormat using the AUConverter audio unit.

    property
  •   clientFormat

    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.

    property

Setting/Getting The Data Source and Delegate

  •   dataSource

    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.

    property
  •   delegate

    The EZOutputDelegate for which to handle the output callbacks

    property
  •   isPlaying

    Provides a flag indicating whether the EZOutput is pulling audio data from the EZOutputDataSource for playback.

    property
  •   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).

    property
  •   volume

    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.

    property

Core Audio Properties

Getting/Setting The Output's Hardware Device

Starting/Stopping The Output

Subclass

Properties

clientFormat

@property (nonatomic, readwrite) AudioStreamBasicDescription clientFormat
Discussion

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.

Return Value

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

Declared In

EZOutput.h

converterAudioUnit

@property (readonly) AudioUnit converterAudioUnit
Discussion

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

Declared In

EZOutput.h

dataSource

@property (nonatomic, weak) id<EZOutputDataSource> dataSource
Discussion

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.

Declared In

EZOutput.h

delegate

@property (nonatomic, weak) id<EZOutputDelegate> delegate
Discussion

The EZOutputDelegate for which to handle the output callbacks

Declared In

EZOutput.h

device

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

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.

Declared In

EZOutput.h

graph

@property (readonly) AUGraph graph
Discussion

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

Declared In

EZOutput.h

inputFormat

@property (nonatomic, readwrite) AudioStreamBasicDescription inputFormat
Discussion

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.

Return Value

An AudioStreamBasicDescription structure describing

Declared In

EZOutput.h

isPlaying

@property (readonly) BOOL isPlaying
Discussion

Provides a flag indicating whether the EZOutput is pulling audio data from the EZOutputDataSource for playback.

Return Value

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

Declared In

EZOutput.h

mixerAudioUnit

@property (readonly) AudioUnit mixerAudioUnit
Discussion

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

Declared In

EZOutput.h

outputAudioUnit

@property (readonly) AudioUnit outputAudioUnit
Discussion

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

Declared In

EZOutput.h

pan

@property (nonatomic, assign) float pan
Discussion

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

Declared In

EZOutput.h

volume

@property (nonatomic, assign) float volume
Discussion

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.

Declared In

EZOutput.h

Class Methods

output

+ (instancetype)output
Discussion

Class method to create a new instance of the EZOutput

Return Value

A newly created instance of the EZOutput class.

Declared In

EZOutput.h

outputWithDataSource:

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

Class method to create a new instance of the EZOutput and allows the caller to specify an 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.

Declared In

EZOutput.h

outputWithDataSource:inputFormat:

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

Class method to create a new instance of the EZOutput and allows the caller to specify an EZOutputDataSource.

Warning: AudioStreamBasicDescriptions that are invalid will cause the EZOutput to fail to initialize

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.

Declared In

EZOutput.h

sharedOutput

+ (instancetype)sharedOutput
Discussion

Creates a shared instance of the EZOutput (one app will usually only need one output and share the role of the EZOutputDataSource).

Return Value

The shared instance of the EZOutput class.

Declared In

EZOutput.h

Instance Methods

connectOutputOfSourceNode:sourceNodeOutputBus:toDestinationNode:destinationNodeInputBus:inGraph:

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

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/.

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.

Declared In

EZOutput.h

defaultClientFormat

- (AudioStreamBasicDescription)defaultClientFormat
Discussion

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.

Return Value

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

Declared In

EZOutput.h

defaultInputFormat

- (AudioStreamBasicDescription)defaultInputFormat
Discussion

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.

Return Value

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

Declared In

EZOutput.h

initWithDataSource:

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

Creates a new instance of the EZOutput and allows the caller to specify an 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.

Declared In

EZOutput.h

initWithDataSource:inputFormat:

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

Creates a new instance of the EZOutput and allows the caller to specify an EZOutputDataSource.

Warning: AudioStreamBasicDescription input formats must be linear PCM!

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.

Declared In

EZOutput.h

outputAudioUnitSubType

- (OSType)outputAudioUnitSubType
Discussion

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.

Return Value

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

Declared In

EZOutput.h

startPlayback

- (void)startPlayback
Discussion

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

Declared In

EZOutput.h

stopPlayback

- (void)stopPlayback
Discussion

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

Declared In

EZOutput.h