KSP Manual

https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/
Admin
Comprehensive reference manual for Kontakt Script Processor (KSP), the scripting language powering...
Tokens:127,284
Snippets:1,162
Trust Score:9.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Picture Configuration File Example

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/control-parameters

This example shows the required format and content for a .txt file accompanying an image file, specifying rendering properties for Kontakt.

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


```

--------------------------------

### Adjust Root Key of First Zone

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/zone-commands

This example demonstrates how to get and set the root key of the first zone using a UI slider. It also displays the number of zones in the instrument.

```ksp
on init
    set_snapshot_type(3) { Must be 2 or 3 or else set_zone_par works only on user zones }

    declare ui_slider $slider (0, 127)
    declare ui_label $label (1, 1)

    $slider := get_zone_par(get_zone_id(0), $ZONE_PAR_ROOT_KEY)

    message("This instrument contains " & get_num_zones() & " zones.")
end on

on ui_control ($slider)
    set_zone_par(get_zone_id(0), $ZONE_PAR_ROOT_KEY, $slider)
    set_text($label, get_zone_par(0, $ZONE_PAR_ROOT_KEY))
end on
```

--------------------------------

### Custom Group Start Options

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/version-history

Allows defining custom group start options, including `NO_SYS_SCRIPT_GROUP_START`.

```ksp
NO_SYS_SCRIPT_GROUP_START
```

--------------------------------

### Create and Configure User Zones

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/zone-commands

This example demonstrates creating two empty user zones and assigning them to different groups using their IDs from the `%NI_USER_ZONE_IDS` array.

```ksp
on init
    set_num_user_zones(2)

    set_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_GROUP, 0)
    set_zone_par(%NI_USER_ZONE_IDS[1], $ZONE_PAR_GROUP, 1)
end on
```

--------------------------------

### Demonstrate Persistent and Non-Persistent Knobs

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/variables

This example shows how to make UI knobs persistent across snapshots and how to make them non-persistent. Persistent variables retain their values when snapshots are loaded.

```ksp
on init
    set_snapshot_type(1)    { init callback not executed upon snapshot loading }

    declare ui_knob $knob_1 (0, 2, 1)
    set_text($knob_1, "Pers")
    make_persistent($knob_1)

    declare ui_knob $knob_2 (0, 2, 1)
    set_text($knob_2, "Inst Pers")
    make_instr_persistent($knob_2)

    declare ui_knob $knob_3 (0, 2, 1)
    set_text($knob_3, "Not Pers")
end on
```

--------------------------------

### set_engine_par() Examples

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/engine-parameter-commands

Examples demonstrating the usage of the set_engine_par() command for controlling instrument volume, filter cutoff, effect bypass, and modulation target intensity.

```APIDOC
## set_engine_par()

### Description
Sets an engine parameter to a specific value.

### Examples
```
on init
    declare ui_knob $Volume (0, 1000000, 1000000)
end on

on ui_control ($Volume)
    set_engine_par($ENGINE_PAR_VOLUME, $Volume, -1, -1, -1)
end on
```
__
_A knob controls the instrument volume._
```
on init
    declare ui_knob $Freq (0, 1000000, 1000000)
    declare ui_button $Bypass
end on

on ui_control ($Freq)
    set_engine_par($ENGINE_PAR_CUTOFF, $Freq, 0, 0, -1)
end on

on ui_control ($Bypass)
    set_engine_par($ENGINE_PAR_EFFECT_BYPASS, $Bypass, 0, 0, -1)
end on
```
__
_Controlling the cutoff and bypass button of any filter module in the first slot of the first group._
```
on init
    declare ui_knob $Knob (-1000, 1000, 10)

    declare $mod_idx
    $mod_idx := get_mod_idx(0, "FILTER_ENV")

    declare $target_idx
    $target_idx := get_target_idx(0, $mod_idx, "ENV_AHDSR_CUTOFF")
end on

on ui_control ($Knob)
    set_engine_par($ENGINE_PAR_MOD_TARGET_MP_INTENSITY, $Knob * 1000, 0, $mod_idx, $target_idx)
end on
```
__
_Controlling the filter envelope amount of an envelope to filter cutoff modulation in the first group. Note: the filter envelope has been manually renamed to "FILTER_ENV"._
```
on init
    declare ui_knob $Vol (0, 1000000, 1000000)
end on

on ui_control ($Vol)
    set_engine_par($ENGINE_PAR_VOLUME, $Vol, -1, -1, $NI_BUS_OFFSET + 15)
end on
```
__
_Controlling the amplifier volume of 16th bus._
```

--------------------------------

### MIDI Harmonizer Example

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/multi-script

A simple harmonizer script that triggers additional notes based on incoming MIDI note events. Ensure correct Note Off commands are also handled.

```ksp
on midi_in
    if ($MIDI_COMMAND = $MIDI_COMMAND_NOTE_ON and $MIDI_BYTE_2 > 0)
        set_midi($MIDI_CHANNEL, $MIDI_COMMAND_NOTE_ON, $MIDI_BYTE_1 + 4, $MIDI_BYTE_2)
        set_midi($MIDI_CHANNEL, $MIDI_COMMAND_NOTE_ON, $MIDI_BYTE_1 + 7, $MIDI_BYTE_2)
    end if

    if ($MIDI_COMMAND = $MIDI_COMMAND_NOTE_OFF or ($MIDI_COMMAND = $MIDI_COMMAND_NOTE_ON and $MIDI_BYTE_2 = 0))
        set_midi($MIDI_CHANNEL, $MIDI_COMMAND_NOTE_ON, $MIDI_BYTE_1 + 4, 0)
        set_midi($MIDI_CHANNEL, $MIDI_COMMAND_NOTE_ON, $MIDI_BYTE_1 + 7, 0)
    end if
