Struct AUAudioUnit

#[repr(C)]
pub struct AUAudioUnit { /* private fields */ }

Available on crate feature AUAudioUnit only.

An audio unit instance.

AUAudioUnit is a host interface to an audio unit. Hosts can instantiate either version 2 or version 3 units with this class, and to some extent control whether an audio unit is instantiated in-process or in a separate extension process.

Implementors of version 3 audio units can and should subclass AUAudioUnit. To port an existing version 2 audio unit easily, AUAudioUnitV2Bridge can be subclassed.

These are the ways in which audio unit components can be registered:

• (v2) Packaged into a component bundle containing an AudioComponents Info.plist entry, referring to an AudioComponentFactoryFunction. See AudioComponent.h.

• (v2) AudioComponentRegister(). Associates a component description with an AudioComponentFactoryFunction. See AudioComponent.h.

• (v3) Packaged into an app extension containing an AudioComponents Info.plist entry. The principal class must conform to the AUAudioUnitFactory protocol, which will typically instantiate an AUAudioUnit subclass.

• (v3) +[AUAudioUnit registerSubclass:asComponentDescription:name:version:]. Associates a component description with an AUAudioUnit subclass.

A host need not be aware of the concrete subclass of AUAudioUnit that is being instantiated. initWithComponentDescription:options:error: ensures that the proper subclass is used.

When using AUAudioUnit with a v2 audio unit, or the C AudioComponent and AudioUnit API’s with a v3 audio unit, all major pieces of functionality are bridged between the two API’s. This header describes, for each v3 method or property, the v2 equivalent.

See also Apple’s documentation

Implementations

impl AUAudioUnit

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

pub unsafe fn initWithComponentDescription_options_error( this: Allocated<Self>, component_description: AudioComponentDescription, options: AudioComponentInstantiationOptions, ) -> Result<Retained<Self>, Retained<NSError>>

Available on crate feature AudioComponent only.

Designated initializer.

Parameter componentDescription: A single AUAudioUnit subclass may implement multiple audio units, for example, an effect that can also function as a generator, or a cluster of related effects. The component description specifies the component which was instantiated.

Parameter options: Options for loading the unit in-process or out-of-process.

Parameter outError: Returned in the event of failure.

pub unsafe fn initWithComponentDescription_error( this: Allocated<Self>, component_description: AudioComponentDescription, ) -> Result<Retained<Self>, Retained<NSError>>

Available on crate feature AudioComponent only.

Convenience initializer (omits options).

pub unsafe fn instantiateWithComponentDescription_options_completionHandler( component_description: AudioComponentDescription, options: AudioComponentInstantiationOptions, completion_handler: &DynBlock<dyn Fn(*mut AUAudioUnit, *mut NSError)>, )

Available on crate features AudioComponent and block2 only.

Asynchronously create an AUAudioUnit instance.

Parameter componentDescription: The AudioComponentDescription of the audio unit to instantiate.

Parameter options: See the discussion of AudioComponentInstantiationOptions in AudioToolbox/AudioComponent.h.

Parameter completionHandler: Called in a thread/dispatch queue context internal to the implementation. The client should retain the supplied AUAudioUnit.

Certain types of AUAudioUnits must be instantiated asynchronously – see the discussion of kAudioComponentFlag_RequiresAsyncInstantiation in AudioToolbox/AudioComponent.h.

Note: Do not block the main thread while waiting for the completion handler to be called; this can deadlock.

pub unsafe fn componentDescription(&self) -> AudioComponentDescription

Available on crate feature AudioComponent only.

The AudioComponentDescription with which the audio unit was created.

pub unsafe fn component(&self) -> AudioComponent

Available on crate feature AudioComponent only.

The AudioComponent which was found based on componentDescription when the audio unit was created.

pub unsafe fn componentName(&self) -> Option<Retained<NSString>>

The unit’s component’s name.

By convention, an audio unit’s component name is its manufacturer’s name, plus “: “, plus the audio unit’s name. The audioUnitName and manufacturerName properties are derived from the component name.

pub unsafe fn audioUnitName(&self) -> Option<Retained<NSString>>

The audio unit’s name.

pub unsafe fn manufacturerName(&self) -> Option<Retained<NSString>>

The manufacturer’s name.

pub unsafe fn audioUnitShortName(&self) -> Option<Retained<NSString>>

A short name for the audio unit.

Audio unit host applications can display this name in situations where the audioUnitName might be too long. The recommended length is up to 16 characters. Host applications may truncate it.

pub unsafe fn componentVersion(&self) -> u32

The unit’s component’s version.

pub unsafe fn allocateRenderResourcesAndReturnError( &self, ) -> Result<(), Retained<NSError>>

Allocate resources required to render.

Hosts must call this before beginning to render. Subclassers should call the superclass implementation.

Bridged to the v2 API AudioUnitInitialize().

pub unsafe fn deallocateRenderResources(&self)

Deallocate resources allocated by allocateRenderResourcesAndReturnError:

