by_marks()

補足

• by_marks()は、set_event_mark()で設定できる、ユーザーが定義したイベントのグループです。note_off()やchange_tune()のように、イベントIDを引数に取るすべてのコマンドで使用できます。

例

on note
    if ($EVENT_NOTE mod 12 = 0) { if played note is a C }
        set_event_mark($EVENT_ID, $MARK_1)
        change_tune(by_marks($MARK_1), %CC[1] * 1000, 0)
    end if
end on

on controller
    if ($CC_NUM = 1)
        change_tune(by_marks($MARK_1), %CC[1] * 1000, 0)
    end if
end on

モジュレーションホイールを動かすと、すべてのCのノート（C-2、C-1…C8）のチューニングが変わります。

関連項目

set_event_mark()

イベントとMIDI：$EVENT_ID、$ALL_EVENTS、$MARK_1 … $MARK_28

change_note()

補足

• change_note()はon noteコールバックの中でのみ使用でき、最初のwait()文より前でのみ動作します。ボイスがすでに鳴っている場合は、$EVENT_NOTE変数の値が変わるだけです。

• あるノートイベントのノートナンバーをいったん変更すると、それが新しい$EVENT_NOTEになります。

• $ALL_EVENTSのようなイベントグループを介してイベントを指定することはできません。

例

on init
    declare %black_keys[5] := (1, 3, 6, 8, 10)
end on

