MIDI Object Commands

General Information

You can use only one MIDI object at a time within an NKI. The MIDI object is held in memory and can be accessed by any of the script slots. It is possible to add, remove and edit MIDI events within the object, as well as import and export MIDI files.

The Multi Script can also hold one MIDI object, and handles it in the same way as an NKI.

Please note that in Kontakt version 5.2, the MIDI file handling has been significantly updated. Commands and working methods from before the 5.2 release will remain in order to keep backwards compatibility; however this reference will document the post-5.2 working method.

Creating, Importing and Exporting MIDI files

When you initialize an instrument, an empty MIDI object is initialized with it. You can either start editing the object by defining a buffer size and inserting events, or by inserting a whole MIDI file.

If you want to create a MIDI sequence from scratch, you first need to assign a buffer size, which effectively creates a number of inactive MIDI events. From this point you can activate, i.e. insert, and edit MIDI events using the MIDI event commands.

You can also load a MIDI file to use or edit the data in a script. Depending on the command and variables you use, this will either be combined with any existing MIDI data, or will replace the existing data. It should be noted that loading a MIDI file is an asynchronous command, and thus the common asynchronous loading commands and working methods apply.

MIDI objects can be exported from Kontakt either by using the save_midi_file() command or via a drag and drop activated label widget. In either case, it is possible to define the export area, both in terms of start and end times, as well as the start and end tracks, by using the mf_set_export_area() command.

It is also possible to define up to 512 different export areas, each capable of pointing at different time and track range. The workflow here is to first set the amount of export areas with mf_set_num_export_areas(), then creating a matching number of ui_label widgets and assigning them to individual export area indices using $CONTROL_PAR_MIDI_EXPORT_AREA_IDX control parameter. From there, consider export area 0 as the "edit buffer", from which you then copy various time/track selections of interest into other export areas by using mf_copy_export_area() command.

Navigating and Editing

MIDI events in Kontakt’s MIDI object are given event parameters, which are accessed using either the mf_get_event_par() or mf_set_event_par() commands. A unique event ID can be used to access a specific event, or you can navigate through events by position. The event ID is assigned whenever a MIDI event is created or loaded.

In order to access the event data of a loaded MIDI file, you can navigate around the MIDI events with a position marker, something analogous to a play-head. The position marker will focus on one single event at a time, allowing you to use a variety of commands to access or edit the event‘s parameters. You have the option to either navigate from one event to the next, or to specify exact positions in MIDI ticks.

It should be noted that MIDI Note Off messages are not used. When you load a MIDI file using the mf_insert_file() command, the Note Off events are used to give a length parameter to the respective Note On event, and then discarded.

by_marks()

`by_marks(<mark>)`
Used to access a user-defined group of MIDI object events.
`<mark>`	The event mark number, `$MARK_1 ... $MARK_10` .

by_track()

`by_track(<track>)`
Used to access events grouped by their track number.
`<track>`	The track number of the events you wish to access.

Remarks

Similar in functionality to the by_marks() command.

mf_copy_export_area()

`mf_copy_export_area(<index>)`
Copies the contents of MIDI export area 0 to the export area with the specified `<index>`.

Example

on init
    message("")
    make_perfview

    declare const $DND_AREAS := 4

    declare ui_label $label1 (1,1)
    declare ui_label $label2 (1,1)
    declare ui_label $label3 (1,1)
    declare ui_label $label4 (1,1)

    declare $i
    declare %ID[$DND_AREAS]
    %ID[0] := get_ui_id($label1)
    %ID[1] := get_ui_id($label2)
    %ID[2] := get_ui_id($label3)
    %ID[3] := get_ui_id($label4)
    declare !track_names[$DND_AREAS]
    !track_names[0] := "Synth 1"
    !track_names[1] := "Synth 2"
    !track_names[2] := "Bass"
    !track_names[3] := "Melody"

    mf_insert_file(get_folder($GET_FOLDER_PATCH_DIR) & "my_midi.mid", 0, 0, 0)
    mf_set_num_export_areas($DND_AREAS + 1)

    $i := 0
    while ($i < $DND_AREAS)
        set_control_par(%ID[$i], $CONTROL_PAR_DND_BEHAVIOUR, 1)
        set_control_par(%ID[$i], $CONTROL_PAR_MIDI_EXPORT_AREA_IDX, $i + 1)
        set_control_par_str(%ID[$i], $CONTROL_PAR_TEXT, !track_names[$i])

        mf_set_export_area(!track_names[$i], -1, -1, $i, $i)
        mf_copy_export_area($i + 1)

        inc($i)
    end while
