0% found this document useful (0 votes)

114 views248 pages

KSP Reference Manual Overview

This document provides a summary of the KSP Reference Manual which details callbacks, variables, control statements, user interface controls, arithmetic commands, and general commands available for KSP plugins. It includes sections on topics like callbacks that occur during async operations or when controllers change, different variable types for integers, reals, strings, and arrays, control structures like if/else and while statements, user interface elements, arithmetic functions, and general commands for things like ignoring controllers, sending messages, and playing notes.

Uploaded by

Thawin Laithong

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

114 views248 pages

KSP Reference Manual Overview

Uploaded by

Thawin Laithong

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 248

KSP Reference Manual

Table of Contents
1. Disclaimer ................................................................................................................. 1

2. Callbacks .................................................................................................................. 2
2.1. General Information ............................................................................................ 2
2.2. on async_complete ............................................................................................. 2
2.3. on controller ....................................................................................................... 3
2.4. on init ................................................................................................................. 4
2.5. on listener .......................................................................................................... 6
2.6. on note ............................................................................................................... 6
2.7. on persistence_changed ...................................................................................... 7
2.8. on pgs_changed .................................................................................................. 8
2.9. on poly_at ........................................................................................................... 9
2.10. on release ......................................................................................................... 9
2.11. on rpn/nrpn .................................................................................................... 10
2.12. on ui_control() ................................................................................................. 10
2.13. on ui_update ................................................................................................... 11

3. Variables .................................................................................................................. 13
3.1. General Information .......................................................................................... 13
3.2. $ (int variable) ................................................................................................... 13
3.3. % (int array) ...................................................................................................... 13
3.4. ~ (real variable) ................................................................................................. 14
3.5. ? (real array) ...................................................................................................... 15
3.6. @ (string variable) ............................................................................................. 15
3.7. ! (string array) ................................................................................................... 16
3.8. const $ (constant integer) .................................................................................. 17
3.9. const ~ (real constant) ...................................................................................... 17
3.10. polyphonic $ (polyphonic integer) ..................................................................... 18
3.11. make_instr_persistent() .................................................................................... 19
3.12. make_persistent() ........................................................................................... 19
3.13. read_persistent_var() ....................................................................................... 20
3.14. watch_var() ..................................................................................................... 21
3.15. watch_array_idx() ............................................................................................ 21

4. Control Statements ................................................................................................... 23

4.1. if…else…end ...................................................................................................... 23
4.2. select() ............................................................................................................. 23
4.3. while() .............................................................................................................. 24
4.4. Boolean Operators ............................................................................................ 24

5. User Interface Controls ............................................................................................. 26

5.1. ui_button .......................................................................................................... 26
5.2. ui_file_selector .................................................................................................. 26
5.3. ui_label ............................................................................................................. 28
5.4. ui_knob ............................................................................................................ 28
5.5. ui_level_meter ................................................................................................... 29
5.6. ui_menu ........................................................................................................... 30
5.7. ui_mouse_area .................................................................................................. 30
5.8. ui_panel ............................................................................................................ 32
5.9. ui_slider ............................................................................................................ 32
3

5.10. ui_switch ........................................................................................................ 33

5.11. ui_table .......................................................................................................... 33
5.12. ui_text_edit ..................................................................................................... 34
5.13. ui_value_edit ................................................................................................... 35
5.14. ui_waveform ................................................................................................... 36
5.15. ui_wavetable ................................................................................................... 36
5.16. ui_xy .............................................................................................................. 37

6. Arithmetic Commands & Operators ............................................................................ 40

6.1. Basic Operators ................................................................................................ 40
6.2. Integer Operators & Commands ......................................................................... 40
6.3. Real Number Commands ................................................................................... 40
6.4. Rounding Commands ........................................................................................ 41
6.5. Trigonometric Commands ................................................................................. 41
6.6. Bit Operators .................................................................................................... 42
6.7. random() .......................................................................................................... 42
6.8. int_to_real() ....................................................................................................... 42
6.9. real_to_int() ....................................................................................................... 43
6.10. msb() ............................................................................................................. 43
6.11. lsb() ............................................................................................................... 44

7. General Commands ................................................................................................... 45

7.1. disable_logging() ............................................................................................... 45
7.2. exit .................................................................................................................. 45
7.3. ignore_controller ............................................................................................... 46
7.4. message() ........................................................................................................ 46
7.5. note_off() ......................................................................................................... 47
7.6. play_note() ........................................................................................................ 48
7.7. set_controller() .................................................................................................. 49
7.8. set_rpn()/set_nrpn() ........................................................................................... 49
7.9. set_snapshot_type() .......................................................................................... 50

8. Event Commands ...................................................................................................... 52

8.1. by_marks() ....................................................................................................... 52
8.2. change_note() ................................................................................................... 52
8.3. change_pan() .................................................................................................... 53
8.4. change_tune() ................................................................................................... 54
8.5. change_velo() ................................................................................................... 55
8.6. change_vol() ..................................................................................................... 55
8.7. delete_event_mark() .......................................................................................... 56
8.8. event_status() ................................................................................................... 56
8.9. fade_in() ........................................................................................................... 57
8.10. fade_out() ....................................................................................................... 57
8.11. get_event_mark() ............................................................................................. 58
8.12. get_event_mark() ............................................................................................. 59
8.13. get_event_par() ............................................................................................... 59
8.14. get_event_par_arr() .......................................................................................... 61
8.15. ignore_event() ................................................................................................. 62
8.16. set_event_mark() ............................................................................................. 62
8.17. set_event_par() ............................................................................................... 63
8.18. set_event_par_arr() .......................................................................................... 65

9. Array Commands ...................................................................................................... 67

9.1. array_equal() ..................................................................................................... 67

9.2. num_elements() ................................................................................................ 67
9.3. search() ............................................................................................................ 68
9.4. sort() ................................................................................................................ 68

10. Group Commands ................................................................................................... 70

10.1. allow_group() .................................................................................................. 70
10.2. disallow_group() .............................................................................................. 70
10.3. find_group() .................................................................................................... 71
10.4. get_purge_state() ............................................................................................ 71
10.5. group_name() ................................................................................................. 72
10.6. purge_group() ................................................................................................. 73

11. Time-Related Commands ........................................................................................ 75

11.1. change_listener_par() ...................................................................................... 75
11.2. ms_to_ticks() .................................................................................................. 76
11.3. set_listener() .................................................................................................. 76
11.4. stop_wait() ...................................................................................................... 77
11.5. reset_ksp_timer ............................................................................................... 78
11.6. ticks_to_ms() .................................................................................................. 79
11.7. wait() ............................................................................................................. 79
11.8. wait_async() ................................................................................................... 80
11.9. wait_ticks() ..................................................................................................... 81

12. User Interface Commands ....................................................................................... 82

12.1. add_menu_item() ............................................................................................ 82
12.2. add_text_line() ................................................................................................. 82
12.3. attach_level_meter() ........................................................................................ 83
12.4. attach_zone() .................................................................................................. 84
12.5. fs_get_filename() ............................................................................................. 85
12.6. fs_navigate() ................................................................................................... 85
12.7. get_control_par() ............................................................................................. 85
12.8. get_font_id() .................................................................................................... 86
12.9. get_menu_item_str() ........................................................................................ 87
12.10. get_menu_item_value() .................................................................................. 88
12.11. get_menu_item_visibility() .............................................................................. 88
12.12. get_ui_id() ..................................................................................................... 89
12.13. get_ui_wf_property() ...................................................................................... 90
12.14. hide_part() .................................................................................................... 91
12.15. load_performance_view() ............................................................................... 92
12.16. make_perfview .............................................................................................. 92
12.17. move_control() .............................................................................................. 93
12.18. move_control_px() ......................................................................................... 94
12.19. set_control_help() .......................................................................................... 95
12.20. set_control_par() ........................................................................................... 95
12.21. set_control_par_arr() ...................................................................................... 96
12.22. set_knob_defval() .......................................................................................... 97
12.23. set_knob_label() ............................................................................................ 97
12.24. set_knob_unit() .............................................................................................. 98
12.25. set_menu_item_str() ...................................................................................... 99
12.26. set_menu_item_value() ................................................................................ 100
12.27. set_menu_item_visibility() ............................................................................ 100
12.28. set_table_steps_shown() .............................................................................. 101
5

12.29. set_script_title() ........................................................................................... 102

12.30. set_skin_offset() .......................................................................................... 102
12.31. set_text() .................................................................................................... 103
12.32. set_ui_color() .............................................................................................. 104
12.33. set_ui_height() ............................................................................................. 104
12.34. set_ui_height_px() ........................................................................................ 105
12.35. set_ui_width_px() ......................................................................................... 105
12.36. set_ui_wf_property() .................................................................................... 106

13. Keyboard Commands ............................................................................................ 107

13.1. get_key_color() .............................................................................................. 107
13.2. get_key_name() ............................................................................................. 107
13.3. get_key_triggerstate() .................................................................................... 108
13.4. get_key_type() ............................................................................................... 109
13.5. get_keyrange_min_note() ............................................................................... 109
13.6. get_keyrange_max_note() .............................................................................. 109
13.7. get_keyrange_name() .................................................................................... 110
13.8. set_key_color() .............................................................................................. 111
13.9. set_key_name() ............................................................................................. 113
13.10. set_key_pressed() ........................................................................................ 113
13.11. set_key_pressed_support() ........................................................................... 114
13.12. set_key_type() ............................................................................................. 115
13.13. set_keyrange() ............................................................................................. 116
13.14. remove_keyrange() ...................................................................................... 116

14. Engine Parameter Commands ............................................................................... 118

14.1. find_mod() .................................................................................................... 118
14.2. find_target() .................................................................................................. 119
14.3. get_engine_par() ............................................................................................ 120
14.4. get_engine_par_disp() .................................................................................... 122
14.5. get_voice_limit() ............................................................................................ 123
14.6. output_channel_name() ................................................................................. 123
14.7. set_engine_par() ............................................................................................ 124
14.8. set_voice_limit() ............................................................................................ 126

15. Zone Commands ................................................................................................... 128

15.1. General Information ....................................................................................... 128
15.2. get_loop_par() ............................................................................................... 128
15.3. get_sample() ................................................................................................. 128
15.4. get_zone_par() .............................................................................................. 129
15.5. is_zone_empty() ............................................................................................ 130
15.6. set_loop_par() ............................................................................................... 131
15.7. set_num_user_zones() ................................................................................... 131
15.8. set_sample ................................................................................................... 132
15.9. set_zone_par() .............................................................................................. 132

16. Load/Save Commands .......................................................................................... 134

16.1. General Information ....................................................................................... 134
16.2. get_folder() ................................................................................................... 134
16.3. load_array() .................................................................................................. 135
16.4. load_array_str() ............................................................................................. 137
16.5. load_ir_sample() ............................................................................................ 139
16.6. save_array() .................................................................................................. 140
6

16.7. save_array_str() ............................................................................................. 141

16.8. save_midi_file() ............................................................................................. 142

17. Music Information Retrieval ................................................................................... 144

17.1. General Information ....................................................................................... 144
17.2. detect_pitch() ................................................................................................ 144
17.3. detect_loudness() .......................................................................................... 144
17.4. detect_peak() ................................................................................................ 144
17.5. detect_rms() ................................................................................................. 145
17.6. detect_sample_type() .................................................................................... 145
17.7. detect_drum_type() ....................................................................................... 145
17.8. detect_instrument_type() ............................................................................... 146
17.9. Examples ..................................................................................................... 147

18. MIDI Object Commands ......................................................................................... 148

18.1. General Information ....................................................................................... 148
18.2. mf_insert_file() .............................................................................................. 149
18.3. mf_set_export_area() ..................................................................................... 150
18.4. mf_set_num_export_areas() ........................................................................... 151
18.5. mf_copy_export_area() .................................................................................. 151
18.6. mf_set_buffer_size() ...................................................................................... 152
18.7. mf_get_buffer_size() ...................................................................................... 153
18.8. mf_reset() ..................................................................................................... 153
18.9. mf_insert_event() .......................................................................................... 153
18.10. mf_remove_event() ...................................................................................... 154
18.11. mf_set_event_par() ...................................................................................... 155
18.12. mf_get_event_par() ...................................................................................... 156
18.13. mf_get_id() .................................................................................................. 157
18.14. mf_set_mark() ............................................................................................. 157
18.15. mf_get_mark() ............................................................................................. 158
18.16. by_marks() .................................................................................................. 158
18.17. by_track() ................................................................................................... 159
18.18. mf_get_first() .............................................................................................. 159
18.19. mf_get_last() ............................................................................................... 160
18.20. mf_get_next() .............................................................................................. 160
18.21. mf_get_next_at() .......................................................................................... 161
18.22. mf_get_prev() .............................................................................................. 161
18.23. mf_get_prev_at() .......................................................................................... 162
18.24. mf_get_num_tracks() ................................................................................... 162

19. Built-in Variables and Constants ............................................................................ 163

19.1. General ........................................................................................................ 163
19.2. Events and MIDI ............................................................................................ 164
19.3. Transport and Timing .................................................................................... 168
19.4. Callbacks and UI ........................................................................................... 170
19.5. Mathemetical Constants ................................................................................ 171

20. Control Parameters ............................................................................................... 172

20.1. General ........................................................................................................ 172
20.2. Specific ........................................................................................................ 176

21. Engine Parameters ................................................................................................ 186

21.1. Instrument, Source and Amp Module .............................................................. 186
7

21.2. Insert Effects ................................................................................................ 188

21.3. Filter and EQ ................................................................................................. 198
21.4. Send Effects ................................................................................................. 200
21.5. Modulation ................................................................................................... 203
21.6. Module Types and Subtypes .......................................................................... 206
21.7. Group Start Options Query ............................................................................. 211

22. Zone Parameters .................................................................................................. 212

22.1. Zone Parameters .......................................................................................... 212
22.2. Loop Parameters ........................................................................................... 214
22.3. Sample Parameters ....................................................................................... 214

23. Advanced Concepts .............................................................................................. 216

23.1. Preprocessor & System Scripts ...................................................................... 216
23.2. PGS ............................................................................................................. 218
23.3. Zone and Slice Functions ............................................................................... 219
23.4. User-defined Functions .................................................................................. 220
23.5. Resource Container ....................................................................................... 221
23.6. Changing FX from KSP .................................................................................. 222
23.7. The Advanced Engine Tab .............................................................................. 223

24. Multi Script ........................................................................................................... 225

24.1. General Information ....................................................................................... 225
24.2. ignore_midi ................................................................................................... 225
24.3. on midi_in ..................................................................................................... 226
24.4. set_midi() ..................................................................................................... 227
24.5. Multi Script Command Arguments .................................................................. 227

25. New Features ........................................................................................................ 230

25.1. KONTAKT 6.5.0 ............................................................................................. 230
25.2. KONTAKT 6.4.0 ............................................................................................. 230
25.3. KONTAKT 6.3.0 ............................................................................................. 231
25.4. KONTAKT 6.2.0 ............................................................................................. 231
25.5. KONTAKT 6.1.0 ............................................................................................. 231
25.6. KONTAKT 6.0.2 ............................................................................................. 232
25.7. KONTAKT 5.8.0 ............................................................................................. 232
25.8. KONTAKT 5.7 ................................................................................................ 232
25.9. KONTAKT 5.6.8 ............................................................................................. 233
25.10. KONTAKT 5.6.5 ........................................................................................... 233
25.11. KONTAKT 5.6 .............................................................................................. 233
25.12. KONTAKT 5.5 .............................................................................................. 233
25.13. KONTAKT 5.4.2 ........................................................................................... 234
25.14. KONTAKT 5.4.1 ........................................................................................... 234
25.15. KONTAKT 5.3 .............................................................................................. 234
25.16. KONTAKT 5.2 .............................................................................................. 234
25.17. KONTAKT 5.1.1 ........................................................................................... 234
25.18. KONTAKT 5.1 .............................................................................................. 235
25.19. KONTAKT 5.0.2 ........................................................................................... 235
25.20. KONTAKT 5.0.1 ........................................................................................... 235
25.21. KONTAKT 5 ................................................................................................. 235
25.22. KONTAKT 4.2 .............................................................................................. 236
25.23. KONTAKT 4.1.2 ........................................................................................... 236
25.24. KONTAKT 4.1.1 ........................................................................................... 237
8

25.25. KONTAKT 4.0.2 ........................................................................................... 237

25.26. KONTAKT 4.1 .............................................................................................. 237
25.27. KONTAKT 4 ................................................................................................. 238
25.28. KONTAKT 3.5 .............................................................................................. 238
25.29. KONTAKT 3 ................................................................................................. 238
25.30. KONTAKT 2.2 .............................................................................................. 239
25.31. KONTAKT 2.1.1 ........................................................................................... 239
25.32. KONTAKT 2.1 .............................................................................................. 239
25.33. KONTAKT 2 ................................................................................................. 240
DISCLAIMER 1

1. Disclaimer
The information in this document is subject to change without notice and does not represent a
commitment on the part of Native Instruments GmbH. The software described by this document
is subject to a License Agreement and may not be copied to other media. No part of this
publication may be copied, reproduced or otherwise transmitted or recorded, for any purpose,
without prior written permission by Native Instruments GmbH, hereinafter referred to as Native
Instruments.
“Native Instruments”, “NI” and associated logos are (registered) trademarks of Native Instruments
GmbH.
Mac, macOS, GarageBand, Logic and iTunes are registered trademarks of Apple Inc., registered in
the U.S. and other countries.
All other trademarks are the property of their respective owners and use of them does not imply
any affiliation with or endorsement by them.
Document authored by: Nikolas Jeroma, Adam Hanley, Mario Krušelj, Elpiniki Pappa, Dinos
Vallianatos, and Yaron Eshkar.
Software version: 6.5.0 (1/2021)
CALLBACKS 2

2. Callbacks
2.1. General Information
• A callback is a section within a script that is being "called" (i.e. executed) at certain times.
• All callbacks start with on <callback-name> and end with end on.
• Callbacks can be stopped by using the exit command.
• Each callback has a unique ID number which can be retrieved with $NI_CALLBACK_ID
• You can query which callback triggered a function with $NI_CALLBACK_TYPE and the
corresponding built-in constants.

Examples
function show_callback_type
if ($NI_CALLBACK_TYPE = $NI_CB_TYPE_NOTE)
message("Function was called from note callback!")
end if
if ($NI_CALLBACK_TYPE = $NI_CB_TYPE_CONTROLLER)
message("Function was called from controller callback!")
end if
end function

on note
call show_callback_type
end on

on controller
call show_callback_type
end on
Query the callback type in a function

declare ui_menu $time

add_menu_item ($time,"16th",0)
add_menu_item ($time,"8th",1)
move_control ($time,0,0)
make_persistent ($time)
end on

function show_menu
if ($Sync = 1)
move_control ($time,2,1)
else
move_control ($time,0,0)
end if
end function

on persistence_changed
call show_menu
end on

on ui_control ($Sync)
call show_menu
end on
The same script functionality, now with persistence_changed callback

See Also
make_persistent()
read_persistent_var()
on persistence_changed
CALLBACKS 6

2.5. on listener
on listener
Listener callback, executed at definable time intervals or whenever a transport command is
received

Remarks
The listener callback is executed at time intervals defined with the set_listener() command.
It can also react to the host's transport start and stop command. This makes it the ideal callback
for anything tempo-synced like sequencers, arpeggiators, MIDI file player etc.
• In some situations (like tempo changes within the host) ticks can be left out.

