ABAudioReceiverPort Class Reference

Receiver port. More...

#import <ABAudioReceiverPort.h>

Inherits ABPort, and <ABLocalPort>.

Instance Methods

(id) - initWithName:title:
 Initialize.
 
(void) - ABAudioReceiverPortReceive
 Receive audio.
 
(void) - ABAudioReceiverPortEndReceiveTimeInterval
 When receiving separate streams, mark the end of the current time interval.
 
(void) - ABAudioReceiverPortReceiveAQ
 Audio Queue version of ABAudioReceiverPortReceive.
 
(BOOL) - ABAudioReceiverPortIsConnected
 Determine if the receiver port is currently connected to any sources.
 
(BOOL) - ABAudioReceiverPortIsConnectedToSelf
 Whether the port is connected to another port from the same app.
 
(void) - setVolume:forSourcePort:
 Set the volume level for a particular source.
 
(float) - volumeForSourcePort:
 Get the volume level for a source.
 
(void) - setPan:forSourcePort:
 Set the pan for a particular source.
 
(float) - panForSourcePort:
 Get the pan level for a source.
 
(AudioUnit) - audioUnitForSourcePort:
 Get access to the Inter-App Audio audio unit for a particular source.
 
- Instance Methods inherited from ABPort
(void) - launch
 Launches the app belonging to the port and triggers ABPortWillLaunchPortNotification in the appropriate app.
 

Properties

NSArray * sources
 Currently-connected sources.
 
BOOL connected
 Whether the port is connected (via IAA or Audiobus)
 
BOOL interAppAudioConnected
 Whether the port is connected via Inter-App Audio.
 
BOOL audiobusConnected
 Whether the port is connected via Audiobus.
 
BOOL receiveMixedAudio
 Whether to receive audio as a mixed stream.
 
AudioStreamBasicDescription clientFormat
 Client format.
 
NSString * title
 The title of the port, for display to the user.
 
UIImage * icon
 The port icon (a 32x32 image)
 
BOOL automaticMonitoring
 Whether the port should perform monitoring itself.
 
BOOL connectedToSelf
 Whether the port is connected to another port from the same app.
 
NSTimeInterval latency
 The current latency.
 
NSString * sourcesTitle
 A title representing the sources connected to the port.
 
UIImage * sourcesIcon
 An icon representing the sources connected to the port.
 
- Properties inherited from ABPort
ABPeerpeer
 The peer this port is on.
 
NSString * name
 The internal port name.
 
NSString * title
 The title of the port, for display to the user.
 
UIImage * icon
 The port icon (a 64x64 image)
 
ABPortType type
 The type of the port.
 
uint8_t attributes
 The attributes of this port.
 
id context
 Use this property to associate some user defined context with the port.
 
uint32_t uniqueIdentifier
 An port identifier that is unique for the peer itself but also for other peers.
 
BOOL connected
 Whether the port is connected.
 
NSString * sourcesTitle
 A title representing the sources connected to the port.
 
UIImage * sourcesIcon
 An icon representing the sources connected to the port.
 
NSArray * sourcesRecursive
 Returns direct and indirect sources of the port in the pipeline.
 
NSString * destinationsTitle
 A title representing the destinations the port is connected to.
 
UIImage * destinationsIcon
 An icon representing the destinations the port is connected to.
 
NSArray * destinationsRecursive
 Returns direct and indirect destinations of the port in the pipeline.
 
NSArray * audioPipelineIDs
 Returns a list of id<NSCopying>.
 
NSArray * MIDIPipelineIDs
 Like audioPipelineIDs.
 

Detailed Description

Receiver port.

This class is used to receive audio sent by other Audiobus-compatible apps.

See the integration guide's section on using the Receiver Port, and the Receiver Port section in the documentation for details.

Method Documentation

- (id) initWithName: (NSString *)  name
title: (NSString *)  title 

Initialize.

Initializes a new receiver port

Parameters
nameName of port, for internal use
titleTitle of port, show to the user
- (void) ABAudioReceiverPortReceive (ABAudioReceiverPort *)  receiverPort
(ABPort *)  sourcePortOrNil
(AudioBufferList *)  audio
(UInt32)  lengthInFrames
(AudioTimeStamp *)  ioTimestamp 

Receive audio.

Use this C function to receive audio from Audiobus. It's suitable for use from within a realtime Core Audio context.