end on

Loads a MIDI file and distributes the content found in the first four MIDI channels to four separate MIDI areas.

mf_get_buffer_size()

`mf_get_buffer_size()`
Returns the size of the MIDI object's event buffer.

Remarks

The maximum buffer size is 1000000 events, including both active and inactive events.
Inserting a MIDI event will decrease the buffer size by one. Removing an event will increase it by one.

mf_get_event_par()

`mf_get_event_par(<event-id>, <parameter>)`
Returns the value of an event parameter.
`<event-id>`	The ID of the event to be edited.
`<parameter>`	The event parameter, either one of four freely assignable event parameters: `$EVENT_PAR_0` `$EVENT_PAR_1` `$EVENT_PAR_2` `$EVENT_PAR_3` or the built-in parameters of a event: `$EVENT_PAR_MIDI_CHANNEL` `$EVENT_PAR_MIDI_COMMAND` `$EVENT_PAR_MIDI_BYTE_1` `$EVENT_PAR_MIDI_BYTE_2` `$EVENT_PAR_POS` `$EVENT_PAR_NOTE_LENGTH` `$EVENT_PAR_ID` `$EVENT_PAR_TRACK_NR`

mf_get_event_par(<event-id>, <parameter>)

Returns the value of an event parameter.

<event-id>

The ID of the event to be edited.

<parameter>

The event parameter, either one of four freely assignable event parameters:

$EVENT_PAR_0

$EVENT_PAR_1

$EVENT_PAR_2

$EVENT_PAR_3

or the built-in parameters of a event:

$EVENT_PAR_MIDI_CHANNEL

$EVENT_PAR_MIDI_COMMAND

$EVENT_PAR_MIDI_BYTE_1

$EVENT_PAR_MIDI_BYTE_2

$EVENT_PAR_POS

$EVENT_PAR_NOTE_LENGTH

$EVENT_PAR_ID

$EVENT_PAR_TRACK_NR

Remarks

You can access all events in the MIDI object by using the $ALL_EVENTS constant as the event ID.
You can access the currently selected event by using the $CURRENT_EVENT constant.
You can also access events by track, or group them with event marks by using the by_track() and by_marks() commands.

mf_get_first()

`mf_get_first(<track-index>)`
Moves the position marker to the first event in the MIDI track.
`<track-index>`	The number of the track you want to edit. -1 refers to the whole file.

Remarks

Using this command will also select the event at the position marker for editing.

mf_get_id()

`mf_get_id()`
Returns the ID of the currently selected event, when using the navigation commands like `mf_get_first()`, `mf_get_next()`, etc.

`mf_get_last(<track-index>)`
Moves the position marker to the last event in the MIDI track.
`<track-index>`	The number of the track you want to edit. -1 refers to the whole file.

Remarks

Using this command will also select the event at the position marker for editing.

mf_get_last_filename()

`mf_get_last_filename()`
Returns the filename (not the full path!) of the last MIDI file that was inserted into Kontakt, either via `mf_insert_file()`, or via drag and drop operation on `ui_mouse_area`.

Remarks

This command will pair Note On and Note Off events to a single Note On with a Note Length parameter. The Note Off events will be discarded.

Example

