Introduction to Scripting In Kontakt, Part 3

Last time we looked at some statements using if...else and select(). These helped us to run a script when something specific happened, like a note being played. If you remember we built a script that let us trigger (or un-bypass) some internal effects by pressing notes on our MIDI keyboard.

Part of this was done by targeting the Bypass control of the effects using some built-in variables, namely $ENGINE_PAR_EFFECT_BYPASS which was simply a reference to that parameter. In this part we're going to delve deeper into variables, both built-in and user defined.

What Is A Variable?

Variables are without doubt the most important thing in any scripting language and it would be quite hard to proceed with the rest of these workshops without explaining them in further detail. 

A variable is a storage device that holds a piece of information. At any point you can refer to that piece of information by referencing that variables name. Think of it like a shortcut.

You can fill a variable with a static (constant) piece of information like a name, number or an object. Alternatively you can fill it with something dynamic, like the current value of a changing parameter which can then be passed on to something else.

There are two main types of variable. Built-In and User Defined. Let's have a look!

Built-In Variables

The Kontakt Scripting Language has many built in variables which are written into the language. These are mainly references to the accessible parameters of the Kontakt engine, namely things you can manipulate with the KSP. Here's a good example. The Lo-Fi effect has four parameters. I can access these by using the built in variables for them. These are:

• $ENGINE_PAR_BITS
  
• $ENGINE_PAR_FREQUENCY
  
• $ENGINE_PAR_NOISELEVEL
  
• $ENGINE_PAR_NOISECOLOR

You'll notice that these all have a certain prefix of $ENGINE_PAR_. This prefix is reserved for Kontakt use only, as are $NI_, $CONTROL_PAR_, $EVENT_PAR_. When you come to define your own variables you'll want to steer clear of using these.

There are also other types that hold information about user actions, like what notes you're playing. We saw one of these last time, $EVENT_NOTE.

There are far too many to cover here but you'll find a list of all built in constants and Variables at the end of the KSP Reference Manual. Saying that I'll give you an example.

There is a built-in variable called $PLAYED_VOICES_INST. This holds the value of how many voices (notes) the current instrument is playing. If I write this on note callback...

I get this message.

You'll notice I've added one to the variable as it counts from 0. The ampersands (&) allow me to include the result between some written text (within quotation marks).

So you'll be using built-in variables to gather information about what is coming into Kontakt as well as accessing parameters and built in features within the Kontakt engine.

User Defined Variables

User variables are defined by you and because Kontakt is not familiar with these variables (unlike the built-in ones) you'll first need to declare them. Declaring a variable has to be done between your on init...end on callback. So what's it all about?

Declare is a way of saying, “Hey Kontakt! I'm going to make a new variable, so listen up!”. 

So let's try! I'm going to make a normal variable (there are a few other types). These are preceded with a $. Any variable is highly case sensitive so beware!

declare $myVariable 

So that's good but what now? At the moment $myVariable is empty as I haven't given it a value. So let's say...

$myVariable := 2

The := means 'equal to'. So my code will look like this.

declare $myVariable

$myVariable := 2

Now Kontakt knows what $myVariable means. I could also write the same thing in one hit like this...

declare $myVariable := 2

Where this is OK in some circumstances you'll see later that we may need to separate the declaration and assigning of values into two parts.

So now my variable has a value I could print a message on a note event by using.

I get this message.

Notice how I can use $myVariable inside the quotation marks without it showing up as '2'. This is because anything inside quotations is considered plain text.

So, one more example using dynamic values. This time I'll fill my $myVariable with the value of  $PLAYED_VOICES_INST. 

$myVariable := $PLAYED_VOICES_INST + 1

$myVariable will now hold the information gathered by $PLAYED_VOICES_INST and add 1. So now I could do this. 

Notice I've assigned the value to $myVariable inside the on note callback. This is because $PLAYED_VOICES_INST can only gather the note data when inside callbacks that deal with note information.

And I get this...

Now, I've only hit one note so "You are playing 1 notes!" is grammatically nonsense!! So let's use our variable to help make this work.

Using an if...else statement we can find out how many notes are playing and display a relevant response that's grammatically correct. 

So let's say “If $myVariable is greater than one, print a message that expresses the plural of note. If it's not then print a message using the singular of note.”

We put $myVariable (which now holds the number of notes played) inside the brackets of the if statement. This way it can weigh up if it's greater (>) than 1.

Our code will look like this.

When I play one note I get....

when I play more than one note I get...

Success!!!

So hopefully you can see how this variable is working. I'm reusing it three times in this script which obviously saves some time and size. When you write more complex scripts you might reference this tens of times and only have to assign the value once. 

A variables value doesn't have to be static and there is nothing to stop you changing a variables value at any time, in fact this is quite common. I'll give some examples in later tutorials.

Variable Types

So far we've dealt with basic variables. There are a few different types of variable in Kontakt each with its own prefix.

• @myText = A String Variable. Holds “Text information”
• const $myVariable = Sets a constant value e.g. 12
• polyphonic $myVariable = Holds a value for each polyphonic event.
• %myArray[] = Holds multiple values in a list
• !myArray[] = Holds multiple text strings in a list
  

We'll cover a few of these in some coming tutorials. 

Next time we'll look at some interface techniques. Knowing about variables should make the process of creating user controls a lot easier to understand. Till then!!

I've included the code examples in this PDF. 

Quick Links:

Introduction To Scripting in Kontakt, Part 1 

Introduction To Scripting in Kontakt, Part 2

Introduction To Scripting in Kontakt, Part 3 (you're reading it)

Introduction To Scripting in Kontakt, Part 4

Introduction To Scripting in Kontakt, Part 5