Hosts should call this after finishing rendering. Subclassers should call the superclass implementation.

Bridged to the v2 API AudioUnitUninitialize().

pub unsafe fn renderResourcesAllocated(&self) -> bool

returns YES if the unit has render resources allocated.

pub unsafe fn reset(&self)

Reset transitory rendering state to its initial state.

Hosts should call this at the point of a discontinuity in the input stream being provided to an audio unit, for example, when seeking forward or backward within a track. In response, implementations should clear delay lines, filters, etc. Subclassers should call the superclass implementation.

Bridged to the v2 API AudioUnitReset(), in the global scope.

pub unsafe fn inputBusses(&self) -> Retained<AUAudioUnitBusArray>

An audio unit’s audio input connection points.

Subclassers must override this property’s getter. The implementation should return the same object every time it is asked for it, since clients can install KVO observers on it.

pub unsafe fn outputBusses(&self) -> Retained<AUAudioUnitBusArray>

An audio unit’s audio output connection points.

Subclassers must override this property’s getter. The implementation should return the same object every time it is asked for it, since clients can install KVO observers on it.

pub unsafe fn renderBlock(&self) -> AURenderBlock

Available on crate features AUComponent and block2 and objc2-core-audio-types only.

Block which hosts use to ask the unit to render.

Before invoking an audio unit’s rendering functionality, a host should fetch this block and cache the result. The block can then be called from a realtime context without the possibility of blocking and causing an overload at the Core Audio HAL level.

This block will call a subclass’ internalRenderBlock, providing all realtime events scheduled for the current render time interval, bracketed by calls to any render observers.

Subclassers should override internalRenderBlock, not this property.

Bridged to the v2 API AudioUnitRender().

pub unsafe fn scheduleParameterBlock(&self) -> AUScheduleParameterBlock

Available on crate features AUParameters and AudioUnitProperties and block2 only.

Block which hosts use to schedule parameters.

As with renderBlock, a host should fetch and cache this block before calling allocateRenderResources, if it intends to schedule parameters.

The block is safe to call from any thread context, including realtime audio render threads.

Subclassers should not override this; it is implemented in the base class and will schedule the events to be provided to the internalRenderBlock.

Bridged to the v2 API AudioUnitScheduleParameters().

pub unsafe fn tokenByAddingRenderObserver( &self, observer: AURenderObserver, ) -> NSInteger

Available on crate features AUComponent and block2 and objc2-core-audio-types only.

Add a block to be called on each render cycle.

The supplied block is called at the beginning and ending of each render cycle. It should not make any blocking calls.

This method is implemented in the base class AUAudioUnit, and should not be overridden.

Bridged to the v2 API AudioUnitAddRenderNotify().

Parameter observer: The block to call.

Returns: A token to be used when removing the observer.

pub unsafe fn removeRenderObserver(&self, token: NSInteger)

Remove an observer block added via tokenByAddingRenderObserver:

Parameter token: The token previously returned by tokenByAddingRenderObserver:

Bridged to the v2 API AudioUnitRemoveRenderNotify().

pub unsafe fn maximumFramesToRender(&self) -> AUAudioFrameCount

The maximum number of frames which the audio unit can render at once.

This must be set by the host before render resources are allocated. It cannot be changed while render resources are allocated.

Bridged to the v2 property kAudioUnitProperty_MaximumFramesPerSlice.

pub unsafe fn setMaximumFramesToRender( &self, maximum_frames_to_render: AUAudioFrameCount, )

Setter for maximumFramesToRender.

pub unsafe fn parameterTree(&self) -> Option<Retained<AUParameterTree>>

Available on crate feature AUParameters only.

An audio unit’s parameters, organized in a hierarchy.

Returns: A parameter tree object, or nil if the unit has no parameters.

Audio unit hosts can fetch this property to discover a unit’s parameters. KVO notifications are issued on this member to notify the host of changes to the set of available parameters.

AUAudioUnit has an additional pseudo-property, “allParameterValues”, on which KVO notifications are issued in response to certain events where potentially all parameter values are invalidated. This includes changes to currentPreset, fullState, and fullStateForDocument.

Hosts should not attempt to set this property.

Subclassers should implement the parameterTree getter to expose parameters to hosts. They should cache as much as possible and send KVO notifications on “parameterTree” when altering the structure of the tree or the static information (ranges, etc) of parameters.

This is similar to the v2 properties kAudioUnitProperty_ParameterList and kAudioUnitProperty_ParameterInfo.

Note that it is not safe to modify this property in a real-time context.

pub unsafe fn setParameterTree(&self, parameter_tree: Option<&AUParameterTree>)

Available on crate feature AUParameters only.

Setter for parameterTree.

pub unsafe fn parametersForOverviewWithCount( &self, count: NSInteger, ) -> Retained<NSArray<NSNumber>>

Returns the audio unit’s count most important parameters.

This property allows a host to query an audio unit for some small number of parameters which are its “most important”, to be displayed in a compact generic view.

