ABAudioSenderPort Class Reference

Sender port. More...

#import <ABAudioSenderPort.h>

Inherits ABPort, and <ABLocalPort>.

Instance Methods
(id)	- initWithName:title:audioComponentDescription:
	Initialize.
(id)	- initWithName:title:audioComponentDescription:audioUnit:
	Initialize, with an audio unit.
(void)	- registerAdditionalAudioComponentDescription:
	Register additional AudioComponentDescriptions that identify your audio unit.
(void)	- ABAudioSenderPortSend
	Send audio.
(BOOL)	- ABAudioSenderPortIsConnected
	Determine if the sender port is currently connected to any destinations.
(BOOL)	- ABAudioSenderPortIsConnectedToSelf
	Whether the port is connected to another port from the same app.
(BOOL)	- ABAudioSenderPortIsMuted
	Determine whether output should be muted.
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 *	destinations
	Currently-connected destinations.
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	muted
	Whether the port is muted.
AudioStreamBasicDescription	clientFormat
	Client format.
BOOL	derivedFromLiveAudioSource
	Whether the port's audio is derived from a live audio source.
AudioUnit	audioUnit
	Audio unit.
AudioComponentDescription	audioComponentDescription
	The AudioComponentDescription, of type kAudioUnitType_RemoteGenerator, which identifies this port's published audio unit.
BOOL	connectedToSelf
	Whether the port is connected to another port from the same app.
UInt32	latency
	The constant latency of this sender, in frames.
NSString *	title
	The title of the port, for display to the user.
UIImage *	icon
	The port icon (a 32x32 image)
BOOL	isHidden
	Prevents showing the port in Audiobus' sender port picker view.
NSString *	destinationsTitle
	A title representing the destinations the port is connected to.
UIImage *	destinationsIcon
	An icon representing the destinations the port is connected to.
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

Sender port.

This class is used to transmit audio.

See the integration guide on using the Sender Port for discussion.

Method Documentation

- (id) initWithName:		(NSString *)	name
title:		(NSString *)	title
audioComponentDescription:		(AudioComponentDescription)	description

Initialize.

Initializes a new sender port. Use ABAudioSenderPortSend to send audio.

Note that unlike the initWithName:title:audioComponentDescription:audioUnit: initializer, audio sent via sender ports initialized with this version will incur a small latency penalty equal to the current hardware buffer duration (e.g. 5 ms) due to necessary buffering. Initialize with an audio unit to avoid this.

Parameters

name	Name of port, for internal use
title	Title of port, show to the user
description	The AudioComponentDescription that identifiers this port. This must match the entry in the AudioComponents dictionary of your Info.plist, and must be of type kAudioUnitType_RemoteGenerator or kAudioUnitType_RemoteInstrument.

- (id) initWithName:		(NSString *)	name
title:		(NSString *)	title
audioComponentDescription:		(AudioComponentDescription)	description
audioUnit:		(AudioUnit)	audioUnit

Initialize, with an audio unit.

Initializes a new sender port, with an audio unit to be used for generating audio.

Note: The audio unit you pass here must be an output unit (kAudioUnitSubType_RemoteIO). If you wish to use a different kind of audio unit, you'll need to use the non-AudioUnit initialiser and call ABAudioSenderPortSend with the output from that audio unit.

Parameters

name	Name of port, for internal use
title	Title of port, show to the user
description	The AudioComponentDescription that identifiers this port. This must match the entry in the AudioComponents dictionary of your Info.plist, and must be of type kAudioUnitType_RemoteGenerator or kAudioUnitType_RemoteInstrument.
audioUnit	The output audio unit to use for sending audio. The audio unit's output will be transmitted.

- (void) registerAdditionalAudioComponentDescription:

(AudioComponentDescription)

description

Register additional AudioComponentDescriptions that identify your audio unit.

Sometimes under Inter-App Audio you may wish to publish your audio unit with an additional AudioComponentDescription, such as providing both kAudioUnitType_RemoteInstrument and kAudioUnitType_RemoteGenerator types.

If you wish to do so, you can use this method to register the additional descriptions (additional to the one passed via the init method). Note that this method will not publish your audio unit with the given description: you'll need to do that yourself.

This will cause the port to correctly recognize incoming connections from the other descriptions.

Parameters

description

The additional AudioComponentDescription to add

- (void) ABAudioSenderPortSend		(ABAudioSenderPort *)	senderPort
		(const AudioBufferList *)	audio
		(UInt32)	lengthInFrames
		(const AudioTimeStamp *)	timestamp

Send audio.

