MIKMIDISequencer

Objective-C

@interface MIKMIDISequencer : NSObject

Swift

class MIKMIDISequencer : NSObject

MIKMIDISequencer can be used to play and record to an MIKMIDISequence.

Note

Recording and using the click track may not yet be fully functional, and should be considered experimental in the meantime. Please submit issues and/or pull requests when you find areas that don’t work as expected.

Creation

  • Convenience method for creating a new MIKMIDISequencer instance with an empty sequence.

    Declaration

    Objective-C

    + (nonnull instancetype)sequencer;

    Return Value

    An initialized MIKMIDISequencer.

  • Initializes and returns a new MIKMIDISequencer ready to playback and record to the specified sequence.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithSequence:(nonnull MIKMIDISequence *)sequence;

    Swift

    init(sequence: MIKMIDISequence)

    Parameters

    sequence

    The sequence to playback and record to.

    Return Value

    An initialized MIKMIDISequencer.

  • Convenience method for creating a new MIKMIDISequencer ready to playback and record to the specified sequence.

    Declaration

    Objective-C

    + (nonnull instancetype)sequencerWithSequence:
    (nonnull MIKMIDISequence *)sequence;

    Parameters

    sequence

    The sequence to playback and record to.

    Return Value

    An initialized MIKMIDISequencer.

Playback

  • Starts playback from the beginning of the sequence.

    Declaration

    Objective-C

    - (void)startPlayback;

    Swift

    func startPlayback()

  • Starts playback from the specified time stamp.

    Declaration

    Objective-C

    - (void)startPlaybackAtTimeStamp:(MusicTimeStamp)timeStamp;

    Swift

    func startPlayback(atTimeStamp timeStamp: MusicTimeStamp)

    Parameters

    timeStamp

    The position in the sequence to begin playback from.

  • Starts playback from the specified MusicTimeStamp at the specified MIDITimeStamp. This could be useful if you need to synchronize the playback with another source such as an audio track, or another MIKMIDISequencer instance.

    Declaration

    Objective-C

    - (void)startPlaybackAtTimeStamp:(MusicTimeStamp)timeStamp
                   MIDITimeStamp:(MIDITimeStamp)midiTimeStamp;

    Swift

    func startPlayback(atTimeStamp timeStamp: MusicTimeStamp, midiTimeStamp: MIDITimeStamp)

    Parameters

    timeStamp

    The position in the sequence to begin playback from.
    midiTimeStamp

    The MIDITimeStamp to begin playback at.

  • Starts playback from the position returned by -currentTimeStamp.

    See

    currentTimeStamp

    Declaration

    Objective-C

    - (void)resumePlayback;

    Swift

    func resumePlayback()

  • Stops all playback and recording.

    Declaration

    Objective-C

    - (void)stop;

    Swift

    func stop()

  • Sends any pending note offs for the command scheduler immeidately. This can be useful if you are changing the notes in the MIDI track and you want the old notes to immediately stop rather than play until their original end time stamp.

    Declaration

    Objective-C

    - (void)stopAllPlayingNotesForCommandScheduler:
    (nonnull id<MIKMIDICommandScheduler>)scheduler;
  • Allows subclasses to modify the MIDI commands that are about to be
scheduled with a command scheduler.

- parameter: commandsToBeScheduled An array of MIKMIDICommands that are about
to be scheduled.

- parameter: scheduler The command scheduler the commands will be scheduled with
after they are modified.

- note: You should not call this method directly. It is made public solely to
give subclasses a chance to alter or override any MIDI commands parsed from the
MIDI sequence before they get sent to their destination endpoint.

    Declaration

    Objective-C

    - (nonnull NSArray<MIKMIDICommand *> *)
    modifiedMIDICommandsFromCommandsToBeScheduled:
        (nonnull NSArray<MIKMIDICommand *> *)commandsToBeScheduled
                              forCommandScheduler:
                                  (nonnull id<MIKMIDICommandScheduler>)
                                      scheduler;
  • Sets the loopStartTimeStamp and loopEndTimeStamp properties.

- parameter: loopStartTimeStamp The MusicTimeStamp to begin looping at.

- parameter: loopEndTimeStamp The MusicTimeStamp to end looping at. To have
the loop end at the end of the sequence, regardless of sequence length, 
pass in MIKMIDISequencerEndOfSequenceLoopEndTimeStamp.