Examples
on init
declare ui_knob $Test (0,99,1)
declare $direction
declare $tick_counter
set_listener($NI_SIGNAL_TIMER_MS,10000)
end on

on listener
if ($NI_SIGNAL_TYPE = $NI_SIGNAL_TIMER_MS)
if ($direction = 0)
inc($tick_counter)
else
dec($tick_counter)
end if

$Test := $tick_counter

if ($tick_counter = 99)
$direction := 1
end if
if ($tick_counter = 0)
$direction := 0
end if
end if
end on
Not useful as such, but nice to look at
See Also
set_listener()
change_listener_par()
$NI_SIGNAL_TYPE
$NI_SONG_POSITION

2.6. on note
on note
Note callback, executed whenever a note on message is received
CALLBACKS 7

Examples
on note
message("Note Nr: " & $EVENT_NOTE & " - Velocity: " & $EVENT_VELOCITY)
end on
Query note data

See Also
on release
ignore_event()
set_event_par()
get_event_par()
$EVENT_NOTE
$EVENT_VELOCITY
$EVENT_ID

2.7. on persistence_changed
on persistence_changed
Executed after the init callback or whenever a snapshot has been loaded

Remarks
The on persistence_changed callback is called whenever the persistent variables change in
an instrument, i.e. it is always executed after the init callback has been called and/or upon loading
a snapshot.

Examples
on init

set_snapshot_type(1) {init callback not executed upon snapshot loading}

reset_ksp_timer

declare $init_flag {1 if init callback has been executed, 0 otherwise}

$init_flag := 1

declare ui_label $label (2,2)

set_text($label,"init callback " & $KSP_TIMER)
end on

function add_text
add_text_line($label,"persistence_changed callback " & $KSP_TIMER)
end function

on persistence_changed
if ($init_flag = 1) {instrument has been loaded}
call add_text
else {snapshot has been loaded}
set_text($label,"Snapshot loaded")
end if
CALLBACKS 8

$init_flag := 0
end on
Query if a snapshot or instrument has been loaded. This also demonstrates the ability to call functions
upon initialization, i.e. the persistence callback acts as an extension to the init callback.

See Also
on init
read_persistent_var()
set_snapshot_type()

2.8. on pgs_changed
on pgs_changed
Executed whenever any pgs_set_key_val() command is executed in any script

Remarks
PGS stands for Program Global Storage and is a means of communication between script slots.
See the chapter on PGS for more details.

Examples
on init
pgs_create_key(FIRST_KEY, 1) {defines a key with 1 element}
pgs_create_key(NEXT_KEY, 128){defines a key with 128 elements}
declare ui_button $Push
end on

on ui_control($Push)
pgs_set_key_val(FIRST_KEY, 0,70 * $Push)
pgs_set_key_val(NEXT_KEY, 0, 50 * $Push)
pgs_set_key_val(NEXT_KEY, 127, 60 * $Push)
end on
Pressing the button...
on init
declare ui_knob $First (0,100,1)
declare ui_table %Next[128] (5,2,100)
end on

on pgs_changed

{checks if FIRST_KEY and NEXT_KEY have been declared}

if(pgs_key_exists(FIRST_KEY) and pgs_key_exists(NEXT_KEY))
$First := pgs_get_key_val(FIRST_KEY,0)
%Next[0] := pgs_get_key_val(NEXT_KEY,0)
%Next[127] := pgs_get_key_val(NEXT_KEY,127)
end if
end on
… will change the controls in this example, regardless of the script slot order

message("Button" & " (" & $ENGINE_UPTIME & ")")

end on
on ui_control ($Switch)
message("Switch" & " (" & $ENGINE_UPTIME & ")")
end on
on ui_control (%Table)
message("Table" & " (" & $ENGINE_UPTIME & ")")
end on
on ui_control ($Menu)
message("Menu" & " (" & $ENGINE_UPTIME & ")")
end on
on ui_control ($VEdit)
message("Value Edit" & " (" & $ENGINE_UPTIME & ")")
end on
on ui_control ($Slider)
message("Slider" & " (" & $ENGINE_UPTIME & ")")
end on
Various UI controls and their corresponding callbacks

3.1. General Information

• All user-defined variables must be declared in the on init callback.
• Variable names may contain only numbers, characters and the underscore ( _ ).
• Please do not create variables with the prefixes below, as these prefixes are used for internal
variables and constants.
$NI_
$CONTROL_PAR_
$EVENT_PAR_
$ENGINE_PAR_

3.2. $ (int variable)

declare $<int variable>
Declare a user-defined variable to store a single integer value

Examples
on init
declare $test
$test := -1
end on
Creating a variable
on init
declare $test := -1
end on
Creating a variable, similarly as above but with in-line value initialization

See Also
on init
make_persistent()
read_persistent_var()
int_to_real()
real_to_int()

3.3. % (int array)

declare %<array-name>[<num-of-elements>]
Declare a user-defined array to store single integer values at specific indices
VARIABLES 14

Remarks
• The maximum size of arrays is 1000000 indices.
• The number of elements must be defined with a constant value, a standard variable cannot be
used.
• It is possible to initialize an array with one value, see the second example below.

Examples
on init
declare %presets[10*8] := (...
{1} 8,8,8,0, 0,0,0,0,...
{2} 8,8,8,8, 0,0,0,0,...
{3} 8,8,8,8, 8,8,8,8,...
{4} 0,0,5,3, 2,0,0,0,...
{5} 0,0,4,4, 3,2,0,0,...
{6} 0,0,8,7, 4,0,0,0,...
{7} 0,0,4,5, 4,4,2,2,...
{8} 0,0,5,4, 0,3,0,0,...
{9} 0,0,4,6, 7,5,3,0,...
{10} 0,0,5,6, 4,4,3,2)
end on
Creating an array for storing preset data
on init
declare %presets[10*8] := (4)
end on
Quick way of initializing the same array with a specific value

See Also
Array and Group Commands
make_persistent()

3.4. ~ (real variable)

declare ~<real variable>
Declare a user-defined variable to store a single real value

Remarks
• Real numbers must always be defined with a decimal point, even if the number is a whole
number. For example 2.0 should be used instead of only 2.

Examples
on init
declare ~test
~test := 0.5
end on
Creating a variable
on init
declare ~test := 0.5
end on
VARIABLES 15

Creating a variable, the same as above but shorter

See Also
on init
make_persistent()
read_persistent_var()
int_to_real()
real_to_int()

3.5. ? (real array)

declare ?<array-name>[<num-of-elements>]
Declare a user-defined array to store single real values at specific indices

Remarks
• The maximum size of arrays is 1000000 indices.
• The number of elements must be defined with a constant real value, a standard variable
cannot be used.
• It is possible to initialize an array with one value, see the second example below.
• The commands array_equal() and search() do not work with arrays of real numbers.

Examples
on init
declare ?presets[5*4] := (...
{1} 1.0, 1.0, 1.0, 1.0,...
{2} 0.5, 0.7, 0.1, 0.5,...
{3} 1.0, 0.6, 0.6, 0.2,...
{4} 0.0, 0.0, 0.5, 0.3,...
{5} 0.0, 1.0, 0.4, 0.1)
end on
Creating an array for storing preset data
on init
declare ?presets[10*8] := (1.0)
end on
Quick way of initializing the same array with a specific value

See Also
Array and Group Commands
make_persistent()

3.6. @ (string variable)

declare @<variable-name>
Declare a user-defined string variable to store text
VARIABLES 16

Remarks
• You cannot declare and define a string variable in the same line of code as you can with an
integer variable.
• It is possible to make string variables persistent.
• The maximum length of text that can be stored in a string variable is 320 characters.

Examples
on init
declare @text
@text := "Last received note number played or released: "
end on

on note
message(@text & $EVENT_NOTE)
end on

on release
message(@text & $EVENT_NOTE)
end on
Use string variables to display long text

See Also
!(string array)
ui_text_edit
make_persistent()

3.7. ! (string array)

declare !<array-name>[<num-of-elements>]
Declare a user-defined string array to store text strings at specified indices

Remarks
• The maximum size of arrays is 1000000 indices.
• Just like with string variables, the contents of a string array cannot be defined on the same line
as the declaration.
• The maximum length of a string at any given indice is 320 characters.

Examples
on init
declare $count

declare !note[12]
!note[0] := "C"
!note[1] := "Db"
!note[2] := "D"
!note[3] := "Eb"
!note[4] := "E"
!note[5] := "F"
VARIABLES 17

!note[6] := "Gb"
!note[7] := "G"
!note[8] := "Ab"
!note[9] := "A"
!note[10] := "Bb"
!note[11] := "B"

declare !name [128]

while ($count < 128)
!name[$count] := !note[$count mod 12] & (($count/12)-2)
inc ($count)
end while
end on

on note
message("Note played: " & !name[$EVENT_NOTE])
end on
Creating a string array with all MIDI note names

3.8. const $ (constant integer)

declare const $<variable-name>
Declare a user-defined constant to store a single integer value

Remarks
• As the name implies, the value of constant variables can only be read, not changed.
• It is quite common to capitalize the names of constants.

Examples
on init
declare const $NUM_OF_PRESETS := 10
declare const $NUM_OF_PARAMETERS := 5

declare %preset_data[$NUM_OF_PRESETS * $NUM_OF_PARAMETERS]

end on
Creating constants – useful when creating preset arrays

3.9. const ~ (real constant)

declare const ~<variable-name>
Declare a user-defined constant to store a single real value
VARIABLES 18

Remarks
• As the name implies, the value of constant variables can only be read, not changed.
• It is quite common to capitalize the names of constants.

Examples
on init
declare const ~BIG_NUMBER := 100000.0
declare const ~SMALL_NUMBER := 0.00001
end on

3.10. polyphonic $ (polyphonic integer)

declare polyphonic $<variable-name>
Declare a user-defined polyphonic variable to store a single integer value per note event

Remarks
• A polyphonic variable acts as a unique variable for each executed note event, avoiding
conflicts in callbacks that are executed in parallel, for example when using wait().
• A polyphonic variable retains its value in the release callback of the corresponding note.
• Polyphonic variables need much more memory than normal variables.
• Polyphonic variables can only be used in note and release callbacks.

Examples
on init
declare polyphonic $a
{declare $a}
end on

on note
ignore_event($EVENT_ID)
$a:= 0
while ($a < 13 and $NOTE_HELD = 1) play_note($EVENT_NOTE+
$a,$EVENT_VELOCITY,0,$DURATION_QUARTER/2)
inc($a)
wait($DURATION_QUARTER)
end while
end on
To hear the effect of the polyphonic variable, play and hold an octave: both notes will ascend
chromatically. Then make $a a normal variable and play the octave again: $a will be shared by both
executed callbacks, thus both notes will ascend in larger intervals.
on init
declare $counter
declare polyphonic $polyphonic_counter
end on

on note
VARIABLES 19

message($polyphonic_counter & " " & $counter)

inc($counter)
inc($polyphonic_counter)
end on
Since a polyphonic variable is always unique per callback, $polyphonic_counter will always be 0 in the
displayed message

3.11. make_instr_persistent()
make_instr_persistent(<variable>)
Retain the value of a variable within the instrument only

Remarks
make_instr_persistent() is similar to make_persistent(), however the value of a
variable is only saved with the instrument, not with snapshots. It can be used to prevent UI
elements from being changed when loading snapshots.

Examples
on init

set_snapshot_type(1) {init callback not executed upon snapshot loading}

declare ui_knob $knob_1 (0,2,1)

set_text($knob_1,"Pers.")
make_persistent($knob_1)

declare ui_knob $knob_2 (0,2,1)

set_text($knob_2,"Inst Pers.")
make_instr_persistent ($knob_2)

declare ui_knob $knob_3 (0,2,1)

set_text($knob_3,"Not Pers.")

end on
The second knob will not be changed when loading snapshots

See Also
read_persistent_var()
make_persistent()
set_snapshot_type()

3.12. make_persistent()
make_persistent(<variable>)
Retain the value of a variable with the instrument and snapshot

Remarks
• The state of the variable is saved not only with the patch (or multi or host chunk), but also
when a script is saved as a KONTAKT preset (.nkp file).
VARIABLES 20

• The state of the variables is read at the end of the init callback. To load a stored value
manually within the init callback, use read_persistent_var().
• You can also use the on persistence callback for retrieving the values of persistent
variables
• When updating script code by replacing old code with new one, the values of persistent
variables will be retained.
• Sometimes, when working on more complex scripts, you might want to flush the values of
persistent variables by resetting the script. You can do this by loading an empty script slot
from the Script Editor preset menu, then applying your code again.

Examples
on init
declare ui_knob $Preset (1,10,1)
make_persistent ($Preset)
end on
User interface elements, such as knobs, should usually retain their value when reloading the instrument

See Also
read_persistent_var()
on persistence_changed
make_instr_persistence()

3.13. read_persistent_var()
read_persistent_var(<variable>)
Instantly reloads the value of a variable that was saved via the make_persistent()
command

Remarks
• This command can only be used within the init callback.
• The state of the variable is saved not only with the patch (or multi or host chunk), but also
when a script is saved as a KONTAKT preset (.nkp file).
• When updating script code by replacing old code with new one, the values of persistent
variables will be retained.
• Sometimes, when working on more complex scripts, you might want to flush the values of
persistent variables by resetting the script. You can do this by loading an empty script slot
from the Script Editor preset menu, then applying your code again.
• You can also use the on persistence callback for retrieving the values of persistent
variables.

Examples
on init
declare ui_label $label (1,1)
declare ui_button $button
set_text($button,"$a := 10000")
VARIABLES 21

declare $a
make_persistent($a)
{read_persistent_var($a)}
set_text ($label,$a)
end on

on ui_control ($button)
$a := 10000
set_text($label,$a)
end on
After applying this script, click on the button and then save and close the NKI. After reloading it, the label
will display 0 because the value of $a is initialized at the very end of the init callback. Now remove the {}
around read_persistent_var and apply the script again.

See Also
make_persistent()
on persistence_changed

3.14. watch_var()
watch_var(<variable>)
sends an event to the Creator Tools KSP Log for every change of the watched variable’s value

Remarks
• This command can only be used within the init callback.
• This command has no effect on KONTAKT’s status bar – the events only appear in Creator
Tools.
• This command does not work with built-in variables

Examples
on init
declare $intVar
watch_var($intVar)
make_persistent($intVar)

end on

on note
$intVar := $EVENT_VELOCITY
end on
Try playing some notes while having Creator Tools running. Make sure you have the Variable Watching
panel of the Debugger tool open.

3.15. watch_array_idx()
watch_array_idx(<array>, <array_idx>)
sends an event to the Creator Tools KSP Log for every change of the watched array cell’s value
VARIABLES 22

Examples
on init
declare %mykeys[128]
watch_array_idx(%mykeys,60)
watch_array_idx(%mykeys,61)
watch_array_idx(%mykeys,62)
watch_array_idx(%mykeys,63)
watch_array_idx(%mykeys,64)

declare ui_button
$save
declare ui_button
$load
end on

on note
%mykeys[$EVENT_NOTE]
:= $EVENT_VELOCITY
end on

on ui_control($save)
save_array(%mykeys,0)
end on

on ui_control($load)
load_array(%mykeys,0)
end on

Try playing some notes or clicking on the save and load buttons while having Creator Tools running.
Make sure you have the Variable Watching panel of the Debugger tool open.
CONTROL STATEMENTS 23

4. Control Statements

4.1. if…else…end
if…else…end if
Conditional if statement

message("Pitch Bend up")

end select
end if
end on
Query the state of the pitch bend wheel

4.4. Boolean Operators

Boolean Operators
x > y Greater than
x > y Less than
x >= y Greater than or equal
x <= y Less than or equal
x = y Equal
x # y Not equal
in_range(x,y,z) True if x is between y and z
not a True if a is false and vice versa
a and b True if a is true and b is true
a or b True if a is true or b is true
CONTROL STATEMENTS 25

Remarks
• Boolean operators are used in if and while statements, since they return if the condition is
either true or false. In the list above. x, y and z denote numerals, a and b stand for Boolean
values.
USER INTERFACE CONTROLS 26

5. User Interface Controls

5.1. ui_button
declare ui_button $<variable-name>
Create a user interface button

Remarks
• A button, i.e. its callback, is triggered when releasing the mouse (mouse-up).
• A button cannot be automated.

Examples
on init
declare ui_button $free_sync_button
$free_sync_button := 1
set_text ($free_sync_button,"Sync")
make_persistent ($free_sync_button)

read_persistent_var($free_sync_button)
if ($free_sync_button = 0)
set_text ($free_sync_button,"Free")
else
set_text ($free_sync_button,"Sync")
end if
end on

on ui_control ($free_sync_button)
if ($free_sync_button = 0)
set_text ($free_sync_button,"Free")
else
set_text ($free_sync_button,"Sync")
end if
end on
A simple free/sync button implementation

declare ui_file_selector $file_browser

declare $browser_id
$browser_id := get_ui_id($file_browser)

set_control_par_str($browser_id,$CONTROL_PAR_BASEPATH,@basepath)
set_control_par($browser_id,$CONTROL_PAR_FILE_TYPE,$NI_FILE_TYPE_MIDI)
set_control_par($browser_id,$CONTROL_PAR_COLUMN_WIDTH,180)
set_control_par($browser_id,$CONTROL_PAR_HEIGHT,170)
set_control_par($browser_id,$CONTROL_PAR_WIDTH,550)
move_control_px($file_browser,66,2)

declare ui_button $prev

declare ui_button $next
move_control($prev,5,1)
move_control($next,6,1)

declare $load_mf_id
$load_mf_id := -1

end on
on async_complete
if ($NI_ASYNC_ID = $load_mf_id)
$load_mf_id := -1
if ($NI_ASYNC_EXIT_STATUS = 0)
message("MIDI file not found!")
else
message("Loaded MIDI File: " & @file_name)
end if
end if
end on
on ui_control ($file_browser)
@file_name := fs_get_filename($browser_id,0)
@file_path := fs_get_filename($browser_id,2)
$load_mf_id := load_midi_file(@file_path)
end on
on ui_control ($prev)
fs_navigate($browser_id,0)
@file_name := fs_get_filename($browser_id,0)
@file_path := fs_get_filename($browser_id,2)
$load_mf_id := load_midi_file(@file_path)
$prev := 0
end on
on ui_control ($next)
fs_navigate($browser_id,1)
@file_name := fs_get_filename($browser_id,0)
@file_path := fs_get_filename($browser_id,2)
$load_mf_id := load_midi_file(@file_path)
$next := 0
end on
Loading MIDI files via UI file selector
USER INTERFACE CONTROLS 28

5.3. ui_label
declare ui_label $<variable-name> (<width>,<height>)
Create a user interface text label
<width> The width of the label in grid units
<height> The height of the label in grid units

Examples
on init
declare ui_label $label_1 (1,1)
set_text ($label_1,"Small Label")

declare ui_label $label_2 (3,6)

set_text ($label_2,"Big Label")
add_text_line ($label_2,"…with a second text line")
end on
Two labels with different sizes
on init
declare ui_label $label_1 (1,1)
set_text ($label_1,"Small Label")
hide_part ($label_1,$HIDE_PART_BG)
end on
Hide the background of a label (also possible with other UI elements)

See Also
set_text()
add_text_line()
hide_part()