on note
    if (search(%black_keys, $EVENT_NOTE mod 12) # -1)
        change_note($EVENT_ID, $EVENT_NOTE - 1)
    end if
end on

すべてのノートを白鍵、つまりCメジャーに限定します。

関連項目

change_velo()

イベントとMIDI：$EVENT_NOTE

change_pan()

補足

• change_pan()はノートイベントのレベルで動作し、インストゥルメント自体のパノラマ設定を変更するものではありません。またパノラマに関するモジュレーションとも関係ありません。

例

on init
    declare $pan_position
end on

on note
    $pan_position := ($EVENT_NOTE * 2000 / 127) - 1000
    change_pan($EVENT_ID, $pan_position, 0)
end on

キーレンジ全体を左から右へパンニングします。つまりC-2が最も左、G8が最も右になります。

on note
    if ($EVENT_NOTE < 60)
        change_pan($EVENT_ID, 1000, 0)
        wait(500000)
        change_pan($EVENT_ID, -1000, 0) { absolute, pan is at -1000 }
    else
        change_pan($EVENT_ID, 1000, 1)
        wait(500000)
        change_pan($EVENT_ID, -1000, 1) { relative, pan is at 0 }
    end if
end on

C3より下のノートはrelative bitに0を、C3以上のノートは1を使います。

関連項目

change_vol()

change_tune()

change_tune()

補足

• change_tune()はノートイベントのレベルで動作し、インストゥルメント自体のチューニング設定を変更するものではありません。またチューニングに関するモジュレーションとも関係ありません。

例

on init
    declare $tune_amount
end on

on note
    $tune_amount := random(-50000, 50000)
    change_tune($EVENT_ID, $tune_amount, 1)
end on

演奏されたすべてのノートを±50セントの範囲でランダムにデチューンします。

関連項目

change_vol()

change_pan()

change_velo()

補足

• change_velo()はon noteコールバックの中でのみ使用でき、最初のwait()文より前でのみ動作します。ボイスがすでに鳴っている場合は、変数の値が変わるだけです。

• あるノートイベントのベロシティをいったん変更すると、それが新しい$EVENT_VELOCITYになります。

• $ALL_EVENTSのようなイベントグループを介してイベントを指定することはできません。

例

on note
    change_velo($EVENT_ID, 100)
    message($EVENT_VELOCITY)
end on

すべてのベロシティが100に設定されます。$EVENT_VELOCITYも100に変わる点に注意してください。

関連項目

change_note()

イベントとMIDI：$EVENT_VELOCITY

change_vol()

補足

• change_vol()はノートイベントのレベルで動作し、インストゥルメント自体のチューニング設定を変更するものではありません。またボリュームに関するMIDIのモジュレーション（例：MIDI CC #7）とも関係ありません。

例

on init
    declare $vol_amount
end on

on note
    $vol_amount := (($EVENT_VELOCITY - 1) * 12000 / 126) - 6000
    change_vol ($EVENT_ID, $vol_amount, 1)
end on

単純なダイナミックエキスパンダーです。弱く弾いたノートはより小さく、強く弾いたノートはより大きくなります。

関連項目

change_tune()

change_pan()

fade_in()

fade_out()

delete_event_mark()

関連項目

set_event_mark()

by_marks()

イベントとMIDI：$EVENT_ID、$ALL_EVENTS、$MARK_1 … $MARK_28

event_status()

補足

• event_status()を使うと、ノートイベントがまだ"生きている"かどうかを調べられます。

例

on init
    declare %key_id[128]
end on

on note
    if (event_status(%key_id[$EVENT_NOTE]) = $EVENT_STATUS_NOTE_QUEUE)
        fade_out(%key_id[$EVENT_NOTE], 10000, 1)
    end if

    %key_id[$EVENT_NOTE] := $EVENT_ID
end on

アクティブなノートイベントの数をMIDIキーごとに1つへ制限します。

関連項目

get_event_ids()

イベントとMIDI：$EVENT_STATUS_INACTIVE、$EVENT_STATUS_NOTE_QUEUE、$EVENT_STATUS_MIDI_QUEUE

fade_in()

補足

• フェードアウトはフェードインのカーブを時間軸で反転した形をたどります。そのため、同じ<curve>を指定した2つのイベントにfade_outとfade_inを組み合わせて使うと、きれいにそろったクロスフェードになります。

• 各フェード形状の使い分けは次のとおりです。

  定数	形状の関数	推奨される用途と特性
  $NI_FADE_LINEAR	t	相関のある素材（同じサンプルで位置やピッチだけが違うもの）のクロスフェード向け。振幅を保ちます。
  $NI_FADE_EQUAL_POWER	sin(πt/2)	相関のない素材（例：リリースサンプルへのフェード）のクロスフェード向け。パワーを保ち、音量の落ち込みを避けます。
  $NI_FADE_S_CURVE	½(1 − cos πt)	なめらかで音楽的なフェード向け。ゆっくり始まり、中盤で急になり、ゆっくり終わります。
  $NI_FADE_EXPONENTIAL	t²	穏やかに始まり、急激に終わります。
  $NI_FADE_LOGARITHMIC	1 − (1 − t)²	急激に始まり、穏やかに終わります。

例

on init
    declare $note_1_id
    declare $note_2_id
end on

on note
    $note_1_id := play_note($EVENT_NOTE + 12, $EVENT_VELOCITY, 0, -1)
    $note_2_id := play_note($EVENT_NOTE + 19, $EVENT_VELOCITY, 0, -1)		

    fade_in ($note_1_id, 1000000)
    fade_in ($note_2_id, 5000000)
end on

最初の2つの倍音をフェードインさせます。

on note    
    $old_id := %held[$EVENT_NOTE]
    if ($old_id # 0)
        fade_out($old_id, 100000, 1, $NI_FADE_EQUAL_POWER)
    end if
    $new_id := play_note($EVENT_NOTE, $EVENT_VELOCITY, 0, -1)
    fade_in($new_id, 100000, $NI_FADE_EQUAL_POWER)
    %held[$EVENT_NOTE] := $new_id
end on

古いボイスをフェードアウトさせながら新しいボイスをフェードインさせます。equal powerを使うと、ブレンドの間も体感上の音量が一定に保たれます。

関連項目

change_vol()

fade_out()

イベントとMIDI：$NI_FADE_LINEAR、$NI_FADE_EQUAL_POWER、$NI_FADE_S_CURVE、$NI_FADE_EXPONENTIAL、$NI_FADE_LOGARITHMIC

fade_out()

例

on controller
    if ($CC_NUM = 1)
        if (%CC[1] mod 2 # 0)
            fade_out($ALL_EVENTS, 5000, 0)
        else
            fade_in($ALL_EVENTS, 5000)
        end if
    end if
end on

押さえたノートに対してモジュレーションホイールを使い、スタッター効果を作ります。

on controller
    if ($CC_NUM = 1)
        fade_out($ALL_EVENTS, 5000, 1)
    end if
end on

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

関連項目

change_vol()

fade_in()

イベントとMIDI：$NI_FADE_LINEAR、$NI_FADE_EQUAL_POWER、$NI_FADE_S_CURVE、$NI_FADE_EXPONENTIAL、$NI_FADE_LOGARITHMIC

get_event_ids()

補足

• このコマンドは、アクティブなイベントがある限り既存の値をすべて上書きし、アクティブなイベントがもう無ければ0を書き込みます。アクティブなイベントの数が配列のインデックス数より多い場合、配列は満杯になるまで埋められ、残りのイベントIDは無視されます。

• アクティブなイベントの数が配列のインデックス数より少ない場合、配列は先頭からすべてのイベントIDで埋められ、その次のインデックスに0が設定されます。

例

on init
    declare const $ARRAY_SIZE := 500

    declare $a
    declare $note_count
    declare %test_array[$ARRAY_SIZE]
end on

on note
    get_event_ids(%test_array)

    $note_count := 0
    $a := 0
    while($a < $ARRAY_SIZE and %test_array[$a] # 0)
        inc($note_count)
        inc($a)
    end while

    message("Active Events: " & $note_count)
end on

アクティブなイベントの数をモニタリングします。

関連項目

event_status()

get_event_mark()

例

on note
    if ($EVENT_NOTE mod 12 = 0)
        set_event_mark($EVENT_ID, $MARK_1)
    end if
end on

on release
    if (get_event_mark($EVENT_ID, $MARK_1) = 1)
        message("You've played a C!")
    else
        message("")
    end if
end on

Cのキーを離したかどうかを調べる、かなり回りくどいやり方です。

関連項目

set_event_mark()

get_event_par()

補足

• ノートイベントは常に、ノートナンバーや演奏されたベロシティだけでなく、ボリューム・パン・チューニングといった情報も保持しています。get_event_par()を使うと、これらのパラメーターを取得したり、$EVENT_PAR_0のような自由に割り当てられるパラメーターを利用したりできます。これはスクリプトを連鎖させるときに特に便利です。つまり、スクリプトスロット1でイベントにイベントパラメーターを設定しておき、スクリプトスロット2でget_event_par()を使ってその情報を取り出す、といった使い方ができます。

例

on note 
    message(get_event_par($EVENT_ID, $EVENT_PAR_NOTE))
end on

message($EVENT_NOTE)と同じ動作です。

on note
    message(get_event_par($EVENT_ID, $EVENT_PAR_SOURCE))
end on

イベントが外部から来たものか（この場合は-1を返します）、5つのスクリプトスロットのいずれかで生成されたものか（0-4を返します）を調べます。

on note
    wait(1)
    message(get_event_par($EVENT_ID, $EVENT_PAR_ZONE_ID))
end on

イベント自体はZone IDを持たないため（Zone IDを持てるのはボイスだけです）、Zone IDを正しく取得するにはwait(1)を挟む必要があります。

関連項目

set_event_par()

ignore_event()

set_event_par_arr()

get_event_par_arr()

???

get_event_par_arr()

補足

• get_event_par_arr()はget_event_par()の配列版です。特定のイベントのグループ許可状態を取得したいときや、標準の4つのイベントパラメーターより多くを扱いたいときに使います。また、Kontaktの"from script"モジュレーターによるイベント単位のモジュレーションの値を取得する用途にも使えます。

例

on init
    declare $count
    declare ui_label $label (2, 4)
    set_text($label, "")
end on

on note
    set_text($label, "")

    $count := 0
    while ($count < $NUM_GROUPS)
        if (get_event_par_arr($EVENT_ID, $EVENT_PAR_ALLOW_GROUP, $count) = 1)
            add_text_line($label,"Group ID " & $count & " allowed")
        else
            add_text_line($label,"Group ID " & $count & " disallowed")
        end if

        inc($count)
    end while
end on

シンプルなグループモニターです。

関連項目

set_event_par_arr()

get_event_par()

イベントとMIDI：$EVENT_PAR_ALLOW_GROUP、$EVENT_PAR_MOD_VALUE_ID、$EVENT_PAR_CUSTOM 、%GROUPS_AFFECTED

ignore_event()

補足

• イベントを無視すると、ボリューム・チューニング・パンの情報は失われます。ただしget_event_par()でその情報を取得できます。下の2つの例を参照してください。

• ignore_event()は非常に"強い"コマンドです。イベントを無視せずに、各種のchange_...()コマンドで同じ結果が得られないか、必ず確認してください。

例

on note
    ignore_event($EVENT_ID)
    wait(500000)
    play_note($EVENT_NOTE, $EVENT_VELOCITY, 0, -1)
end on

すべてのノートを0.5秒遅らせます。悪くありませんが、たとえばこのスクリプトの前にマイクロチューナーを挿しても、チューニング情報は失われてしまいます。

on init
    declare $new_id
end on

on note
    ignore_event($EVENT_ID)
    wait(500000)
    $new_id := play_note($EVENT_NOTE, $EVENT_VELOCITY, 0, -1)

    change_vol($new_id, get_event_par($EVENT_ID, $EVENT_PAR_VOLUME), 1)
    change_tune($new_id, get_event_par($EVENT_ID, $EVENT_PAR_TUNE), 1)
    change_pan($new_id, get_event_par($EVENT_ID, $EVENT_PAR_PAN), 1)
end on

こちらのほうが良い方法です。チューニング（正確にはボリュームとパンも）の情報が取得され、演奏されるノートに適用されます。

関連項目

ignore_controller

get_event_par()

redirect_­output(­)

補足

• redirect_output()を使うと、グループの出力設定は完全に無視されます。

例

on init
    declare $new_id_0
    declare $new_id_1
    decalre $new_id_2
end on

on note
    ignore_event($EVENT_ID)

    $new_id_0 := play_note($EVENT_NOTE, $EVENT_VELOCITY, 0, -1)
    $new_id_1 := play_note($EVENT_NOTE + 4, $EVENT_VELOCITY, 0, -1)
    $new_id_2 := play_note($EVENT_NOTE + 7, $EVENT_VELOCITY, 0, -1)

    redirect_output($new_id_0, $OUTPUT_TYPE_BUS_OUT, 0)
    redirect_output($new_id_1, $OUTPUT_TYPE_BUS_OUT, 1)
    redirect_output($new_id_2, $OUTPUT_TYPE_BUS_OUT, 2)
end on

メジャートライアドを生成し、それぞれのノートを別々のinstrument busへルーティングします。

関連項目

get_event_par()

set_event_mark()

補足

• イベントIDを扱うコマンドを使うときは、個々のIDの代わりにby_marks()を使ってイベントをグループ化できます。IDではなくマークを指定したいことを、Kontaktに伝える必要があるためです。

例

on init
    declare $new_id
end on

on note
    set_event_mark($EVENT_ID, $MARK_1)

    $new_id := play_note($EVENT_NOTE + 12, 120, 0, -1)
    set_event_mark($new_id, $MARK_1 + $MARK_2)

    change_pan(by_marks($MARK_1), -1000, 1) { both notes panned to left }
    change_pan(by_marks($MARK_2), 2000, 1) { new note panned to right }
end on

演奏されたノートはイベントマーク1に、ハーモナイズされたノートはイベントマーク1と2の両方に属します。

関連項目

by_marks()

delete_event_mark()

イベントとMIDI：$EVENT_ID、$ALL_EVENTS、$MARK_1 … $MARK_28

set_event_par()

補足

• ノートイベントは常に、ノートナンバーや演奏されたベロシティだけでなく、ボリューム・パン・チューニングといった情報も保持しています。set_event_par()を使うと、これらのパラメーターを設定したり、$EVENT_PAR_0のような自由に割り当てられるパラメーターを利用したりできます。これはスクリプトを連鎖させるときに特に便利です。つまり、スクリプトスロット1でイベントにイベントパラメーターを設定しておき、スクリプトスロット2でget_event_par()を使ってその情報を取り出す、といった使い方ができます。

• 4つを超えるカスタムパラメーターが必要な場合は、set_event_par_arr()を$EVENT_PAR_CUSTOMと組み合わせて使ってください。

例

on note 
    set_event_par($EVENT_ID, $EVENT_PAR_NOTE, 60)
end on

すべてのノートを中央のC3に設定します。change_note($EVENT_ID, 60)と同じ動作です。

on init
    message("")
    declare ui_switch $switch

    declare ui_label $midiChan1 (1, 1)
    declare ui_label $midiChan2 (1, 1)
    declare ui_label $midiChan3 (1, 1)
    declare ui_label $midiChan4 (1, 1)
    declare ui_label $midiChan5 (1, 1)
    declare ui_label $midiChan6 (1, 1)
    declare ui_label $midiChan7 (1, 1)
    declare ui_label $midiChan8 (1, 1)
    declare ui_label $midiChan9 (1, 1)
    declare ui_label $midiChan10 (1, 1)
    declare ui_label $midiChan11 (1, 1)
    declare ui_label $midiChan12 (1, 1)
    declare ui_label $midiChan13 (1, 1)
    declare ui_label $midiChan14 (1, 1)
    declare ui_label $midiChan15 (1, 1)
    declare ui_label $midiChan16 (1, 1)

    declare %midiChans[16]
    %midiChans[0] := get_ui_id($midiChan1)
    %midiChans[1] := get_ui_id($midiChan2)
    %midiChans[2] := get_ui_id($midiChan3)
    %midiChans[3] := get_ui_id($midiChan4)
    %midiChans[4] := get_ui_id($midiChan5)
    %midiChans[5] := get_ui_id($midiChan6)
    %midiChans[6] := get_ui_id($midiChan7)
    %midiChans[7] := get_ui_id($midiChan8)
    %midiChans[8] := get_ui_id($midiChan9)
    %midiChans[9] := get_ui_id($midiChan10)
    %midiChans[10] := get_ui_id($midiChan11)
    %midiChans[11] := get_ui_id($midiChan12)
    %midiChans[12] := get_ui_id($midiChan13)
    %midiChans[13] := get_ui_id($midiChan14)
    %midiChans[14] := get_ui_id($midiChan15)
    %midiChans[15] := get_ui_id($midiChan16)
end on

on release
    if ($switch = 1)
        set_event_par($EVENT_ID, $EVENT_PAR_REL_VELOCITY, 127)
    end if

    set_control_par_str(%midiChans[$MIDI_CHANNEL], $CONTROL_PAR_TEXT, get_event_par($EVENT_ID, $EVENT_PAR_REL_VELOCITY))
end on

MPE（MIDI Polyphonic Expression）の文脈におけるリリースベロシティの例です。

関連項目

get_event_par()

ignore_event()

set_event_par_arr()

get_event_par_arr()

set_event_par_arr()

補足

• set_event_par_arr()はset_event_par()の配列版です。特定のイベントのグループ許可状態を設定したいときや、標準の4つのイベントパラメーターより多くを扱いたいときに使います。また、Kontaktの"from script"モジュレーターによるイベント単位のモジュレーションを設定する用途にも使えます。

例

on note
    if (get_event_par_arr($EVENT_ID, $EVENT_PAR_ALLOW_GROUP, 0) = 0)
        set_event_par_arr($EVENT_ID, $EVENT_PAR_ALLOW_GROUP, 1, 0)
    end if
end on

最初のグループが必ず鳴るようにします。

on init
    declare const $CUSTOM_EVENT_PAR_4 := 4
end on

on note
    set_event_par_arr($EVENT_ID, $EVENT_PAR_CUSTOM, $ENGINE_UPTIME, $CUSTOM_EVENT_PAR_4)
end on

on release
    message(get_event_par_arr($EVENT_ID, $EVENT_PAR_CUSTOM, $CUSTOM_EVENT_PAR_4))
end on

$EVENT_PAR_CUSTOMのシンプルな実装例です。

on note
    if ($EVENT_NOTE = 60)
        set_event_par_arr($EVENT_ID, $EVENT_PAR_MOD_VALUE_ID, 500000, 1)
    end if
end on

中央のC（MIDIノート60）だけにモジュレーションがかかります。IDを"1"に設定した"from script"モジュレーターによるものです。

関連項目

allow_group()

disallow_group()

get_event_par_arr()

set_event_par()

イベントとMIDI：$EVENT_PAR_ALLOW_GROUP

set_map_editor_event_color()

補足

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

• 指定した色は常に不透明度50%で描画されます。複数のスクリプトスロットから生成されたイベントが重なった場合でも見分けられるようにするためです。

• このコマンドは、スクリプトが生成したイベントをKontaktのMapping Editorに表示することが許可されている場合にのみ動作します（Mapping EditorのEditメニューにあるオプションです）。

例

on init
    set_map_editor_event_color(000FF00h)
end on

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

1オクターブ上のノートを追加で鳴らします。このイベントはKontaktのMapping Editorに緑色の点として表示されます。

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