KSPリファレンスマニュアル 19 - ゾーンコマンド（Zone Commands）

KSPリファレンスマニュアル 19 - ゾーンコマンド（Zone Commands）


ユーザーZone情報

ユーザーZoneは特殊な種類のZoneで、Zoneの作成と操作を“その場で”行えるようにするものです。インストゥルメント内のサンプルコンテンツに対してユーザーが操作できるようにする用途に使用できます（たとえばサンプルのドラッグアンドドロップと組み合わせる場合など）。これらのZoneはon initコールバックの中で宣言する必要があります。

ユーザーZoneが作成された時点では、すべてのZoneパラメーターが既定で0に設定されます（ルートキー、ハイベロシティ、ハイノート、ローノートなど）。そのためこのZoneはMapping Editorの通常のビューには表示されませんが、Mapping EditorのList View、およびKontaktのMonitor → Zonesペインには一覧表示され、存在しています。


ゾーンとスライスの関数

find_zone(<zone-name>)

指定したZone名のZone IDを返します。on initコールバックでのみ使用できます。

get_sample_length(<zone-id>)

指定したZoneのサンプルの長さをマイクロ秒単位で返します。

num_slices_zone(<zone-id>)

指定したZone内のスライスの数を返します。

zone_slice_length(<zone-id>, <slice-index>)

指定したスライスの長さを、現在のテンポを反映したマイクロ秒単位で返します。

zone_slice_start(<zone-id>,<slice-index>)

指定したスライスの絶対的な開始位置を、現在のテンポとは無関係にマイクロ秒単位で返します。

zone_slice_idx_loop_start(<zone-id>, <loop-index>)

ループスタート位置にあるスライスのインデックス番号を返します。

zone_slice_idx_loop_end(<zone-id>, <loop-index>)

ループエンド位置にあるスライスのインデックス番号を返します。

zone_slice_loop_count(<zone-id>, <loop-index>)

指定したループのループ回数を返します。

dont_use_machine_mode(<ID-number>)

指定したイベントをSampler modeで再生します（再生を許可されているグループがいずれかのMachine modeになっている場合にのみ意味があります）。


get_loop_par()

get_loop_par(<zone-id>, <loop-index>, <parameter>)

Zoneの特定のループパラメーターの値を返します。

<zone-id>

ZoneのIDです。

<loop-index>

ループのインデックスです（0 ... 7）。

<parameter>

以下のパラメーターを使用できます：

$LOOP_PAR_MODE

$LOOP_PAR_START

$LOOP_PAR_LENGTH

$LOOP_PAR_XFADE

$LOOP_PAR_COUNT

$LOOP_PAR_TUNING

補足

  • get_loop_par()は通常のZoneとユーザーZoneの両方で動作します。

例

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

関連項目

set_loop_par()


get_num_zones()

get_num_zones()

インストゥルメント内に存在するすべてのZoneの総数を返します（通常のZoneとユーザーZoneの両方）。

例

on init
    message(get_num_zones())
end on

説明の必要はないでしょう。


get_sample()

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

サンプルのパス、ファイル名、拡張子を返します。

<zone-id>

ZoneのIDです。

<return-parameter>

以下のパラメーターを使用できます：

$NI_FILE_NAME

$NI_FILE_FULL_PATH

$NI_FILE_FULL_PATH_OS

$NI_FILE_EXTENSION

補足

  • get_sample()は通常のZoneとユーザーZoneの両方で動作します。

  • Kontaktで絶対ファイルパスを扱うときは、必ずスラッシュ（/）を使用してください。

例

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

関連項目

set_sample()

サンプルパラメーター


get_sel_zones_idx()

get_sel_zones_idx(<array-name>)

KontaktのMapping Editorで選択されているすべてのZoneのインデックスを、指定した配列に格納します。

<array-name>

選択されているZoneのインデックスを格納する配列です。

