KSPリファレンスマニュアル 15 - MIDIオブジェクトコマンド（MIDI Object Commands）

一般情報

1つのNKIの中で同時に使用できるMIDIオブジェクトは1つだけです。MIDIオブジェクトはメモリー上に保持され、どのスクリプトスロットからでもアクセスできます。オブジェクトの中のMIDIイベントは追加・削除・編集ができ、MIDIファイルのインポートとエクスポートも行えます。

Multi ScriptもMIDIオブジェクトを1つ保持でき、NKIと同じ方法で扱います。

Kontaktのバージョン5.2で、MIDIファイルの扱いが大きく更新されている点にご注意ください。5.2リリース以前のコマンドや作業方法も下位互換性を保つために残されていますが、このリファレンスでは5.2以降の作業方法を記載します。

MIDIファイルの作成、インポート、エクスポート

Instrumentを初期化すると、空のMIDIオブジェクトも一緒に初期化されます。オブジェクトの編集を始めるには、バッファサイズを定義してイベントを挿入するか、MIDIファイル全体を挿入します。

MIDIシーケンスをゼロから作成したい場合は、まずバッファサイズを割り当てる必要があります。これにより、指定した数の非アクティブなMIDIイベントが実質的に作成されます。ここから先は、MIDIイベントコマンドを使ってMIDIイベントをアクティブに、つまり挿入し、編集できます。

スクリプトの中でデータを使ったり編集したりするために、MIDIファイルを読み込むこともできます。使用するコマンドと変数によって、読み込んだデータは既存のMIDIデータと結合されるか、既存のデータを置き換えます。MIDIファイルの読み込みは非同期コマンドであり、非同期の読み込みに共通するコマンドと作業方法が当てはまる点に注意してください。

MIDIオブジェクトは、save_midi_file()コマンドを使うか、ドラッグアンドドロップを有効にしたlabelウィジェット経由で、Kontaktから書き出せます。どちらの場合も、mf_set_export_area()コマンドを使って、開始時刻と終了時刻、および開始トラックと終了トラックの両面から、エクスポートエリアを定義できます。

エクスポートエリアは最大512個まで定義でき、それぞれが異なる時間範囲とトラック範囲を指すことができます。ここでの手順は、まずmf_set_num_export_areas()でエクスポートエリアの数を設定し、次に同じ数のui_labelウィジェットを作成して、$CONTROL_PAR_MIDI_EXPORT_AREA_IDXコントロールパラメーターを使って個々のエクスポートエリアのインデックスに割り当てる、というものです。そこから先は、エクスポートエリア0を「編集バッファ」とみなし、そこから関心のあるさまざまな時間／トラックの選択範囲を、mf_copy_export_area()コマンドを使って他のエクスポートエリアにコピーします。

ナビゲーションと編集

KontaktのMIDIオブジェクトの中のMIDIイベントにはイベントパラメーターが与えられており、mf_get_event_par()またはmf_set_event_par()コマンドを使ってアクセスします。特定のイベントにアクセスするには固有のイベントIDを使うか、位置によってイベントをたどることができます。イベントIDは、MIDIイベントが作成または読み込まれるたびに割り当てられます。

読み込んだMIDIファイルのイベントデータにアクセスするには、再生ヘッドに相当するポジションマーカーでMIDIイベントの間を移動します。ポジションマーカーは一度に1つのイベントだけに焦点を合わせ、さまざまなコマンドを使ってそのイベントのパラメーターにアクセスしたり編集したりできるようにします。1つのイベントから次のイベントへ順に移動することも、MIDIティックで正確な位置を指定することもできます。

MIDIのNote Offメッセージは使用されない点に注意してください。mf_insert_file()コマンドでMIDIファイルを読み込むと、Note Offイベントは対応するNote Onイベントに長さのパラメーターを与えるために使われ、その後は破棄されます。

by_marks()

`by_marks(<mark>)`
MIDIオブジェクトのイベントのうち、ユーザーが定義したグループにアクセスするために使用します。
`<mark>`	イベントマーク番号。`$MARK_1 ... $MARK_10` のいずれかです。