- see: loopStartTimeStamp
- see: loopEndTimeStamp
- see: loop
- see: looping

    Declaration

    Objective-C

    - (void)setLoopStartTimeStamp:(MusicTimeStamp)loopStartTimeStamp
                 endTimeStamp:(MusicTimeStamp)loopEndTimeStamp;

    Swift

    func setLoopStartTimeStamp(_ loopStartTimeStamp: MusicTimeStamp, endTimeStamp loopEndTimeStamp: MusicTimeStamp)

Recording

  • Starts playback from the beginning of the sequence minus the value returned by -preRoll, and enables recording of incoming events to the record enabled tracks.

    See

    preRoll

    See

    recordEnabledTracks

    Declaration

    Objective-C

    - (void)startRecording;

    Swift

    func startRecording()

  • Starts playback from the specified time stamp minus the value returned by -preRoll, and enables recording of incoming events to the record enabled tracks.

    See

    preRoll

    See

    recordEnabledTracks

    Declaration

    Objective-C

    - (void)startRecordingAtTimeStamp:(MusicTimeStamp)timeStamp;

    Swift

    func startRecording(atTimeStamp timeStamp: MusicTimeStamp)

  • Starts playback from the specified MusicTimeStamp minus the value returned by -preRoll at the specified MIDITimeStamp, and enables recording of incoming events to the record enabled tracks.

    See

    preRoll

    See

    recordEnabledTracks

    Declaration

    Objective-C

    - (void)startRecordingAtTimeStamp:(MusicTimeStamp)timeStamp
                    MIDITimeStamp:(MIDITimeStamp)midiTimeStamp;

    Swift

    func startRecording(atTimeStamp timeStamp: MusicTimeStamp, midiTimeStamp: MIDITimeStamp)

  • Starts playback from the position returned by -currentTimeStamp minus the value returned by -preRoll, and enables recording of incoming events to the record enabled tracks.

    See

    preRoll

    See

    recordEnabledTracks

    Declaration

    Objective-C

    - (void)resumeRecording;

    Swift

    func resumeRecording()

  • Records a MIDI command to the record enabled tracks.

    Note

    When recording is NO, calls to this method will do nothing.

    See

    recording

    See

    recordEnabledTracks

    Declaration

    Objective-C

    - (void)recordMIDICommand:(nonnull MIKMIDICommand *)command;

    Swift

    func record(_ command: MIKMIDICommand)

    Parameters

    command

    The MIDI command to record to the record enabled tracks.

Configuration

  • Sets the command scheduler for a track in the sequencer’s sequence. Calling this method is optional. By default, the sequencer will setup internal synthesizers so that playback “just works”.

    Note

    If track is not contained by the receiver’s sequence, this method does nothing.

    Declaration

    Objective-C

    - (void)setCommandScheduler:
            (nullable id<MIKMIDICommandScheduler>)commandScheduler
                   forTrack:(nonnull MIKMIDITrack *)track;

    Parameters

    commandScheduler

    An object that conforms to MIKMIDICommandScheduler with which events in track should be scheduled during playback. MIKMIDIDestinationEndpoint and MIKMIDISynthesizer both conform to MIKMIDICommandScheduler, so they can be used here. Pass nil to remove an existing command scheduler.
    track

    An MIKMIDITrack instance.

  • Returns the command scheduler for a track in the sequencer’s sequence.

    MIKMIDISequencer will automatically create its own default synthesizers connected for any tracks not configured manually. This means that even if you haven’t called -setCommandScheduler:forTrack:, you can use this method to retrieve the default command scheduler for a given track.

    Note

    If track is not contained by the receiver’s sequence, this method returns nil.

    See

    -setCommandScheduler:forTrack:

    See

    -builtinSynthesizerForTrack:

    See

    createSynthsIfNeeded

    Declaration

    Objective-C

    - (nullable id<MIKMIDICommandScheduler>)commandSchedulerForTrack:
    (nonnull MIKMIDITrack *)track;

    Parameters

    track

    An MIKMIDITrack instance.

    Return Value

    The command scheduler associated with track, or nil if one can’t be found.

  • Returns synthesizer the receiver will use to synthesize MIDI during playback for any tracks whose MIDI has not been routed to a custom scheduler using -setCommandScheduler:forTrack:. For tracks where a custom scheduler has been set, this method returns nil.

    The caller is free to reconfigure the synthesizer(s) returned by this method, e.g. to load a custom soundfont file or select a different instrument.

    Declaration

    Objective-C

    - (nullable MIKMIDISynthesizer *)builtinSynthesizerForTrack:
    (nonnull MIKMIDITrack *)track;

    Swift

    func builtinSynthesizer(for track: MIKMIDITrack) -> MIKMIDISynthesizer?

    Parameters

    track

    The track for which the builtin synthesizer is desired.

    Return Value

    An MIKMIDISynthesizer instance, or nil if a builtin synthesizer for track doesn’t exist.

