EZOutput Class Reference 
| 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
-
– initWithDataSource:Creates a new instance of the EZOutput and allows the caller to specify an EZOutputDataSource.
-
– initWithDataSource:inputFormat:Creates a new instance of the EZOutput and allows the caller to specify an EZOutputDataSource.
Class Initializers
-
+ outputClass method to create a new instance of the EZOutput
-
+ outputWithDataSource:Class method to create a new instance of the EZOutput and allows the caller to specify an EZOutputDataSource.
-
+ outputWithDataSource:inputFormat:Class method to create a new instance of the EZOutput and allows the caller to specify an EZOutputDataSource.
Shared Instance
-
+ sharedOutputCreates a shared instance of the EZOutput (one app will usually only need one output and share the role of the EZOutputDataSource).
Setting/Getting The Stream Formats
-
inputFormatProvides the AudioStreamBasicDescription structure used at the beginning of the playback graph which is then converted into the
propertyclientFormatusing the AUConverter audio unit. -
clientFormatProvides 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
propertyinputFormatis converted into this format at the beginning of the playback graph using an AUConverter audio unit. Defaults to the whatever thedefaultClientFormatmethod returns is if a custom one isn’t explicitly set.
Setting/Getting The Data Source and Delegate
-
dataSourceThe EZOutputDataSource that provides the audio data in the
propertyinputFormatfor the EZOutput to play. If an EZOutputDataSource is not specified then the EZOutput will just output silence. -
delegateThe EZOutputDelegate for which to handle the output callbacks
property -
isPlayingProvides a flag indicating whether the EZOutput is pulling audio data from the EZOutputDataSource for playback.
property -
panProvides 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 -
volumeProvides 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
-
graphThe AUGraph used to chain together the converter, mixer, and output audio units.
property -
converterAudioUnitThe AudioUnit that is being used to convert the audio data coming into the output’s playback graph.
property -
mixerAudioUnitThe AudioUnit that is being used as the mixer to adjust the volume on the output’s playback graph.
property -
outputAudioUnitThe AudioUnit that is being used as the hardware output for the output’s playback graph.
property
Getting/Setting The Output's Hardware Device
-
deviceAn 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
propertyoutputDevicesmethod.
Starting/Stopping The Output
-
– startPlaybackStarts pulling audio data from the EZOutputDataSource to the default device output.
-
– stopPlaybackStops pulling audio data from the EZOutputDataSource to the default device output.
Subclass
-
– connectOutputOfSourceNode:sourceNodeOutputBus:toDestinationNode:destinationNodeInputBus:inGraph: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.
-
– defaultClientFormatThe default AudioStreamBasicDescription set as the client format of the output if no custom
clientFormatis set. Defaults to a 44.1 kHz stereo, non-interleaved, float format. -
– defaultInputFormatThe default AudioStreamBasicDescription set as the
inputFormatof the output if no custominputFormatis set. Defaults to a 44.1 kHz stereo, non-interleaved, float format. -
– outputAudioUnitSubTypeThe 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.
Properties
clientFormat 
@property (nonatomic, readwrite) AudioStreamBasicDescription clientFormatDiscussion
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 converterAudioUnitDiscussion
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> dataSourceDiscussion
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> delegateDiscussion
The EZOutputDelegate for which to handle the output callbacks
Declared In
EZOutput.h
device
@property (nonatomic, strong, readwrite) EZAudioDevice *deviceDiscussion
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 graphDiscussion
The AUGraph used to chain together the converter, mixer, and output audio units.
Declared In
EZOutput.h
inputFormat
@property (nonatomic, readwrite) AudioStreamBasicDescription inputFormatDiscussion
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 isPlayingDiscussion
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 mixerAudioUnitDiscussion
The AudioUnit that is being used as the mixer to adjust the volume on the output’s playback graph.
Declared In
EZOutput.h
pan
@property (nonatomic, assign) float panDiscussion
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
Class Methods
output
+ (instancetype)outputDiscussion
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>)dataSourceDiscussion
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)inputFormatDiscussion
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)sharedOutputDiscussion
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)graphDiscussion
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.
Return Value
An OSStatus code. For no error return back noErr.
Declared In
EZOutput.h
defaultClientFormat
- (AudioStreamBasicDescription)defaultClientFormatDiscussion
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)defaultInputFormatDiscussion
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>)dataSourceDiscussion
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)inputFormatDiscussion
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)outputAudioUnitSubTypeDiscussion
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)startPlaybackDiscussion
Starts pulling audio data from the EZOutputDataSource to the default device output.
Declared In
EZOutput.h
stopPlayback
- (void)stopPlaybackDiscussion
Stops pulling audio data from the EZOutputDataSource to the default device output.
Declared In
EZOutput.h