Skip to main content

Built-in Variables and Constants

General

$CURRENT_SCRIPT_SLOT 

The script slot of the current script (zero-based, i.e. the first script slot is 0).             

%GROUPS_SELECTED[<group-idx>] 

An array with each array index pointing to the group with the same index.

If a group is selected for editing, the corresponding array cell contains a 1, otherwise 0.

$NI_ASYNC_EXIT_STATUS 

Returns a value of 1 if the command that triggered the on async_complete callback has successfully completed its action. 0 if the command could not complete its action, e.g. file not found. 

$NI_ASYNC_ID 

Returns the ID of the command that triggered the on async_complete callback.

$NI_BUS_OFFSET 

To be used in the <generic> part of the engine parameter commands to point to the instrument bus level. Add the index of the bus you wish to address, e.g. $NI_BUS_OFFSET + 2 will point to instrument bus 3.

$NUM_GROUPS 

Total amount of groups in an instrument. This is not a constant and thus cannot be used to define the size of an array.               

$NUM_OUTPUT_CHANNELS 

Total amount of output channels of the respective KONTAKT Multi, not counting Aux channels.

$NUM_ZONES 

Total amount of zones in an instrument.

$PLAYED_VOICES_INST 

The amount of played voices for the current instrument.

$PLAYED_VOICES_TOTAL 

The amount of played voices for all instruments.             

Path Variables

$GET_FOLDER_LIBRARY_DIR

If used with an NKI belonging to an encoded library: library folder.

If used with an unencoded NKI: the user content directory.

$GET_FOLDER_FACTORY_DIR

The factory folder of KONTAKT, mainly used for loading factory IR samples.

Note: this is not the factory library folder!

$GET_FOLDER_PATCH_DIR

The directory in which the patch was saved.

If the patch was not saved before, an empty string is returned.

Time Machine Pro Variables 

User access for the two voice limits (Standard and High Quality) of the Time Machine Pro, to be used with set_voice_limit() and get_voice_limit().

$NI_VL_TMPRO_STANDARD

$NI_VL_TMRPO_HQ

$REF_GROUP_IDX 

Group index number of the currently viewed group.

Events and MIDI

$ALL_GROUPS

Addresses all groups in the instrument when used in a disallow_group() and allow_group() function.

$ALL_EVENTS

Addresses all events in functions which deal with an event ID number.

This constant also works with MIDI event commands that require a MIDI event ID.

Bit Mark Constants

Bit mark of an event group, to be used with by_marks()

$MARK_1

$MARK_2

$MARK_28

%CC[<controller-number>]

Current controller value for the specified controller

$CC_NUM

Controller number of the controller which triggered the callback

%CC_TOUCHED[<controller-number>]

1 if the specified controller value has changed, 0 otherwise

$EVENT_ID

Unique ID number of the event which triggered the callback

$CURRENT_EVENT

The currently selected MIDI event, i.e. the MIDI event at the position marker

$EVENT_NOTE

Note number of the event which triggered the callback

$EVENT_VELOCITY

Velocity of the note which triggered the callback

Event Parameter Constants

Event parameters to be used with set_event_par() and get_event_par():

  • $EVENT_PAR_0$EVENT_PAR_3

  • $EVENT_PAR_VOLUME

  • $EVENT_PAR_PAN

  • $EVENT_PAR_TUNE

  • $EVENT_PAR_NOTE

  • $EVENT_PAR_VELOCITY

Event Parameters to be used with set_event_par_arr() and get_event_par_arr():

  • $EVENT_PAR_ALLOW_GROUP

  • $EVENT_PAR_MOD_VALUE_ID

Event Parameters to be used with get_event_par():

  • $EVENT_PAR_SOURCE (-1 if event originates from outside, otherwise slot number 0 - 4)

  • $EVENT_PAR_PLAY_POS (Returns the value of the play cursor within a zone)

  • $EVENT_PAR_ZONE_ID (Returns the zone ID of the event and can only be used with active events. Returns -1 if no zone is triggered. Returns the highest zone id if more than one zone is triggered by the event. Make sure the voice is running by writing e.g. wait (1) before retrieving the zone ID!)

