KSPリファレンスマニュアル 8 - 一般コマンド（General Commands）

KSPリファレンスマニュアル 8 - 一般コマンド（General Commands）


disable_logging()

disable_logging(<event-type>)

メッセージ、警告、監視中の変数のイベントを、KontaktのステータスバーとCreator ToolsのDebuggerの両方に出力しないようにします。

<event-type>

出力を無効にするイベントタイプです。選択できるオプションは次のとおりです：

  • $NI_LOG_MESSAGE

  • $NI_LOG_WARNING

  • $NI_LOG_WATCHING

補足

  • このコマンドはon initコールバックでのみ使用できます。

例

on init
    disable_logging($NI_LOG_MESSAGE)
    disable_logging($NI_LOG_WARNING)
    disable_logging($NI_LOG_WATCHING)
end on

開発中は上記の行をコメントアウトしたままにしておき、製品を出荷する直前に元へ戻して、デバッグに関する内容が一切出力されないようにします。

関連項目

watch_var()

watch_array_idx()


exit

exit

コールバックを直ちに停止するか、関数を抜けます。

補足

  • exitは非常に強力なコマンドです。特に大きなスクリプトを扱うときは、使用に注意してください。

  • 関数の中で使用した場合、exitはその関数を抜けるだけで、コールバック全体は終了しません。

例

on note
    if (not in_range($EVENT_NOTE, 60, 71))
        exit
    end if

    { from here on, only notes between C3 to B3 will be processed }
end on

スクリプトの影響を受けるキーレンジを手早く設定したいときに便利です。

関連項目

wait()

stop_wait()


ignore_controller

ignore_controller

on controllerコールバックにおけるMIDI Continuous Controller、Pitch Bend、Channel Aftertouchのイベント、またはon poly_atコールバックにおけるPolyphonic Aftertouchのイベントを無視します。

例

on controller
    if ($CC_NUM = 1)
        ignore_controller
        set_controller($VCC_MONO_AT, %CC[1])
    end if
end on

モジュレーションホイールをアフタータッチに変換します。

関連項目

ignore_event()

set_controller()

on controller


message()

message(<variable-or-string>)

Kontaktのステータスラインにテキストを表示します。

補足

  • このコマンドは、スクリプトを書いている最中のデバッグとテストに使うことを想定しています。Kontaktにはステータスラインが1つしかないため、ユーザーとやり取りするための一般的な手段として使うべきではありません。その用途にはラベルウィジェットか、Creator ToolsのDebuggerペインを使用してください。

  • message("")をon initコールバックの先頭に書く習慣をつけてください。そうすれば、それまでのメッセージ（スクリプトによるものもシステムによるものも）がすべて消去され、新しいメッセージだけが表示されることが保証されます。

例

on init
    message("Hello, world!")
end on

KSPにおける、お約束の「Hello, world!」の実装です。

on note
    message("Note " & $EVENT_NOTE & " received at " &  $ENGINE_UPTIME & " milliseconds")
end on

message()コマンドの中で文字列と式を連結します。

関連項目

reset_ksp_timer

ui_label

set_text()

時間とトランスポート: $ENGINE_UPTIME, $KSP_TIMER


note_off()

note_off(<event-id>)

note_off(<event-id>, <time-offset>)

特定のノートイベントIDに対してMIDI Note Offメッセージを送信します。

<event-id>

変更するノートイベントの一意な識別番号です。

<time-offset>

ノートオフが実際に発生するまでの時間オフセットをマイクロ秒単位で指定する、省略可能な引数です。

補足

  • note_off()はキーを離すことと同等であり、常にon releaseコールバックをトリガーするとともに、ボリュームエンベロープのリリース部分へジャンプします。note_off()とfade_out()の違いに注意してください。fade_out()はボイス単位で動作します。

  • 省略可能な時間オフセットは、イベントに設定されている可能性のあるデュレーションを上書きします（つまり、play_note()コマンドの最後の引数が0より大きい場合です）。

