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.
(NSArray *audioPipelineIDs)	- __deprecated_msg
(NSArray *MIDIPipelineIDs)	- __deprecated_msg

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
ABPeer *	peer
	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.
NSSet < ABConnectionGraphPipeline * > *	pipelines
	The connection pipelines of which this port is a member.

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

name	Name of port, for internal use
title	Title 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

receiverPort	The receiver port.
sourcePortOrNil	If 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.
audio	The 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.
lengthInFrames	The number of frames requested. This method will never return less than the requested frames.
ioTimestamp	On 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

receiverPort

The 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

receiverPort	The receiver port.
sourcePortOrNil	If you are receiving separate streams (receiveMixedAudio is NO), this must be nil. Otherwise, pass the port to receive audio from.
bufferList	The buffer list to receive audio into, in the format specified by clientFormat. If NULL, then audio will simply be discarded.
lengthInFrames	The number of frames requested. This method will never return less than the requested frames.
ioTimestamp	On 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

receiverPort

The 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

receiverPort

The 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

volume	Volume level (0 - 1); default 1
port	Source port

- (float) volumeForSourcePort:

(ABPort *)

port

Get the volume level for a source.

Parameters

port	Source 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

pan	Pan (-1.0 - 1.0); default 0.0
port	Source port

- (float) panForSourcePort:

(ABPort *)

port

Get the pan level for a source.

Parameters

port	Source 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

port	Source 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:

• ABAudioReceiverPort.h