end on
```

--------------------------------

### Get Sample File Name

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/zone-commands

Retrieves the file name of the sample associated with a specific zone ID. Always use forward slashes for file paths in Kontakt.

```ksp
message(get_sample(%NI_USER_ZONE_IDS[0], $NI_FILE_NAME))
```

--------------------------------

### Handle Asynchronous File Loading

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/callbacks

This example shows how to use the `on async_complete` callback to manage asynchronous file loading. It pauses the UI control callback until the file is fully loaded by checking the $NI_ASYNC_ID against the loaded file's ID.

```ksp
on init
    declare $load_midi_file_id
    declare ui_button $load_midi_file
end on

on ui_control ($load_midi_file)
    $load_midi_file_id := load_midi_file(<midi-file-path>)

    while ($load_midi_file_id # -1)
        wait(1)
    end while

    message("MIDI file loaded!")
end on

on async_complete
    if ($NI_ASYNC_ID = $load_midi_file_id)
        $load_midi_file_id := -1
    end if
end on
```

--------------------------------

### Release Callback for Note Off

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/callbacks

Demonstrates the release callback, triggered by a MIDI Note Off message. This example creates an artificial release noise by playing a note and changing its volume after a delay.

```ksp
on init
    declare polyphonic $new_id
end on

on release
    wait(1000)
    $new_id := play_note($EVENT_NOTE, $EVENT_VELOCITY, 0, 100000)
    change_vol($new_id, -24000, 1)
end on
```

--------------------------------

### Purge Group Example

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/group-commands

This script demonstrates how to purge all samples from the first group (index 0) using the `purge_group` command. It also shows how to monitor the asynchronous operation's completion and check the purge state.

```ksp
on init
    declare $async_id := -1
    declare ui_button $purge

    set_text($purge,"Purge first group")
end on

on ui_control ($purge)
    $async_id := purge_group(0, abs($purge - 1))
end on

on async_complete
    if ($NI_ASYNC_ID = $async_id)
        if (get_purge_state(0) = 0)
            message("Group is purged")
        else
            message("Group is not purged")
        end if
    end if
end on
```

--------------------------------

### Monitor Incoming MIDI Messages

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/multi-script

The on midi_in callback is triggered for every incoming MIDI event. This example demonstrates how to identify and display messages for Note On, Note Off, Controller, Pitch Bend, Channel Pressure, Poly Pressure, and Program Change.

```ksp
on midi_in
    select ($MIDI_COMMAND)
        case $MIDI_COMMAND_NOTE_ON
            if ($MIDI_BYTE_2 > 0)
                message("Note On")
            else
                message("Note Off")
            end if
        case $MIDI_COMMAND_NOTE_OFF
            message("Note Off")
        case $MIDI_COMMAND_CC
            message("Controller")
        case $MIDI_COMMAND_PITCH_BEND
            message("Pitch Bend")
        case $MIDI_COMMAND_MONO_AT
            message("Channel Pressure")
        case $MIDI_COMMAND_POLY_AT
            message("Poly Pressure")
        case $MIDI_COMMAND_PROGRAM_CHANGE
            message("Program Change")
    end select
end on
```

--------------------------------

### Display Menu Item Value

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/user-interface-commands

This example retrieves and displays the numerical value of a specific menu item from a `ui_menu` widget when a button is clicked. It uses `get_menu_item_value()` to get the value based on the item's index.

```ksp
on init
 
    declare ui_button $button
    declare ui_menu $menu

    add_menu_item($menu, "First Entry", 0)
    add_menu_item($menu, "Second Entry", 5)
    add_menu_item($menu, "Third Entry", 10)
end on

on ui_control ($button)
 
    message(get_menu_item_value(get_ui_id($menu), 1))
end on
```

--------------------------------

### Get Voice Limit for Sampler Modes

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/engine-parameter-commands

This example shows how to retrieve the voice limit for different quality modes (Standard and HQ) in the Time Machine Pro sampler. It's useful for displaying sampler capabilities.

```knob
on init
    declare ui_label $label (3, 2)

    add_text_line($label, "Standard Voice Limit: " &  get_voice_limit($NI_VL_TMPRO_STANDARD))
    add_text_line($label, "HQ Voice Limit: " & get_voice_limit($NI_VL_TMPRO_HQ))
end on
```

--------------------------------

### Create and Set Key Values with PGS

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/callbacks

Demonstrates how to create keys with specified element counts and set their values using pgs_create_key and pgs_set_key_val. Use when interacting with persistent storage for key-value pairs.

```ksp
on init
    pgs_create_key(FIRST_KEY, 1)    { defines a key with 1 element }
    pgs_create_key(NEXT_KEY, 128)   { defines a key with 128 elements }

    declare ui_button $Push
end on

on ui_control($Push)
    pgs_set_key_val(FIRST_KEY, 0, 70 * $Push)
    pgs_set_key_val(NEXT_KEY, 0, 50 * $Push)
    pgs_set_key_val(NEXT_KEY, 127, 60 * $Push)
end on
```

--------------------------------

### Initialize Instrument and Handle Sample Drop

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/music-information-retrieval

Initializes the instrument, sets up a drop area for samples, and processes dropped audio files. It then detects the pitch of the sample and sets the zone's root key and tune based on the detected pitch.

```ksp
on init
    message("")

    declare ~pitch_result

    set_num_user_zones(1)

    declare ui_mouse_area $Drop
    declare ui_label $Info (1, 1)

    set_text($Info, "Drop sample here!")

    move_control_px($Drop, 66, 2)
    move_control_px($Info, 66, 2)

    set_control_par(get_ui_id($Drop), $CONTROL_PAR_DND_ACCEPT_AUDIO, $NI_DND_ACCEPT_ONE)
    set_control_par(get_ui_id($Drop), $CONTROL_PAR_WIDTH, 150)
    set_control_par(get_ui_id($Info), $CONTROL_PAR_WIDTH, 150)

    set_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_HIGH_KEY, 127)
    set_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_LOW_VELO, 1)
    set_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_HIGH_VELO, 127)
    set_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_GROUP, 0)
