MIDI Object Commands

General Information

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.

You can only use 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.

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 element. 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.

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 are then discarded.

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: Replace all existing events 1: Replace only overlapping events 2: Merge all events

Remarks

The loading of MIDI files with this command is asynchronous, so it is advised to use the async_complete callback to check the status of the load. However, the async_complete callback will not be called if this command is used in the init callback.
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

(see next page)

on init
	declare @file_name
	declare @filepath

	@file_name := "test.mid"
	@filepath := get_folder($GET_FOLDER_FACTORY_DIR) & @file_name
	
	declare $load_mf_id
	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("FATAL 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 folder. Otherwise the defined error message will be displayed.

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 the `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
	@filepath := get_folder($GET_FOLDER_FACTORY_DIR) & "test.mid"
	mf_insert_file(@filepath,0,0,0)

	declare ui_button $check_area
	declare $area_status
end on

on ui_control($check_area)
$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
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 folder.

mf_set_num_export_areas()

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

Remarks

Area index 0 is set with the previously existing command mf_set_export_area.
The contents of index 0 can be copied to other areas by calling mf_copy_export_area.

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

Example

on init	
    message("")	
    make_perfview	
    declare $i	
    declare const $drag_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 %labelID[$drag_areas]		
        %labelID[0] := get_ui_id($label1)		
        %labelID[1] := get_ui_id($label2)		
        %labelID[2] := get_ui_id($label3)		
        %labelID[3] := get_ui_id($label4)	
    declare !midiTracks[$drag_areas]		
        !midiTracks[0] := "Synth1"		
        !midiTracks[1] := "Synth2"		
        !midiTracks[2] := "Bass"		
        !midiTracks[3] := "Melody"	
    mf_insert_file(get_folder($GET_FOLDER_PATCH_DIR) & "/my_midi.mid",0,0,0)
    mf_set_num_export_areas($drag_areas+1)	
    $i := 0	
    while($i<$drag_areas)		
        set_control_par(%labelID[$i], $CONTROL_PAR_DND_BEHAVIOUR, 1)		
        set_control_par(%labelID[$i], $CONTROL_PAR_MIDI_EXPORT_AREA_IDX, $i+1)
        set_control_par_str(%labelID[$i], $CONTROL_PAR_TEXT, !midiTracks[$i])		            
        mf_set_export_area(!midiTracks[$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_set_buffer_size()

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

Remarks

Using the mf_insert_event() and mf_remove_event() technically activate or deactivate events in the buffer.
It is not possible to insert MIDI events without first setting a buffer size.
The maximum buffer size is 1,000,000 events, including both active and inactive events.
If this command is called outside of the init callback, it is asynchronous, and thus calls the async_complete callback.
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_get_buffer_size()

`mf_get_buffer_size()`
Returns the size of the MIDI event buffer

Remarks

The maximum buffer size is 1,000,000 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_reset()

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

Remarks

This command purges all MIDI data. Use with caution.
This command is also asynchronous, and thus calls the async_complete callback.

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 in a variable by writing:
<variable> := mf_insert_event(<track>,<pos>,<command>,<byte1>,<byte2>)

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 increase the MIDI event buffer size by one.

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 markers by using the by_track() and by_mark() commands.

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 parameter: `$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 parameter:

$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 markers by using the by_track() and by_mark() commands.

mf_get_id()

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

KONTAKT 7

New Features

Engine parameter for adjusting LFO phase, $ENGINE_PAR_LFO_PHASE
Engine parameters for adjusting step modulator parameters: $ENGINE_PAR_STEPSEQ_NUM_STEPS, $ENGINE_PAR_STEPSEQ_ONESHOT, $ENGINE_PAR_STEPSEQ_STEP_VALUE
Engine parameter for bipolar adjustment of modulation amount, $ENGINE_PAR_MOD_TARGET_MP_INTENSITY
Engine parameters for the following new effects: PsycheDelay, Ring Modulator
ui_mouse_area now responds to $CONTROL_PAR_KEY_CONTROL, $CONTROL_PAR_KEY_SHIFT, $CONTROL_PAR_KEY_ALT control parameters

Improved Features

Increased number of user zones to 1024
$EVENT_PAR_MOD_VALUE_ID can now be retrieved by using get_event_par_arr()

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 mark number. Use the constants `$MARK_1` to `$MARK_10`
`<status>`	Set this to 1 to mark an event or to 0 to unmark an event

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 mark number. Use the constants `$MARK_1` to `$MARK_10`

by_marks()

`by_marks(<mark>)`
Can be used to access a user-defined group of events
`<mark>`	The mark number. Use the constants `$MARK_1` to `$MARK_10`

by_track()

`by_track(<track>)`
Can be used to group events 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_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_last()

`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_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 ticks

Remarks

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

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

MIDI Object Commands

General Information

Creating, Importing and Exporting MIDI files

Navigating and Editing

mf_insert_file()

Remarks

Example

See Also

mf_set_export_area()

Remarks

Example

See Also

mf_set_num_export_areas()

Remarks

See Also

mf_copy_export_area()

Example

See Also

mf_set_buffer_size()

Remarks

See Also

mf_get_buffer_size()

Remarks

See Also

mf_reset()

Remarks

See Also

mf_insert_event()

Remarks

See Also

mf_remove_event()

Remarks

See Also

mf_set_event_par()

Remarks

See Also

mf_get_event_par()

Remarks

See Also

mf_get_id()

See Also

KONTAKT 7

New Features

Improved Features

mf_set_mark()

See Also

mf_get_mark()

See Also

by_marks()

See Also

by_track()

Remarks

See Also

mf_get_first()

Remarks

See Also

mf_get_last()

Remarks

See Also

mf_get_next()

Remarks

See Also

mf_get_next_at()

Remarks

See Also

mf_get_prev()

Remarks

See Also

mf_get_prev_at()

Remarks

See Also

mf_get_num_tracks()

See Also

Search results