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.
 

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

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
nameName of port, for internal use
titleTitle of port, show to the user
descriptionThe 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
nameName of port, for internal use
titleTitle of port, show to the user
descriptionThe 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.
audioUnitThe 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
descriptionThe 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
senderPortSender port.
audioAudio buffer list to send, in the client format .
lengthInFramesLength of the audio, in frames.
timestampThe 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
senderPortSender 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
senderPortSender 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
senderPortSender 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: