名前¶

MIDI::Opus -- MIDIオプス（ソング）のための関数とメソッド

概要¶

 use MIDI; # MIDI::Opus その他をuseする
 foreach $one (@ARGV) {
   my $opus = MIDI::Opus->new({ 'from_file' => $one, 'no_parse' => 1 });
   print "$one has ", scalar( $opus->tracks ) " tracks\n";
 }
 exit;

説明¶

MIDI::OpusはMIDIオプス（ソング）オブジェクトに対する コンストラクタとメソッドを提供する。 このモジュールはMIDIパッケージの一部である。

オプスオブジェクトは三つの属性を持つ：フォーマット（MIDI Fromat 0の'0'）、 ティック（MIDI::Filespecにおける分解能）、そして オプスの実質的な内容であるトラックオブジェクトのリスト。

オプスのエンコード・デコードに対するオプション指定については、 このモジュールドキュメント内では説明していないので注意すること。 これらのオプション指定は恐らく（実際に一般的にそうなのだが）MIDI::Eventの デコーダー・エンコーダーへ伝えられるものなので、大概の説明はMIDI::Eventの 方を見て欲しい。

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

MIDI::Opusは以下を提供する。

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

This returns a new opus object. The options, which are optional, is an anonymous hash. By default, you get a new format-0 opus with no tracks and a tick parameter of 96. There are six recognized options: format, to set the MIDI format number (generally either 0 or 1) of the new object; ticks, to set its ticks parameter; tracks, which sets the tracks of the new opus to the contents of the list-reference provided; tracks_r, which is an exact synonym of tracks; from_file, which reads the opus from the given filespec; and from_handle, which reads the opus from the the given filehandle reference (e.g., *STDIN{IO}), after having called binmode() on that handle, if that's a problem.

これは新規のオプスオブジェクトを返す。なくても良いオプションとして 無名ハッシュを引数にとる。デフォルトでは、トラック無し・ティック96・ フォーマット0のオプスを得ることになる。モジュールが認識できる六つの オプションがある。formatは新規オブジェクトのMIDIフォーマットナンバーを セットする（通常0か1）。ticksはティックの値を設定する。tracksは新規 オプスのトラックに与えらたリストリファレンスの内容をセットする。 tracks_rはtracksと同じ意味。from_fileは与えられたファイル名の ファイルからオプスを読み込む。from_handleは与えられたファイルハンドル （例えば*STDIN{IO}）からオプスを読み込む。 問題がある場合はそのファイルハンドルに対しbinmode()を呼び出してから使う。

If you specify either from_file or from_handle, you probably don't want to specify any of the other options -- altho you may well want to specify options that'll get passed down to the decoder in MIDI::Events, such as 'include' => ['sysex_f0', 'sysex_f7'], just for example.

from_fileかfrom_handleを指定する際、他のオプションを指定したいとは 思わないだろう。にもかかわらずオプションを指定しようという場合は、 MIDI::Eventsのデコーダーに対してオプションを渡すことになる。 例えば 'include' => ['sysex_f0', 'sysex_f7'] 。

Finally, the option no_parse can be used in conjuction with either from_file or from_handle, and, if true, will block MTrk tracks' data from being parsed into MIDI events, and will leave them as track data (i.e., what you get from $track->data). This is useful if you are just moving tracks around across files (or just counting them in files, as in the code in the Synopsis, above), without having to deal with any of the events in them. (Actually, this option is implemented in code in MIDI::Track, but in a routine there that I've left undocumented, as you should access it only thru here.)

最後に、no_parseオプションはfrom_fileかfrom_handleとセットで使う。 このオプションに真値を設定した場合、MTrkトラックはMIDIイベントにパースされず、 トラックデータのままにされる（これは$track->dataで取得できる）。 ファイル間でトラックを移動させるだけなら（あるいは前述の"概要"における コードのように、ファイル中のトラック数を数えたいだけなら）、これは役に立つ。 というのも、ファイルの中のいかなるイベントも、いじり回さないからである （実際には、このオプションはMIDI::Trackで実装されている。しかしそのルーチンに ドキュメントをつけていないので、ここでしかこのことに触れることはできない）。

$new_opus = $opus->copy

This duplicates the contents of the given opus, and returns the duplicate. If you are unclear on why you may need this function, read the documentation for the copy method in MIDI::Track.

このメソッドはオプスの内容をコピーし、複製されたオブジェクトを返す。 なぜこの機能が必要なのかよくわからない場合は、MIDI::Trackの copyメソッドのドキュメントを読むこと。

$opus->tracks( @tracks )

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

オプスのトラックリストを返す。または、@tracksを指定し、それが空でなければ 内容をセットする（もしもトラックリストに空リストをセットしたいと思ったら、 理由は何であれ"$opus->tracks_r([])"を使わなければならない）。

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

つまり、（@tracksが空リストでないとして）$opus->tracks(@tracks)はトラック リストのセット方法で、@tracks = $opus->tracksは取得方法ということだ。

$opus->tracks_r( $tracks_r )

Returns a reference to the list of tracks in the opus, possibly after having set it to $tracks_r, if specified. "$tracks_r" can actually be any listref, whether it comes from a scalar as in $some_tracks_r, or from something like [@tracks], or just plain old \@tracks

オプスのトラックリストのリファレンスを返す。$tracks_rを指定すると、その内容を セットする。"$tracks_r"はリストリファレンスでありさえすればよいので、それが $some_tracks_rからなのか、[@tracks]からなのか、あるいは古き簡素な \@tracksからであるかのかは問わない。

Originally $opus->tracks was the only way to deal with tracks, but I added $opus->tracks_r to make possible 1) setting the list of tracks to (), for whatever that's worth, 2) parallel structure between MIDI::Opus::tracks[_r] and MIDI::Tracks::events[_r] and 3) so you can directly manipulate the opus's tracks, without having to copy the list of tracks back and forth. This way, you can say:

もともと$opus->tracksがトラックを扱う唯一の方法だった。だが私が $opus->tracks_rを付け加えたのは、(1)トラックリストを何らかの有意義な理由で 丸括弧()にセットできるようにするため。(2)MIDI::Opus::tracks[_r]と MIDI::Tracks::events[_r]の間のパラレル構造を可能にするため。 (3)トラックリストを前後でコピーしなくても、オプスのトラックを 直接操作できるようにするためである。そこでこのように書くことができる：

          $tracks_r = $opus->tracks_r();
          @some_stuff = splice(@$tracks_r, 4, 6);

But if you don't know how to deal with listrefs like that, that's OK, just use $opus->tracks.

だがこのようなリストリファレンスの扱い方を知らなくても、大丈夫。 $opus->tracksを使えばよい。

$opus->ticks( $tick_parameter )

Returns the tick parameter from $opus, after having set it to $tick_parameter, if provided.

$opusからティックの値を返す。$tick_parameterを与えればそれがセットされる。

$opus->format( $format )

Returns the MIDI format for $opus, after having set it to $format, if provided.

$opusのMIDIフォーマットの値を返す。$formatを与えればそれがセットされる。

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

Dumps the opus object as a bunch of text, for your perusal. Options include: flat, if true, will have each event in the opus as a tab-delimited line -- or as delimited with whatever you specify with option delimiter; otherwise, dump the data as Perl code that, if run, would/should reproduce the opus. For concision's sake, the track data isn't dumped, unless you specify the option dump_tracks as true.

オプスオブジェクトをダンプしてテクストの塊にする。次のオプションを とることができる：flatに真値を与えると、オプスのイベントは全て タブ区切りになる。あるいはc<delimiter>オプションで指定した区切りが使われる。 flatに真値が与えられていない場合、Perlのコードとしてダンプされる。 このコードを実行すればオプスは復元する。簡潔にするため、トラックデータは ダンプされない。dump_tracksを真に設定した場合はダンプされる。

$opus->write_to_file('filespec', { ...options...} )

Writes $opus as a MIDI file named by the given filespec. The options hash is optional, and whatever you specify as options percolates down to the calls to MIDI::Event::encode -- which see. Currently this just opens the file, calls $opus->write_to_handle on the resulting filehandle, and closes the file.

$opusを、指定した名前のMIDIファイルに書き出す。ハッシュをオプションとして 指定できる。指定したオプションは全てMIDI::Event::encodeを呼び出すときに 渡される（そちらを参照）。現在このメソッドは、ファイルを開き、ファイル ハンドルに対し$opus->write_to_handleを呼び出し、ファイルを閉じるだけである。

$opus->write_to_handle(IOREF, { ...options...} )

Writes $opus as a MIDI file to the IO handle you pass a reference to (example: *STDOUT{IO}). The options hash is optional, and whatever you specify as options percolates down to the calls to MIDI::Event::encode -- which see. Note that this is probably not what you'd want for sending music to /dev/sequencer, since MIDI files are not MIDI-on-the-wire.

リファレンスとして渡したIOハンドル（例：*STDOUT{IO}）に対し、$opusを、 MIDIファイルとして書き出す。ハッシュをオプションとして指定できる。指定した オプションは全てMIDI::Event::encodeを呼び出すときに渡される（そちらを参照）。 このことは、ミュージックを/dev/sequencerに送ろうとすることとは違うことに注意。 なぜならMIDIファイルはMIDI通信(MIDI-on-the-wire)ではないからだ。

$opus->draw({ ...options...})

This currently experimental method returns a new GD image object that's a graphic representation of the notes in the given opus. Options include: width -- the width of the image in pixels (defaults to 600); bgcolor -- a six-digit hex RGB representation of the background color for the image (defaults to $MIDI::Opus::BG_color, currently '000000'); channel_colors -- a reference to a list of colors (in six-digit hex RGB) to use for representing notes on given channels. Defaults to @MIDI::Opus::Channel_colors. This list is a list of pairs of colors, such that: the first of a pair (color N*2) is the color for the first pixel in a note on channel N; and the second (color N*2 + 1) is the color for the remaining pixels of that note. If you specify only enough colors for channels 0 to M, notes on a channels above M will use 'recycled' colors -- they will be plotted with the color for channel "channel_number % M" (where % = the MOD operator).

この現状実験的なメソッドは、新規のGDオブジェクトを返す。 このオブジェクトはオプスのノートをグラフィカルに表現するものだ。 オプションとして：width…ピクセル単位の画像の横幅（デフォルトは600）、 bgcolor…イメージの背景色を16進数6文字のRGB値で表す（デフォルトは $MIDI::Opus::BG_colorに設定され、現在は'000000'）、channel_colors…指定した チャンネルのノートを表示するために使う色（16進数6個のRBG値）のリストリファレンス。 デフォルトは@MIDI::Opus::Channel_colorsに設定されている。このリストは対になった 色のリストで、以下のようなもの：組の一番目(color N*2)はチャンネルNのノートの 最初のピクセルの色。そして二番目(color N*2 + 1)はそのノートの残りのピクセル色。 もしチャンネル0からMまでの色を指定しただけなら、M以降のチャンネルのノートの色は 使いまわしになる -- これは"channel_number % M"（%はMOD演算子）の色で表示される。

This means that if you specify

このように指定した場合、次のことを意味する。

          channel_colors => ['00ffff','0000ff']

then all the channels' notes will be plotted with an aqua pixel followed by blue ones; and if you specify

全てのチャンネルノートが、アクアブルーの後に青のピクセルで描画される。 また、次のように指定すると、

          channel_colors => ['00ffff','0000ff', 'ff00ff','ff0000']

then all the even channels' notes will be plotted with an aqua pixel followed by blue ones, and all the odd channels' notes will be plotted with a purple pixel followed by red ones.

偶数番号のチャンネルは全てアクアブルーの後に青のピクセルで描画され、 奇数番号のチャンネルは紫の後に赤のピクセルで描画される。