by_track()

`by_track(<track>)`
トラック番号でグループ化されたイベントにアクセスするために使用します。
`<track>`	アクセスしたいイベントのトラック番号。

補足

機能はby_marks()コマンドと同様です。

mf_copy_export_area()

`mf_copy_export_area(<index>)`
MIDIエクスポートエリア0の内容を、指定した`<index>`のエクスポートエリアにコピーします。

例

on init
    message("")
    make_perfview

    declare const $DND_AREAS := 4

    declare ui_label $label1 (1,1)
    declare ui_label $label2 (1,1)
    declare ui_label $label3 (1,1)
    declare ui_label $label4 (1,1)

    declare $i
    declare %ID[$DND_AREAS]
    %ID[0] := get_ui_id($label1)
    %ID[1] := get_ui_id($label2)
    %ID[2] := get_ui_id($label3)
    %ID[3] := get_ui_id($label4)
    declare !track_names[$DND_AREAS]
    !track_names[0] := "Synth 1"
    !track_names[1] := "Synth 2"
    !track_names[2] := "Bass"
    !track_names[3] := "Melody"

    mf_insert_file(get_folder($GET_FOLDER_PATCH_DIR) & "my_midi.mid", 0, 0, 0)
    mf_set_num_export_areas($DND_AREAS + 1)

    $i := 0
    while ($i < $DND_AREAS)
        set_control_par(%ID[$i], $CONTROL_PAR_DND_BEHAVIOUR, 1)
        set_control_par(%ID[$i], $CONTROL_PAR_MIDI_EXPORT_AREA_IDX, $i + 1)
        set_control_par_str(%ID[$i], $CONTROL_PAR_TEXT, !track_names[$i])

        mf_set_export_area(!track_names[$i], -1, -1, $i, $i)
        mf_copy_export_area($i + 1)

        inc($i)
    end while
end on

MIDIファイルを読み込み、最初の4つのMIDIチャンネルにある内容を4つの個別のMIDIエリアに振り分けます。

mf_get_buffer_size()

`mf_get_buffer_size()`
MIDIオブジェクトのイベントバッファのサイズを返します。

補足

バッファサイズの最大値は、アクティブなイベントと非アクティブなイベントを合わせて1000000イベントです。
MIDIイベントを挿入するとバッファサイズが1つ減ります。イベントを削除すると1つ増えます。

mf_get_event_par()

`mf_get_event_par(<event-id>, <parameter>)`
イベントパラメーターの値を返します。
`<event-id>`	編集するイベントのID。
`<parameter>`	イベントパラメーター。自由に割り当てられる4つのイベントパラメーターのいずれか: `$EVENT_PAR_0` `$EVENT_PAR_1` `$EVENT_PAR_2` `$EVENT_PAR_3` またはイベントのビルトインパラメーター: `$EVENT_PAR_MIDI_CHANNEL` `$EVENT_PAR_MIDI_COMMAND` `$EVENT_PAR_MIDI_BYTE_1` `$EVENT_PAR_MIDI_BYTE_2` `$EVENT_PAR_POS` `$EVENT_PAR_NOTE_LENGTH` `$EVENT_PAR_ID` `$EVENT_PAR_TRACK_NR`

mf_get_event_par(<event-id>, <parameter>)

イベントパラメーターの値を返します。

<event-id>

編集するイベントのID。

<parameter>

イベントパラメーター。自由に割り当てられる4つのイベントパラメーターのいずれか:

$EVENT_PAR_0

$EVENT_PAR_1

$EVENT_PAR_2

$EVENT_PAR_3

またはイベントのビルトインパラメーター:

$EVENT_PAR_MIDI_CHANNEL

$EVENT_PAR_MIDI_COMMAND

$EVENT_PAR_MIDI_BYTE_1

$EVENT_PAR_MIDI_BYTE_2

$EVENT_PAR_POS

$EVENT_PAR_NOTE_LENGTH

$EVENT_PAR_ID

