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

Download all Resources (free)

DOWNLOAD


commands &  parameters used in this article

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

move_control_px(<variable>,<x-position>,<y-position>)
this moves the controls inside your UI originating the top left position

set_control_par(<ui-ID>,<control-parameter>,<value-int>)
change various parameters of the specified ui control like font-type, parameter value etc.

set_control_par_str(<ui-ID>,<control-parameter>,<value-string>)
same as set_control_par but for use with strings (like “picture1”) e.g in combination with $CONTROL_PAR_PICTURE

$CONTROL_PAR_MOUSE_BEHAVIOUR
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_PAR_PICTURE
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.

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

%<array-name>[]
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)

this is already covered in the create a resource container article

2. Create & assign a knob image

To use custom knob images we need to use the ui_slider control, since we can’t assign images to the ui_knob control. To create our image:

knob11. we must arrange the single knobs vertically whereas each “line” represents an animation step (see left image). We can draw each animation step manually in Photoshop, Gimp etc. Or we can use KnobMan to automatically create those animation steps. The more animation steps we do, the smoother the knob movement feels later on. However we don’t need to exceed more than 100 animation steps for a 360° knob turn. Even 64 steps are already smooth enough.

2. we then store the knob image into Resources –> Pictures”

3. we create a standard *.txt file (with any text editor) and name it exactly like the knob’s image file name. In this case “Knob1.txt”.  We need to put this txt file into Resources –> Pictures as well. Kontakt needs this extra text file to retrieve additional info about the knob image like the number of animation steps. We can do as many animation steps as we want but we always have to set the correct number at “Number of Animations” in our text file.

In our 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. The KSP Script

  on init
    make_perfview
    set_ui_height_px(200)
 
    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_str(%ui_id[$count],$CONTROL_PAR_PICTURE,"knob1")
        set_control_par(%ui_id[$count],$CONTROL_PAR_MOUSE_BEHAVIOUR,-400) {declares which mouse movements turn the knob in which speed...in this case only vertical movements in a normal speed}
        set_control_par(%ui_id[$count],$CONTROL_PAR_GRID_X,$count+1)
        set_control_par(%ui_id[$count],$CONTROL_PAR_GRID_Y,2)
        
        {alternatively you can position the knobs to exact pixels with the following code}
        {set_control_par(%ui_id[$count],$CONTROL_PAR_POS_X,$count*80+70)
        set_control_par(%ui_id[$count],$CONTROL_PAR_POS_Y,20)}
        inc($count)
    end while
end on

declare ui_slider $<variable-name> (<min>,<max>)creates a slider with  Min / Max which defines the range of values we want to pass to the Kontakt engine when turning the Knob. 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 we want to use 1.000.000 for the max value because this is the general max value of almost all engine parameters. For more details for the correct max value refer to the KSP Reference Guide. Of course we can also state min = 0 and max = 10 and do a multiplication by 100.000 afterwards.

 

declare %ui_id[]we create an array to store all ui id’s Each UI element has its unique id (integer value). The use of arrays is not necessarily required but with arrays we can save lots of time and lines of code  since we can address all ui controls at once with one lightweight while loop. Also this method is mostly less error prone.

 

set_control_par_str(<SLIDER_UI_ID>,$CONTROL_PAR_PICTURE,"knob1")sets our custom picture . We have to use the exact file name of our knob image without any file extension like png

 

set_control_par(%ui_id[$count],$CONTROL_PAR_GRID_X,$count+1) lastly we position the knob within the grid (or by pixels see alternate code below).

How useful was this article?

We are sorry that this post was not useful for you!