例

on controller
    if ($CC_NUM = 1)
        note_off($ALL_EVENTS)
    end if
end on

モジュレーションホイールでトリガーする、独自の「All Notes Off」の実装です。

on init
    declare polyphonic $new_id
end on

on note
    ignore_event($EVENT_ID)
    $new_id := play_note($EVENT_NOTE, $EVENT_VELOCITY, 0, 0)
end on

on release
    ignore_event($EVENT_ID)
    wait(200000)
    note_off($new_id)
end on

各ノートのリリースを200ミリ秒だけ遅らせます。

on init
    declare ui_button $KillAll
end on

on note
    ignore_event($EVENT_ID)
    play_note($EVENT_NOTE, $EVENT_VELOCITY, 0, 5000000)
end on

on ui_control ($KillAll)
    note_off($ALL_EVENTS, 0)
    $KillAll := 0
end on

Kontakt 8より前は、上の例のようにデュレーションが5秒とあらかじめ決まっているイベントに対してnote_off()コマンドを使うことはできませんでした。省略可能な時間オフセット引数を使えば、これができるようになりました。

関連項目

fade_out()

play_note()


play_note()

play_note(<note-number>, <velocity>, <sample-offset>, <duration>)

ノートイベント、すなわちNote Onメッセージとそれに続くNote Offメッセージを生成します。

<note-number>

生成するMIDIノートナンバーです（0 ... 127）。

<velocity>

生成するノートのベロシティです（1 ... 127）。

<sample-offset>

マイクロ秒単位のサンプルオフセットです。

<duration>

生成するノートの長さをマイクロ秒単位で指定します。

このパラメーターは2つの特別な値も受け付けます：

-1：コールバックを開始したノートを離すと、サンプルが停止します。

0：サンプル全体が再生されます（ループしたサンプルには注意してください。この場合は無限に再生され続けます）。

補足

  • DFDモードでは、サンプルオフセットはそれぞれのZoneのSample Mod（S. Mod）の値に依存します（KontaktのWave Editorにあります）。ZoneのS. Modの設定より大きいサンプルオフセット値は無視され、サンプルオフセットは適用されません。

  • 次のように書くと、再生したノートイベントのイベントIDを変数に取得できます：

    <variable> := play_note(<note>, <velocity>, <sample-offset>, <duration>)

例

on note
    play_note($EVENT_NOTE + 12, $EVENT_VELOCITY, 0, -1)
end on

弾いたノートを1オクターブ上の音でハモらせます。

on init
    declare $new_id
end on

on controller
    if ($CC_NUM = 64)
        if (%CC[64] = 127)
            $new_id := play_note(60, 100, 0, 0)
        else
            note_off($new_id)
        end if
    end if
end on

サステインペダルを踏むとMIDIノートがトリガーされます。

関連項目

note_off()


set_controller()

set_controller(<controller>, <value>)

MIDI Continuous Controller、Pitch Bend、Channel Pressureのいずれかのメッセージを送信します。

<controller>

このパラメーターはタイプを設定し、MIDI CCの場合はCCナンバーも設定します：

• 数値（0 ... 127）はMIDI CCナンバーを指定します

• $VCC_PITCH_BENDはMIDI Pitch Bendを表します

• $VCC_MONO_ATはMIDI Channel Pressure（モノフォニックアフタータッチ）を表します

<value>

指定したコントローラーの値です。

• MIDI CCとChannel Pressureの値の範囲：0 ... 127

• MIDI Pitch Bendの値の範囲：-8192 ... 8191

補足

  • set_controller()はon initコールバックでは使用できません。何らかの理由でInstrumentのロード時にコントローラーの値を送信したい場合は、on persistence_changedコールバックを使用してください。

on note
    if ($EVENT_NOTE = 36)
        ignore_event($EVENT_ID)
        set_controller($VCC_MONO_AT, $EVENT_VELOCITY)
    end if
end on

