Skip to main content

Event Commands

by_marks()

by_marks(<bit-mark>)

A user-defined group of event IDs

Remarks

  • by_marks() is a user-defined group of events which can be set with set_event_mark(). It can be used with all commands which take event ID as an argument, like note_off(), change_tune() etc.

Examples

on note
    if ($EVENT_NOTE mod 12 = 0) { if played note is a C }
        set_event_mark($EVENT_ID, $MARK_1)
        change_tune(by_marks($MARK_1), %CC[1] * 1000, 0)
    end if
end on

on controller
    if ($CC_NUM = 1)
        change_tune(by_marks($MARK_1), %CC[1] * 1000, 0)
    end if
end on

Moving the modwheel changes the tuning of all C notes (C-2, C-1…C8)

See Also

set_event_mark()

Events and MIDI: $EVENT_ID, $ALL_EVENTS, $MARK_1 … $MARK_28

change_note()

change_note(<event-ID>, <note-number>)

Changes the note number of a specific event ID

Remarks

  • change_note() is only allowed in the note callback and only works before the first wait() statement. If the voice is already running, only the value of the $EVENT_NOTE variable changes.

  • Once the note number of a particular note event is changed, it becomes the new $EVENT_NOTE

  • It is not possible to address events via event groups like $ALL_EVENTS

Examples

on init
    declare %black_keys[5] := (1, 3, 6, 8, 10)
end on

