Struct AVSpeechSynthesisProviderAudioUnit 

pub struct AVSpeechSynthesisProviderAudioUnit { /* private fields */ }

Available on crate feature AVSpeechSynthesisProvider and crate feature objc2-audio-toolbox and non-watchOS only.

Apple’s documentation

Implementations

impl AVSpeechSynthesisProviderAudioUnit

pub unsafe fn speechVoices( &self, ) -> Retained<NSArray<AVSpeechSynthesisProviderVoice>>

Returns the voices this audio unit has available and ready for synthesis.

This method should fetch and return the voices ready to synthesize that a user can select from (usually through Settings). Required for speech synthesizer audio unit extensions. An audio unit with a dynamic list of voices can override this property’s getter to perform a more complex fetch.

pub unsafe fn setSpeechVoices( &self, speech_voices: &NSArray<AVSpeechSynthesisProviderVoice>, )

Setter for speechVoices.

pub unsafe fn speechSynthesisOutputMetadataBlock( &self, ) -> AVSpeechSynthesisProviderOutputBlock

Available on crate features AVSpeechSynthesis and block2 only.

A property set by the host that is called by the audio unit to supply metadata for a speech request.

A synthesizer should call this method when it has produced relevant data to the audio buffers it is sending back to the host. In some cases speech output may be delayed until these markers are delivered. For example, word highlighting depends on marker data from synthesizers in order to properly time which words are highlighted. Many speech synthesizers generate this information on the fly, while synthesizing the audio. The array of markers can reference future audio buffers that have yet to be delivered.

There may be cases in which marker data is not fully known until further audio processing is done. In these cases, and other casers where marker data has changed, calling this block with marker data that contains perviously delivered audio buffer ranges will replace that audio buffer range’s marker data, as it will be considered stale.

Safety

• The returned block’s argument 1 must be a valid pointer.
• The returned block’s argument 2 must be a valid pointer.

pub unsafe fn setSpeechSynthesisOutputMetadataBlock( &self, speech_synthesis_output_metadata_block: AVSpeechSynthesisProviderOutputBlock, )

Available on crate features AVSpeechSynthesis and block2 only.

Setter for speechSynthesisOutputMetadataBlock.

This is copied when set.

Safety

speech_synthesis_output_metadata_block must be a valid pointer or null.

pub unsafe fn synthesizeSpeechRequest( &self, speech_request: &AVSpeechSynthesisProviderRequest, )

Sends a new speech request to be synthesized

Sends a new speech request to the synthesizer to render. When the synthesizer audio unit is finished generating audio buffers for the speech request, it should indicate this within its internal render block, AUInternalRenderBlock,specifically through the AudioUnitRenderActionFlagsflag kAudioOfflineUnitRenderAction_Complete.

pub unsafe fn cancelSpeechRequest(&self)

Informs the audio unit that the speech request job should be discarded.

impl AVSpeechSynthesisProviderAudioUnit

Methods declared on superclass 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>>

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

Convenience initializer (omits options).

impl AVSpeechSynthesisProviderAudioUnit

Methods declared on superclass NSObject.

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

Methods from Deref<Target = AUAudioUnit>

pub unsafe fn componentDescription(&self) -> AudioComponentDescription

The AudioComponentDescription with which the audio unit was created.

pub unsafe fn component(&self) -> *mut OpaqueAudioComponent

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 removeRenderObserver(&self, token: isize)

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

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: u32)

Setter for maximumFramesToRender.

pub unsafe fn parametersForOverviewWithCount( &self, count: isize, ) -> 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) -> isize

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, ) -> *mut Block<dyn Fn(i64, u8, isize, NonNull<u8>)>

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.

Safety

The returned block’s argument 4 must be a valid pointer.

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, ) -> *mut Block<dyn Fn(i64, u8, isize, NonNull<u8>) -> i32>

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.

Safety

The returned block’s argument 4 must be a valid pointer.

pub unsafe fn setMIDIOutputEventBlock( &self, midi_output_event_block: *mut Block<dyn Fn(i64, u8, isize, NonNull<u8>) -> i32>, )

