Event Commands
by_marks()
| |
|---|---|
A user-defined group of events. | |
| One of 28 marks, |
Remarks
by_marks()is a user-defined group of events which can be set withset_event_mark(). It can be used with all commands which take event ID as an argument, likenote_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 onMoving the modwheel changes the tuning of all C notes (C-2, C-1…C8).
See Also
Events and MIDI: $EVENT_ID, $ALL_EVENTS, $MARK_1 … $MARK_28
change_note()
|
|---|
Changes the note number of a specific event ID. |
Remarks
change_note()is only allowed in theon notecallback and only works before the firstwait()statement. If the voice is already running, only the value of the$EVENT_NOTEvariable 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 onConstrain all notes to white keys, i.e. C major.
See Also
Events and MIDI: $EVENT_NOTE
change_pan()
| |
|---|---|
Changes the pan position of a specific note event. | |
| Unique identification number of the note event to be changed. |
| The pan position of the note event, from -1000 (left) to 1000 (right). |
| If set to 0, the amount is absolute, i.e. the amount overwrites any previous set values of that event. Note that this mode also overwrites any zone volume adjustments! If set to 1, the amount is relative to the actual value of the event. If set to 2, it behaves like mode 0 (absolute adjustment), except any zone volume adjustments are preserved. The different implications between absolute and relative adjustments are more apparent with more than one |
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 onPanning the entire key range from left to right, i.e. C-2 all the way to the left, G8 all the way to the 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 onNotes below C3 utilize a relative bit of 0. C3 and above utilize a relative bit of 1.
See Also
change_tune()
| |
|---|---|
Changes the tuning of a specific note event in millicents. | |
| Unique identification number of the note event to be changed. |
| The tune amount in millicents. 100000 equals 100 cents (one semitone). |
| If 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 between absolute and relative adjustments are more apparent with more than one |
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 onRandomly detune every played note by ±50 cents
See Also
change_velo()
|
|---|
Changes the velocity of a specific note event ID. |
Remarks
change_velo()is only allowed in the on note callback and only works before the firstwait()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 onAll velocities are set to 100. Note that $EVENT_VELOCITY will also change to 100.
See Also
Events and MIDI: $EVENT_VELOCITY
change_vol()
| |
|---|---|
Changes the volume of a specific note event in millidecibels. | |
| Unique identification number of the note event to be changed. |
| The volume change in millidecibels (1000 millidecibels = 1 decibel). |
| If set to 0, the amount is absolute, i.e. the amount overwrites any previous set values of that event. Note that this mode also overwrites any zone volume adjustments! If set to 1, the amount is relative to the actual value of the event. If set to 2, it behaves like mode 0 (absolute adjustment), except any zone volume adjustments are preserved. The different implications between absolute and relative adjustments are more apparent with more than one |
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 onA simple dynamic expander: lightly played notes will be softer, harder played notes will be louder.
See Also
delete_event_mark()
| |
|---|---|
Delete an event mark, i.e. ungroup the specified event from an event group. | |
| Unique identification number of the note event to be ungrouped. |
| One of 28 marks, |
See Also
Events and MIDI: $EVENT_ID, $ALL_EVENTS, $MARK_1 … $MARK_28
event_status()
|
|---|
Retrieves the status of a particular note event (or MIDI event in the multi script). These are the possible states:
|
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
Events and MIDI: $EVENT_STATUS_INACTIVE, $EVENT_STATUS_NOTE_QUEUE, $EVENT_STATUS_MIDI_QUEUE
fade_in()
| |
|---|---|
Performs a fade in for a specific note event. | |
| Unique identification number of the note event to be faded in. |
| 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
fade_out()
| |
|---|---|
Performs a fade-out for a specific note event. | |
| Unique identification number of the note event to be faded out. |
| The fade out time in microseconds. |
| 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
get_event_ids()
| |
|---|---|
Fills the specified array with all active event IDs. | |
| 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 event IDs, followed by one array index with its value set to 0.
Examples
on init
declare const $ARRAY_SIZE := 500
declare $a
declare $note_count
declare %test_array[$ARRAY_SIZE]
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 onMonitoring the number of active events.
See Also
get_event_mark()
| |
|---|---|
Checks if the specified event ID belongs to a specific event group (returns 1 if the bit mark is set, 0 otherwise). | |
| Unique identification number of the note event to be checked. |
| The bit mark, |
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 onA rather long-winded way to check if you've released a C key.
See Also
get_event_par()
| |
|---|---|
Returns the value of a specific event parameter of the specified event. | |
| Unique identification number of the note event to be changed. |
| The event parameter, either one of four freely assignable event parameters:
or the "built-in" parameters of a note event:
|
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 usingget_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
An event itself does not carry a zone ID (only a voice can carry zone IDs), therefore you need to insert wait(1) in order to properly retrieve the zone ID.
See Also
get_event_par_arr()
| |
|---|---|
Retrieves the value of a specified event parameter of a specific event. | |
| Unique identification number of the note event. |
| Can be one of the following:
|
| When used with:
|
Remarks
get_event_par_arr()is the array variant ofget_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 onA simple group monitor.
See Also
Events and MIDI: $EVENT_PAR_ALLOW_GROUP, $EVENT_PAR_MOD_VALUE_ID, $EVENT_PAR_CUSTOM , %GROUPS_AFFECTED
ignore_event()
|
|---|
Ignores a note event in |
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 variouschange_...()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
redirect_output()
| |
|---|---|
Routes the audio signal of the specified event to a specific output or bus. | |
| Unique identification number of the note event to be routed. |
| Can be one of the following:
|
| Specifies the output channel, aux channel or instrument bus, depending on Has no effect when |
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 onCreating a major triad and routing each note to a separate instrument bus.
set_event_mark()
| |
|---|---|
Assigns the specified event ID to a specific event group. | |
| Unique identification number of the note event. |
| One of 28 marks, from |
Remarks
When working with commands that deal with event IDs, you can group events by using
by_marks()instead of using individual IDs, as Kontakt 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
Events and MIDI: $EVENT_ID, $ALL_EVENTS, $MARK_1 … $MARK_28
set_event_par()
| |
|---|---|
Assigns a specific event parameter value to a specific event. | |
| Unique identification number of the note event. |
| The event parameter, either one of four freely assignable event parameters:
or the "built-in" parameters of a note event:
|
| 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 usingget_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 onSetting 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 onRelease velocity in MPE (MIDI Polyphonic Expression) context.
See Also
set_event_par_arr()
| |
|---|---|
Assigns an event parameter array to a specific event. | |
| Unique identification number of the note event. |
| Can be one of the following:
|
| When used with:
|
| When used with:
|
Remarks
set_event_par_arr()is the array variant ofset_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 onMaking 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 onSimple 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 onOnly middle C (MIDI note 60) will have any modulation applied, facilitated by "from script" modulator that has its ID set to "1".
See Also
Events and MIDI: $EVENT_PAR_ALLOW_GROUP
set_map_editor_event_color()
| |
|---|---|
Assigns the specified color to events generated in the current script slot, visible in Kontakt's Mapping Editor. | |
| The hexadecimal color value in the following format:
The 0 at the start lets Kontakt know the value is a number. The h at the end indicates that it is a hexadecimal value. You can also use uppercase H. |
Remarks
This command is only available in
on initcallback.The specified color will always be drawn 50% opaque, so that cases of overlapping events from multiple script slots could be discerned.
This command will only work if script generated events are allowed to be displayed in Kontakt's Mapping Editor (option available in Mapping Editor's Edit menu).
Examples
on init
set_map_editor_event_color(000FF00h)
end on
on note
play_note(($EVENT_NOTE + 12) mod 127, $EVENT_VELOCITY, 0, -1)
end on
Add a note played an octave up. This event will be shown as a green blip in Kontakt's Mapping Editor.