As to what to do with the object you get back, you probably want something like:

メソッドから得られたオブジェクトを扱うには次のようにすることになる。

          $im = $chachacha->draw;
          open(OUT, ">$gif_out"); binmode(OUT);
          print OUT $im->gif;
          close(OUT);

Using this method will cause a die if it can't successfully use GD.

use GDがうまくいかないでこのメソッドを使うと、dieが発生する。

I emphasise that draw is expermental, and, in any case, is only meant to be a crude hack. Notably, it does not address well some basic problems: neither volume nor patch-selection (nor any notable aspects of the patch selected) are represented; pitch-wheel changes are not represented; percussion (whether on percussive patches or on channel 10) is not specially represented, as it probably should be; notes overlapping are not represented at all well.

強調しておきたいのは、drawは実験的であるということだ。いずれにせよ このメソッドは未完成の仕組み(a crude hack)でしかない。特に、基本的な問題に ちゃんと取り組んではいない。例えば： 音量とパッチセレクション（つまり音色別のノート）はどちらも表示されない。 ピッチホイールの変化は表示されない。 （パーカッション音色かチャンネル10かに関わらず）パーカッションを区別して 表示しない（区別すべきではあるが）。和音も全然表現されない。

デストラクタはどこか？¶

（オプスかトラックかに関わらず）MIDIオブジェクトはいかなる循環構造データも 含まないので、メモリを綺麗にするために明示的にオブジェクトを破壊する必要はない。 この小さなコードを見てみよう：

 use MIDI;
 foreach $one (@ARGV) {
   my $opus = MIDI::Opus->new({ 'from_file' => $one, 'no_parse' => 1 });
   print "$one has ", scalar( $opus->tracks ) " tracks\n";
 }

foreachループの毎回の繰り返しの最後に変数$opusが消え去る。このとき一緒に オプスオブジェクトのリファレンスも消える。（グローバルな@All_opusesに対して push(@All_opuses,$opus)みたいなことをしていない場合）他に参照している リファレンスが存在しないので、そのオブジェクトは自動的に破壊され、 メモリーは解放のための印がつく。

オプスオブジェクトがスコープの外に出るまで待つのではなく、明示的に使用された メモリーを解放したい場合、単に新規の空オブジェクトを代入すればよい。

 $opus = MIDI::Opus->new;

あるいは代入するのは何でもいい -- undefしてもよい。

 undef $opus;

もちろん、後者の場合、その後$opusをオプスオブジェクトとして使うことはできない。

ティックについての注意¶

もしティックに負の値を使おうとするなら（仕様書には「分解能がマイナスの場合、 ファイルの中のデルタタイムを秒で表す…」とある）、"n"でpack()することに よって、曲全体を正しく表す方法を理解しなければならない。 たぶんこのような感じになるだろう：

  $opus->ticks(  (unpack('C', pack('c', -25)) << 8) & 80  );

25 frames/sec のビット分解能(80) に対応する。

ただし、私はこれを試したことはない。正しく動作したら知らせてくれないだろうか？ もし誰かがうまくいって、どのようにやったかを私に教えてくれるなら、 この機能をネイティブにサポートしようと思う。

WARNとDIEの注意¶

不正な形式のMIDIファイル（共通の事象というよりも自分の経験からだが）を パースしようとすると、このモジュール（あるいはMIDI::TrackやMIDI::Event）は warn()かdie()するだろう（実際にはcarp()やcroak()かもしれないが、 結局は同じことだ）。そのため、うまくwarnやdieできないスクリプトの中では このパッケージを使うべきではない。例えば、正しい形式なのかどうなのかわからない アップロードされたMIDIファイルのテクストイベントをスキャンするようなCGIなど。 もしあなたやあなたの知り合いが欲しいというなら、今後のリリースの際には 'no_die'パラメータのようなものを考慮するだろう（あるいはdieしそうな呼び出し の周りをeval{}でトラップするだけでもよい）。

著作権¶

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