Setter for MIDIOutputEventBlock.

This is copied when set.

Safety

midi_output_event_block must be a valid pointer or null.

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

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

Setter for fullState.

This is copied when set.

Safety

full_state generic should be of the correct type.

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

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

Setter for fullStateForDocument.

This is copied when set.

Safety

full_state_for_document generic should be of the correct type.

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>>, 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) -> f64

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

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

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: isize)

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, ) -> *mut Block<dyn Fn(*mut f64, *mut f64, *mut isize, *mut f64, *mut isize, *mut f64) -> Bool>

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.

Safety

• The returned block’s argument 1 must be a valid pointer or null.
• The returned block’s argument 2 must be a valid pointer or null.
• The returned block’s argument 3 must be a valid pointer or null.
• The returned block’s argument 4 must be a valid pointer or null.
• The returned block’s argument 5 must be a valid pointer or null.
• The returned block’s argument 6 must be a valid pointer or null.

pub unsafe fn setMusicalContextBlock( &self, musical_context_block: *mut Block<dyn Fn(*mut f64, *mut f64, *mut isize, *mut f64, *mut isize, *mut f64) -> Bool>, )

Setter for musicalContextBlock.

This is copied when set.

Safety

musical_context_block must be a valid pointer or null.

pub unsafe fn transportStateBlock( &self, ) -> *mut Block<dyn Fn(*mut AUHostTransportStateFlags, *mut f64, *mut f64, *mut f64) -> Bool>

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.

Safety

• The returned block’s argument 1 must be a valid pointer or null.
• The returned block’s argument 2 must be a valid pointer or null.
• The returned block’s argument 3 must be a valid pointer or null.
• The returned block’s argument 4 must be a valid pointer or null.

pub unsafe fn setTransportStateBlock( &self, transport_state_block: *mut Block<dyn Fn(*mut AUHostTransportStateFlags, *mut f64, *mut f64, *mut f64) -> Bool>, )

Setter for transportStateBlock.

This is copied when set.

Safety

transport_state_block must be a valid pointer or null.

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.

This is copied when set.

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.

This is copied when set.

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.

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 deviceID(&self) -> u32

Get the I/O hardware device.

pub unsafe fn setDeviceID_error( &self, device_id: u32, ) -> 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) -> f64

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

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.

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 AVSpeechSynthesisProviderAudioUnit

fn as_ref(&self) -> &AUAudioUnit

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

impl AsRef<AVSpeechSynthesisProviderAudioUnit> for AVSpeechSynthesisProviderAudioUnit

fn as_ref(&self) -> &Self

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

impl AsRef<AnyObject> for AVSpeechSynthesisProviderAudioUnit

fn as_ref(&self) -> &AnyObject

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

impl AsRef<NSObject> for AVSpeechSynthesisProviderAudioUnit

fn as_ref(&self) -> &NSObject

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

impl Borrow<AUAudioUnit> for AVSpeechSynthesisProviderAudioUnit

fn borrow(&self) -> &AUAudioUnit

Immutably borrows from an owned value.

impl Borrow<AnyObject> for AVSpeechSynthesisProviderAudioUnit

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for AVSpeechSynthesisProviderAudioUnit

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for AVSpeechSynthesisProviderAudioUnit

const NAME: &'static str = "AVSpeechSynthesisProviderAudioUnit"

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

type Super = AUAudioUnit

The superclass of this class.

type ThreadKind = <<AVSpeechSynthesisProviderAudioUnit 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 AVSpeechSynthesisProviderAudioUnit

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

Formats the value using the given formatter.

impl Deref for AVSpeechSynthesisProviderAudioUnit

type Target = AUAudioUnit

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for AVSpeechSynthesisProviderAudioUnit

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 AVSpeechSynthesisProviderAudioUnit

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for AVSpeechSynthesisProviderAudioUnit

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 AVSpeechSynthesisProviderAudioUnit

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 AVSpeechSynthesisProviderAudioUnit

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

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

impl DowncastTarget for AVSpeechSynthesisProviderAudioUnit

impl Eq for AVSpeechSynthesisProviderAudioUnit