Zone Commands
User Zone Information
User zones are a special kind of zone that allow for zone creation and manipulation “on the fly”, and can be used to allow user interaction with the sampled content within an instrument (for example, in conjunction with sample drag-and-drop). These zones must be declared in the on init
callback.
When a user zone is created, all zone parameters will be set to 0 by default (root key, high velocity, high note, low note etc…). Therefore, the zone will not show in the Mapping Editor’s normal view, however it will be listed and present in the List View and in KONTAKT's sidepane Monitor->Zones sub-tab.
Note that some of the functions listed below only work on user zones, while some also work on every zone.
Zone and Slice Functions
|
---|
Returns the zone ID for the specified zone name. Only available in the |
|
---|
Returns the length of the specified zone's sample in microseconds |
|
---|
Returns the number of slices in the specified zone |
|
---|
Returns the length of the specified slice in microseconds, with respect to the current tempo |
|
---|
Returns the absolute start point of the specified slice in microseconds, independent of the current tempo |
|
---|
Returns the index number of the slice at the loop start |
|
---|
Returns the index number of the slice at the loop end |
|
---|
Returns the loop count of the specified loop |
|
---|
Play the specified event in Sampler mode (only makes sense when the groups allowed for playback are in one of Machine modes) |
get_loop_par()
| |
---|---|
Returns the loop parameters of a zone | |
| The ID of the zone |
| The index number of the loop |
| The following parameters are available:
|
Remarks
get_loop_par()
works on every loop from every zoneThis function runs synchronously
Examples
message(get_loop_par($myZoneId, 0, $LOOP_PAR_MODE))
get_num_zones()
| |
---|---|
Returns the total number of all zones that are present in the instrument (regular and user zones) |
Remarks
This function runs synchronously
Examples
on init message(get_num_zones()) end on
Quite self-explanatory
get_sample()
| |
---|---|
Returns paths, file names and extensions of samples. | |
| The ID of the zone |
| The following parameters are available:
|
Remarks
get_sample()
works on every zoneThis function runs synchronously
Examples
message(get_sample(%NI_USER_ZONE_IDS[0], $NI_FILE_NAME))
See Also
get_zone_id()
| |
---|---|
Returns the ID of the zone with the specified zone index | |
| Index of the zone (ordinal number of the zone in the Monitor->Zones list) |
Examples
on init set_snapshot_type(3) { Must be 2 or 3 or else set_zone_par works only on user zones } declare ui_slider $slider (0, 127) declare ui_label $label (1, 1) $slider := get_zone_par(get_zone_id(0), $ZONE_PAR_ROOT_KEY) message("This instrument contains " & get_num_zones() & " zones.") end on on ui_control ($slider) set_zone_par(get_zone_id(0), $ZONE_PAR_ROOT_KEY, $slider) set_text($label, get_zone_par(0, $ZONE_PAR_ROOT_KEY)) end on
Adjusting the root key of the first zone in the instrument
get_zone_par()
| |
---|---|
Returns the zone parameters | |
| The ID of the zone |
| The following parameters are available:
|
Remarks
get_zone_par()
works on every zone$ZONE_PAR_BPM
returns the BPM value multiplied by 1000, so 120 BPM would be 120000.This function runs synchronously
Examples
get_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_PAN)
get_zone_status()
| |
---|---|
Queries the status of the zone ID in question. Zone status has four possible states:
| |
| The ID of the zone |
Remarks
This command requires a valid zone ID that exists in the instrument. For example, if coupled with
get_event_par(<event-id>, $EVENT_PAR_ZONE_ID)
a zone ID is not found (which would happen when attempting playback of an empty user zone or a purged zone),get_zone_status()
will throw a script warning.get_zone_status()
works on every zoneThis function runs synchronously
Examples
on init declare ui_value_edit $ZoneID (0, 1000, 1) end on on ui_control ($ZoneID) select (get_zone_status($ZoneID)) case $NI_ZONE_STATUS_EMPTY message("Zone ID " & $zoneID & " is empty!") case $NI_ZONE_STATUS_LOADED message("Zone ID " & $zoneID & " is loaded!") case $NI_ZONE_STATUS_PURGED message("Zone ID " & $zoneID & " is purged!") case $NI_ZONE_STATUS_IGNORED message("Zone ID " & $zoneID & " is ignored!") end select end on
Query the status of the first 1001 zone IDs
set_loop_par()
| |
---|---|
Sets the loop parameters of a user zone | |
| The ID of the zone |
| The index number of the loop |
| The following parameters are available:
|
| The value of the loop parameter |
Remarks
set_loop_par()
only works for setting user zone loops when using snapshot modes 0 and 1. In case of using snapshot modes 2 and 3,set_loop_par()
will work for all zones, when called frominit
andpersistence_changed
callbacks!When executed in the
init
callback, this function runs synchronously and returns -1When executed outside the
init
callback, this function runs asynchronously and returns an async ID
Examples
wait_async(set_loop_par(%NI_USER_ZONE_IDS[0], 0, $LOOP_PAR_MODE, $SampleLoopOnA))
set_num_user_zones()
| |
---|---|
Creates empty user zones | |
| Defines the number of user zones to be created. |
Remarks
A maximum of 1024 user zones per instrument can be created
User zones are shown with a different color in the mapping editor
User zones cannot be modified from the mapping editor
In order to manipulate the user zones, the IDs stored in the
%NI_USER_ZONE_IDS
array should be used, instead of the hardcoded zone IDs
Examples
on init set_num_user_zones(2) set_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_GROUP, 0) set_zone_par(%NI_USER_ZONE_IDS[1], $ZONE_PAR_GROUP, 1) end on
Create two empty zones and place each to its own group
set_sample()
| |
---|---|
Sets the user sample in a zone | |
| The ID of the zone |
| The sample path of the sample |
Remarks
set_sample()
only works for user zones when using snapshot modes 0 and 1. In case of using snapshot modes 2 and 3,set_sample()
will work for all zones, when called frominit
andpersistence_changed
callbacks!When executed in the
init
callback, this function runs synchronously and returns -1When executed outside the
init
callback, this function runs asynchronously and returns an async ID
Examples
on ui_control ($myMouseArea) if ($NI_MOUSE_EVENT_TYPE = $NI_MOUSE_EVENT_TYPE_DROP) if (num_elements(!NI_DND_ITEMS_AUDIO) = 1) $async_lock := 1 wait_async(set_sample(%NI_USER_ZONE_IDS[0], !NI_DND_ITEMS_AUDIO[0])) end on
set_zone_par()
| |
---|---|
Sets the user zone parameters | |
| The ID of the zone |
| The following flags are available:
|
| The value of the zone parameter |
Remarks
set_zone_par()
only works for user zones when using snapshot modes 0 and 1. In case of using snapshot modes 2 and 3,set_zone_par()
will work for all zones, when called frominit
andpersistence_changed
callbacks!When executed in the
init
callback, this function runs synchronously and returns -1When executed outside the
init
callback, this function runs asynchronously and returns an async ID$ZONE_PAR_BPM
requires an input value multiplied by 1000, so 120 BPM would be 120000. Valid BPM input range is 0.1 to 400 BPM. Setting the BPM is not supported for REX files!
Examples
set_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_GROUP, 0)