Posted by & filed under KSP Scripting (NI Kontakt) - Tutorials, KSP: Custom UI (design).

Download all Resources (free)


commands &  parameters you need

set the UI height in pixels

ui_slider $<variable-name> (<min>,<max>)
this creates a slider but you can add custom graphics like round knobs which is not possible with ui_knob

make_persistent (<variable>)
with this command you store and read all current variables/parameters when closing and starting the Kontakt Instrument again

this moves the controls inside your UI originating the top left position

change various parameters of the specified ui control like font-type, parameter value etc.

same as set_control_par but for use with strings (like “picture1”) e.g in combination with $CONTROL_PAR_PICTURE

use in combination with get_control_par() or set_control_par()
values from -5000 to 5000,
sets the move direction of a slider and its drag-scale
settings are relative to the size of the slider picture
negative values = vertical slider behavior, positive values = horizontal behavior

control parameter: use with get_control_par() or set_control_par()
sets the picture name. An extension is not required for the picture name, neither is the full path. If the nki references a resource container, Kontakt will look for the file in the pictures subfolder. If the nki does not reference a resource container, it will first look in the user pictures folder (located in user/documents/Native Instruments/Kontakt 5/pictures), then in the Kontakt pictures folder.

retrieve the ID number of an ui contro (integer)

array to store single integer values at specific indices. You may wanna use arrays e.g. to automate settings or changes…

1. Create a resource container (learn more)

2. Create & assign a knob image

To use custom knob images you need to use the ui_slider control, since you can’t assign images to the ui_knob control. This is how you create your image:

knob11. The single knobs must be arranged vertically whereas each line represents an animation step (see left image). You can draw each animation step yourself in photoshop or gimp etc. Or you can use KnobMan to help you creating those animations. The more animation steps you do, the smoother the movement. However yo don’t need to draw more than 100 animation steps for a 360° knob turn. Store the graphic into Resources –> Pictures” then

2. Create a usual *.txt file with the knob image’s file name and put it into Resources –> Pictures as well. In this cas “Knob1.txt”. Kontakt needs this text file to retrieve additional info about the knob image like the number of animation steps or if the graphic uses an alpha channel (for transparency) etc. You can do as many animation steps as you like but you have to add the correct number at “Number of Animations” in your text file of course.

In this case the txt file has to look like this:

 Has Alpha Channel: yes
 Number of Animations: 10
 Horizontal Animation:  no
 Vertical Resizable: no
 Horizontal Resizable: no
 Fixed Top: 0
 Fixed Bottom: 0
 Fixed Left: 0
 Fixed Right:  0

Note: Custom images can only be used with menus, sliders, labels, switches and buttons.


3. KSP – Script

  1. create a slider with declare ui_slider $<variable-name> (<min>,<max>). Min / Max defines the interval of values you want to pass to the Kontakt engine when the Knob is turned. So a Knob position at 0% will pass the Knob’s min value and a Knob position at 100% will pass the max value. Usually you want to use 1.000.000 for the max value because this is also the max value of almost all engine parameters. For more details for the correct max value refer to the KSP Reference Guide. Of course you can also state min = 0 and max = 10 and do a multiplication by 100.000 afterwards or do any other calculation.
  2. create an array to store all ui id’s declare %ui_id[] Each UI element has its unique id (integer value). The use of arrays is not necessarily required but with arrays you can save lots of time and lines of code  since you can address all ui controls at once via one little while loop (see example below). Also this method is less error-prone.
  3. Set your custom picture with set_control_par_str(<SLIDER_UI_ID>,$CONTROL_PAR_PICTURE,"knob1"). Use the the file name of your knob image without any extension like .png
  4. Position the knob within the grid (see alternate code below to position the knob with exact pixels).


