Struct AVAudioFormat

Source

pub struct AVAudioFormat { /* private fields */ }

Available on crate feature AVAudioFormat only.

Expand description

A representation of an audio format.

AVAudioFormat wraps a Core Audio AudioStreamBasicDescription struct, with convenience initializers and accessors for common formats, including Core Audio’s standard deinterleaved 32-bit floating point.

Instances of this class are immutable.

Implementations§

Source §

impl AVAudioFormat

Source

pub unsafe fn initWithStreamDescription( this: Allocated<Self>, asbd: NonNull<AudioStreamBasicDescription>, ) -> Option<Retained<Self>>

Available on crate feature objc2-core-audio-types only.

Initialize from an AudioStreamBasicDescription.

Parameter asbd: the AudioStreamBasicDescription

If the format specifies more than 2 channels, this method fails (returns nil).

§Safety

asbd must be a valid pointer.

Source

pub unsafe fn initWithStreamDescription_channelLayout( this: Allocated<Self>, asbd: NonNull<AudioStreamBasicDescription>, layout: Option<&AVAudioChannelLayout>, ) -> Option<Retained<Self>>

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

Initialize from an AudioStreamBasicDescription and optional channel layout.

Parameter asbd: the AudioStreamBasicDescription

Parameter layout: the channel layout. Can be nil only if asbd specifies 1 or 2 channels.

If the format specifies more than 2 channels, this method fails (returns nil) unless layout is non-nil.

§Safety

asbd must be a valid pointer.

Source

pub unsafe fn initStandardFormatWithSampleRate_channels( this: Allocated<Self>, sample_rate: c_double, channels: AVAudioChannelCount, ) -> Option<Retained<Self>>

Available on crate feature AVAudioTypes only.

Initialize to deinterleaved float with the specified sample rate and channel count.

Parameter sampleRate: the sample rate

Parameter channels: the channel count

If the format specifies more than 2 channels, this method fails (returns nil).

Source

pub unsafe fn initStandardFormatWithSampleRate_channelLayout( this: Allocated<Self>, sample_rate: c_double, layout: &AVAudioChannelLayout, ) -> Retained<Self>

Available on crate feature AVAudioChannelLayout only.

Initialize to deinterleaved float with the specified sample rate and channel layout.

Parameter sampleRate: the sample rate

Parameter layout: the channel layout. must not be nil.

Source

pub unsafe fn initWithCommonFormat_sampleRate_channels_interleaved( this: Allocated<Self>, format: AVAudioCommonFormat, sample_rate: c_double, channels: AVAudioChannelCount, interleaved: bool, ) -> Option<Retained<Self>>

Available on crate feature AVAudioTypes only.

Initialize to float with the specified sample rate, channel count and interleavedness.

Parameter format: the common format type

Parameter sampleRate: the sample rate

Parameter channels: the channel count

Parameter interleaved: true if interleaved

If the format specifies more than 2 channels, this method fails (returns nil).

Source

pub unsafe fn initWithCommonFormat_sampleRate_interleaved_channelLayout( this: Allocated<Self>, format: AVAudioCommonFormat, sample_rate: c_double, interleaved: bool, layout: &AVAudioChannelLayout, ) -> Retained<Self>

Available on crate feature AVAudioChannelLayout only.

Initialize to float with the specified sample rate, channel layout and interleavedness.

Parameter format: the common format type

Parameter sampleRate: the sample rate

Parameter interleaved: true if interleaved

Parameter layout: the channel layout. must not be nil.

Source

pub unsafe fn initWithSettings( this: Allocated<Self>, settings: &NSDictionary<NSString, AnyObject>, ) -> Option<Retained<Self>>

Initialize using a settings dictionary.

See AVAudioSettings.h. Note that many settings dictionary elements pertain to encoder settings, not the basic format, and will be ignored.

Returns nil if a format cannot be constructed with the provided settings, e.g. when:

