0% found this document useful (0 votes)

241 views

KSP Reference Manual

KSP Reference Manual was written by: Nicki Marinic. Manual contains: Callbacks. 2 Variables. 10 Control Statements. 16 Operators. 19 Array Functions. 21 Group Functions. 25 User Interface Controls. 32 Commands. 60 Built-in Variables and Constants. 94 Engine Parameter Commands. 97 Engine Parameter Variables. 104 Advanced Concepts. 119 version history.

Uploaded by

gonzambo

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)

241 views

KSP Reference Manual

Uploaded by

gonzambo

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

KSP Reference Manual

Table of Contents

Table of Contents ........................................................................................................................ 1 Callbacks .................................................................................................................................... 2 Variables .................................................................................................................................. 10 Control Statements .................................................................................................................... 16 Operators .................................................................................................................................. 19 Array Functions ......................................................................................................................... 21 Group Functions ........................................................................................................................ 25 User Interface Controls .............................................................................................................. 32 Commands................................................................................................................................ 60 Built-in Variables & Constants..................................................................................................... 90 Control Parameter Variables ........................................................................................................ 94 Engine Parameter Commands ..................................................................................................... 97 Engine Parameter Variables ...................................................................................................... 104 Advanced Concepts ................................................................................................................. 114 Multi Script ............................................................................................................................ 119 Version History ........................................................................................................................ 125 Index...................................................................................................................................... 128

KSP Reference Manual Callbacks

Callbacks on controller
on controller
controller callback, executed whenever a CC, pitch bend or channel pressure message is received

Examples
on controller if (in_range($CC_NUM,0,127)) message("CC Number: "& $CC_NUM&" - Value: " & %CC[$CC_NUM]) else if ($CC_NUM = $VCC_PITCH_BEND) message("Pitchbend" & " - Value: " & %CC[$CC_NUM]) end if if ($CC_NUM = $VCC_MONO_AT) message("Channel Pressure" &" - Value: "&%CC[$CC_NUM]) end if end if end on

query CC, pitch bend and channel pressure data

See Also
set_controller() ignore_controller %CC[] $CC_NUM $VCC_PITCH_BEND $VCC_MONO_AT

KSP Reference Manual Callbacks

on init
on init
init callback, executed when the script was successfully analyzed

Examples
on init declare ui_button $Sync declare ui_menu $time add_menu_item ($time,"16th",0) add_menu_item ($time,"8th",1) $Sync := 0 {sync is off by default, so hide menu} move_control ($time,0,0) move_control ($Sync,1,1) make_persistent ($Sync) make_persistent ($time) read_persistent_var ($Sync) if ($Sync = 1) move_control ($time,2,1) else move_control ($time,0,0) end if end on on ui_control ($Sync) if ($Sync = 1) move_control ($time,2,1) else move_control ($time,0,0) end if end on

init callback with read_persistent_var()

See Also
make_persistent read_persistent_var

KSP Reference Manual Callbacks

on note
on note
note callback, executed whenever a note on message is received

Examples
on note message ("Note Number: " & $EVENT_NOTE ... & " - Velocity: " & $EVENT_VELOCITY) end on

query note data

KSP Reference Manual Callbacks

on release
on release
release callback, executed whenever a note off message is received

Examples
on init declare $new_id end on on release wait(1000) $new_id := play_note($EVENT_NOTE,$EVENT_VELOCITY,0,100000) change_vol ($new_id,-24000,1) end on

creating an artificial release noise

KSP Reference Manual Callbacks

on pgs_changed
on pgs_changed
callback type, executed whenever any pgs_set_key_val() command is executed in any script

Remarks
pgs stands for Program Global Storag 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

Example 1 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.

KSP Reference Manual Callbacks

on rpn/nrpn
on rpn/nrpn
rpn and nrpn callbacks, executed whenever a rpn or nrpn (registered/nonregistered parameter number) message is received

Examples
on rpn select ($RPN_ADDRESS) case 0 message ("Pitch Bend Sensitivity"&" - Value: "& $RPN_VALUE) case 1 message ("Fine Tuning" & " - Value: " & $RPN_VALUE) case 2 message ("Coarse Tuning" & " - Value: " & $RPN_VALUE) end select end on

query standard rpn messages

See Also
on controller set_rpn/set_nrpn msb()/lsb() $RPN_ADDRESS $RPN_VALUE

KSP Reference Manual Callbacks

on ui_control()
on ui_control(<variable>)
UI callback, executed whenever the user changes the respective UI element

Examples
on init declare ui_knob $Knob (0,100,1) declare ui_button $Button declare ui_switch $Switch declare ui_table %Table[10] (2,2,100) declare ui_menu $Menu add_menu_item ($Menu,"Entry 1",0) add_menu_item ($Menu,"Entry 2",1) declare ui_value_edit $VEdit (0,127,1) declare ui_slider $Slider (0,100) end on on ui_control ($Knob) message("Knob" & " (" & $ENGINE_UPTIME & ")") end on on ui_control ($Button) 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

KSP Reference Manual Callbacks

on ui_update
on ui_update
UI update callback, executed with every GUI change in Kontakt

Remarks
on ui_update should be used with caution, since it is triggered with every GUI change in Kontakt.

Examples
on init declare ui_knob $Volume (0,1000000,1) set_knob_unit ($Volume,$KNOB_UNIT_DB) set_knob_defval ($Volume,630859) $Volume := _get_engine_par ($ENGINE_PAR_VOLUME,-1,-1,-1) set_knob_label ($Volume,_get_engine_par_disp... ($ENGINE_PAR_VOLUME,-1,-1,-1)) end on on ui_update $Volume := _get_engine_par ($ENGINE_PAR_VOLUME,-1,-1,-1) set_knob_label($Volume,_get_engine_par_disp... ($ENGINE_PAR_VOLUME,-1,-1,-1)) end on on ui_control ($Volume) _set_engine_par($ENGINE_PAR_VOLUME,$Volume,-1,-1,-1) set_knob_label ($Volume,_get_engine_par_disp... ($ENGINE_PAR_VOLUME,-1,-1,-1)) end on

mirroring instrument volume with a KSP control

KSP Reference Manual Variables

Variables $ (variable)
declare $<variable-name>
declare a user-defined normal variable to store a single integer value

query CC, pitch bend and channel pressure data

See Also
set_controller() ignore_controller

KSP Reference Manual Variables

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

query CC, pitch bend and channel pressure data

See Also
set_controller() ignore_controller

KSP Reference Manual Variables

polyphonic $ (polyphonic variable)

declare polyphonic $<variable-name>
declare a user-defined polyphonic variable to store a single integer value.

Remarks
A polyphonic variable acts as a unique variable for each executed event, avoiding conflicts in callbacks that are executed in parallel. A polyphonic variable retains its value in the release callback of the corresponding note. Polyphonic variables need much more memory than normal variables.

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

KSP Reference Manual Variables

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

Remarks
The maximal size of arrays is 32768.

query CC, pitch bend and channel pressure data

KSP Reference Manual Variables

@ (string variable)
declare @<variable-name>
declare a user-defined string variable to store text

query CC, pitch bend and channel pressure data

KSP Reference Manual Variables

! (string array)
declare !<array-name>
declare a user-defined string array to store text strings at specified indices

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

KSP Reference Manual Control Statements

Control Statements ifelseend if

ifelseend if
declare a user-defined normal variable to store a single integer value

query CC, pitch bend and channel pressure data

KSP Reference Manual Control Statements

select()
select(<variable>)end select
select statement

query CC, pitch bend and channel pressure data

KSP Reference Manual Control Statements

while()
while(<condition>)end while
while loop

Examples
on note ignore_event($EVENT_ID) while($NOTE_HELD = 1) play_note($EVENT_NOTE,$EVENT_VELOCITY,0,$DURATION_QUARTER/2) wait($DURATION_QUARTER) end while end on

repeating held notes at the rate of one quarter note

KSP Reference Manual Operators

Operators Boolean Operators

Boolean operators are used in if and while statements, since they return if the condition is either true or false. Below is a list of all Boolean operators. x, y and z denote numerals, a and b stand for Boolean values.

Boolean Operators x > y x > y x >= y x <= y x = y x # y in_range(x,y,z) not a a and b a or b

greater than less than greater than or equal less than or equal equal not equal true if x is between y and z true if a is false and vice versa true if a is true and b is true true if a is true or b is true

Arithmetic Operators
The following arithmetic operators can be used:

Arithmetic operators x + y x - y x * y x / y x mod y -x

addition subtraction multiplication division modulo negative value

KSP Reference Manual Operators

Bit Operators
The following bit operators can be used:

Bit Operators x .and. y x .or. y .not. x sh_left(<expression>,<shift-bits>) sh_right(<expression>,<shift-bits>)

bitwise and bitwise or bitwise negation shifts the bits in <expression> by the amount of <shift-bits> to the left shifts the bits in <expression> by the amount of <shift-bits> to the right

KSP Reference Manual Array Functions

Array Functions array_equal()

array_equal(<array1-variable>,<array2-variable>)
check the values of two arrays, true if all values are equal, false if not

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 since the the two arrays don't have the same size

KSP Reference Manual Array Functions

num_elements()
num_elements(<array-variable>)
return the number of elements in an array

Remarks
With this function you can, e.g., check how many groups are affected by the current event by using num_elements(%GROUPS_AFFECTED).

Examples
on note message(num_elements(%GROUPS_AFFECTED)) end on

outputs the number of groups playing

See Also
array_equal() sort() search() %GROUPS_AFFECTED

KSP Reference Manual Array Functions

search()
search(<array-variable>,<value>)
searches the specified array for the specified value and returns the index of its first position. If the value is not found, the function returns -1

Examples
on init declare ui_table %array[10] (2,2,5) declare ui_button $check set_text ($check,"Zero present?") end on on ui_control ($check) if (search(%array,0) = -1) message ("No") else message("Yes") end if $check := 0 end on

checking if a specific value is present

See Also
array_equal() num_elements() sort()

KSP Reference Manual Array Functions

sort()
sort(<array-variable>,<direction>)
sort an array in ascending or descending order. With direction = 0, the array is sorted in ascending order With direction # 0, the array is sorted in descending order

Remarks
With this function you can, e.g., check how many groups are affected by the current event by using num_elements(%GROUPS_AFFECTED).

Examples
on init declare $count 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()

KSP Reference Manual Group Functions

Group Functions allow_group()

allow_group(<group-index>)
turn on the specified group,i.e. make it available for playback

Remarks
Note that the numbering of the group index is zero based, i.e. the first group has the group index 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()

KSP Reference Manual Group Functions

disallow_group()
disallow_group(<group-index>)
turn off the specified group,i.e. make it unavailable for playback

Remarks
Note that the numbering of the group index is zero based, i.e. the first group has the group index 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 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()

KSP Reference Manual Group Functions

find_group()
find_group(<group-name>)
returns the group index for the specified group

Examples
on init declare $new_note end on on note $new_note := abs($EVENT_NOTE-127) change_note ($EVENT_ID,$new_note) end on

a simple note inverter

See Also
$ALL_GROUPS $REF_GROUP_IDX %GROUPS_SELECTED allow_group() disallow_group group_name()

KSP Reference Manual Group Functions

