MIKMIDISequence

Objective-C

@interface MIKMIDISequence : NSObject

Swift

class MIKMIDISequence : NSObject

Instances of MIKMIDISequence contain a collection of MIDI tracks. MIKMIDISequences may be thought of as MIDI “songs”. They can be loaded from and saved to MIDI files. They can also be played using an MIKMIDISequencer.

See

MIKMIDITrack

See

MIKMIDISequencer

  • Creates and initializes a new instance of MIKMIDISequence.

    Declaration

    Objective-C

    + (nullable instancetype)sequence;

    Return Value

    A new instance of MIKMIDISequence, or nil if an error occured.

  • Creates and initilazes a new instance of MIKMIDISequence from a MIDI file.

    Declaration

    Objective-C

    + (nullable instancetype)sequenceWithFileAtURL:(nonnull NSURL *)fileURL
                                         error:(NSError *_Nullable *_Nullable)
                                                   error;

    Parameters

    fileURL

    The URL of the MIDI file.
    error

    If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

    Return Value

    A new instance of MIKMIDISequence containing the loaded file’s MIDI sequence, or nil if an error occured.

  • Creates and initilazes a new instance of MIKMIDISequence from a MIDI file.

    Declaration

    Objective-C

    + (nullable instancetype)sequenceWithFileAtURL:(nonnull NSURL *)fileURL
                   convertMIDIChannelsToTracks:(BOOL)convertMIDIChannelsToTracks
                                         error:(NSError *_Nullable *_Nullable)
                                                   error;

    Parameters

    fileURL

    The URL of the MIDI file.
    convertMIDIChannelsToTracks

    Determines whether or not the track structure should be altered. When YES, the resulting sequence will contain a tempo track, 1 track for each MIDI Channel that is found in the MIDI file, and 1 track for SysEx or MetaEvents as the last track in the sequence. When NO, the track structure of the original MIDI file is left unaltered.
    error

    If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

    Return Value

    A new instance of MIKMIDISequence containing the loaded file’s MIDI sequence, or nil if an error occured.

  • Initilazes a new instance of MIKMIDISequence from a MIDI file.

    Declaration

    Objective-C

    - (nullable instancetype)initWithFileAtURL:(nonnull NSURL *)fileURL
                                     error:(NSError *_Nullable *_Nullable)error;

    Swift

    init(fileAt fileURL: URL) throws

    Parameters

    fileURL

    The URL of the MIDI file.
    error

    If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

    Return Value

    A new instance of MIKMIDISequence containing the loaded file’s MIDI sequence, or nil if an error occured.

  • Initilazes a new instance of MIKMIDISequence from a MIDI file.

    Declaration

    Objective-C

    - (nullable instancetype)initWithFileAtURL:(nonnull NSURL *)fileURL
               convertMIDIChannelsToTracks:(BOOL)convertMIDIChannelsToTracks
                                     error:(NSError *_Nullable *_Nullable)error;

    Swift

    init(fileAt fileURL: URL, convertMIDIChannelsToTracks: Bool) throws

    Parameters

    fileURL

    The URL of the MIDI file.
    convertMIDIChannelsToTracks

    Determines whether or not the track structure should be altered. When YES, the resulting sequence will contain a tempo track, 1 track for each MIDI Channel that is found in the MIDI file, and 1 track for SysEx or MetaEvents as the last track in the sequence. When NO, the track structure of the original MIDI file is left unaltered.
    error

    If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

    Return Value

    A new instance of MIKMIDISequence containing the loaded file’s MIDI sequence, or nil if an error occured.

  • Creates and initializes a new instance of MIKMIDISequence from MIDI data.

    Declaration

    Objective-C

    + (nullable instancetype)sequenceWithData:(nonnull NSData *)data
                                    error:(NSError *_Nullable *_Nullable)error;

    Parameters

    data

    An NSData instance containing the data for the MIDI sequence/file.
    error

    If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors,

    Return Value

    If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

  • Creates and initializes a new instance of MIKMIDISequence from MIDI data.

    Declaration

    Objective-C

    + (nullable instancetype)sequenceWithData:(nonnull NSData *)data
              convertMIDIChannelsToTracks:(BOOL)convertMIDIChannelsToTracks
                                    error:(NSError *_Nullable *_Nullable)error;

    Parameters

    data

    An NSData instance containing the data for the MIDI sequence/file.
    convertMIDIChannelsToTracks

    Determines whether or not the track structure should be altered. When YES, the resulting sequence will contain a tempo track, 1 track for each MIDI Channel that is found in the MIDI file, and 1 track for SysEx or MetaEvents as the last track in the sequence. When NO, the track structure of the original MIDI file is left unaltered.
    error

    If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors,

    Return Value

    If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

  • Initializes a new instance of MIKMIDISequence from MIDI data.

    Declaration

    Objective-C

    - (nullable instancetype)initWithData:(nonnull NSData *)data
                                error:(NSError *_Nullable *_Nullable)error;

    Swift

    init(data: Data, error: ()) throws

    Parameters

    data

    An NSData instance containing the data for the MIDI sequence/file.
    error

    If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors,

    Return Value

    If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

  • Initializes a new instance of MIKMIDISequence from MIDI data.

    Declaration

    Objective-C

    - (nullable instancetype)initWithData:(nonnull NSData *)data
          convertMIDIChannelsToTracks:(BOOL)convertMIDIChannelsToTracks
                                error:(NSError *_Nullable *_Nullable)error;

    Swift

    init(data: Data, convertMIDIChannelsToTracks: Bool) throws

    Parameters

    data

    An NSData instance containing the data for the MIDI sequence/file.
    convertMIDIChannelsToTracks

    Determines whether or not the track structure should be altered. When YES, the resulting sequence will contain a tempo track, 1 track for each MIDI Channel that is found in the MIDI file, and 1 track for SysEx or MetaEvents as the last track in the sequence. When NO, the track structure of the original MIDI file is left unaltered.
    error

    If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors,

    Return Value

    If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

  • Writes the MIDI sequence in Standard MIDI File format to a file at the specified URL.

    Declaration

    Objective-C

    - (BOOL)writeToURL:(nonnull NSURL *)fileURL
             error:(NSError *_Nullable *_Nullable)error;

    Swift

    func write(to fileURL: URL) throws

    Parameters

    fileURL

    The URL to write the MIDI file to.
    error

    If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

    Return Value

    Whether or not the file write was successful.