$EVENT_PAR_TRACK_NR

補足

イベントIDとして$ALL_EVENTS定数を使うと、MIDIオブジェクト内のすべてのイベントにアクセスできます。
$CURRENT_EVENT定数を使うと、現在選択されているイベントにアクセスできます。
by_track()とby_marks()コマンドを使って、トラックごとにイベントにアクセスしたり、イベントマークでグループ化したりすることもできます。

mf_get_first()

`mf_get_first(<track-index>)`
ポジションマーカーをMIDIトラックの最初のイベントに移動します。
`<track-index>`	編集したいトラックの番号。-1 はファイル全体を指します。

補足

このコマンドを使うと、ポジションマーカーの位置にあるイベントが編集対象として選択されます。

mf_get_id()

`mf_get_id()`
`mf_get_first()`や`mf_get_next()`などのナビゲーションコマンドを使っているときに、現在選択されているイベントのIDを返します。

`mf_get_last(<track-index>)`
ポジションマーカーをMIDIトラックの最後のイベントに移動します。
`<track-index>`	編集したいトラックの番号。-1 はファイル全体を指します。

補足

このコマンドを使うと、ポジションマーカーの位置にあるイベントが編集対象として選択されます。

mf_get_last_filename()

`mf_get_last_filename()`
`mf_insert_file()`または`ui_mouse_area`でのドラッグアンドドロップ操作によって、最後にKontaktに挿入されたMIDIファイルのファイル名（フルパスではありません）を返します。

補足

このコマンドは、Note OnイベントとNote Offイベントを組み合わせて、Note Lengthパラメーターを持つ1つのNote Onにまとめます。Note Offイベントは破棄されます。

例

on init
    message("")
    make_perfview

    declare const $DND_AREAS := 4

    declare ui_label $label1 (1,1)
    declare ui_label $label2 (1,1)
    declare ui_label $label3 (1,1)
    declare ui_label $label4 (1,1)

    declare $i
    declare %ID[$DND_AREAS]
    %ID[0] := get_ui_id($label1)
    %ID[1] := get_ui_id($label2)
    %ID[2] := get_ui_id($label3)
    %ID[3] := get_ui_id($label4)
    declare !track_names[$DND_AREAS]
    !track_names[0] := "Synth 1"
    !track_names[1] := "Synth 2"
    !track_names[2] := "Bass"
    !track_names[3] := "Melody"

    mf_insert_file(get_folder($GET_FOLDER_PATCH_DIR) & "my_midi.mid", 0, 0, 0)
    { declare export areas, area 0 serves as an edit buffer, so add one extra }
    mf_set_num_export_areas($DND_AREAS + 1)

    $i := 0
    while ($i < $DND_AREAS)
        set_control_par(%ID[$i], $CONTROL_PAR_DND_BEHAVIOUR, 1)
        set_control_par(%ID[$i], $CONTROL_PAR_MIDI_EXPORT_AREA_IDX, $i + 1)
        set_control_par_str(%ID[$i], $CONTROL_PAR_TEXT, mf_get_last_filename & " " & !track_names[$i])

        mf_set_export_area(!track_names[$i], -1, -1, $i, $i)
        mf_copy_export_area($i + 1)

        inc($i)
    end while
end on

最初の4トラックを個別のMIDIファイルとして書き出せるMIDIファイルローダーです。mf_get_last_filename()を使って、読み込まれたMIDIファイルの正確な名前を表示します。

mf_get_mark()

`mf_get_mark(<event-id>, <mark>)`
イベントにマークが付いているかどうかを調べます。付いていれば1を、付いていなければ0を返します。
<`event-id>`	編集するイベントのID
`<mark>`	イベントマーク番号。`$MARK_1 ... $MARK_10` のいずれかです。1つのイベントに複数のマークを割り当てることもできます。その場合は、コマンドをもう一度書くか、ビット演算子`.or.`を使うか、単にイベントマークを合計します。

mf_get_next()