An audio unit subclass should return an array of NSNumbers representing the addresses of the count most important parameters.

The base class returns an empty array regardless of count.

Partially bridged to kAudioUnitProperty_ParametersForOverview (v2 hosts can use that property to access this v3 method of an audio unit).

pub unsafe fn allParameterValues(&self) -> bool

pub unsafe fn isMusicDeviceOrEffect(&self) -> bool

Specifies whether an audio unit responds to MIDI events.

This is implemented in the base class and returns YES if the component type is music device or music effect.

pub unsafe fn virtualMIDICableCount(&self) -> NSInteger

The number of virtual MIDI cables implemented by a music device or effect.

A music device or MIDI effect can support up to 256 virtual MIDI cables of input; this property expresses the number of cables supported by the audio unit.

pub unsafe fn scheduleMIDIEventBlock(&self) -> AUScheduleMIDIEventBlock

Available on crate features AudioUnitProperties and block2 only.

Block used to schedule MIDI events.

As with renderBlock, a host should fetch and cache this block before calling allocateRenderResources if it intends to schedule MIDI events.

This is implemented in the base class. It is nil when musicDeviceOrEffect is NO.

Subclasses should not override. When hosts schedule events via this block, they are sent to the Audio Unit via the list of AURenderEvents delivered to internalRenderBlock.

All events sent via this block will be delivered to the internalRenderBlock in the MIDI protocol returned by the AudioUnitMIDIProtocol property. For example, if AudioUnitMIDIProtocol returns kMIDIProtocol_2_0, incoming events will be translated to MIDI 2.0 if necessary. If AudioUnitMIDIProtocol is not set, events will be delivered as legacy MIDI.

This bridged to the v2 API MusicDeviceMIDIEvent.

pub unsafe fn MIDIOutputNames(&self) -> Retained<NSArray<NSString>>

Count, and names of, a plug-in’s MIDI outputs.

A plug-in may override this method to inform hosts about its MIDI outputs. The size of the array is the number of outputs the Audio Unit supports. Each item in the array is the name of the MIDI output at that index.

This is bridged to the v2 API property kAudioUnitProperty_MIDIOutputCallbackInfo.

pub unsafe fn providesUserInterface(&self) -> bool

Specifies whether an audio unit provides UI (normally in the form of a view controller).

Implemented in the framework and should not be overridden by implementators. The framework detects whether any subclass has implemented requestViewControllerWithCompletionHandler: or is implemented by an AU extension whose extension point identifier is com.apple.AudioUnit-UI. See also requestViewControllerWithCompletionHandler: in <CoreAudioKit /AUViewController.h>

pub unsafe fn MIDIOutputEventBlock(&self) -> AUMIDIOutputEventBlock

Available on crate features AudioUnitProperties and block2 only.

Block used by the host to access the MIDI output generated by an Audio Unit.

The host can set this block and the plug-in can call it in its renderBlock to provide to the host the MIDI data associated with the current render cycle.

All events sent via this block will be delivered to the host in the MIDI protocol returned by the hostMIDIProtocol property. For example, if hostMIDIProtocol is set to kMIDIProtocol_2_0, incoming events will be translated to MIDI 2.0. If hostMIDIProtocol is not set, events will be delivered as legacy MIDI.

Note: AUMIDIEventListBlock should be preferred over this block going forward.

This is bridged to the v2 API property kAudioUnitProperty_MIDIOutputCallback.

pub unsafe fn setMIDIOutputEventBlock( &self, midi_output_event_block: AUMIDIOutputEventBlock, )

Available on crate features AudioUnitProperties and block2 only.

Setter for MIDIOutputEventBlock.

pub unsafe fn AudioUnitMIDIProtocol(&self) -> MIDIProtocolID

Available on crate feature objc2-core-midi only.

The MIDI protocol used by the Audio Unit for receiving MIDIEventList data.

Subclassers should override to return the desired protocol in which the Audio Unit wants to receive input MIDI data, otherwise the Audio Unit will default to receiving legacy MIDI.

All translatable messages will be converted (if necessary) to this protocol prior to delivery to the Audio Unit.

This is bridged to the v2 API property kAudioUnitProperty_AudioUnitMIDIProtocol.

pub unsafe fn hostMIDIProtocol(&self) -> MIDIProtocolID

Available on crate feature objc2-core-midi only.

The MIDI protocol to be used by the host for receiving MIDIEventList data.

Hosts should set this property to the protocol they wish to receive MIDIEventList data from the Audio Unit. This should be set prior to initialization, all translatable messages will be converted (if necessary) to this property’s protocol prior to delivery to the host.

Host should setup in the following order:

• Set hostMIDIProtocol
• Set MIDIOutputEventListBlock
• Call allocateRenderResourcesAndReturnError

This is bridged to the v2 API property kAudioUnitProperty_HostMIDIProtocol.

Notes:

