Zone Commands

User Zone Information

User zones are a special kind of a 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 Mapping Editor's List View and in Kontakt's Monitor → Zones pane.

Zone and Slice Functions

`find_zone(<zone-name>)`
Returns the zone ID for the specified zone name. Only available in the `on init` callback.

`get_sample_length(<zone-id>)`
Returns the length of the specified zone's sample in microseconds.

`num_slices_zone(<zone-id>)`
Returns the number of slices in the specified zone.

`zone_slice_length(<zone-id>, <slice-index>)`
Returns the length of the specified slice in microseconds, with respect to the current tempo.

`zone_slice_start(<zone-id>,<slice-index>)`
Returns the absolute start point of the specified slice in microseconds, independent of the current tempo.

`zone_slice_idx_loop_start(<zone-id>, <loop-index>)`
Returns the index number of the slice at the loop start.

`zone_slice_idx_loop_end(<zone-id>, <loop-index>)`
Returns the index number of the slice at the loop end.

`zone_slice_loop_count(<zone-id>, <loop-index>)`
Returns the loop count of the specified loop.

`dont_use_machine_mode(<ID-number>)`
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()

`get_loop_par(<zone-id>, <loop-index>, <parameter>)`
Returns the value of a particular loop parameter of a zone.
`<zone-id>`	The ID of the zone.
`<loop-index>`	The index of the loop (0 ... 7).
`<parameter>`	The following parameters are available: `$LOOP_PAR_MODE` `$LOOP_PAR_START` `$LOOP_PAR_LENGTH` `$LOOP_PAR_XFADE` `$LOOP_PAR_COUNT` `$LOOP_PAR_TUNING`

Remarks

get_loop_par() works on both normal and user zones.

Examples

message(get_loop_par($myZoneId, 0, $LOOP_PAR_MODE))

get_num_zones()

`get_num_zones()`
Returns the total number of all zones that are present in the instrument (normal and user zones).

Examples

on init
    message(get_num_zones())
end on

Quite self-explanatory.

get_sample()

`get_sample(<zone-id>, <return-parameter>)`
Returns paths, file names and extensions of samples.
`<zone-id>`	The ID of the zone.
`<return-parameter>`	The following parameters are available: `$NI_FILE_NAME` `$NI_FILE_FULL_PATH` `$NI_FILE_FULL_PATH_OS` `$NI_FILE_EXTENSION`

get_sample(<zone-id>, <return-parameter>)

Returns paths, file names and extensions of samples.

<zone-id>

The ID of the zone.

<return-parameter>

The following parameters are available:

$NI_FILE_NAME

$NI_FILE_FULL_PATH

$NI_FILE_FULL_PATH_OS

$NI_FILE_EXTENSION

Remarks

get_sample() works on both normal and user zones.
Always use forwards slash (/) when working with absolute file paths in Kontakt!

Examples

message(get_sample(%NI_USER_ZONE_IDS[0], $NI_FILE_NAME))

get_sel_zones_idx()

`get_sel_zones_idx(<array-name>)`
Fills the specified array with indices of all selected zones in Kontakt's Mapping Editor.
`<array-name>`	Array to be filled with indices of selected zones.

Remarks

The command overwrites all existing values as long as there are selected zones. If there are more selected zones than array indices, the array will be filled until it is full, ignoring the remaining selected zones.
If there are less selected zones than array indices, the array will be filled from the beginning with all selected zone indices, followed by one array index with its value set to -1.
This command allows relative adjustment of various zone parameters like zone volume, pan, tune, etc.

Examples

on init
    message("")

    set_snapshot_type(3) { Must be 2 or 3 or else set_zone_par works only on user zones }

    declare $a
    declare $i
    declare $zone_id
    declare %sel_zones[1000]
    declare %zone_par[4] := ($ZONE_PAR_VOLUME, $ZONE_PAR_VOLUME, $ZONE_PAR_TUNE, $ZONE_PAR_TUNE)
    declare %offset[4] := (-1, 1, -1, 1)
end on

on note
    { pressing the lowest A on an 88-key MIDI controler will gather all selected zones }
    if ($EVENT_NOTE = 21)
        get_sel_zones_idx(%sel_zones)
    end if

    { pressing the following 4 keys will adjust volume down and up 0.01 dB, then tuning down and up 1 cent }
    if (in_range($EVENT_NOTE, 22, 25))
        ignore_event($EVENT_ID)

        $a := $EVENT_NOTE - 22
        $i := 0
        while ($i < num_elements(%sel_zones))
            if (%sel_zones[$i] > -1)
                $zone_id := get_zone_id(%sel_zones[$i])

                set_zone_par($zone_id, ...
                             %zone_par[$a], ...
                             get_zone_par($zone_id, %zone_par[$a]) + %offset[$a])
            end if

            inc($i)
        end while

        exit
    end if
