Skip to main content
  • KSP Reference Manual
  • General Commands

General Commands

disable_logging()

disable_logging(<event-type>)

Disables emission of messages, warnings or watched variable events to both the Kontakt status bar and Creator Tools Debugger.

<event-type>

Which event type emission to deactivate. Available options:

  • $NI_LOG_MESSAGE

  • $NI_LOG_WARNING

  • $NI_LOG_WATCHING

Remarks

  • This command is only available in the on init callback.

Examples

on init
    disable_logging($NI_LOG_MESSAGE)
    disable_logging($NI_LOG_WARNING)
    disable_logging($NI_LOG_WATCHING)
end on

Keep the lines above commented out while development and bring them back in right before shipping your product to disable any debugging-related content.

See Also

watch_var()

watch_array_idx()

exit

exit

Immediately stops a callback or exits a function.

Remarks

  • exit is a very strong command. Be careful when using it, especially when dealing with larger scripts.

  • If used within a function, exit only exits the function, but not the entire callback.

Examples

on note
    if (not in_range($EVENT_NOTE, 60, 71))
        exit
    end if

    { from here on, only notes between C3 to B3 will be processed }
end on

Useful for quickly setting up key ranges to be affected by the script.

See Also

wait()

stop_wait()

ignore_controller

ignore_controller

Ignores a MIDI Continuous Controller, Pitch Bend or Channel Aftertouch event in the on controller callback, or Polyphonic Aftertouch event in the on poly_at callback.

Examples

on controller
    if ($CC_NUM = 1)
        ignore_controller
        set_controller($VCC_MONO_AT, %CC[1])
    end if
end on

Transform the modwheel into aftertouch.

See Also

ignore_event()

set_controller()

on controller

message()

message(<variable-or-string>)

Displays text in the status line of Kontakt.

Remarks

  • This command is intended to be used for debugging and testing while programming a script. Since there is only one status line in Kontakt, it should not be used as a generic means of communication with the user. Instead, use a label widget, or Debugger pane in Creator Tools.

  • Make it a habit to write message("") at the start of the on init callback. You can then be sure that all previous messages (by the script or by the system) are deleted and you see only new messages.

Examples

on init
    message("Hello, world!")
end on

The inevitable implementation of "Hello, world!" in KSP.

on note
    message("Note " & $EVENT_NOTE & " received at " &  $ENGINE_UPTIME & " milliseconds")
end on

Concatenating strings and expressions in a message() command.

See Also

reset_ksp_timer

ui_label

set_text()

Time and Transport: $ENGINE_UPTIME, $KSP_TIMER

note_off()

note_off(<event-id>)

note_off(<event-id>, <time-offset>)

Sends a MIDI Note Off message for a specific note event ID.

<event-id>

Unique identification number of the note event to be changed.

<time-offset>

Optional argument defining the time offset in microseconds after which the note off will actually happen.

Remarks

  • note_off() is equivalent to releasing a key, thus it will always trigger an on release callback, as well as jump to the release portion of a volume envelope. Notice the difference between note_off() and fade_out(), since fade_out() works on voice level.

  • The optional time offset overwrites a potentially given event duration (i. e. in case the last argument of play_note() command is larger than 0).

Examples

on controller
    if ($CC_NUM = 1)
        note_off($ALL_EVENTS)
    end if
end on

A custom "All Notes Off" implementation triggered by the modwheel.

on init
    declare polyphonic $new_id
end on

on note
    ignore_event($EVENT_ID)
    $new_id := play_note($EVENT_NOTE, $EVENT_VELOCITY, 0, 0)
end on

on release
    ignore_event($EVENT_ID)
    wait(200000)
    note_off($new_id)
end on

Delaying the release of each note by 200 milliseconds.

on init
    declare ui_button $KillAll
end on

on note
    ignore_event($EVENT_ID)
    play_note($EVENT_NOTE, $EVENT_VELOCITY, 0, 5000000)
end on

on ui_control ($KillAll)
    note_off($ALL_EVENTS, 0)
    $KillAll := 0
end on

Prior to Kontakt 8, we could not use the note_off() command on events which had a predefined duration, like in the above case where it is 5 seconds. Using the optional time offset argument, we can now do this.

See Also

fade_out()

play_note()

play_note()

play_note(<note-number>, <velocity>, <sample-offset>, <duration>)

Generates a note event, i.e. a Note On message followed by a Note Off message.

<note-number>

The MIDI note number to be generated (0 ... 127).

<velocity>

Velocity of the generated note (1 ... 127).

<sample-offset>

Sample offset in microseconds.

<duration>

Length of the generated note in microseconds.

This parameter also accepts two special values:

-1: releasing the note which started the callback stops the sample.

0: the entire sample is played (be careful with looped samples, as they would be played indefinitely in this case!).