• If overriding this property, subclassers must call [super setHostMIDIProtocol:]
• hostMIDIProtocol should be set before attempting to query AudioUnitMIDIProtocol or calling allocateRenderResourcesAndReturnError to allow Audio Units to optionally match their input MIDI protocol to the desired host protocol and prevent protocol conversion.

pub unsafe fn setHostMIDIProtocol(&self, host_midi_protocol: MIDIProtocolID)

Available on crate feature objc2-core-midi only.

Setter for hostMIDIProtocol.

pub unsafe fn fullState( &self, ) -> Option<Retained<NSDictionary<NSString, AnyObject>>>

A persistable snapshot of the Audio Unit’s properties and parameters, suitable for saving as a user preset.

Hosts may use this property to save and restore the state of an Audio Unit being used in a user preset or document. The Audio Unit should not persist transitory properties such as stream formats, but should save and restore all parameters and custom properties.

The base class implementation of this property saves the values of all parameters currently in the parameter tree. A subclass which dynamically produces multiple variants of the parameter tree needs to be aware that the serialization method does a depth-first preorder traversal of the tree.

Bridged to the v2 property kAudioUnitProperty_ClassInfo.

pub unsafe fn setFullState( &self, full_state: Option<&NSDictionary<NSString, AnyObject>>, )

Setter for fullState.

pub unsafe fn fullStateForDocument( &self, ) -> Option<Retained<NSDictionary<NSString, AnyObject>>>

A persistable snapshot of the audio unit’s properties and parameters, suitable for saving in a user’s document.

This property is distinct from fullState in that some state is suitable for saving in user presets, while other state is not. For example, a synthesizer’s master tuning setting could be considered global state, inappropriate for storing in reusable presets, but desirable for storing in a document for a specific live performance.

Hosts saving documents should use this property. If the audio unit does not implement it, the base class simply sets/gets fullState.

Bridged to the v2 property kAudioUnitProperty_ClassInfoFromDocument.

pub unsafe fn setFullStateForDocument( &self, full_state_for_document: Option<&NSDictionary<NSString, AnyObject>>, )

Setter for fullStateForDocument.

pub unsafe fn factoryPresets( &self, ) -> Option<Retained<NSArray<AUAudioUnitPreset>>>

A collection of presets provided by the audio unit’s developer.

A preset provides users of an audio unit with an easily-selectable, fine-tuned set of parameters provided by the developer. This property returns all of the available factory presets.

Bridged to the v2 property kAudioUnitProperty_FactoryPresets.

pub unsafe fn userPresets(&self) -> Retained<NSArray<AUAudioUnitPreset>>

A collection of presets saved by the user

In addition to factory presets, provided by the audio unit vendor, users have the ability to save the values of the parameters of an audio unit into a user preset. These users presets can be accessed using this property.

The default implementation of this method will load the user presets from an internal location that might not be directly accessible to the audio unit host application or to the audio unit. Instead of accessing this path directly, the audio unit should rely on the superclass implementation of this method to retrieve the presets.

Audio Units are free to override this method to load their user presets via different means (e.g. from their iCloud container).

pub unsafe fn saveUserPreset_error( &self, user_preset: &AUAudioUnitPreset, ) -> Result<(), Retained<NSError>>

Persistently save the current state of the audio unit into a userPreset

The new preset will be added to userPresets and will become selectable by assigning it to the currentPreset property. If a preset with the provided name already exists then it will be overwritten.

For user presets, the preset number is required to be negative. If a positive number is passed, the sign will be changed to negative. If zero is passed, the number will be set to -1. These changes will be reflected on the userPreset argument.

The default implementation of this method will save the user preset to an internal location.

Audio Units are free to override this method to operate on a different location (e.g. their iCloud container).

Parameter userPreset: The preset under which the current state will be saved.

Parameter outError: In the event of a failure, the method will return NO and outError will be set to an NSError, describing the problem. Some possible errors:

• domain: NSOSStatusErrorDomain code: kAudioUnitErr_NoConnection
• domain: NSOSStatusErrorDomain code: kAudioUnitErr_InvalidFilePath
• domain: NSOSStatusErrorDomain code: kAudioUnitErr_MissingKey

Returns: YES for success. NO in the event of a failure, in which case the error is returned in outError.

pub unsafe fn deleteUserPreset_error( &self, user_preset: &AUAudioUnitPreset, ) -> Result<(), Retained<NSError>>

Remove a user preset.

The user preset will be removed from userPresets and will be permanently deleted.

The default implementation of this method will delete the user preset from an internal location.

Audio Units are free to override this method to operate on a different location (e.g. their iCloud container).

Parameter userPreset: The preset to be deleted.

Parameter outError: In the event of a failure, the method will return NO and outError will be set to an NSError, describing the problem. Some possible errors:

• domain: NSOSStatusErrorDomain code: kAudioUnitErr_NoConnection
• domain: NSPOSIXErrorDomain code: ENOENT
• domain: NSOSStatusErrorDomain code: kAudioUnitErr_InvalidFilePath

