Skip to main content
  • KSP Reference Manual
  • Keyboard Commands

Keyboard Commands

get_key_color()

get_key_color(<note-number>)

Returns the color constant of the specified note number.

Examples

on init
    message("")

    declare $count

    while ($count < 128)
        set_key_color($count, $KEY_COLOR_INACTIVE)

        inc($count)
    end while

    declare $random_key
    $random_key := random(60, 71)

    set_key_color($random_key, $KEY_COLOR_RED)
end on

on note
    if (get_key_color($EVENT_NOTE) = $KEY_COLOR_RED)
        message("Bravo!")

        set_key_color($random_key, $KEY_COLOR_INACTIVE)
        $random_key := random(60, 71)
        set_key_color($random_key, $KEY_COLOR_RED)
    else
        message("Try again!")
    end if
end on

on release
    message("")
end on

Catch me if you can.

See Also

set_key_color()

get_key_name()

get_key_name(<note-number>)

Returns the name of the specified note number.

Examples

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

See Also

set_key_name()

get_key_triggerstate()

get_key_triggerstate(<note-number>)

Returns the pressed state of the specified note number, i.e. key, on the Kontakt keyboard. It can be either 1 (key pressed) or 0 (key released).

Remarks

Examples

on init
    set_key_pressed_support(1)
end on

on note
    set_key_pressed($EVENT_NOTE, 1)
    message(get_key_triggerstate($EVENT_NOTE))
end on

on release
    set_key_pressed($EVENT_NOTE, 0)
    message(get_key_triggerstate($EVENT_NOTE))
end on

See Also

set_key_pressed()

set_key_pressed_support()

get_key_type()

get_key_type(<note-number>)

Returns the key type constant of the specified note number.

See Also

set_key_type()

get_keyrange_min_note()

get_keyrange_min_note(<note-number>)

Returns the lowest note of the specified key range.

Remarks

  • Since a key range cannot have overlapping notes, it is sufficient with all get_keyrange_... commands to specify the key range with one note number only.

Examples

on init
    declare $count
    while ($count < 128)
        remove_keyrange($count)

        inc($count)
    end while

    set_keyrange(36, 72, "Middle Range")
end on

on note
    message(get_keyrange_min_note($EVENT_NOTE))
end on

See Also

set_keyrange()

get_keyrange_max_note()

get_keyrange_max_note(<note-number>)

Returns the highest note of the specified key range.

Remarks

  • Since a key range cannot have overlapping notes, it is sufficient with all get_keyrange_... commands to specify the key range with one note number only.

Examples

on init
    declare $count
    while ($count < 128)
        remove_keyrange($count)

        inc($count)
    end while

    set_keyrange(36, 72, "Middle Range")
end on

on note
    message(get_keyrange_max_note($EVENT_NOTE))
end on

See Also

set_keyrange()

get_keyrange_name()

get_keyrange_name(<note-number>)

Returns the name of the specified key range.

Remarks

  • Since a key range cannot have overlapping notes, it is sufficient with all get_keyrange_... commands to specify the key range with one note number only.

Examples

on init
    declare $count
    while ($count < 128)
        remove_keyrange($count)

        inc($count)
    end while

    set_keyrange(36, 72, "Middle Range")
end on

on note
    message(get_keyrange_name($EVENT_NOTE))
end on

See Also

set_keyrange()

set_key_color()

set_key_color(<note-number>, <key-color-constant>)

Sets the color of the specified key, i.e. MIDI note, on the Kontakt virtual keyboard.

<note-number>

MIDI note number of the key (0 ... 127).

<key-color-constant>

One of available key color constant to specify the color used. The following constants are available:

$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

$KEY_COLOR_DEFAULT Sets the key to Kontakt's standard color for mapped notes

$KEY_COLOR_INACTIVE Resets the key to standard black and white

$KEY_COLOR_NONE Resets the key to its normal Kontakt color, e.g. red for internal keyswitches

Remarks

  • The keyboard colors reside outside of KSP, i.e. changing the color of a key is similar to changing a Kontakt knob with set_engine_par(). It is therefore a good practice to set all keys to either $KEY_COLOR_INACTIVE or $KEY_COLOR_NONE in the on init callback.

Example

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

Kontakt rainbow.

See Also

set_control_help()

get_key_color()

set_key_name()

set_keyrange()

set_key_name()

set_key_name(<note-number>, <name>)

Assigns a text string to the specified note number.

<note-number>

MIDI note number of the key (0 ... 127).

<name>

Text string to assign.

Remarks

  • Key names are instrument parameters and reside outside of KSP, i.e. changing the key name is similar to changing a Kontakt knob with set_engine_par(). Make sure to always reset all key names in the on init callback.

  • Key names and ranges are displayed in Kontakt's info pane when hovering the mouse over the key on the Kontakt keyboard.

Examples

on init
    declare $count

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

        inc($count)
    end while

    set_key_name(60, "Middle C")
end on

See Also