on release
    if ($EVENT_NOTE = 36)
        ignore_event($EVENT_ID)
        set_controller($VCC_MONO_AT, 0)
    end if
end on

アフタータッチのないキーボードを使っている場合は、代わりにC1を押してください。

関連項目

ignore_controller

イベントとMIDI: $VCC_PITCH_BEND, $VCC_MONO_AT


set_note_controller()

set_note_controller(<controller>, <note-number>, <value>)

MIDI 2.0 Registered Per-Note Controller、MIDI 2.0 Assignable Per-Note Controller、MIDI 2.0 Per-Note Pitch Bendのいずれかのメッセージを送信します。

<controller>

このパラメーターはメッセージタイプを設定します

• 0 ... 255の数値はMIDI 2.0 Registered Per-Note Controllerを指定します

• 256 ... 511の数値はMIDI 2.0 Assignable Per-Note Controllerを指定します

• $VNC_PITCH_BENDはMIDI 2.0 Per-Note Pitch Bendを表します

<note-number>

MIDI 2.0のパーノートコントローラーを生成する対象のMIDIノートナンバーです（0 ... 127）。

<value>

指定したパーノートコントローラーの値です。

• MIDI 2.0 Per-Note Controllerの値の範囲：0 ... 127

• MIDI 2.0 Per-Note Pitch Bendの値の範囲：-8192 ... 8191

補足

  • set_note_controller()はon initコールバックでは使用できません。何らかの理由でInstrumentのロード時にコントローラーの値を送信したい場合は、on persistence_changedコールバックを使用してください。

