名前¶

MIDI::Event - MIDIイベント

概要¶

  # MIDIファイル中のテキストイベントをダンプする
  die "No filename" unless @ARGV;
  use MIDI;  # MIDI::Event を use している
  MIDI::Opus->new( {
     "from_file" => $ARGV[0],
     "exclusive_event_callback" => sub{print "$_[2]\n"},
     "include" => \@MIDI::Event::Text_events
   } ); # これらのオプションは MIDI::Event::decode に渡される
  exit;

説明¶

MIDIイベントを扱う関数とリスト、及びMIDIイベントの構造。

一つのイベントはこのようなリストである：

  ( 'note_on', 141, 4, 50, 64 )

最初の要素はイベント名。二番目はデルタタイム。そして残りは追加パラメータで、 この後に出てくるイベント形式の仕様別パラメータである。

一つのイベント構造体は、このような諸イベントへのリファレンスのリスト、 すなわちリストのリスト(LoL)である。 もしLoLの扱いがわからないなら、perllplを読まなければならない。

小物¶

（概要に例示しているような）プログラム中で使うために、このモジュールは ほんの少しであるがリストを提供している。

@MIDI_events

a list of all "MIDI events" AKA voice events -- e.g., 'note_on'

ボイスメッセージ(voice events)と呼ばれる全MIDIイベントのリスト。例：'note_on'

@Text_events

a list of all text meta-events -- e.g., 'track_name'

テキスト型のメタイベント。例：'track_name'

@Nontext_meta_events

all other meta-events (plus 'raw_data' and F-series events like 'tune_request').

非テキスト型メタイベント（さらに'raw_data'や、'tune_request'のような F系列のイベントも加わる）

@Meta_events

the combination of Text_events and Nontext_meta_events.

テキスト型イベントと非テキスト型メタイベントの組み合わせ。

@All_events

the combination of all the above lists.

以上あげた全てのリストの組み合わせ。

関数¶

このモジュールはイベント構造体に作用する三つの興味深い関数を提供する。 あなたがエンドユーザーなら、これらの関数を直接利用する必要はないだろう。 だが、from_fileやfrom_handleオプションとともに使うMIDI::Opus->newに指定する オプションは、これらの関数へと送られることに注意すること。だから、これから あげる関数の２番目までについては、そのオプションを理解しておくべきだろう。

MIDI::Event::decode( \$data, { ...options... } )

This takes a reference to binary MIDI data and decodes it into a new event structure (a LoL), a reference to which is returned. Options are:

この関数はバイナリ形式のMIDIデータへのリファレンスを引数に取り、 新しいイベント構造体（LoL）にデコードする。関数の戻り値はこの構造体への リファレンスである。オプションは次の通り：

'include' => LISTREF

If specified, listref is interpreted as a reference to a list of event names (e.g., 'cue_point' or 'note_off') such that only these events will be parsed from the binary data provided. Events whose names are NOT in this list will be ignored -- i.e., they won't end up in the event structure, and they won't be each passed to any callbacks you may have specified.

このオプションを指定すると、リストリファレンスはイベント名 （例：'cue_point'や'note_off'）リストへのリファレンスとして解釈される。 このリストにあるイベント名だけが、与えられたバイナリデータからパースされる。 このリストに"ない"イベント名は無視される。つまり、それらはイベント構造体には ならない。また、指定したいかなるコールバック関数にもデータは渡されない。

'exclude' => LISTREF

If specified, listref is interpreted as a reference to a list of event names (e.g., 'cue_point' or 'note_off') that will NOT be parsed from the binary stream; they'll be ignored -- i.e., they won't end up in the event structure, and they won't be passed to any callbacks you may have specified. Don't specify both an include and an exclude list. And if you specify neither, all events will be decoded -- this is what you probably want most of the time. I've created this include/exclude functionality mainly so you can scan a file rather efficiently for just a few specific event types, e.g., just text events, or just sysexes.

このオプションを指定すると、リストリファレンスはイベント名 （例：'cue_point'や'note_off'）リストへのリファレンスとして解釈される。 このリストにあるイベント名はバイナリストリームから"パースされない"。 それらは無視される。つまり、それらはイベント構造体にはならない。また、 指定したいかなるコールバック関数にもデータは渡されない。 includeオプションとexcludeオプションのリストを両方指定してはならない。 また、両方のオプションを指定しない場合、全てのイベントがデコードされる。 これをすると、パースにかなり時間が必要になるかもしれない。 私がこのinclude/exclude機能を作ったのは、ほんの少しの特殊なイベントタイプ （例えば単なるテキストイベントやシステムエクスクルーシブメッセージ）に対し 効率的にファイルを走査するためである。