Track Management

  • Creates and adds a new MIDI track to the sequence.

    Declaration

    Objective-C

    - (nullable MIKMIDITrack *)addTrackWithError:
    (NSError *_Nullable *_Nullable)error;

    Swift

    func addTrack() throws -> MIKMIDITrack

    Parameters

    error

    If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

    Return Value

    The newly created track, or nil if an error occurred.

  • Deprecated

    Creates and adds a new MIDI track to the sequence. May return nil if an error occurs.

    @deprecated: This method is deprecated. You should use -addTrackWithError: instead.

    Declaration

    Objective-C

    - (nullable MIKMIDITrack *)addTrack;

  • Removes the specified MIDI track from the sequence.

    Declaration

    Objective-C

    - (BOOL)removeTrack:(nonnull MIKMIDITrack *)track;

    Swift

    func removeTrack(_ track: MIKMIDITrack) -> Bool

    Parameters

    track

    The track to remove.

    Return Value

    Whether or not removing the track was successful.

Tempo & Time Signature

  • Returns an array of MIKMIDIEvent from the tempo track.

    This is a convenience method, and is equivalent to calling -eventsOfClass:fromTimeStamp:toTimeStamp: on the tempo track with the parameters [MIKMIDIMetaTimeSignatureEvent class], 0, and kMusicTimeStamp_EndOfTrack respectively.

    Declaration

    Objective-C

    - (nonnull NSArray<MIKMIDIMetaTimeSignatureEvent *> *)timeSignatureEvents;

    Swift

    func timeSignatureEvents() -> [MIKMIDIMetaTimeSignatureEvent]

    Return Value

    An array of MIKMIDIMetaTimeSignatureEvent.

  • Returns an array of MIKMIDITempoEvent from the tempo track.

    This is a convenience method, and is equivalent to calling -eventsOfClass:fromTimeStamp:toTimeStamp: on the tempo track with the parameters [MIKMIDITempoEvent class], 0, and kMusicTimeStamp_EndOfTrack respectively.

    Declaration

    Objective-C

    - (nonnull NSArray<MIKMIDITempoEvent *> *)tempoEvents;

    Swift

    func tempoEvents() -> [MIKMIDITempoEvent]

    Return Value

    An array of MIKMIDITempoEvent.

  • Removes any existing tempo events and inserts a tempo event with the desired bpm at the beginning of the tempo track.

    Declaration

    Objective-C

    - (BOOL)setOverallTempo:(Float64)bpm;

    Swift

    func setOverallTempo(_ bpm: Float64) -> Bool

    Parameters

    bpm

    The number of beats per minute for the new tempo.

    Return Value

    Whether or not setting the tempo of the sequence was successful.

  • Inserts a tempo event with the desired tempo in beats per minute (BPM) into the tempo track at the specified time stamp.

    Declaration

    Objective-C

    - (BOOL)setTempo:(Float64)bpm atTimeStamp:(MusicTimeStamp)timeStamp;

    Swift

    func setTempo(_ bpm: Float64, atTimeStamp timeStamp: MusicTimeStamp) -> Bool

    Parameters

    bpm

    The number of beats per minute for the tempo.
    timeStamp

    The time stamp at which to set the tempo.

    Return Value

    Whether or not setting the tempo of the sequence was succesful.

  • Returns the tempo in beats per minute (BPM) of the last tempo event before the specified time stamp.

    Declaration

    Objective-C

    - (Float64)tempoAtTimeStamp:(MusicTimeStamp)timeStamp;

    Swift

    func tempo(atTimeStamp timeStamp: MusicTimeStamp) -> Float64

    Parameters

    timeStamp

    The time stamp at which you would like to know the sequence’s tempo.

    Return Value

    The tempo in beats per minute at the specified time stamp, or 0.0 if an error occurred.

  • Sets the overall time signature for the receiver.

    This method deletes all existing time signature events from the receiver’s tempo track, replacing them with a single event with the specified time signature.

    See

    -timeSignatureAtTimeStamp:

    See

    -setTimeSignature:atTimeStamp:

    Declaration

    Objective-C

    - (BOOL)setOverallTimeSignature:(MIKMIDITimeSignature)signature;

    Swift

    func setOverallTimeSignature(_ signature: MIKMIDITimeSignature) -> Bool

    Parameters

    signature

    An MIKMIDITimeSignature struct with the desired overall time signature.

    Return Value

    YES if setting the overall time signature was succesful, NO if an error occurred.

  • Sets the time signature of the receiver at a specified time.

    Unlike -setOverallTimeSignature, this method does not modify any existing time signature events.

    See

    -timeSignatureAtTimeStamp:

    See

    -setOverallTimeSignature:

    Declaration

    Objective-C

    - (BOOL)setTimeSignature:(MIKMIDITimeSignature)signature
             atTimeStamp:(MusicTimeStamp)timeStamp;

    Swift

    func setTimeSignature(_ signature: MIKMIDITimeSignature, atTimeStamp timeStamp: MusicTimeStamp) -> Bool

    Parameters

    signature

    An MIKMIDITimeSignature struct representing the desired time signature.
    timeStamp

    The time stamp at which the time signature should be effective.

    Return Value

    YES if setting the time signature was successful, NO if an error occurred.

  • Returns the time signature in effect at the the specified time stamp.

    See

    -timeSignatureAtTimeStamp:

    See

    -setOverallTimeSignature:

    Declaration

    Objective-C

    - (MIKMIDITimeSignature)timeSignatureAtTimeStamp:(MusicTimeStamp)timeStamp;

    Swift

    func timeSignature(atTimeStamp timeStamp: MusicTimeStamp) -> MIKMIDITimeSignature

    Parameters

    timeStamp

    The time stamp at which you would like to know the receiver’s time signature.

    Return Value

    An MIKMIDITimeSignature struct representing the time signature of the sequence at the specified time stamp. Defaults to 4/4 if no time signature events are found.