Remarks

  • In DFD mode, the sample offset is dependent on the Sample Mod (S. Mod) value of the respective zones (found in Kontakt's Wave Editor). Sample offset value greater than the zone's S. Mod setting will be ignored and no sample offset will be applied.

  • You can retrieve the event ID of the played note event in a variable by writing:

    <variable> := play_note(<note>, <velocity>, <sample-offset>, <duration>)

Examples

on note
    play_note($EVENT_NOTE + 12, $EVENT_VELOCITY, 0, -1)
end on

Harmonizes the played note with the upper octave.

on init
    declare $new_id
end on

on controller
    if ($CC_NUM = 64)
        if (%CC[64] = 127)
            $new_id := play_note(60, 100, 0, 0)
        else
            note_off($new_id)
        end if
    end if
end on

Trigger a MIDI note by pressing the sustain pedal.

See Also

note_off()

set_controller()

set_controller(<controller>, <value>)

Sends a MIDI Continuous Controller, Pitch Bend or Channel Pressure message.

<controller>

This parameter sets the type, and in the case of MIDI CCs, sets the CC number:

• A number (0 ... 127) designates a MIDI CC number

• $VCC_PITCH_BEND indicates MIDI Pitch Bend

• $VCC_MONO_AT indicates MIDI Channel Pressure (monophonic aftertouch)

<value>

The value of the specified controller.

• MIDI CC and Channel Pressure value range: 0 ... 127

• MIDI Pitch Bend value range: -8192 ... 8191

Remarks

  • set_controller() cannot be used in the on init callback. If for some reason you wat to send a controller value upon instrument load, use on persistence_changed callback.

on note
    if ($EVENT_NOTE = 36)
        ignore_event($EVENT_ID)
        set_controller($VCC_MONO_AT, $EVENT_VELOCITY)
    end if
end on

on release
    if ($EVENT_NOTE = 36)
        ignore_event($EVENT_ID)
        set_controller($VCC_MONO_AT, 0)
    end if
end on

If you have a keyboard with no aftertouch, press C1 instead.

See Also

ignore_controller

Events and MIDI: $VCC_PITCH_BEND, $VCC_MONO_AT

set_note_controller()

set_note_controller(<controller>, <note-number>, <value>)

Sends a MIDI 2.0 Registered Per-Note Controller, MIDI 2.0 Assignable Per-Note Controller or MIDI 2.0 Per-Note Pitch Bend message.

<controller>

This parameter sets the message type

• A number between 0 ... 255 designates a MIDI 2.0 Registered Per-Note Controller

• A number between 256 ... 511 designates a MIDI 2.0 Assignable Per-Note Controller

• $VNC_PITCH_BEND indicates MIDI 2.0 Per-Note Pitch Bend

<note-number>

The MIDI note number for which the MIDI 2.0 per-note controller will be generated (0 ... 127).

<value>

The value of the specified per-note controller.

• MIDI 2.0 Per-Note Controller value range: 0 ... 127

• MIDI 2.0 Per-Note Pitch Bend value range: -8192 ... 8191

Remarks

  • set_note_controller() cannot be used in the on init callback. If for some reason you wat to send a controller value upon instrument load, use on persistence_changed callback.

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
on init
    declare const $BEND_RANGE := 2

    declare $i
    declare %events[128]
end on

on note
    %events[$EVENT_NOTE] := $EVENT_ID
end on

on note_controller
    if ($NC_NUM = $VNC_PITCH_BEND and in_range($NC_NOTE, 36, 96))
        change_tune(%events[$NC_NOTE], int(real($NC_VALUE) * 12.208522) * $BEND_RANGE, 0)
    end if
end on

An example similar to the one for set_poly_at() command, however this one requires two script slots: the first slot sends the MIDI 2.0 note controller messages, and the second acts upon those messages by applying a custom per-note pitch bend change.

See Also

ignore_controller

Events and MIDI: $VNC_PITCH_BEND

set_poly_at()

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

Sends a MIDI Polyphonic Aftertouch message.

<note-number>

The MIDI note for which the Polyphonic Aftertouch messages will be generated (0 ... 127).

<value>

The value of the Polyphonic Aftertouch message (0 ... 127).

Remarks

  • set_poly_at() cannot be used in the on init callback. If for some reason you wat to send a Polyphonic Aftertouch message upon instrument load, use on persistence_changed callback.

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

If you don't have a keyboard with polyphonic aftertouch, try using this table which sends these events (in the standard 5 octave keyboard range). It will also double as a monitoring tool for incoming polyphonic aftertouch messages!

See Also

ignore_controller

set_rpn()/set_nrpn()

set_rpn(<address>, <value>)

set_nrpn(<address>, <value>)

Sends a MIDI RPN or NRPN message.

<address>

The RPN or NRPN address (0 ... 16383).

<value>

The value of the RPN or NRPN message (0 ... 16383).

Remarks

  • Kontakt cannot handle RPN or NRPN messages as external modulation sources. You can however use these messages for simple inter-script communication.

See Also

on rpn/nrpn

set_controller()

msb()

lsb()

Events and MIDI: $RPN_ADDRESS, $RPN_VALUE

set_snapshot_type()

set_snapshot_type(<type>)

Configures the behavior of all five slots when a snapshot is saved or recalled.

<type>

The available types are:

0: The init callback will always be executed upon snapshot change, then the on persistence_changed callback will be executed (default behavior).

1: the init callback will not be executed upon loading a snapshot, only the on persistence_callback will be executed.

2: same as type 0, but only KSP variables are saved with the snapshot.

3: same as type 1, but only KSP variables are saved with the snapshot.

Remarks

  • This command acts globally, i.e. it can applied in any script slot.

  • In snapshot types 1 and 3, values of persistent and instrument persistent variables are preserved.

  • Loading a snapshot always resets Kontakt's audio engine, i.e. audio is stopped and all active events are deleted.

Examples

on init
    set_snapshot_type(1)

    declare ui_knob $knob_1 (0, 127, 1)
    set_text($knob_1, "Knob")
    make_persistent($knob_1)

    declare ui_button $gui_btn
    set_text($gui_btn, "Page 1")
end on

function show_gui()
    if ($gui_btn = 1)
        set_control_par(get_ui_id($knob_1), $CONTROL_PAR_HIDE, $HIDE_PART_NOTHING)
    else
        set_control_par(get_ui_id($knob_1), $CONTROL_PAR_HIDE, $HIDE_WHOLE_CONTROL)
    end if
end function

on persistence_changed
    call show_gui()
end on

on ui_control ($gui_btn)
    call show_gui()
end on

Retaining the GUI upon loading snapshots.

See Also

on init

on persistence_changed