`mf_get_next(<track-index>)`
ポジションマーカーをMIDIトラックの次のイベントに移動します。
`<track-index>`	編集したいトラックの番号。-1 はファイル全体を指します。

補足

このコマンドを使うと、ポジションマーカーの位置にあるイベントが編集対象として選択されます。

mf_get_next_at()

`mf_get_next_at(<track-index>, <pos>)`
ポジションマーカーを、指定した位置の直後にあるMIDIトラックの次のイベントに移動します。
`<track-index>`	編集したいトラックの番号。-1 はファイル全体を指します。
`<pos>`	MIDIティックでの位置。

補足

このコマンドを使うと、ポジションマーカーの位置にあるイベントが編集対象として選択されます。

mf_get_num_tracks()

`mf_get_num_tracks()`
MIDIオブジェクト内のトラック数を返します。

mf_get_prev()

`mf_get_prev(<track-index>)`
ポジションマーカーをMIDIトラックの直前のイベントに移動します。
`<track-index>`	編集したいトラックの番号。-1 はファイル全体を指します。

補足

このコマンドを使うと、ポジションマーカーの位置にあるイベントが編集対象として選択されます。

mf_get_prev_at()

`mf_get_prev_at(<track-index>, <pos>)`
ポジションマーカーを、指定した位置より前にある最初のイベントに移動します。
`<track-index>`	編集したいトラックの番号。-1 はファイル全体を指します。
`<pos>`	MIDIティックでの位置。

補足

このコマンドを使うと、ポジションマーカーの位置にあるイベントが編集対象として選択されます。

mf_insert_event()

`mf_insert_event(<track>, <pos>, <command>, <byte1>, <byte2>)`
MIDIオブジェクト内の非アクティブなMIDIイベントをアクティブにします。ただし、コマンドと位置をこのコマンドの中で定義するため、実質的には挿入とみなせます。
`<track>`	イベントの挿入先となるトラック。
`<pos>`	イベントが挿入される位置。単位はティックです。
`<command>`	イベントのコマンドタイプを定義します。次のいずれかを指定できます: `$MIDI_COMMAND_NOTE_ON` `$MIDI_COMMAND_POLY_AT` `$MIDI_COMMAND_CC` `$MIDI_COMMAND_PROGRAM_CHANGE` `$MIDI_COMMAND_MONO_AT` `$MIDI_COMMAND_PITCH_BEND`
`<byte1>`	コマンドの1バイト目。
`<byte2>`	コマンドの2バイト目。

補足

mf_set_buffer_size()コマンドでイベントバッファサイズを先に設定しなければ、MIDIイベントを挿入することはできません。
バッファがいっぱいのとき、つまりサイズが0のときにこのコマンドを使っても、何も起こりません。
次のように書くと、挿入したイベントのイベントIDを変数に取得できます:
<variable> := mf_insert_event(<track>, <pos>, <command>, <byte1>, <byte2>)

mf_insert_file()

`mf_insert_file(<path>, <track-offset>, <position-offset>, <mode>)`
MIDIファイルをオブジェクトに挿入します。
`<path>`	ファイル名を含む、MIDIファイルの絶対パス。
`<track-offset>`	MIDIデータにトラックオフセットを適用します。
`<position-offset>`	MIDIデータに、ティック単位の位置オフセットを適用します。
`<mode>`	挿入のモードを定義します: 0: 既存のイベントをすべて置き換える 1: 重なっているイベントのみを置き換える 2: すべてのイベントをマージする

補足

このコマンドはon initコールバックでは同期的に、それ以外のすべてのコールバックでは非同期的に実行されます。そのため、読み込みの状態を確認するにはon async_completeコールバックを使うことをおすすめします。
このコマンドは、Note OnイベントとNote Offイベントを組み合わせて、長さのパラメーターを持つ1つのNote Onにまとめます。Note Offイベントは破棄されます。
Kontaktで絶対ファイルパスを扱うときは、必ずスラッシュ（/）を使ってください!

例