Returns: YES for success. NO in the event of a failure, in which case the error is returned in outError.

pub unsafe fn presetStateFor_error( &self, user_preset: &AUAudioUnitPreset, ) -> Result<Retained<NSDictionary<NSString, AnyObject>>, Retained<NSError>>

Retrieve the state stored in a user preset

This method allows access to the contents of a preset without having to set that preset as current. The returned dictionary is assignable to the audio unit’s fullState and/or fullStateForDocument properties.

Audio units can override this method in order to vend user presets from a different location (e.g. their iCloud container).

In order to restore the state from a user preset, the audio unit should override the setter for the currentPreset property and check the preset number to determine the type of preset. If the preset number is >= 0 then the preset is a factory preset. If the preset number is < 0 then it is a user preset.

This method can then be called to retrieve the state stored in a user preset and the audio unit can assign this to fullState or fullStateForDocument.

Parameter userPreset: The preset to be selected.

Parameter outError: In the event of a failure, the method will return nil and outError will be set to an NSError, describing the problem. Some possible errors:

• domain: NSOSStatusErrorDomain code: kAudioUnitErr_NoConnection
• domain: NSPOSIXErrorDomain code: ENOENT
• domain: NSCocoaErrorDomain code: NSCoderReadCorruptError

Returns: Returns nil if there was an error, otherwise returns a dictionary containing the full state of the audio unit saved in the preset. For details on the possible keys present in the full state dictionary, please see the documentation for kAudioUnitProperty_ClassInfo. The minimal set of keys and their type is: : NSNumber, : NSNumber, : NSNumber, : NSNumber, : NSString, : NSNumber, : NSData

pub unsafe fn supportsUserPresets(&self) -> bool

Specifies whether an audio unit supports loading and saving user presets

The audio unit should set this property to YES if a user preset can be assigned to currentPreset.

Audio unit host applications should query this property to determine whether the audio unit supports user presets.

Assigning a user preset to the currentPreset property of an audio unit that does not support restoring state from user presets may result in incorrect behavior.

pub unsafe fn isLoadedInProcess(&self) -> bool

Set to YES when an AUAudioUnit is loaded in-process

If the AUAudioUnit is instantiated with kAudioComponentInstantiation_LoadInProcess, but the audio unit is not packaged properly to support loading in-process, the system will silently fall back to loading the audio unit out-of-process.

This property can be used to determine whether the instantiation succeeded as intended and the audio unit is running in-process.

The presence of an extension process is not sufficient indication that the audio unit failed to load in-process, since the framework might launch the audio unit extension process to fulfill auxiliary functionality. If the audio unit is loaded in-process then rendering is done in the host process. Other operations that are not essential to rendering audio, might be done in the audio unit’s extension process.

pub unsafe fn currentPreset(&self) -> Option<Retained<AUAudioUnitPreset>>

The audio unit’s last-selected preset.

Hosts can let the user select a preset by setting this property. Note that when getting this property, it does not reflect whether parameters may have been modified since the preset was selected.

Bridged to the v2 property kAudioUnitProperty_PresentPreset.

pub unsafe fn setCurrentPreset( &self, current_preset: Option<&AUAudioUnitPreset>, )

Setter for currentPreset.

pub unsafe fn latency(&self) -> NSTimeInterval

The audio unit’s processing latency, in seconds.

This property reflects the delay between when an impulse in the unit’s audio unit stream arrives in the input vs. output streams. This should reflect the delay due to signal processing (e.g. filters, FFT’s, etc.), not delay or reverberation which is being applied as an effect.

Note that a latency that varies with parameter settings, including bypass, is generally not useful to hosts. A host is usually only prepared to add delays before starting to render and those delays need to be fixed. A variable delay would introduce artifacts even if the host could track it. If an algorithm has a variable latency it should be adjusted upwards to some fixed latency within the audio unit. If for some reason this is not possible, then latency could be regarded as an unavoidable consequence of the algorithm and left unreported (i.e. with a value of 0).

Bridged to the v2 property kAudioUnitProperty_Latency.

pub unsafe fn tailTime(&self) -> NSTimeInterval

The audio unit’s tail time, in seconds.

This property reflects the time interval between when the input stream ends or otherwise transitions to silence, and when the output stream becomes silent. Unlike latency, this should reflect the duration of a delay or reverb effect.

Bridged to the v2 property kAudioUnitProperty_TailTime.

pub unsafe fn renderQuality(&self) -> NSInteger

Provides a trade-off between rendering quality and CPU load.

The range of valid values is 0-127.

Bridged to the v2 property kAudioUnitProperty_RenderQuality.

pub unsafe fn setRenderQuality(&self, render_quality: NSInteger)

Setter for renderQuality.

pub unsafe fn shouldBypassEffect(&self) -> bool

Directs an effect to route input directly to output, without any processing.

Bridged to the v2 property kAudioUnitProperty_BypassEffect.

