Struct AVAudioSequencer

Source

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

Available on crate feature AVAudioSequencer only.

Expand description

A collection of MIDI events organized into AVMusicTracks, plus a player to play back the events.

Implementations§

Source §

impl AVAudioSequencer

Source

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

Initialize a new sequencer, which will not be connected to an audio engine.

This is used to create a sequencer whose tracks will only send events to external MIDI endpoints.

Source

pub unsafe fn initWithAudioEngine( this: Allocated<Self>, engine: &AVAudioEngine, ) -> Retained<Self>

Available on crate feature AVAudioEngine only.

Initialize a new sequencer, handing it the audio engine.

Source

pub unsafe fn loadFromURL_options_error( &self, file_url: &NSURL, options: AVMusicSequenceLoadOptions, ) -> Result<(), Retained<NSError>>

Load the file referenced by the URL and add the events to the sequence

Parameter fileURL: the URL to the file

Parameter options: determines how the file’s contents are mapped to tracks inside the sequence

Parameter outError: on exit, if an error occurs, a description of the error

Source

pub unsafe fn loadFromData_options_error( &self, data: &NSData, options: AVMusicSequenceLoadOptions, ) -> Result<(), Retained<NSError>>

Parse the data and add the its events to the sequence

Parameter data: the data to load from

Parameter options: determines how the contents are mapped to tracks inside the sequence

Parameter outError: on exit, if an error occurs, a description of the error

Source

pub unsafe fn writeToURL_SMPTEResolution_replaceExisting_error( &self, file_url: &NSURL, resolution: NSInteger, replace: bool, ) -> Result<(), Retained<NSError>>

Create and write a MIDI file containing the events and complete state of the sequence

Parameter fileURL: the path for the file to be created

Parameter resolution: the relationship between “tick” and quarter note for saving to a Standard MIDI File - pass in zero to use default - this will be the value that is currently set on the tempo track

Parameter replace: if the file already exists, YES will cause it to be overwritten with the new data. Otherwise the call will fail with a permission error.

Parameter outError: on exit, if an error occurs, a description of the error

A MIDI file saved via this method will contain not only the complete MIDI content of the sequence, but also the state of all tracks, including muting, loop points and enablement, etc. It will also contain all non-MIDI AVMusicEvent types which had been added to the sequence’s track.

MIDI files are normally beat based, but can also have a SMPTE (or real-time rather than beat time) representation. The relationship between “tick” and quarter note for saving to Standard MIDI File

pass in zero to use default - this will be the value that is currently set on the tempo track

Source

pub unsafe fn secondsForBeats(&self, beats: AVMusicTimeStamp) -> NSTimeInterval

Available on crate feature AVAudioTypes only.

Get the time in seconds for the given beat position (timestamp) in the AVMusicTrack

Source

pub unsafe fn beatsForSeconds( &self, seconds: NSTimeInterval, ) -> AVMusicTimeStamp

Available on crate feature AVAudioTypes only.

Get the beat position (timestamp) for the given time in the AVMusicTrack

Source

pub unsafe fn reverseEvents(&self)

Reverse the order of all events in all AVMusicTracks, including the tempo track

Source

pub unsafe fn createAndAppendTrack(&self) -> Retained<AVMusicTrack>

Create a new AVMusicTrack and append it to the AVMusicSequencer’s list

Source

pub unsafe fn removeTrack(&self, track: &AVMusicTrack) -> bool

Remove the given AVMusicTrack from the AVMusicSequencer.

This does not destroy the AVMusicTrack because it may be re-used.

Source

pub unsafe fn setUserCallback( &self, user_callback: AVAudioSequencerUserCallback, )

Available on crate features AVAudioTypes and block2 only.

Add a block which will be called each time the AVAudioSequencer encounters an AVMusicUserEvent during playback.

The same callback is called for events which occur on any track in the sequencer.

Set the block to nil to disable it.

Source

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

An NSArray containing all the AVMusicTracks in the sequence

This list will not include the tempo track.

Source

pub unsafe fn tempoTrack(&self) -> Retained<AVMusicTrack>

The tempo track

Each AVMusicSequence has a single tempo track.

All tempo events read from external MIDI files are placed into this track (as well as other appropriate events (e.g., the time signature meta event from the file).

The tempo track can be edited and iterated upon as any other track.

Non-tempo-related events will generate exceptions if added.

Source

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

A dictionary containing meta-data derived from a sequence

The dictionary can contain one or more of the values accessible via the AVAudioSequencerInfoDictionaryKeys.

Source §

impl AVAudioSequencer

Methods declared on superclass NSObject.

Source

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

Source §

impl AVAudioSequencer

AVAudioSequencer_Player.

Source

pub unsafe fn currentPositionInSeconds(&self) -> NSTimeInterval

The current playback position in seconds

Setting this positions the sequencer’s player to the specified time. This can be set while the player is playing, in which case playback will resume at the new position.

Source

pub unsafe fn setCurrentPositionInSeconds( &self, current_position_in_seconds: NSTimeInterval, )

Setter for currentPositionInSeconds.

Source

pub unsafe fn currentPositionInBeats(&self) -> NSTimeInterval

The current playback position in beats

Setting this positions the sequencer’s player to the specified beat. This can be set while the player is playing, in which case playback will resume at the new position.

Source

pub unsafe fn setCurrentPositionInBeats( &self, current_position_in_beats: NSTimeInterval, )

Setter for currentPositionInBeats.

Source

pub unsafe fn isPlaying(&self) -> bool

Indicates whether or not the sequencer’s player is playing

Returns TRUE if the sequencer’s player has been started and not stopped. It may have “played” past the end of the events in the sequence, but it is still considered to be playing (and its time value increasing) until it is explicitly stopped.

Source

pub unsafe fn rate(&self) -> c_float

The playback rate of the sequencer’s player

1.0 is normal playback rate. Rate must be > 0.0.

Source

pub unsafe fn setRate(&self, rate: c_float)

Setter for rate.

Source

pub unsafe fn prepareToPlay(&self)

Get ready to play the sequence by prerolling all events

Happens automatically on play if it has not already been called, but may produce a delay in startup.

Source

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

Start the sequencer’s player

If the AVAudioSequencer has not been prerolled, it will pre-roll itself and then start. When the sequencer is associated with an audio engine, the sequencer’s player will only play if the audio engine is running.

Source

pub unsafe fn stop(&self)

Stop the sequencer’s player

Stopping the player leaves it in an un-prerolled state, but stores the playback position so that a subsequent call to startAndReturnError will resume where it left off. This action will not stop an associated audio engine.

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.

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