on init
    declare $load_mf_id := -1
    declare @file_name
    declare @filepath

    @file_name := "test.mid"
    @filepath := get_folder($GET_FOLDER_FACTORY_DIR) & @file_name

    declare ui_button $load_file
end on

on ui_control($load_file)
    $load_mf_id := mf_insert_file(@filepath, 0, 0, 0)
end on

on async_complete
    if ($NI_ASYNC_ID = $load_mf_id)
        $load_mf_id := -1

        if ($NI_ASYNC_EXIT_STATUS = 0)
            message("ERROR: MIDI file not found!")
        else
            message("Loaded MIDI file: " & @file_name & "!")
        end if
    end if
end on

ボタンでMIDIファイルを読み込む例です。これを動作させるには、「test.mid」という名前のMIDIファイルをKontaktのファクトリーデータフォルダーに置く必要があります。そうでない場合は、定義したエラーメッセージが表示されます。

mf_remove_event()

`mf_remove_event(<event-id>)`
MIDIオブジェクト内のイベントを非アクティブにし、実質的に削除します。
`<event-id>`	非アクティブにするイベントのID。

補足

このコマンドを使うと、MIDIイベントバッファのサイズが1つ減ります。

mf_reset()

`mf_reset()`
MIDIオブジェクトをリセットし、イベントバッファを0にして、すべてのイベントを削除します。

補足

このコマンドはMIDIオブジェクト内のすべてのデータを消去します。使用には注意してください!
このコマンドは非同期であるため、非同期IDを返し、on async_completeコールバックを呼び出します。

mf_set_buffer_size()

`mf_set_buffer_size(<num-events>)`
アクティブにして編集できる、非アクティブなMIDIイベントの数を定義します。
`<num-events>`	MIDIオブジェクトの編集バッファのサイズ。

補足

mf_insert_event()とmf_remove_event()は、技術的にはバッファ内のイベントをアクティブまたは非アクティブにするものです。
バッファサイズを先に設定しなければ、MIDIイベントを挿入することはできません。
バッファサイズの最大値は、アクティブなイベントと非アクティブなイベントを合わせて1000000イベントです。
このコマンドはon initコールバックでは同期的に、それ以外のすべてのコールバックでは非同期的に実行されます。そのため、読み込みの状態を確認するにはon async_completeコールバックを使うことをおすすめします。
MIDIイベントを挿入するとバッファサイズが1つ減ります。イベントを削除すると1つ増えます。
MIDIファイルを挿入してもバッファには影響しません。

mf_set_event_par()

`mf_set_event_par(<event-id>, <parameter>, <value>)`
イベントパラメーターを設定します。
`<event-id>`	編集するイベントのID。
`<parameter>`	イベントパラメーター。自由に割り当てられる4つのイベントパラメーターのいずれか: `$EVENT_PAR_0` `$EVENT_PAR_1` `$EVENT_PAR_2` `$EVENT_PAR_3` またはイベントのビルトインパラメーター: `$EVENT_PAR_MIDI_CHANNEL` `$EVENT_PAR_MIDI_COMMAND` `$EVENT_PAR_MIDI_BYTE_1` `$EVENT_PAR_MIDI_BYTE_2` `$EVENT_PAR_POS` `$EVENT_PAR_NOTE_LENGTH` `$EVENT_PAR_ID` `$EVENT_PAR_TRACK_NR`
`<value>`	イベントパラメーターの値。

補足

イベントIDとして$ALL_EVENTS定数を使うと、MIDIオブジェクト内のすべてのイベントを制御できます。
$CURRENT_EVENT定数を使うと、現在選択されているイベントにアクセスできます。
by_track()とby_marks()コマンドを使って、トラックごとにイベントを制御したり、イベントマークでグループ化したりすることもできます。

mf_set_export_area()