'no_eot_magic' => 0 or 1

See the description of 'end_track', in "EVENTS", below.

後に出てくる"イベント"の'end_track'の説明を参照。

'event_callback' => CODEREF

If defined, the code referred to (whether as \&wanted or as sub { BLOCK }) is called on every event after it's been parsed into an event list (and any EOT magic performed), but before it's added to the event structure. So if you want to alter the event stream on the way to the event structure (which counts as deep voodoo), define 'event_callback' and have it modify its @_.

サブルーチンへのリファレンス（\&wantedでもsub { BLOCK }でもよい）を定義 すると、データがイベントリストへとパースされた後、イベント毎にそのコードが 呼び出される（そして何らかのEOTマジックが実行される）。 ただし、コードはイベントがイベント構造体に追加される前に呼び出される。 つまり、イベント構造体へ付け加える過程でイベントストリームに変更を加えたいなら、 'event_callback'を定義して、そのルーチンの@_を修正するということだ。

'exclusive_event_callback' => CODEREF

Just like 'event_callback'; but if you specify this, the callback is called instead of adding the events to the event structure. (So the event structure returned by decode() at the end will always be empty.) Good for cases like the text dumper in the Synopsis, above.

'event_callback'と同じだ。ただしこのオプションを指定すると、イベントを イベント構造体に付け加える代わりにコールバックが呼び出される（それゆえ、 最後にdecode()で返されるイベント構造体は常に空となる）。 先に概要のところでみたように、テキストダンプのようなケースで使うとよい。

MIDI::Event::encode( \@events, {...options...})

This takes a reference to an event structure (a LoL) and encodes it as binary data, which it returns a reference to. Options:

この関数はイベント構造体（LoL）へのリファレンスを引数に取り、 バイナリデータとしてエンコードする。関数の戻り値はこのデータへのリファレンス である。オプションは次の通り：

'unknown_callback' => CODEREF

If this is specified, it's interpreted as a reference to a subroutine to be called when an unknown event name (say, 'macro_10' or something), is seen by encode(). The function is fed all of the event (its name, delta-time, and whatever parameters); the return value of this function is added to the encoded data stream -- so if you don't want to add anything, be sure to return ''.

このオプションに指定したサブルーチンへのリファレンスは、encode()が未知の イベント名（例えば'macro_10'とか何か）に出くわしたときに呼び出される。 この関数にはイベントの要素全て（イベント名前、デルタタイム、その他の パラメーター）が与えられ、戻り値はエンコードされたデータストリームに 追加される。だから、何も追加したくないなら必ず''（空文字）を返すようにすること。

If no 'unknown_callback' is specified, encode() will warn (well, carp) of the unknown event. To merely block that, just set 'unknown_callback' to sub{return('')}

'unknown_callbackを指定しないと、encode()は未知のイベントに対しwarn （あるいはcarp）を発生させる。これをさせないためには、'unknown_callback' オプションにsub{return('')}をセットすればよい。

'no_eot_magic' => 0 or 1

Determines whether a track-final 0-length text event is encoded as a end-track event -- since a track-final 0-length text event probably started life as an end-track event read in by decode(), above.

トラック終端の0長サイズのテキストイベントを、エンドオブトラックとしてエンコード するかどうか決定する。というのも、トラック終端の0長サイズのテキストイベントは、 decode()が読み込むと、エンドオブトラックとして生成されるからだ。

'never_add_eot' => 0 or 1

If 1, encode() never ever adds an end-track (EOT) event to the encoded data generated unless it's explicitly there as an 'end_track' in the given event structure. You probably don't ever need this unless you're encoding for straight writing to a MIDI port, instead of to a file.

1にすると、encode()は自ら生成するエンコードデータにエンドオブトラック(EOT)を 加えなくなる。ただしイベント構造内に明示的に'end_track'がある場合は別だ。 あなたがファイルではなくてMIDIポートに直接書き込もうとしない限り、 このオプションは必要ないだろう。

'no_running_status' => 0 or 1

If 1, disables MIDI's "running status" compression. Probably never necessary unless you need to feed your MIDI data to a strange old sequencer that doesn't understand running status.

1にするとランニングステータスが利用できなくなる。ランニングステータスを 理解しない古びて珍奇なシーケンサでも使わない限り、たぶんこのオプションは 必要ないだろう。

Note: If you're encoding just a single event at a time or less than a whole trackful in any case, then you probably want something like:

注意：一度に一つのイベントだけをエンコードする場合、あるいはとにかく一度に 全トラックをエンコードしない場合、このようにするだろう：

          $data_r = MIDI::Event::encode(
            [
              [ 'note_on', 141, 4, 50, 64 ]
            ],
            { 'never_add_eot' => 1} );

which just encodes that one event as an event structure of one event -- i.e., an LoL that's just a list of one list.

これは、一つのイベントからなるイベント構造体として一つのイベントを エンコードしている。つまり、一つのLoLはまさに一つのリストのリストである。

But note that running status will not always apply when you're encoding less than a whole trackful at a time, since running status works only within a LoL encoded all at once. This'll result in non-optimally compressed, but still effective, encoding.

しかし注意したいのは、一度に全トラックをエンコードしないなら、 ランニングステータスは必ずしも適用されるとは限らないということだ。なぜなら ランニングステータスは一度に全部エンコードされたLoLの中でのみ機能するからだ。 これは非最適圧縮型（だが依然効率的な）エンコードの結果である。

MIDI::Event::copy_structure()

This takes a reference to an event structure, and returns a reference to a copy of it. If you're thinking about using this, you probably should want to use the more straightforward

この関数はイベント構造体へのリファレンスを引数に取り、コピーしたリファレンスを 返す。もしこの関数を使うことについて思案しているなら、もっと素直な使い方を 望むべきだろう。

          $track2 = $track->copy

instead. But it's here if you happen to need it.

これが代わりになる。

イベントとイベントデータのタイプ¶

データタイプ¶

イベントはこれらのデータタイプを使用する：

channel = 0〜15の値

note = 0〜127の値

dtime = 0〜268,435,455 (0x0FFFFFFF)の値

velocity = 0〜127の値

patch = 0〜127の値

sequence = 0-65,535 (0xFFFF)の値

text = 0byte以上のASCII文字列

raw = 0byte以上のバイナリデータの文字列

pitch_wheel = -8192〜8191 (0x1FFF)の値

song_pos = 0〜16,383 (0x3FFF)の値

song_number = 0〜127の値

tempo = マイクロ秒, 0〜16,777,215 (0x00FFFFFF)の値

上で定義していないデータタイプ（例：'key_signature'用のsfやmi） については、 MIDI::FilespecやMIDI::Event.pmのソースで調べて欲しい。 そのドキュメントにも書いていなければ、たぶん私の理解していないタイプなので、 実際のMIDIリファレンスを調べるべきだろう。

イベント¶

イベント：

('note_off', dtime, channel, note, velocity)

('note_on', dtime, channel, note, velocity)

('key_after_touch', dtime, channel, note, velocity)

('control_change', dtime, channel, controller(0-127), value(0-127))

('patch_change', dtime, channel, patch)

('channel_after_touch', dtime, channel, velocity)

('pitch_wheel_change', dtime, channel, pitch_wheel)

('set_sequence_number', dtime, sequence)

('text_event', dtime, text)

('copyright_text_event', dtime, text)

('track_name', dtime, text)

('instrument_name', dtime, text)

('lyric', dtime, text)

('marker', dtime, text)

('cue_point', dtime, text)

('text_event_08', dtime, text)

('text_event_09', dtime, text)

('text_event_0a', dtime, text)

('text_event_0b', dtime, text)

('text_event_0c', dtime, text)

('text_event_0d', dtime, text)

('text_event_0e', dtime, text)

('text_event_0f', dtime, text)

('end_track', dtime)

('set_tempo', dtime, tempo)

('smpte_offset', dtime, hr, mn, se, fr, ff)

('time_signature', dtime, nn, dd, cc, bb)

('key_signature', dtime, sf, mi)

('sequencer_specific', dtime, raw)

('raw_meta_event', dtime, command(0-255), raw)

('sysex_f0', dtime, raw)

('sysex_f7', dtime, raw)

('song_position', dtime)

('song_select', dtime, song_number)

('tune_request', dtime)

('raw_data', dtime, raw)

上のイベントのうち三つは、標準MIDIファイルの仕様からすると少し変である。

'pitch_wheel_change'用のpitch_wheelは-8192から8191の値をとる。 しかし実際には、仕様書通り0から16,383としてエンコードされる。

システムエクスクルーシブイベントは'sysex_f0'か'sysex_f7'として表される。 これは一緒にエンコードされたステータスバイトに依存している。

'end_track'は奇妙な代物だ。実際、ほとんど見かけることも、必要とされることも ない。MIDIデコーダーはEOT（エンドトラックステータス：FF 2F 00）を0のデルタタイム とセットで見つけると無視してしまう！もしも0のデルタタイムでない珍しいイベント内 だったら、それはデルタタイムの値が何であれ、'text_event'としてデコードされる。 そしてこれは0長サイズのテキストパラメーターになる（これは'event_callback'や 'exclusive_event_callback'が実行される前に発生する）。エンコードする側から すると、EOTはトラックデータを包む通常パートとしてトラックの最後に追加される。