Properties

  • The sequencer this sequence is assigned to for playback.

    Declaration

    Objective-C

    @property (nonatomic, weak, readonly, nullable) MIKMIDISequencer *sequencer;

    Swift

    weak var sequencer: MIKMIDISequencer? { get }

  • The tempo track for the sequence. Even in a new, empty sequence, this will return a tempo track to which tempo events can be added.

    Declaration

    Objective-C

    @property (nonatomic, readonly) MIKMIDITrack *_Nonnull tempoTrack;

    Swift

    var tempoTrack: MIKMIDITrack { get }

  • The MIDI music tracks for the sequence. An array of MIKMIDITrack instances. Does not include the tempo track.

    This property can be observed using Key Value Observing.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSArray<MIKMIDITrack *> *_Nonnull tracks;

    Swift

    var tracks: [MIKMIDITrack] { get }

  • The underlying MusicSequence that backs the instance of MIKMIDISequence.

    Declaration

    Objective-C

    @property (nonatomic, readonly) MusicSequence _Nonnull musicSequence;

    Swift

    var musicSequence: MusicSequence { get }

  • The length of the sequence as a MusicTimeStamp.

    Set to MIKMIDISequenceLongestTrackLength to make the length equal to the length of the longest track.

    This property can be observed using Key Value Observing.

    Declaration

    Objective-C

    @property (nonatomic) MusicTimeStamp length;

    Swift

    var length: MusicTimeStamp { get set }

  • The duration of the sequence in seconds.

    This property can be observed using Key Value Observing.

    Declaration

    Objective-C

    @property (nonatomic, readonly) Float64 durationInSeconds;

    Swift

    var durationInSeconds: Float64 { get }

  • The MIDI data that composes the sequence. This data is equivalent to an NSData representation of a standard MIDI file.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSData *dataValue;

    Swift

    var dataValue: Data? { get }

  • A block to be called for each user event added to any music track owned by the sequence.

    This block is to be used in the same fashion as you would use the callback function sent to MusicSequenceSetUserCallback() if you were working directly with CoreMIDI.

    Declaration

    Objective-C

    @property (nonatomic, copy) void (^_Nonnull) (MIKMIDITrack *_Nonnull, MusicTimeStamp, const MusicEventUserData *_Nonnull, MusicTimeStamp, MusicTimeStamp) callBackBlock;

    Swift

    var callBackBlock: (MIKMIDITrack, MusicTimeStamp, UnsafePointer<MusicEventUserData>, MusicTimeStamp, MusicTimeStamp) -> Void { get set }

