Introduction To Scripting in Kontakt, Part 2

So last time we looked at some basic callbacks, namely "on init", "on note" and "on release". We saw how placing some simple code between these callbacks printed some messages letting us know our code was working. 

This time, we're going to build something!! I'm sure you've all seen Heavyocitys Damage and Evolve instruments. One of the cool things they have are note triggered FX. Well I'm going to show you how to build a simple script to do this as I think it's something that users would like to do. Let's go!

The Plan!

Here's what we're after. You load a bunch of Insert effects and bypass them. You then map the Bypass parameter for each effect to a note. When you hit a note, the effect corresponding to that note is active, when you release the note the effect is bypassed!

To achieve this we first need to learn about statements.

Statements

So what are statements? Well these let Kontakt make decisions about what's going to happen when you do something. 

The 'if...else' statement is found in all scripting languages. It allows your script to only run if something very specific happens. Let's take our simple message from last time as an example.

on note

message ("You're Playing A Note")

end on

This will show up if you hit any note, it is a note on callback after all. Let's say we only want this to show up on C3 though. The 'if' statement is perfect for this.

If

Here's the structure of the 'if' statement.

if ( define some parameters here like 'something equals something' )

{Do something clever if something equals something!}

end if  {End the if statement!}

So that's pretty simple! But what is 'something equals something'? Well it could be anything. In our case we need to tell the if statement about C3. We can do this using a built-in variable called $EVENT_NOTE (There is also $EVENT_VELOCITY too!). This holds the value of the currently held note(s) as a MIDI note number and can only be used inside a on note or on release callback. 

So we could say, “If $EVENT_NOTE is equal to 60 (C3) then run the script!”. So how do we write that. Well, like this!

If I play notes that aren't C3, I won't see anything as this script is specific to C3. But if I do!

So what about all the other notes? Well, we can expand this to an if...else statement.

If...Else

The 'else' part pertains to anything that isn't on the list. You can think of this like a doorman at a club!

if ( the person is attractive )

Let them in!

else

Send them away!

end if

Only kidding (Or am I?) but that does sum it up! We could use this.

The wrong notes now have a message too!

So what if we want a load of different messages on different notes? We don't want to have to keep writing loads of if statements for each one. There is however another handy statement called select().

Select

Select is like a more versatile version of if...else. This time the 'if' is a 'case', like on a 'case by case' basis. Here's how it works.

Instead of saying $EVENT_NOTE = 60 inside the brackets of the if statement, we now just insert $EVENT_NOTE inside the select brackets like so.

select( $EVENT_NOTE )

end select

The note number value of $EVENT_NOTE is passed to the case.

This will do exactly the same thing as our first if example. You can state as many cases as you like.

You can also set a range for the case like so.

When you play within the ranges you'll see this.

Of course you need to pair the on note with an on release like this.

When you release any note.

Now that we know how that works, we're going to use select() to trigger our effects. 

Load Some Effects!

I'm going to load three effects into the Instrument Insert Effects slots. I've got a Distortion, a Lo-Fi and a Phaser. I'm now going to bypass these effects.

Target The Effects

Anything that can be automated in Kontakt can be accessed by the KSP. There is a built-in function in the KSP called set_engine_par() that allows you to manipulate parameters inside the Kontakt engine. You'll use this a lot!!

We need to pass some information into the brackets of this function. This is as follows:

set_engine_par( , , , , )

Let's break this down:

• The Parameter we want to effect e.g $ENGINE_PAR_DRIVE on our Distortion. (You'll find a list of all the available parameters in the Kontakt KSP reference at the end.)
  
• The value for the parameter. This can be passed by a UI control or you can set a value.
  
• The Group number (if applicable). This corresponds to Group FX. Set this to -1 if you want to target effects at the Instrument level. 
  
• The Slot number of the target effect. Starts at 0. Slot 1 = 0, Slot 2 = 1 etc.
  
• Is it an Insert or Send effect? 1 = Insert, 0 = Send
  

Set Some Parameters

So, the parameter I want to effect is Bypass. This is targeted using $ENGINE_PAR_EFFECT_BYPASS. Let's put that in.

set_engine_par( $ENGINE_PAR_EFFECT_BYPASS, , , , )

The values for bypass are 0 is on and 1 is bypassed. I want to activate the effect so I'll put 0 into the Value.

set_engine_par( $ENGINE_PAR_EFFECT_BYPASS, 0, , , )

My slots are on the Instrument level so I'll put -1 into Group.

set_engine_par( $ENGINE_PAR_EFFECT_BYPASS, 0, -1, , )

My Distortion is in Slot 1 so I'll put 0 into Slot.

set_engine_par( $ENGINE_PAR_EFFECT_BYPASS, 0, -1, 0, )

My effect is an Insert effect so I'll put 1 in Generic.

set_engine_par( $ENGINE_PAR_EFFECT_BYPASS, 0, -1, 0, 1 )

Now I have a finished line of code I can drop this into my select() statement.

When I hit C3 the first effect slot (the Distortion) will become active. 

I need to reverse this in an on release callback so when I take my finger of the key the effect is bypassed again. I do this by putting a 1 into Value like so.

I can now set this up for different keys using a different case for each. All I have to do is increase the slot number.

Here's the result of hitting D3.

And then using on release bypass the effect when I release the key by putting 1 into Value.

I can trigger more than one effect at the same time too, which is a bonus!

Here's an example of my script at work.

I can then set a title for my script like we covered last time.

I can then go and save this as a preset for later use!

Success! Try this out for yourself. I've included the code snippets in a PDF. If you want more effects just load them and add more cases to the script.

So there you have it. A simple script with a cool result. Next time we'll have a look at some interface design.