pub unsafe fn setShouldBypassEffect(&self, should_bypass_effect: bool)

Setter for shouldBypassEffect.

pub unsafe fn canProcessInPlace(&self) -> bool

Expresses whether an audio unit can process in place.

In-place processing is the ability for an audio unit to transform an input signal to an output signal in-place in the input buffer, without requiring a separate output buffer.

A host can express its desire to process in place by using null mData pointers in the output buffer list. The audio unit may process in-place in the input buffers. See the discussion of renderBlock.

Partially bridged to the v2 property kAudioUnitProperty_InPlaceProcessing; in v3 it is not settable.

Defaults to NO. Subclassers can override to return YES.

pub unsafe fn isRenderingOffline(&self) -> bool

Communicates to an audio unit that it is rendering offline.

A host should set this property when using an audio unit in a context where there are no realtime deadlines, before asking the unit to allocate render resources. An audio unit may respond by using a more expensive signal processing algorithm, or allowing itself to block at render time if data being generated on secondary work threads is not ready in time. (Normally, in a realtime thread, this data would have to be dropped).

Bridged to the v2 property kAudioUnitProperty_OfflineRender.

pub unsafe fn setRenderingOffline(&self, rendering_offline: bool)

Setter for isRenderingOffline.

pub unsafe fn channelCapabilities(&self) -> Option<Retained<NSArray<NSNumber>>>

Expresses valid combinations of input and output channel counts.

Elements are NSNumber containing integers; [0]=input count, [1]=output count, [2]=2nd input count, [3]=2nd output count, etc.

An input, output count of (2, 2) signifies that the audio unit can process 2 input channels to 2 output channels.

Negative numbers (-1, -2) indicate any number of channels. (-1, -1) means any number of channels on input and output as long as they are the same. (-1, -2) means any number of channels on input or output, without the requirement that the counts are the same.

A negative number less than -2 is used to indicate a total number of channels across every bus in that scope, regardless of how many channels are set on any particular bus. For example, (-16, 2) indicates that a unit can accept up to 16 channels of input across its input busses, but will only produce 2 channels of output.

Zero on either side (though typically input) means “not applicable”, because there are no elements on that side.

Bridged to the v2 property kAudioUnitProperty_SupportedNumChannels.

pub unsafe fn musicalContextBlock(&self) -> AUHostMusicalContextBlock

Available on crate feature block2 only.

A callback for the AU to call the host for musical context information.

Note that an audio unit implementation accessing this property should cache it in realtime-safe storage before beginning to render.

Bridged to the HostCallback_GetBeatAndTempo and HostCallback_GetMusicalTimeLocation callback members in kAudioUnitProperty_HostCallbacks.

pub unsafe fn setMusicalContextBlock( &self, musical_context_block: AUHostMusicalContextBlock, )

Available on crate feature block2 only.

Setter for musicalContextBlock.

pub unsafe fn transportStateBlock(&self) -> AUHostTransportStateBlock

Available on crate feature block2 only.

A callback for the AU to call the host for transport state information.

Note that an audio unit implementation accessing this property should cache it in realtime-safe storage before beginning to render.

Bridged to the HostCallback_GetTransportState and HostCallback_GetTransportState2 callback members in kAudioUnitProperty_HostCallbacks.

pub unsafe fn setTransportStateBlock( &self, transport_state_block: AUHostTransportStateBlock, )

Available on crate feature block2 only.

Setter for transportStateBlock.

pub unsafe fn contextName(&self) -> Option<Retained<NSString>>

Information about the host context in which the audio unit is connected, for display in the audio unit’s view.

For example, a host could set “track 3” as the context, so that the audio unit’s view could then display to the user “My audio unit on track 3”.

Bridged to the v2 property kAudioUnitProperty_ContextName.

pub unsafe fn setContextName(&self, context_name: Option<&NSString>)

Setter for contextName.

pub unsafe fn migrateFromPlugin(&self) -> Retained<NSArray>

Information for migrating data from other audio plug-ins to the v3 Audio Unit architecture.

This can be used to migrate settings from an older Audio Unit; this allows manufacturers to deprecate older Audio Units and replace them with new ones. The data for the older Audio Unit is an array of NSData representing byte encoded AudioUnitOtherPluginDescs to migrate from. Can also be used to migrate from a v2 to a v3 Audio Unit.

Bridged to the v2 property kAudioUnitMigrateProperty_FromPlugin.

pub unsafe fn supportsMPE(&self) -> bool

Specifies whether an audio unit supports Multi-dimensional Polyphonic Expression.

Bridged to the v2 property kAudioUnitProperty_SupportsMPE.

pub unsafe fn channelMap(&self) -> Option<Retained<NSArray<NSNumber>>>

Specify a mapping of input channels to output channels.

Converter and input/output audio units may support re-ordering or splitting of input channels to output channels. The number of channels in the channel map is the number of channels of the destination (output format). The channel map entries contain a channel number of the source channel that should be mapped to that destination channel. If -1 is specified, then that destination channel will not contain any channel from the source (so it will be silent).

