Skip to main content
  • KSP Reference Manual
  • Zone Commands

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

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 loop parameters of a zone

<zone_id>

The ID of the zone

<loop-index>

The index number of the loop

<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 every loop from every zone

  • This function runs synchronously

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 (regular and user zones)

Remarks

  • This function runs synchronously

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

Remarks

  • get_sample() works on every zone

  • This function runs synchronously

Examples

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

See Also

Sample Parameters

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

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

Returns the zone parameters

<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_BPM

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

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 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 zone

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

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 number of the loop

<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 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 from init and persistence_changed callbacks!

  • When executed in the init callback, this function runs synchronously and returns -1

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

set_num_user_zones(<number_of_user_zones>)

Creates empty user zones

<number_of_user_zones>

Defines the number of user zones to be created. %NI_USER_ZONE_IDS is the array of size <number_of_user_zones> 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 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()

set_sample(<zone-id>,<sample-path>)

Sets the user sample in a zone

<zone-id>

The ID of the zone

<sample-path>

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 from init and persistence_changed callbacks!

  • When executed in the init callback, this function runs synchronously and returns -1

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

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 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 from init and persistence_changed callbacks!

  • When executed in the init callback, this function runs synchronously and returns -1

  • When 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)