end on

Using the lowest keys of an 88 key MIDI controller to finely adjust zone volume and tuning in 0.01 steps

get_zone_id()

`get_zone_id(<zone-index>)`
Returns the ID of the zone with the specified zone index.
`<zone-index>`	Index of the zone (see Index column in Monitor → Zones pane in Kontakt) .

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

`get_zone_par(<zone-id>, <parameter>)`
Returns the value of a particular zone parameter.
`<zone-id>`	The ID of the zone.
`<parameter>`	The following parameters are available: `$ZONE_PAR_HIGH_KEY` `$ZONE_PAR_LOW_KEY` `$ZONE_PAR_HIGH_VELO` `$ZONE_PAR_LOW_VELO` `$ZONE_PAR_ROOT_KEY` `$ZONE_PAR_FADE_LOW_KEY` `$ZONE_PAR_FADE_HIGH_KEY` `$ZONE_PAR_FADE_LOW_VELO` `$ZONE_PAR_FADE_HIGH_VELO` `$ZONE_PAR_VOLUME` `$ZONE_PAR_PAN` `$ZONE_PAR_TUNE` `$ZONE_PAR_GROUP` `$ZONE_PAR_SAMPLE_START` `$ZONE_PAR_SAMPLE_END` `$ZONE_PAR_SAMPLE_MOD_RANGE` `$ZONE_PAR_SAMPLE_RATE` `$ZONE_PAR_SELECTED` `$ZONE_PAR_BPM`

get_zone_par(<zone-id>, <parameter>)

Returns the value of a particular zone parameter.

<zone-id>

The ID of the zone.

<parameter>

The following parameters are available:

$ZONE_PAR_HIGH_KEY

$ZONE_PAR_LOW_KEY

$ZONE_PAR_HIGH_VELO

$ZONE_PAR_LOW_VELO

$ZONE_PAR_ROOT_KEY

$ZONE_PAR_FADE_LOW_KEY

$ZONE_PAR_FADE_HIGH_KEY

$ZONE_PAR_FADE_LOW_VELO

$ZONE_PAR_FADE_HIGH_VELO

$ZONE_PAR_VOLUME

$ZONE_PAR_PAN

$ZONE_PAR_TUNE

$ZONE_PAR_GROUP

$ZONE_PAR_SAMPLE_START

$ZONE_PAR_SAMPLE_END

$ZONE_PAR_SAMPLE_MOD_RANGE

$ZONE_PAR_SAMPLE_RATE

$ZONE_PAR_SELECTED

$ZONE_PAR_BPM

Remarks

get_zone_par() works on both normal and user zones.
$ZONE_PAR_BPM returns the BPM value multiplied by 1000, so 120 BPM would be 120000.

Examples

get_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_PAN)

get_zone_status()

`get_zone_status(<zone-ID>)`
Queries the status of the zone ID in question. Zone status has four possible states: `$NI_ZONE_STATUS_EMPTY` Zone is a user zone and has no sample loaded `$NI_ZONE_STATUS_LOADED` Zone is a user zone and has a sample loaded `$NI_ZONE_STATUS_PURGED` Zone is purged from memory (valid for both regular and user zones) `$NI_ZONE_STATUS_IGNORED` Zone is ignored by the user response in the Content Missing dialog (valid for both regular and user zones)
`<zone-ID>`	The ID of the zone.

get_zone_status(<zone-ID>)

Queries the status of the zone ID in question. Zone status has four possible states:

$NI_ZONE_STATUS_EMPTY Zone is a user zone and has no sample loaded
$NI_ZONE_STATUS_LOADED Zone is a user zone and has a sample loaded
$NI_ZONE_STATUS_PURGED Zone is purged from memory (valid for both regular and user zones)
$NI_ZONE_STATUS_IGNORED Zone is ignored by the user response in the Content Missing dialog (valid for both regular and user zones)

<zone-ID>

The ID of the zone.

Remarks

This command requires a valid zone ID that exists in the instrument. For example, if when using get_event_par() 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 both normal and user zones.

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

`set_loop_par(<zone-id>, <loop-index>, <parameter>, <value>`
Sets the loop parameters of a user zone.
`<zone-id>`	The ID of the zone.
`<loop-index>`	The index of the loop (0 ... 7).
`<parameter>`	The following parameters are available: `$LOOP_PAR_MODE` `$LOOP_PAR_START` `$LOOP_PAR_LENGTH` `$LOOP_PAR_XFADE` `$LOOP_PAR_COUNT` `$LOOP_PAR_TUNING`
`<value>`	The value of the loop parameter.

Remarks

