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
-
+ output
Class 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
-
+ sharedOutput
Creates 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
-
inputFormat
Provides the AudioStreamBasicDescription structure used at the beginning of the playback graph which is then converted into the
propertyclientFormat
using the AUConverter audio unit. -
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
propertyinputFormat
is converted into this format at the beginning of the playback graph using an AUConverter audio unit. Defaults to the whatever thedefaultClientFormat
method returns is if a custom one isn’t explicitly set.
Setting/Getting The Data Source and Delegate
-
dataSource
The EZOutputDataSource that provides the audio data in the
propertyinputFormat
for the EZOutput to play. If an EZOutputDataSource is not specified then the EZOutput will just output silence. -
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
-
graph
The AUGraph used to chain together the converter, mixer, and output audio units.
property -
converterAudioUnit
The AudioUnit that is being used to convert the audio data coming into the output’s playback graph.
property -
mixerAudioUnit
The AudioUnit that is being used as the mixer to adjust the volume on the output’s playback graph.
property -
outputAudioUnit
The AudioUnit that is being used as the hardware output for the output’s playback graph.
property
Getting/Setting The Output's Hardware Device
-
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
propertyoutputDevices
method.
Starting/Stopping The Output
-
– startPlayback
Starts pulling audio data from the EZOutputDataSource to the default device output.
-
– stopPlayback
Stops 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.
-
– defaultClientFormat
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. -
– defaultInputFormat
The default AudioStreamBasicDescription set as the
inputFormat
of the output if no custominputFormat
is set. Defaults to a 44.1 kHz stereo, non-interleaved, float format. -
– outputAudioUnitSubType
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.
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
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
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.
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