Event Parameters to be used with get_event_par(), multi script only:

  • $EVENT_PAR_MIDI_CHANNEL

  • $EVENT_PAR_MIDI_COMMAND

  • $EVENT_PAR_MIDI_BYTE_1

  • $EVENT_PAR_MIDI_BYTE_2

Event Parameters to be used with mf_set_event_par() and mf_get_event_par():

  • $EVENT_PAR_POS

  • $EVENT_PAR_NOTE_LENGTH

  • $EVENT_PAR_ID

  • $EVENT_PAR_TRACK_NR

%EVENT_PAR

Array which contains values of $EVENT_PAR_0... $EVENT_PAR_3 along with $EVENT_PAR_CUSTOM indices 4-15, valid for $EVENT_ID.

Event Status Constants

$EVENT_STATUS_INACTIVE

$EVENT_STATUS_NOTE_QUEUE

$EVENT_STATUS_MIDI_QUEUE

%GROUPS_AFFECTED

An array with the group indices of those groups that are affected by the current Note On or Note Off events.

The size of the array changes depending on the number of groups the event affects, so use the num_elements() command to get the correct array size.

The returned indices come before any allow or disallow group commands, and so it can be used to analyze the mapping of the instrument.

$NOTE_HELD

1 if the key which triggered the callback is still held, 0 otherwise

%POLY_AT[<note-number>]

The polyphonic aftertouch value of the specified note number

$POLY_AT_NUM

The note number of the polyphonic aftertouch note which triggered the callback

$RPN_ADDRESS

The parameter number of a received RPN/NRPN message (0 – 16383)

$RPN_VALUE

The value of a received RPN or NRPN message (0 – 16383)

$VCC_MONO_AT

The value of the virtual CC controller for mono aftertouch (channel pressure)

$VCC_PITCH_BEND

The value of the virtual CC controller for pitch bend

%KEY_DOWN[<note-number>]

Array which contains the current state of all keys. 1 if the key is held, 0 otherwise

%KEY_DOWN_OCT[<note-number>]

1 if a note, independent of the octave, is held. 0 otherwise. Due to this, the note number should be a value between 0 (C) and 11 (B).

Transport and Timing

$DISTANCE_BAR_START 

Returns the time of a note on message in microseconds from the beginning of the current bar with respect to the current tempo.

$DURATION_BAR 

Returns the duration in microseconds of one bar with respect to the current tempo.

This variable only works if the clock is running, otherwise it will return a value of zero.

You can also retrieve the duration of one bar by using $SIGNATURE_NUM and $SIGNATURE_DENOM in combination with $DURATION_QUARTER.

$DURATION_QUARTER 

Duration of a quarter note in microseconds, with respect to the current tempo.

Also available:

$DURATION_EIGHTH

$DURATION_SIXTEENTH

$DURATION_QUARTER_TRIPLET

$DURATION_EIGHTH_TRIPLET

$DURATION_SIXTEENTH_TRIPLET

$ENGINE_UPTIME 

Returns the time period in milliseconds (not microseconds) that has passed since the start of KONTAKT. The engine uptime is calculated from the sample rate and can thus be used in ‘musical’ contexts, (eg. building arpeggiators or sequencers) as it remains in sync, even in an offline bounce.

$KSP_TIMER 

Returns the time period in microseconds that has passed since the start of KONTAKT.

Can be reset with reset_ksp_timer.

The KSP timer is based on the CPU clock and thus runs at a constant rate, regardless of whether or not KONTAKT is being used in real-time. As such, it should be used to test the efficiency of script and not to make musical calculations, as musical calculations use the $ENGINE_UPTIME timer.

$NI_SONG_POSITION 

Returns the host’s current song position in 960 ticks per quarter note.