Deprecated

  • Deprecated

    @deprecated This method is deprecated. Use +sequenceWithData:error: instead.

    Creates and initializes a new instance of MIKMIDISequence from MIDI data.

    Declaration

    Objective-C

    + (nullable instancetype)sequenceWithData:(nonnull NSData *)data;

    Parameters

    data

    The MIDI data for the new sequence.

    Return Value

    A new instance of MIKMIDISequence containing the MIDI data, or nil if an error occured.

  • Deprecated

    @deprecated This method is deprecated. Use -initWithData:error: instead.

    Initializes a new instance of MIKMIDISequence from MIDI data.

    Declaration

    Objective-C

    - (nullable instancetype)initWithData:(nonnull NSData *)data;

    Swift

    init?(data: Data)

    Parameters

    data

    The MIDI data for the new sequence.

    Return Value

    A new instance of MIKMIDISequence containing the MIDI data, or nil if an error occured.

  • Deprecated

    @deprecated This method is deprecated. Use -[MIKMIDISequencer 
setDestinationEndpoint:forTrack:] instead.

    Sets the destination endpoint for each track in the sequence.

    Declaration

    Objective-C

    - (void)setDestinationEndpoint:
    (nullable MIKMIDIDestinationEndpoint *)destinationEndpoint;

    Swift

    func setDestinationEndpoint(_ destinationEndpoint: MIKMIDIDestinationEndpoint?)

    Parameters

    destinationEndpoint

    The destination endpoint to set for each track in the sequence.

  • Deprecated

    @deprecated This method has been replaced by -tempoAtTimeStamp: and simply calls through to that method.

    You should not call it, and should update your code to call -timeSignatureAtTimeStamp: instead.

    Declaration

    Objective-C

    - (BOOL)getTempo:(nonnull Float64 *)bpm atTimeStamp:(MusicTimeStamp)timeStamp;

    Swift

    func getTempo(_ bpm: UnsafeMutablePointer<Float64>, atTimeStamp timeStamp: MusicTimeStamp) -> Bool

    Parameters

    bpm

    On output, the beats per minute of the tempo at the specified time stamp.
    timeStamp

    The time stamp that you would like to know the sequence’s tempo at.

    Return Value

    YES if getting the tempo was successful, NO if an error occurred.

  • Deprecated

    @deprecated This method has been replaced by -timeSignatureAtTimeStamp: and simply calls through to that method. You should not call it, and should update your code to call -timeSignatureAtTimeStamp: instead.

    Declaration

    Objective-C

    - (BOOL)getTimeSignature:(nonnull MIKMIDITimeSignature *)signature
             atTimeStamp:(MusicTimeStamp)timeStamp;

    Swift

    func getTimeSignature(_ signature: UnsafeMutablePointer<MIKMIDITimeSignature>, atTimeStamp timeStamp: MusicTimeStamp) -> Bool

    Parameters

    signature

    On output, a time signature instance with its values populated.
    timeStamp

    The time stamp at which you would like to know the time signature.

    Return Value

    YES if getting the time signature was successful, NO if an error occurred.

  • Deprecated

    @deprecated This method is only useful in the context of using a sequence in MIKMIDIPlayer, which has been deprecated.

    A MusicTimeStamp that is less than the sequence’s length, but is at an equivalent position in the looped sequence as loopedTimeStamp

    When the music sequence is being looped by an MIKMIDIPlayer, the time stamp of the player continuosly increases. This method can be used to find where in the MIDI sequence the looped playback is at. For example, in a sequence with a length of 16, calling this method with a loopedTimeStamp of 17 would return 1.

    Declaration

    Objective-C

    - (MusicTimeStamp)equivalentTimeStampForLoopedTimeStamp:
    (MusicTimeStamp)loopedTimeStamp;

    Swift

    func equivalentTimeStamp(forLoopedTimeStamp loopedTimeStamp: MusicTimeStamp) -> MusicTimeStamp

    Parameters

    loopedTimeStamp

    The time stamp that you would like an equivalent time stamp for.

    Return Value

    The MusicTimeStamp of the sequence that is in an equivalent position in the sequence as loopedTimeStamp.