名前¶

MIDI::Track -- MIDIトラックのための関数とメソッド

概要¶

 use MIDI; # MIDI::Track その他を use する
 $taco_track = MIDI::Track->new;
 $taco_track->events(
  ['text_event', 0, "I like tacos!"],
  ['note_on',    0, 4, 50, 96 ],
  ['note_off', 300, 4, 50, 96 ],
 );
 $opus = MIDI::Opus->new(
  {  'format' => 0,  'ticks' => 240,  'tracks' => [ $taco_track ] }
 );
   ...etc...

説明¶

MIDI::Trackは、MIDIトラックを表現するオブジェクトに対する コンストラクタとメソッドを提供する。

現在MIDIトラックはタイプ、イベント、データという三つの属性を持っている。 あなたが扱うほとんど全てのトラックは"MTrk"タイプのトラックだ。 そしてこれがデフォルトのタイプである。イベントは、MTrkトラックを構成している。 もしあるトラックがMTrkタイプでないか、あるいはMTrkとして解析されない場合、 それはデータということだ。

MTrkトラックがエンコードされる時、そこに定義済みのデータがあるなら、それが エンコードされる（「データをエンコードする」とは、データを未接触のものへと 送るこをと意味する）。データが""で定義されていてもエンコードされることに注意 （データがundefになっているならエンコードされない）。しかし、定義済みデータが MTrkトラックにない場合（これはよくあることだ）、トラックが有するイベントが エンコードされる。これはMIDI::Event::encodeの呼び出しを通じて行われる。

（もしどのイベントも定義されていないなら、0サイズのトラックとして振舞う。）

非MTrkタイプのトラックがエンコードされるなら、トラックにあるデータはエンコード される。トラックにデータが無い場合は、0長サイズのトラックとして振舞う。

つまり、(1)イベントはMTrkタイプのトラック内部でのみ意味を持つ。 (2)定義されたデータとイベントの両方を必要とはしないだろう。 (3)あなたの時間の99.999%はMTrkトラック内のイベントに気をまわすことになる。 なぜなら、それがあなたが関わろうとすることの全てだからだ。

コンストラクタとメソッド¶

MIDI::Trackは以下のものを提供する。

MIDI::Track->new({ ...options... })

This returns a new track object. By default, the track is of type MTrk, which is probably what you want. The options, which are optional, is an anonymous hash. There are four recognized options: data, which sets the data of the new track to the string provided; type, which sets the type of the new track to the string provided; events, which sets the events of the new track to the contents of the list-reference provided (i.e., a reference to a LoL -- see perllol for the skinny on LoLs); and events_r, which is an exact synonym of events.

新しいトラックオブジェクトを返す。デフォルトでMTrkタイプになる。これはたぶん あなたが望むものだろう。任意のオプションとして無名ハッシュを渡せる。 モジュールは四つのオプションを認識する：dataは新規のトラックデータに 与えられた文字列をセットする。typeは新規のトラックのタイプに与えられた 文字列をセットする。eventsは新規のトラックのイベントに与えられたリスト リファレンスの内容をセットする（配列の配列へのリファレンス。正確な情報は perllolを参照すること）。そして events_rはeventsと同義。

$new_track = $track->copy

This duplicates the contents of the given track, and returns the duplicate. If you are unclear on why you may need this function, consider:

このメソッドはトラックの内容を複製し、オブジェクトを返す。 もしこの機能がなぜ必要なのかよくわからない場合は、次の例を考えてみよう。

          $funk  = MIDI::Opus->new({'from_file' => 'funk1.mid'});
          $samba = MIDI::Opus->new({'from_file' => 'samba1.mid'});

          $bass_track = ( $funk->tracks )[-1]; # $funkの最後尾のトラック
          push(@{ $samba->tracks_r }, $bass_track );
               # $sambaの最後尾のトラックにする

          &funk_it_up(  ( $funk->tracks )[-1]  );
               # $funkの最後尾のトラックを修正
          &turn_it_out(  ( $samba->tracks )[-1]  );
               # $sambaの最後尾のトラックを修正

          $funk->write_to_file('funk2.mid');
          $samba->write_to_file('samba2.mid');
          exit;

So you have your routines funk_it_up and turn_it_out, and they each modify the track they're applied to in some way. But the problem is that the above code probably does not do what you want -- because the last track-object of $funk and the last track-object of $samba are the same object. An object, you may be surprised to learn, can be in different opuses at the same time -- which is fine, except in cases like the above code. That's where you need to do copy the object. Change the above code to read:

つまり、あなたはfunk_it_upとturn_it_outというルーチンをつくり、何らかの方法で それぞれのトラックを修正することになる。しかし問題は、上記のコードではあなたの 望むことをやってくれないだろうということだ。$funkの最後尾の トラックオブジェクトと$sambaの最後尾のトラックオブジェクトが 同じオブジェクトだからだ。驚くかもしれないが、一つのオブジェクトが別の オプスの中に同時に存在しうる（上のようなケースの除けば、これはこれで良い）。 だからオブジェクトをコピーする必要がある。上記のコードを変更すると：

          push(@{ $samba->tracks_r }, $bass_track->copy );

and what you want to happen, will.

これであなたの望んだとおりになるだろう。

Incidentally, this potential need to copy also occurs with opuses (and in fact any reference-based data structure, altho opuses and tracks should cover almost all cases with MIDI stuff), which is why there's $opus->copy, for copying entire opuses.