$NI_TRANSPORT_RUNNING 

1 if the host's transport is running, 0 otherwise

$SIGNATURE_NUM 

Numerator of the current time signature, i.e. 4/4

$SIGNATURE_DENOM 

Denominator of the current time signature, i.e. 4/4

Tempo Unit Variables

Used to control the unit parameter of time-related controls (e.g. Delay Time, Attack etc.) with engine parameter variables like $ENGINE_PAR_DL_TIME_UNIT.

$NI_SYNC_UNIT_ABS

$NI_SYNC_UNIT_WHOLE

$NI_SYNC_UNIT_WHOLE_TRIPLET

$NI_SYNC_UNIT_HALF

$NI_SYNC_UNIT_HALF_TRIPLET

$NI_SYNC_UNIT_QUARTER

$NI_SYNC_UNIT_QUARTER_TRIPLET

$NI_SYNC_UNIT_8TH

$NI_SYNC_UNIT_8TH_TRIPLET

$NI_SYNC_UNIT_16TH

$NI_SYNC_UNIT_16TH_TRIPLET

$NI_SYNC_UNIT_32ND

$NI_SYNC_UNIT_32ND_TRIPLET

$NI_SYNC_UNIT_64TH

$NI_SYNC_UNIT_64TH_TRIPLET

$NI_SYNC_UNIT_256TH

$NI_SYNC_UNIT_ZONE (Only applies to the Source Module Speed parameter)

%NOTE_DURATION[<note-number>] 

Note length since note start in microseconds for each key.

$NI_BAR_START_POSITION

Returns the start of current bar in ticks (at 960 PPQ) from the start of the host's song.

Callbacks and UI

Callback Type Variables and Constants

$NI_CALLBACK_ID

Returns the ID number of the callback. Every callback has a unique ID number which remains the same within a function.

$NI_CALLBACK_TYPE

Returns the callback type. Useful for retrieving the callback that triggered a specific function.

The following constants are available:

$NI_CB_TYPE_ASYNC_OUT

$NI_CB_TYPE_CONTROLLER

$NI_CB_TYPE_INIT

$NI_CB_TYPE_LISTENER

$NI_CB_TYPE_NOTE

$NI_CB_TYPE_PERSISTENCE_CHANGED

$NI_CB_TYPE_PGS

$NI_CB_TYPE_POLY_AT

$NI_CB_TYPE_RELEASE

$NI_CB_TYPE_RPN/$NI_CB_TYPE_NRPN

$NI_CB_TYPE_UI_CONTROL

$NI_CB_TYPE_UI_UPDATE

$NI_CB_TYPE_MIDI_IN

Listener Constants

Can be used with set_listener() or change_listener_par() to set which signals will trigger the on listener callback. Can also be used with $NI_SIGNAL_TYPE to determine which signal type triggered the callback.

$NI_SIGNAL_TRANSP_STOP

$NI_SIGNAL_TRANSP_START

$NI_SIGNAL_TIMER_MS

$NI_SIGNAL_TIMER_BEAT

Knob Unit Mark Constants

To be used with set_knob_unit().

$KNOB_UNIT_NONE

$KNOB_UNIT_DB

$KNOB_UNIT_HZ

$KNOB_UNIT_PERCENT

$KNOB_UNIT_MS

$KNOB_UNIT_ST

$KNOB_UNIT_OCT

$NI_SIGNAL_TYPE

Can be used in the on listener callback to determine which signal type triggered the callback.

$NI_KONTAKT_IS_HEADLESS

Returns 1 if the GUI of KONTAKT is not available and not loadable. Currently this is only possible with KONTAKT being used in MASCHINE+, i.e. with KONTAKT being used in a regular host, it will still return 0 even if the GUI is not visible.

Mathematical Constants

~NI_MATH_PI 

Returns the mathematical constant pi (approx. 3.14159…)

~NI_MATH_E

Returns the mathematical constant e (approx. 2.71828…)