on init
    message("")
    make_perfview

    declare const $DND_AREAS := 4

    declare ui_label $label1 (1,1)
    declare ui_label $label2 (1,1)
    declare ui_label $label3 (1,1)
    declare ui_label $label4 (1,1)

    declare $i
    declare %ID[$DND_AREAS]
    %ID[0] := get_ui_id($label1)
    %ID[1] := get_ui_id($label2)
    %ID[2] := get_ui_id($label3)
    %ID[3] := get_ui_id($label4)
    declare !track_names[$DND_AREAS]
    !track_names[0] := "Synth 1"
    !track_names[1] := "Synth 2"
    !track_names[2] := "Bass"
    !track_names[3] := "Melody"

    mf_insert_file(get_folder($GET_FOLDER_PATCH_DIR) & "my_midi.mid", 0, 0, 0)
    { declare export areas, area 0 serves as an edit buffer, so add one extra }
    mf_set_num_export_areas($DND_AREAS + 1)

    $i := 0
    while ($i < $DND_AREAS)
        set_control_par(%ID[$i], $CONTROL_PAR_DND_BEHAVIOUR, 1)
        set_control_par(%ID[$i], $CONTROL_PAR_MIDI_EXPORT_AREA_IDX, $i + 1)
        set_control_par_str(%ID[$i], $CONTROL_PAR_TEXT, mf_get_last_filename & " " & !track_names[$i])

        mf_set_export_area(!track_names[$i], -1, -1, $i, $i)
        mf_copy_export_area($i + 1)

        inc($i)
    end while
end on

MIDI file loader which allows exporting first four tracks as individual MIDI files. Utilizes mf_get_last_filename() to show the exact name of the MIDI file that was loaded.

mf_get_mark()

`mf_get_mark(<event-id>, <mark>)`
Checks if an event is marked or not. Returns 1 if it is marked or 0 if it is not.
<`event-id>`	The ID of the event to be edited
`<mark>`	The event mark number, `$MARK_1 ... $MARK_10` . You can also assign more than one mark to a single event, either by typing the command again, or by using the bitwise `.or.` operator, or by simply summing the event marks.

mf_get_next()

`mf_get_next(<track-index>)`
Moves the position marker to the next event in the MIDI track.
`<track-index>`	The number of the track you want to edit. -1 refers to the whole file.

Remarks

Using this command will also select the event at the position marker for editing.

mf_get_next_at()

`mf_get_next_at(<track-index>, <pos>)`
Moves the position marker to the next event in the MIDI track right after the defined position.
`<track-index>`	The number of the track you want to edit. -1 refers to the whole file.
`<pos>`	Position in MIDI ticks.

Remarks

Using this command will also select the event at the position marker for editing.

mf_get_num_tracks()

`mf_get_num_tracks()`
Returns the number of tracks in the MIDI object.

mf_get_prev()

`mf_get_prev(<track-index>)`
Moves the position marker to the previous event in the MIDI track.
`<track-index>`	The number of the track you want to edit. -1 refers to the whole file.

Remarks

Using this command will also select the event at the position marker for editing.

mf_get_prev_at()

`mf_get_prev_at(<track-index>, <pos>)`
Moves the position marker to the first event before the defined position.
`<track-index>`	The number of the track you want to edit. -1 refers to the whole file.
`<pos>`	Position in MIDI ticks.

Remarks

Using this command will also select the event at the position marker for editing.

mf_insert_event()

`mf_insert_event(<track>, <pos>, <command>, <byte1>, <byte2>)`
Activates an inactive MIDI event in the MIDI object. However, because the command and position are defined in this command, it can be considered as an insertion.
`<track>`	The track into which the event will be inserted.
`<pos>`	The position at which the event will be inserted, in ticks.
`<command>`	Defines the command type of the event, can be one of the following: `$MIDI_COMMAND_NOTE_ON` `$MIDI_COMMAND_POLY_AT` `$MIDI_COMMAND_CC` `$MIDI_COMMAND_PROGRAM_CHANGE` `$MIDI_COMMAND_MONO_AT` `$MIDI_COMMAND_PITCH_BEND`
`<byte1>`	The first byte of the command.
`<byte2>`	The second byte of the command.