Just as with AudioUnitRender, it's important to continually call ABAudioReceiverPortReceive once ABAudioReceiverPortIsConnected returns YES, even if you're not currently using the returned audio. If you don't do this, your app will not work correctly.

Please note that if you are receiving separate streams (receiveMixedAudio is NO), then this function will provide synchronized streams for each connected source port. The following procedures must be followed:

  • All calls to ABAudioReceiverPortReceive must be performed on the same thread.
  • You must call ABAudioReceiverPortEndReceiveTimeInterval at the end of each time interval (such as for each render of your audio system, or each input notification), to tell Audiobus that you are finished with all audio for that interval. Audio for any sources that you did not receive audio for will be discarded.
Parameters
receiverPortThe receiver port.
sourcePortOrNilIf you are receiving separate streams (receiveMixedAudio is NO), this must be a valid source port - one of the ports from the sources array. Otherwise, if you are receiving a mixed stream, pass nil.
audioThe audio buffer list to receive audio into, in the format specified by clientFormat. Must not be NULL. If 'mData' pointers are NULL, then an internal buffer will be provided.
lengthInFramesThe number of frames requested. This method will never return less than the requested frames.
ioTimestampOn input, the current audio timestamp. On output, the timestamp of the returned audio (may differ due to latency).
- (void) ABAudioReceiverPortEndReceiveTimeInterval (ABAudioReceiverPort *)  receiverPort

When receiving separate streams, mark the end of the current time interval.

When you are receiving separate streams (receiveMixedAudio is NO), this function must be called at the end of each time interval to signal to Audiobus that you have finished receiving the incoming audio for the given interval.

Parameters
receiverPortThe receiver port.
- (void) ABAudioReceiverPortReceiveAQ (ABAudioReceiverPort *)  receiverPort
(ABPort *)  sourcePortOrNil
(AudioQueueBufferRef)  bufferList
(UInt32)  lengthInFrames
(AudioTimeStamp *)  ioTimestamp 

Audio Queue version of ABAudioReceiverPortReceive.

You can use this function to pull audio from Audiobus into an Audio Queue buffer. This may be used inside an AudioQueueInputCallback to replace the audio received from the microphone with audio from Audiobus, for instance.

See discussion for ABAudioReceiverPortReceive.

Parameters
receiverPortThe receiver port.
sourcePortOrNilIf you are receiving separate streams (receiveMixedAudio is NO), this must be nil. Otherwise, pass the port to receive audio from.
bufferListThe buffer list to receive audio into, in the format specified by clientFormat. If NULL, then audio will simply be discarded.
lengthInFramesThe number of frames requested. This method will never return less than the requested frames.
ioTimestampOn input, the current audio timestamp. On output, the timestamp of the returned audio (may differ due to latency).
- (BOOL) ABAudioReceiverPortIsConnected (ABAudioReceiverPort *)  receiverPort

Determine if the receiver port is currently connected to any sources.

This function is suitable for use from within a realtime Core Audio context.

Parameters
receiverPortThe receiver port.
Returns
YES if there are currently sources connected; NO otherwise.
- (BOOL) ABAudioReceiverPortIsConnectedToSelf (ABAudioReceiverPort *)  receiverPort

Whether the port is connected to another port from the same app.

This returns YES when the receiver port is connected to a sender port also belonging to your app.