5.4. ui_knob
declare ui_knob $<variable-name>(<min>,<max>,<display-ratio>)
Create a user interface knob
<min> The minimum value of the knob
<max> The maximum value of the knob
<display-ratio> The knob value is divided by <display-ratio> for display purposes

Examples
on init
declare ui_knob $Knob_1 (0,1000,1)
declare ui_knob $Knob_2 (0,1000,10)
declare ui_knob $Knob_3 (0,1000,100)
declare ui_knob $Knob_4 (0,1000,20)
declare ui_knob $Knob_5 (0,1000,-10)
end on
Various display ratios
on init
declare $count
USER INTERFACE CONTROLS 29

declare !note_class[12]
!note_class[0] := "C"
!note_class[1] := "Db"
!note_class[2] := "D"
!note_class[3] := "Eb"
!note_class[4] := "E"
!note_class[5] := "F"
!note_class[6] := "Gb"
!note_class[7] := "G"
!note_class[8] := "Ab"
!note_class[9] := "A"
!note_class[10] := "Bb"
!note_class[11] := "B"
declare !note_names [128]
while ($count < 128)
!note_names[$count] := !note_class[$count mod 12] & (($count/12)-2)
inc ($count)
end while

declare ui_knob $Note (0,127,1)

set_knob_label ($Note,!note_names[$Note])
make_persistent ($Note)

read_persistent_var($Note)
set_knob_label ($Note,!note_names[$Note])
end on
on ui_control ($Note)
set_knob_label ($Note,!note_names[$Note])
end on
Knob displaying MIDI note names

5.5. ui_level_meter
declare ui_level_meter $<variable-name>
Create a level meter

Remarks
• The level meter can only be attached to the output levels of buses or the instrument master.

Examples
on init
declare ui_level_meter $Level1
declare ui_level_meter $Level2
attach_level_meter (get_ui_id($Level1),-1,-1,0,-1)
attach_level_meter (get_ui_id($Level2),-1,-1,1,-1)
end on
Creating two volume meters, each displaying one channel of KONTAKT’s instrument output

See Also
$CONTROL_PAR_BG_COLOR
$CONTROL_PAR_OFF_COLOR
$CONTROL_PAR_ON_COLOR
USER INTERFACE CONTROLS 30

$CONTROL_PAR_OVERLOAD_COLOR
$CONTROL_PAR_PEAK_COLOR
$CONTROL_PAR_VERTICAL
attach_level_meter()

5.6. ui_menu
declare ui_menu $<variable-name>
Create a user interface drop-down menu

Examples
on init
declare ui_menu $menu
add_menu_item ($menu, "First Entry",0)
add_menu_item ($menu, "Second Entry",1)
add_menu_item ($menu, "Third Entry",2)
end on
A simple menu
on init
declare $count
declare ui_menu $menu

$count := 1
while ($count < 17)
add_menu_item ($menu, "Entry Nr: " & $count,$count)
inc ($count)
end while
end on
Quickly create a menu with many entries

See Also
add_menu_item()
get_menu_item_str()
get_menu_item_value()
get_menu_item_visibility()
set_menu_item_str()
set_menu_item_value()
set_menu_item_visibility()

5.7. ui_mouse_area
declare ui_mouse_area
Create a user interface mouse area
USER INTERFACE CONTROLS 31

Remarks
• A mouse area supports drag and drop of the following file types: audio (WAV, AIF, AIFF, NCW),
MIDI and array (NKA).
• It is possible to define which types of files are accepted as drop targets, and whether to accept
just one or multiple files.
• The mouse area widget is invisible, but the drop target can be shown or hidden like any other
UI widget.

Examples
on init
declare ui_mouse_area $waveDnD
set_control_par(get_ui_id($waveDnD),
$CONTROL_PAR_DND_ACCEPT_AUDIO, $NI_DND_ACCEPT_ONE)
set_control_par(get_ui_id($waveDnD),
$CONTROL_PAR_DND_ACCEPT_ARRAY,
$NI_DND_ACCEPT_ONE)set_control_par(get_ui_id($waveDnD),
$CONTROL_PAR_WIDTH,90)set_control_par(get_ui_id($waveDnD),
$CONTROL_PAR_HEIGHT,32)set_control_par(get_ui_id($waveDnD),
$CONTROL_PAR_RECEIVE_DRAG_EVENTS, 1)

end on
The on ui_control callback is triggered by a drop action. It has 3 built-in arrays:
!NI_DND_ITEMS_AUDIO
!NI_DND_ITEMS_MIDI
!NI_DND_ITEMS_ARRAY

Example UI callback
on ui_control ($waveDnD)
if ($NI_MOUSE_EVENT_TYPE = $NI_MOUSE_EVENT_TYPE_DRAG)
message("DRAG")
message("MOUSE OVER CONTROL: " & $NI_MOUSE_OVER_CONTROL)
end if

if ($NI_MOUSE_EVENT_TYPE = $NI_MOUSE_EVENT_TYPE_DROP)
if (num_elements(!NI_DND_ITEMS_AUDIO) = 1)
wait_async(set_sample(%NI_USER_ZONE_IDS[0],
!NI_DND_ITEMS_AUDIO[0]))
end if
end if
end on

See Also
$NI_MOUSE_EVENT_TYPE
$NI_MOUSE_EVENT_TYPE_DND_DROP
$NI_MOUSE_EVENT_TYPE_DND_DRAG
$NI_MOUSE_OVER_CONTROL
USER INTERFACE CONTROLS 32

5.8. ui_panel
declare ui_panel $<variable-name>
Create a user interface panel

Remarks
A panel is a control that can contain one or multiple controls. Unlike the rest of the UI control
types, panels don’t have size. They are very useful for grouping controls that are meant to be
handled together, then one can simultaneously modify the $CONTROL_PAR_HIDE,
$CONTROL_PAR_POS_X, $CONTROL_PAR_POS_Yor $CONTROL_PAR_Z_LAYER properties of all
the controls contained in that panel. The position of a contained control is relative to the panel’s
position. This means that the control’s (0,0) position is the current (x,y) position of the panel.
Panels can be nested, so they can contain other panels. If panelA is contained in panelB, then
panelA will appear in front of panelB. This is because children panels have a higher Z-layer value
than their parent panels. One could use this logic to easily create hierarchies in a performance
view.

Examples
on init
declare ui_panel $mixer
declare ui_knob $volume(0,300,1)

set_control_par(get_ui_id($volume),$CONTROL_PAR_PARENT_PANEL,get_ui_id($mixer))
end on
Adds the volume knob in the mixer panel

declare ui_table %<array>[columns](<width>,<height>,<range>)

<height> The height of the table in grid units
<range> The range of the table. If negative values are used, a bipolar table is created.

Remarks
• The maximum number of columns in a ui_table is 128.

Examples
on init
declare ui_table %table_uni[10] (2,2,100)
declare ui_table %table_bi[10] (2,2,-100)
end on
Unipolar and bipolar tables
on init
declare ui_table %table[128] (5,2,100)
declare ui_value_edit $Steps (1,127,1)
$Steps := 16
set_table_steps_shown (%table,$Steps)
end on
on ui_control ($Steps)
set_table_steps_shown (%table,$Steps)
end on
Changes the amount of shown steps (columns) in a table
on init
declare ui_table %table[20] (4,4,100)
declare ui_button $button
end on

on ui_control($button)
if($button = 1)
hide_part(%table,$HIDE_PART_VALUE)
else
hide_part(%table,$HIDE_PART_NOTHING)
end if
end on
Hiding a table value

See Also
set_table_steps_shown()
$NI_CONTROL_PAR_IDX
hide_part()

5.12. ui_text_edit
declare ui_text_edit @<variable-name>
Create a text edit field

Examples
on init
USER INTERFACE CONTROLS 35

declare ui_text_edit @label_name

make_persistent(@label_name)

set_control_par_str(get_ui_id(@label_name),$CONTROL_PAR_TEXT,"empty")
set_control_par(get_ui_id(@label_name),$CONTROL_PAR_FONT_TYPE,25)
set_control_par(get_ui_id(@label_name),$CONTROL_PAR_POS_X,73)
set_control_par(get_ui_id(@label_name),$CONTROL_PAR_POS_Y,2)

declare ui_label $pattern_lbl(1,1)

set_text($pattern_lbl,"")
move_control_px($pattern_lbl,66,2)

end on

on ui_control (@label_name)
message(@label_name & " it is!")
end on
A text edit field on top of a label

You can also use $VALUE_EDIT_MODE_NOTE_NAMES to display note

names instead of numbers.

Examples
on init
declare ui_value_edit $test (0,100,$VALUE_EDIT_MODE_NOTE_NAMES)
set_text ($test,"")
set_control_par (get_ui_id($test),$CONTROL_PAR_WIDTH,45)
move_control_px($test,66,2)
end on

on note
$test := $EVENT_NOTE
end on
Value edit displaying note names
on init
declare ui_value_edit $test (0,10000,1000)
set_text ($test,"Value")
end on
Value edit with three decimal spaces
USER INTERFACE CONTROLS 36

See Also
$VALUE_EDIT_MODE_NOTE_NAMES
$CONTROL_PAR_SHOW_ARROWS

5.14. ui_waveform
declare ui_waveform $<variable>(<width>,<height>)
Create a waveform control to display zones and slices. This can also be used to control specific
parameters per slice and for drag and drop functionality.
<width> The width of the waveform in grid units
<height> The height of the waveform in grid units

Examples
on init
declare ui_waveform $Waveform(6,6)
attach_zone ($Waveform,find_zone(”Test”),0)
end on
Displays the zone “Test” within the waveform control. Use a sample named Test to test the above code.

See Also
set_ui_wf_property()
get_ui_wf_property()
attach_zone()
find_zone()
Waveform Flag Constants
Waveform Property Constants
$CONTROL_PAR_WAVE_COLOR
$CONTROL_PAR_BG_COLOR
$CONTROL_PAR_WAVE_CURSOR_COLOR
$CONTROL_PAR_SLICEMARKERS_COLOR
$CONTROL_PAR_BG_ALPHA

5.15. ui_wavetable
declare ui_wavetable $ <variable>
create a wavetable widget, visualizing the state of a zone that is running in wavetable mode

Examples
on init
declare ui_wavetable $wavetable
set_control_par(get_ui_id($wavetable), $CONTROL_PAR_WT_ZONE,…
find_zone(“Wavetable01”)
USER INTERFACE CONTROLS 37

end on
Displays the zone “Wavetable01” within the wavetable control. Use a wavetable named Wavetable01 to
test the above code.

See Also
set_control_par()
find_zone()
$CONTROL_PAR_WT_VIS_MODE
$NI_WT_VIS_2D
$NI_WT_VIS_3D
$CONTROL_PAR_WAVE_COLOR
$CONTROL_PAR_BG_COLOR
$CONTROL_PAR_BG_ALPHA
$CONTROL_PAR_WAVE_COLOR
$CONTROL_PAR_WAVE_ALPHA
$CONTROL_PAR_WAVE_END_COLOR
$CONTROL_PAR_WAVE_END_ALPHA
$CONTROL_PAR_WAVETABLE_COLOR
$CONTROL_PAR_WAVETABLE_ALPHA
$CONTROL_PAR_WAVETABLE_END_COLOR
$CONTROL_PAR_WAVETABLE_END_ALPHA
$CONTROL_PAR_PARALLAX_X
$CONTROL_PAR_PARALLAX_Y
$CONTROL_PAR_WT_ZONE

5.16. ui_xy
declare ui_xy ?<array>[num-of-elements]
Create an XY pad

Remarks
• The range of each axis on the XY pad is always between 0.0 and 1.0.
• The number of cursors in the XY pad, i.e. the interactive elements, is defined by the size of the
array. Each index in the array represents one axis of one cursor, so two indices are needed for
each cursor. Applying this, if you wanted to create an XY pad with 3 cursors, then the size of
the XY array would be 6 elements.
• The maximum size of the XY array is 32 elements, so the maximum number of cursors in the
XY pad is 16.
• The even indices of the array hold the X axis value of the cursors, and the odd indices hold the
Y axis values. So index 0 is the X value of the first cursor, and index 1 is the Y value of the first
cursor.
USER INTERFACE CONTROLS 38

• It is possible to define how the XY pad reacts to mouse interaction using the
$CONTROL_PAR_MOUSE_MODE parameter.
• Querying $NI_MOUSE_EVENT_TYPE within the on ui_control() callback allows
identification of the mouse event type that triggered it.

Examples
on init

{basic initialization}
message("")
make_perfview

set_ui_color(9ddddddh)
set_ui_height_px(350)

{create an XY pad with 2 cursors}

declare ui_xy ?myXY[4]

{store the UI ID of the XY pad}

declare $xyID
$xyID := get_ui_id(?myXY)

{skinning the cursors}

set_control_par_str_arr($xyID, $CONTROL_PAR_CURSOR_PICTURE, ...
"Picture1", 0)
set_control_par_str_arr($xyID, $CONTROL_PAR_CURSOR_PICTURE, ...
"Picture2", 2)

{set automation IDs and names}

set_control_par_arr($xyID, $CONTROL_PAR_AUTOMATION_ID, 0, 0)
set_control_par_arr($xyID, $CONTROL_PAR_AUTOMATION_ID, 1, 1)
set_control_par_arr($xyID, $CONTROL_PAR_AUTOMATION_ID, 2, 2)
set_control_par_arr($xyID, $CONTROL_PAR_AUTOMATION_ID, 3, 3)

set_control_par_str_arr($xyID, $CONTROL_PAR_AUTOMATION_NAME, ...

"Cutoff", 0)
set_control_par_str_arr($xyID, $CONTROL_PAR_AUTOMATION_NAME, ...
"Resonance", 1)
set_control_par_str_arr($xyID, $CONTROL_PAR_AUTOMATION_NAME, ...
"Delay Pan", 2)
set_control_par_str_arr($xyID, $CONTROL_PAR_AUTOMATION_NAME, ...
"Delay Feedback", 3)

{define the mouse behaviour}

set_control_par($xyID, $CONTROL_PAR_MOUSE_MODE, 0)
set_control_par($xyID, $CONTROL_PAR_MOUSE_BEHAVIOUR_X, 1000)
set_control_par($xyID, $CONTROL_PAR_MOUSE_BEHAVIOUR_Y, 1000)

{position and size}

set_control_par($xyID, $CONTROL_PAR_POS_X, 50)
set_control_par($xyID, $CONTROL_PAR_POS_Y, 50)
set_control_par($xyID, $CONTROL_PAR_WIDTH, 200)
set_control_par($xyID, $CONTROL_PAR_HEIGHT, 200)

{move the cursors to the center of the XY pad}

?myXY[0] := 0.5 {1st cursor, X axis}
?myXY[1] := 0.5 {1st cursor, Y axis}
USER INTERFACE CONTROLS 39

?myXY[2] := 0.5 {2nd cursor, X axis}

?myXY[3] := 0.5 {2nd cursor, Y axis}

end on
Creating an XY pad control with two cursors, custom cursor images, and automation information

See Also
$CONTROL_PAR_MOUSE_MODE
$CONTROL_PAR_ACTIVE_INDEX
$CONTROL_PAR_CURSOR_PICTURE
$CONTROL_PAR_MOUSE_BEHAVIOUR_X
$CONTROL_PAR_MOUSE_BEHAVIOUR_Y
set_control_par_arr()
set_control_par_str_arr()
$HIDE_PART_CURSOR
$NI_CONTROL_PAR_IDX
ARITHMETIC COMMANDS & OPERATORS 40

6. Arithmetic Commands & Operators

6.1. Basic Operators

Basic operators
The following operators work on both integers and real numbers.
x := y Assignment (the value of y is assigned to x)
x + y Addition
x - y Subtraction
x * y Multiplication
x / y Division
-x Negative value
abs(x) Absolute value

6.2. Integer Operators & Commands

The following commands and operators can only be performed on integer variables and values.

inc(x)
Increment an expression by 1 (x + 1)

dec(x)
Decrement an expression by 1 (x – 1)

x mod y
Modulo; returns the remainder of a division

e.g. 13 mod 8 returns the value 5

6.3. Real Number Commands

The following commands can only be performed on real numbers.

exp(x)
Exponential function (returns the value of e^x)

log(x)
Logarithmic function

pow(x,y)
Power (returns the value of x^y)
ARITHMETIC COMMANDS & OPERATORS 41

sqrt(x)
Square root

6.4. Rounding Commands

Rounding commands can only be performed on real numbers.

ceil(x)
Ceiling (round up)

ceil(2.3) = 3.0

floor(x)
Floor (round down)

floor(2.8) = 2.0

round(x)
Round (round to nearest)

round(2.3) = 2.0

round(2.8) = 3.0

6.5. Trigonometric Commands

Trigonometric commands can only be performed on real numbers.

cos(x)
cosine function

sin(x)
sine function

tan(x)
tangent function

acos(x)
arccosine (inverse cosine function)

asin(x)
arcsine (inverse sine function)

atan(x)
arctangent (inverse tangent function)
ARITHMETIC COMMANDS & OPERATORS 42

6.6. Bit Operators

The following bit operators can be used:

Bit Operators
x .and. y Bitwise and
x .or. y Bitwise or
.not. x Bitwise negation
sh_left(<expression>,<shift-bits>) Shifts the bits in <expression> by the
amount of <shift-bits> to the left
sh_right(<expression>,<shift- Shifts the bits in <expression> by the
bits>) amount of <shift-bits> to the right

6.7. random()
random(<min>,<max>)
Generate a random integer between (and including) <min> and <max>.

Examples
on init
declare $rnd_amt
declare $new_vel
end on

on note
$rnd_amt := $EVENT_VELOCITY * 10/100
$new_vel := random($EVENT_VELOCITY-$rnd_amt,$EVENT_VELOCITY+$rnd_amt)
change_velo($EVENT_ID,$new_vel)
end on
Randomly changing velocities by ±10 percent

6.8. int_to_real()
int_to_real(<integer value>)
Converts an integer value into a real number

Examples
on init
declare ~velocity_disp
end on

on note
~velocity_disp := int_to_real($EVENT_VELOCITY)/127.0
message(~velocity_disp)
end on
Displays the event velocity in the range 0.0 to 1.0
ARITHMETIC COMMANDS & OPERATORS 43

$ENGINE_UPTIME & " milliseconds")

end on
Concatenating elements in a message() command

See Also
$ENGINE_UPTIME
$KSP_TIMER
reset_ksp_timer
declare ui_label
set_text()

7.5. note_off()
note_off(<ID-number>)
Send a note off message to a specific note
<ID-number> The ID number of the note event

Remarks
• note_off() is equivalent to releasing a key, thus it will always trigger a release callback as
well as the release portion of a volume envelope. Notice the difference between note_off()
and fade_out(), since fade_out() works on voice level.

Examples
on controller
if ($CC_NUM = 1)
note_off($ALL_EVENTS)
end if
end on
A custom "All Notes Off" implementation triggered by the mod wheel
on init
declare polyphonic $new_id
end on

on note
ignore_event($EVENT_ID)
$new_id := play_note($EVENT_NOTE,$EVENT_VELOCITY,0,0)
end on

on release
ignore_event($EVENT_ID)
wait(200000)
note_off($new_id)
end on
Delaying the release of each note by 200ms

See Also
fade_out()
play_note()
GENERAL COMMANDS 48