Remarks

It is not possible to insert MIDI events without first setting an event buffer size with the mf_set_buffer_size() command.
Using this command when the buffer is full, i.e. has a size of zero, will do nothing.
You can retrieve the event ID of the inserted event into a variable by writing:
<variable> := mf_insert_event(<track>, <pos>, <command>, <byte1>, <byte2>)

mf_insert_file()

`mf_insert_file(<path>, <track-offset>, <position-offset>, <mode>)`
Inserts a MIDI file into the object.
`<path>`	The absolute path of the MIDI file, including the file name.
`<track-offset>`	Applies a track offset to the MIDI data.
`<position-offset>`	Applies a position offset, in ticks, to the MIDI data.
`<mode>`	Defines the mode of insertion: 0: Replaces all existing events 1: Replaces only overlapping events 2: Merges all events

Remarks

This command runs synchronously in on init callback and asynchronously in all other callbacks, so it is advised to use the on async_complete callback to verify the loading status.
This command will pair Note On and Note Off events to a single Note On with a length parameter. The Note Off events will be discarded.
Always use forwards slash (/) when working with absolute file paths in Kontakt!

Example

on init
    declare $load_mf_id := -1
    declare @file_name
    declare @filepath

    @file_name := "test.mid"
    @filepath := get_folder($GET_FOLDER_FACTORY_DIR) & @file_name

    declare ui_button $load_file
end on

on ui_control($load_file)
    $load_mf_id := mf_insert_file(@filepath, 0, 0, 0)
end on

on async_complete
    if ($NI_ASYNC_ID = $load_mf_id)
        $load_mf_id := -1

        if ($NI_ASYNC_EXIT_STATUS = 0)
            message("ERROR: MIDI file not found!")
        else
            message("Loaded MIDI file: " & @file_name & "!")
        end if
    end if
end on

Loading a MIDI file with a button. In order for this to work, you will need to put a MIDI file called "test.mid" into your Kontakt factory data folder. Otherwise, the defined error message will be displayed.

mf_remove_event()

`mf_remove_event(<event-id>)`
Deactivates an event in the MIDI object, effectively removing it.
`<event-id>`	The ID of the event to be deactivated.

Remarks

Using this command will decrease the MIDI event buffer size by one.

mf_reset()

`mf_reset()`
Resets the MIDI object, sets the event buffer to zero, and removes all events.

Remarks

This command purges all data in the MIDI object. Use with caution!
This command is asynchronous, thus it returns an async ID and calls the on async_complete callback.

mf_set_buffer_size()

`mf_set_buffer_size(<num-events>)`
Defines a number of inactive MIDI events, that can be activated and edited.
`<num-events>`	The size of the MIDI object edit buffer.

Remarks

Using the mf_insert_event() and mf_remove_event() technically activates or deactivates events in the buffer.
It is not possible to insert MIDI events without setting a buffer size first.
The maximum buffer size is 1000000 events, including both active and inactive events.
This command runs synchronously in on init callback and asynchronously in all other callbacks, so it is advised to use the on async_complete callback to verify the loading status.
Inserting a MIDI event will decrease the buffer size by one. Removing an event will increase it by one.
Inserting a MIDI file will not affect the buffer.

mf_set_event_par()

`mf_set_event_par(<event-id>, <parameter>, <value>)`
Sets an event parameter.
`<event-id>`	The ID of the event to be edited.
`<parameter>`	The event parameter, either one of four freely assignable event parameters: `$EVENT_PAR_0` `$EVENT_PAR_1` `$EVENT_PAR_2` `$EVENT_PAR_3` Or the built-in parameters of a event: `$EVENT_PAR_MIDI_CHANNEL` `$EVENT_PAR_MIDI_COMMAND` `$EVENT_PAR_MIDI_BYTE_1` `$EVENT_PAR_MIDI_BYTE_2` `$EVENT_PAR_POS` `$EVENT_PAR_NOTE_LENGTH` `$EVENT_PAR_ID` `$EVENT_PAR_TRACK_NR`
`<value>`	The value of the event parameter.