This C function is used to send audio. It's suitable for use within a realtime thread, as it does not hold locks, allocate memory or call Objective-C methods. You should keep a local pointer to the ABAudioSenderPort instance, to be passed as the first parameter.

Note: If you provided an audio unit when you initialized this class, you cannot use this function.

Parameters

senderPort	Sender port.
audio	Audio buffer list to send, in the client format .
lengthInFrames	Length of the audio, in frames.
timestamp	The timestamp of the audio.

- (BOOL) ABAudioSenderPortIsConnected

(ABAudioSenderPort *)

senderPort

Determine if the sender port is currently connected to any destinations.

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

Parameters

senderPort

Sender port.

Returns

YES if there are currently destinations connected; NO otherwise.

- (BOOL) ABAudioSenderPortIsConnectedToSelf

(ABAudioSenderPort *)

senderPort

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

This returns YES when the sender port is connected to a receiver 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 ABAudioSenderPortIsConnectedToSelf and the equivalent ABAudioReceiverPort function, ABAudioReceiverPortIsConnectedToSelf to determine this state from the Core Audio realtime thread, and perform muting/etc as appropriate.

Parameters

senderPort

Sender port.

Returns

YES if one of this port's destinations belongs to this app

- (BOOL) ABAudioSenderPortIsMuted

(ABAudioSenderPort *)

senderPort

Determine whether output should be muted.

  This C function allows you to determine whether your output should be muted.

  If the return value of this function is YES, then you must silence your app's corresponding audio output   to avoid doubling up the audio (which is being output at the other end), and to enable your app to   go silent when disconnected from Audiobus.  You can do this by zeroing your buffers using memset,   and/or setting the kAudioUnitRenderAction_OutputIsSilence flag on the ioActionFlags variable in a render callback.

  MIDI that this muting is handled for you automatically if you are using an audio unit with the port, but either way   you may be able to save some rendering time by not running your audio processing routines when this function returns YES.

  The muted property provides a key-value observable version of this method, which should   only be used outside of the Core Audio realtime thread.

Parameters

senderPort

Sender port.

Returns

Whether the output should be muted

Property Documentation

- (NSArray*) destinations

readnonatomicstrong

Currently-connected destinations.

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

readnonatomicassign

Whether the port is muted.

See discussion for ABAudioSenderPortIsMuted for details.

This property is observable.

- (AudioStreamBasicDescription) clientFormat

readwritenonatomicassign

Client format.

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

Note: If you provided an audio unit when you initialized this class, you cannot use this property.

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

- (BOOL) derivedFromLiveAudioSource

readwritenonatomicassign

Whether the port's audio is derived from a live audio source.

If this sender port's audio comes from the system audio input (such as a microphone), then you should set this property to YES to allow apps downstream to react accordingly. For example, an app that provides audio monitoring might want to disable monitoring by default when connected to a live audio source in order to prevent feedback.

- (AudioUnit) audioUnit

readwritenonatomicassign

Audio unit.

The output audio unit to use for sending audio. The audio unit's output will be transmitted. If you uninitialize the audio unit passed to this class's initializer, be sure to set this property to NULL immediately beforehand.

If you did not provide an audio unit when initializing the port, this property will allow you to gain access to the internal audio unit used for audio transport, for the purposes of custom Inter-App Audio interactions such as transport control or MIDI exchange.

- (AudioComponentDescription) audioComponentDescription

readnonatomicassign

The AudioComponentDescription, of type kAudioUnitType_RemoteGenerator, which identifies this port's published audio unit.

- (BOOL) connectedToSelf

readnonatomicassign

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

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

- (UInt32) latency

readwritenonatomicassign

The constant latency of this sender, in frames.

If your audio generation code adds a constant amount of latency to the audio stream (such as an FFT or lookahead operation), you should specify that here in order to have Audiobus automatically account for it.

This is important when users have the same input signal going through different paths, so that Audiobus can synchronize these properly at the output. If you don't specify the correct latency, the user will hear phasing due to incorrectly aligned signals at the output.

Default: 0

- (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 sender port, but if your app defines multiple sender ports, it is highly recommended that you provide icons for each, for easy identification by the user.

- (BOOL) isHidden

readwritenonatomicassign

Prevents showing the port in Audiobus' sender port picker view.

If this property is true, the port is created but not shown in the list of sender ports. Set this property to true in the case that the port is only used for inter app audio launching and background launching of your app.

- (NSString*) destinationsTitle

readnonatomicassign

A title representing the destinations the port is connected to.

- (UIImage*) destinationsIcon

readnonatomicassign

An icon representing the destinations the port is connected to.

---

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

• ABAudioSenderPort.h