補足

  • 選択されているZoneがある限り、このコマンドは既存の値をすべて上書きします。選択されているZoneの数が配列のインデックス数より多い場合、配列は満杯になるまで格納され、残りの選択されたZoneは無視されます。

  • 選択されているZoneの数が配列のインデックス数より少ない場合、配列の先頭から選択されたすべてのZoneのインデックスが格納され、続く1つのインデックスに値-1が設定されます。

  • このコマンドを使うと、Zoneのボリューム、パン、チューンなど、さまざまなZoneパラメーターを相対的に調整できます。

例

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

88鍵のMIDIコントローラーの最低音域のキーを使って、Zoneのボリュームとチューニングを0.01刻みで微調整する例です。


get_zone_id()

get_zone_id(<zone-index>)

指定したZoneインデックスを持つZoneのIDを返します。

<zone-index>

Zoneのインデックスです（KontaktのMonitor → ZonesペインにあるIndex列を参照してください）。

例

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

インストゥルメント内の最初のZoneのルートキーを調整する例です。


get_zone_par()

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

特定のZoneパラメーターの値を返します。

<zone-id>

ZoneのIDです。

<parameter>

以下のパラメーターを使用できます：

$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とユーザーZoneの両方で動作します。

  • $ZONE_PAR_BPMはBPM値を1000倍した値を返します。したがって120 BPMなら120000になります。

例

get_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_PAN)

関連項目

set_zone_par()


get_zone_status()

get_zone_status(<zone-ID>)

対象となるZone IDのステータスを問い合わせます。Zoneのステータスには4つの状態があります：

  • $NI_ZONE_STATUS_EMPTY ZoneはユーザーZoneで、サンプルが読み込まれていません

  • $NI_ZONE_STATUS_LOADED ZoneはユーザーZoneで、サンプルが読み込まれています

  • $NI_ZONE_STATUS_PURGED Zoneはメモリからパージされています（通常のZoneとユーザーZoneの両方で有効）

  • $NI_ZONE_STATUS_IGNORED ZoneはContent Missingダイアログでのユーザーの応答により無視されています（通常のZoneとユーザーZoneの両方で有効）

<zone-ID>

ZoneのIDです。

補足

  • このコマンドには、インストゥルメント内に実在する有効なZone IDが必要です。たとえばget_event_par()の使用時にZone IDが見つからない場合（空のユーザーZoneやパージされたZoneを再生しようとしたときに起こります）、get_zone_status()はスクリプト警告を発生させます。

  • get_zone_status()は通常のZoneとユーザーZoneの両方で動作します。

例

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

最初の1001個のZone IDのステータスを問い合わせる例です。


set_loop_par()