get_event_par_arr()
get_event_par_arr(<ID-number>,<parameter>,<group-index>)
special form of get_event_par(), used to retrieve the group allow state of the specified event <ID-number> <parameter> <group-index> the ID number of the note event in this case, only $EVENT_PAR_ALLOW_GROUP the index of the group for changing the specified note's group allow state

Remarks
get_event_par_arr() is a special form (or to be more precise, it's the array variant) of get_event_par(). It is used to retrieve the allow state of a specific event. If will return 1, if the specified group is allowed and 0 if it's disaalowed.

Examples
on note disallow_group($ALL_GROUPS) set_event_par_arr($EVENT_ID,$EVENT_PAR_ALLOW_GROUP,1,0) end on

allowing only the first group, same as allow_group(0)

See Also
set_event_par_arr() get_event_par() $EVENT_PAR_ALLOW_GROUP

KSP Reference Manual Group Functions

group_name()
group_name(<group-index>)
returns the group name for the specified group

Remarks
Note that the numbering of the group index is zero based, i.e. the first group has the group index 0.

Examples
on init declare $count declare ui_menu $groups_menu while ($count < $NUM_GROUPS) add_menu_item ($groups_menu,group_name($count),$count) inc($count) end while end on

quickly creating a menu with all available groups

See Also
$ALL_GROUPS $NUM_GROUPS allow_group() disallow_group find_group() output_channel_name()

KSP Reference Manual Group Functions

purge_group()
purge_group(<group-index>,<mode>)
purges (i.e. unload) the samples of the specified group <group-index> <mode> the index number of the group which contains the samples to be purged If set to 0, the samples of the specified group are unloaded. If set to 1, the samples are reloaded.

Remarks
purge_group() is an advanced command, so it should be used with caution. Also, don't use purge_group() in a while loop or with $ALL_GROUPS. purge_group() can only be used in an ui 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

unloading all samples of the first group

KSP Reference Manual Group Functions

set_event_par_arr()
set_event_par_arr(<ID-number>,<parameter>,<value>,<groupindex>)
special form of set_event_par(), used to set the group allow state of the specified event <ID-number> <parameter> <value> <group-index> the ID number of the note event in this case, only $EVENT_PAR_ALLOW_GROUP If set to 1, the group set with <group-index> will be allowed for the event. If set to 0, the group set with <group-index> will be disallowed for the event. the index of the group for changing the specified note's group allow state

Remarks
set_event_par_arr() is a special form (or to be more precise, it's the array variant) of set_event_par(). It is used to set the allow state of a specific event.

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, that the first group is always played

See Also
get_event_par_arr() set_event_par() $EVENT_PAR_ALLOW_GROUP

KSP Reference Manual User Interface Controls

User Interface Controls add_menu_item()

add_menu_item(<variable>,<text>,<value>)
create a menu entry <variable> <text> <value> the variable of the ui menu the text of the menu entry the value of the menu entry

Remarks
You can only create menu entries in the init callback.

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

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

the values need not be in order

KSP Reference Manual User Interface Controls

add_text_line()
add_text_line (<variable>,<text>)
add a new text line in the specified label without erasing existing text <variable> <text> the variable of the ui label 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

KSP Reference Manual User Interface Controls

hide_part()
hide_part(<variable>,<hide-mask>)
hide specific parts of user interface controls <variable> <hide-mask> the name of the ui control bit by bit combination of the following constants: $HIDE_PART_BG {Background of knobs, labels, value edits and tables} $HIDE_PART_VALUE {value of knobs} $HIDE_PART_TITLE {title of knobs} $HIDE_PART_MOD_LIGHT {mod ring light of knobs}

Remarks
hide_part() is only available in the init callback.

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 (also possible with other ui elements)

See Also
$CONTROL_PAR_HIDE $HIDE_PART_NOTHING $HIDE_WHOLE_CONTROL

KSP Reference Manual User Interface Controls

get_control_par()
get_control_par(<ui-ID>,<control-parameter>)
retrieve various parameters of the specified gui control <ui-ID> <control-parameter> the ID number of the ui control. You can retrieve the ID number with get_ui_id() the control parameter variable like $CONTROL_PAR_WIDTH

Remarks
get_control_par() comes in two additional flavors, get_control_par_str() for the usage with text strings and get_control_arr() for working with arrays.

Examples
on init declare ui_value_edit $Test (0,100,1) message(get_control_par(get_ui_id($Test),... $CONTROL_PAR_WIDTH)) end on

retrieving the width of a value edit in pixels

KSP Reference Manual User Interface Controls

get_ui_id()
get_ui_id(<variable>)
retrieve the ID number of an ui control

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

declare ui_value_edit $Set(0,100,1) 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

KSP Reference Manual User Interface Controls

make_perfview
make_perfview
activates the performance view for the respective script

Remarks
make_perfview is only available 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_skin_offset() set_ui_height()

KSP Reference Manual User Interface Controls

move_control()
move_control(<variable>,<x-position>,<y-position>)
position ui elements in the standard Kontakt grid <variable> <x-position> <y-position> the name of the ui control the horizontal position of the control (0 to 6) the vertical position of the control (0 to 16)

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 (why you'd want to do that is up to you)

KSP Reference Manual User Interface Controls

move_control_px()
move_control_px(<variable>,<x-position>,<y-position>)
position ui elements in pixels <variable> <x-position> <y-position> the name of the ui control the horizontal position of the control in pixels 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. move_control_px(<variable>,66,2) equals move_control(variable>,1,1)

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 might be useful for reference

See Also
move_control() $CONTROL_PAR_POS_X $CONTROL_PAR_POS_Y

KSP Reference Manual User Interface Controls

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> <text> the name of the ui control the info text to be displayed

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

KSP Reference Manual User Interface Controls

set_control_par()
set_control_par(<ui-ID>,<control-parameter>,<value>)
change various parameters of the specified gui control <ui-ID> <control-parameter> <value> the ID number of the ui control. You can retrieve the ID number with get_ui_id() the control parameter variable like $CONTROL_PAR_WIDTH the (integer) value

Remarks
set_control_par() comes in two additional flavors, set_control_par_str() for the usage with text strings and set_control_arr() for working with arrays.

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 have to specify its position in pixels, too, once you enter "pixel-mode".
on init declare ui_label $test (1,1) set_text($test,"Text") set_control_par(get_ui_id($test),$CONTROL_PAR_TEXT_ALIGNMENT,1) end on

center text in lables

KSP Reference Manual User Interface Controls

set_key_color()
set_key_color(<note-number>,<key-color-constant>)
sets the color of the specified key (i.e. MIDI note) on the Kontakt keyboard. The following colors are available: $KEY_COLOR_NONE {default value} $KEY_COLOR_WHITE $KEY_COLOR_YELLOW $KEY_COLOR_GREEN $KEY_COLOR_RED $KEY_COLOR_CYAN $KEY_COLOR_BLUE

Examples
on init declare $count while ($count < 128) set_key_color($count,$KEY_COLOR_WHITE) inc($count) end while end on on note select ($EVENT_VELOCITY) case 1 to 25 set_key_color($EVENT_NOTE,$KEY_COLOR_BLUE) case 25 to 50 set_key_color($EVENT_NOTE,$KEY_COLOR_CYAN) case 51 to 75 set_key_color($EVENT_NOTE,$KEY_COLOR_GREEN) case 75 to 100 set_key_color($EVENT_NOTE,$KEY_COLOR_YELLOW) case 100 to 127 set_key_color($EVENT_NOTE,$KEY_COLOR_RED) end select end on on release set_key_color($EVENT_NOTE,$KEY_COLOR_WHITE) end on

your own, private light organ

KSP Reference Manual User Interface Controls

set_knob_defval()
set_knob_defval(<variable>,<value>)
assign a default value to a knob to which the knob is reset when Cmd-clicking 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

KSP Reference Manual User Interface Controls

set_knob_label()
set_knob_label(<variable>,<text>)
assign a text string to a knob <width> <height> the width of the label in grids the height of the label in grids

Examples
on init declare !rate_names[18] !rate_names[0] := "1/128" !rate_names[1] := "1/64" !rate_names[2] := "1/32" !rate_names[3] := "1/16 T" !rate_names[4] := "3/64" !rate_names[5] := "1/16" !rate_names[6] := "1/8 T" !rate_names[7] := "3/32" !rate_names[8] := "1/8" !rate_names[9] := "1/4 T" !rate_names[10] := "3/16" !rate_names[11] := "1/4" !rate_names[12] := "1/2 T" !rate_names[13] := "3/8" !rate_names[14] := "1/2" !rate_names[15] := "3/4" !rate_names[16] := "4/4" !rate_names[17] := "Bar" 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

KSP Reference Manual User Interface Controls

set_knob_unit()
set_knob_unit(<variable>,<knob-unit-constant>)
assign a unit mark to a knob. 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) 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

KSP Reference Manual User Interface Controls

set_table_steps_shown()
set_table_steps_shown(<variable>,<num-of-steps>)
changes the number of displayed columns in an ui table <variable> <num-of-steps> the name of the ui table the number of displayed steps

Examples
on init declare ui_table %table[32] (2,2,127) 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

KSP Reference Manual User Interface Controls

set_script_title()
set_script_title(<text>)
set the title of the script

Examples
on init make_perfview set_script_title("Performance View") set_ui_height(6) message("") end on

many performance view scripts start like this

KSP Reference Manual User Interface Controls

set_skin_offset()
set_skin_offset(<offset-in-pixel>)
offsets the chosen background tga file by the specified number of pixels

Remarks
If a background tga graphic file has been selected in the instrument options and this file is larger than the maximum height of the performance view, you can use this command to offset the background graphic, thus creating separate backgrounds for each of the script slots.

Examples
on init make_perfview set_ui_height(1) end on on controller if ($CC_NUM = 1) set_skin_offset(%CC[1]) end if end on

try this with the wallpaper called "Sunrise.tga" (Kontakt 4/presets/wallpaper/Sunrise.tga)

See Also
make_perfview set_ui_height_px()

KSP Reference Manual User Interface Controls

set_text()
set_text(<variable>,<text>)
when applied to a label: delete the text currently visible in the specified label and add new text when applied to knobs, buttons, switches and value edits: set the name of the ui element

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 size

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)

KSP Reference Manual User Interface Controls

set_ui_height()
set_ui_height(<height>)
set the height of a script in grids <height> the height of script in grids (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

KSP Reference Manual User Interface Controls

set_ui_height_px()
set_ui_height_px(<height>)
set the height of a script in grids <height> the height of script in pixel (50 to 350)

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

try this with some of the wallpaper tga files of the Kontakt 4 Factory Library, e.g. /Kontakt 4 Library/Choir/Z - Samples/Wallpaper/pv_choir_bg.tga

KSP Reference Manual User Interface Controls

ui_button
declare ui_button $<variable-name>
create a user interface button

Remarks
ui_button is similiar to ui_switch, however it 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

KSP Reference Manual User Interface Controls

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

Examples
on init declare declare declare declare declare end on ui_knob ui_knob ui_knob ui_knob ui_knob $Knob_1 $Knob_2 $Knob_3 $Knob_4 $Knob_5 (0,1000,1) (0,1000,10) (0,1000,100) (0,1000,20) (0,1000,-10)

various display ratios

on init declare $count 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

See Also
set_knob_defval() set_knob_label() set_knob_unit() ui_slider 53

KSP Reference Manual User Interface Controls

ui_label
declare ui_label $<variable-name> (<width>,<height>)
create a user interface text label <width> <height> the width of the label in grids the height of the label in grids

two labels with different size

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

KSP Reference Manual User Interface Controls

ui_menu
declare ui_menu $<variable-name>
create a user interface 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

create a menu with many entries in a jiffy

KSP Reference Manual User Interface Controls

ui_switch
declare ui_switch $<variable-name>
create a user interface switch

Remarks
ui_switch is similiar to ui_button, however it's possible to automate the control.

Examples
on init declare ui_switch $rec_button set_text ($rec_button,"Record") declare $rec_button_id $rec_button_id:= get_ui_id ($rec_button) set_control_par ($rec_button_id,$CONTROL_PAR_WIDTH,60) set_control_par ($rec_button_id,$CONTROL_PAR_HEIGHT,20) set_control_par ($rec_button_id,$CONTROL_PAR_TEXT_ALIGNMENT,1) set_control_par ($rec_button_id,$CONTROL_PAR_POS_X,250) set_control_par ($rec_button_id,$CONTROL_PAR_POS_Y,5) end on

switch with various settings utilizing set_control_par()

KSP Reference Manual User Interface Controls

ui_table
declare ui_table %<array>[columns](<width>,<height>,<range>)
create a user interface knob <width> <height> <range> the width of the table in grids the height of the table in grids the range of the table. If negative values are used, a bipolar table is created

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

KSP Reference Manual User Interface Controls

ui_slider
declare ui_slider $<variable-name> (<min>,<max>)
create a user interface slider <min> <max> the minimum value of the slider the maximum value of the slider

Examples
on init declare ui_slider $test (0,100) set_control_par(get_ui_id($test),$CONTROL_PAR_DEFAULT_VALUE,50) end on

slider with default value

on init declare ui_slider $test (-100,100) $test := 0 declare $id $id := get_ui_id($test) set_control_par($id,$CONTROL_PAR_MOUSE_BEHAVIOUR,2000) set_control_par($id,$CONTROL_PAR_DEFAULT_VALUE,0) set_control_par_str($id,$CONTROL_PAR_PICTURE,"K4_SLIDER_BIP_1") end on

creating a bipolar slider by loading a different picture background

KSP Reference Manual User Interface Controls

ui_value_edit
declare ui_value_edit $<variable>(<min>,<max>,<$display-ratio>)
create a user interface number box <min> <max> <display-ratio> the minimum value of the value edit the maximum value of the value edit the value is diveded by <display-ratio> for display purposes You can also use $VALUE_EDIT_MODE_NOTE_NAMES to display note names

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

See Also
$VALUE_EDIT_MODE_NOTE_NAMES $CONTROL_PAR_SHOW_ARROWS

KSP Reference Manual Commands

Commands abs()
abs(<expression>)
return the absolute value of an expression

Examples
on init declare $new_note end on on note $new_note := abs($EVENT_NOTE-127) change_note ($EVENT_ID,$new_note) end on

a simple note inverter

KSP Reference Manual Commands

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's (C-2, C-1C8)

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

KSP Reference Manual Commands

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 adress events via event groups like $ALL_EVENTS

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

KSP Reference Manual Commands

change_pan()
change_pan(<ID-number>,<panorama>,<relative-bit>)
change the pan position of a specific note event <ID-number> <panorama> <relative-bit> the ID number of the note event to be changed the pan position of the note event, from -1000 (left) to 1000 (right) If the relative bit is set to 0, the amount is absolute, i.e. the amount overwrites any previous set values of that event. 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 a note event level and does not change any panorama settings in the instrument itself. It is also not related to any MIDI 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) 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

KSP Reference Manual Commands

change_tune()
change_tune(<ID-number>,<tune-amount>,<relative-bit>)
change the tuning of a specific note event in millicent <ID-number> <tune-amount> <relative-bit> the ID number of the note event to be changed the tune amount in millicents, so 100000 equals 100 cent (i.e. a half tone) If the relative bit is set to 0, the amount is absolute, i.e. the amount overwrites any previous set values of that event. 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 a note event level and does not change any tune settings in the instrument itself. It is also not related to any MIDI 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 each note by 50 cent

KSP Reference Manual Commands

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

KSP Reference Manual Commands

change_vol()
change_vol(<ID-number>,<volume>,<relative-bit>)
change the volume of a specific note event in millidecibel <ID-number> <volume> <relative-bit> the ID number of the note event to be changed the volume change in millidecibel If the relative bit is set to 0, the amount is absolute, i.e. the amount overwrites any previous set values of that event. 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 a 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).

Examples
on init declare $vol_amount end on 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()

KSP Reference Manual Commands

dec()
dec(<expression>)
decrement an expression by 1

Examples
on init declare ui_button $Reset declare $volume end on on ui_control ($Reset) $volume := 0 $Reset := 0 end on on note dec($volume) change_vol($EVENT_ID,$volume*1000,0) end on

note fader: each played note is 1dB softer than the previous one

KSP Reference Manual Commands

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

KSP Reference Manual Commands

exit
exit
immediately stops a callback

Remarks
exit is a very "strong" command. Be very careful when using it, especially when dealing with larger scripts.

Examples
on note if (not(in_range($EVENT_NOTE,60,71))) exit end if {from here on, only notes between C3 to B3 will be processed} end on

useful for quickly setting up key ranges to be affected by the script

KSP Reference Manual Commands

fade_in()
fade_in(<ID-number>,<fade-time>)
perform a fade-in for a specific note event <ID-number> <fade-time> the ID number of the note event to be faded in 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

KSP Reference Manual Commands

fade_out()
fade_out(<ID-number>,<fade-time>,<stop-voice>)
perform a fade-out for a specific note event <ID-number> <fade-time> <stop_voice> the ID number of the note event to be faded in the fade-in time in microseconds If set to 1, the voice is stopped after the fade out. If set to 0, the voice will still be running after the fade out

Examples
on controller if ($CC_NUM = 1) if (%CC[1] mod 2 # 0) fade_out($ALL_EVENTS,5000,0) else fade_in($ALL_EVENTS,5000) end if end if end on

use the mod whel on held notes to create a stutter effect

on controller if ($CC_NUM = 1) fade_out($ALL_EVENTS,5000,1) end if end on

a custom "All Sound Off" implementation triggered by the mod wheel

KSP Reference Manual Commands

get_event_par()
get_event_par(<ID-number>,<parameter>)
return the value of a specific event parameter of the specified event <ID-number> <parameter> the ID number of the event 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 note event: $EVENT_PAR_VOLUME $EVENT_PAR_PAN $EVENT_PAR_TUNE $EVENT_PAR_NOTE $EVENT_PAR_VELOCITY $EVENT_PAR_SOURCE

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
on note message(get_event_par($EVENT_ID,$EVENT_PAR_NOTE)) end on

the same functionality as message($EVENT_NOTE)

check if the event comes from outside (-1) or if it was created in one of the five script slots ( 0-4)

on note message(get_event_par($EVENT_ID,$EVENT_PAR_SOURCE)) end on

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

KSP Reference Manual Commands

ignore_controller
ignore_controller
ignore a controller event in a controller callback

Examples
on controller if ($CC_NUM = 1) ignore_controller set_controller($VCC_MONO_AT,%CC[1] end if end on

transform the mod wheel into aftertouch

See Also
ignore_event() set_controller()

KSP Reference Manual Commands

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

KSP Reference Manual Commands

inc()
inc(<expression>)
increment an expression by 1

Examples
on init declare $count declare ui_table %table[100] (6,2,100) while ($count < num_elements(%table)) %table[$count] := 50 inc ($count) end while end on

initializing a table with a specific value by using a while loop

KSP Reference Manual Commands

lsb()
lsb(<value>)
return the LSB portion (least significant byte) of a 14 bit value

Examples
on rpn message(lsb($RPN_VALUE)) end on

commonly used when working with rpn and nrpn messages

on init declare ui_value_edit $Value (0,16383,1) end on on ui_control ($Value) message("MSB: " & msb($Value) & " - LSB: " & lsb($Value)) end on

Understanding MSB and LSB

KSP Reference Manual Commands

make_persistent()
make_persistent(<variable>)
retain the value of a variable when a patch is saved

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). When replacing script code by copy and replacing the text, the values of persistent variables is also retained. Sometimes, when working on more complex scripts, you'll want to "flush" the variables by resetting the script, that is applying an empty script in the respective slot.

Examples
on init declare ui_knob $Preset (1,10,1) make_persistent ($Preset) end on

user interface elements like knobs should usually retain their value when reloading the instrument

KSP Reference Manual Commands

message()
message(<variable/text>)
display text in the status line of Kontakt

Remarks
The message command is intended to be used for debugging and testing while programming a script. Since there is only one status line in Kontakt, it should not be used as a generic means of communication with the user, use a label instead. Make it a habit to write message("") in the init callback. You can then be sure that all previous messages (by the script or by the system) are deleted and you see only new messages.

Examples
on init message("Hello, world!") end on

the inevitable implementation of "Hello, world!" in KSP

on note message("Note " & $EVENT_NOTE & " received at " & ... $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()

KSP Reference Manual Commands

msb()
msb(<value>)
return the MSB portion (most significant byte) of a 14 bit value

Examples
on rpn message(msb($RPN_VALUE)) end on

commonly used when working with rpn and nrpn messages

on init declare ui_value_edit $Value (0,16383,1) end on on ui_control ($Value) message("MSB: " & msb($Value) & " - LSB: " & lsb($Value)) end on

Understanding MSB and LSB

KSP Reference Manual Commands

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 more on a 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

KSP Reference Manual Commands

output_channel_name()
output_channel_name(<output-number>)
returns the channel name for the specified putput <output-number> the number of the output channel (zero based, i.e. the first output is 0) if -1 is applied, the default output (as specified in the instrument header) will be used

Examples
on init declare $count declare ui_menu $menu add_menu_item($menu,"Default",-1) $count := 0 while($count < $NUM_OUTPUT_CHANNELS) add_menu_item($menu,output_channel_name($count),$count) inc($count) end while $menu := get_engine_par($ENGINE_PAR_OUTPUT_CHANNEL,0,-1,-1) end on on ui_control ($menu) set_engine_par($ENGINE_PAR_OUTPUT_CHANNEL,$menu,0,-1,-1) end on

mirroring the output channel assignment menu of the first group

See Also
$NUM_OUTPUTS $ENGINE_PAR_OUTPUT_CHANNEL

KSP Reference Manual Commands

play_note()
play_note(<note-number>,<velocity>,<sample-offset>,<duration>)
generate a MIDI note, i.e. generate a note on message followed by a note off message <note-number> <velocity> <sample-offset> <duration> the note number to be generated (0 -127) velocity of the generated note (1 -127) this parameter specifies an offset in the sample in microseconds specifies the 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
The sample offset parameter does not work in DFD mode only in sampler mode. You can retrieve the event ID of the played note 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

KSP Reference Manual Commands

random()
random(<min>,<max>)
generate a random number

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 in by 10 percent

KSP Reference Manual Commands

reset_ksp_timer
reset_ksp_timer
resets the KSP timer ($KSP_TIMER) to zero

Remarks
Since the built-in variable $KSP_TIMER returns the engine uptime in microseconds (instead of milliseconds as with $ENGINE_UPTIME), the variable $KSP_TIMER will reach ist limit after after ca. 30 minutes due to ist 32 bit nature. By using reset_ksp_timer, the variable is reset to 0.

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

KSP Reference Manual Commands

set_controller()
set_controller(<controller>,<value>)
send a MIDI CC, pitchbend or channel pressure value <controller> this parameter sets the type and in the case of MIDI CCs the CC number: a number from 0 to 127 designates a MIDI CC number $VCC_PITCH_BEND indicates Pitchbend $VCC_MONO_AT indicates Channel Pressure (monophonic aftertouch) the value of the specified controller MIDI CC and channel pressure values go from 0 to 127 PitchBend values go from -8192 to 8191

<value>

Examples
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

Got a keyboard with no aftertouch? Press C1 instead.

See Also
ignore_controller $VCC_PITCH_BEND $VCC_MONO_AT

KSP Reference Manual Commands

set_rpn()/set_nrpn
set_rpn(<address>,<value>)
send a rpn or nrpn message <address> <value> the rpn or nrpn address (0 - 16383) the value of the rpn or nrpn message (0 - 16383)

Remarks
Currently, Kontakt cannot handle rpn on 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()

KSP Reference Manual Commands

set_event_mark()
set_event_mark(<ID-number>,<bit-mark>
assign the specified event to a specific event group <ID-number> <bit-mark> the ID number of the event to be grouped here you can enter one of 28 marks from $MARK_1 to $MARK_28 which is addressed to the event. You can also address 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, since 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() $EVENT_ID $ALL_EVENTS $MARK_1 $MARK_28

KSP Reference Manual Commands

set_event_par()
set_event_par(<ID-number>,<parameter>,<value>)
assign a parameter to a specific event <ID-number> <parameter> the ID number of the event 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 note event: $EVENT_PAR_VOLUME $EVENT_PAR_PAN $EVENT_PAR_TUNE $EVENT_PAR_NOTE $EVENT_PAR_VELOCITY the value of the event parameter

<value>

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)

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

KSP Reference Manual Commands

wait()
wait(<wait-time>)
pauses the callback for the specified time in microseconds

Remarks
wait() stops the callback at the position in the script for the specified time. In other words, it freezes the callback (although other callbacks can be accessed or processed). After the specified time period the callback continues.

Examples
on note ignore_event($EVENT_ID) wait($DURATION_BAR - $DISTANCE_BAR_START) play_note($EVENT_NOTE,$EVENT_VELOCITY,0,-1) end on

quantize all notes to the downbeat of the next measure

KSP Reference Manual Built-in Variables & Constants

Built-in Variables & Constants

$ALL_GROUPS $ALL_EVENTS

addresses all groups in a disallow_group() and allow_group() function

addresses all events in functions which deal with a event ID number

Bit Mark Constants

bit mark of an event group, to be used with by_marks() $MARK_1 $MARK_2 $MARK_28

%CC[<controller-number>] $CC_NUM

current controller value for the specified controller.

controller number of the controller which triggered the callback

%CC_TOUCHED[<controller-number>] $CURRENT_SCRIPT_SLOT $DISTANCE_BAR_START

1 if the specified controller value has changed, 0 otherwise

the script slot of the current script (zero based, i.e. the first script slot is 0)

returns the time of a note on message in sec from the beginning of the current bar with respect to the current tempo

$DURATION_BAR

returns the duration in sec of one bar with respect to the current tempo

$DURATION_QUARTER

duration of a quarter note in microseconds, with respect to the current tempo. Also available: $DURATION_EIGHTH $DURATION_SIXTEENTH $DURATION_QUARTER_TRIPLET $DURATION_EIGHTH_TRIPLET $DURATION_SIXTEENTH_TRIPLET

$ENGINE_UPTIME

Returns the time period in milliseconds (not microseconds) that has passed since the start of Kontakt 90

KSP Reference Manual Built-in Variables & Constants

$EVENT_ID

unique ID number of the event which triggered the callback

$EVENT_NOTE

note number of the event which triggered the callback

$EVENT_VELOCITY

velocity of the note which triggered the callback

Event Parameter Constants

event parameters to be used with set_event_par() and get_event_par() $EVENT_PAR_0 $EVENT_PAR_1 $EVENT_PAR_2 $EVENT_PAR_3 $EVENT_PAR_VOLUME $EVENT_PAR_PAN $EVENT_PAR_TUNE $EVENT_PAR_NOTE $EVENT_PAR_VELOCITY To be used with set_event_par_arr(): $EVENT_PAR_ALLOW_GROUP To be used with get_event_par(): $EVENT_PAR_SOURCE (-1 if event originates from outside, otherwise slot number 0 - 4)

Event Status Constants

$EVENT_STATUS_INACTIVE $EVENT_STATUS_NOTE_QUEUE $EVENT_STATUS_MIDI_QUEUE

%GROUPS_AFFECTED

an array with the group indices of those groups that are affected by the current Note On or Note Off events

%GROUPS_SELECTED

an array with each array index pointing to the group with the same index. If a group is selected for editing the corresponding array index contains a 1, otherwise 0

Hide Part Constants

to be used with hide_part() $HIDE_PART_BG {Background of knobs, labels, value edits and tables} $HIDE_PART_VALUE {value of knobs} $HIDE_PART_TITLE {title of knobs} $HIDE_PART_MOD_LIGHT {mod ring light of knobs} $HIDE_PART_MOD_NOTHING {Show all} $HIDE_WHOLE_CONTROL 91

KSP Reference Manual Built-in Variables & Constants

%KEY_DOWN[<note-number>]

array which contains the current state of all keys. 1 if the key is held, 0 otherwise

%KEY_DOWN_OCT[<octave-number>] Knob Unit Mark Constants

to be used with set_knob_unit() $KNOB_UNIT_NONE $KNOB_UNIT_DB $KNOB_UNIT_HZ $KNOB_UNIT_PERCENT $KNOB_UNIT_MS $KNOB_UNIT_ST $KNOB_UNIT_OCT

1 if a note independently of the octave is held, 0 otherwise

$KSP_TIMER

Returns the time period in microseconds that has passed since the start of Kontakt. Can be reset with reset_ksp_timer

%NOTE_DURATION[<note-number>] $NOTE_HELD

note length since note-start in sec for each key

1 if the key which triggered the callback is still held, 0 otherwise

$NUM_GROUPS

total amount of groups in an instrument

$NUM_OUTPUT_CHANNEL $NUM_ZONES

total amount of output channels of the respective Kontakt Multi (not counting Aux channels)

total amount of zones in an instrument

$PLAYED_VOICES_INST

the amount of played voices of the respective instrument

$PLAYED_VOICES_TOTAL $REF_GROUP_IDX $RPN_ADDRESS

the amount of played voices all instruments

group index number of the currently viewed group

the parameter number of a received rpn/nrpn message (0 16383)

KSP Reference Manual Built-in Variables & Constants

$RPN_VALUE

the value of a received rpn or nrpn message (0 16383)

$SIGNATURE_NUM

nominator of the current time signature

$SIGNATURE_DENOM $VCC_MONO_AT

denominator of the current time signature

the value of the virtual cc controller for mono aftertouch (channel pressure)

$VCC_PITCH_BEND

the value of the virtual cc controller for pitch bend

KSP Reference Manual Control Parameter Variables

Control Parameter Variables

$CONTROL_PAR_NONE

nothing will be applied to the control

$CONTROL_PAR_POS_X

sets the horizontal position in pixel

$CONTROL_PAR_POS_Y

sets the vertical position in pixel

$CONTROL_PAR_GRID_X $CONTROL_PAR_GRID_Y $CONTROL_PAR_WIDTH

sets the horizontal position in grids

sets the vertical position in grids

sets the width of the control in pixel

$CONTROL_PAR_HEIGHT

sets the height of the control in pixel

$CONTROL_PAR_GRID_WIDTH
sets the width of the control in grids

$CONTROL_PAR_GRID_HEIGHT
sets the height of the control in grids

$CONTROL_PAR_HIDE
sets the hide status

$CONTROL_PAR_MIN_VALUE
sets the minimum value

$CONTROL_PAR_MAX_VALUE
sets the maximum value

$CONTROL_PAR_VALUE
sets the value

$CONTROL_PAR_DEFAULT_VALUE
sets the default value

KSP Reference Manual Control Parameter Variables

$CONTROL_PAR_HELP

sets the help text which is displayed in the info pane when hovering the control

$CONTROL_PAR_PICTURE
sets the picture name

$CONTROL_PAR_TEXT

sets the control text, similar to set_text()

$CONTROL_PAR_TEXTLINE $CONTROL_PAR_LABEL $CONTROL_PAR_UNIT

adds a text line, similar to add_text_line()

sets the knob label, similar to set_knob_label()

sets the knob unit, similar to set_knob_unit()

$CONTROL_PAR_MOUSE_BEHAVIOUR $CONTROL_PAR_PICTURE_STATE $CONTROL_PAR_FONT_TYPE

a value from -5000 to 5000, setting the move direction of a slider and its drag-scale

the picture state of the control for tables, value edits and labels

sets the font type. Only Kontakt 4 factory fonts can be used, the font itself is designated by a number (currently 0 to 24)

$CONTROL_PAR_TEXTPOS_Y

shifts the vertical position in pixels of text in buttons, menus, switches and labels

$CONTROL_PAR_TEXT_ALIGNMENT
The following values can be used: 0: left 1: centered 2: right

the text alignment in buttons, menus, switches and labels.

$CONTROL_PAR_SHOW_ARROWS
hide arrows of value edits: 0: arrows are hidden 1: arrows are shown

$CONTROL_PAR_BAR_COLOR

sets the color of the step bar in ui tables 95

KSP Reference Manual Control Parameter Variables

$CONTROL_PAR_ZERO_LINE_COLOR
sets the color of the middle line in ui tables

$INST_ICON_ID

the (fixed) ID of the instrument icon. It's possible to hide the instrument icon: set_control_par($INST_ICON_ID,$CONTROL_PAR_HIDE,$HIDE_WHOLE_CONTROL) It's also possible to load a different picture file for the instrument icon: set_control_par_str($INST_ICON_ID,$CONTROL_PAR_PICTURE,<file-name>)

KSP Reference Manual Engine Parameter Commands

Engine Parameter Commands get_engine_par()

get_engine_par(<parameter>,<group>,<slot>,<generic>)
return the value of a specific engine parameter <parameter> <group> <slot> specifies the engine parameter the index (zero based) of the group in which the specified parameter resides. If the specified parameter resides on an Instrument level, enter -1. the slot index (zero based) of the specified parameter (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>) <generic> For all other applications, set this parameter to -1. this parameter applies to instrument effects and to internal modulators. For instrument effects, this parameter distinguishes between 1: Insert Effect 0: Send Effect 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,"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

KSP Reference Manual Engine Parameter Commands 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 slots of send effects

KSP Reference Manual Engine Parameter Commands

get_engine_par_disp()
get_engine_par_disp(<parameter>,<group>,<slot>,<generic>)
return the displayed value of a specific engine parameter <parameter> <group> <slot> specifies the engine parameter the index (zero based) of the group in which the specified parameter resides. If the specified parameter resides on an Instrument level, enter -1. the slot index (zero based) of the specified parameter (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>) <generic> For all other applications, set this parameter to -1. this parameter applies to instrument effects and to internal modulators. For instrument effects, this parameter distinguishes between 1: Insert Effect 0: Send Effect 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) & ": " & ... 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

KSP Reference Manual Engine Parameter Commands

get_folder()
get_folder(<path-variable>)
return the path specified with the built-in path variable <path-variable> the following path variables are available: $GET_FOLDER_LIBRARY_DIR the library directory (as set in Options/Load-Import) $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.

Examples
on init message(get_folder($GET_FOLDER_LIBRARY_DIR)) end on

where did I put my factory library?

KSP Reference Manual Engine Parameter Commands

load_ir_sample()
load_ir_sample(<file-name>,<slot>,<generic>)
load an impulse response sample into Kontakt's convolution effect <file-name> the file name of the sample, specified with a relative path If no path is specified, the command will look for the specified sample inside the folder called "ir_samples". This folder is located in the user folder: (OS X) /Users/<username>/Documents/Native Instruments/Kontakt 4 (Windows) C:\Users\<username>\Documents\Native Instruments\Kontakt 4\ Please note that sub directories inside the "ir_samples" folder will not be scanned. <slot> <generic> the slot index of the convolution effect (zero-based) specifies wether the convolution effect is used as an 1: Insert Effect 0: Send Effect

Examples
on init declare ui_button $Load end on on ui_control ($Load) load_ir_sample(get_folder($GET_FOLDER_FACTORY_DIR) & ... "presets/effects/convolution/<<<K4IR.nkx>>>/K4 IR Samples/Concert Hall A.wav"... ,0,0) $Load := 0 end on

load a factory IR sample into a convolution send effect in the first slot

KSP Reference Manual Engine Parameter Commands

set_engine_par()
set_engine_par(<parameter>,<value>,<group>,<slot>,<generic>)
control automatable Kontakt parameters and bypass buttons <parameter> <value> <group> <slot> the parameter to be controlled with a built-in variable like $ENGINE_PAR_CUTOFF The value to which the specified parameter is set. The range of values is always 0 to 1000000. the index (zero based) of the group in which the specified parameter resides. If the specified parameter resides on an Instrument level, enter -1. the slot index (zero based) of the specified parameter (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>) <generic> For all other applications, set this parameter to -1. this parameter applies to instrument effects and to internal modulators. For instrument effects, this parameter distinguishes between 1: Insert Effect 0: Send Effect 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

102

KSP Reference Manual Engine Parameter Commands

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 $Attack (0,1000000,1000000) declare $vol_env_idx $vol_env_idx := find_mod(0,"VOL_ENV") end on on ui_control ($Attack) set_engine_par($ENGINE_PAR_ATTACK,$Attack,0,$vol_env_idx,-1) end on

controlling attack time of the volume envelope of the first group. Note: the envelope has been manually renamed to "VOL_ENV"
on init declare ui_knob $Velocity (0,1000000,1000000) declare $mod_idx $mod_idx := find_mod(0,"VEL_VOLUME") end on on ui_control ($Velocity) set_engine_par($ENGINE_PAR_MOD_TARGET_INTENSITY,... $Velocity,0,$mod_idx,-1) end on

controlling the velocity to volume modulation intensity of the first group. Note: the default name of the modulation assignment ("VEL_VOLUME") has been used.
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 the filter envelope hass been manually renamed to "FILTER_ENV"

103

KSP Reference Manual Engine Parameter Variables

Engine Parameter Variables Instrument, Source and Amp Module

$ENGINE_PAR_VOLUME
instrument volume

$ENGINE_PAR_PAN
instrument panorama

$ENGINE_PAR_TUNE
instrument tuning

Source Module
$ENGINE_PAR_TUNE $ENGINE_PAR_SMOOTH $ENGINE_PAR_FORMANT $ENGINE_PAR_SPEED $ENGINE_PAR_GRAIN_LENGTH $ENGINE_PAR_SLICE_ATTACK $ENGINE_PAR_SLICE_RELEASE $ENGINE_PAR_TRANSIENT_SIZE

Amp Module
$ENGINE_PAR_VOLUME $ENGINE_PAR_PAN $ENGINE_PAR_OUTPUT_CHANNEL

104

KSP Reference Manual Engine Parameter Variables

Filter and EQ
$ENGINE_PAR_CUTOFF
cutoff frequency of all filters

$ENGINE_PAR_RESONANCE
resonance of all filters

$ENGINE_PAR_EFFECT_BYPASS
bypass button of all filters/EQ

3x2 Versatile
$ENGINE_PAR_FILTER_SHIFTB $ENGINE_PAR_FILTER_SHIFTC $ENGINE_PAR_FILTER_RESB $ENGINE_PAR_FILTER_RESC $ENGINE_PAR_FILTER_TYPEA $ENGINE_PAR_FILTER_TYPEB $ENGINE_PAR_FILTER_TYPEC $ENGINE_PAR_FILTER_BYPA $ENGINE_PAR_FILTER_BYPB $ENGINE_PAR_FILTER_BYPC $ENGINE_PAR_FILTER_GAIN

EQ
$ENGINE_PAR_FREQ1 $ENGINE_PAR_BW1 $ENGINE_PAR_GAIN1 $ENGINE_PAR_FREQ2 $ENGINE_PAR_BW2 $ENGINE_PAR_GAIN2 $ENGINE_PAR_FREQ3 $ENGINE_PAR_BW3 $ENGINE_PAR_GAIN3

105

KSP Reference Manual Engine Parameter Variables

Insert Effects
$ENGINE_PAR_EFFECT_BYPASS
bypass button of all insert effects

$ENGINE_PAR_INSERT_EFFECT_OUTPUT_GAIN
output gain of all insert effects

Compressor
$ENGINE_PAR_THRESHOLD $ENGINE_PAR_RATIO $ENGINE_PAR_COMP_ATTACK $ENGINE_PAR_COMP_DECAY

Limiter
$ENGINE_PAR_LIM_IN_GAIN $ENGINE_PAR_LIM_RELEASE

Surround Panner
$ENGINE_PAR_SP_OFFSET_DISTANCE $ENGINE_PAR_SP_OFFSET_AZIMUTH $ENGINE_PAR_SP_OFFSET_X $ENGINE_PAR_SP_OFFSET_Y $ENGINE_PAR_SP_LFE_VOLUME $ENGINE_PAR_SP_SIZE $ENGINE_PAR_SP_DIVERGENCE

Saturation
$ENGINE_PAR_SHAPE

Lo-Fi
$ENGINE_PAR_BITS $ENGINE_PAR_FREQUENCY $ENGINE_PAR_NOISELEVEL $ENGINE_PAR_NOISECOLOR

Stereo Modeller
$ENGINE_PAR_STEREO $ENGINE_PAR_STEREO_PAN

Distortion
$ENGINE_PAR_DRIVE $ENGINE_PAR_DAMPING

Send Levels
$ENGINE_PAR_SENDLEVEL_0 $ENGINE_PAR_SENDLEVEL_1 $ENGINE_PAR_SENDLEVEL_2 <...> $ENGINE_PAR_SENDLEVEL_7 106

KSP Reference Manual Engine Parameter Variables

Skreamer
$ENGINE_PAR_SK_TONE $ENGINE_PAR_SK_DRIVE $ENGINE_PAR_SK_BASS $ENGINE_PAR_SK_BRIGHT $ENGINE_PAR_SK_MIX

Rotator
$ENGINE_PAR_RT_SPEED $ENGINE_PAR_RT_BALANCE $ENGINE_PAR_RT_ACCEL_HI $ENGINE_PAR_RT_ACCEL_LO $ENGINE_PAR_RT_DISTANCE $ENGINE_PAR_RT_MIX

Twang
$ENGINE_PAR_TW_VOLUME $ENGINE_PAR_TW_TREBLE $ENGINE_PAR_TW_MID $ENGINE_PAR_TW_BASS

Cabinet
$ENGINE_PAR_CB_SIZE $ENGINE_PAR_CB_AIR $ENGINE_PAR_CB_TREBLE $ENGINE_PAR_CB_BASS $ENGINE_PAR_CABINET_TYPE

AET Filter Module

$ENGINE_PAR_EXP_FILTER_MORPH $ENGINE_PAR_EXP_FILTER_AMOUNT

107

KSP Reference Manual Engine Parameter Variables

Send Effects
$ENGINE_PAR_SEND_EFFECT_BYPASS
bypass button of all send effects

$ENGINE_PAR_SEND_EFFECT_DRY_LEVEL

dry amount of send effects when used in an insert chain

$ENGINE_PAR_SEND_EFFECT_OUTPUT_GAIN

when used with send effects, this controls either: wet amount of send effects when used in an insert chain return amount of send effects when used in a send chain

Phaser

$ENGINE_PAR_PH_DEPTH $ENGINE_PAR_PH_SPEED $ENGINE_PAR_PH_PHASE $ENGINE_PAR_PH_FEEDBACK

Flanger

$ENGINE_PAR_FL_DEPTH $ENGINE_PAR_FL_SPEED $ENGINE_PAR_FL_PHASE $ENGINE_PAR_FL_FEEDBACK $ENGINE_PAR_FL_COLOR

Chorus

$ENGINE_PAR_CH_DEPTH $ENGINE_PAR_CH_SPEED $ENGINE_PAR_CH_PHASE

Reverb

$ENGINE_PAR_RV_PREDELAY $ENGINE_PAR_RV_SIZE $ENGINE_PAR_RV_COLOUR $ENGINE_PAR_RV_STEREO $ENGINE_PAR_RV_DAMPING

Delay

$ENGINE_PAR_DL_TIME $ENGINE_PAR_DL_DAMPING $ENGINE_PAR_DL_PAN $ENGINE_PAR_DL_FEEDBACK

Convolution
$ENGINE_PAR_IRC_PREDELAY $ENGINE_PAR_IRC_LENGTH_RATIO_ER $ENGINE_PAR_IRC_FREQ_LOWPASS_ER $ENGINE_PAR_IRC_FREQ_HIGHPASS_ER $ENGINE_PAR_IRC_LENGTH_RATIO_LR $ENGINE_PAR_IRC_FREQ_LOWPASS_LR $ENGINE_PAR_IRC_FREQ_HIGHPASS_LR 108

KSP Reference Manual Engine Parameter Variables

Gainer
$ENGINE_PAR_GN_GAIN

109

KSP Reference Manual Engine Parameter Variables

Modulation
$ENGINE_PAR_EXTMOD_INTENSITY $ENGINE_PAR_INTMOD_INTENSITY $ENGINE_PAR_INTMOD_BYPASS AHDSR
$ENGINE_PAR_ATK_CURVE $ENGINE_PAR_ATTACK $ENGINE_PAR_HOLD $ENGINE_PAR_DECAY $ENGINE_PAR_SUSTAIN $ENGINE_PAR_RELEASE the intensity slider of an external modulation assignment (e.g. velocity, pitchbend, aftertouch, midi CC)

the intensity slider of an internal modulation assignment (e.g. AHDSR envelope, LFO)

the bypass button of an internal modulation assignment (e.g. AHDSR envelope, LFO)

DBD
$ENGINE_PAR_DECAY1 $ENGINE_PAR_BREAK $ENGINE_PAR_DECAY2

LFO
For all LFOs: $ENGINE_PAR_INTMOD_FREQUENCY $ENGINE_PAR_LFO_DELAY For Rectangle: $ENGINE_PAR_INTMOD_PULSEWIDTH For Multi: $ENGINE_PAR_LFO_SINE $ENGINE_PAR_LFO_RECT $ENGINE_PAR_LFO_TRI $ENGINE_PAR_LFO_SAW $ENGINE_PAR_LFO_RAND

Glide
$ENGINE_PAR_GLIDE_COEF

110

KSP Reference Manual Engine Parameter Variables

Module Status Retrieval

$ENGINE_PAR_EFFECT_TYPE
used to query the type of a group insert or instrument insert effect, can be any of the following: $EFFECT_TYPE_FILTER $EFFECT_TYPE_COMPRESSOR $EFFECT_TYPE_LIMITER $EFFECT_TYPE_INVERTER $EFFECT_TYPE_SURROUND_PANNER $EFFECT_TYPE_SHAPER {Saturation} $EFFECT_TYPE_LOFI $EFFECT_TYPE_STEREO {Stereo Modeller} $EFFECT_TYPE_DISTORTION $EFFECT_TYPE_SEND_LEVELS $EFFECT_TYPE_PHASER $EFFECT_TYPE_CHORUS $EFFECT_TYPE_FLANGER $EFFECT_TYPE_REVERB $EFFECT_TYPE_DELAY $EFFECT_TYPE_IRC {Convolution} $EFFECT_TYPE_GAINER $EFFECT_TYPE_SKREAMER $EFFECT_TYPE_ROTATOR $EFFECT_TYPE_TWANG $EFFECT_TYPE_CABINET $EFFECT_TYPE_AET_FILTER $EFFECT_TYPE_NONE {empty slot}

$ENGINE_PAR_SEND_EFFECT_TYPE
$EFFECT_TYPE_PHASER $EFFECT_TYPE_CHORUS $EFFECT_TYPE_FLANGER $EFFECT_TYPE_REVERB $EFFECT_TYPE_DELAY $EFFECT_TYPE_IRC {Convolution} $EFFECT_TYPE_GAINER $EFFECT_TYPE_NONE {empty slot}

used to query the type of a send effect, can be any of the following:

111

KSP Reference Manual Engine Parameter Variables

Group Start Options Query

Group Start Options Variables
$ENGINE_PAR_START_CRITERIA_MODE $ENGINE_PAR_START_CRITERIA_KEY_MIN $ENGINE_PAR_START_CRITERIA_KEY_MAX $ENGINE_PAR_START_CRITERIA_CONTROLLER $ENGINE_PAR_START_CRITERIA_CC_MIN $ENGINE_PAR_START_CRITERIA_CC_MAX $ENGINE_PAR_START_CRITERIA_CYCLE_CLASS $ENGINE_PAR_START_CRITERIA_ZONE_IDX $ENGINE_PAR_START_CRITERIA_SLICE_IDX $ENGINE_PAR_START_CRITERIA_SEQ_ONLY $ENGINE_PAR_START_CRITERIA_NEXT_CRIT $ENGINE_PAR_START_CRITERIA_MODE can return one of the following values: $START_CRITERIA_NONE $START_CRITERIA_ON_KEY $START_CRITERIA_ON_CONTROLLER $START_CRITERIA_CYCLE_ROUND_ROBIN $START_CRITERIA_CYCLE_RANDOM $START_CRITERIA_SLICE_TRIGGER $ENGINE_PAR_START_CRITERIA_NEXT_CRIT can return one of the following values: $START_CRITERIA_AND_NEXT $START_CRITERIA_AND_NOT_NEXT $START_CRITERIA_OR_NEXT

112

KSP Reference Manual Engine Parameter Variables

$ENGINE_PAR_EFFECT_SUBTYPE
$FILTER_TYPE_LP1POLE $FILTER_TYPE_HP1POLE $FILTER_TYPE_BP2POLE $FILTER_TYPE_LP2POLE $FILTER_TYPE_HP2POLE $FILTER_TYPE_LP4POLE $FILTER_TYPE_HP4POLE $FILTER_TYPE_BP4POLE $FILTER_TYPE_BR4POLE $FILTER_TYPE_LP6POLE $FILTER_TYPE_PHASER $FILTER_TYPE_VOWELA $FILTER_TYPE_VOWELB $FILTER_TYPE_PRO52 $FILTER_TYPE_LADDER $FILTER_TYPE_VERSATILE $FILTER_TYPE_EQ1BAND $FILTER_TYPE_EQ2BAND $FILTER_TYPE_EQ3BAND

used to query the type of filter/EQ, can be any of the following:

$ENGINE_PAR_INTMOD_TYPE
$EFFECT_TYPE_ENVELOPE $EFFECT_TYPE_LFO $EFFECT_TYPE_STEPMOD $EFFECT_TYPE_ENV_FOLLOW $EFFECT_TYPE_GLIDE

used to query the type of internal modulators, can be any of the following:

$ENGINE_PAR_INTMOD_SUBTYPE
$ENV_TYPE_AHDSR $ENV_TYPE_FLEX $ENV_TYPE_DBD $LFO_TYPE_RECTANGLE $LFO_TYPE_TRIANGLE $LFO_TYPE_SAWTOOTH $LFO_TYPE_RANDO$LFO_TYPE_MULTI

used to query the sub type of envelopes and LFOs, can be any of the following:

113

KSP Reference Manual Advanced Concepts

Advanced Concepts Preprocessor & System Scripts

SET_CONDITION(<condition-symbol>)
define a symbol to be used as a condition

RESET_CONDITION(<condition-symbol>)
delete a definition

USE_CODE_IF(<condition-symbol>) ... END_USE_CODE

interpret code when <condition> is defined

USE_CODE_IF_NOT(<condition-symbol>) ... END_USE_CODE

interpret code when <condition> is not defined

NO_SYS_SCRIPT_GROUP_START

condition; if defined with SET_CONDITION(), the system script which handles all group start options will be bypassed

NO_SYS_SCRIPT_PEDAL

condition; if defined with SET_CONDITION(), the system script which sustains notes when CC# 64 is received will be bypassed

NO_SYS_SCRIPT_RLS_TRIG

condition; if defined with SET_CONDITION(), the system script which triggers samples upon the release of a key is bypassed

reset_rls_trig_counter(<note>)

resets the release trigger counter (used by the release trigger system script)

will_never_terminate(<event-id>)

tells the script engine that this event will never be finished (used by the release trigger system script)

114

KSP Reference Manual Advanced Concepts

Examples
A preprocessor is used to exclude code elements from interpretation. Here's how it works: USE_CODE_IF(<condition>) ... END_USE_CODE or USE_CODE_IF_NOT(<condition>) ... END_USE_CODE <condition> refers to a symbolic name which consists of alphanumeric symbols, preceded by a letter. You could write for example: on note {do something general} $var := 5 {do some conditional code} USE_CODE_IF_NOT(dont_do_sequencer) while ($count > 0) play_note() end while END_USE_CODE end on What's happening here? Only if the symbol dont_do_sequencer is not defined, the code between USE_ and END_USE will be processed. If the symbol were to be found, the code would not be passed on to the parser; it is as if the code was never written (therefore it does not utilize any CPU power). You can define symbols with SET_CONDITION(<condition symbol>) and delete the definition with RESET_CONDITION(<condition symbol>) All commands will be interpreted before the script is running, i.e. by using USE_CODE_ the code might get stalled before it is passed to the script engine. That means, SET_CONDITION and RESET_CONDITION are actually not true commands: they cannot be utilized in if()...end if statements; also a wait() statement before those commands is useless. Each SET_CONDITION and RESET_CONDITION will be executed before something else happens. All defined symbols are passed on to following scripts, i.e. if script 3 contains conditional code, you can turn it on or off in script 1 or 2. You can use conditional code to bypass system scripts. There are two built-in symbols: NO_SYS_SCRIPT_PEDAL NO_SYS_SCRIPT_RLS_TRIG

115

KSP Reference Manual Advanced Concepts If you define one of those symbols with SET_CONDITION(), the corresponding part of the system scripts will be bypassed. For clarity reasons, those definitions should always take place in the init callback. on init {we want to do our own release triggering} SET_CONDITION(NO_SYS_SCRIPT_RLS_TRIG) end on on release {do something custom here} end on

116

KSP Reference Manual Advanced Concepts

PGS
It is now possible to send and receive values from one script to another, discarding the usual left-toright order by using the new Program Global Storage (PGS) commands. PGS is a dynamic memory which can be read/written by any script. Here are the commands:

PGS commands
pgs_create_key(<key-id>,<size>) pgs_key_exists(<key-id>) pgs_set_key_val(<key-id>,<index>,<value>) pgs_get_key_val(<key-id>,<index>) <key-id> is something similar to a variable name, it can only contain letters and numbers and must start with a number. It might be a good idea to always write them in capitals to emphasize their unique status. Here's an example, insert this script into any slot:
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 $Just_Do_It end on on ui_control($Just_Do_It) {writes 70 into the first and only memory location of FIRST_KEY} pgs_set_key_val(FIRST_KEY, 0, 70)
{writes 50 into the first and 60 into the last memory location of NEXT_KEY}

pgs_set_key_val(NEXT_KEY, 0, 50) pgs_set_key_val(NEXT_KEY, 127, 60) end on

and insert the following script into any other slot:

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) {in this case 70} %Next[0] := pgs_get_key_val(NEXT_KEY,0) {in this case 50} %Next[127] := pgs_get_key_val(NEXT_KEY,127) {in this case 60} end if end on

As illustrated above, there is also a new callback type which is executed whenever a set_key command has been executed:

on pgs_changed

callback type, executed whenever any pgs_set_key_val() is executed in any script It is possible to have as many keys as you want, however each key can only have up to 256 elements. 117

KSP Reference Manual Advanced Concepts

Slice Functions
num_slices(<group-index>)
returns the number of slices in the specified group

slice_length(<group-index>,<slice-index>) slice_start(<group-index>,<slice-index>)

return the length of the specified slice in the specified group with respect to the current tempo

return the absolute start point of the specified slice, independent of the current tempo

slice_idx_loop_start(<group-index>,<loop-index>)
return the index number of the slice at the loop start

slice_idx_loop_end(<group-index>,<loop-index>)
return the index number of the slice at the loop end

slice_loop_count(<group-index>,<loop-index>)
return the loop count of the specified loop

dont_use_machine_mode(<ID-number>)
play the specified event in sampler mode

118

KSP Reference Manual Multi Script

Multi Script Introduction

The multi script utilizes basically the same KSP syntax as the instrument scripts. Here are the main differences: the multi script works on a pure MIDI event basis, i.e. you're working with raw MIDI data there are no "on note", "on release" and "on controller" callbacks every MIDI event triggers the "on midi_in" callback there are various built-in variables for the respective MIDI bytes

The new multi script tab is accessed by clicking on the "KSP" button in the multi header. Just like instrument scripts are saved with the instrument, multi scripts are saved with the multi. GUIwise everything's identical with the instrument script except for the height, it's limited to 3 grid spaces (just like the instrument scripts in Kontakt 2/3). The scripts are stored in a folder called "multiscripts", which resides next to the already existing "scripts" folder, that is inside the "presets" folder: /Native Instruments/Kontakt 4/presets/multiscripts The multi script has only two callback types, the on midi_in callback and the various on ui_control callbacks. Each MIDI event like Note, Controller, Program Change etc. is triggering the midi_in callback. It is very important to understand the different internal structure of the event processing in the multi script opposed to the instrument script. On the instrument level, you can retrieve the event IDs of notes only, that is, $EVENT_ID only works in the on note and on release callback. On the multi level, any incoming MIDI event has a unique ID which can be retrieved with $EVENT_ID. This means, $EVENT_ID can be a note event, a controller message, a program change command etc. This brings us to the usage of change_note(), change_velo() etc. commands. Since $EVENT_ID does not necessarily refer to a note event, this commands will not work in the multi script (there will be a command coming soon which enables you to change the MIDI bytes of events without having to ignore them first). And most important of all, remember that the multi script is really nothing more than a MIDI processor (where as the instrument script is an event processor). A note event in the instrument script is bound to a voice, whereas MIDI events from the multi script are "translated' into note events on the instrument level. This simply means, that play_note(), change_tune() etc. don't work in the multi script. Please note that you should be familiar with the basic structure of MIDI messages when working with the multi script.

119

KSP Reference Manual Multi Script

ignore_midi
ignores MIDI events

ignore_midi

Remarks
Like ignore_event(), ignore_midi is a very "strong" command. Keep in mind that ignore_midi will ignore all incoming MIDI events. If you simply want to change the MIDI channel and/or any of the MIDI bytes, you can also use set_event_par().

Examples
on midi_in if ($MIDI_COMMAND = $MIDI_COMMAND_NOTE_ON and $MIDI_BYTE_2 > 0) ignore_midi end if if ($MIDI_COMMAND = $MIDI_COMMAND_NOTE_OFF or ... ($MIDI_COMMAND = $MIDI_COMMAND_NOTE_ON and $MIDI_BYTE_2 = 0)) ignore_midi end if end on

ignoring note on and note off messages. Note that some keyboards use a note on command with a velocity of 0 to designate a note off command.

KSP Reference Manual Multi Script

on midi_in
on midi_in

midi callback, triggered by every incoming MIDI event

Examples
on midi_in if ($MIDI_COMMAND = $MIDI_COMMAND_NOTE_ON and $MIDI_BYTE_2 > 0) message ("Note On") end if if ($MIDI_COMMAND = $MIDI_COMMAND_NOTE_ON and $MIDI_BYTE_2 = 0) message ("Note Off") end if if ($MIDI_COMMAND = $MIDI_COMMAND_NOTE_OFF) message ("Note Off") end if if ($MIDI_COMMAND = $MIDI_COMMAND_CC) message ("Controller") end if if ($MIDI_COMMAND = $MIDI_COMMAND_PITCH_BEND) message ("Pitch Bend") end if if ($MIDI_COMMAND = $MIDI_COMMAND_MONO_AT) message ("Channel Pressure") end if if ($MIDI_COMMAND = $MIDI_COMMAND_POLY_AT) message ("Poly Pressure") end if if ($MIDI_COMMAND = $MIDI_COMMAND_PROGRAM_CHANGE) message ("Program Change") end if end on

monitoring various MIDI data

KSP Reference Manual Multi Script

set_midi()
create any type of MIDI event

set_midi(<channel>,<command>,<byte-1>, <byte-2>)

Remarks
If you simply want to change the MIDI channel and/or any of the MIDI bytes, you can also use set_event_par().

Examples
on midi_in if ($MIDI_COMMAND = $MIDI_COMMAND_NOTE_ON and $MIDI_BYTE_2 > 0) set_midi ($MIDI_CHANNEL,$MIDI_COMMAND_NOTE_ON,$MIDI_BYTE_1+4,$MIDI_BYTE_2) set_midi ($MIDI_CHANNEL,$MIDI_COMMAND_NOTE_ON,$MIDI_BYTE_1+7,$MIDI_BYTE_2) end if if ($MIDI_COMMAND = $MIDI_COMMAND_NOTE_OFF or ... ($MIDI_COMMAND = $MIDI_COMMAND_NOTE_ON and $MIDI_BYTE_2 = 0)) set_midi ($MIDI_CHANNEL,$MIDI_COMMAND_NOTE_ON,$MIDI_BYTE_1+4,0) set_midi ($MIDI_CHANNEL,$MIDI_COMMAND_NOTE_ON,$MIDI_BYTE_1+7,0) end if end on

a simple harmonizer notice that you have to supply the correct note off commands as well

See Also
set_event_par() $EVENT_PAR_MIDI_CHANNEL $EVENT_PAR_MIDI_COMMAND $EVENT_PAR_MIDI_BYTE_1 $EVENT_PAR_MIDI_BYTE_2

122

KSP Reference Manual Multi Script

Multi Script Variables

$MIDI_CHANNEL
the MIDI channel of the received MIDI event. Since Kontakt can handle four different MIDI ports, this number can go from 0 - 63 (four ports x 16 MIDI channels)

$MIDI_COMMAND

the command type like Note, CC, Program Change etc. of the received MIDI event. There are various constants for this variable (see below)

$MIDI_BYTE_1 $MIDI_BYTE_2

the two MIDI bytes of the MIDI message (always in the range 0-127)

$MIDI_COMMAND_NOTE_ON

$MIDI_BYTE_1 = note number $MIDI_BYTE_2 = velocity Note: a velocity value of 0 equals a note off command

$MIDI_COMMAND_NOTE_OFF
$MIDI_BYTE_1 = note number $MIDI_BYTE_2 = release velocity

$MIDI_COMMAND_POLY_AT

$MIDI_BYTE_1 = note number $MIDI_BYTE_2 = polyphonic key pressure value

$MIDI_COMMAND_CC

$MIDI_BYTE_1 = controller number $MIDI_BYTE_2 = controller value

$MIDI_COMMAND_PROGRAM_CHANGE
$MIDI_BYTE_1 = program number $MIDI_BYTE_2 = not used

$MIDI_COMMAND_MONO_AT

$MIDI_BYTE_1 = channel pressure value $MIDI_BYTE_2 = not used

$MIDI_COMMAND_PITCH_BEND
$MIDI_BYTE_1 = LSB value $MIDI_BYTE_2 = MSB value

$MIDI_COMMAND_RPN/$MIDI_COMMAND_NRPN
$MIDI_BYTE_1 = rpn/nrpn address $MIDI_BYTE_2 = rpn/nrpn value

123

KSP Reference Manual Multi Script

Event Parameter Constants

event parameters to be used with set_event_par() and get_event_par() $EVENT_PAR_MIDI_CHANNEL $EVENT_PAR_MIDI_COMMAND $EVENT_PAR_MIDI_BYTE_1 $EVENT_PAR_MIDI_BYTE_2

124

KSP Reference Manual Version History

Version History Kontakt 4.0.2

New Features new engine parameter to set the group output channel: $ENGINE_PAR_OUTPUT_CHANNEL new built-in variable: $NUM_OUTPUT_CHANNELS new function: output_channel_name() new built-in variable: $CURRENT_SCRIPT_SLOT new built-in variable: $EVENT_PAR_SOURCE Improved Features The load_ir_sample() command now also accepts single file names for loading IR samples into KONTAKT's convolution effect, i.e. without a path designation. In this case the sample is expected to reside in the folder called "ir_samples" inside the user folder.

Kontakt 4
New Features Multiscript New id-based User Interface Controls system: set_control_par(), get_control_par()and get_ui_id() Pixel exact positioning and resizing of UI controls Skinning of UI controls New UI controls: switch and slider Assign colors to Kontakt's keyboard by using set_key_color() new timing variable: $KSP_TIMER (in microseconds) new path variable: $GET_FOLDER_FACTORY_DIR new hide constants: $HIDE_PART_NOTHING & $HIDE_WHOLE_CONTROL link scripts to text files Improved Features New array size limit: 32768 Retrieve and set event parameters for tuning, volume and pan of an event ($EVENT_PAR_TUNE, $EVENT_PAR_VOL and $EVENT_PAR_PAN) larger performance view size, set_ui_height(), set_script_title() beginning underscores from Kontakt 2/3 commands like _set_engine_par() can be omitted, i.e. you can write set_engine_par() instead

125

KSP Reference Manual Version History

Kontakt 3.5
New Features Retrieve the status of a particular event: event_status() Hide specific parts of UI controls: hide_part() %GROUPS_SELECTED Improved Features Support for channel aftertouch: $VCC_MONO_AT New array size limit: 2048

Kontakt 3
New Features Offset for wallpaper graphic: _set_skin_offset() Program Global Storage (PGS) for inter-script communication _pgs_create_key() _pgs_key_exists() _pgs_set_key_val() _pgs_get_key_val() New callback type: on _pgs_changed Adressing modulators by name: find_mod() find_target() Change the number of displayed steps in a column: set_table_steps_shown() Info tags for UI controls: set_control_help() Improved Features All five performance views can now be displayed together

Kontakt 2.2
New Features New callback type: on ui_update New built-in variables for group based scripting $REF_GROUP_IDX %GROUPS_SELECTED Ability to create custom group start options: NO_SYS_SCRIPT_GROUP_START (+ various Group Start Options Variables) Retrieving the release trigger state of a group: $ENGINE_PAR_RELEASE_TRIGGER Default values for knobs: set_knob_defval()

126

KSP Reference Manual Version History

Kontakt 2.1.1
New Features Assign unit marks to knobs: set_knob_unit() Assign text strings to knobs: set_knob_label() Retrieve the knob display: _get_engine_par_disp()

Kontakt 2.1
New Features string arrays (! prefix) and string variables (@ prefix) engine parameter: _set_engine_par() loading IR samples: _load_ir_sample() Performance View: make_perfview rpn/nrpn implementation: on rpn & on nrpn $RPN_ADDRESS $RPN_VALUE msb() & lsb() set_rpn() & set_nrpn() event parameters: set_event_par() New built-in variables: $NUM_GROUPS $NUM_ZONES $VCC_PITCH_BEND $PLAYED_VOICES_TOTAL $PLAYED_VOICES_INST Improved Features possible to name UI controls with set_text() moving and hiding UI controls MIDI CCs generated by set_controller() can now also be used for automation (as well as modulation).

Kontakt 2
Initial release.

127

KSP Reference Manual Index

Index
! (string variable), 15 $ (constant), 11 $ (polyphonic variable), 12 $ (variable), 10 % (array), 13 @ (string variable), 14 abs(), 60 add_menu_item(), 32 add_text_line(), 33 allow_group(), 25 Arithmetic Operators, 19 array_equal(), 21 Bit Operators, 20 Boolean Operators, 19 by_marks(), 61 change_note(), 62 change_pan(), 63 change_tune(), 64 change_velo(), 65 change_vol(), 66 Control Statements, 16 dec(), 67 disallow_group(), 26 event_status(), 68 exit, 69 fade_in(), 70 fade_out(), 71 find_group(), 27 get_control_par(), 35 get_engine_par(), 97 get_engine_par_disp(), 99 get_event_par(), 72 get_event_par_arr(), 28 get_folder(), 100 get_ui_id(), 36 group_name(), 29 hide_part(), 34 ifelseend if, 16 ignore_controller, 73 ignore_event(), 74 ignore_midi, 120 inc(), 75 load_ir_sample(), 101 make_perfview, 37 make_persistent(), 77 message(), 78 move_control(), 38 move_control_px(), 39 msb(), 76, 79 note_off(), 80 num_elements(), 22 on controller, 2 on init, 3 on midi_in, 121 on note, 4 on pgs_changed, 6 on release, 5 on rpn/nrpn, 7 on ui_control, 8 on ui_update, 9 Operators, 19 output_channel_name(), 81 play_note(), 82 Preprocessor, 114 purge_group(), 30 random(), 83 reset_ksp_timer, 84 search(), 23 select(), 17 set_control_help(), 40 set_control_par(), 41 set_controller(), 85, 86 set_engine_par(), 102 set_event_mark(), 87 set_event_par(), 88 set_event_par_arr(), 31 set_key_color(), 42 set_knob_defval(), 43 set_knob_label(), 44 set_knob_unit(), 45 set_midi(), 122 set_script_title(), 47 set_skin_offset(), 48 set_table_steps_shown(), 46 set_text(), 49 set_ui_height(), 50 set_ui_height_px(), 51 sort(), 24 ui_button, 52 ui_knob, 53 ui_label, 54 ui_menu, 55 ui_slider, 58 ui_switch, 56 ui_table, 57 ui_value_edit, 59

128

KSP Reference Manual Index

wait(), 89 while(), 18

129

Hellobox8 User Manuel1
100% (6)
Hellobox8 User Manuel1
14 pages
MW-12A Operation Manual v4.0
0% (1)
MW-12A Operation Manual v4.0
69 pages
KSP Reference Manual
No ratings yet
KSP Reference Manual
202 pages
Automatic External
100% (1)
Automatic External
16 pages
UISS Manual
No ratings yet
UISS Manual
71 pages
GRBL Commands v1.1 2 PDF
No ratings yet
GRBL Commands v1.1 2 PDF
14 pages
GRBL Software Instructions
100% (3)
GRBL Software Instructions
30 pages
KSP Reference Manual
No ratings yet
KSP Reference Manual
155 pages
KSP Reference Manual
No ratings yet
KSP Reference Manual
215 pages
KSP Reference Manual
No ratings yet
KSP Reference Manual
236 pages
KSP Reference Manual 2
No ratings yet
KSP Reference Manual 2
211 pages
KONTAKT 610 KSP Reference Manual
No ratings yet
KONTAKT 610 KSP Reference Manual
232 pages
KSP Reference Manual 07 07 2020 ENGLISH
No ratings yet
KSP Reference Manual 07 07 2020 ENGLISH
372 pages
KONTAKT 602 KSP Reference Manual
100% (1)
KONTAKT 602 KSP Reference Manual
223 pages
KSP Reference Manual
No ratings yet
KSP Reference Manual
248 pages
KSP Reference Manual 6.7 English 18-02-22
No ratings yet
KSP Reference Manual 6.7 English 18-02-22
346 pages
What's New in Kontakt 2.1 - KSP
No ratings yet
What's New in Kontakt 2.1 - KSP
9 pages
KSP Reference Manual en 7 1
No ratings yet
KSP Reference Manual en 7 1
358 pages
Nils Liberg S Kontakt Script Editor PDF
No ratings yet
Nils Liberg S Kontakt Script Editor PDF
9 pages
Nils Liberg's Kontakt Script Editor
0% (1)
Nils Liberg's Kontakt Script Editor
9 pages
Variables and Conditions For The PMDG 737 Ngxu
No ratings yet
Variables and Conditions For The PMDG 737 Ngxu
26 pages
KSP Reference Manual
No ratings yet
KSP Reference Manual
379 pages
Auto Ext Config
No ratings yet
Auto Ext Config
15 pages
PX 777 Programming Software Instructions
No ratings yet
PX 777 Programming Software Instructions
7 pages
Automatico Externo PDF
No ratings yet
Automatico Externo PDF
17 pages
Acspl Software Guide Revision 3 00
50% (2)
Acspl Software Guide Revision 3 00
353 pages
KSPedia XB1
No ratings yet
KSPedia XB1
175 pages
KUKA PLC en
No ratings yet
KUKA PLC en
26 pages
KSP 7 10 Reference Manual English
No ratings yet
KSP 7 10 Reference Manual English
388 pages
Machine Data Collection - NGC
No ratings yet
Machine Data Collection - NGC
8 pages
Kspedia PC
No ratings yet
Kspedia PC
199 pages
PG3
No ratings yet
PG3
577 pages
FANUC机器人培训教材
No ratings yet
FANUC机器人培训教材
140 pages
950 Transceiver Software Control Manual
No ratings yet
950 Transceiver Software Control Manual
29 pages
Manual de Programación
No ratings yet
Manual de Programación
37 pages
Configuration Manual: Title: Default Jbus Memory Mapping For Lei Gateway
No ratings yet
Configuration Manual: Title: Default Jbus Memory Mapping For Lei Gateway
23 pages
Mcosmos E4180 525 PDF
No ratings yet
Mcosmos E4180 525 PDF
28 pages
Mcosmos E4180 525
No ratings yet
Mcosmos E4180 525
28 pages
Mcosmos: Data Processing System For Manual/CNC CMM
100% (1)
Mcosmos: Data Processing System For Manual/CNC CMM
28 pages
ASM-Guide 1
No ratings yet
ASM-Guide 1
9 pages
Uav 6
No ratings yet
Uav 6
22 pages
Espritp Ep01
No ratings yet
Espritp Ep01
20 pages
mg6130 PDF
No ratings yet
mg6130 PDF
40 pages
AGC 150_setting
No ratings yet
AGC 150_setting
19 pages
Milltronics Centurion V
No ratings yet
Milltronics Centurion V
313 pages
Creating C-Gauges by Dai Griffith PDF
No ratings yet
Creating C-Gauges by Dai Griffith PDF
112 pages
Flying Saturn V
No ratings yet
Flying Saturn V
10 pages
FANUC Robotics Documentation U
No ratings yet
FANUC Robotics Documentation U
9 pages
Calterm Commands
No ratings yet
Calterm Commands
8 pages
Fanuc Input Output
No ratings yet
Fanuc Input Output
9 pages
Avionic Checklists
No ratings yet
Avionic Checklists
24 pages
Downloaded From Manuals Search Engine
No ratings yet
Downloaded From Manuals Search Engine
132 pages
KVARA 6 MAUAL 752tool0gb
No ratings yet
KVARA 6 MAUAL 752tool0gb
48 pages
KONTAKT Scripting
100% (1)
KONTAKT Scripting
14 pages
Avionic Checklists
No ratings yet
Avionic Checklists
21 pages
Profound Linux For Developers
From Everand
Profound Linux For Developers
Onder Teker
No ratings yet
Python-Deprecated Library v1.1 Documentation
From Everand
Python-Deprecated Library v1.1 Documentation
Laurent LAPORTE
No ratings yet
Python Advanced Programming: The Guide to Learn Python Programming. Reference with Exercises and Samples About Dynamical Programming, Multithreading, Multiprocessing, Debugging, Testing and More
From Everand
Python Advanced Programming: The Guide to Learn Python Programming. Reference with Exercises and Samples About Dynamical Programming, Multithreading, Multiprocessing, Debugging, Testing and More
Marcus Richards
No ratings yet
Vb Net Programming
From Everand
Vb Net Programming
Martin Booch
No ratings yet
Introduction to PHP, Part 5, Second Edition
From Everand
Introduction to PHP, Part 5, Second Edition
Adam Majczak
No ratings yet
Derinlemesine React Data
From Everand
Derinlemesine React Data
Onder Teker
No ratings yet
5-4-2024 Ashani_Mahanama_CV
No ratings yet
5-4-2024 Ashani_Mahanama_CV
2 pages
OBJECTIVES
No ratings yet
OBJECTIVES
4 pages
iridology-heart
No ratings yet
iridology-heart
9 pages
GAPS Manual
No ratings yet
GAPS Manual
148 pages
2024 Gedik
No ratings yet
2024 Gedik
8 pages
Group 7 Brake Pedal (Valve)
No ratings yet
Group 7 Brake Pedal (Valve)
2 pages
What Is Astrology-Intro To Jyotish-Free-eBook
100% (1)
What Is Astrology-Intro To Jyotish-Free-eBook
44 pages
E-receipt3
No ratings yet
E-receipt3
2 pages
ÔN TẬP VIẾT LẠI CÂU ANH 1
No ratings yet
ÔN TẬP VIẾT LẠI CÂU ANH 1
2 pages
The Mask You Live in - Curriculum Overview - Second Edition
No ratings yet
The Mask You Live in - Curriculum Overview - Second Edition
18 pages
10th English Maths 2
No ratings yet
10th English Maths 2
192 pages
Top 5 Telecom Operators in The Middle East 2018
No ratings yet
Top 5 Telecom Operators in The Middle East 2018
3 pages
Sony Hdr-cx550 Xr550 Level-2 Ver-1.0 SM
No ratings yet
Sony Hdr-cx550 Xr550 Level-2 Ver-1.0 SM
51 pages
No More Homework Petition
100% (1)
No More Homework Petition
7 pages
Tabel f-0-05
No ratings yet
Tabel f-0-05
1 page
1 Lista 5ce - Co Canais BR
No ratings yet
1 Lista 5ce - Co Canais BR
53 pages
Processes in Music Therapy
No ratings yet
Processes in Music Therapy
11 pages
System Manager Integration With BlueXP
No ratings yet
System Manager Integration With BlueXP
5 pages
6 Roleplaying Droids
No ratings yet
6 Roleplaying Droids
8 pages
Albert Einstein Alugbati Basella Alba Stem Extract As An Alternative Ink For Permanent Markers
No ratings yet
Albert Einstein Alugbati Basella Alba Stem Extract As An Alternative Ink For Permanent Markers
20 pages
Product Brief LevelPlus-Series TankSLAYER 551864 en
No ratings yet
Product Brief LevelPlus-Series TankSLAYER 551864 en
2 pages
Python Syllabus
No ratings yet
Python Syllabus
5 pages
Tutorial 2 - Sol
No ratings yet
Tutorial 2 - Sol
2 pages
@NEETpassionate Units and Measurement Aakash RM Modules
No ratings yet
@NEETpassionate Units and Measurement Aakash RM Modules
31 pages
Safe Work Practices On High Voltage Cables
100% (2)
Safe Work Practices On High Voltage Cables
35 pages
(Ebook) Multicultural Education Policies in Canada and the United States by Reva Joshee ISBN 9780774813259, 0774813253 - Discover the ebook with all chapters in just a few seconds
No ratings yet
(Ebook) Multicultural Education Policies in Canada and the United States by Reva Joshee ISBN 9780774813259, 0774813253 - Discover the ebook with all chapters in just a few seconds
56 pages
Plant Layout: End Term Jury
No ratings yet
Plant Layout: End Term Jury
16 pages
Hydraulics
No ratings yet
Hydraulics
8 pages
TLC 1514
No ratings yet
TLC 1514
40 pages