on init
    set_ui_height(3)

    declare $i
    declare %black[5] := (1, 3, 6, 8, 10)
    declare %key_id[128]

    declare ui_label $L (1, 1)
    declare ui_table %Active[61] (6, 1, 1)
    declare ui_table %BG[61] (6, 1, 1)
    declare ui_table %KB[61] (6, 1, -8191)

    set_control_par(get_ui_id(%KB), $CONTROL_PAR_HIDE, $HIDE_PART_BG .or. $HIDE_PART_VALUE)
    set_control_par(get_ui_id(%KB), $CONTROL_PAR_WIDTH, 555)
    set_control_par(get_ui_id(%KB), $CONTROL_PAR_HEIGHT, 110)

    set_control_par(get_ui_id(%BG), $CONTROL_PAR_HIDE, $HIDE_PART_BG)
    set_control_par(get_ui_id(%BG), $CONTROL_PAR_WIDTH, 555)
    set_control_par(get_ui_id(%BG), $CONTROL_PAR_HEIGHT, 110)
    set_control_par(get_ui_id(%BG), $CONTROL_PAR_BAR_COLOR, 0777777H)

    set_control_par(get_ui_id(%Active), $CONTROL_PAR_WIDTH, 555)
    set_control_par(get_ui_id(%Active), $CONTROL_PAR_HEIGHT, 110)
    set_control_par(get_ui_id(%Active), $CONTROL_PAR_BAR_COLOR, 0AAAAAAH)

    set_control_par(get_ui_id($L), $CONTROL_PAR_HIDE, $HIDE_PART_BG)
    set_control_par(get_ui_id($L), $CONTROL_PAR_WIDTH, 560)
    set_control_par(get_ui_id($L), $CONTROL_PAR_FONT_TYPE, 19)

    set_text($L, "C1                               " & ...
                 "C2                               " & ...
                 "C3                               " & ...
                 "C4                               " & ...
                 "C5                               " & ...
                 "C6")

    while ($i < num_elements(%BG))
        if (search(%black, $i mod 12) # -1)
            %BG[$i] := 1
        end if

        inc($i)
    end while

    move_control_px($L, 55, 0)
    move_control_px(%BG, 62, 15)
    move_control_px(%Active, 62, 15)
    move_control_px(%KB, 62, 15)
end on

on note
    { make sure we only have one event per key }
    if (event_status(%key_id[$EVENT_NOTE]) = $EVENT_STATUS_NOTE_QUEUE)
        fade_out(%key_id[$EVENT_NOTE], 1000, 1)
    end if

    %key_id[$EVENT_NOTE] := $EVENT_ID

    set_note_controller($VNC_PITCH_BEND, $EVENT_NOTE, %KB[$EVENT_NOTE - 36])

    if (in_range($EVENT_NOTE, 36, 96))
        %Active[$EVENT_NOTE - 36] := 1
    end if
end on

on release
    if (in_range($EVENT_NOTE, 36, 96))
        %Active[$EVENT_NOTE - 36] := 0
    end if
end on

on ui_control (%KB)
    set_note_controller($VNC_PITCH_BEND, 36 + $NI_CONTROL_PAR_IDX, %KB[$NI_CONTROL_PAR_IDX])
end on
on init
    declare const $BEND_RANGE := 2

    declare $i
    declare %events[128]
end on

on note
    %events[$EVENT_NOTE] := $EVENT_ID
end on

on note_controller
    if ($NC_NUM = $VNC_PITCH_BEND and in_range($NC_NOTE, 36, 96))
        change_tune(%events[$NC_NOTE], int(real($NC_VALUE) * 12.208522) * $BEND_RANGE, 0)
    end if
end on

set_poly_at()コマンドの例に似ていますが、こちらは2つのスクリプトスロットを必要とします。1つ目のスロットがMIDI 2.0のノートコントローラーメッセージを送信し、2つ目がそのメッセージを受けて独自のパーノートピッチベンド変化を適用します。

関連項目

ignore_controller

イベントとMIDI: $VNC_PITCH_BEND


set_poly_at()

set_poly_at(<note-number>, <value>)

MIDI Polyphonic Aftertouchメッセージを送信します。

<note-number>

Polyphonic Aftertouchメッセージを生成する対象のMIDIノートです（0 ... 127）。

<value>

Polyphonic Aftertouchメッセージの値です（0 ... 127）。

補足

  • set_poly_at()はon initコールバックでは使用できません。何らかの理由でInstrumentのロード時にPolyphonic Aftertouchメッセージを送信したい場合は、on persistence_changedコールバックを使用してください。

on init
    set_ui_height(3)

    declare $i
    declare %black[5] := (1, 3, 6, 8, 10)

    declare ui_label $L (1, 1)
    declare ui_table %Active[61] (6, 1, 1)
    declare ui_table %BG[61] (6, 1, 1)
    declare ui_table %KB[61] (6, 1, 127)

    set_control_par(get_ui_id(%KB), $CONTROL_PAR_HIDE, $HIDE_PART_BG .or. $HIDE_PART_VALUE)
    set_control_par(get_ui_id(%KB), $CONTROL_PAR_WIDTH, 555)
    set_control_par(get_ui_id(%KB), $CONTROL_PAR_HEIGHT, 110)

    set_control_par(get_ui_id(%BG), $CONTROL_PAR_HIDE, $HIDE_PART_BG)
    set_control_par(get_ui_id(%BG), $CONTROL_PAR_WIDTH, 555)
    set_control_par(get_ui_id(%BG), $CONTROL_PAR_HEIGHT, 110)
    set_control_par(get_ui_id(%BG), $CONTROL_PAR_BAR_COLOR, 0777777H)

    set_control_par(get_ui_id(%Active), $CONTROL_PAR_WIDTH, 555)
    set_control_par(get_ui_id(%Active), $CONTROL_PAR_HEIGHT, 110)
    set_control_par(get_ui_id(%Active), $CONTROL_PAR_BAR_COLOR, 0AAAAAAH)

    set_control_par(get_ui_id($L), $CONTROL_PAR_HIDE, $HIDE_PART_BG)
    set_control_par(get_ui_id($L), $CONTROL_PAR_WIDTH, 560)
    set_control_par(get_ui_id($L), $CONTROL_PAR_FONT_TYPE, 19)

    set_text($L, "C1                               " & ...
                 "C2                               " & ...
                 "C3                               " & ...
                 "C4                               " & ...
                 "C5                               " & ...
                 "C6")

    while ($i < num_elements(%BG))
        if (search(%black, $i mod 12) # -1)
            %BG[$i] := 1
        end if

        inc($i)
    end while

    move_control_px($L, 55, 0)
    move_control_px(%BG, 62, 15)
    move_control_px(%Active, 62, 15)
    move_control_px(%KB, 62, 15)
end on

on note
    if (in_range($EVENT_NOTE, 36, 96))
        %Active[$EVENT_NOTE - 36] := 1
    end if
end on

on release
    if (in_range($EVENT_NOTE, 36, 96))
        %Active[$EVENT_NOTE - 36] := 0
    end if
end on

on ui_control (%KB)
    set_poly_at(36 + $NI_CONTROL_PAR_IDX, %KB[$NI_CONTROL_PAR_IDX])
end on

on poly_at
    if (in_range($POLY_AT_NUM, 36, 96))
        %KB[$POLY_AT_NUM - 36] := %POLY_AT[$POLY_AT_NUM]
    end if
end on

ポリフォニックアフタータッチに対応したキーボードがない場合は、これらのイベントを送信するこのテーブルを使ってみてください（標準的な5オクターブのキーボードの範囲です）。入力されるポリフォニックアフタータッチメッセージのモニタリングツールとしても使えます！

関連項目

ignore_controller


set_rpn()/set_nrpn()

set_rpn(<address>, <value>)

set_nrpn(<address>, <value>)

MIDIのRPNまたはNRPNメッセージを送信します。

<address>

RPNまたはNRPNのアドレスです（0 ... 16383）。

<value>

RPNまたはNRPNメッセージの値です（0 ... 16383）。

補足

  • KontaktはRPNやNRPNのメッセージを外部モジュレーションソースとして扱うことはできません。ただし、これらのメッセージをスクリプト間の簡単なやり取りに使うことはできます。

関連項目

on rpn/nrpn

set_controller()

msb()

lsb()

イベントとMIDI: $RPN_ADDRESS, $RPN_VALUE


set_snapshot_type()

set_snapshot_type(<type>)

Snapshotを保存またはリコールするときの、5つのスロットすべての動作を設定します。

<type>

利用できるタイプは次のとおりです：

0：Snapshotの切り替え時に必ずinitコールバックが実行され、続いてon persistence_changedコールバックが実行されます（既定の動作）。

1：Snapshotのロード時にinitコールバックは実行されず、on persistence_callbackだけが実行されます。

2：タイプ0と同じですが、Snapshotと一緒に保存されるのはKSPの変数だけです。

3：タイプ1と同じですが、Snapshotと一緒に保存されるのはKSPの変数だけです。

補足

  • このコマンドはグローバルに作用します。つまり、どのスクリプトスロットでも適用できます。

  • Snapshotのタイプ1と3では、persistentおよびinstrument persistentな変数の値が保持されます。

  • Snapshotをロードすると、常にKontaktのオーディオエンジンがリセットされます。つまり、オーディオが停止し、アクティブなイベントがすべて削除されます。

例

on init
    set_snapshot_type(1)

    declare ui_knob $knob_1 (0, 127, 1)
    set_text($knob_1, "Knob")
    make_persistent($knob_1)

    declare ui_button $gui_btn
    set_text($gui_btn, "Page 1")
end on

function show_gui()
    if ($gui_btn = 1)
        set_control_par(get_ui_id($knob_1), $CONTROL_PAR_HIDE, $HIDE_PART_NOTHING)
    else
        set_control_par(get_ui_id($knob_1), $CONTROL_PAR_HIDE, $HIDE_WHOLE_CONTROL)
    end if
end function

on persistence_changed
    call show_gui()
end on

on ui_control ($gui_btn)
    call show_gui()
end on

Snapshotのロード時にGUIを維持します。

関連項目

on init

on persistence_changed

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