私がこの特殊な振る舞いを付け加えることを選択したのは、トラック終端の 'end_track'を避けなくても、トラックの後ろにイベントを付け加えることが できるようにするためである。

しかし、もしデコードのパラメータにno_eot_magicをセットしたら、デコードする 側ではこの魔法は起きない。'end_track'はそのままデコードされるのだ。

そしてエンコードのパラメータにno_eot_magicをセットしたなら、0でない デルタタイムを伴う0長サイズの'text_event'は、そのまま残される。 通常そのようなイベントは、'text_event'からそのデルタタイムを伴った 'end_track'に変換される。

通常、エンコード・デコードのいずれでも、no_eot_magicオプションを使いたがる 人はいない。だが、あなたがイベントLoLをバイナリデータとして絶対的に文字通りの 表現にしたい場合には、そして・あるいは、その逆の場合には、このオプションを 与えることになる。

MIDI BNF¶

（あなたが理解できるとして）参考のために、MIDI BNFの写しを載せておく。 私はこれを1980年代後半以来ネットに出回っていたテキストファイルの中から 見つけだした。

これはMIDI通信で使われるものとして記述されていることに注意。リアルタイムデータ 挿入（リアルタイムのデータがメッセージの途中に飛び込んでくる）は、 MIDIファイルで生じうるようなものではないと思う。

実際、このライブラリは、これまで書いてきたように、データがメッセージに リアルタイムに挿入されるようなMIDIデータを正しくパースすることはできない。 MIDIイベント構造において、ファイルに書き込みをするためにエンコード可能な データ挿入を表現することもサポートしていない。（理論的には <リアルタイムデータ>の埋め込まれたイベントをraw_dataイベントとして 表現することは可能だろう。しかしそれだと、どんなデータも常にraw_data イベントとして詰め込めることになる。）

 1.  <MIDI Stream> ::=           <MIDI msg> < MIDI Stream>
 2.  <MIDI msg> ::=              <sys msg> | <chan msg>
 3.  <chan msg> ::=              <chan 1byte msg> |
                                 | <chan 2byte msg>
 4.  <chan 1byte msg> ::=        <chan stat1 byte> <data singlet>
                                   <running singlets>
 5.  <chan 2byte msg> ::=        <chan stat2 byte> <data pair>
                                   <running pairs>
 6.  <chan stat1 byte> ::=       <chan voice stat1 nibble>
                                   <hex nibble>
 7.  <chan stat2 byte> ::=       <chan voice stat2 nibble>
                                   <hex nibble>
 8.  <chan voice stat1 nyble>::= C | D
 9.  <chan voice stat2 nyble>::= 8 | 9 | A | B | E
 10. <hex nyble> ::=             0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
                                 | 8 | 9 | A | B | C | D | E | F
 11. <data pair> ::=             <data singlet> <data singlet>
 12. <data singlet> ::=          <realtime byte> <data singlet> |
                                 | <data byte>
 13. <running pairs> ::=         <empty> | <data pair> <running pairs>
 14. <running singlets> ::=      <empty> |
                                 | <data singlet> <running singlets>
 15. <data byte> ::=             <data MSD> <hex nyble>
 16. <data MSD> ::=              0 | 1 | 2 | 3 | 4 | 5 | 6 | 7
 17. <realtime byte> ::=         F8 | FA | FB | FC | FE | FF
 18. <sys msg> ::=               <sys common msg> |
                                 | <sysex msg> |
                                 | <sys realtime msg>
 19. <sys realtime msg> ::=      <realtime byte>
 20. <sysex msg> ::=             <sysex data byte>
                                   <data singlet> <running singlets>
                                   <eox byte>
 21. <sysex stat byte> ::=       F0
 22. <eox byte> ::=              F7
 23. <sys common msg> ::=        <song position msg> |
                                 | <song select msg> |
                                 | <tune request>
 24. <tune request> ::=          F6
 25. <song position msg> ::=     <song position stat byte>
                                   <data pair>
 26. <song select msg> ::=       <song select stat byte>
                                   <data singlet>
 27. <song position stat byte>::=F2
 28. <song select stat byte> ::= F3

著作権¶

Copyright (c) 1998-2002 Sean M. Burke. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

作者¶

Sean M. Burke sburke@cpan.org (Except the BNF -- who knows who's behind that.)