Remarks

You can control all events in the MIDI object by using the $ALL_EVENTS constant as the event ID.
You can access the currently selected event by using the $CURRENT_EVENT constant.
You can also control events by track, or group them with event marks by using the by_track() and by_marks() commands.

mf_set_export_area()

`mf_set_export_area(<name>, <start-pos>, <end-pos>, <start-track>, <end-track>)`
Defines the part of the object that will be exported when using a drag and drop area, or when using `save_midi_file()` command.
`<name>`	Sets the name of the exported file.
`<start-pos>`	Defines the start position (in ticks) of the export area. Use -1 to set this to the start of the object.
`<end-pos>`	Defines the end position (in ticks) of the export area. Use -1 to set this to the end of the object.
`<start-track>`	Defines the first track to be included in the export area. Use -1 to set this to the first track of the object.
`<end-track>`	Defines the last track to be included in the export area. Use -1 to set this to the last track of the object.

Remarks

If a start point is given a value greater than the end point, the values will be swapped.
When this command is executed, the events in the range are checked if they are valid MIDI commands. The command will return a value of 0 if all events are valid, otherwise it will return the event ID of the first invalid event.

Example

on init
    declare $area_status
    declare @filepath
    @filepath := get_folder($GET_FOLDER_FACTORY_DIR) & "test.mid"

    declare ui_button $CheckMIDI

    mf_insert_file(@filepath, 0, 0, 0)
end on

on ui_control($CheckMIDI)
    $area_status := mf_set_export_area(“name”, -1, -1,-1,-1)

    if ($area_status = 0)
        message(“All Good”)
    else
        message(“Error: Check event with ID ” & $area_status & "!")
    end if

    $CheckMIDI := 0
end on

A simple script, using this command to check if all events in a MIDI file are valid. If there is an error it will display the event ID of the first invalid event. In order for this to work you will have to put a MIDI file called "test.mid" into your Kontakt factory data folder.

mf_set_mark()

`mf_set_mark(<event-id>, <mark>, <status>)`
Marks an event, so that you may group events together and process that group quickly.
`<event-id>`	The ID of the event to be marked.
`<mark>`	The event mark number, `$MARK_1 ... $MARK_10` . You can also assign more than one mark to a single event, either by typing the command again, or by using the bitwise `.or.` operator, or by simply summing the event marks.
`<status>`	Set this to 1 to mark an event or to 0 to unmark an event.

mf_set_num_export_areas()

`mf_set_num_export_areas(<num-areas>)`
Sets the number of export areas, with a maximum of 512.

Remarks

Area index 0 is always set with mf_set_export_area().
The contents of area index 0 can be copied to other areas by calling mf_copy_export_area().

MIDI Object Commands

General Information

Creating, Importing and Exporting MIDI files

Navigating and Editing

by_marks()

See Also

by_track()

Remarks

See Also

mf_copy_export_area()

Example

See Also

mf_get_buffer_size()

Remarks

See Also

mf_get_event_par()

Remarks

See Also

mf_get_first()

Remarks

See Also

mf_get_id()

See Also

mf_get_last()

Remarks

See Also

mf_get_last_filename()

Remarks

Example

See Also

mf_get_mark()

See Also

mf_get_next()

Remarks

See Also

mf_get_next_at()

Remarks

See Also

mf_get_num_tracks()

See Also

mf_get_prev()

Remarks

See Also

mf_get_prev_at()

Remarks

See Also

mf_insert_event()

Remarks

See Also

mf_insert_file()

Remarks

Example

See Also

mf_remove_event()

Remarks

See Also

mf_reset()

Remarks

See Also

mf_set_buffer_size()

Remarks

See Also

mf_set_event_par()

Remarks

See Also

mf_set_export_area()

Remarks

Example

See Also

mf_set_mark()

See Also

mf_set_num_export_areas()

Remarks

See Also

Search results