set_keyrange()

get_key_name()

set_key_pressed()

set_key_pressed(<note-number>, <value>)

Sets the trigger state of the specified key on Kontakt's keyboard.

<note-number>

MIDI note number of the key (0 ... 127).

<value>

0: Key is released

1: Key is pressed

Remarks

  • By using set_key_pressed() in combination with set_key_pressed_support() set to 1, it is possible to show script generated notes on Kontakt's keyboard. The typical use case would be if an instrument features a built-in sequencer, arpeggiator or harmonizer, and the triggered notes should be shown on the keyboard.

Examples

on init
    set_key_pressed_support(1)
end on

on note
    set_key_pressed($EVENT_NOTE, 1)
end on

on release
    set_key_pressed($EVENT_NOTE, 0)
end on

Insert this after an arpeggiator or harmonizer script.

See Also

set_key_pressed_support()

get_key_triggerstate()

set_key_pressed_support()

set_key_pressed_support(<mode>)

Sets the pressed state support mode for Kontakt's keyboard.

<mode>

0: Kontakt handles all pressed states. set_key_pressed() commands are ignored (this is the default).

1: Kontakt's keyboard is only affected by set_key_pressed() commands.

Remarks

  • The pressed state mode resides outside of KSP, i.e. changing the mode is similar to changing a Kontakt knob with set_engine_par(). Make sure to always set the desired mode in the on init callback.

Examples

on init
    declare ui_button $Enable
    set_key_pressed_support(0)
end on

on ui_control ($Enable)
    set_key_pressed_support($Enable)
end on

on note
    play_note($EVENT_NOTE + 4, $EVENT_VELOCITY, 0, -1)
    play_note($EVENT_NOTE + 7, $EVENT_VELOCITY, 0, -1)

    set_key_pressed($EVENT_NOTE, 1)
    set_key_pressed($EVENT_NOTE + 4, 1)
    set_key_pressed($EVENT_NOTE + 7, 1)
end on

on release
    set_key_pressed($EVENT_NOTE, 0)
    set_key_pressed($EVENT_NOTE + 4, 0)
    set_key_pressed($EVENT_NOTE + 7, 0)
end on

Press the button and you will see what you hear.

See Also

set_key_pressed()

get_key_triggerstate()

set_key_type()

set_key_type(<note-number>, <key-type-constant>)

Assigns a key type to the specified key.

<note-number>

MIDI note number of the key (0 ... 127).

<key-type-constant>

The following key types are available:

$NI_KEY_TYPE_DEFAULT Normally mapped keys that produce sound.

$NI_KEY_TYPE_CONTROL Keyswitches or other keysthat do not produce sound.

$NI_KEY_TYPE_NONE Resets the key to its standard Kontakt behaviour.

Remarks

  • Setting the key type is useful for supported hosts like Komplete Kontrol, where keys with control functionality, e.g. keyswitches, should not be affected by any note processing.

Examples

on init
    declare $count

    $count := 0
    while ($count < 128)
        set_key_type($count, $NI_KEY_TYPE_NONE)

        inc($count)
    end while

    $count := 36
    while ($count <= 96)
        select ($count)
            case 36 to 47 { e.g. key switch }
                set_key_type($count, $NI_KEY_TYPE_CONTROL)
            case 48 to 96 { e.g. playable notes }
                set_key_type($count, $NI_KEY_TYPE_DEFAULT)
        end select

        inc($count)
    end while
end on

See Also

get_key_type()

set_keyrange()

set_keyrange(<min-note>, <max-note>, <name>)

Assigns a text string to the specified range of keys.

<min-note>

First key of the key range (0 ... 127).

<max-note>

Last key of the key range (0 ... 127).

<name>

Text string specifying the name of the key range.

Remarks

  • Key ranges are instrument parameters and reside outside of KSP, i.e. changing the key range is similar to changing a Kontakt knob with set_engine_par(). Make sure to always remove all key ranges in the on init callback or whenever you want to change them later.

  • There can be up to 16 key ranges per instrument.

  • Key names and ranges are displayed in Kontakt's info pane when hovering the mouse over the key on the Kontakt keyboard. The range name is followed by the key name, separated by a dash.

Examples

on init
    declare $count

    while ($count < 128)
        remove_keyrange($count)

        inc($count)
    end while

    set_keyrange(36, 72, "Middle Range")
end on

See Also

remove_keyrange()

set_key_name()

remove_keyrange()

remove_keyrange(<note-number>)

Removes the range of keys to which the specified note number belongs.

Remarks

  • Key ranges are instrument parameters and reside outside of KSP, i.e. changing the key range is similar to changing a Kontakt knob withset_engine_par(). Make sure to always remove all key ranges in the on init callback or whenever you want to change them later.

Examples

on init
    declare $count

    while ($count < 128)
        remove_keyrange($count)

        inc($count)
    end while

    set_keyrange(36, 72, "Middle Range")
end on

See Also

set_keyrange()