7.6. play_note()
play_note(<note-number>,<velocity>,<sample-offset>,<duration>)
Generate a note, i.e. generate a note-on message followed by a note-off message
<note-number> The note number to be generated (0 - 127)
<velocity> Velocity of the generated note (1 - 127)
<sample-offset> Sample offset in microseconds
<duration> Length of the generated note in microseconds

This parameter also accepts two special values:

-1: releasing the note which started the callback stops the sample

0: the entire sample is played

Remarks
• In DFD mode, the sample offset is dependent on the Sample Mod (S.Mod) value of the
respective zones. Sample offset value greater than the zone's S.Mod setting will be ignored
and no sample offset will be applied.
• You can retrieve the event ID of the played note in a variable by writing:
<variable> := play_note(<note>, <velocity>, <sample-offset>,
<duration>)

Examples
on note
play_note($EVENT_NOTE+12,$EVENT_VELOCITY,0,-1)
end on

Harmonizes the played note with the upper octave

on init
declare $new_id
end on
on controller
if ($CC_NUM = 64)
if (%CC[64] = 127)
$new_id := play_note(60,100,0,0)
else
note_off($new_id)
end if
end if
end on
Trigger a MIDI note by pressing the sustain pedal

• A number from 0 to 127 designates a MIDI CC number

• $VCC_PITCH_BEND indicates pitch bend

• $VCC_MONO_AT indicates channel pressure (monophonic

aftertouch)
<value> The value of the specified controller:

• MIDI CC and channel pressure values go from 0 to 127

• Pitch bend values go from -8192 to 8191

Remarks
• set_controller()cannot be used within an init callback. If for some reason you wat to
send a controller value upon instrument load, use persistance_changed callback.
on note
if ($EVENT_NOTE = 36)
ignore_event($EVENT_ID)
set_controller($VCC_MONO_AT,$EVENT_VELOCITY)
end if
end on
on release
if ($EVENT_NOTE = 36)
ignore_event($EVENT_ID)
set_controller($VCC_MONO_AT,0)
end if
end on
If you have a keyboard with no aftertouch, press C1 instead

See Also
ignore_controller
$VCC_PITCH_BEND
$VCC_MONO_AT

7.8. set_rpn()/set_nrpn()
set_rpn(<address>,<value>)
Send a RPN or NRPN message
<address> The RPN or NRPN address (0 - 16383)
<value> The value of the RPN or NRPN message (0 - 16383)
GENERAL COMMANDS 50

Remarks
• KONTAKT cannot handle RPN or NRPN messages as external modulation sources. You can
however use these message for simple inter-script communication.

See Also
on rpn/nrpn
set_controller
$RPN_ADDRESS
$RPN_VALUE
msb()
lsb()

7.9. set_snapshot_type()
set_snapshot_type(<type>)
Configures the KSP processor behavior of all five slots when a snapshot is recalled
<type> The available types are:

0: The init callback will always be executed upon snapshot change, afterwards
the on persistence_changed callback will be executed (default behavior)

1: the init callback will not be executed upon loading a snapshot, only the on
persistence_callback will be executed

Remarks
• This command acts globally, i.e. it can applied in any script slot.
• In snapshot type 1, the value of non-persistent and instrument persistence variable is
preserved.
• Loading a snapshot always resets KONTAKT's audio engine, i.e. audio is stopped and all active
events are deleted.

Examples
on init
set_snapshot_type(1)

declare ui_knob $knob_1 (0,127,1)

set_text($knob_1,"Knob")
make_persistent($knob_1)

declare ui_button $gui_btn

set_text($gui_btn,"Page 1")
end on
function show_gui
if ($gui_btn = 1)

set_control_par(get_ui_id($knob_1),$CONTROL_PAR_HIDE,...
$HIDE_PART_NOTHING)
else
GENERAL COMMANDS 51

set_control_par(get_ui_id($knob_1),$CONTROL_PAR_HIDE,$HIDE_WHOLE_CONTROL)
end if
end function
on persistence_changed
call show_gui
end on
on ui_control ($gui_btn)
call show_gui
end on
Retaining the GUI upon loading snapshots

See Also
on init
on persistence_changed
EVENT COMMANDS 52

8. Event Commands

8.1. by_marks()
by_marks(<bit-mark>)
A user-defined group of events (or event IDs)

Remarks
by_marks() is a user-defined group of events which can be set with set_event_mark(). It can
be used with all commands which utilize event IDs like note_off(), change_tune() etc.

Examples
on note
if ($EVENT_NOTE mod 12 = 0) {if played note is a c}
set_event_mark($EVENT_ID,$MARK_1)
change_tune(by_marks($MARK_1),%CC[1]*1000,0)
end if
end on

on controller
if($CC_NUM = 1)
change_tune(by_marks($MARK_1),%CC[1]*1000,0)
end if
end on
Moving the mod wheel changes the tuning of all C notes (C-2, C-1…C8)

See Also
set_event_mark()
$EVENT_ID
$ALL_EVENTS
$MARK_1 … $MARK_28

8.2. change_note()
change_note(<ID-number>,<note-number>)
Change the note number of a specific note event

Remarks
• change_note() is only allowed in the note callback and only works before the first wait()
statement. If the voice is already running, only the value of the variable changes.
• Once the note number of a particular note event is changed, it becomes the new
$EVENT_NOTE
• It is not possible to address events via event groups like $ALL_EVENTS
EVENT COMMANDS 53

Examples
on init
declare %black_keys[5] := (1,3,6,8,10)
end on

