pytakt.midiio module

このモジュールにはリアルタイムMIDI入出力、およびタイマのための関数が 定義されています。

デバイス

PytaktではMIDIメッセージの送信の対象となるもの（MIDIインタフェースや アプリケーションポート) を出力デバイス、受信の対象となるものを入力デバイス と呼んでいます。使用できるデバイスの一覧は show_devices() 関数で 確認できます。各デバイスには整数のデバイス番号が割り振られています。

特殊なデバイスとして、ループバックデバイスが用意されています (show_devices() では表示されません)。 ループバックデバイスは出力デバイスかつ入力デバイスであり、 送られたメッセージを自分自身で受け取ることができます。 通常はLoopBackEventの送受に利用されますが、 それ以外のイベントについて利用することも可能です。

デバイスを使用するには予めオープンする必要があります。 ただし、ループバックデバイスは常に使用可能で、オープンの必要はありません。

入力、出力デバイスのそれぞれに、現在選択されているデバイスが存在します。 これの初期値はプラットフォームごとに決まっています。ただし、 環境変数 PYTAKT_OUTPUT_DEVICE や PYTAKT_INPUT_DEVICE に find_output_device() や find_input_device() で認識できるような 文字列を設定することで、初期値を変えることができます。

入出力キュー

モジュール内部には、入力と出力のそれぞれに、メッセージ (イベントを Event.to_message() メソッドで変換したバイト列) を蓄えるためのキューが あります。各メッセージにはタイムスタンプとトラック番号が付与されています。 queue_event() 関数によってイベントを出力デバイスへ送ると、イベントは メッセージに変換されたのちにまず出力キューへ置かれ、送出時刻に なるまで待ってから実際にデバイスへ送出されます。入力デバイスからのメッセージ は入力キューにまず置かれ、recv_event() 関数によって取り出されるまで そこで保管されます。キューの容量制限は特にありません。

タイマ

モジュールには、モジュールをインポートしたときからの時間を表すタイマ が備わっています。時間の単位はティック (4分音符の480分の1に相当する 浮動小数点の値) で、秒とティックとの関係はテンポ (beat per minute, BPM) と テンポスケールという2つの値により下の式によって決定されます。

ticks = seconds * テンポ * テンポスケール / 60 * 480

初期状態ではテンポは125、テンポスケールは1に設定されており、 これにより 1 tick = 1 msec という関係が成り立っています。 テンポは TempoEvent を出力デバイスのどれかに送ることによって、 またテンポスケールは set_tempo_scale() 関数を呼ぶことによって、 動的に変更できます。

current_output_device() → int

現在選択されている出力デバイスの番号を返します。

current_input_device() → int

現在選択されている入力デバイスの番号を返します。

find_output_device(dev) → int

デバイスの記述をもとに、出力デバイス番号を取得します。

Parameters:

dev (int, str, list, tuple) – デバイスの記述。整数の場合は、それが そのままデバイス番号になります。整数を表す文字列の場合は、それが 整数に変換されてデバイス番号となります。それ以外の文字列の場合は、 デバイス名の全部または一部がそれと一致するデバイス(複数ある場合は デバイス番号の小さい方)を意味します。文字列はセミコロンで区切った 複数のデバイス記述でも良く、その場合最初に存在を確認できたものが 有効になります。リストまたはタプルの場合、各要素は整数または セミコロンを含まない文字列であり、先頭から順番に単独の場合と同じ ように調べられ、最初にデバイスの存在を確認できたものが有効になり ます。 存在を確認できるデバイスがなかった場合には、例外が送出されます。

Returns:

出力デバイス番号

Examples

  • find_output_device(1)

  • find_output_device('1')

  • find_output_device('TiMidity; MIDI Mapper')

  • find_output_device([2, 0])

output_devices() → List[str]

すべての出力デバイスの名前のリストを取得します。

set_output_device(dev) → None

dev を　“現在選択されている出力デバイス” として指定します。

Parameters:

dev – find_output_device() によって認識可能なデバイス記述。

open_output_device(dev=None) → None

出力デバイス dev をオープンします。

デバイスによっては少し時間がかかる場合があります。

Parameters:

dev – 対象となる出力デバイス。Noneの場合は現在選択されている 出力デバイス、それ以外の場合はこれを引数として find_output_device() を呼んだ結果が対象のデバイス となります。

close_output_device(dev=None) → None

出力デバイス dev をクローズします。

Parameters:

dev – 対象となる出力デバイス。Noneの場合は現在選択されている 出力デバイス、それ以外の場合はこれを引数として find_output_device() を呼んだ結果が対象のデバイス となります。

is_opened_output_device(dev) → bool