on note
    if (search(%black_keys, $EVENT_NOTE mod 12) # -1)
        change_note($EVENT_ID, $EVENT_NOTE - 1)
    end if
end on

Constrain all notes to white keys, i.e. C major

See Also

change_velo()

Events and MIDI: $EVENT_NOTE

change_pan()

change_pan(<event-id>, <panorama>, <relative-bit>)

Changes the pan position of a specific note event

<event-id>

Unique identification number of the note event to be changed.

<panorama>

The pan position of the note event, from -1000 (left) to 1000 (right)

<relative-bit>

If the relative bit is set to 0, the amount is absolute, i.e. the amount overwrites any previous set values of that event.

If set to 1, the amount is relative to the actual value of the event.

The different implications are only relevant with more than one change_pan() statement applied to the same event.

Remarks

  • change_pan() works on the note event level and does not change any panorama settings in the instrument itself. It is also not related to any modulations regarding panorama.

Examples

on init
    declare $pan_position
end on

on note
    $pan_position := ($EVENT_NOTE * 2000 / 127) - 1000
    change_pan($EVENT_ID, $pan_position, 0)
end on

Panning the entire key range from left to right, i.e. C-2 all the way left, G8 all the way right

on note
    if ($EVENT_NOTE < 60)
        change_pan($EVENT_ID, 1000, 0)
        wait(500000)
        change_pan($EVENT_ID, -1000, 0) { absolute, pan is at -1000 }
    else
        change_pan($EVENT_ID, 1000, 1)
        wait(500000)
        change_pan($EVENT_ID, -1000, 1) { relative, pan is at 0 }
    end if
end on

Notes below C3 utilize a relative bit of 0. C3 and above utilize a relative bit of 1

See Also

change_vol()

change_tune()

change_tune()

change_tune(<event-id>, <tune-amount>, <relative-bit>)

Changes the tuning of a specific note event in millicents.

<event-id>

Unique identification number of the note event to be changed.

<tune-amount>

The tune amount in millicents. 100000 equals 100 cents (one semitone).

<relative-bit>

If the relative bit is set to 0, the amount is absolute, i.e. the amount overwrites any previous set values of that event.

If it is set to 1, the amount is relative to the actual value of the event.

The different implications are only relevant with more than one change_tune()statement applied to the same event.

Remarks

  • change_tune() works on the note event level and does not change any tune settings in the instrument itself. It is also not related to any modulations regarding tuning.

Examples

on init
    declare $tune_amount
end on

on note
    $tune_amount := random(-50000, 50000)
    change_tune($EVENT_ID, $tune_amount, 1)
end on

Randomly detune every played note by ±50 cents

See Also

change_vol()

change_pan()

change_velo()

change_velo(<event-id>, <velocity>)

Changes the velocity of a specific note event ID

Remarks

  • change_velo() is only allowed in the note callback and only works before the first wait() statement. If the voice is already running, only the value of the variable changes.

  • Once the velocity of a particular note event is changed, it becomes the new $EVENT_VELOCITY

  • It is not possible to address events via event groups like $ALL_EVENTS

Examples

on note
    change_velo($EVENT_ID, 100)
    message($EVENT_VELOCITY)
end on

All velocities are set to 100. Note that $EVENT_VELOCITY will also change to 100.

See Also

change_note()

Events and MIDI: $EVENT_VELOCITY

change_vol()

change_vol(<event-id>, <volume>, <relative-bit>)

Changes the volume of a specific note event in millidecibels

<ID-number>

Unique identification number of the note event to be changed

<volume>

The volume change in millidecibels (1000 millidecibels = 1 decibel)

<relative-bit>

If the relative bit is set to 0, the amount is absolute, i.e. the amount overwrites any previous set values of that event.

If it is set to 1, the amount is relative to the actual value of the event.

The different implications are only relevant with more than one change_vol() statement applied to the same event.

Remarks

  • change_vol() works on the note event level and does not change any tune settings in the instrument itself. It is also not related to any MIDI modulations regarding volume (e.g. MIDI CC 7).

Example

on init
    declare $vol_amount
end on

on note
    $vol_amount := (($EVENT_VELOCITY - 1) * 12000 / 126) - 6000
    change_vol ($EVENT_ID, $vol_amount, 1)
end on

A simple dynamic expander: lightly played notes will be softer, harder played notes will be louder

See Also

change_tune()

change_pan()

fade_in()

fade_out()

delete_event_mark()

delete_event_mark(<ID-number>, <bit-mark>)

Delete an event mark, i.e. ungroup the specified event from an event group

<ID-number>

Unique identification number of the note event to be ungrouped

<bit-mark>

One of 28 marks from $MARK_1 to $MARK_28, which was assigned to the event.

See Also 

set_event_mark()

by_marks()

Events and MIDI: $EVENT_ID, $ALL_EVENTS, $MARK_1 … $MARK_28

event_status()

event_status(<ID-number>)

Retrieves the status of a particular note event (or MIDI event in the multi script).

The note can either be active, when this function returns:

$EVENT_STATUS_NOTE_QUEUE (or $EVENT_STATUS_MIDI_QUEUE in the multi script)

or inactive, when the function returns:

$EVENT_STATUS_INACTIVE

Remarks

  • event_status() can be used to find out if a note event is still "alive" or not.

Examples 

on init
    declare %key_id[128]
end on

on note
    if (event_status(%key_id[$EVENT_NOTE]) = $EVENT_STATUS_NOTE_QUEUE)
        fade_out(%key_id[$EVENT_NOTE], 10000, 1)
    end if
    %key_id[$EVENT_NOTE] := $EVENT_ID
end on

Limit the number of active note events to one per MIDI key

See Also 

get_event_ids()

Events and MIDI: $EVENT_STATUS_INACTIVE, $EVENT_STATUS_NOTE_QUEUE, $EVENT_STATUS_MIDI_QUEUE

fade_in()

fade_in(<ID-number>, <fade-time>)

Performs a fade in for a specific note event

<ID-number>

Unique identification number of the note event to be faded in

<fade-time>

The fade in time in microseconds

Examples 

on init
    declare $note_1_id
    declare $note_2_id
end on

on note
    $note_1_id := play_note($EVENT_NOTE + 12, $EVENT_VELOCITY, 0, -1)
    $note_2_id := play_note($EVENT_NOTE + 19, $EVENT_VELOCITY, 0, -1)		

    fade_in ($note_1_id, 1000000)
    fade_in ($note_2_id, 5000000)
end on

Fading in the first two harmonics

See Also 

change_vol()

fade_out()

fade_out()

fade_out(<ID-number>, <fade-time>, <stop-voice>)

Performs a fade-out for a specific note event

<ID-number>

Unique identification number of the note event to be faded out

<fade-time>

The fade out time in microseconds

<stop-voice>

If set to 1, the voice is stopped after the fade out

If set to 0, the voice will still be running after the fade out

Examples

on controller
    if ($CC_NUM = 1)
        if (%CC[1] mod 2 # 0)
            fade_out($ALL_EVENTS, 5000, 0)
        else
            fade_in($ALL_EVENTS, 5000)
        end if
    end if
end on

Use the modwheel on held notes to create a stutter effect

on controller
    if ($CC_NUM = 1)
        fade_out($ALL_EVENTS,5000,1)
    end if
end on

A custom "All Sound Off" implementation triggered by the modwheel

See Also 

change_vol()

fade_out()

get_event_ids()

get_event_ids(<array-name>)

Fills the specified array with all active event IDs

<array-name>

array to be filled with active event IDs

Remarks

  • The command overwrites all existing values as long as there are active events, and writes 0 if no events are active anymore. If there are more active events than array indices, the array will be filled until it is full, ignoring the remaining event IDs.

  • If there are less active events than array indices, the array will be filled from the beginning with all IDs followed by one index with its value set to 0.

Examples

on init
    declare const $ARRAY_SIZE := 500
    declare %test_array[$ARRAY_SIZE]
    declare $a
    declare $note_count
end on

on note
    get_event_ids(%test_array)

    $note_count := 0
    $a := 0
    while($a < $ARRAY_SIZE and %test_array[$a] # 0)
        inc($note_count)
        inc($a)
    end while

    message("Active Events: " & $note_count)
end on

Monitoring the number of active events

See Also

event_status()

get_event_mark()

get_event_mark(<ID-number>, <bit-mark>)

Checks if the specified event ID belongs to a specific event group (returns 1 if the bit mark is set, 0 otherwise)

<ID-number>

Unique identification number of the note event to be checked

<bit-mark>

The bit mark from $MARK_1 to $MARK_28

Examples

on note
    if ($EVENT_NOTE mod 12 = 0)
        set_event_mark($EVENT_ID, $MARK_1)
    end if
end on

on release
    if (get_event_mark($EVENT_ID, $MARK_1) = 1)
        message("You've played a C!")
    else
        message("")
    end if
end on

A rather long-winded way to check if you've released a C key.

See Also

set_event_mark()

get_event_par()

get_event_par(<ID-number>, <parameter>)

Returns the value of a specific event parameter of the specified event

<ID-number>

Unique identification number of the note event to be changed

<parameter>

The event parameter, either one of four freely assignable event parameters:

  • $EVENT_PAR_0

  • $EVENT_PAR_1

  • $EVENT_PAR_2

  • $EVENT_PAR_3

or the "built-in" parameters of a note event:

  • $EVENT_PAR_VOLUME

  • $EVENT_PAR_PAN

  • $EVENT_PAR_TUNE

  • $EVENT_PAR_NOTE

  • $EVENT_PAR_VELOCITY

  • $EVENT_PAR_REL_VELOCITY

  • $EVENT_PAR_SOURCE

  • $EVENT_PAR_PLAY_POS

  • $EVENT_PAR_ZONE_ID (use with care, see below)

Remarks

A note event always carries certain information like the note number, the played velocity, but also volume, pan and tune. With get_event_par(), you can get either these parameters or use the freely assignable parameters like $EVENT_PAR_0. This is especially useful when chaining scripts, i.e. set an event parameter for an event in script slot 1, then retrieve this information in script slot 2 by using get_event_par().

Examples

on note 
    message(get_event_par($EVENT_ID, $EVENT_PAR_NOTE))
end on

The same functionality as message($EVENT_NOTE)

on note
    message(get_event_par($EVENT_ID, $EVENT_PAR_SOURCE))
end on

Check if the event comes from outside (returns -1 in this case) or if it was created in one of the five script slots (returns 0-4)

on note
    wait(1)
    message(get_event_par($EVENT_ID, $EVENT_PAR_ZONE_ID))
end on

In the above example, an event itself does not carry a zone ID (only a voice carries zone IDs), therefore you need to insert wait(1) in order to retrieve the zone ID.

See Also 

set_event_par()

ignore_event()

set_event_par_arr()

get_event_par_arr()

get_event_par_arr()

get_event_par_arr(<ID-number>, <parameter>, <index>)

Retrieves the value of a specified event parameter of a specific event

<ID-number>

Unique identification number of the note event

<parameter>

Can be one of the following:

  • $EVENT_PAR_ALLOW_GROUP

  • $EVENT_PAR_CUSTOM

  • $EVENT_PAR_MOD_VALUE_ID

<index>

When used with:

  • $EVENT_PAR_ALLOW_GROUP: the group index (0 to 4095, however this depends on the amount of groups present in a particular KONTAKT instrument)

  • $EVENT_PAR_CUSTOM: the event parameter index (0 to 15)

  • $EVENT_PAR_MOD_VALUE_ID: the "from script" modulator index, as set in the modulation assignment in KONTAKT (0 to 1000).

Remarks

  • get_event_par_arr() is the array variant of get_event_par(). You can use it to retrieve the group allow state of a specific event, or if you need to access more than the four standard event parameters. You can also use it to retrieve the value of event-specific modulations, facilitated by "from script" modulators in KONTAKT.

Examples

on init
    declare $count
    declare ui_label $label (2, 4)
    set_text($label, "")
end on

on note
    set_text($label, "")

    $count := 0
    while ($count < $NUM_GROUPS)
        if (get_event_par_arr($EVENT_ID, $EVENT_PAR_ALLOW_GROUP, $count) = 1)
            add_text_line($label,"Group ID " & $count & " allowed")
        else
            add_text_line($label,"Group ID " & $count & " disallowed")
        end if

        inc($count)
    end while
end on

A simple group monitor

See Also

set_event_par_arr()

get_event_par()

Events and MIDI: $EVENT_PAR_ALLOW_GROUP, $EVENT_PAR_MOD_VALUE_ID, $EVENT_PAR_CUSTOM , %GROUPS_AFFECTED

ignore_event()

ignore_event(<ID-number>)

Ignores a note event in on note or on release callbacks

Remarks

  • If you ignore an event, any volume, tune or pan information is lost. You can however retrieve this infomation with get_event_par(), refer to the two examples below.

  • ignore_event() is a very "strong" command. Always check if you can get the same results with the various change_xxx() commands without having to ignore the event.

Examples 

on note
    ignore_event($EVENT_ID)
    wait(500000)
    play_note($EVENT_NOTE, $EVENT_VELOCITY, 0, -1)
end on

Delaying all notes by half a second. Not bad, but if you, for example insert a microtuner before this script, the tuning information will be lost.

on init
    declare $new_id
end on

on note
    ignore_event($EVENT_ID)
    wait(500000)
    $new_id := play_note($EVENT_NOTE, $EVENT_VELOCITY, 0, -1)

    change_vol($new_id, get_event_par($EVENT_ID, $EVENT_PAR_VOLUME), 1)
    change_tune($new_id, get_event_par($EVENT_ID, $EVENT_PAR_TUNE), 1)
    change_pan($new_id, get_event_par($EVENT_ID, $EVENT_PAR_PAN), 1)
end on

Better: the tuning (plus volume and pan, to be precise) information is retrieved and applied to the played note

See Also 

ignore_controller

get_event_par()

redirect_­output(­)

redirect_output(<ID-number>, <output-type>, <index>)

Routes the audio signal of the specified event to a specific output or bus.

<ID-number>

Unique identification number of the note event to be routed

<output-type>

Can be one of the following:

  • $OUTPUT_TYPE_DEFAULT: The audio signal of the event is routed to the default instrument output.

  • $OUTPUT_TYPE_MASTER_OUT: The audio signal of the event is routed directly to the output channel specified with <index> (0 to 63, depending on number of output channels defined in KONTAKT). The audio signal will not be affected by any instrument effect.

  • $OUTPUT_TYPE_AUX_OUT: The audio signal of the event is routed directly to the Aux channel specified with <index>. (0 to 3) The audio signal will not be affected by any instrument effect.

  • $OUTPUT_TYPE_BUS_OUT: The audio signal of the event is routed to the instrument bus specified with <index> (0 to 15).

<index>

Specifies the output channel, aux channel or instrument bus, depending on <output-type>.

Has no effect when <output-type> is set to $OUTPUT_TYPE_DEFAULT.

Remarks

  • When using redirect_output(), the output selection of a group is completely ignored.

Examples

on init
    declare $new_id_0
    declare $new_id_1
    decalre $new_id_2
end on

on note
    ignore_event($EVENT_ID)

    $new_id_0 := play_note($EVENT_NOTE, $EVENT_VELOCITY, 0, -1)
    $new_id_1 := play_note($EVENT_NOTE + 4, $EVENT_VELOCITY, 0, -1)
    $new_id_2 := play_note($EVENT_NOTE + 7, $EVENT_VELOCITY, 0, -1)

    redirect_output($new_id_0, $OUTPUT_TYPE_BUS_OUT, 0)
    redirect_output($new_id_1, $OUTPUT_TYPE_BUS_OUT, 1)
    redirect_output($new_id_2, $OUTPUT_TYPE_BUS_OUT, 2)
end on

Creating a major triad and routing each note to a separate instrument bus.

set_event_mark()

set_event_mark(<ID-number>, <bit-mark>)

Assigns the specified event ID to a specific event group

<ID-number>

Unique identification number of the note event

<bit-mark>

One of 28 marks, from $MARK_1 to $MARK_28 which will be assigned to the event. You can also assign more than one mark to a single event, either by typing the command again, or by using the bitwise .or. operator, or by simply summing the event marks.

Remarks

  • When working with commands that deal with event IDs, you can group events by using by_marks(<bit-mark>) instead of using individual IDs, as the program needs to know that you want to address marks, and not IDs.

Examples

on init
    declare $new_id
end on

on note
    set_event_mark($EVENT_ID, $MARK_1)

    $new_id := play_note($EVENT_NOTE + 12, 120, 0, -1)
    set_event_mark($new_id, $MARK_1 + $MARK_2)

    change_pan(by_marks($MARK_1), -1000, 1) { both notes panned to left }
    change_pan(by_marks($MARK_2), 2000, 1) { new note panned to right }
end on

The played note belongs to event mark 1, the harmonized note belongs to both event marks 1 and 2

See Also 

by_marks()

delete_event_mark()

Events and MIDI: $EVENT_ID, $ALL_EVENTS, $MARK_1 … $MARK_28

set_event_par()

set_event_par(<ID-number>, <parameter>, <value>)

Assigns a specific event parameter value to a specific event

<ID-number>

Unique identification number of the note event

<parameter>

The event parameter, either one of four freely assignable event parameters:

  • $EVENT_PAR_0

  • $EVENT_PAR_1

  • $EVENT_PAR_2

  • $EVENT_PAR_3

or the "built-in" parameters of a note event:

  • $EVENT_PAR_VOLUME

  • $EVENT_PAR_PAN

  • $EVENT_PAR_TUNE

  • $EVENT_PAR_NOTE

  • $EVENT_PAR_VELOCITY

  • $EVENT_PAR_REL_VELOCITY

<value>

The value of the event parameter

Remarks

  • A note event always carries certain information like the note number, the played velocity, but also volume, pan and tune. With set_event_par(), you can set either these parameters or use the freely assignable parameters like $EVENT_PAR_0. This is especially useful when chaining scripts, i.e. set an event parameter for an event in script slot 1, then retrieve this information in script slot 2 by using get_event_par().

  • If you need access to more than four custom parameters, please use set_event_par_arr() with $EVENT_PAR_CUSTOM

Examples

on note 
    set_event_par($EVENT_ID, $EVENT_PAR_NOTE, 60)
end on

Setting all notes to middle C3, same as change_note($EVENT_ID, 60)

on init
    message("")
    declare ui_switch $switch

    declare ui_label $midiChan1 (1, 1)
    declare ui_label $midiChan2 (1, 1)
    declare ui_label $midiChan3 (1, 1)
    declare ui_label $midiChan4 (1, 1)
    declare ui_label $midiChan5 (1, 1)
    declare ui_label $midiChan6 (1, 1)
    declare ui_label $midiChan7 (1, 1)
    declare ui_label $midiChan8 (1, 1)
    declare ui_label $midiChan9 (1, 1)
    declare ui_label $midiChan10 (1, 1)
    declare ui_label $midiChan11 (1, 1)
    declare ui_label $midiChan12 (1, 1)
    declare ui_label $midiChan13 (1, 1)
    declare ui_label $midiChan14 (1, 1)
    declare ui_label $midiChan15 (1, 1)
    declare ui_label $midiChan16 (1, 1)

    declare %midiChans[16]
    %midiChans[0] := get_ui_id($midiChan1)
    %midiChans[1] := get_ui_id($midiChan2)
    %midiChans[2] := get_ui_id($midiChan3)
    %midiChans[3] := get_ui_id($midiChan4)
    %midiChans[4] := get_ui_id($midiChan5)
    %midiChans[5] := get_ui_id($midiChan6)
    %midiChans[6] := get_ui_id($midiChan7)
    %midiChans[7] := get_ui_id($midiChan8)
    %midiChans[8] := get_ui_id($midiChan9)
    %midiChans[9] := get_ui_id($midiChan10)
    %midiChans[10] := get_ui_id($midiChan11)
    %midiChans[11] := get_ui_id($midiChan12)
    %midiChans[12] := get_ui_id($midiChan13)
    %midiChans[13] := get_ui_id($midiChan14)
    %midiChans[14] := get_ui_id($midiChan15)
    %midiChans[15] := get_ui_id($midiChan16)
end on

on release
    if ($switch = 1)
        set_event_par($EVENT_ID, $EVENT_PAR_REL_VELOCITY, 127)
    end if

    set_control_par_str(%midiChans[$MIDI_CHANNEL], $CONTROL_PAR_TEXT, get_event_par($EVENT_ID, $EVENT_PAR_REL_VELOCITY))
end on

Release velocity within an MPE context

See Also

get_event_par()

ignore_event()

set_event_par_arr()

get_event_par_arr()

set_event_par_arr()

set_event_par_arr(<ID-number>, <parameter>, <value>, <index>)

Assigns an event parameter array to a specific event

<ID-number>

Unique identification number of the note event

<parameter>

Can be one of the following:

  • $EVENT_PAR_ALLOW_GROUP

  • $EVENT_PAR_CUSTOM

  • $EVENT_PAR_MOD_VALUE_ID

<value>

When used with:

  • $EVENT_PAR_ALLOW_GROUP: the allow state for the group (1 for allowed, 0 for disallowed)

  • $EVENT_PAR_CUSTOM: the value of the specified event parameter

  • $EVENT_PAR_MOD_VALUE_ID: the modulation value to be sent to "from script" modulator (-1000000 to 1000000)

<index>

When used with:

  • $EVENT_PAR_ALLOW_GROUP: the group index (0 to 4095, however this depends on the amount of groups present in a particular KONTAKT instrument)

  • $EVENT_PAR_CUSTOM: the event parameter index (0 to 15)

  • $EVENT_PAR_MOD_VALUE_ID: the "from script" modulator index, as set in the modulation assignment in KONTAKT (0 to 1000).

Remarks

  • set_event_par_arr() is the array variant of set_event_par(). You can use it to set the group allow state of a specific event, or if you need to access more than the four standard event parameters. You can also use it to set up event-specific modulations, facilitated by "from script" modulators in KONTAKT.

Examples

on note
    if (get_event_par_arr($EVENT_ID, $EVENT_PAR_ALLOW_GROUP, 0) = 0)
        set_event_par_arr($EVENT_ID, $EVENT_PAR_ALLOW_GROUP, 1, 0)
    end if
end on

Making sure the first group is always played.

on init
    declare const $CUSTOM_EVENT_PAR_4 := 4
end on

on note
    set_event_par_arr($EVENT_ID, $EVENT_PAR_CUSTOM, $ENGINE_UPTIME, $CUSTOM_EVENT_PAR_4)
end on

on release
    message(get_event_par_arr($EVENT_ID, $EVENT_PAR_CUSTOM, $CUSTOM_EVENT_PAR_4))
end on

Simple implementation of $EVENT_PAR_CUSTOM

on note
    if ($EVENT_NOTE = 60)
        set_event_par_arr($EVENT_ID, $EVENT_PAR_MOD_VALUE_ID, 500000, 1)
    end if
end on

Only middle C (MIDI note 60) will have any modulation applied, facilitated by "from script" modulator and "1" as its ID.

See Also

allow_group()

disallow_group()

get_event_par_arr()

set_event_par()

Events and MIDI: $EVENT_PAR_ALLOW_GROUP