set_loop_par() only works on user zones.
When executed in the on init callback, this function runs synchronously and returns -1.
When executed outside of the on init callback, this function returns an async ID and triggers the on async_complete callback.
Since Kontakt 7.2, the performance of this command has been improved. Previously, every execution of this command required suspending then resuming the audio engine. Moving forward, execution of this command has been delayed until the first wait() command, or until the end of the callback, whichever comes first. So, if it is required to set a lot of zone parameters in batch, it is recommended to first collect all the async IDs into an array, and only then run any wait() commands, as shown in the description of wait_async() command.

Examples

wait_async(set_loop_par(%NI_USER_ZONE_IDS[0], 0, $LOOP_PAR_MODE, $SampleLoopOnA))

set_num_user_zones()

`set_num_user_zones(<value>)`
Creates empty user zones.
`<value>`	Defines the number of user zones to be created. `%NI_USER_ZONE_IDS` is the array of size `<value>` with all the user zone IDs.

Remarks

A maximum of 1024 user zones per instrument can be created.
User zones are shown with a different color in Kontakt's Mapping Editor.
User zones cannot be modified from Mapping Editor or Wave Editor.
In order to manipulate the user zones, the IDs stored in the %NI_USER_ZONE_IDS array should be used instead of the hard-coded 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()

`set_sample(<zone-id>, <path>)`
Sets the user sample in a zone.
`<zone-id>`	The ID of the zone.
`<path>`	The file path to the sample to be loaded.

Remarks

set_sample() only works on user zones.
When executed in the on init callback, this function runs synchronously and returns -1.
When executed outside of the on init callback, this function returns an async ID and triggers the on async_complete callback.
Since Kontakt 7.2, the performance of this command has been improved. Previously, every execution of this command required suspending then resuming the audio engine. Moving forward, execution of this command has been delayed until the first wait() command, or until the end of the callback, whichever comes first. So, if it is required to set a lot of zone parameters in batch, it is recommended to first collect all the async IDs into an array, and only then run any wait() commands, as shown in the description of wait_async() command.
Always use forwards slash (/) when working with absolute file paths in Kontakt!

Examples

on ui_control ($myMouseArea)    
    if ($NI_MOUSE_EVENT_TYPE = $NI_MOUSE_EVENT_TYPE_DROP)      
        if (num_elements(!NI_DND_ITEMS_AUDIO) = 1)            
            wait_async(set_sample(%NI_USER_ZONE_IDS[0], !NI_DND_ITEMS_AUDIO[0]))
        end if
    end if
end on

set_zone_par()

`set_zone_par(<zone-id>, <parameter>, <value>)`
Sets the user zone parameters.
`<zone-id>`	The ID of the zone.
`<parameter>`	The following flags are available: `$ZONE_PAR_HIGH_KEY` `$ZONE_PAR_LOW_KEY` `$ZONE_PAR_HIGH_VELO` `$ZONE_PAR_LOW_VELO` `$ZONE_PAR_ROOT_KEY` `$ZONE_PAR_FADE_LOW_KEY` `$ZONE_PAR_FADE_HIGH_KEY` `$ZONE_PAR_FADE_LOW_VELO` `$ZONE_PAR_FADE_HIGH_VELO` `$ZONE_PAR_VOLUME` `$ZONE_PAR_PAN` `$ZONE_PAR_TUNE` `$ZONE_PAR_GROUP` `$ZONE_PAR_SAMPLE_START` `$ZONE_PAR_SAMPLE_END` `$ZONE_PAR_SAMPLE_MOD_RANGE` `$ZONE_PAR_BPM`
`<value>`	The value of the zone parameter

Remarks

set_zone_par() only works on user zones when using snapshot modes 0 and 1. In case of using snapshot modes 2 and 3, set_zone_par() will work on both normal and user zones, from any callback (please excercise caution with "fast" callback types, like on controller or on listener)!
When executed in the on init callback, this function runs synchronously and returns -1.
When executed outside of the on init callback, this function returns an async ID and triggers the on async_complete callback.
$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!
Since Kontakt 7.2, the performance of this command has been improved. Previously, every execution of this command required suspending then resuming the audio engine. Moving forward, execution of this command has been delayed until the first wait() command, or until the end of the callback, whichever comes first. So, if it is required to set a lot of zone parameters in batch, it is recommended to first collect all the async IDs into an array, and only then run any wait() commands, as shown in the description of wait_async() command.

Examples

set_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_GROUP, 0)

Zone Commands

User Zone Information

Zone and Slice Functions

get_loop_par()

Remarks

Examples

See Also

get_num_zones()

Examples

get_sample()

Remarks

Examples

See Also

get_sel_zones_idx()

Remarks

Examples

get_zone_id()

Examples

get_zone_par()

Remarks

Examples

See Also

get_zone_status()

Remarks

Examples

set_loop_par()

Remarks

Examples

See Also

set_num_user_zones()

Remarks

Examples

set_sample()

Remarks

Examples

See Also

set_zone_par()

Remarks

Examples

See Also

Search results