出力デバイス dev がオープンされていれば True、そうでなければ False を返します。

Parameters:

dev – find_output_device() によって認識可能なデバイス記述。

find_input_device(dev) → int

デバイスの記述をもとに、入力デバイス番号を取得します。

Parameters:

dev (int, str, list, tuple) – find_output_device() と同じ形式の デバイス記述。

input_devices() → List[str]

すべての入力デバイスの名前のリストを取得します。

set_input_device(dev) → None

dev を　“現在選択されている入力デバイス” として指定します。

Parameters:

dev – find_intput_device() によって認識可能なデバイス記述。

open_input_device(dev=None) → None

入力デバイス dev をオープンします。

入力デバイスはオープンしている期間のみ受信したメッセージを入力キューに 挿入し、クローズ中はメッセージを破棄します。入力キューに意図しない メッセージが溜まるのを避けるため、オープンは必要な期間のみに 限定する必要があります。

Parameters:

dev – 対象となる入力デバイス。Noneの場合は現在選択されている 入力デバイス、それ以外の場合はこれを引数として find_input_device() を呼んだ結果が対象のデバイス となります。

close_input_device(dev=None) → None

入力デバイス dev をクローズします。

Parameters:

dev – 対象となる入力デバイス。Noneの場合は現在選択されている 入力デバイス、それ以外の場合はこれを引数として find_input_device() を呼んだ結果が対象のデバイス となります。

is_opened_input_device(dev) → bool

入力デバイス dev がオープンされていれば True、そうでなければ False を返します。

Parameters:

dev – find_input_device() によって認識可能なデバイス記述。

show_devices() → None

利用可能なデバイスの一覧を表示します。

current_time() → float

現在の時刻を返します。

Returns:

モジュールがimportされた時を0としたティック単位の時刻。

current_tempo_scale() → float

現在のテンポスケールを返します。

Returns:

テンポスケール値

set_tempo_scale(tempo_scale) → None

テンポスケールを変更します。

Parameters:

tempo_scale (float) – テンポスケール値 (非負)

queue_event(ev, time=None, devnum=None) → None

イベントをメッセージ (バイト列) に変換した上で、そのメッセージを送出時刻と トラック番号とともに出力キューへ置きます。置かれたメッセージは その送出時刻に達すると出力デバイスへ送られます。 この関数でのブロック (出力待ち) はありません。

注意: テンポ変更のため TempoEvent をキューする場合は、送出時刻が現時刻 より過去であってはなりません。

Parameters:

  • ev (Event) – キューするイベント。これは、Event.to_message() メソッドによりメッセージに変換されて、出力キューに置かれます。 ev が NoteEvent の場合は、ノートオンとノートオフの2つの メッセージが置かれます（このとき、ノートオフの送出時刻は ノートオンの送出時刻に対して、ev がdu属性を持つならその値、 無ければL属性の値を加えたものとなります）。 この関数を呼び出した後にイベントを書き換えても キュー中のメッセージには影響を与えません。

  • time (ticks, optional) – メッセージ送出時刻(ティック単位)を 指定します。指定しない場合は、ev が持つt属性の値になります。

  • devnum (int, optional) – メッセージを送る出力デバイス番号を指定します。指定しない場合は、 現在選択されている出力デバイスとなります。 ev が LoopBackEvent であったときには、この値にかかわらず 必ずループバックデバイスへ送られます。

recv_ready() → bool

入力キューにメッセージがあれば True, そうでなければ False を返します。 この値が True であれば、次に recv_event() を呼んだときにブロック 状態にならないことが保証されます。

recv_event() → Optional[Event]

入力デバイスからのメッセージを受け取りイベントとして返します。 すべてのオープンされている入力デバイスが対象となります。 入力キューにメッセージが無いときはブロック(入力待ち)状態になります。 ブロックはメッセージが到着するか、キーボード・インタラプトを受けると 解除されます。

ループバックデバイスからのメッセージと通常の入力デバイスからのメッセージが ほぼ同時刻に到着した場合、その受け取り順序がイベントの時刻順にならないこと があります。

エクスクルーシブ・メッセージ以外のシステム・メッセージは無視され、 受け取ることができません。

Returns:

受け取ったメッセージを変換したイベント。そのt属性は メッセージを受け取った時刻になっています。キーボード・インタラプトを 受けたときは None を返します。

cancel_events(tk=-1, devnum=None) → None

指定されたデバイスの指定されたトラックに対して、以下の2つの 操作を行います。

  1. 出力キューに入っているメッセージをすべて削除します。

  2. 発音中のノートおよび使用中のサスティンペダルに対してそれらを オフにするメッセージを送ります。