set_loop_par(<zone-id>, <loop-index>, <parameter>, <value>

ユーザーZoneのループパラメーターを設定します。

<zone-id>

ZoneのIDです。

<loop-index>

ループのインデックスです（0 ... 7）。

<parameter>

以下のパラメーターを使用できます：

$LOOP_PAR_MODE

$LOOP_PAR_START

$LOOP_PAR_LENGTH

$LOOP_PAR_XFADE

$LOOP_PAR_COUNT

$LOOP_PAR_TUNING

<value>

ループパラメーターの値です。

補足

  • set_loop_par()はユーザーZoneでのみ動作します。

  • on initコールバックの中で実行した場合、この関数は同期的に実行され、-1を返します。

  • on initコールバックの外で実行した場合、この関数は非同期IDを返し、on async_completeコールバックをトリガーします。

  • Kontakt 7.2以降、このコマンドのパフォーマンスは改善されています。以前はこのコマンドを実行するたびにオーディオエンジンの一時停止と再開が必要でした。今後は、このコマンドの実行は最初のwait()コマンドまで、またはコールバックの終わりまでのいずれか早いほうまで遅延されます。そのため、多数のZoneパラメーターをまとめて設定する必要がある場合は、まずすべての非同期IDを配列に集めてからwait()コマンドを実行することをおすすめします。wait_async()コマンドの説明に示されているとおりです。

例

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

関連項目

get_loop_par()

wait_async()


set_num_user_zones()

set_num_user_zones(<value>)

空のユーザーZoneを作成します。

<value>

作成するユーザーZoneの数を指定します。%NI_USER_ZONE_IDSは、すべてのユーザーZone IDを格納したサイズ<value>の配列です。

補足

  • 1つのインストゥルメントにつき最大1024個のユーザーZoneを作成できます。

  • ユーザーZoneは、KontaktのMapping Editorでは異なる色で表示されます。

  • ユーザーZoneはMapping EditorやWave Editorから変更することはできません。

  • ユーザーZoneを操作するには、ハードコードされたZone IDではなく、%NI_USER_ZONE_IDS配列に格納されているIDを使用してください。

例

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

2つの空のZoneを作成し、それぞれを別のグループに配置する例です。


set_sample()

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

Zoneにユーザーサンプルを設定します。

<zone-id>

ZoneのIDです。

<path>

読み込むサンプルへのファイルパスです。

補足

  • set_sample()はユーザーZoneでのみ動作します。

  • on initコールバックの中で実行した場合、この関数は同期的に実行され、-1を返します。

  • on initコールバックの外で実行した場合、この関数は非同期IDを返し、on async_completeコールバックをトリガーします。

  • Kontakt 7.2以降、このコマンドのパフォーマンスは改善されています。以前はこのコマンドを実行するたびにオーディオエンジンの一時停止と再開が必要でした。今後は、このコマンドの実行は最初のwait()コマンドまで、またはコールバックの終わりまでのいずれか早いほうまで遅延されます。そのため、多数のZoneパラメーターをまとめて設定する必要がある場合は、まずすべての非同期IDを配列に集めてからwait()コマンドを実行することをおすすめします。wait_async()コマンドの説明に示されているとおりです。

  • Kontaktで絶対ファイルパスを扱うときは、必ずスラッシュ（/）を使用してください。

例

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

関連項目

get_sample()

wait_async()


set_zone_par()

set_zone_par(<zone-id>, <parameter>, <value>)

ユーザーZoneのパラメーターを設定します。

<zone-id>

ZoneのIDです。

<parameter>

以下のフラグを使用できます：

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

Zoneパラメーターの値です

補足

  • set_zone_par()は、スナップショットモード0および1を使用している場合、ユーザーZoneでのみ動作します。スナップショットモード2および3を使用している場合、set_zone_par()は通常のZoneとユーザーZoneの両方に対して、どのコールバックからでも動作します（on controllerやon listenerのような「高速な」コールバックタイプでは十分に注意してください）。

  • on initコールバックの中で実行した場合、この関数は同期的に実行され、-1を返します。

  • on initコールバックの外で実行した場合、この関数は非同期IDを返し、on async_completeコールバックをトリガーします。

  • $ZONE_PAR_BPMには1000倍した入力値が必要です。したがって120 BPMなら120000になります。有効なBPMの入力範囲は0.1から400 BPMです。BPMの設定はREXファイルではサポートされていません。

  • Kontakt 7.2以降、このコマンドのパフォーマンスは改善されています。以前はこのコマンドを実行するたびにオーディオエンジンの一時停止と再開が必要でした。今後は、このコマンドの実行は最初のwait()コマンドまで、またはコールバックの終わりまでのいずれか早いほうまで遅延されます。そのため、多数のZoneパラメーターをまとめて設定する必要がある場合は、まずすべての非同期IDを配列に集めてからwait()コマンドを実行することをおすすめします。wait_async()コマンドの説明に示されているとおりです。

例

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

関連項目

get_zone_par()

wait_async()

参照元情報：Zone Commands
https://docs.native-instruments.com/online-guides/ksp-manual/en/zone-commands