ABSenderPort Class Reference

Sender port. More...

#import <ABSenderPort.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)	- ABSenderPortSend
	Send audio.
(BOOL)	- ABSenderPortIsConnected
	Determine if the sender port is currently connected to any destinations.
(BOOL)	- ABSenderPortIsConnectedToSelf
(BOOL)	- ABSenderPortIsMuted
	Determine whether output should be muted.
(NSTimeInterval)	- ABSenderPortGetAverageLatency
	Get average latency.

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

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 ABSenderPortSend 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 ABSenderPortSend 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) ABSenderPortSend		(ABSenderPort *)	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 ABSenderPort 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) ABSenderPortIsConnected

(ABSenderPort *)

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

(ABSenderPort *)

senderPort

- (BOOL) ABSenderPortIsMuted

(ABSenderPort *)

senderPort

Determine whether output should be muted.

This C function allows you to determine whether your output should be muted. You only need to use this function when you did not pass an audio unit when initializing the port.

If the return value of this function is YES, 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.

Note that this muting is handled for you automatically if you are using an audio unit with the port.

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

- (NSTimeInterval) ABSenderPortGetAverageLatency

(ABSenderPort *)

senderPort

Get average latency.

Deprecated: no longer in use.

Parameters

senderPort

Sender port.

Returns

Latency, in seconds.

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 ABSenderPortIsMuted 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 ABSenderPortIsConnectedToSelf. See the documentation for ABSenderPortIsConnectedToSelf 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.

---

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

• ABSenderPort.h