Skip to main content

Zone Commands

General 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 via script in the on init callback.

When a user zone is created the mapping is set to 0 on all zone parameters by default (root key, high velocity, high note, low note etc…). Therefore, the zone will not show in the mapping editor’s normal view (it will be listed and present in the list view).

Note that some of the functions listed below only work on user zones, while some also work on every zone.

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_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: $NI_FILE_NAME, $NI_FILE_FULL_PATH, $NI_FILE_FULL_PATH_OS, $NI_FILE_EXTENSION

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

Remarks

  • get_zone_par() works on every zone

  • This function runs synchronously

Examples

get_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_PAN)

is_zone_empty()

is_zone_empty(<zone-ID>)

Returns 1 if a zone is empty (has no sample), otherwise returns 0

<zone-ID>

The ID of the zone

Examples

message("Zone empty status: " & is_zone_empty(%NI_USER_ZONE_IDS[0]))

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 in user zone loops

  • 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, 30)    
    set_zone_par(%NI_USER_ZONE_IDS[1], $ZONE_PAR_GROUP, 31)
...
end on

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 in user zones

  • 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

<value>

The value of the zone parameter

Remarks

  • set_zone_par() only works in user zones

  • 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

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