Properties

  • The sequence to playback and record to.

    Declaration

    Objective-C

    @property (nonatomic, strong) MIKMIDISequence *_Nonnull sequence;

    Swift

    var sequence: MIKMIDISequence { get set }
  • Whether or not the sequencer is currently playing. This can be observed with KVO.

    See

    recording

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isPlaying) BOOL playing;

    Swift

    var isPlaying: Bool { get }

  • Whether or not the sequence is currently playing and is record enabled. This can be observed with KVO.

    Note

    When recording is YES, events will only be recorded to the tracks specified by -recordEnabledTracks.

    See

    playing

    See

    recordEnabledTracks

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isRecording) BOOL recording;

    Swift

    var isRecording: Bool { get }

  • The tempo the sequencer should play its sequence at. When set to 0, the sequence will be played using the tempo events from the sequence’s tempo track. Default is 0.

    Declaration

    Objective-C

    @property (nonatomic) Float64 tempo;

    Swift

    var tempo: Float64 { get set }

  • The length the that the sequencer should consider its sequence to be. When set to 0, the sequencer will use sequence.length instead.

    This can be handy if you want to alter the duration of playback to be shorter or longer than the sequence’s length without affecting the sequence itself.

    Declaration

    Objective-C

    @property (nonatomic) MusicTimeStamp overriddenSequenceLength;

    Swift

    var overriddenSequenceLength: MusicTimeStamp { get set }

  • The current playback position in the sequence.

    Note

    This property is not observable using Key Value Observing.

    Declaration

    Objective-C

    @property (nonatomic) MusicTimeStamp currentTimeStamp;

    Swift

    var currentTimeStamp: MusicTimeStamp { get set }

  • The amount of time (in beats) to pre-roll the sequence before recording. For example, if preRoll is set to 4 and you begin recording, the sequence will start 4 beats ahead of the specified recording position.

    The default is 4.

    Declaration

    Objective-C

    @property (nonatomic) MusicTimeStamp preRoll;

    Swift

    var preRoll: MusicTimeStamp { get set }

  • Whether or not playback should loop when between loopStartTimeStamp and loopEndTimeStamp.

    See

    loopStartTimeStamp

    See

    loopEndTimeStamp

    See

    looping

    Declaration

    Objective-C

    @property (nonatomic, getter=shouldLoop) BOOL loop;

    Swift

    var shouldLoop: Bool { get set }

  • Whether or not playback is currently looping between loopStartTimeStamp and loopEndTimeStamp.

    Note

    If loop is YES, and playback starts before loopStartTimeStamp, looping will be NO until currentTimeStamp reaches loopStartTimeStamp. At that point, looped playback will begin and the looping property will become YES. Conversely, if playback starts after loopEndTimeStamp, then the looped area of playback will never be reached and looping will remain NO.

    See

    loop

    See

    loopStartTimeStamp

    See

    loopEndTimeStamp

    See

    -setLoopStartTimeStamp:loopEndTimeStamp:

    See

    currentTimeStamp

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isLooping) BOOL looping;

    Swift

    var isLooping: Bool { get }

  • The loop’s beginning time stamp during looped playback.

    - - see: --setLoopStartTimeStamp:loopEndTimeStamp:

    Declaration

    Objective-C

    @property (nonatomic, readonly) MusicTimeStamp loopStartTimeStamp;

    Swift

    var loopStartTimeStamp: MusicTimeStamp { get }

  • The loop’s ending time stamp during looped playback, or MIKMIDISequencerEndOfSequenceLoopEndTimeStamp.

    - - note: When this is set to MIKMIDISequencerEndOfSequenceLoopEndTimeStamp
the loopEndTimeStamp will be treated as if it is set to the length of the
sequence. The default is MIKMIDISequencerEndOfSequenceLoopEndTimeStamp.
    • - see: effectiveLoopEndTimeStamp

      See

      -setLoopStartTimeStamp:loopEndTimeStamp:

    Declaration

    Objective-C

    @property (nonatomic, readonly) MusicTimeStamp loopEndTimeStamp;

    Swift

    var loopEndTimeStamp: MusicTimeStamp { get }
  • The loop's ending time stamp during looped playback.

- note: When loopEndTimeStamp is set to MIKMIDISequencerEndOfSequenceLoopEndTimeStamp,
this will return the same length as the sequence.length. Otherwise loopEndTimeStamp
will be returned.

    Declaration

    Objective-C

    @property (nonatomic, readonly) MusicTimeStamp effectiveLoopEndTimeStamp;

    Swift

    var effectiveLoopEndTimeStamp: MusicTimeStamp { get }
  • Whether or not the sequencer should create synthesizers and endpoints