on init

    declare $count

    declare ui_slider $attack(0,1000000)
    declare ui_slider $decay(0,1000000)
    declare ui_slider $sustain(0,1000000)
    declare ui_slider $release(0,1000000)

    declare %ui_id[4]
    %ui_id[0] := get_ui_id($attack)
    %ui_id[1] := get_ui_id($decay)
    %ui_id[2] := get_ui_id($sustain)
    %ui_id[3] := get_ui_id($release)

    make_persistent ($attack)
    make_persistent ($decay)
    make_persistent ($sustain)
    make_persistent ($release)

    $count := 0
    while ($count < 4){This while loop is setting the parameters & images of all 4 knobs at once}
        set_control_par(%ui_id[$count],$CONTROL_PAR_MOUSE_BEHAVIOUR,-400) {declares which mouse movements turn the knob in which this case only vertical movements in a normal speed}
        {alternatively you can position the knobs to exact pixels
    end while
end on

13 Responses to “Kontakt Scripting (KSP) :: Custom Knob Images / Custom Controls”

  1. Magnus

    Hey thanks for the help!
    I had no problem adding the graphics, but they just added to my instrument.
    This Tutorial was only about adding the graphic (64×64), right? But what about animating it?
    Because it doesn’t animate my sliders at all. The vertically long png (60 animations) just overlays my whole wallpaper; beginning at the position of my 4 sliders.
    I then wanted to use

    on ui_control ($attack)
    end on

    but it’s not as easy as i thought x)
    Also how can I add a mask then? So it doesn’t show all the 60 animations, but only one?
    Any tips?
    Thanks again for sharing :)

    • YummyBeats

      Hey, did you add the txt file to your pictures folder? Make sure that it has the same filename as your knob’s image. You must also add 60 animations at “number of animations” .. just like shown in the example txt.
      The size of your knob image doesn’t matter actually. But make sure that the single animation frames in your sprite are equally arranged, means that the diestance of each animation frame needs to be the same. Sometimes this is not that easy to achive when you have a transparent border around your actual knob. But if you are working with knobman it takes care of that.

    • YummyBeats

      on ui_control($attack)
      end on

      Hope this helps. Probably there will be a tutorial soon.

  2. bertox

    My Kontakt are not reading the txt files from PNGs. No matter what i put on them. Any thoughts?

    • YummyBeats

      Possible sources of error are:
      – wrong file name (it has to be the exact same name as the png file)
      – wrong coding (currently not sure all of which are allowed but ANSI should work)
      – no line breaks (make sure every parameter is in a separate line)
      – use of parameters which are not allowed
      – missing parameters which are required (refer to the example above)
      – typos

    • YummyBeats

      Either create a new array which looks the same or expand the existing array like this:

      declare %ui_id[5]
      %ui_id[0] := get_ui_id($attack)
      %ui_id[1] := get_ui_id($decay)
      %ui_id[2] := get_ui_id($sustain)
      %ui_id[3] := get_ui_id($release)
      %ui_id[4] := get_ui_id($new_knob)

      Of course you need to declare the knob / slider before like this:
      declare ui_slider $new_knob("min","max")

      Then simply also extend the while loop like this:
      while ($count < 5)
      end while

      Or if you want to add a new graphic, position etc only for this knob add the following after the while loop:

      set_control_par(%ui_id[$count],$CONTROL_PAR_POS_X,"x position in px")
      set_control_par(%ui_id[$count],$CONTROL_PAR_POS_Y,"y position in px")
  3. Paolo

    Can i manage the size of my knobs via script? Or has the .pgn file to be in the right size ?

    • YummyBeats

      Unfortunately you can’t scale any graphic. So yes, the png has to be in the right size.

    • YummyBeats

      sorry, this article is only about custom knobs. The knob names ($attack $release, etc) are just an example. They could have also been named $a, $b, $c, $d which would make no difference. To make the knobs functional you need on ui_control events for each knob which would have bloat this article too much.


Leave a Reply

Your email address will not be published. Required fields are marked *