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.

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. Use a label widget instead.

  • 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()

Transport and Timing: $ENGINE_UPTIME, $KSP_TIMER

note_off()

note_off(<event-id>)

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

<event-id>

Unique identification number of the note event to be changed.

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.

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.

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_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