`mf_set_export_area(<name>, <start-pos>, <end-pos>, <start-track>, <end-track>)`
ドラッグアンドドロップエリアを使うとき、または`save_midi_file()`コマンドを使うときに書き出される、オブジェクトの範囲を定義します。
`<name>`	書き出されるファイルの名前を設定します。
`<start-pos>`	エクスポートエリアの開始位置（ティック単位）を定義します。オブジェクトの先頭に設定するには -1 を使います。
`<end-pos>`	エクスポートエリアの終了位置（ティック単位）を定義します。オブジェクトの末尾に設定するには -1 を使います。
`<start-track>`	エクスポートエリアに含める最初のトラックを定義します。オブジェクトの最初のトラックに設定するには -1 を使います。
`<end-track>`	エクスポートエリアに含める最後のトラックを定義します。オブジェクトの最後のトラックに設定するには -1 を使います。

補足

開始点に終了点より大きい値を指定した場合、値は入れ替えられます。
このコマンドを実行すると、範囲内のイベントが有効なMIDIコマンドかどうかがチェックされます。すべてのイベントが有効であればこのコマンドは0を返し、そうでなければ最初の無効なイベントのイベントIDを返します。

例

on init
    declare $area_status
    declare @filepath
    @filepath := get_folder($GET_FOLDER_FACTORY_DIR) & "test.mid"

    declare ui_button $CheckMIDI

    mf_insert_file(@filepath, 0, 0, 0)
end on

on ui_control($CheckMIDI)
    $area_status := mf_set_export_area(“name”, -1, -1,-1,-1)

    if ($area_status = 0)
        message(“All Good”)
    else
        message(“Error: Check event with ID ” & $area_status & "!")
    end if

    $CheckMIDI := 0
end on

このコマンドを使って、MIDIファイル内のすべてのイベントが有効かどうかをチェックする簡単なスクリプトです。エラーがある場合は、最初の無効なイベントのイベントIDを表示します。これを動作させるには、「test.mid」という名前のMIDIファイルをKontaktのファクトリーデータフォルダーに置く必要があります。

mf_set_mark()

`mf_set_mark(<event-id>, <mark>, <status>)`
イベントにマークを付け、イベントをグループ化してそのグループをすばやく処理できるようにします。
`<event-id>`	マークを付けるイベントのID。
`<mark>`	イベントマーク番号。`$MARK_1 ... $MARK_10` のいずれかです。1つのイベントに複数のマークを割り当てることもできます。その場合は、コマンドをもう一度書くか、ビット演算子`.or.`を使うか、単にイベントマークを合計します。
`<status>`	イベントにマークを付けるには1を、マークを外すには0を設定します。

mf_set_num_export_areas()

`mf_set_num_export_areas(<num-areas>)`
エクスポートエリアの数を設定します。最大は512です。

補足

エリアインデックス0は常にmf_set_export_area()で設定します。
エリアインデックス0の内容は、mf_copy_export_area()を呼び出すことで他のエリアにコピーできます。

KSPリファレンスマニュアル 15 - MIDIオブジェクトコマンド（MIDI Object Commands）

KSPリファレンスマニュアル 15 - MIDIオブジェクトコマンド（MIDI Object Commands）

一般情報

MIDIファイルの作成、インポート、エクスポート

ナビゲーションと編集

by_marks()

関連項目

by_track()

補足

関連項目

mf_copy_export_area()

例

関連項目

mf_get_buffer_size()

補足

関連項目

mf_get_event_par()

補足

関連項目

mf_get_first()

補足

関連項目

mf_get_id()

関連項目

mf_get_last()

補足

関連項目

mf_get_last_filename()

補足

例

関連項目

mf_get_mark()

関連項目

mf_get_next()

補足

関連項目

mf_get_next_at()

補足

関連項目

mf_get_num_tracks()

関連項目

mf_get_prev()

補足

関連項目

mf_get_prev_at()

補足

関連項目

mf_insert_event()

補足

関連項目

mf_insert_file()

補足

例

関連項目

mf_remove_event()

補足

関連項目

mf_reset()

補足

関連項目

mf_set_buffer_size()

補足

関連項目

mf_set_event_par()

補足

関連項目

mf_set_export_area()

補足

例

関連項目

mf_set_mark()

関連項目

mf_set_num_export_areas()

補足

関連項目