# 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. #### See Also on async_complete save_midi_file() mf_set_event_par() mf_get_event_par() General: $NI_ASYNC_ID, $NI_ASYNC_EXIT_STATUS ## 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_insert_file()

save_midi_file()

Specific: $CONTROL_PAR_DND_BEHAVIOUR ## 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. #### See Also mf_set_export_area() mf_copy_export_area() ## 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. #### See Also mf_set_export_area() mf_set_num_export_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. #### See Also mf_insert_file() mf_get_buffer_size() mf_reset() mf_insert_event() mf_remove_event() save_midi_file() ## 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. #### See Also mf_insert_file() mf_set_buffer_size() mf_reset() mf_insert_event() mf_remove_event() save_midi_file() ## 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. #### See Also mf_insert_file() mf_set_buffer_size() mf_reset() mf_insert_event() mf_remove_event() save_midi_file() ## 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>) #### See Also mf_insert_file() mf_set_buffer_size() mf_get_buffer_size() mf_reset() mf_remove_event() save_midi_file() ## 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. #### See Also mf_insert_file() mf_set_buffer_size() mf_get_buffer_size() mf_reset() mf_insert_event() save_midi_file() ## 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

• 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. #### See Also mf_insert_file() mf_insert_event() mf_remove_event() Events and MIDI: $ALL_EVENTS, $CURRENT_EVENT by_marks() by_track() mf_set_mark() mf_get_id() save_midi_file() ## 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

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

mf_get_first()

mf_get_next()

mf_get_next_at()

mf_get_prev()

mf_get_prev_at()

mf_get_last()

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

by_marks()

mf_set_mark()

mf_get_mark()

mf_get_id()

save_midi_file()

## 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_insert_file()

mf_get_next()

mf_get_next_at()

mf_get_num_tracks()

mf_get_prev()

mf_get_prev_at()

mf_get_last()

save_midi_file()

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

load_midi_file()

mf_get_first()

mf_get_next()

mf_get_next_at()

mf_get_num_tracks()

mf_get_prev()

mf_get_prev_at()

save_midi_file()

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

load_midi_file()

mf_get_first()

mf_get_next_at()

mf_get_num_tracks()

mf_get_prev()

mf_get_prev_at()

mf_get_last()

save_midi_file()

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

load_midi_file()

mf_get_first()

mf_get_next()

mf_get_num_tracks()

mf_get_prev()

mf_get_prev_at()

mf_get_last()

save_midi_file()

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

load_midi_file()

mf_get_first()

mf_get_next()

mf_get_next_at()

mf_get_num_tracks()

mf_get_prev_at()

mf_get_last()

save_midi_file()

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

load_midi_file()

mf_get_first()

mf_get_next()

mf_get_next_at()

mf_get_num_tracks()

mf_get_prev()

mf_get_last()

save_midi_file()

## mf_get_num_tracks()

mf_get_num_tracks()

Returns the number of tracks in the MIDI object

mf_insert_file()

mf_get_first()

mf_get_next()

mf_get_next_at()

mf_get_prev()

mf_get_prev_at()

mf_get_last()

save_midi_file()