If the property value is nil, then the audio unit does not support this property.

Bridged to the v2 property kAudioOutputUnitProperty_ChannelMap.

pub unsafe fn setChannelMap(&self, channel_map: Option<&NSArray<NSNumber>>)

Setter for channelMap.

pub unsafe fn profileStateForCable_channel( &self, cable: u8, channel: MIDIChannelNumber, ) -> Retained<MIDICIProfileState>

Available on crate feature objc2-core-midi only.

Given a MIDI cable and channel number, return the supported MIDI-CI Profiles.

Parameter cable: The virtual MIDI cable for which the profiles are requested.

Parameter channel: The MIDI channel for which the profiles are requested.

Returns: A MIDICIProfileState object containing all the supported MIDI-CI profiles for this channel on this cable.

pub unsafe fn enableProfile_cable_onChannel_error( &self, profile: &MIDICIProfile, cable: u8, channel: MIDIChannelNumber, ) -> Result<(), Retained<NSError>>

Available on crate feature objc2-core-midi only.

Enable a MIDI-CI Profile on the specified cable/channel.

Parameter profile: The MIDI-CI profile to be enabled.

Parameter cable: The virtual MIDI cable.

Parameter channel: The MIDI channel.

Parameter outError: Returned in the event of failure.

Returns: YES for success. NO in the event of a failure, in which case the error is returned in outError.

pub unsafe fn disableProfile_cable_onChannel_error( &self, profile: &MIDICIProfile, cable: u8, channel: MIDIChannelNumber, ) -> Result<(), Retained<NSError>>

Available on crate feature objc2-core-midi only.

Disable a MIDI-CI Profile on the specified cable/channel.

Parameter profile: The MIDI-CI profile to be disabled.

Parameter cable: The virtual MIDI cable.

Parameter channel: The MIDI channel.

Parameter outError: Returned in the event of failure.

Returns: YES for success. NO in the event of a failure, in which case the error is returned in outError.

pub unsafe fn profileChangedBlock(&self) -> AUMIDICIProfileChangedBlock

Available on crate features block2 and objc2-core-midi only.

A block called when a device notifies that a MIDI-CI profile has been enabled or disabled.

Since enabling / disabling MIDI-CI profiles is an asynchronous operation, the host can set this block and the audio unit is expected to call it every time the state of a MIDI-CI profile has changed.

pub unsafe fn setProfileChangedBlock( &self, profile_changed_block: AUMIDICIProfileChangedBlock, )

Available on crate features block2 and objc2-core-midi only.

Setter for profileChangedBlock.

pub unsafe fn messageChannelFor( &self, channel_name: &NSString, ) -> Retained<ProtocolObject<dyn AUMessageChannel>>

Returns an object for bidirectional communication between an Audio Unit and its host.

Message channels provide a flexible way for custom data exchange between an Audio Unit and its host. An Audio Unit can support multiple message channels which are identified by the channelName. The message channel object’s lifetime is managed by the host. Message channel objects should be designed in such a way that they could outlive the AU that vended them. For further details see discussion for AUMessageChannel.

Parameter channelName: The name of the message channel to be returned by the Audio Unit if supported.

Returns: An object that conforms to the AUMessageChannel protocol.

impl AUAudioUnit

Methods declared on superclass NSObject.

pub unsafe fn new() -> Retained<Self>

impl AUAudioUnit

AUAudioInputOutputUnit. Additional methods for audio units which can do input/output.

These methods will fail if the audio unit is not an input/output audio unit.

pub unsafe fn canPerformInput(&self) -> bool

Whether the I/O device can perform input.

pub unsafe fn canPerformOutput(&self) -> bool

Whether the I/O device can perform output.

pub unsafe fn isInputEnabled(&self) -> bool

Flag enabling audio input from the unit.

Input is disabled by default. This must be set to YES if input audio is desired. Setting to YES will have no effect if canPerformInput is false.

pub unsafe fn setInputEnabled(&self, input_enabled: bool)

Setter for isInputEnabled.

pub unsafe fn isOutputEnabled(&self) -> bool

Flag enabling audio output from the unit.

Output is enabled by default. Setting to YES will have no effect if canPerformOutput is false.

pub unsafe fn setOutputEnabled(&self, output_enabled: bool)

Setter for isOutputEnabled.

pub unsafe fn outputProvider(&self) -> AURenderPullInputBlock

Available on crate features AUComponent and block2 and objc2-core-audio-types only.

The block that the output unit will call to get audio to send to the output.

This block must be set if output is enabled.

pub unsafe fn setOutputProvider(&self, output_provider: AURenderPullInputBlock)

Available on crate features AUComponent and block2 and objc2-core-audio-types only.

Setter for outputProvider.

pub unsafe fn inputHandler(&self) -> AUInputHandler

Available on crate features AUComponent and block2 and objc2-core-audio-types only.

The block that the output unit will call to notify when input is available.