ついでにいうと、このようなコピーの必要性が、オプスにおいても生じる（そして 実際、リファレンスに基づくどんなデータ構造でも生じる。オプスとトラックは MIDI要素のほとんど全てのケースをカバーしなければならないにもかかわらず）。 これがオプスを丸ごとコピーするために$opus->copyが存在する理由である。

(If you happen to need to copy a single event, it's just $new = [@$old] ; and if you happen to need to copy an event structure (LoL) outside of a track for some reason, use MIDI::Event::copy_structure.)

（単一のイベントをコピーする必要があるなら、単に$new = [@$old]でよい。 何らかの理由で一つのトラックを越えてイベント構造（リストのリスト）を コピーする必要が出たらMIDI::Event::copy_structureを使うこと。）

$track->events( @events )

Returns the list of events in the track, possibly after having set it to @events, if specified and not empty. (If you happen to want to set the list of events to an empty list, for whatever reason, you have to use "$track->events_r([])".)

トラックのイベントリストを返す。あるいは、@eventsを指定し、それが空でなければ その値がセットされる（理由は何であれ、リストイベントに空リストをセットしたい ならば、"$track->events_r([])"を使わなければならない）。

In other words: $track->events(@events) is how to set the list of events (assuming @events is not empty), and @events = $track->events is how to read the list of events.

つまり、（@eventsは空でないとして）$track->events(@events)はイベントリストの セット方法で、@events = $track->eventsはイベントリストの取得方法である。

$track->events_r( $event_r )

Returns a reference to the list of events in the track, possibly after having set it to $events_r, if specified. Actually, "$events_r" can be any listref to a LoL, whether it comes from a scalar as in $some_events_r, or from something like [@events], or just plain old \@events

トラックのイベントリストへのリファレンスを返す。あるいは、$events_rを指定すると リファレンスがセットされる。実際のところ、"$events_r"はリストのリスト(LoL)への リファレンスでありさえすればよいので、$some_events_rからだろうと、 [@events]からだろうと、古き簡素な\@eventsからだろうと構わない。

Originally $track->events was the only way to deal with events, but I added $track->events_r to make possible 1) setting the list of events to (), for whatever that's worth, and 2) so you can directly manipulate the track's events, without having to copy the list of events (which might be tens of thousands of elements long) back and forth. This way, you can say:

もともと$track->eventsがイベントを扱う唯一の方法だった。だが私が $track->events_rを付け加えたのは、(1)イベントリストを何らかの有意義な理由で 丸括弧()にセットできるようにするため。(2)（10000要素の長さにもなるような） イベントリストを前後でコピーしなくても、直接トラックイベントを操作できる ようにするためである。そこでこのように書くことができる：

          $events_r = $track->events_r();
          @some_stuff = splice(@$events_r, 4, 6);

But if you don't know how to deal with listrefs outside of LoLs, that's OK, just use $track->events.

だが配列の配列を越えてリストリファレンスの扱い方を知らなくても、大丈夫。 $track->eventsを使えばよい。

$track->type( 'MFoo' )

Returns the type of $track, after having set it to 'MFoo', if provided. You probably won't ever need to use this method, other than in a context like:

$trackのタイプを返す。'MFoo'を与えれば、それがセットされる。たぶん次のような 文脈以外では、このメソッドを使う必要が生じることはないだろう：

          if( $track->type eq 'MTrk' ) { # 普通の場合
            give_up_the_funk($track);
          } # それ以外なら処理を続けよう！

Track types must be 4 bytes long; see MIDI::Filespec for details.

トラックタイプは4バイト長でなければならない。 詳細はMIDI::Filespecを参照のこと。

$track->data( $kooky_binary_data )

Returns the data from $track, after having set it to $kooky_binary_data, if provided -- even if it's zero-length! You probably won't ever need to use this method. For your information, $track->data(undef) is how to undefine the data for a track.

$trackからデータを返す。$kooky_binary_dataを与えれば、それがセットされる。 これは0サイズのデータでもよい！たぶんこのメソッドを使う必要が生じることは ないだろう。参考までにいうと、$track->data(undef)は、 トラックデータを未定義にする方法である。

$track->new_event('event', ...parameters... )

This adds the event ('event', ...parameters...) to the end of the event list for $track. It's just sugar for:

$trackのイベントリストの最後にイベント('event', ...parameters...)を 付け加える。これは次のコードの構文糖に他ならない：

          push( @{$this_track->events_r}, [ 'event', ...params... ] )

If you want anything other than the equivalent of that, like some kinda splice(), then do it yourself with $track->events_r or $track->events.

もしもこれ以上のこと、例えばsplice()のようなことをしたいなら、 $track->events_rや$track->eventsを使って自分自身でやること。

$track->dump({ ...options... })

This dumps the track's contents for your inspection. The dump format is code that looks like Perlcode you'd use to recreate that track. This routine outputs with just print, so you can use select to change where that'll go. I intended this to be just an internal routine for use only by the method MIDI::Opus::dump, but I figure it might be useful to you, if you need te dump the code for just a given track. Read the source if you really need to know how this works.

このメソッドは、あなたが内容を確かめられるようにトラックの内容を ダンプする。ダンプ形式はPerlのコードようなものだ。このコードを使えば トラックを復元することができる。 このルーチンはprintを使って出力する。だから出力先を変えるためには selectを使うことになる。私はこのルーチンをMIDI::Opus::dumpだけから 利用される内部ルーチンにしようとした。だが、特定のトラックだけを ダンプしたい人にとって便利になるよう図った。このルーチンがどのような 動作をするのか本当に知りたいなら、ソースを見てもらいたい。

著作権¶

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