If your app supports connections to self (ABAudiobusController's allowsConnectionsToSelf is set to YES), then you should take care to avoid feedback issues when the app's input is being fed from its own output.

Primarily, this means not sending output derived from the input through the sender port.

You can use ABAudioReceiverPortIsConnectedToSelf and the equivalent ABAudioSenderPort function, ABAudioSenderPortIsConnectedToSelf to determine this state from the Core Audio realtime thread, and perform muting/etc as appropriate.

Parameters
receiverPortThe receiver port.
Returns
YES if one of this port's sources belongs to this app
- (void) setVolume: (float)  volume
forSourcePort: (ABPort *)  port 

Set the volume level for a particular source.

Note that this only applies to the mixed stream as accessed via ABAudioReceiverPortReceive when the receiveMixedAudio property is YES.

It does not affect separate streams accessed via ABAudioReceiverPortReceive when receiveMixedAudio is NO.

Parameters
volumeVolume level (0 - 1); default 1
portSource port
- (float) volumeForSourcePort: (ABPort *)  port

Get the volume level for a source.

Parameters
portSource port
Returns
Volume for the given port (0 - 1)
- (void) setPan: (float)  pan
forSourcePort: (ABPort *)  port 

Set the pan for a particular source.

Note that this only applies to the mixed stream as accessed via ABAudioReceiverPortReceive when the receiveMixedAudio property is YES.

It does not affect separate streams accessed via ABAudioReceiverPortReceive when receiveMixedAudio is NO.

Parameters
panPan (-1.0 - 1.0); default 0.0
portSource port
- (float) panForSourcePort: (ABPort *)  port

Get the pan level for a source.

Parameters
portSource port
Returns
Pan for the given port (-1.0 - 1.0)
- (AudioUnit) audioUnitForSourcePort: (ABPort *)  port

Get access to the Inter-App Audio audio unit for a particular source.

You may use this method to gain direct access to the audio unit for a source in order to perform custom Inter-App Audio interactions, such as MIDI exchange.

Watch the ABAudioReceiverPortPortInterAppAudioUnitWillInitializeNotification notification to be informed when an audio unit for a port that is being connected is about to be initialised. You can use this to set IAA host transport callbacks. Watch ABAudioReceiverPortPortInterAppAudioUnitConnectedNotification notification to be informed when an audio unit for a connected port has been connected. Watch ABAudioReceiverPortPortInterAppAudioUnitDisconnectedNotification to be notified when an audio unit has been disconnected, after which you should not access the audio unit again.

You must never add this audio unit to a graph, call AudioUnitRender upon it, or change the client formats.

Note that once this audio unit has been disconnected, either due to an Audiobus disconnection, or an error like the source app crashing, the audio unit will be invalidated. If you retain references to audio units returned from this method, it's very important that you observe the ABAudioReceiverPortPortInterAppAudioUnitDisconnectedNotification notification, and unset your references.

Parameters
portSource port
Returns
The audio unit connected to the source, if Inter-App Audio in use. Otherwise, NULL.

Property Documentation

- (NSArray*) sources
readnonatomicstrong

Currently-connected sources.

This is an array of ABPorts .

- (BOOL) connected
readnonatomicassign

Whether the port is connected (via IAA or Audiobus)

- (BOOL) interAppAudioConnected
readnonatomicassign

Whether the port is connected via Inter-App Audio.

Note that this property will also return YES when connected to Audiobus peers using the 2.1 SDK.

- (BOOL) audiobusConnected
readnonatomicassign

Whether the port is connected via Audiobus.

- (BOOL) receiveMixedAudio
readwritenonatomicassign

Whether to receive audio as a mixed stream.

If YES (default), then all incoming audio across all sources will be mixed to a single audio stream. Otherwise, you will receive separate audio streams for each connected port.

See documentation for ABAudioReceiverPortReceive and ABAudioReceiverPortEndReceiveTimeInterval.

- (AudioStreamBasicDescription) clientFormat
readwritenonatomicassign

Client format.

Use this to specify what audio format your app uses. Audio will be automatically converted from the Audiobus line format.

The default value is non-interleaved stereo floating-point PCM.

- (NSString*) title
readwritenonatomicstrong

The title of the port, for display to the user.

- (UIImage*) icon
readwritenonatomicstrong

The port icon (a 32x32 image)

This is optional if your app only has one receiver port, but if your app defines multiple receiver ports, it is highly recommended that you provide icons for each, for easy identification by the user.

- (BOOL) automaticMonitoring
readwritenonatomicassign

Whether the port should perform monitoring itself.

If your app does not do audio monitoring - such as a guitar tuner app without a passthrough feature - you should set this property to YES, which will cause the receiver port to do its own monitoring, so input apps can still be heard.

If, on the other hand, your app does do its own audio monitoring, leave this property at its default value, NO, to disable internal monitoring.

The default value is NO.

- (BOOL) connectedToSelf
readnonatomicassign

Whether the port is connected to another port from the same app.

This is a key-value-observable property equivalent of ABAudioReceiverPortIsConnectedToSelf. See the documentation for ABAudioReceiverPortIsConnectedToSelf for details.

- (NSTimeInterval) latency
readnonatomicassign

The current latency.

This reports the total latency of the audio chain ending at this receiver. Note that this latency is already represented in the AudioTimeStamp value returned from the receive methods.

- (NSString*) sourcesTitle
readnonatomicassign

A title representing the sources connected to the port.

- (UIImage*) sourcesIcon
readnonatomicassign

An icon representing the sources connected to the port.


The documentation for this class was generated from the following file: