Like with any other programming languages in KSP there are also variables, arrays and constants.

They can only be declared inside the on init callback and can then be used throughout the whole script. So they are all on global scope by default and can even be used inside custom functions.

• Variables

  • Integer
  • string
  • real

• constant variables

• Arrays

  • integer
  • string
  • real

• Built-In Variables

• global vs local variables

VARIABLES

Into variables we can store different values and read or access them anywhere we want throughout the whole script.

There are different variable types like string, integer, real and constant variables.

Furthermore there’s a special polyphonic variable which is not addressed in this article.

Integer Variables

can only store integer numbers and have to be declared like this declare $<variable-name>
The $ makes it an int variable

on init
     declare $count := 8 {sets the variable named "count" and stores 8}
     message ($count) {outputs 8}
 end on

String Variables

can only store strings and have to be declared like this: declare @<variable-name>
The @ makes it a string variable

on init
     declare @hint
     @hint:= "Within string variables we can store complete sentences! And yes, she works fine :)"
     message(@hint)
end on

REAL VARIABLES

can only store real numbers (or floating points) and have to be declared like this declare ~<variable-name>
The ~ makes it a real variable

declare ~RealNumber := 4 //this produces an error:
declare ~RealNumber := 4.00 // this works
declare ~RealNumber := 7694.987653428 // this works

We can not mix integer variables with real variables so if we want to use both within the same calculation we have to convert one or the other

on init
  declare $integer := 4
  declare ~real := 3.9

  message(~real + $integer) {this produces an error}

  message(~real + int_to_real($integer)) {this outputs 7.9}

  message(real_to_int(~real) + $integer) {this outputs 7}
end on

Constant Variables

Constant variables can’t be changed anymore once they have been set. You may wanna use them to avoid accidentally overwriting their values especially when your code gets more complex.

User defined constants can be declared by adding a “const” before the variable name. You also have to define the value right after on:

declare const $<variable-name>:= <value>

This works

on init
    declare const $MY_CONST := 10 {always stays 10 now}
end on

This won’t work

on init
    declare const $MY_CONST
    $MY_CONST := 10
end on

This won’t work either

on init
    declare const $MY_CONST := 10
    $MY_CONST := 11
end on

ARRAYS

Compared to a variable an array can hold multiple values at once while each value is stored or assigned to a certain key inside the array.

Think of it like a filing cabinet with little or many drawers. Each drawer (key) holds an individual file (value). We can access and read those files by opening the drawer we need.
Which means:

//To declare an array:
declare %array[number_of_total_keys]

//To return values of an array: 
message(%array[$key]) // outputs the value of $key

//To Store values into an array: we simply do 
%array[$key] := $value

//To search the key of a given value: 
search(%array, $value) // outputs the key index where the value was first found

To do so we first declare an array, specify its size (= number of keys). We can then fill the single keys with values (like shown below).

There are also different types of arrays like int, string and real arrays (see below).

int arrays

can only store integers and have to be declared like this declare %<array-name>[number_of_keys]
The % makes it an int array. The value between the brackets [] defines the size of the array. The array size can’t be changed anymore once it is set.

on init
    declare %parameter[4] {defines an int array named "parameter", with the size of 4 keys }
    %parameter[0] := 10 {stores 10 into key 0 .. note: the first key starts with 0 not 1}
    %parameter[1] := 126
    %parameter[2] := 10024
    %parameter[3] := 8
    message(%parameter[2]) {outputs 10024}
end on

string arrays

can only store strings and have to be declared like this declare !<array-name>[number_of_keys]
The ! makes it a string array. The value between the brackets [] defines the size of the array. The array size can’t be changed anymore once it is set.

on init
     declare !notes[4]
     !notes[0] := "C"
     !notes[1] := "C#"
     !notes[2] := "D"
     !notes[3] := "D#"
     message(!notes[3]) {outputs D#}
end on

real arrays

can only store real numbers and have to be declared like this declare ?<array-name>[number_of_keys]
The ? makes it an array of real numbers. The value between the brackets [] defines the size of the array. The array size can’t be changed anymore once it is set.

Real arrays work the same as real variables:

on init 
  declare ?realArray[8] 	 {declares an array of real numbers with 8 keys}
  ?realArray[0] := 4 	 {this produces an error}
  ?realArray[1] := 4.00 	 {this works}
  ?realArray[2] := 854.9882 {this works}

  message(?realArray[2])    {this outputs 854.9882}
end on

To mix int with real arrays we also need to convert one or the other:

on init 
  declare ?realArray[3] 	
  ?realArray[0] := 2.5 	
  ?realArray[1] := 7.5
  ?realArray[2] := 7.9

  declare %intArray[2] 	
  %intArray[0] := 2 	
  %intArray[1] := 4 	

  message(?realArray[0] * int_to_real(%intArray[1])) {outputs 10}

  message(real_to_int(?realArray[1]) * %intArray[0]) {outputs 14}

  message(real_to_int(?realArray[2]) * %intArray[0]) {outputs 14, so real_to_int just cuts the decimals (or floors the decimal)}
end on

BUILT-IN Variables

(also called Control Parameter Variables, Engine Parameter Variables,..)

There are also internal variables which are holding or returning specific values given by the Kontakt engine. Like the actual played note ($EVENT_NOTE) or engine parameters, but also UI parameters and many more.

We use them to control or to address all kinds of Kontakt internal engine parameters like the Instrument’s Volume, or our ui controls and many other parameters. There is a full list of all internal variables and what they do in the KSP Reference Manual.

Without these variables we wouldn’t be able to operate Kontakt with custom scripts. Internal variables cannot be declared or changed. They are always available globally.

Working with these Variables is mainly what Kontakt scripting is about so you will see them a lot with yor scripts. And you will get familiar with many of them. At best study all of them to get to know what Kontakt is capable of and what not. Also this may inspire you.

global & local variables explained

First of all, in KSP there are NO local variables. So all variables are global by default and have to be declared inside the on init callback.
Although we can’t use local variables in KSP it is still helpful to understand the differences. For example to better understand the limitations of KSP compared to other programming languages.

Global variables

are accessible from anywhere in a program. They are declared outside any function and remain in memory throughout the runtime of the program. This makes them useful for sharing data across multiple functions. So any changes made to global variables are reflected in all functions that access them. However with global variables more errors can occure since they can be changed from anywhere in our code. There is also a higher risk of losing track if lots of variables are used.

Local variables

are variables defined within a specific area of code or function and can only be accessed within that code area. Local variables prevent the accidental sharing of data between those code areas / functions and help to maintain data integrity within a specific scope. If a local variable name has already been used we can even assign the same variable name again for the next function.

In summary

global variables provide broader accessibility and can be useful for sharing data across functions. However, they can lead to unintended changes. On the other hand, local variables ensure data integrity and offer predictable results, but are limited to the area / function they are declared in. It’s important to carefully consider the use of global and local variables based on the specific requirements of your program.