for MIDI tracks that are not assigned an endpoint.

When this property is YES, -commandSchedulerForTrack: will create a 
synthesizer for any track that has MIDI commands scheduled for it
and doesn't already have an assigned scheduler. The default for this property
is YES.

- see: -commandSchedulerForTrack:

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=shouldCreateSynthsIfNeeded) BOOL createSynthsIfNeeded;

    Swift

    var shouldCreateSynthsIfNeeded: Bool { get set }

  • The metronome to send click track events to.

    Declaration

    Objective-C

    @property (nonatomic, strong, nullable) MIKMIDIMetronome *metronome;

    Swift

    var metronome: MIKMIDIMetronome? { get set }

  • When the click track should be heard. The default is MIKMIDISequencerClickTrackStatusEnabledInRecord.

    Declaration

    Objective-C

    @property (nonatomic) MIKMIDISequencerClickTrackStatus clickTrackStatus;

    Swift

    var clickTrackStatus: MIKMIDISequencerClickTrackStatus { get set }

  • The tracks to record incoming MIDI events to while recording is enabled.

    Each incoming event is added to every track in this set.

    See

    recording

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) NSSet<MIKMIDITrack *> *recordEnabledTracks;

    Swift

    var recordEnabledTracks: Set<AnyHashable>? { get set }

  • An MIKMIDIClock that is synced with the sequencer’s internal clock.

    @ - see: -[MIKMIDIClock syncedClock]

    Declaration

    Objective-C

    @property (nonatomic, readonly) MIKMIDIClock *_Nonnull syncedClock;

    Swift

    var syncedClock: MIKMIDIClock { get }

  • The latest MIDITimeStamp the sequencer has looked ahead to to schedule MIDI events.

    Declaration

    Objective-C

    @property (nonatomic, readonly) MIDITimeStamp latestScheduledMIDITimeStamp;

    Swift

    var latestScheduledMIDITimeStamp: MIDITimeStamp { get }
  • The maximum amount the sequencer will look ahead to schedule MIDI events. (0.05 to 1s).

The default of 0.1s should suffice for most uses. You may however, need a longer time
if your sequencer needs to playback on iOS while the device is locked.

    Declaration

    Objective-C

    @property (nonatomic) NSTimeInterval maximumLookAheadInterval;

    Swift

    var maximumLookAheadInterval: TimeInterval { get set }

Deprecated

  • Deprecated

    use -setCommandScheduler:forTrack: instead

    @deprecated Use -setCommandScheduler:forTrack: instead.

    Sets the destination endpoint for a track in the sequencer’s sequence. Calling this method is optional. By default, the sequencer will setup internal default endpoints connected to synthesizers so that playback “just works”.

    Note

    If track is not contained by the receiver’s sequence, this method does nothing.

    Declaration

    Objective-C

    - (void)setDestinationEndpoint:(nonnull MIKMIDIDestinationEndpoint *)endpoint
                      forTrack:(nonnull MIKMIDITrack *)track;

    Swift

    func setDestinationEndpoint(_ endpoint: MIKMIDIDestinationEndpoint, for track: MIKMIDITrack)

    Parameters

    endpoint

    The MIKMIDIDestinationEndpoint instance to which events in track should be sent during playback.
    track

    An MIKMIDITrack instance.

  • Deprecated

    use -setCommandScheduler:forTrack: instead

    @deprecated Use -commandSchedulerForTrack: instead.

    Returns the destination endpoint for a track in the sequencer’s sequence.

    MIKMIDISequencer will automatically create its own default endpoints connected to MIKMIDISynthesizers for any tracks not configured manually. This means that even if you haven’t called -setDestinationEndpoint:forTrack:, you can use this method to retrieve the default endpoint for a given track.

    Note

    If track is not contained by the receiver’s sequence, this method returns nil.

    See

    -setDestinationEndpoint:forTrack:

    See

    -builtinSynthesizerForTrack:

    See

    createSynthsAndEndpointsIfNeeded

    Declaration

    Objective-C

    - (nullable MIKMIDIDestinationEndpoint *)destinationEndpointForTrack:
    (nonnull MIKMIDITrack *)track;

    Swift

    func destinationEndpoint(for track: MIKMIDITrack) -> MIKMIDIDestinationEndpoint?

    Parameters

    track

    An MIKMIDITrack instance.

    Return Value

    The destination endpoint associated with track, or nil if one can’t be found.