end on

on ui_control ($Drop)
    if ($NI_MOUSE_EVENT_TYPE = $NI_MOUSE_EVENT_TYPE_DROP)
        wait_async(set_sample(%NI_USER_ZONE_IDS[0], !NI_DND_ITEMS_AUDIO[0]))

        wait_async(detect_pitch(%NI_USER_ZONE_IDS[0], ~pitch_result))
        wait_async(set_zone_par(%NI_USER_ZONE_IDS[0], ...
                                $ZONE_PAR_ROOT_KEY, ...
                                int(round(~pitch_result))))
        wait_async(set_zone_par(%NI_USER_ZONE_IDS[0], ...
                                $ZONE_PAR_TUNE, ...
                                int(100.0 * (round(~pitch_result) - ~pitch_result))
    end if
end on
```

--------------------------------

### Initialize UI and Handle Notes

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/general-commands

Initializes UI elements like labels and tables, sets their properties, and handles note on/off events. It also demonstrates setting note controllers for pitch bend and updating UI states based on note activity.

```ksp
on init
    set_ui_height(3)

    declare $i
    declare %black[5] := (1, 3, 6, 8, 10)
    declare %key_id[128]

    declare ui_label $L (1, 1)
    declare ui_table %Active[61] (6, 1, 1)
    declare ui_table %BG[61] (6, 1, 1)
    declare ui_table %KB[61] (6, 1, -8191)

    set_control_par(get_ui_id(%KB), $CONTROL_PAR_HIDE, $HIDE_PART_BG .or. $HIDE_PART_VALUE)
    set_control_par(get_ui_id(%KB), $CONTROL_PAR_WIDTH, 555)
    set_control_par(get_ui_id(%KB), $CONTROL_PAR_HEIGHT, 110)

    set_control_par(get_ui_id(%BG), $CONTROL_PAR_HIDE, $HIDE_PART_BG)
    set_control_par(get_ui_id(%BG), $CONTROL_PAR_WIDTH, 555)
    set_control_par(get_ui_id(%BG), $CONTROL_PAR_HEIGHT, 110)
    set_control_par(get_ui_id(%BG), $CONTROL_PAR_BAR_COLOR, 0777777H)

    set_control_par(get_ui_id(%Active), $CONTROL_PAR_WIDTH, 555)
    set_control_par(get_ui_id(%Active), $CONTROL_PAR_HEIGHT, 110)
    set_control_par(get_ui_id(%Active), $CONTROL_PAR_BAR_COLOR, 0AAAAAAH)

    set_control_par(get_ui_id($L), $CONTROL_PAR_HIDE, $HIDE_PART_BG)
    set_control_par(get_ui_id($L), $CONTROL_PAR_WIDTH, 560)
    set_control_par(get_ui_id($L), $CONTROL_PAR_FONT_TYPE, 19)

    set_text($L, "C1                               " & ...
                 "C2                               " & ...
                 "C3                               " & ...
                 "C4                               " & ...
                 "C5                               " & ...
                 "C6")

    while ($i < num_elements(%BG))
        if (search(%black, $i mod 12) # -1)
            %BG[$i] := 1
        end if

        inc($i)
    end while

    move_control_px($L, 55, 0)
    move_control_px(%BG, 62, 15)
    move_control_px(%Active, 62, 15)
    move_control_px(%KB, 62, 15)
end on

on note
    { make sure we only have one event per key }
    if (event_status(%key_id[$EVENT_NOTE]) = $EVENT_STATUS_NOTE_QUEUE)
        fade_out(%key_id[$EVENT_NOTE], 1000, 1)
    end if

    %key_id[$EVENT_NOTE] := $EVENT_ID

    set_note_controller($VNC_PITCH_BEND, $EVENT_NOTE, %KB[$EVENT_NOTE - 36])

    if (in_range($EVENT_NOTE, 36, 96))
        %Active[$EVENT_NOTE - 36] := 1
    end if
end on

on release
    if (in_range($EVENT_NOTE, 36, 96))
        %Active[$EVENT_NOTE - 36] := 0
    end if
end on

on ui_control (%KB)
    set_note_controller($VNC_PITCH_BEND, 36 + $NI_CONTROL_PAR_IDX, %KB[$NI_CONTROL_PAR_IDX])
end on
```

--------------------------------

### Initialize UI and Handle Keyboard/Note Events

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/general-commands

This snippet initializes a virtual keyboard UI, including background, active key, and KB tables. It handles note on/off events to update the active keys and uses polyphonic aftertouch to control the KB table values. The `on_poly_at` callback updates the KB table based on incoming polyphonic aftertouch messages.

```ksp
on init
    set_ui_height(3)

    declare $i
    declare %black[5] := (1, 3, 6, 8, 10)

    declare ui_label $L (1, 1)
    declare ui_table %Active[61] (6, 1, 1)
    declare ui_table %BG[61] (6, 1, 1)
    declare ui_table %KB[61] (6, 1, 127)

    set_control_par(get_ui_id(%KB), $CONTROL_PAR_HIDE, $HIDE_PART_BG .or. $HIDE_PART_VALUE)
    set_control_par(get_ui_id(%KB), $CONTROL_PAR_WIDTH, 555)
    set_control_par(get_ui_id(%KB), $CONTROL_PAR_HEIGHT, 110)

    set_control_par(get_ui_id(%BG), $CONTROL_PAR_HIDE, $HIDE_PART_BG)
    set_control_par(get_ui_id(%BG), $CONTROL_PAR_WIDTH, 555)
    set_control_par(get_ui_id(%BG), $CONTROL_PAR_HEIGHT, 110)
    set_control_par(get_ui_id(%BG), $CONTROL_PAR_BAR_COLOR, 0777777H)

    set_control_par(get_ui_id(%Active), $CONTROL_PAR_WIDTH, 555)
    set_control_par(get_ui_id(%Active), $CONTROL_PAR_HEIGHT, 110)
    set_control_par(get_ui_id(%Active), $CONTROL_PAR_BAR_COLOR, 0AAAAAAH)

    set_control_par(get_ui_id($L), $CONTROL_PAR_HIDE, $HIDE_PART_BG)
    set_control_par(get_ui_id($L), $CONTROL_PAR_WIDTH, 560)
    set_control_par(get_ui_id($L), $CONTROL_PAR_FONT_TYPE, 19)

    set_text($L, "C1                               " & ...
                 "C2                               " & ...
                 "C3                               " & ...
                 "C4                               " & ...
                 "C5                               " & ...
                 "C6")

    while ($i < num_elements(%BG))
        if (search(%black, $i mod 12) # -1)
            %BG[$i] := 1
        end if

        inc($i)
    end while

    move_control_px($L, 55, 0)
    move_control_px(%BG, 62, 15)
    move_control_px(%Active, 62, 15)
    move_control_px(%KB, 62, 15)
end on

on note
    if (in_range($EVENT_NOTE, 36, 96))
        %Active[$EVENT_NOTE - 36] := 1
    end if
end on

on release
    if (in_range($EVENT_NOTE, 36, 96))
        %Active[$EVENT_NOTE - 36] := 0
    end if
end on

on ui_control (%KB)
    set_poly_at(36 + $NI_CONTROL_PAR_IDX, %KB[$NI_CONTROL_PAR_IDX])
end on

on poly_at
    if (in_range($POLY_AT_NUM, 36, 96))
        %KB[$POLY_AT_NUM - 36] := %POLY_AT[$POLY_AT_NUM]
    end if
end on
```

--------------------------------

### Get Engine Parameter Display Value - Kontakt 8

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/version-history

Command to get the display value of an engine parameter based on an externally provided value, added in Kontakt 8.

```ksp
get_engine_par_disp_ext()
```

--------------------------------

### get_sample()

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/zone-commands

Returns paths, file names and extensions of samples. Works on both normal and user zones.

```APIDOC
## get_sample
### Description
Returns paths, file names and extensions of samples.
### Signature
`get_sample(<zone-id>, <return-parameter>)`
### Parameters
#### Path Parameters
- **zone-id** (int) - The ID of the zone.
- **return-parameter** (enum) - The following parameters are available: `$NI_FILE_NAME`, `$NI_FILE_FULL_PATH`, `$NI_FILE_FULL_PATH_OS`, `$NI_FILE_EXTENSION`
### Remarks
`get_sample()` works on both normal and user zones.
Always use forwards slash (`/`) when working with absolute file paths in Kontakt!
### Examples
```
message(get_sample(%NI_USER_ZONE_IDS[0], $NI_FILE_NAME))
```
```

--------------------------------

### Get Display Value of Engine Parameter with Custom Value

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/engine-parameter-commands

This function allows you to get the display string for an engine parameter at a specific, arbitrary value, not just its current setting. This is useful for previewing parameter changes.

```ksp
get_engine_par_disp_ext(<parameter>, <value>, <group>, <slot>, <generic>)
```

--------------------------------

### Get Event IDs Command

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/version-history

Adds a command to retrieve unique identifiers for events.

```ksp
get_event_ids()
```

--------------------------------

### Add and Control Menu Items

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/user-interface-commands

Demonstrates adding menu items with specific values and controlling their visibility based on a button press. Also shows how to retrieve the visibility state.

```ksp
on init
 	declare ui_button $visibility
 	declare ui_button $value
 	declare ui_menu $menu

 	add_menu_item($menu, "First Entry", 0)
 	add_menu_item($menu, "Second Entry", 5)
 	add_menu_item($menu, "Third Entry", 10)
end on

on ui_control ($visibility)
 	set_menu_item_visibility(get_ui_id($menu), 1, $visibility)
end on

on ui_control ($value)
 	message(get_menu_item_visibility(get_ui_id($menu), 1))
end on
```

--------------------------------

### Get Factory Directory Path

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/version-history

Provides a variable to retrieve the path to the Kontakt factory directory.

```ksp
$GET_FOLDER_FACTORY_DIR
```

--------------------------------

### Set Sample via Drag and Drop

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/zone-commands

This snippet handles a drag-and-drop event to set a sample for the first user zone. It checks if exactly one audio item was dropped and uses `wait_async` for the `set_sample` command.

```ksp
on ui_control ($myMouseArea)    
    if ($NI_MOUSE_EVENT_TYPE = $NI_MOUSE_EVENT_TYPE_DROP)      
        if (num_elements(!NI_DND_ITEMS_AUDIO) = 1)            
            wait_async(set_sample(%NI_USER_ZONE_IDS[0], !NI_DND_ITEMS_AUDIO[0]))
        end if
    end if
end on
```

--------------------------------

### Get Control Parameter Index

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/version-history

Retrieve the index of a built-in control parameter using `$NI_CONTROL_PAR_IDX`.

```ksp
$NI_CONTROL_PAR_IDX
```

--------------------------------

### Get Release Trigger Groups

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/engine-parameter-commands

Iterates through all groups to identify and list those with release triggers enabled.

```ksp
on init
    declare $i

    declare ui_label $label (2, 6)
    set_text($label,"Release Trigger Groups:")

    while ($i < $NUM_GROUPS)
        if (get_engine_par($ENGINE_PAR_RELEASE_TRIGGER, $i, -1, -1) = 1)
            add_text_line($label, group_name($i) & " (Index: " & $i & ")")
        end if

        inc($i)
    end while
end on
```

--------------------------------

### Quickly Create a UI Menu with Many Entries

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/user-interface-widgets

Dynamically creates a UI menu with 20 entries, each labeled sequentially and assigned a corresponding integer value.

```ksp
on init
    declare $count
    declare ui_menu $menu

    $count := 0
    while ($count < 20)
        add_menu_item($menu, "Entry #" & $count + 1, $count)

        inc($count)
    end while
end on
```

--------------------------------

### Initialize MIDI File Loader and Export Areas

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/midi-object-commands

Sets up the MIDI file loader, defines drag-and-drop areas, and configures them for exporting MIDI tracks. Utilizes `mf_get_last_filename()` to display the loaded MIDI file name.

```ksp
on init
    message("")
    make_perfview

    declare const $DND_AREAS := 4

    declare ui_label $label1 (1,1)
    declare ui_label $label2 (1,1)
    declare ui_label $label3 (1,1)
    declare ui_label $label4 (1,1)

    declare $i
    declare %ID[$DND_AREAS]
    %ID[0] := get_ui_id($label1)
    %ID[1] := get_ui_id($label2)
    %ID[2] := get_ui_id($label3)
    %ID[3] := get_ui_id($label4)
    declare !track_names[$DND_AREAS]
    !track_names[0] := "Synth 1"
    !track_names[1] := "Synth 2"
    !track_names[2] := "Bass"
    !track_names[3] := "Melody"

    mf_insert_file(get_folder($GET_FOLDER_PATCH_DIR) & "my_midi.mid", 0, 0, 0)
    { declare export areas, area 0 serves as an edit buffer, so add one extra }
    mf_set_num_export_areas($DND_AREAS + 1)

    $i := 0
    while ($i < $DND_AREAS)
        set_control_par(%ID[$i], $CONTROL_PAR_DND_BEHAVIOUR, 1)
        set_control_par(%ID[$i], $CONTROL_PAR_MIDI_EXPORT_AREA_IDX, $i + 1)
        set_control_par_str(%ID[$i], $CONTROL_PAR_TEXT, mf_get_last_filename & " " & !track_names[$i])

        mf_set_export_area(!track_names[$i], -1, -1, $i, $i)
        mf_copy_export_area($i + 1)

        inc($i)
    end while
end on
```

--------------------------------

### Get Number of Menu Items

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/control-parameters

Retrieve the number of entries in a `ui_menu`. This function only works with `get_control_par()`.

```ksp
$CONTROL_PAR_NUM_ITEMS
```

--------------------------------

### Get Number of MIDI Tracks

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/midi-object-commands

Retrieves the total number of tracks present in the loaded MIDI object.

```ksp
mf_get_num_tracks()
```

--------------------------------

### Initialize UI and Persistent Variables

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/callbacks

Initializes UI elements and handles persistent variables for synchronization. It shows how to set up buttons and menus, make variables persistent, and read their values on initialization.

```ksp
on init
    declare ui_button $Sync
    declare ui_menu $Time

    add_menu_item($Time, "16th", 0)
    add_menu_item($Time, "8th", 1)

    $Sync := 0   { sync is off by default, so hide menu }

    move_control($Time, 0, 0)
    move_control($Sync, 1, 1)

    make_persistent($Sync)
    make_persistent($Time)

    read_persistent_var ($Sync)

    if ($Sync = 1)
        move_control($time, 2, 1)
    else
        move_control($Time, 0, 0)
    end if
end on

on ui_control ($Sync)
    if ($Sync = 1)
        move_control($Time, 2, 1)
    else
        move_control($Time, 0, 0)
    end if
end on
```

--------------------------------

### Get Event Parameter (Source)

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/event-commands

Checks the source of an event. Returns -1 for external sources and 0-4 for script slots.

```Kontakt Script
on note
    message(get_event_par($EVENT_ID, $EVENT_PAR_SOURCE))
end on
```

--------------------------------

### set_sample()

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/zone-commands

Sets the user sample within a specified zone. This command is applicable only to user zones and has asynchronous behavior outside the 'on init' callback. File paths should use forward slashes.

```APIDOC
## set_sample()

`set_sample(<zone-id>, <path>)`  

---

Sets the user sample in a zone.  

`<zone-id>`| The ID of the zone.  
`<path>`| The file path to the sample to be loaded.  

#### Remarks
  * `set_sample()` only works on user zones.
  * When executed in the `on init` callback, this function runs synchronously and returns **-1**.
  * When executed outside of the `on init` callback, this function returns an async ID and triggers the `on async_complete` callback.
  * Since Kontakt 7.2, the performance of this command has been improved. Previously, every execution of this command required suspending then resuming the audio engine. Moving forward, execution of this command has been delayed until the first `wait()` command, or until the end of the callback, whichever comes first. So, if it is required to set a lot of zone parameters in batch, it is recommended to first collect all the async IDs into an array, and only then run any `wait()` commands, as shown in the description of `wait_async()` command.
  * Always use forwards slash (`/`) when working with absolute file paths in Kontakt!


#### Examples
```
on ui_control ($myMouseArea)    
    if ($NI_MOUSE_EVENT_TYPE = $NI_MOUSE_EVENT_TYPE_DROP)      
        if (num_elements(!NI_DND_ITEMS_AUDIO) = 1)            
            wait_async(set_sample(%NI_USER_ZONE_IDS[0], !NI_DND_ITEMS_AUDIO[0]))
        end if
    end if
end on

```
 __
#### See Also
get_sample()
wait_async()
```

--------------------------------

### Set Wallpaper via Script

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/version-history

Use the new ID `$INST_WALLPAPER_ID` to set instrument wallpapers through scripting.

```ksp
$INST_WALLPAPER_ID
```

--------------------------------

### Get Event Parameter (Note)

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/event-commands

Retrieves the note number of an event. This is functionally equivalent to using the $EVENT_NOTE variable directly.

```Kontakt Script
on note
    message(get_event_par($EVENT_ID, $EVENT_PAR_NOTE))
end on
```

--------------------------------

### Get Selected Menu Item Index

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/control-parameters

Retrieve the index of the currently selected menu entry in a `ui_menu`. This function only works with `get_control_par()`.

```ksp
$CONTROL_PAR_SELECTED_ITEM_IDX
```

--------------------------------

### Initialize and Display Key Names

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/keyboard-commands

Initializes all key names to empty strings and then sets a specific key to 'Middle C'. Responds to note events by displaying the name of the pressed key.

```nks
on init
    declare $count

    while ($count < 128)
        set_key_name($count, "")

        inc($count)
    end while

    set_key_name(60, "Middle C")
end on

on note
    message(get_key_name($EVENT_NOTE))
end on
```

--------------------------------

### set_loop_par()

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/zone-commands

Sets various parameters for loops within a user zone, including mode, start point, length, crossfade, count, and tuning.

```APIDOC
## set_loop_par()
`set_loop_par(<zone-id>, <loop-index>, <parameter>, <value>`

### Description
Sets the loop parameters of a user zone.

### Parameters
#### Path Parameters
- **zone-id** (integer) - Required - The ID of the zone.
- **loop-index** (integer) - Required - The index of the loop (**0 ... 7**).
- **parameter** (constant) - Required - The following parameters are available:
    - `$LOOP_PAR_MODE`
    - `$LOOP_PAR_START`
    - `$LOOP_PAR_LENGTH`
    - `$LOOP_PAR_XFADE`
    - `$LOOP_PAR_COUNT`
    - `$LOOP_PAR_TUNING`
- **value** (integer/float) - Required - The value of the loop parameter.
```

--------------------------------

### Load and Save Array with UI Buttons

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/load-save-commands

This example demonstrates loading and saving array data from a UI table using `load_array` and `save_array`. It handles asynchronous completion and updates the UI accordingly. Note that `load_array` in mode 0 has implicit persistence behavior.

```Kontakt Script
on init
 	declare $count
 	declare $load_arr_id := -1
 	declare $save_arr_id := -1
 	declare %preset[8]

 	declare ui_button $Load
 	declare ui_button $Save
 	declare ui_table %table[8] (2,2,100)

 	make_persistent(%table)
end on

on ui_control (%table)
 	$count := 0
 	while ($count < 8)
 		%preset[$count] := %table[$count]

 		inc($count)
 	end while
end on

on ui_control ($Load)
 	$load_arr_id := load_array(%preset, 0)
end on

on ui_control ($Save)
 	$save_arr_id := save_array(%preset, 0)
end on

on async_complete
 	if ($NI_ASYNC_ID = $load_arr_id)
 		$load_arr_id := -1
 		$Load := 0

 		if ($NI_ASYNC_EXIT_STATUS = 1)
 			$count := 0
 			while($count < 8)
 				%table[$count] := %preset[$count]

 				inc($count)
 			end while
 		end if
 	end if

 	if ($NI_ASYNC_ID = $save_arr_id)
 		$save_arr_id := -1
 		$Save := 0
 	end if
end on
```

--------------------------------

### Display Group Names in a Label

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/group-commands

This example displays the names of groups stored in an array (`%GROUPS_AFFECTED`) in a UI label. It clears the label on release.

```ksp
on init
    declare $count
    declare ui_label $label (2, 6)

    set_text($label, "")
end on

on note
    $count := 0
    while ($count < num_elements(%GROUPS_AFFECTED))
        add_text_line($label, group_name(%GROUPS_AFFECTED[$count]))

        inc($count)
    end while
end on

on release
    set_text($label, "")
end on
```

--------------------------------

### Load MIDI File with Button

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/midi-object-commands

Loads a MIDI file when a UI button is pressed. Requires a MIDI file named 'test.mid' in the factory data folder. Uses async completion to verify loading status.

```NKS
on init
    declare $load_mf_id := -1
    declare @file_name
    declare @filepath

    @file_name := "test.mid"
    @filepath := get_folder($GET_FOLDER_FACTORY_DIR) & @file_name

    declare ui_button $load_file
end on

on ui_control($load_file)
    $load_mf_id := mf_insert_file(@filepath, 0, 0, 0)
end on

on async_complete
    if ($NI_ASYNC_ID = $load_mf_id)
        $load_mf_id := -1

        if ($NI_ASYNC_EXIT_STATUS = 0)
            message("ERROR: MIDI file not found!")
        else
            message("Loaded MIDI file: " & @file_name & "!")
        end if
    end if
end on
```

--------------------------------

### Get Output Type and Index - Kontakt 8.4

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/version-history

Retrieve the output type and index set by redirect_output(). Requires Kontakt 8.4 or later.

```ksp
get_event_par(event_id, $EVENT_PAR_OUTPUT_TYPE)
get_event_par(event_id, $EVENT_PAR_OUTPUT_INDEX)
```

--------------------------------

### Load Custom Instrument Wallpaper

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/control-parameters

Load a custom wallpaper for the instrument using `$INST_WALLPAPER_ID` and `$CONTROL_PAR_PICTURE`. This command is restricted to the 'on init' callback and only supports wallpapers within the Resource Container.

```ksp
set_control_par_str($INST_WALLPAPER_ID, $CONTROL_PAR_PICTURE, <file_name>)
```

--------------------------------

### Get Zone Pan Parameter

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/zone-commands

Retrieves the pan parameter for the first user zone ID. Ensure the zone ID is valid before calling.

```ksp
get_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_PAN)
```

--------------------------------

### Get Kontakt Factory Data Folder Path

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/load-save-commands

Displays the path to Kontakt's factory data folder using the `$GET_FOLDER_FACTORY_DIR` variable.

```KSP
on init
    message(get_folder($GET_FOLDER_FACTORY_DIR))
end on
```

--------------------------------

### Initialize and Color Keyboard Keys

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/keyboard-commands

Initializes the keyboard by setting all keys to inactive or none, then applies specific colors to white keys based on a predefined color array. This is useful for creating visual patterns or feedback on the keyboard.

```ksp
on init
    message("")

    declare ui_button $Color

    declare $count
    declare $note_count
    declare $color_count
    declare %white_keys[7] := (0, 2, 4, 5, 7, 9, 11)
    declare %colors[16] := ( ...
        $KEY_COLOR_RED, ...
        $KEY_COLOR_ORANGE, ...
        $KEY_COLOR_LIGHT_ORANGE, ...
        $KEY_COLOR_WARM_YELLOW, ...
        $KEY_COLOR_YELLOW, ...
        $KEY_COLOR_LIME, ...
        $KEY_COLOR_GREEN, ...
        $KEY_COLOR_MINT, ...
        $KEY_COLOR_CYAN, ...
        $KEY_COLOR_TURQUOISE, ...
        $KEY_COLOR_BLUE, ...
        $KEY_COLOR_PLUM, ...
        $KEY_COLOR_VIOLET, ...
        $KEY_COLOR_PURPLE, ...
        $KEY_COLOR_MAGENTA, ...
        $KEY_COLOR_FUCHSIA)

    $count := 0
    while ($count < 128)
        set_key_color($count, $KEY_COLOR_NONE)

        inc($count)
    end while
end on

on ui_control ($Color)
    if ($Color = 1)
        $count := 0
        while ($count < 128)
            set_key_color($count, $KEY_COLOR_INACTIVE)
            inc($count)
        end while

        $note_count := 0
        $color_count := 0
        while ($color_count < 16)
            if (search(%white_keys, (60 + $note_count) mod 12) # -1)
                set_key_color(60 + $note_count, %colors[$color_count])
                inc($color_count)
            end if

            inc($note_count)
        end while
    else
        $count := 0
        while ($count < 128)
            set_key_color($count, $KEY_COLOR_NONE)

            inc($count)
        end while
    end if
end on

```

--------------------------------

### Get Loop Parameter Value

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/zone-commands

Retrieves the value of a specific loop parameter for a given zone and loop index. Works on both normal and user zones.

```ksp
message(get_loop_par($myZoneId, 0, $LOOP_PAR_MODE))
```

--------------------------------

### Handle Persistence with New Commands

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/version-history

Manage instrument persistence using new commands for snapshots and making instruments persistent.

```ksp
set_snapshot_type()
```

```ksp
make_instr_persistent()
```

--------------------------------

### Get Modulator Index and Engine Parameter

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/engine-parameter-commands

Retrieves the index of a volume envelope modulator and then its attack time. This is useful for dynamically controlling envelope parameters.

```ksp
on init
    declare $grp_idx := 0
    declare $env_idx

    $env_idx := get_mod_idx($grp_idx, "VOL_ENV")

    declare ui_knob $Attack (0, 1000000, 1)

    $Attack := get_engine_par($ENGINE_PAR_ATTACK, $grp_idx, $env_idx, -1)

    set_knob_unit($Attack, $KNOB_UNIT_MS)
    set_knob_label($Attack, get_engine_par_disp($ENGINE_PAR_ATTACK, $grp_idx, $env_idx, -1))
end on

on ui_control ($Attack)
    set_engine_par($ENGINE_PAR_ATTACK, $Attack, $grp_idx, $env_idx, -1)
    set_knob_label($Attack, get_engine_par_disp($ENGINE_PAR_ATTACK, $grp_idx, $env_idx, -1))
end on
```

--------------------------------

### get_ui_id()

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/user-interface-commands

Retrieves the UI ID number of a UI widget. UI IDs are assigned sequentially from the very first variable or constant declared in the script, starting at 32768.

```APIDOC
## get_ui_id()
`get_ui_id(<variable>)`

### Description
Retrieves the UI ID number of a UI widget.

### Remarks
* UI IDs are assigned sequentially from the very first variable or constant declared in the script, which starts at **32768**.
* Even regular variables and constants (those that are not UI widgets) get a UI ID assigned, however this ID cannot be used with various `get_control_par()/set_control_par()` commands!

### Examples
```APIDOC
on init
    declare const $NUM_KNOBS := 4

    declare ui_knob $Knob_1 (0, 100, 1)
    declare ui_knob $Knob_2 (0, 100, 1)
    declare ui_knob $Knob_3 (0, 100, 1)
    declare ui_knob $Knob_4 (0, 100, 1)

    declare ui_value_edit $Set (0, 100, 1)

    declare $i
    declare %ID[$NUM_KNOBS]

    while ($i < $NUM_KNOBS)
        %ID[$i] := get_ui_id($Knob_1) + $i

        inc($i)
    end while
end on

on ui_control ($Set)
    $i := 0
    while ($i < $NUM_KNOBS)
        set_control_par(%ID[$i], $CONTROL_PAR_VALUE, $Set)
        inc($i)
    end while
end on
```
### See Also
set_control_par()
get_control_par()
```

--------------------------------

### Implement a UI File Selector for MIDI Files

Source: https://www.native-instruments.com/ni-tech-manuals/ksp-manual/en/user-interface-widgets

Creates a file selector in the performance view for loading MIDI files. It configures the browser path, file type, and dimensions, and handles asynchronous loading completion.

```ksp
on init
    message("")
    set_ui_height(5)

    declare $load_mf_id := -1
    declare @file_name
    declare @file_path
    declare @basepath
    { set browser path here, for example:
    @basepath := "/Users/username/Desktop/MIDI Files/" }

    declare ui_file_selector $file_browser

    declare $browser_id
    $browser_id := get_ui_id($file_browser)

    set_control_par_str($browser_id, $CONTROL_PAR_BASEPATH, @basepath)
    set_control_par($browser_id, $CONTROL_PAR_FILE_TYPE, $NI_FILE_TYPE_MIDI)
    set_control_par($browser_id, $CONTROL_PAR_COLUMN_WIDTH, 180)
    set_control_par($browser_id, $CONTROL_PAR_HEIGHT, 170)
    set_control_par($browser_id, $CONTROL_PAR_WIDTH, 550)

    move_control_px($file_browser, 66, 2)

    declare ui_button $prev
    declare ui_button $next

    move_control($prev, 5, 1)
    move_control($next, 6, 1)
end on

on async_complete
    if ($NI_ASYNC_ID = $load_mf_id)
        $load_mf_id := -1

        if ($NI_ASYNC_EXIT_STATUS = 0)
            message("MIDI file not found!")
        else
            message("Loaded MIDI File: " & @file_name)
        end if
    end if
end on

on ui_control ($file_browser)
    @file_name := fs_get_filename($browser_id, 0)
    @file_path := fs_get_filename($browser_id, 2)
    $load_mf_id := load_midi_file(@file_path)
end on

on ui_control ($prev)
    { calls 'on ui_control ($file_browser)' }
    fs_navigate($browser_id, 0)
    $prev := 0
end on

on ui_control ($next)
    { calls 'on ui_control ($file_browser)' }
    fs_navigate($browser_id, 1)
    $next := 0
end on
```
Tokens:
Raw