See discussion for AUInputHandler.

pub unsafe fn setInputHandler(&self, input_handler: AUInputHandler)

Available on crate features AUComponent and block2 and objc2-core-audio-types only.

Setter for inputHandler.

pub unsafe fn deviceID(&self) -> AUAudioObjectID

Get the I/O hardware device.

pub unsafe fn setDeviceID_error( &self, device_id: AUAudioObjectID, ) -> Result<(), Retained<NSError>>

Set the I/O hardware device.

Parameter deviceID: The device to select.

Parameter outError: Returned in the event of failure.

pub unsafe fn deviceInputLatency(&self) -> NSTimeInterval

The audio device’s input latency, in seconds.

Bridged to the HAL property kAudioDevicePropertyLatency, which is implemented by v2 input/output units.

pub unsafe fn deviceOutputLatency(&self) -> NSTimeInterval

The audio device’s output latency, in seconds.

Bridged to the HAL property kAudioDevicePropertyLatency, which is implemented by v2 input/output units.

pub unsafe fn isRunning(&self) -> bool

The audio device’s running state.

pub unsafe fn startHardwareAndReturnError( &self, ) -> Result<(), Retained<NSError>>

Starts the audio hardware.

Parameter outError: Returned in the event of failure.

pub unsafe fn stopHardware(&self)

Stops the audio hardware.

impl AUAudioUnit

AUAudioUnitImplementation. Aspects of AUAudioUnit of interest only to subclassers.

pub unsafe fn registerSubclass_asComponentDescription_name_version( cls: &AnyClass, component_description: AudioComponentDescription, name: &NSString, version: u32, )

Available on crate features AUAudioUnitImplementation and AudioComponent only.

Register an audio unit component implemented as an AUAudioUnit subclass.

This method dynamically registers the supplied AUAudioUnit subclass with the Audio Component system, in the context of the current process (only). After registering the subclass, it can be instantiated via AudioComponentInstanceNew, -[AUAudioUnit initWithComponentDescription:options:error:], and via any other API’s which instantiate audio units via their component descriptions (e.g. <AudioToolbox /AUGraph.h>, or <AVFoundation /AVAudioUnitEffect.h>).

pub unsafe fn MIDIOutputBufferSizeHint(&self) -> NSInteger

Available on crate feature AUAudioUnitImplementation only.

Hint to control the size of the allocated buffer for outgoing MIDI events.

This property allows the plug-in to provide a hint to the framework regarding the size of its outgoing MIDI data buffer.

If the plug-in produces more MIDI output data than the default size of the allocated buffer, then the plug-in can provide this property to increase the size of this buffer.

The value represents the number of 3-byte Legacy MIDI messages that fit into the buffer or a single MIDIEventList containing 1 MIDIEventPacket of 2 words when using MIDI 2.0 (MIDIEventList based API’s).

This property is set to the default value by the framework.

In case of kAudioUnitErr_MIDIOutputBufferFull errors caused by producing too much MIDI output in one render call, set this property to increase the buffer.

This only provides a recommendation to the framework.

Bridged to kAudioUnitProperty_MIDIOutputBufferSizeHint.

pub unsafe fn setMIDIOutputBufferSizeHint( &self, midi_output_buffer_size_hint: NSInteger, )

Available on crate feature AUAudioUnitImplementation only.

Setter for MIDIOutputBufferSizeHint.

pub unsafe fn setRenderResourcesAllocated(&self, flag: bool)

Available on crate feature AUAudioUnitImplementation only.

Parameter flag: In the base class implementation of allocateRenderResourcesAndReturnError:, the property renderResourcesAllocated is set to YES. If allocateRenderResourcesAndReturnError: should fail in a subclass, subclassers must use this method to set renderResourcesAllocated to NO.

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AUAudioUnit> for AUAudioUnit

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<AUAudioUnit> for AUAudioUnitV2Bridge

Available on crate feature AUAudioUnitImplementation only.

fn as_ref(&self) -> &AUAudioUnit

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<AnyObject> for AUAudioUnit

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSObject> for AUAudioUnit

fn as_ref(&self) -> &NSObject

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AUAudioUnit> for AUAudioUnitV2Bridge

Available on crate feature AUAudioUnitImplementation only.

fn borrow(&self) -> &AUAudioUnit

Immutably borrows from an owned value.

impl Borrow<AnyObject> for AUAudioUnit

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for AUAudioUnit

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for AUAudioUnit

const NAME: &'static str = "AUAudioUnit"

The name of the Objective-C class that this type represents.

type Super = NSObject

The superclass of this class.

type ThreadKind = <<AUAudioUnit as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl Debug for AUAudioUnit

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for AUAudioUnit

type Target = NSObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for AUAudioUnit

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for AUAudioUnit

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for AUAudioUnit

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl PartialEq for AUAudioUnit

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for AUAudioUnit

const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl DowncastTarget for AUAudioUnit

impl Eq for AUAudioUnit