on note
if (search(%black_keys,$EVENT_NOTE mod 12) # -1)
change_note($EVENT_ID,$EVENT_NOTE-1)
end if
end on
Constrain all notes to white keys, i.e. C major

If set to 1, the amount is relative to the actual value of the event.

The different implications are only relevant with more than one
change_pan() statement applied to the same event.

Remarks
• change_pan() works on the note event level and does not change any panorama settings in
the instrument itself. It is also not related to any modulations regarding panorama.

Examples
on init
declare $pan_position
end on
on note
$pan_position := ($EVENT_NOTE * 2000 / 127) - 1000
change_pan ($EVENT_ID,$pan_position,0)
end on
Panning the entire key range from left to right, i.e. C-2 all the way left, G8 all the way right
on note
if ($EVENT_NOTE < 60)
change_pan ($EVENT_ID,1000,0)
wait(500000)
change_pan ($EVENT_ID,-1000,0) {absolute, pan is at -1000}
else
change_pan ($EVENT_ID,1000,1)
EVENT COMMANDS 54

wait(500000)
change_pan ($EVENT_ID,-1000,1) {relative, pan is at 0}
end if
end on
Notes below C3 utilize a relative bit of 0. C3 and above utilize a relative bit of 1

If it is set to 1, the amount is relative to the actual value of the event.

The different implications are only relevant with more than one
change_tune()statement applied to the same event.

Remarks
• change_tune() works on the note event level and does not change any tune settings in the
instrument itself. It is also not related to any modulations regarding tuning.

Examples
on init
declare $tune_amount
end on

on note
$tune_amount := random(-50000,50000)
change_tune ($EVENT_ID,$tune_amount,1)
end on
Randomly detune every played note by ± 50 cent

See Also
change_vol()
change_pan()
EVENT COMMANDS 55

8.5. change_velo()
change_velo(<ID-number>, <velocity>)
Change the velocity of a specific note event

Remarks
• change_velo() is only allowed in the note callback and only works before the first wait()
statement. If the voice is already running, only the value of the variable changes.
• Once the velocity of a particular note event is changed, it becomes the new
$EVENT_VELOCITY
• It is not possible to address events via event groups like $ALL_EVENTS

Examples
on note
change_velo ($EVENT_ID,100)
message($EVENT_VELOCITY)
end on
All velocities are set to 100. Note that $EVENT_VELOCITY will also change to 100.

If it is set to 1, the amount is relative to the actual value of the event.

The different implications are only relevant with more than one
change_vol() statement applied to the same event.

Remarks
• change_vol() works on the note event level and does not change any tune settings in the
instrument itself. It is also not related to any MIDI modulations regarding volume (e.g. MIDI
CC7).

Example
on init
declare $vol_amount
end on
EVENT COMMANDS 56

on note
$vol_amount := (($EVENT_VELOCITY - 1) * 12000/126) - 6000
change_vol ($EVENT_ID,$vol_amount,1)
end on
A simple dynamic expander: lightly played notes will be softer, harder played notes will be louder

See ALSO
change_tune()
change_pan()
fade_in()
fade_out()

8.7. delete_event_mark()
delete_event_mark(<ID-number>,<bit-mark>)
Delete an event mark, i.e. ungroup the specified event from an event group
<ID-number> The ID number of the event to be ungrouped
<bit-mark> Here you can enter one of 28 marks from $MARK_1 to $MARK_28, which is
assigned to the event.

See Also
set_event_mark()
by_marks()
$EVENT_ID
$ALL_EVENTS
$MARK_1 … $MARK_28

8.8. event_status()
event_status(<ID-number>)
Retrieve the status of a particular note event, or MIDI event in the multi script.

The note can either be active, then this function returns.

$EVENT_STATUS_NOTE_QUEUE (or $EVENT_STATUS_MIDI_QUEUE in the multi script)

or inactive, then the function returns

$EVENT_STATUS_INACTIVE

Remarks
event_status() can be used to find out if a note event is still "alive" or not.

Examples
on init
declare %key_id[128]
EVENT COMMANDS 57

end on

on note
if (event_status(%key_id[$EVENT_NOTE])= $EVENT_STATUS_NOTE_QUEUE)
fade_out(%key_id[$EVENT_NOTE],10000,1)
end if
%key_id[$EVENT_NOTE] := $EVENT_ID
end on
Limit the number of active note events to one per MIDI key

See Also
$EVENT_STATUS_INACTIVE
$EVENT_STATUS_NOTE_QUEUE
$EVENT_STATUS_MIDI_QUEUE
get_event_ids()

8.9. fade_in()
fade_in(<ID-number>,<fade-time>)
Perform a fade-in for a specific note event
<ID-number> The ID number of the note event to be faded in
<fade-time> The fade-in time in microseconds

Examples
on init
declare $note_1_id
declare $note_2_id
end on

on note
$note_1_id := play_note($EVENT_NOTE+12,$EVENT_VELOCITY,0,-1)
$note_2_id := play_note($EVENT_NOTE+19,$EVENT_VELOCITY,0,-1)
fade_in ($note_1_id,1000000)
fade_in ($note_2_id,5000000)
end on
Fading in the first two harmonics

or the "built-in" parameters of a note event:

$EVENT_PAR_VOLUME

$EVENT_PAR_PAN

$EVENT_PAR_TUNE

$EVENT_PAR_NOTE

$EVENT_PAR_VELOCITY

$EVENT_PAR_REL_VELOCITY

$EVENT_PAR_SOURCE

$EVENT_PAR_PLAY_POS

$EVENT_PAR_ZONE_ID (use with caution, see below)

Remarks
A note event always carries certain information like the note number, the played velocity, but also
volume, pan and tune. With set_event_par(), you can set either these parameters or use the
freely assignable parameters like $EVENT_PAR_0. This is especially useful when chaining scripts,
i.e. set an event parameter for an event in slot 1, then retrieve this information in slot 2 by using
get_event_par().

Examples
(see next page)
on note
message(get_event_par($EVENT_ID,$EVENT_PAR_NOTE))
end on
The same functionality as message($EVENT_NOTE)
on note
message(get_event_par($EVENT_ID,$EVENT_PAR_SOURCE))
end on
Check if the event comes from outside (-1) or if it was created in one of the five script slots (0-4)
on note
wait(1)
message(get_event_par($EVENT_ID,$EVENT_PAR_ZONE_ID))
end on
Note that in the above example, an event itself does not carry a zone ID (only a voice has zone IDs),
therefore you need to insert wait(1) in order to retrieve the zone ID.
EVENT COMMANDS 61

See Also
set_event_par()
ignore_event()
set_event_par_arr()
get_event_par_arr()

8.14. get_event_par_arr()
get_event_par_arr(<ID-number>,<parameter>,<index>)
Retrieve the value of a specified event parameter of a specific event
<ID-number> The ID number of the note event
<parameter> Can be either $EVENT_PAR_ALLOW_GROUP or $EVENT_PAR_CUSTOM
<index> When used with $EVENT_PAR_ALLOW_GROUP: the group indexWhen used
with $EVENT_PAR_CUSTOM: the index (0 to 15)

Remarks
• get_event_par_arr() is a special form (or to be more precise, it's the array variant) of
get_event_par(). It can be used to retrieve the group allow state of a specific event
(returning 1 if the specified group is allowed and 0 if it's disallowed). It can also be used to
retrieve a value when using more than the standard four event parameters when using
$EVENT_PAR_CUSTOM.

Examples
on init
declare $count
declare ui_label $label (2,4)
set_text ($label,"")
end on

on note
set_text($label,"")
$count := 0
while($count < $NUM_GROUPS)

if (get_event_par_arr($EVENT_ID,$EVENT_PAR_ALLOW_GROUP,$count) = 1)
add_text_line($label,"Group ID " & $count & " allowed")
else
add_text_line($label,"Group ID " & $count & " disallowed")
end if

inc($count)
end while
end on
A simple group monitor

See Also
set_event_par_arr()
get_event_par()
EVENT COMMANDS 62

$EVENT_PAR_ALLOW_GROUP
%GROUPS_AFFECTED
$EVENT_PAR_CUSTOM

8.15. ignore_event()
ignore_event(<ID-number>)
Ignore a note event in a note on or note off callback

Remarks
• If you ignore an event, any volume, tune or pan information is lost. You can however retrieve
this infomation with get_event_par(), see the two examples below.
• ignore_event() is a very "strong" command. Always check if you can get the same results
with the various change_xxx() commands without having to ignore the event.

Examples
on note
ignore_event($EVENT_ID)
wait (500000)
play_note($EVENT_NOTE,$EVENT_VELOCITY,0,-1)
end on
Delaying all notes by 0.5s. Not bad, but if you, for example insert a microtuner before this script, the
tuning information will be lost.
on init
declare $new_id
end on

on note
ignore_event($EVENT_ID)
wait (500000)
$new_id := play_note($EVENT_NOTE,$EVENT_VELOCITY,0,-1)

change_vol($new_id,get_event_par($EVENT_ID,$EVENT_PAR_VOLUME),1)
change_tune($new_id,get_event_par($EVENT_ID,$EVENT_PAR_TUNE),1)
change_pan($new_id,get_event_par($EVENT_ID,$EVENT_PAR_PAN),1)
end on
Better: the tuning (plus volume and pan to be precise) information is retrieved and applied to the played
note

See Also
ignore_controller
get_event_par()

8.16. set_event_mark()
set_event_mark(<ID-number>,<bit-mark>)
Assign the specified event to a specific event group
EVENT COMMANDS 63

set_event_mark(<ID-number>,<bit-mark>)
<ID-number> The ID number of the event to be grouped
<bit-mark> Here you can enter one of 28 marks from $MARK_1 to $MARK_28 which is
assigned to the event. You can also assign more than one mark to a single
event, either by typing the command or by using the + operator.

Remarks
When dealing with commands that deal with event IDs, you can group events by using
by_marks(<bit-mark>) instead of the individual ID, as the program needs to know that you
want to address marks and not IDs.

Examples
on init
declare $new_id
end on

on note

set_event_mark($EVENT_ID,$MARK_1)

$new_id := play_note($EVENT_NOTE + 12,120,0,-1)

set_event_mark($new_id,$MARK_1 + $MARK_2)

change_pan(by_marks($MARK_1),-1000,1) {both notes panned to left}

change_pan(by_marks($MARK_2), 2000,1) {new note panned to right}

end on
The played note belongs to group 1, the harmonized belongs to group 1 and group 2

See Also
by_marks()
delete_event_mark()
$EVENT_ID
$ALL_EVENTS
$MARK_1 … $MARK_28

8.17. set_event_par()
set_event_par(<ID-number>,<parameter>,<value>)
Assign a parameter to a specific event
<ID-number> The ID number of the event
EVENT COMMANDS 64

set_event_par(<ID-number>,<parameter>,<value>)
<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 note event:

$EVENT_PAR_VOLUME

$EVENT_PAR_PAN

$EVENT_PAR_TUNE

$EVENT_PAR_NOTE

$EVENT_PAR_VELOCITY

$EVENT_PAR_REL_VELOCITY
<value> The value of the event parameter

Remarks
• A note event always "carries" certain information like the note number, the played velocity, but
also volume, pan and tune. With set_event_par(), you can set either these parameters or
use the freely assignable parameters like $EVENT_PAR_0. This is especially useful when
chaining scripts, i.e. set an event parameter for an event in slot 1, then retrieve this information
in slot 2 by using get_event_par().
• If you need access to more than four custom parameters, use set_event_par_arr() with
$EVENT_PAR_CUSTOM

Examples
on note
set_event_par($EVENT_ID,$EVENT_PAR_NOTE,60)
end on
Setting all notes to middle C3, same as change_note($EVENT_ID,60)
on init
message("")
declare ui_switch $switch

declare ui_label $midiChan1 (1,1)

declare ui_label $midiChan2 (1,1)
declare ui_label $midiChan3 (1,1)
declare ui_label $midiChan4 (1,1)
declare ui_label $midiChan5 (1,1)
declare ui_label $midiChan6 (1,1)
declare ui_label $midiChan7 (1,1)
declare ui_label $midiChan8 (1,1)
declare ui_label $midiChan9 (1,1)
declare ui_label $midiChan10 (1,1)
declare ui_label $midiChan11 (1,1)
declare ui_label $midiChan12 (1,1)
EVENT COMMANDS 65

declare ui_label $midiChan13 (1,1)

declare ui_label $midiChan14 (1,1)
declare ui_label $midiChan15 (1,1)
declare ui_label $midiChan16 (1,1)

declare %midiChans[16]
%midiChans[0] := get_ui_id($midiChan1)
%midiChans[1] := get_ui_id($midiChan2)
%midiChans[2] := get_ui_id($midiChan3)
%midiChans[3] := get_ui_id($midiChan4)
%midiChans[4] := get_ui_id($midiChan5)
%midiChans[5] := get_ui_id($midiChan6)
%midiChans[6] := get_ui_id($midiChan7)
%midiChans[7] := get_ui_id($midiChan8)
%midiChans[8] := get_ui_id($midiChan9)
%midiChans[9] := get_ui_id($midiChan10)
%midiChans[10] := get_ui_id($midiChan11)
%midiChans[11] := get_ui_id($midiChan12)
%midiChans[12] := get_ui_id($midiChan13)
%midiChans[13] := get_ui_id($midiChan14)
%midiChans[14] := get_ui_id($midiChan15)
%midiChans[15] := get_ui_id($midiChan16)
end on

on release
if ($switch=1)
set_event_par($EVENT_ID, $EVENT_PAR_REL_VELOCITY, 127)
end if

set_control_par_str(%midiChans[$MIDI_CHANNEL],$CONTROL_PAR_TEXT,get_event_par($
EVENT_ID, $EVENT_PAR_REL_VELOCITY))
end on
Release velocity within an MPE context

See Also
get_event_par()
ignore_event()
set_event_par_arr()
get_event_par_arr()

8.18. set_event_par_arr()
set_event_par_arr(<ID-number>,<parameter>,<value>,<index>)
Assign an event parameter array to a specific event
<ID-number> The ID number of the note event
<parameter> Can either be $EVENT_PAR_ALLOW_GROUP or $EVENT_PAR_CUSTOM
<value> When used with $EVENT_PAR_ALLOW_GROUP: the allow state for the
group (1 or 0)

When used with $EVENT_PAR_CUSTOM: the value of the specified index

EVENT COMMANDS 66

set_event_par_arr(<ID-number>,<parameter>,<value>,<index>)
<index> When used with $EVENT_PAR_ALLOW_GROUP: the group index

When used with $EVENT_PAR_CUSTOM: the index (0 to 15)

Remarks
• set_event_par_arr() is a special form (or to be more precise, it's the array variant) of
set_event_par(). You can use it to set the group allow state of a specific event, or if you
need to access more than four event parameters.
• $EVENT_PAR_CUSTOM is a build-in array that holds 16 assignable event parameters.

Examples
on note
if (get_event_par_arr($EVENT_ID,$EVENT_PAR_ALLOW_GROUP,0) = 0)
set_event_par_arr($EVENT_ID,$EVENT_PAR_ALLOW_GROUP,1,0)
end if
end on
Making sure the first group is always played.
on init
declare const $CUSTOM_EVENT_PAR_4 := 4
end on

on note
set_event_par_arr...
($EVENT_ID,$EVENT_PAR_CUSTOM,$ENGINE_UPTIME,$CUSTOM_EVENT_PAR_4)
end on

on release
message(get_event_par_arr...
($EVENT_ID,$EVENT_PAR_CUSTOM,$CUSTOM_EVENT_PAR_4))
end on
Simple implementation of $EVENT_PAR_CUSTOM

See Also
allow_group()
disallow_group()
get_event_par_arr()
set_event_par()
$EVENT_PAR_ALLOW_GROUP
ARRAY COMMANDS 67

9. Array Commands
9.1. array_equal()
array_equal(<array-variable>,<array-variable>)
Checks the values of two arrays. True if all values are equal, false if not

Remarks
This command does not work with arrays of real numbers.

Examples
on init
declare %array_1[10]
declare %array_2[11]

if (array_equal(%array_1,%array_2))
message($ENGINE_UPTIME)
end if

end on
This script will produce an error message as the two arrays don't have the same size

With direction # 0, the array is sorted in descending order.

Examples
on init
declare $count
ARRAY COMMANDS 69

declare ui_table %array[128] (3,3,127)

while ($count < 128)

%array[$count] := $count
inc($count)
end while
declare ui_button $Invert

end on

on ui_control ($Invert)
sort(%array,$Invert)
end on
Quickly inverting a linear curve display

See Also
array_equal()
num_elements()
sort()
GROUP COMMANDS 70

10. Group Commands

10.1. allow_group()
allow_group(<group-index>)
Allows the specified group, i.e. makes it available for playback

Remarks
• The numbering of the group index is zero-based, i.e. index of the first instrument group is 0.
• The groups can only be changed if the voice is not running.

Examples
on note
disallow_group($ALL_GROUPS)
allow_group(0)
end on
Only the first group will play back

See Also
$ALL_GROUPS
$EVENT_PAR_ALLOW_GROUP
disallow_group()
set_event_par_arr()

10.2. disallow_group()
disallow_group(<group-index>)
Disallows the specified group, i.e. makes it unavailable for playback

Remarks
• The numbering of the group index is zero-based, i.e. index of the first instrument group is 0.
• The groups can only be changed if the voice is not running.

Examples
on init
declare $count
declare ui_menu $groups_menu

add_menu_item ($groups_menu,"Play All",-1)

while ($count < $NUM_GROUPS)
add_menu_item ($groups_menu,"Mute: " & group_name($count),$count)
inc($count)
end while
end on
GROUP COMMANDS 71

on note
if ($groups_menu # -1)
disallow_group($groups_menu)
end if
end on
Muting one specific group of an instrument

See Also
$ALL_GROUPS
$EVENT_PAR_ALLOW_GROUP
allow_group()
set_event_par_arr()

10.3. find_group()
find_group(<group-name>)
Returns the group index for the specified group name

Remarks
If no group with the specified name is found, this command will return a value of zero. This can
cause problems as this is the group index of the first group, so be careful when using this
command.

Examples
on note
disallow_group(find_group("Accordion"))
end on
A simple, yet useful script

See Also
allow_group()
disallow_group
group_name()

10.4. get_purge_state()
get_purge_state(<group-index>)
Returns the purge state of the specified group:

0: The group is purged.

1: The group is not purged, i.e. the samples are loaded.

<group-index> The index number of the group that should be checked.
GROUP COMMANDS 72

Examples
on init
declare ui_button $purge
declare ui_button $checkpurge
set_text ($purge,"Purge 1st Group")
set_text ($checkpurge,"Check purge status")
end on

on ui_control ($purge)
purge_group(0,abs($purge-1))
end on

on ui_control ($checkpurge)
if (get_purge_state(0) = 0)
message(“Group is purged.”)
else
message(“Group is not purged.”)
end if
end on
A simple purge check

If set to 1, the samples are reloaded.

Remarks
• When using purge_group() in a while loop, don’t use any wait commands within the loop.
• purge_group() can only be used a UI and persistence_changed callback.
• It is recommended to not use the purge_group() command in the callback of an
automatable control.
• It is now possible to supply an async ID to the purge_group() function and get a return in
the async_complete callback.

Examples
on init
declare ui_button $purge
set_text ($purge,"Purge 1st Group")
end on

on ui_control ($purge)
purge_group(0,abs($purge-1))
end on

on async_complete
if (get_purge_state(0) = 0)
message("Group is purged")
else
GROUP COMMANDS 74

message("Group is not purged")

end if
end on
Unloading all samples of the first group

See Also
get_purge_state
TIME-RELATED COMMANDS 75

11. Time-Related Commands

11.1. change_listener_par()
change_listener_par(<signal-type>,<parameter>)
Changes the parameters of the on listener callback. It can be used in every callback.
<signal-type> The signal to be changed, can be either:
$NI_SIGNAL_TIMER_MS

$NI_SIGNAL_TIMER_BEAT
<parameter> Dependent on the specified signal type:
$NI_SIGNAL_TIMER_MS

Time interval in microseconds

$NI_SIGNAL_TIMER_BEAT

Time interval in fractions of a beat/quarter note

Examples
on init

declare ui_value_edit $Tempo (20,300,1)

$Tempo := 120

declare ui_switch $Play

set_listener($NI_SIGNAL_TIMER_MS,60000000 / $Tempo)

end on

on listener
if ($NI_SIGNAL_TYPE = $NI_SIGNAL_TIMER_MS and $Play = 1)
play_note(60,127,0,$DURATION_EIGHTH)
end if
end on

on ui_control($Tempo)
change_listener_par($NI_SIGNAL_TIMER_MS,60000000 / $Tempo)
end on
A very basic metronome

See Also
on listener
set_listener()
$NI_SIGNAL_TYPE
TIME-RELATED COMMANDS 76

11.2. ms_to_ticks()
ms_to_ticks(<microseconds>)
Converts a microseconds value into a tempo-dependent ticks value

Examples
on init
declare ui_label $bpm(1,1)
set_text($bpm,ms_to_ticks(60000000)/960)
end on
Displaying the current host tempo

See Also
ticks_to_ms()
$NI_SONG_POSITION

11.3. set_listener()
set_listener(<signal-type>,<parameter>)
Sets the signals on which the listener callback should react to. Can only be used in the init
callback.
<signal-type> The event on which the listener callback should react. The following
types are available:
$NI_SIGNAL_TRANSP_STOP

$NI_SIGNAL_TRANSP_START

$NI_SIGNAL_TIMER_MS

$NI_SIGNAL_TIMER_BEAT
<parameter> User defined parameter, dependant on the specified signal type:
$NI_SIGNAL_TIMER_MS

Time interval in microseconds

$NI_SIGNAL_TIMER_BEAT

Time interval in fractions of a beat/quarter note

$NI_SIGNAL_TRANSP_START

Set to 1 if the listener callback should react to the host's transport start
command
$NI_SIGNAL_TRANSP_STOP

Set to 1 if the listener callback should react to the host's transport stop
command
TIME-RELATED COMMANDS 77

Remarks
When using $NI_SIGNAL_TIMER_BEAT, the maximum resolution is 24 ticks per beat/quarter
note.

Examples
on init
set_listener($NI_SIGNAL_TIMER_BEAT,1)
end on
on listener
if ($NI_SIGNAL_TYPE = $NI_SIGNAL_TIMER_BEAT)
message($ENGINE_UPTIME)
end if
end on
Triggering the listener callback every beat. Triggering will occur even when transport is stopped.

See Also
change_listener_par()
$NI_SIGNAL_TYPE

11.4. stop_wait()
stop_wait(<callback-ID>,<parameter>)
Stops wait commands in the specified callback
<callback-ID> The callback’s ID number in which the wait commands will be stopped
<parameter> 0: stops only the current wait

1: stops the current wait and ignores all following wait commands in this
callback.

Remarks
• Be careful with while loops when stopping all wait commands in a callback.

Examples
on init
declare ui_button $Play
declare $id
end on
on ui_control ($Play)
if ($Play = 1)
$id := $NI_CALLBACK_ID
play_note(60,127,0,$DURATION_QUARTER)

wait($DURATION_QUARTER)
if ($Play = 1)
play_note(64,127,0,$DURATION_QUARTER)
end if

wait($DURATION_QUARTER)
if ($Play = 1)
play_note(67,127,0,$DURATION_QUARTER)
TIME-RELATED COMMANDS 78

end if
else
stop_wait($id,1)
fade_out($ALL_EVENTS,10000,1)
end if
end on
The Play button triggers a simple triad arpeggio. Without the stop_wait() command, parallel callbacks
could occur when pressing the Play button quickly in succession resulting in multiple arpeggios.

See Also
wait()
wait_ticks()
Callback Type Variables and Constants (Built-in variables/Specific)

11.5. reset_ksp_timer
reset_ksp_timer
Resets the KSP timer ($KSP_TIMER) to zero

Remarks
• Note that the $KSP_TIMER variable, due to its 32-bit signed nature, will reach its limit after
2147483648 microseconds, or roughly 35 minutes and 47 seconds.
• Since the KSP timer is based on the CPU clock, the main reason to use it is for debugging and
optimization. It is a great tool to measure the efficiency of certain script passages. However, it
should not be used for ‘musical’ timing, as it remains at a real-time constant rate, even if
KONTAKT is being used in an offline bounce.

Examples
on init
declare $a
declare $b
declare $c
end on

on note
reset_ksp_timer
$c := 0
while($c < 128)
$a := 0
while($a < 128)
set_event_par($EVENT_ID,$EVENT_PAR_TUNE,random(-1000,1000))
inc($a)
end while
inc($c)
end while
message($KSP_TIMER)
end on
A nested while loop – takes about 5400 to 5800 microseconds
TIME-RELATED COMMANDS 79

Example performing a single operation

wait_async(set_engine_par($ENGINE_PAR_EFFECT_TYPE, ... $EFFECT_TYPE_CHORUS,
-1, 2, 1))

Example performing multiple operations

%asyncid[0] := async_operation
%asyncid[1] := another_async_operation
...
%asyncid[x] := last_async_operation

$i := 0
while($i < num_elements(%asyncid))
wait_async(%asyncid[$i])
inc($i)
end while

See also
$NI_ASYNC_EXIT_STATUS
$NI_ASYNC_ID
TIME-RELATED COMMANDS 81

11.9. wait_ticks()
wait_ticks(<wait-time>)
Pauses the callback for the specified time in ticks

Remarks
Same as wait(), but with ticks as the wait time parameter.

See Also
stop_wait()
wait()
USER INTERFACE COMMANDS 82

12. User Interface Commands

12.1. add_menu_item()
add_menu_item(<variable>,<text>,<value>)
Create a menu entry
<variable> The variable name of the menu UI control
<text> The text of the menu entry
<value> The value of the menu entry

Remarks
• You can create menu entries only in the init callback but you can change their text and value
afterwards by using set_menu_item_str() and set_menu_item_value(). You can add
as many menu entries as you want and then show or hide them dynamically by using
set_menu_item_visibility().
• Using the $CONTROL_PAR_VALUE constant in the get_control_par() command will
return the menu index and not the value. If you want to get the menu value, use the
get_menu_item_value() command.

Examples
on init
declare ui_menu $menu
add_menu_item ($menu, "First Entry",0)
add_menu_item ($menu, "Second Entry",1)
add_menu_item ($menu, "Third Entry",2)
end on
A simple menu

See Also
$CONTROL_PAR_SELECTED_ITEM_IDX
$CONTROL_PAR_NUM_ITEMS
get_menu_item_str()
get_menu_item_value()
get_menu_item_visibility()
set_menu_item_str()
set_menu_item_visibility()
ui_menu

12.2. add_text_line()
add_text_line(<variable>,<text>)
Add a new text line in the specified label without erasing existing text
USER INTERFACE COMMANDS 83

add_text_line(<variable>,<text>)
<variable> The variable name of the label UI control
<text> The text to be displayed

Examples
on init
declare ui_label $label (1,4)
set_text($label,"")
declare $count
end on

on note
inc($count)
select ($count)
case 1
set_text($label, $count & ": " & $EVENT_NOTE)
case 2 to 4
add_text_line($label, $count & ": " & $EVENT_NOTE)
end select
if ($count = 4)
$count := 0
end if
end on
Monitoring the last four played notes

1: Returns the filename with extension.

2: Returns the whole path.

declare ui_button $visibility

declare ui_button $value
end on

on ui_control ($visibility)
set_menu_item_visibility (get_ui_id($menu),$visibility))
end on

on ui_control ($value)
message (get_menu_item_visibility (get_ui_id($menu),1))
end on
Clicking on Visibility button shows or hides the second menu entry, while clicking on Value button shows
the visibility state of that same menu entry.

See Also
$CONTROL_PAR_SELECTED_ITEM_IDX
$CONTROL_PAR_NUM_ITEMS
add_menu_item()
get_menu_item_str()
get_menu_item_value()
set_menu_item_str()
set_menu_item_value()
set_menu_item_visibility()

12.12. get_ui_id()
get_ui_id(<variable>)
Retrieve the ID number of a UI control

Examples
on init
declare ui_knob $Knob_1 (0,100,1)
declare ui_knob $Knob_2 (0,100,1)
declare ui_knob $Knob_3 (0,100,1)
declare ui_knob $Knob_4 (0,100,1)

declare ui_value_edit $Set(0,100,1)

USER INTERFACE COMMANDS 90

declare $a
declare %knob_id[4]
%knob_id[0] := get_ui_id ($Knob_1)
%knob_id[1] := get_ui_id ($Knob_2)
%knob_id[2] := get_ui_id ($Knob_3)
%knob_id[3] := get_ui_id ($Knob_4)

end on

on ui_control ($Set)
$a := 0
while ($a < 4)
set_control_par(%knob_id[$a],$CONTROL_PAR_VALUE,$Set)
inc($a)
end while
end on
Store IDs in an array

See Also
set_control_par()
get_control_par()

12.13. get_ui_wf_property()
get_ui_wf_property(<variable>,<property>,<index>)
Returns the value of the waveform’s different properties
<variable> The variable of the waveform UI control
<property> The following properties are available:
$UI_WF_PROP_PLAY_CURSOR

$UI_WF_PROP_FLAGS

$UI_WF_PROP_TABLE_VAL

$UI_WF_PROP_TABLE_IDX_HIGHLIGHT

$UI_WF_PROP_MIDI_DRAG_START_NOTE
<index> The index of the slice

Examples
on init
declare $play_pos
declare ui_waveform $Waveform(6,6)
attach_zone ($Waveform,find_zone ("Test"),0)
end on

on note
while ($NOTE_HELD = 1)
$play_pos := get_event_par($EVENT_ID,$EVENT_PAR_PLAY_POS)
set_ui_wf_property($Waveform,$UI_WF_PROP_PLAY_CURSOR,...
0,$play_pos)
message(get_ui_wf_property($Waveform,...
$UI_WF_PROP_PLAY_CURSOR,0))
USER INTERFACE COMMANDS 91

wait (10000)
end while
end on
Displays the current play position value

See Also
set_ui_wf_property()
ui_waveform()
attach_zone()
find_zone()
Waveform Flag Constants
Waveform Property Constants

12.14. hide_part()
hide_part(<variable>,<hide-mask>)
Hide specific parts of user interface controls
<variable> The variable name of the UI control
<hide-mask> Bitmask of visibility states for various parts of UI controls, consisting of the
following constants:

$HIDE_PART_BG (background of knobs, labels, value edits and tables)

$HIDE_PART_VALUE (value of knobs and tables)

$HIDE_PART_TITLE (title of knobs)

$HIDE_PART_MOD_LIGHT (mod ring light of knobs)

Examples
on init
declare ui_knob $Knob (0,100,1)

hide_part($Knob,$HIDE_PART_BG...
.or. $HIDE_PART_MOD_LIGHT...
.or. $HIDE_PART_TITLE...
.or. $HIDE_PART_VALUE)

end on
A naked knob
on init
declare ui_label $label_1 (1,1)
set_text ($label_1,"Small Label")
hide_part ($label_1,$HIDE_PART_BG)
end on
Hide the background of a label. This is also possible with other UI elements.

See Also
$CONTROL_PAR_HIDE
USER INTERFACE COMMANDS 92

$HIDE_PART_NOTHING
$HIDE_WHOLE_CONTROL

12.15. load_performance_view()
load_performance_view(<filename>)
Loads a performance view file (NCKP) that was created in the Creator Tools GUI Designer
<filename> The filename of the NCKP file, without extension, as a string (in
quotation marks)

Remarks
• Only one performance view file can be loaded per script slot
• This command is only available in the init callback
• This command cannot be used alongside make_perfview()
• The performance view file should be in the performance_view subfolder of the resource
container
• All contained controls are then accessible as if they were declared and set up in KSP; variable
names can be identified in Creator Tools
• More information in the Creator Tools documentation

Examples
on init
load_performance_view(“performanceView”)
end on

on ui_control ($testButton)
if ($testButton = 0)
set_control_par(get_ui_id($testSlider), $CONTROL_PAR_HIDE,
$HIDE_PART_WHOLE_CONTROL)
else
set_control_par(get_ui_id($testSlider), $CONTROL_PAR_HIDE,
$HIDE_PART_NOTHING)
end if
end on
Loads a performance view file and then defines some basic behavior involving two of the contained
controls

12.16. make_perfview
make_perfview
Activates the performance view for the respective script

Remarks
• make_perfview is only available in the init callback.
• Cannot be used alongside the load_performance_view() command.
USER INTERFACE COMMANDS 93

Examples
on init
make_perfview
set_script_title("Performance View")
set_ui_height(6)
message("")
end on
Many performance view scripts start like this

See Also
set_skin_offset()
set_ui_height()
set_ui_height_px()
set_ui_width_px()
set_ui_color()

12.17. move_control()
move_control(<variable>,<x-position>,<y-position>)
Position UI elements in the standard KONTAKT grid
<variable> The variable name of the UI control
<x-position> The horizontal position of the control (0 to 6) in grid units
<y-position> The vertical position of the control (0 to 16) in grid units

Remarks
• move_control() can be used in the init and other callbacks.
• Note that the usage of move_control() in other callbacks than the init callback is more
CPU intensive, so handle with care.
• move_control(<variable>,0,0) will hide the UI element.

Examples
on init
set_ui_height(3)
declare ui_label $label (1,1)
set_text ($label,"Move the wheel!")
move_control ($label,3,6)
end on
on controller
if ($CC_NUM = 1)
move_control ($label,3,(%CC[1] * (-5) / (127)) + 6 )
end if
end on
Move a UI element with the modwheel

See Also
move_control_px()
USER INTERFACE COMMANDS 94

$CONTROL_PAR_HIDE

12.18. move_control_px()
move_control_px(<variable>,<x-position>,<y-position>)
Position UI elements in pixels
<variable> The variable name of the UI control
<x-position> The horizontal position of the control in pixels
<y-position> The vertical position of the control in pixels

Remarks
• Once you position a control in pixel, you have to make all other adjustments in pixels too, i.e.
you cannot change between "pixel" and "grid" mode for a specific control.
• move_control_px() can be used in the init and other callbacks.
• Note that the usage of move_control_px() in other callbacks than the init callback is more
CPU intensive, so handle with care.
• In order to match grid size to pixel position, the following formulas can be used:
• X position: ((grid_value - 1) * 92) + 66
• Y position: ((grid_value - 1) * 21) + 2
• Width (to be used with $CONTROL_PAR_WIDTH): (grid_value * 92) - 5
• Height (to be used with $CONTROL_PAR_HEIGHT): (grid_value * 21) - 3

Examples
on init
declare ui_label $label (1,1)
set_text ($label,"Move the wheel!")
move_control_px ($label,66,2)
end on
on controller
if ($CC_NUM = 1)
move_control_px ($label,%CC[1]+66,2)
end if
end on
Transform CC values into pixel position. This might be useful for reference.

See Also
move_control()
$CONTROL_PAR_POS_X
$CONTROL_PAR_POS_Y
USER INTERFACE COMMANDS 95

12.19. set_control_help()
set_control_help(<variable>,<text>)
Assigns a text string to be displayed when hovering the UI control. The text will appear in
KONTAKT's info pane.
<variable> The variable name of the UI control
<text> The info text to be displayed

Remarks
The text string used can contain a maximum of 320 characters.

Examples
on init
declare ui_knob $Knob(0,100,1)
set_control_help($Knob,"I'm the only knob, folks")
end on
set_control_help() in action

See Also
set_script_title()
$CONTROL_PAR_HELP

12.20. set_control_par()
set_control_par(<ui-ID>,<control-parameter>,<value>)
Change various parameters of the specified UI control
<ui-ID> The ID number of the UI control. You can retrieve the ID number
with get_ui_id()
<control-parameter> Parameter of the UI control we wish to retrieve, i.e.
$CONTROL_PAR_WIDTH
<value> The (integer) value

Remarks
set_control_par_str() is a variation of the command for usage with text strings.

Examples
on init
declare ui_value_edit $test (0,100,$VALUE_EDIT_MODE_NOTE_NAMES)
set_text ($test,"")
set_control_par (get_ui_id($test),$CONTROL_PAR_WIDTH,45)
move_control_px($test,100,10)
end on
Changing the width of a value edit to 45 pixels. Note that you also have to specify its position in pixels
once you enter "pixel-mode".
on init
declare ui_label $test (1,1)
USER INTERFACE COMMANDS 96

set_control_par_str(get_ui_id($test),$CONTROL_PAR_TEXT,"This is Text")
set_control_par(get_ui_id($test),$CONTROL_PAR_TEXT_ALIGNMENT,1)
end on
Set and center text in labels

declare ui_xy ?myXY[4]

declare $xyID
$xyID := get_ui_id(?myXY)

set_control_par_str_arr($xyID, $CONTROL_PAR_AUTOMATION_NAME, ...

See Also
$CONTROL_PAR_CURSOR_PICTURE
$CONTROL_PAR_AUTOMATION_ID
$CONTROL_PAR_AUTOMATION_NAME
$HIDE_PART_CURSOR

12.22. set_knob_defval()
set_knob_defval(<variable>,<value>)
Assign a default value to a knob to which the knob is reset when Cmd-clicking (Mac) or Ctrl-
clicking (PC) the knob.

Remarks
In order to assign a default value to a slider, use
set_control_par(<ui-ID>,$CONTROL_PAR_DEFAULT_VALUE,<value>)

Examples
on init
declare ui_knob $Knob(-100,100,0)
set_knob_defval ($Knob,0)
$Knob := 0

declare ui_slider $Slider (-100,100)

set_control_par(get_ui_id($Slider),$CONTROL_PAR_DEFAULT_VALUE,0)
$Slider := 0
end on
Assigning default values to a knob and slider

declare ui_knob $Rate (0,17,1)

set_knob_label($Rate,!rate_names[$Rate])

read_persistent_var($Rate)
set_knob_label($Rate,!rate_names[$Rate])
end on

on ui_control ($Rate)
set_knob_label($Rate,!rate_names[$Rate])
end on
Useful for displaying rhythmical values

The following constants are available:

$KNOB_UNIT_NONE

$KNOB_UNIT_DB

$KNOB_UNIT_HZ

$KNOB_UNIT_PERCENT

$KNOB_UNIT_MS

$KNOB_UNIT_OCT

$KNOB_UNIT_ST

Examples
on init
declare ui_knob $Time (0,1000,10)
set_knob_unit ($Time,$KNOB_UNIT_MS)

declare ui_knob $Octave (1,6,1)

set_knob_unit ($Octave,$KNOB_UNIT_OCT)

declare ui_knob $Volume (-600,600,100)

USER INTERFACE COMMANDS 99

set_knob_unit ($Volume,$KNOB_UNIT_DB)

declare ui_knob $Scale (0,100,1)

set_knob_unit ($Scale,$KNOB_UNIT_PERCENT)

declare ui_knob $Tune (4300,4500,10)

set_knob_unit ($Tune,$KNOB_UNIT_HZ)
end on
Various knob unit marks

declare ui_value_edit $Steps (8,32,1)

$Steps := 16
set_table_steps_shown(%table,$Steps)

end on

on ui_control($Steps)
set_table_steps_shown(%table,$Steps)
end on
Changing the number of shown steps

declare ui_label $label_2 (3,6)

See Also
add_text_line()
$CONTROL_PAR_TEXT
set_control_par_str()
USER INTERFACE COMMANDS 104

12.32. set_ui_color()
set_ui_color(<hex value>)
Set the main background color of the performance view
<hex value> The hexadecimal color value in the following format:
9ff0000h {red}

The 9 at the start lets KONTAKT know the value is a number.

The h at the end indicates that it is a hexadecimal value.

Remarks
Can be used in all callbacks.

Examples
on init
make_perfview
set_ui_color(9000000h)
end on
Creates a black interface

See Also
set_ui_height()
set_ui_height_px()

12.33. set_ui_height()
set_ui_height(<height>)
Set the height of a script performance view in grid units
<height> The height of script in grid units (1 to 8)

Remarks
Only possible in the init callback.

Examples
on init
make_perfview
set_script_title("Performance View")
set_ui_height(6)
message("")
end on
Many performance view scripts start like this

See Also
set_ui_height_px()
USER INTERFACE COMMANDS 105

12.34. set_ui_height_px()
set_ui_height_px(<height>)
Set the height of a script performance view in pixels
<height> The height of script in pixels (50 to 750)

Remarks
Only possible in the init callback.

Examples
on init
make_perfview
declare const $SIZE := 1644 {size of tga file}
declare const $NUM_SLIDES := 4 {amount of slides in tga file}

declare ui_value_edit $Slide (1,$NUM_SLIDES,1)

declare const $HEADER_SIZE := 93

set_ui_height_px(($SIZE/$NUM_SLIDES)-$HEADER_SIZE)
set_skin_offset (($Slide-1)*($SIZE/$NUM_SLIDES))

end on

on ui_control ($Slide)
set_skin_offset (($Slide-1)*($SIZE/$NUM_SLIDES))
end on

See Also
set_ui_height()
set_ui_width_px()

12.35. set_ui_width_px()
set_ui_width_px(<width>)
Set the width of a script performance view in pixels
<width> The width of the script in pixels (633 to 1000)

Remarks
Only possible in the init callback.

Examples
on init
make_perfview
set_ui_height_px(750)
set_ui_width_px(1000)
end on
Making a performance view with the largest possible dimensions
USER INTERFACE COMMANDS 106

13. Keyboard Commands

13.1. get_key_color()
get_key_color(<note-nr>)
Returns the color constant of the specified note number

Examples
on init
message("")
declare $count
while ($count < 128)
set_key_color($count,$KEY_COLOR_INACTIVE)
inc($count)
end while

declare $random_key
$random_key := random(60,71)

set_key_color($random_key,$KEY_COLOR_RED)

end on

on note
if (get_key_color($EVENT_NOTE) = $KEY_COLOR_RED)
message("Bravo!")

set_key_color($random_key,$KEY_COLOR_INACTIVE)
$random_key := random(60,71)
set_key_color($random_key,$KEY_COLOR_RED)
else
message("Try again!")
end if
end on

on release
message("")
end on
Catch me if you can

The following colors are available:

$KEY_COLOR_RED

$KEY_COLOR_ORANGE

$KEY_COLOR_LIGHT_ORANGE

$KEY_COLOR_WARM_YELLOW

$KEY_COLOR_YELLOW

$KEY_COLOR_LIME

$KEY_COLOR_GREEN

$KEY_COLOR_MINT

$KEY_COLOR_CYAN

$KEY_COLOR_TURQUOISE

$KEY_COLOR_BLUE

$KEY_COLOR_PLUM

$KEY_COLOR_VIOLET

$KEY_COLOR_PURPLE

$KEY_COLOR_MAGENTA

$KEY_COLOR_FUCHSIA

$KEY_COLOR_DEFAULT sets the key to KONTAKT's standard color for mapped notes

$KEY_COLOR_INACTIVE resets the key to standard black and white

$KEY_COLOR_NONE resets the key to its normal KONTAKT color, e.g. red for internal
keyswitches

Remarks
The keyboard colors reside outside of KSP, i.e. changing the color of a key is similar to changing a
KONTAKT knob with set_engine_par(). It is therefore a good practice to set all keys to either
$KEY_COLOR_INACTIVE or $KEY_COLOR_NONE in the init callback or whenever changed later.

Example
(see next page)
on init
message("")
declare ui_button $Color

declare $count
KEYBOARD COMMANDS 112

declare $note_count
declare $color_count
declare %white_keys[7] := (0,2,4,5,7,9,11)
declare %colors[16] := (...
$KEY_COLOR_RED,$KEY_COLOR_ORANGE,$KEY_COLOR_LIGHT_ORANGE,...
$KEY_COLOR_WARM_YELLOW,$KEY_COLOR_YELLOW,$KEY_COLOR_LIME,...
$KEY_COLOR_GREEN,$KEY_COLOR_MINT,$KEY_COLOR_CYAN,...
$KEY_COLOR_TURQUOISE,$KEY_COLOR_BLUE,$KEY_COLOR_PLUM,...
$KEY_COLOR_VIOLET,$KEY_COLOR_PURPLE,$KEY_COLOR_MAGENTA,$KEY_COLOR_FUCHSIA)

$count := 0
while ($count < 128)
set_key_color($count,$KEY_COLOR_NONE)
inc($count)
end while
end on

on ui_control ($Color)
if ($Color = 1)

$count := 0
while ($count < 128)
set_key_color($count,$KEY_COLOR_INACTIVE)
inc($count)
end while

$note_count := 0
$color_count := 0
while ($color_count < 16)

if (search(%white_keys,(60 + $note_count) mod 12) # -1)

set_key_color(60 + $note_count,%colors[$color_count])
inc ($color_count)
end if

inc($note_count)

end while

else

$count := 0
while ($count < 128)
set_key_color($count,$KEY_COLOR_NONE)
inc($count)
end while

end if

end on
KONTAKT rainbow

See Also
set_control_help()
get_key_color()
set_key_name()
set_keyrange()
KEYBOARD COMMANDS 113

13.9. set_key_name()
set_key_name(<note-nr>,<name>)
Assigns a text string to the specified key

Remarks
Key names are instrument parameters and reside outside KSP, i.e. changing the key name is
similar to changing a KONTAKT knob with set_engine_par(). Make sure to always reset all key
names in the init callback or whenever changed later.
Key names and ranges are displayed in KONTAKT's info pane when hovering the mouse over the
key on the KONTAKT keyboard.

Examples
on init

declare $count
while ($count < 128)
set_key_name($count,"")
inc($count)
end while

set_key_name(60,"Middle C")

end on

1: KONTAKT's keyboard is only affected by set_key_pressed()commands.

Remarks
The pressed state mode resides outside KSP, i.e. changing the mode is similar to changing a
KONTAKT knob with set_engine_par(). Make sure to always set the desired mode in the init
callback.

Examples
on init
declare ui_button $Enable
set_key_pressed_support(0)
end on

on ui_control ($Enable)
set_key_pressed_support($Enable)
end on

on note
play_note($EVENT_NOTE+4,$EVENT_VELOCITY,0,-1)
play_note($EVENT_NOTE+7,$EVENT_VELOCITY,0,-1)
set_key_pressed($EVENT_NOTE,1)
set_key_pressed($EVENT_NOTE+4,1)
set_key_pressed($EVENT_NOTE+7,1)
end on

on release
set_key_pressed($EVENT_NOTE,0)
set_key_pressed($EVENT_NOTE+4,0)
set_key_pressed($EVENT_NOTE+7,0)
end on
Press the button and you will see what you hear

See Also
set_key_pressed()
KEYBOARD COMMANDS 115

get_key_triggerstate()

13.12. set_key_type()
set_key_type(<note-nr>,<key-type-constant>)
Assigns a key type to the specified key.

The following key types are available:

$NI_KEY_TYPE_DEFAULT i.e. normal mapped notes that produce sound.

$NI_KEY_TYPE_CONTROL i.e. key switches or other notes that do not produce sound.

$NI_KEY_TYPE_NONE resets the key to its normal KONTAKT behaviour.

Remarks
Setting the key type is useful for supported hosts like KOMPLETE KONTROL, where keys with
control functionality, e.g. key switches, should not be affected by any note processing.

Examples
on init

declare $count

$count := 0
while ($count < 128)
set_key_type($count,$NI_KEY_TYPE_NONE)
inc($count)
end while

$count := 36
while ($count <= 96)

select ($count)

case 36 to 47 {e.g. key switch}

set_key_type($count,$NI_KEY_TYPE_CONTROL)

case 48 to 96 {e.g. main notes}

set_key_type($count,$NI_KEY_TYPE_DEFAULT)

end select

inc($count)
end while
end on

See Also
get_key_type()
KEYBOARD COMMANDS 116

13.13. set_keyrange()
set_keyrange(<min-note>,<max-note>,<name>)
Assigns a text string to the specified range of keys

Remarks
Key ranges are instrument parameters and reside outside KSP, i.e. changing the key range is
similar to changing a KONTAKT knob with set_engine_par(). Make sure to always remove all
key ranges in the init callback or whenever changed later.
There can be up to 16 key ranges per instrument.
Key names and ranges are displayed in KONTAKT's info pane when hovering the mouse over the
key on the KONTAKT keyboard. The range name is followed by the key name, separated by a dash.

Examples
on init

declare $count
while ($count < 128)

remove_keyrange($count)
inc($count)
end while

set_keyrange(36,72,"Middle Range")

end on

See Also
remove_keyrange()
set_key_name()

13.14. remove_keyrange()
remove_keyrange(<note-nr>)
Assigns a text string to the specified range of keys

Examples
on init

declare $count
while ($count < 128)
KEYBOARD COMMANDS 117

remove_keyrange($count)
inc($count)
end while

set_keyrange(36,72,"Middle Range")

end on

See Also
set_keyrange()
ENGINE PARAMETER COMMANDS 118

14. Engine Parameter Commands

14.1. find_mod()
find_mod(<group-index>,<mod-name>)
Returns the slot index of an internal modulator or external modulation slot
<group-index> The index of the group
<mod-name> The name of the modulator or modulation slot.

Each modulator or modulation slot has a predefined name, based on the

modulation source and target.

The name can be changed with the script editor's edit area open and
right-clicking on the modulator or modulation slot.

Examples
on init
declare $grp_idx
$grp_idx := 0

declare $env_idx
$env_idx := find_mod(0,"VOL_ENV")

declare ui_knob $Attack (0,1000000,1)

set_knob_unit($Attack,$KNOB_UNIT_MS)

$Attack := get_engine_par($ENGINE_PAR_ATTACK,$grp_idx,$env_idx,-1)

set_knob_label($Attack,get_engine_par_disp...
($ENGINE_PAR_ATTACK,$grp_idx,$env_idx,-1))

end on
on ui_control ($Attack)

set_engine_par($ENGINE_PAR_ATTACK,$Attack,$grp_idx,$env_idx,-1)

set_knob_label($Attack,get_engine_par_disp...
($ENGINE_PAR_ATTACK,$grp_idx,$env_idx,-1))

end on
Controlling the attack time of the volume envelope of the first group. Note: the envelope has been
manually renamed to "VOL_ENV"
on init

declare $count
declare ui_slider $test (0,1000000)
$test := get_engine_par($ENGINE_PAR_MOD_TARGET_INTENSITY,0,...
find_mod(0,"VEL_VOLUME"),-1)

end on

on ui_control ($test)
ENGINE PARAMETER COMMANDS 119

$count := 0
while($count < $NUM_GROUPS)
set_engine_par($ENGINE_PAR_MOD_TARGET_INTENSITY,$test,$count,...
find_mod($count,"VEL_VOLUME"),-1)
inc($count)
end while

end on
Creating a slider which controls the velocity to volume modulation intensity of all groups

Each modulation slot has a predefined name, based on the modulation

source and target.

The name can be changed with the script editor's edit area open and
right-clicking on the modulation slot.

Examples
on init
declare ui_knob $Knob (-100,100,1)
declare $mod_idx
$mod_idx := find_mod(0,"FILTER_ENV")

declare $target_idx
$target_idx := find_target(0,$mod_idx,"ENV_AHDSR_CUTOFF")
end on

on ui_control ($Knob)
if ($Knob < 0)
set_engine_par ($MOD_TARGET_INVERT_SOURCE,...
1,0,$mod_idx,$target_idx)
else
set_engine_par ($MOD_TARGET_INVERT_SOURCE,...
0,0,$mod_idx,$target_idx)
end if
set_engine_par($ENGINE_PAR_MOD_TARGET_INTENSITY,...
abs($Knob*10000),0,$mod_idx,$target_idx)
end on
Controlling the filter envelope amount of an envelope to filter cutoff modulation in the first group. Note:
the filter envelope has been manually renamed to "FILTER_ENV".
ENGINE PARAMETER COMMANDS 120

If the specified parameter resides on an Instrument level,

enter -1.
<slot> The slot index (zero-based) of the specified parameter. It
applies only to group/instrument effects, modulators and
modulation intensities.

For group/instrument effects, this parameter specifies the

slot in which the effect resides (zero-based).

For modulators and modulation intensities, this parameters

specifies the index which you can retrieve by using:
find_mod(<group-idx>,<mod-name>)

For all other applications, set this parameter to -1.

<generic> This parameter applies to instrument effects and to internal
modulators.

For instrument effects, this parameter distinguishes

between:

1: Insert Effect

0: Send Effect

For buses, this parameter specifies the actual bus:

$NI_BUS_OFFSET + [0-15] one of the 16 busses

For internal modulators, this parameter specifies the

modulation slider which you can retrieve by using:
find_target(<group-idx>,<mod-idx>,<target-
name>)

For all other applications, set this parameter to -1.

Examples
on init
declare $a
ENGINE PARAMETER COMMANDS 121

declare ui_label $label (2,6)

set_text ($label,"Release Trigger Groups:")

while ($a < $NUM_GROUPS)

if(get_engine_par($ENGINE_PAR_RELEASE_TRIGGER ,$a,-1,-1)=1)
add_text_line($label,group_name($a)&" (Index: "&$a&")")
end if
inc($a)
end while
end on
Output the name and index of release trigger group
on init
declare ui_label $label (2,6)

declare ui_button $Refresh

declare !effect_name[128]
!effect_name[$EFFECT_TYPE_NONE] := "None"
!effect_name[$EFFECT_TYPE_PHASER] := "Phaser"
!effect_name[$EFFECT_TYPE_CHORUS] := "Chorus"
!effect_name[$EFFECT_TYPE_FLANGER] := "Flanger"
!effect_name[$EFFECT_TYPE_REVERB] := "Reverb"
!effect_name[$EFFECT_TYPE_DELAY] := "Delay"
!effect_name[$EFFECT_TYPE_IRC] := "Convolution"
!effect_name[$EFFECT_TYPE_GAINER] := "Gainer"

declare $count
while ($count < 8)
add_text_line($label,"Slot: " & $count+1 & ": " & ...
!
effect_name[get_engine_par($ENGINE_PAR_SEND_EFFECT_TYPE,-1,$count,-1)])
inc($count)
end while

end on

on ui_control ($Refresh)
set_text($label,"")
$count := 0
while ($count < 8)
add_text_line($label,"Slot: " & $count+1 & ": " & ...
!
effect_name[get_engine_par($ENGINE_PAR_SEND_EFFECT_TYPE,-1,$count,-1)])
inc($count)
end while

$Refresh := 0
end on
Output the effect types of all eight send effect slots

See Also
Module Status Retrieval
ENGINE PARAMETER COMMANDS 122

14.4. get_engine_par_disp()
get_engine_par_disp(<parameter>,<group>,<slot>,<generic>)
Returns the displayed string of a specific engine parameter
<parameter> Specifies the engine parameter.
<group> The index (zero-based) of the group in which the specified
parameter resides.

If the specified parameter resides on an Instrument level,

enter -1.
<slot> The slot index (zero-based) of the specified parameter. It
applies only to group/instrument effects, modulators and
modulation intensities.

For group/instrument effects, this parameter specifies

the slot in which the effect resides (zero-based).

For modulators and modulation intensities, this

parameters specifies the index which you can retrieve by
using:
find_mod(<group-idx>,<mod-name>)

For all other applications, set this parameter to -1.

<generic> this parameter applies to instrument effects and to
internal modulators.

For instrument effects, this parameter distinguishes

between

1: Insert Effect

0: Send Effect

For buses, this parameter specifies the actual bus:

$NI_BUS_OFFSET + [0-15] one of the 16
busses

For internal modulators, this parameter specifies the

modulation slider which you can retrieve by using:
find_target(<group-idx>,<mod-idx>,<target-
name>)

For all other applications, set this parameter to -1

Examples
on init
declare $a

declare ui_label $label (2,6)

set_text ($label,"Group Volume Settings:")

while ($a < $NUM_GROUPS)

add_text_line($label,group_name($a) & ": " & ...
ENGINE PARAMETER COMMANDS 123

get_engine_par_disp($ENGINE_PAR_VOLUME,$a,-1,-1) & " dB")

inc($a)
end while
end on
Query the group volume settings in an instrument

14.5. get_voice_limit()
get_voice_limit(<voice-type>)
Returns the voice limit for the Time Machine Pro mode of the source module
<voice-type> The voice type, can be one of the following:
$NI_VL_TMPRO_STANDARD {Standard Mode}

$NI_VL_TMRPO_HQ {High Quality Mode}

Examples
on init
declare ui_label $label (3,2)

add_text_line($label,"Standard Voice Limit: " & ...

get_voice_limit($NI_VL_TMPRO_STANDARD))

add_text_line($label,"HQ Voice Limit: " & ...

get_voice_limit($NI_VL_TMPRO_HQ))

end on
Displaying TM Pro voice limits

The range of values is always 0 to 1000000, except for

switches in which case it is 0 or 1.
<group> The index (zero-based) of the group in which the
specified parameter resides.

If the specified parameter resides on an Instrument

level, enter -1.

Busses and Main FX also reside on Instrument level, so

you need to set <group> to -1 if you want to address a
bus.
<slot> The slot index (zero-based) of the specified parameter.
This applies only to group/instrument effects,
modulators and modulation intensities.

For group/instrument effects, this parameter specifies

the slot in which the effect resides (zero-based).

For modulators and modulation intensities, this

parameters specifies the index which you can retrieve
by using:
find_mod(<group-idx>,<mod-name>)

For all other applications, set this parameter to -1.

ENGINE PARAMETER COMMANDS 125

set_engine_par(<parameter>,<value>,<group>,<slot>,<generic>)
<generic> This parameter applies to instrument effects and to
internal modulators.

For instrument effects, this parameter distinguishes

between:

$NI_SEND_BUS: Send Effect

$NI_INSERT_BUS: Insert Effect

$NI_MAIN_BUS: Main Effect

For buses, this parameter specifies the actual bus:

$NI_BUS_OFFSET + [0-15] one of the 16
busses

For internal modulators, this parameter specifies the

modulation slider which you can retrieve by using:
find_target(<group-idx>,<mod-
idx>,<target-name>)

For all other applications, set this parameter to -1

Examples
on init
declare ui_knob $Volume (0,1000000,1000000)
end on
on ui_control ($Volume)
set_engine_par($ENGINE_PAR_VOLUME,$Volume,-1,-1,-1)
end on
Controlling instrument volume
on init
declare ui_knob $Freq (0,1000000,1000000)
declare ui_button $Bypass
end on

on ui_control ($Freq)
set_engine_par($ENGINE_PAR_CUTOFF,$Freq,0,0,-1)
end on

on ui_control ($Bypass)
set_engine_par($ENGINE_PAR_EFFECT_BYPASS,$Bypass,0,0,-1)
end on
Controlling the cutoff and bypass button of any filter module in the first slot of the first group
on init
declare ui_knob $Knob (-100,100,1)
declare $mod_idx
$mod_idx := find_mod(0,"FILTER_ENV")

declare $target_idx
$target_idx := find_target(0,$mod_idx,"ENV_AHDSR_CUTOFF")
end on

on ui_control ($Knob)
ENGINE PARAMETER COMMANDS 126

if ($Knob < 0)
set_engine_par ($MOD_TARGET_INVERT_SOURCE,...
1,0,$mod_idx,$target_idx)
else
set_engine_par ($MOD_TARGET_INVERT_SOURCE,...
0,0,$mod_idx,$target_idx)
end if
set_engine_par($ENGINE_PAR_MOD_TARGET_INTENSITY,...
abs($Knob*10000),0,$mod_idx,$target_idx)
end on
Controlling the filter envelope amount of an envelope to filter cutoff modulation in the first group. Note:
the the filter envelope has been manually renamed to "FILTER_ENV".
on init
declare ui_knob $Vol (0,1000000,1)
end on

on ui_control ($Vol)
set_engine_par($ENGINE_PAR_VOLUME,$Vol,-1,-1,$NI_BUS_OFFSET + 15)
end on
Controlling the amplifier volume of the 16th bus

14.8. set_voice_limit()
set_voice_limit(<voice-type>,<value>)
Sets the voice limit for the Time Machine Pro mode of the source module
<voice-type> The voice type, can be one of the following:
$NI_VL_TMPRO_STANDARD {Standard Mode}

$NI_VL_TMRPO_HQ {High Quality Mode}

<value> The voice limit of the Time Machine Pro mode

Remarks
• Changing voice limits is an asynchronous operation. This means, that one cannot reliably
access the newly allocated voices immediately after instantiation. To resolve this, the
set_voice_limit() command returns an $NI_ASYNC_ID and triggers the on
async_complete callback.

Examples
on init
declare ui_value_edit $Voices (1,8,1)
make_persistent($Voices)

declare $change_voices_id

end on

on ui_control ($Voices)
$change_voices_id := set_voice_limit($NI_VL_TMPRO_STANDARD,$Voices)
end on

on async_complete
if ($NI_ASYNC_ID = $change_voices_id)
ENGINE PARAMETER COMMANDS 127

message("New TMPro Std Voice Limit: " &

get_voice_limit($NI_VL_TMPRO_STANDARD))
end if
end on
Changing TM Pro voice limits

See Also
get_voice_limit()
ZONE COMMANDS 128

15. Zone Commands

15.1. General Information

User zones are a special kind of zone that allow for zone creation and manipulation “on the fly” and
can be used to allow user interaction with the sampled content within an instrument (for example
in conjunction with sample drag-and-drop). These zones must be declared via script in the on
init callback.
When a user zone is created the mapping is set to 0 on all zone parameters by default (root key,
high velocity, high note, low note etc…). Therefore, the zone will not show in the mapping editor’s
normal view (it will be listed and present in the list view).
Note that some of the functions listed below only work on user zones, while some also work on
every zone.

15.2. get_loop_par()
get_loop_par(<zone_id>,<loop-index>,<parameter>)
Returns the loop parameters of a zone
<zone_id> The ID of the zone
<loop-index> The index number of the loop
<parameter> The following parameters are available:
$LOOP_PAR_MODE

$LOOP_PAR_START

$LOOP_PAR_LENGTH

$LOOP_PAR_XFADE

$LOOP_PAR_COUNT

$LOOP_PAR_TUNING

Remarks
• get_loop_par() works on every loop from every zone
• This function runs synchronously

Examples
message(get_loop_par($myZoneId, 0, $LOOP_PAR_MODE))

15.3. get_sample()
get_sample(<zone-id>,<return-parameter>)
Returns paths, file names and extensions of samples.
ZONE COMMANDS 129

get_sample(<zone-id>,<return-parameter>)
<zone-id> The ID of the zone
<return-parameter> The following parameters are available:
$NI_FILE_NAME

$NI_FILE_FULL_PATH

$NI_FILE_FULL_PATH_OS

$NI_FILE_EXTENSION

Remarks
• get_sample() works on every zone
• This function runs synchronously

Examples
message(get_sample(%NI_USER_ZONE_IDS[0], $NI_FILE_NAME))

See Also
$NI_FILE_NAME
$NI_FILE_FULL_PATH
$NI_FILE_FULL_PATH_OS
$NI_FILE_EXTENSION

15.4. get_zone_par()
get_zone_par(<zone-id>,<parameter>)
Returns the zone parameters
<zone-id> The ID of the zone
ZONE COMMANDS 130

get_zone_par(<zone-id>,<parameter>)
<parameter> The following parameters are available:
$ZONE_PAR_HIGH_KEY

$ZONE_PAR_LOW_KEY

$ZONE_PAR_HIGH_VELO

$ZONE_PAR_LOW_VELO

$ZONE_PAR_ROOT_KEY

$ZONE_PAR_FADE_LOW_KEY

$ZONE_PAR_FADE_HIGH_KEY

$ZONE_PAR_FADE_LOW_VELO

$ZONE_PAR_FADE_HIGH_VELO

$ZONE_PAR_VOLUME

$ZONE_PAR_PAN

$ZONE_PAR_TUNE

$ZONE_PAR_GROUP

$ZONE_PAR_SAMPLE_START

$ZONE_PAR_SAMPLE_END

$ZONE_PAR_SAMPLE_MOD_RANGE

Remarks
• get_zone_par() works on every zone
• This function runs synchronously

Examples
get_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_PAN)

15.5. is_zone_empty()
is_zone_empty(<zone-ID>)
Returns 1 if a zone is empty (has no sample), otherwise returns 0
<zone-ID> The ID of the zone

Examples
message("Zone empty status: " & is_zone_empty(%NI_USER_ZONE_IDS[0]))
ZONE COMMANDS 131

15.6. set_loop_par()
set_loop_par(<zone-id>,<loop-index>,<parameter>,<value>
Sets the loop parameters of a user zone
<zone-id> The ID of the zone
<loop-index> The index number of the loop
<parameter> The following parameters are available:
$LOOP_PAR_MODE

$LOOP_PAR_START

$LOOP_PAR_LENGTH

$LOOP_PAR_XFADE

$LOOP_PAR_COUNT

$LOOP_PAR_TUNING
<value> The value of the loop parameter

Remarks
• set_loop_par() only works in user zone loops
• When executed in the init callback, this function runs synchronously and returns -1
• When executed outside the init callback, this function runs asynchronously and returns an
async ID

Examples
wait_async(set_loop_par(%NI_USER_ZONE_IDS[0], 0, $LOOP_PAR_MODE,
$SampleLoopOnA))

15.7. set_num_user_zones()
set_num_user_zones(<number_of_user_zones>)
Creates empty user zones
<number_of_user_zones> Defines the number of user zones to be created.
%NI_USER_ZONE_IDS is the array of size
<number_of_user_zones> with all the user zone IDs.

Remarks
• A maximum of 512 user zones per instrument can be created
• User zones are shown with a different color in the mapping editor
• User zones cannot be modified from the mapping editor
• In order to manipulate the user zones, the IDs stored in the %NI_USER_ZONE_IDS array
should be used, instead of the hardcoded zone IDs
ZONE COMMANDS 132

Examples
on init
...
set_num_user_zones(2)
set_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_GROUP, 30)
set_zone_par(%NI_USER_ZONE_IDS[1], $ZONE_PAR_GROUP, 31)
...
end on

15.8. set_sample
set_sample(<zone-id>,<sample-path>)
Sets the user sample in a zone
<zone-id> The ID of the zone
<sample-path> The sample path of the sample

Remarks
• set_sample() only works in user zones
• When executed in the init callback, this function runs synchronously and returns -1
• When executed outside the init callback, this function runs asynchronously and returns an
async ID

Examples
on ui_control ($myMouseArea)
if ($NI_MOUSE_EVENT_TYPE = $NI_MOUSE_EVENT_TYPE_DROP)
if (num_elements(!NI_DND_ITEMS_AUDIO) = 1)
$async_lock := 1
wait_async(set_sample(%NI_USER_ZONE_IDS[0],
!NI_DND_ITEMS_AUDIO[0]))
end on

15.9. set_zone_par()
set_zone_par(<zone-id>,<parameter>,<value>)
Sets the user zone parameters
<zone-id> The ID of the zone
ZONE COMMANDS 133

set_zone_par(<zone-id>,<parameter>,<value>)
<parameter> The following flags are available:
$ZONE_PAR_HIGH_KEY

$ZONE_PAR_LOW_KEY

$ZONE_PAR_HIGH_VELO

$ZONE_PAR_LOW_VELO

$ZONE_PAR_ROOT_KEY

$ZONE_PAR_FADE_LOW_KEY

$ZONE_PAR_FADE_HIGH_KEY

$ZONE_PAR_FADE_LOW_VELO

$ZONE_PAR_FADE_HIGH_VELO

$ZONE_PAR_VOLUME

$ZONE_PAR_PAN

$ZONE_PAR_TUNE

$ZONE_PAR_GROUP

$ZONE_PAR_SAMPLE_START

$ZONE_PAR_SAMPLE_END

$ZONE_PAR_SAMPLE_MOD_RANGE
<value> The value of the zone parameter

Remarks
• set_zone_par() only works in user zones
• When executed in the init callback, this function runs synchronously and returns -1
• When executed outside the init callback, this function runs asynchronously and returns an
async ID

Examples
set_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_GROUP, 0)
LOAD/SAVE COMMANDS 134

16. Load/Save Commands

16.1. General Information

File Formats
It is possible to load and save the following file formats:
• KONTAKT arrays (.nka files)
• MIDI files (.mid) to be used with the file commands in KSP
• IR samples (.wav, .aif, .aiff, .ncw) to be used with KONTAKT's convolution effect (loading only)

Async Handling
Loading and saving files cannot be executed in real-time. This is why all load/save commands
return a unique value upon completion of their action. You can use this value in combination with
$NI_ASYNC_ID and $NI_ASYNC_EXIT_STATUS within the on_async_complete callback to
check whether the the command has completed its action, and whether or not the loading or
saving was successful.

Path Handling
All file paths in KSP use a slash character (/) as a folder separator. Backslash characters are not
supported. The full path has to start with a slash character “/”.

Examples
Factory folder on OS X:
/Library/Application Support/Native Instruments/Kontakt 6/
Factory folder on Windows:
/C:/Program Files/Common Files/Native Instruments/Kontakt 6/
When loading or saving files with an absolute path as opposed to loading from the Resource
Container, always use path variables in combination with get_folder().

See Also
$NI_ASYNC_ID
$NI_ASYNC_EXIT_STATUS
on async_complete

16.2. get_folder()
get_folder(<path-variable>)
Returns the path specified with the built-in path variable
LOAD/SAVE COMMANDS 135

get_folder(<path-variable>)
<path- The following path variables are available:
variable>
$GET_FOLDER_LIBRARY_DIR

If used with an NKI belonging to an encoded library: library folder.

If used with an unencoded NKI: the user content directory.

$GET_FOLDER_FACTORY_DIR

The factory folder of KONTAKT, mainly used for loading factory IR

samples.

Note: this is not the factory library folder!

$GET_FOLDER_PATCH_DIR

The directory in which the patch was saved.

If the patch was not saved before, an empty string is returned.

Remarks
• The behaviour $GET_FOLDER_LIBRARY_DIR changed from KONTAKT 5 onwards. If the NKI
belongs to an encoded library, it will point to its library folder. Otherwise, the user content
directory is returned.

Example
on init
message(get_folder($GET_FOLDER_FACTORY_DIR))
end on
Displaying the path of the factory folder of KONTAKT

See Also
load_ir_sample()
$GET_FOLDER_LIBRARY_DIR
$GET_FOLDER_FACTORY_DIR
$GET_FOLDER_PATCH_DIR

16.3. load_array()
load_array(<array-variable>,<mode>)
Loads an array from an external file (.nka file)
<array- The array variable, this name must be present in the .nka file
variable>
LOAD/SAVE COMMANDS 136

load_array(<array-variable>,<mode>)
<mode> 0: A dialog window pops up, allowing you to select an .nka file. Can only
be used in UI, PGS and persistence_changed callbacks.

1: The array is directly loaded from the "Data" folder.

For user instruments, the "Data" folder is located beside the resource
container.

For library instruments, the "Data" folder is located here:

OS X: <UserName>/Library/Application Support/<Library
Name>/

Win: C:\User\<UserName>\AppData\Local\<Library Name>\

Can be used in UI, PGS, init (synchronous) and persistence_changed

callbacks.

2: The array is directly loaded from the "data" folder inside the resource
container. Can be used in UI, PGS, init (synchronous) and
persistence_changed callbacks.

Remarks
• It is also possible to load string arrays from .nka files.
• It is not possible to load an array with %xyz in its .nka file into array %abc.
• The array data is not directly available after the load_array() command has been executed
since the command works asynchronously. The only situation in which the values are instantly
available is when using mode 1 or mode 2 within an init callback.
• When using mode 0 the callback continues even if the loading dialog is still open.
• Mode 2 is only available for loading arrays, i.e. save_array() does not have this option.
• When loading an array within the init callback, please remember that the loaded data will be
overwritten at the end of the callback if the array is persistent. Use
read_persistent_var() before loading the array to avoid this problem.
• .nka files loaded from the resource container should always have a newline character at the
end of the file. If this last newline is missing, then KONTAKT will not know the file has ended
and will continue to try and load other data from the resources container. Files generated by
the save_array() command have this automatically, but if you are creating files manually,
then this is something to take care of.

Example
(see next page)
on init
declare $count
declare ui_button $Load
declare ui_button $Save
declare ui_table %table[8] (2,2,100)
make_persistent(%table)
declare %preset[8]
declare $load_arr_id
$load_arr_id := -1
declare $save_arr_id
LOAD/SAVE COMMANDS 137

$save_arr_id := -1
end on

on ui_control (%table)
$count := 0
while($count < 8)
%preset[$count] := %table[$count]
inc($count)
end while
end on

on ui_control ($Load)
$load_arr_id := load_array(%preset,0)
end on

on ui_control ($Save)
$save_arr_id := save_array(%preset,0)
end on

on async_complete
if ($NI_ASYNC_ID = $load_arr_id)
$load_arr_id := -1
$Load := 0
if ($NI_ASYNC_EXIT_STATUS = 1)
$count := 0
while($count < 8)
%table[$count] := %preset[$count]
inc($count)
end while
end if
end if
if ($NI_ASYNC_ID = $save_arr_id)
$save_arr_id := -1
$Save := 0
end if
end on
Exporting and loading the contents of a UI table

See Also
$NI_ASYNC_ID
$NI_ASYNC_EXIT_STATUS
on async_complete
save_array()

16.4. load_array_str()
load_array_str(<array-variable>,<path>)
Loads an array from an external file (.nka file) using the file's absolute path
<array-variable> The array variable. This name must be present in the .nka file
<path> The absolute path of the .nka file
LOAD/SAVE COMMANDS 138

Remarks
• The behaviour is similar to load_array() with mode set to 0, but instead of manually
choosing an .nka file you can specify it with an absolute path.
• Can be used in init (synchronous), persistence_changed, UI and PGS callbacks.

Example
(see next page)
on init
set_ui_height(2)

declare @basepath_browser
{set browser path here, for example
@basepath_browser := "/Users/<username>/Desktop/Arrays"}

declare @file_path
make_persistent(@file_path)

declare @file_name
make_persistent(@file_name)

declare ui_file_selector $file_browser

declare $browser_id
$browser_id := get_ui_id($file_browser)
set_control_par_str($browser_id,$CONTROL_PAR_BASEPATH,@basepath_browser)
set_control_par($browser_id,$CONTROL_PAR_WIDTH,112)
set_control_par($browser_id,$CONTROL_PAR_HEIGHT,68)
set_control_par($browser_id,$CONTROL_PAR_COLUMN_WIDTH,110)
set_control_par($browser_id,$CONTROL_PAR_FILE_TYPE,$NI_FILE_TYPE_ARRAY)
move_control_px($file_browser,66,2)

declare ui_table %table[8] (2,2,100)

make_persistent(%table)
move_control(%table,3,1)

declare %preset[8]

declare $load_arr_id
$load_arr_id := -1
declare $count
end on

on async_complete

if ($NI_ASYNC_ID = $load_arr_id)

$load_arr_id := -1

if ($NI_ASYNC_EXIT_STATUS = 0)
message("Array not found!")
else
message("")
$count := 0
while($count < 8)
%table[$count] := %preset[$count]
inc($count)
end while
LOAD/SAVE COMMANDS 139

end if
end if
end on

on ui_control ($file_browser)
@file_name := fs_get_filename($browser_id,0)
@file_path := fs_get_filename($browser_id,2)
$load_arr_id := load_array_str(%preset,@file_path)
end on
Loading different table presets with a browser. Make sure to first set the browser path of the file selector
to point to a folder with compatible .nka files

16.5. load_ir_sample()
load_ir_sample(<file-path>,<slot>,<generic>)
Loads an impulse response sample into KONTAKT's convolution effect
<file-path> The absolute file path of the IR sample.

If no path is specified, the command will look for the specified sample
within the “ir_samples” folder of the Resource Container.

If no Resource Container is available, the folder "ir_samples" within the

KONTAKT user folder will be checked.

The KONTAKT user folder is loacated here:

OS X: /Users/<username>/Documents/Native Instruments/
Kontakt/

Windows: C:/Users/<username>/Documents/Native
Instruments/Kontakt/
<slot> The slot index of the convolution effect (zero-based)
<generic> Specifies whether the convolution effect is used as an:

1: Insert Effect

0: Send Effect

For buses, this parameter specifies the actual bus:

$NI_BUS_OFFSET + [0-15] one of the 16 busses

Remarks
• Please note that subfolders inside the "ir_samples" folder will not be scanned and it is not
recommended to add them manually via text strings. Doing so could lead to problems
because subfolders are being ignored during the creation of a Resource Container monolith.

Example
(see next page)
on init
declare ui_button $Load
declare $load_ir_id
$load_ir_id := -1
LOAD/SAVE COMMANDS 140

end on

on ui_control ($Load)
$load_ir_id := load_ir_sample("Small Ambience.wav",0,0)
$Load := 0
end on

on async_complete

if ($NI_ASYNC_ID = $load_ir_id)

$load_ir_id := -1

if ($NI_ASYNC_EXIT_STATUS = 0)
message("IR sample not found!")
else
message("IR sample loaded!")
end if

end if

end on
Load an IR sample into a convolution send effect in the first slot

See Also
$NI_ASYNC_ID
get_folder()
on async_complete

16.6. save_array()
save_array(<array-variable>,<mode>)
Saves an array to an external file, i.e. an .nka file
<array- The array to be saved
variable>
<mode> 0: A dialog window pops up, allowing you to save the .nka file. Can only
be used in UI and PGS callbacks.

1: The array is directly loaded from the "Data" folder.

For user instruments, the "Data" folder is located beside the resource
container.

For library instruments, the "Data" folder is located here:

OS X: <UserName>/Library/Application Support/<Library
Name>/

Win: C:\User\<UserName>\AppData\Local\<Library Name>\

Can be used in UI, PGS, and persistence_changed callbacks.

LOAD/SAVE COMMANDS 141

Remarks
• It is also possible to save string arrays into .nka files.
• The exported .nka file consists of the name of the array followed its values.
• When using mode 0 the callback continues even if the loading dialog is still open.

See Also
$NI_ASYNC_ID
$NI_ASYNC_EXIT_STATUS
on async_complete
load_array()

16.7. save_array_str()
save_array_str(<array-variable>,<path>)
Saves an array to an external file, i.e. an .nka file, using the specified absolute path
<array-variable> The array to be saved
<path> The absolute path of the .nka file to be saved

Remarks
• The behaviour is similar to save_array(), but instead of manually choosing a save location,
you can directly save the file to the specified location.
• If the file does not exist but the folder does, a new .nka file will be created.
• Can be used in persistence_changed, UI and PGS callbacks.

Example
(see next page)
on init
declare $count

declare @path
{set save path here, for example
@path := "/Users/<username>/Desktop/Arrays/"}

declare ui_button $Save

declare ui_table %table[8] (2,2,100)

make_persistent(%table)

declare %preset[8]

declare $save_arr_id
$save_arr_id := -1

declare ui_text_edit @preset_name

make_persistent(@preset_name)

set_control_par_str(get_ui_id(@preset_name),$CONTROL_PAR_TEXT,"empty")
LOAD/SAVE COMMANDS 142

set_control_par(get_ui_id(@preset_name),$CONTROL_PAR_FONT_TYPE,25)
set_control_par(get_ui_id(@preset_name),$CONTROL_PAR_POS_X,73 + 3*92)
set_control_par(get_ui_id(@preset_name),$CONTROL_PAR_POS_Y,2)

declare ui_label $pattern_lbl(1,1)

set_text($pattern_lbl,"")
move_control_px($pattern_lbl,66 + 3*92,2)

end on

on ui_control (%table)
$count := 0
while($count < 8)
%preset[$count] := %table[$count]
inc($count)
end while
end on

on ui_control ($Save)
$save_arr_id := save_array_str(%preset,@path & @preset_name & ".nka")
end on

on async_complete
if ($NI_ASYNC_ID = $save_arr_id)
$save_arr_id := -1
$Save := 0
end if
end on
Save table presets with custom names. Make sure to set the path where the .nka files will be saved.

declare ui_text_edit @file_name

set_control_par_str(get_ui_id(@file_name),$CONTROL_PAR_TEXT,"<empty>")
set_control_par(get_ui_id(@file_name),$CONTROL_PAR_FONT_TYPE,25)
make_persistent(@file_name)
move_control_px(@file_name,73,2)

declare ui_label $file_name_lbl(1,1)

LOAD/SAVE COMMANDS 143

set_text($file_name_lbl,"")
move_control_px($file_name_lbl,66,2)

declare ui_button $Save

move_control($Save,2,1)

declare $save_mf_id
$save_mf_id := -1

end on

on ui_control ($Save)
$save_mf_id := save_midi_file(@path & @file_name & ".mid")
end on

on async_complete
if ($NI_ASYNC_ID = $save_mf_id)
$save_mf_id := -1
$Save := 0
end if
end on
Saving a MIDI file

See Also
mf_insert_file()
mf_set_export_area()
MUSIC INFORMATION RETRIEVAL 144

17. Music Information Retrieval

17.1. General Information

Music Information Retrieval (MIR) allows the extraction of meaningful features from audio files,
such as pitch or the volume level of a sample. New KSP commands allow extraction of such
parameters from samples via script. MIR functions are not asyncronous in the init callback (-1
as async ID), but asynchronous otherwise.
Note: the type detection functions listed below (Sample Type, Drum Type, and Instrument Type)
are designed to process one-shot audio samples.

17.2. detect_pitch()
detect_pitch(<zone-id>,<pitch-result>)
Returns a real value representing the fundamental frequency of an audio sample, in semitones
and cents. If detection fails, the function will set <pitch-result> to

~NI_DETECT_PITCH_INVALID
<zone-id> The ID of the zone
<pitch-result> The MIDI note value of the detected pitch

17.3. detect_loudness()
detect_loudness(<zone-id>,<loudness-result>)
Returns a real value representing the loudness of an audio sample in dB. Loudness is measured
according to the standard established by the International Telecommunication Union:
Algorithms to measure audio program loudness and true-peak audio level - ITU-R BS.1770-4 (2015).
If detection fails, the function will set <loudness-result> to:

~NI_DETECT_LOUDNESS_INVALID
<zone-id> The ID of the zone
<loudness-result> The detected loudness in dB

17.4. detect_peak()
detect_peak(<zone-id>,<peak-result>)
Returns a real value representing peak level of an audio sample in dB. Peak is measured
according to the standard established by the International Telecommunication Union:
Algorithms to measure audio program loudness and true-peak audio level - ITU-R BS.1770-4 (2015). If
detection fails, the function will set <peak-result> to: ~NI_DETECT_PEAK_INVALID
<zone-id> The ID of the zone
MUSIC INFORMATION RETRIEVAL 145

detect_peak(<zone-id>,<peak-result>)
<peak-result> The detected peak level in dB

17.5. detect_rms()
detect_rms(<zone-id>,<rms-result>)
Returns a real value representing the RMS level of an audio sample in dB. If detection fails, the
function will set <rms-result> to: ~NI_DETECT_RMS_INVALID
<zone-id> The ID of the zone
<rms-result> The real value of the RMS level of the audio
sample in dB

17.6. detect_sample_type()
detect_sample_type(<zone-id>,<sample-type-result>)
Assigns <sample-type-result> a $NI_DETECT_SAMPLE_TYPE tag describing the whether
an audio sample is a drum or an instrument. If detection fails, the function will set <sample-
type-result> to: $NI_DETECT_SAMPLE_TYPE_INVALID.
<zone-id> The ID of the zone
<sample-type- The detected sample type, can be one of the following:
result>
$NI_DETECT_SAMPLE_TYPE_INVALID

$NI_DETECT_SAMPLE_TYPE_INSTRUMENT

$NI_DETECT_SAMPLE_TYPE_DRUM

17.7. detect_drum_type()
detect_drum_type(<zone-id>,<drum-type-result>)
Assigns <drum-type-result> a $NI_DETECT_DRUM_TYPE tag describing the drum type of
an audio sample. Hint: use this function if detect_sample_type() determines that a given
audio sample is of type $NI_DETECT_SAMPLE_TYPE_DRUM. If detection fails, the function will
set <drum-type-result> to: ~NI_DETECT_DRUM_TYPE_INVALID.
<zone-id> The ID of the zone
MUSIC INFORMATION RETRIEVAL 146

detect_drum_type(<zone-id>,<drum-type-result>)
<drum-type-result> The detected drum type, can be one of the following:
$NI_DETECT_DRUM_TYPE_INVALID

$NI_DETECT_DRUM_TYPE_KICK

$NI_DETECT_DRUM_TYPE_SNARE

$NI_DETECT_DRUM_TYPE_CLOSED_HH

$NI_DETECT_DRUM_TYPE_OPEN_HH

$NI_DETECT_DRUM_TYPE_TOM

$NI_DETECT_DRUM_TYPE_CYMBAL

$NI_DETECT_DRUM_TYPE_CLAP

$NI_DETECT_DRUM_TYPE_SHAKER

$NI_DETECT_DRUM_TYPE_PERC_DRUM

$NI_DETECT_DRUM_TYPE_PERC_OTHER

17.8. detect_instrument_type()
detect_instrument_type(<zone-id>,<instrument-type-result>)
Assigns <drum-type-result> a $NI_DETECT_INSTRUMENT_TYPE tag describing the
instrument type of an audio sample. Hint: use this function if detect_sample_type()
determines that a given audio sample is of type $NI_DETECT_SAMPLE_TYPE_INSTRUMENT. If
detection fails, the function will set <instrument-type-result> to:
$NI_DETECT_INSTRUMENT_TYPE_INVALID.
<zone-id> The ID of the zone
MUSIC INFORMATION RETRIEVAL 147

detect_instrument_type(<zone-id>,<instrument-type-result>)
<instrument-type- The detected instrument type, can be one of the following:
result>
$NI_DETECT_INSTRUMENT_TYPE_INVALID

$NI_DETECT_INSTRUMENT_TYPE_BASS

$NI_DETECT_INSTRUMENT_TYPE_BOWED_STRING

$NI_DETECT_INSTRUMENT_TYPE_BRASS

$NI_DETECT_INSTRUMENT_TYPE_FLUTE

$NI_DETECT_INSTRUMENT_TYPE_GUITAR

$NI_DETECT_INSTRUMENT_TYPE_KEYBOARD

$NI_DETECT_INSTRUMENT_TYPE_MALLET

$NI_DETECT_INSTRUMENT_TYPE_ORGAN

$NI_DETECT_INSTRUMENT_TYPE_PLUCKED_STRING

$NI_DETECT_INSTRUMENT_TYPE_REED

$NI_DETECT_INSTRUMENT_TYPE_SYNTH

$NI_DETECT_INSTRUMENT_TYPE_VOCAL

17.9. Examples
wait_async(detect_pitch(%NI_USER_ZONE_IDS[0], ~pitch_result))
wait_async(set_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_ROOT_KEY,
real_to_int(round(~pitch_result))))
wait_async(set_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_TUNE,
real_to_int(100.0 * (round(~pitch_result) - ~pitch_result)))
Set the zone root key by rounding the pitch result to an integer value. Then set the zone tune to correct
for the pitch offset.
wait_async(detect_sample_type(%NI_USER_ZONE_IDS[0], $sample_type))
if ($sample_type = $NI_DETECT_SAMPLE_TYPE_INSTRUMENT)
wait_async(detect_instrument_type(%NI_USER_ZONE_IDS[0], $instrument_type))
else
wait_async(detect_drum_type(%NI_USER_ZONE_IDS[0], $drum_type))
end if

if ($sample_type = $NI_DETECT_SAMPLE_TYPE_INSTRUMENT)
if ($instrument_type = $NI_DETECT_INSTRUMENT_TYPE_BASS)
set_text ($label_5,"Bass")
end if
else
if ($drum_type = $NI_DETECT_DRUM_TYPE_KICK)
set_text ($label_5,"Kick")
end if
end if
Detect whether a sample is of type instrument or drum, and detect the corresponding drum or
instrument type.
MIDI OBJECT COMMANDS 148

18. MIDI Object Commands

18.1. 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 enabled 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.
MIDI OBJECT COMMANDS 149

18.2. 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.
MIDI OBJECT COMMANDS 150

See Also
$NI_ASYNC_ID
$NI_ASYNC_EXIT_STATUS
on async_complete
save_midi_file()
mf_set_event_par()
mf_get_event_par()

18.3. 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)
MIDI OBJECT COMMANDS 151

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.

See Also
mf_insert_file()
$CONTROL_PAR_DND_BEHAVIOUR
save_midi_file()

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

18.5. 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"
MIDI OBJECT COMMANDS 152

!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()

18.6. 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()
MIDI OBJECT COMMANDS 153

18.7. 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()

18.8. 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()

18.9. 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
MIDI OBJECT COMMANDS 154

mf_insert_event(<track>,<pos>,<command>,<byte1>,<byte2>)
<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()

18.10. 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()
MIDI OBJECT COMMANDS 155

mf_set_buffer_size()
mf_get_buffer_size()
mf_reset()
mf_insert_event()
save_midi_file()

18.11. 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_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.

See Also
mf_insert_file()
mf_insert_event()
mf_remove_event()
$ALL_EVENTS
MIDI OBJECT COMMANDS 156

$CURRENT_EVENT
by_marks()
by_track()
mf_set_mark()
mf_get_id()
save_midi_file()

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

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.

See Also
mf_insert_file()
mf_insert_event()
mf_remove_event()
MIDI OBJECT COMMANDS 157

$CURRENT_EVENT
mf_get_id()
save_midi_file()

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

See Also
mf_get_first()
mf_get_next()
mf_get_next_at()
mf_get_prev()
mf_get_prev_at()
mf_get_last()

18.14. mf_set_mark()
mf_set_mark(<event-id>,,<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
 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

See Also
mf_insert_file()
mf_insert_event()
mf_remove_event()
$ALL_EVENTS
$CURRENT_EVENT
mf_get_mark()
by_marks()
by_track()
mf_get_mark()
mf_get_id()
save_midi_file()
MIDI OBJECT COMMANDS 158

18.15. mf_get_mark()
mf_get_mark(<event-id>,)
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
 The mark number. Use the constants $MARK_1 to $MARK_10

See Also
mf_insert_file()
mf_insert_event()
mf_remove_event()
$ALL_EVENTS
$CURRENT_EVENT
mf_set_mark()
by_marks()
by_track()
mf_get_mark()
mf_get_id()
save_midi_file()

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

See Also
mf_insert_file()
mf_insert_event()
mf_remove_event()
$ALL_EVENTS
$CURRENT_EVENT
mf_set_mark()
mf_get_mark()
by_marks()
by_track()
mf_get_mark()
mf_get_id()
save_midi_file()
MIDI OBJECT COMMANDS 159

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

See Also
mf_insert_file()
mf_insert_event()
mf_remove_event()
$ALL_EVENTS
$CURRENT_EVENT
mf_set_mark()
mf_get_mark()
by_marks()
mf_get_mark()
mf_get_id()
save_midi_file()

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