Let us improve this post!

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

  1. FergusAlder

    Is it possible to show ms/sec values with a custom knob - how would that happen?

    • YummyBeats

      Yes, you can use get_engine_par_disp() to get pretty much all of the values directly from the Kontakt engine. This automatically shows the right values and units, with no recalculation required. This also adds the correct unit like Hz, ms, dB,...

      EDIT: for displaying the values inside your UI create a label and change the label's text via

      @text := get_engine_par_disp([parameter],[group],[slot],[generic])
      set_control_par_str(get_ui_id(@your_label_name),$CONTROL_PAR_TEXT,@text)
      
      you can also refer to the custom ui tutorial and to the mouse release tutorial

  2. matt

    This is a great tutorial thank you.Above you said you could create a new array that looks the same, however when I try to declare a new variable I get %ui_id has been declared already . Do i have to declare all my variables in the first array? thx in advance
    on init
        make_perfview
        set_ui_height_px(470)
     
        declare $count
     
        declare ui_slider $mono(0,1000000)
        declare ui_slider $port(0,1000000)
        declare ui_slider $time(0,1000000)
    	
        declare %ui_id[3]
        %ui_id[0] := get_ui_id($mono)
        %ui_id[1] := get_ui_id($port)
        %ui_id[2] := get_ui_id($time)
        
        make_persistent ($mono)
        make_persistent ($port)
        make_persistent ($time)
     
        $count := 0
        while ($count < 3){This while loop is setting the parameters & images of all 4 knobs at once}
            set_control_par_str(%ui_id[$count],$CONTROL_PAR_PICTURE,"knob2")
            set_control_par(%ui_id[$count],$CONTROL_PAR_MOUSE_BEHAVIOUR,-400) {declares which mouse movements turn the knob in which speed...in this case only vertical movements in a normal speed}
            set_control_par(%ui_id[$count],$CONTROL_PAR_POS_X,$count*68+44)
            set_control_par(%ui_id[$count],$CONTROL_PAR_POS_Y,92)
            {alternatively you can position the knobs to exact pixels
            set_control_par(%ui_id[$count],$CONTROL_PAR_POS_X,40)
            set_control_par(%ui_id[$count],$CONTROL_PAR_POS_Y,20)
            }
            inc($count)
        end while
    
        declare $count1 
    
    	declare ui_slider $uniso(0,1000000)
        declare ui_slider $detune(0,1000000)
        declare ui_slider $spread(0,1000000)
    
        declare %ui_id[3]
    	%ui_id[3] := get_ui_id($uniso)
        %ui_id[4] := get_ui_id($detune)
        %ui_id[5] := get_ui_id($spread)
    
        make_persistent ($uniso)
        make_persistent ($detune)
        make_persistent ($spread)
     
        $count1 := 0
        while ($count1 < 3){This while loop is setting the parameters & images of all 4 knobs at once}
            set_control_par_str(%ui_id[$count1],$CONTROL_PAR_PICTURE,"knob2")
            set_control_par(%ui_id[$count1],$CONTROL_PAR_MOUSE_BEHAVIOUR,-400) {declares which mouse movements turn the knob in which speed...in this case only vertical movements in a normal speed}
            set_control_par(%ui_id[$count1],$CONTROL_PAR_POS_X,$count*68+44)
            set_control_par(%ui_id[$count1],$CONTROL_PAR_POS_Y,92)
            {alternatively you can position the knobs to exact pixels
            set_control_par(%ui_id[$count],$CONTROL_PAR_POS_X,40)
            set_control_par(%ui_id[$count],$CONTROL_PAR_POS_Y,20)
            }
            inc($count1)
        end while
    end on
    

    • YummyBeats

      thx. Arrays also must be unique like variables so you can't declare the twice. Just add another array or expand the array keys if you want to use only one array. In this case it is better to use a separate array.

      Note: working with arrays and while loops to customize the UI controls is a little old fashioned. Rather work with macros now. Just read this tutorial

      Fixed Code:
      on init
      	make_perfview
      	set_ui_height_px(470)
      
      	declare $count
      
      	declare ui_slider $mono(0,1000000)
      	declare ui_slider $port(0,1000000)
      	declare ui_slider $time(0,1000000)
      
      	declare %ui_id[3]
      	%ui_id[0] := get_ui_id($mono)
      	%ui_id[1] := get_ui_id($port)
      	%ui_id[2] := get_ui_id($time)
      
      	make_persistent ($mono)
      	make_persistent ($port)
      	make_persistent ($time)
      
      	$count := 0
      	while ($count < 3)
      		set_control_par_str(%ui_id[$count],$CONTROL_PAR_PICTURE,"knob2")
      		set_control_par(%ui_id[$count],$CONTROL_PAR_MOUSE_BEHAVIOUR,-400)
      		set_control_par(%ui_id[$count],$CONTROL_PAR_POS_X,$count*68+44)
      		set_control_par(%ui_id[$count],$CONTROL_PAR_POS_Y,92)
      		inc($count)
      	end while
      
      	{declare $count1} {no need to decalre another $count}
      
      	declare ui_slider $uniso(0,1000000)
      	declare ui_slider $detune(0,1000000)
      	declare ui_slider $spread(0,1000000)
      
      	declare %ui_id_2[3]
      	%ui_id_2[0] := get_ui_id($uniso)
      	%ui_id_2[1] := get_ui_id($detune)
      	%ui_id_2[2] := get_ui_id($spread)
      
      	make_persistent ($uniso)
      	make_persistent ($detune)
      	make_persistent ($spread)
      
      	$count := 0
      	while ($count < 3)
      		set_control_par_str(%ui_id_2[$count],$CONTROL_PAR_PICTURE,"knob2")
      		set_control_par(%ui_id_2[$count],$CONTROL_PAR_MOUSE_BEHAVIOUR,-400)
      		set_control_par(%ui_id_2[$count],$CONTROL_PAR_POS_X,$count*68+44) 
      		set_control_par(%ui_id_2[$count],$CONTROL_PAR_POS_Y,120) {adjust y position}
      		inc($count)
      	end while
      
      end on
      

  3. 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 (64x64), 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) move_control_px 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.

  4. 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_str(%ui_id[4],$CONTROL_PAR_PICTURE,"knob2")
      set_control_par(%ui_id[4],$CONTROL_PAR_MOUSE_BEHAVIOUR,-400)
      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")

  5. 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 to irfan Cancel reply

use <pre></pre> to wrap code blocks

use <code></code> to wrap small code snippets

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