Parameters:

  • tk (int, optional) – 対象となるトラック番号を指定します。-1 を指定すると、全ての トラックの意味になります。

  • devnum (int, optional) – 対象となる出力デバイス番号を指定します。指定しない場合は、 現在選択されている出力デバイスとなります。ループバックデバイスは 指定できません。

stop() → None

入出力キューに入っているすべてのメッセージを削除するとともに、 発音中のノートおよび使用中のサスティンペダルに対してそれらをオフにする メッセージを送ります。 さらに、下のMIDIメッセージをすべてのオープンされている出力デバイスの すべてのチャネルに送り、シンセサイザからの発音の完全停止を試みます。

  • オール・ノート・オフ (123番のコントロールチェンジ)

  • 値が0のサスティン・ペダル・コントロール (64番のコントロールチェンジ)

  • オール・サウンド・オフ (120番のコントロールチェンジ)

このモジュールをインポートした状態でキーボードインタラプトを受けた ときにはこの関数が自動的に呼ばれます。

play(score, dev=None, callback=None) → None

スコアを再生します。スコアに含まれるイベントに従って順にメッセージを出力 デバイスへ送ります。この関数は、スコアの演奏長に相当する時間が経過するか、 あるいはキーボード・インタラプトを受けるまでリターンしません。

Parameters:

  • score (Score or str) – 演奏対象のスコア。無限長スコアであっても 構いません。この引数が文字列の場合はMMLだと見なされます。

  • dev – 対象となる出力デバイス。Noneの場合は現在選択されている 出力デバイス、それ以外の場合はこれを引数として find_output_device() を呼んだ結果が対象のデバイス となります。 指定したデバイスがオープンされていないときは、自動的にオープン されます。

  • callback (function, optional) – 単一の引数を取る関数(コールバック関数)を指定すると、再生開始時に それが呼び出されます。引数にはループバックイベントが渡され、 そのイベントをコールバック関数内で時刻を更新して queue_event() で出力キューに挿入すれば、その時刻に再び コールバック関数が呼ばれるようにスケジュールすることができます。

record(indev=None, play=None, outdev=None, metro=None, monitor=False, callback=None) → EventList

入力デバイスからの演奏を録音してイベントリストを返します。 スコアを再生しながら録音することもできます。 この関数は、再生スコアの演奏長に相当する時間が経過するか、 あるいはキーボード・インタラプトを受けるまでリターンしません。

Parameters:

  • indev – 対象となる入力デバイス。Noneの場合は現在選択されている 入力デバイス、それ以外の場合はこれを引数として find_input_device() を呼んだ結果が対象のデバイス となります。指定したデバイスがオープンされていないときは、 自動的にオープンされます。また、関数から戻るときにはクローズ されます。 このデバイス以外の他の入力デバイスが既にオープンされていた場合 には、そのデバイスからのイベントも一緒に録音されます。

  • play (Score, optional) – 同時に再生するスコア。 無限長スコアであっても構いません。

  • outdev – 再生するときの出力デバイス。Noneの場合は現在選択されている 出力デバイス、それ以外の場合はこれを引数として find_output_device() を呼んだ結果が対象のデバイス となります。 指定したデバイスがオープンされていないときは、自動的にオープン されます。

  • metro (str, bool or Score, optional) – 指定するとメトロノームを鳴らします。標準のメトロノームは、 MIDIチャンネル10がGM規格のリズム音源であることを仮定しています。 この引数には、”3/4” のような拍子を表す文字列を指定するか、 True (“4/4”と同じ意味) を指定するか、あるいはメトロノームを 鳴らすためのスコアを指定します (例: record(metro=mml("ch=10 {A5 {Ab5* Ab5}/3}@@")))。

  • monitor (bool, optional) – Trueの場合、入力デバイスからのメッセージを出力デバイスへ送ります。

  • callback (function, optional) – 単一の引数を取る関数(コールバック関数)を指定すると、録音開始時に それが呼び出されます。引数にはループバックイベントが渡され、 そのイベントをコールバック関数内で時刻を更新して queue_event() で出力キューに挿入すれば、その時刻に再び コールバック関数が呼ばれるようにスケジュールすることができます。

Returns:

録音されたスコア

listen(dev=None) → RealTimeStream
monitor(dev=None) → None

入力デバイスからのイベント列を表示します。 この関数はキーボード・インタラプトを受けるまでリターンしません。

Parameters:

dev – 対象となる入力デバイス。Noneの場合は現在選択されている 入力デバイス、それ以外の場合はこれを引数として find_input_device() を呼んだ結果が対象のデバイス となります。指定したデバイスがオープンされていないときは、 自動的にオープンされます。また、関数から戻るときにはクローズ されます。