AVNumberOfChannelsKey specifies more than 2 channels, but AVChannelLayoutKey hasn’t been specified or the layout does not match
AVLinearPCMBitDepthKey for linear PCM format specifies less than 8 or greater than 32 bits
values for the keys are not of the expected types

§Safety

settings generic should be of the correct type.

Source

pub unsafe fn initWithCMAudioFormatDescription( this: Allocated<Self>, format_description: &CMAudioFormatDescription, ) -> Retained<Self>

Available on crate feature objc2-core-media only.

initialize from a CMAudioFormatDescriptionRef.

Parameter formatDescription: the CMAudioFormatDescriptionRef.

If formatDescription is invalid, this method fails (returns nil).

Source

pub unsafe fn isEqual(&self, object: &AnyObject) -> bool

Determine whether another format is functionally equivalent.

Parameter object: the format to compare against

For PCM, interleavedness is ignored for mono. Differences in the AudioStreamBasicDescription alignment and packedness are ignored when they are not significant (e.g. with 1 channel, 2 bytes per frame and 16 bits per channel, neither alignment, the format is implicitly packed and can be interpreted as either high- or low-aligned.) For AVAudioChannelLayout, a layout with standard mono/stereo tag is considered to be equivalent to a nil layout. Otherwise, the layouts are compared for equality.

§Safety

object should be of the correct type.

Source

pub unsafe fn isStandard(&self) -> bool

Describes whether the format is deinterleaved native-endian float.

This property is not atomic.

§Safety

This might not be thread-safe.

Source

pub unsafe fn commonFormat(&self) -> AVAudioCommonFormat

An AVAudioCommonFormat identifying the format

This property is not atomic.

§Safety

This might not be thread-safe.

Source

pub unsafe fn channelCount(&self) -> AVAudioChannelCount

Available on crate feature AVAudioTypes only.

The number of channels of audio data.

This property is not atomic.

§Safety

This might not be thread-safe.

Source

pub unsafe fn sampleRate(&self) -> c_double

A sampling rate in Hertz.

This property is not atomic.

§Safety

This might not be thread-safe.

Source

pub unsafe fn isInterleaved(&self) -> bool

Describes whether the samples are interleaved.

For non-PCM formats, the value is undefined.

This property is not atomic.

§Safety

This might not be thread-safe.

Source

pub unsafe fn streamDescription(&self) -> NonNull<AudioStreamBasicDescription>

Available on crate feature objc2-core-audio-types only.

Returns the AudioStreamBasicDescription, for use with lower-level audio API’s.

This property is not atomic.

§Safety

This might not be thread-safe.

Source

pub unsafe fn channelLayout(&self) -> Option<Retained<AVAudioChannelLayout>>

Available on crate feature AVAudioChannelLayout only.

The underlying AVAudioChannelLayout, if any.

Only formats with more than 2 channels are required to have channel layouts.

This property is not atomic.

§Safety

This might not be thread-safe.

Source

pub unsafe fn magicCookie(&self) -> Option<Retained<NSData>>

The underlying magic cookie, if any.

A magic cookie contains metadata associated with encoders and decoders. Encoders produce a magic cookie, and some decoders require a magic cookie to decode properly.

This property is not atomic.

§Safety

This might not be thread-safe.

Source

pub unsafe fn setMagicCookie(&self, magic_cookie: Option<&NSData>)

Setter for magicCookie.

§Safety

This might not be thread-safe.

Source

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

Returns the format represented as a dictionary with keys from AVAudioSettings.h.

This property is not atomic.

§Safety

This might not be thread-safe.

Source

pub unsafe fn formatDescription(&self) -> Retained<CMAudioFormatDescription>

Available on crate feature objc2-core-media only.

Converts to a CMAudioFormatDescriptionRef, for use with Core Media API’s.

This property is not atomic.

§Safety

This might not be thread-safe.

Source §

impl AVAudioFormat

Methods declared on superclass NSObject.

Source

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

Source

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

Methods from Deref<Target = NSObject>§

Source

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

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>§

Source

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

Source

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.

Source

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