=encoding euc-jp

=head1 NAME

=begin original

MIDI::Opus -- functions and methods for MIDI opuses

=end original

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

=head1 概要

 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;

=head1 説明

=begin original

MIDI::Opus provides a constructor and methods for objects
representing a MIDI opus (AKA "song").  It is part of the MIDI suite.

=end original

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

=begin original

An opus object has three attributes: a format (0 for MIDI Format 0), a
tick parameter (parameter "division" in L<MIDI::Filespec>), and a list
of tracks objects that are the real content of that opus.

=end original

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

=begin original

Be aware that options specified for the encoding or decoding of an
opus may not be documented in I<this> module's documentation, as they
may be (and, in fact, generally are) options just passed down to the
decoder/encoder in MIDI::Event -- so see L<MIDI::Event> for an
explanation of most of them, actually.

=end original

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


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

=begin original

MIDI::Opus provides...

=end original

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

=over

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

=begin original

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:
C<format>, to set the MIDI format number (generally either 0 or 1) of
the new object; C<ticks>, to set its ticks parameter; C<tracks>, which
sets the tracks of the new opus to the contents of the list-reference
provided; C<tracks_r>, which is an exact synonym of C<tracks>;
C<from_file>, which reads the opus from the given filespec; and
C<from_handle>, which reads the opus from the the given filehandle
reference (e.g., C<*STDIN{IO}>), after having called binmode() on that
handle, if that's a problem.

=end original

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

=begin original

If you specify either C<from_file> or C<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.

=end original

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

=begin original

Finally, the option C<no_parse> can be used in conjuction with either
C<from_file> or C<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.)

=end original

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

=item $new_opus = $opus->copy

=begin original

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 C<copy> method in L<MIDI::Track>.

=end original

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

=item $opus->tracks( @tracks )

=begin original

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([])".)

=end original

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

=begin original

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.

=end original

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

=item $opus->tracks_r( $tracks_r )

=begin original

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 C<$some_tracks_r>,
or from something like C<[@tracks]>, or just plain old C<\@tracks>

=end original

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

=begin original

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 I<copy> the
list of tracks back and forth.  This way, you can say:

=end original

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

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

=begin original

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

=end original

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

=item $opus->ticks( $tick_parameter )

=begin original

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

=end original

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

=item $opus->format( $format )

=begin original

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

=end original

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

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

=begin original

Dumps the opus object as a bunch of text, for your perusal.  Options
include: C<flat>, if true, will have each event in the opus as a
tab-delimited line -- or as delimited with whatever you specify with
option C<delimiter>; I<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 C<dump_tracks> as true.

=end original

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

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

=begin original

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.

=end original

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

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

=begin original

Writes $opus as a MIDI file to the IO handle you pass a reference to
(example: C<*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 C</dev/sequencer>, since MIDI files are not MIDI-on-the-wire.

=end original

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

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

=begin original

This currently experimental method returns a new GD image object that's
a graphic representation of the notes in the given opus.  Options include:
C<width> -- the width of the image in pixels (defaults to 600);
C<bgcolor> -- a six-digit hex RGB representation of the background color
for the image (defaults to $MIDI::Opus::BG_color, currently '000000');
C<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 C<%> = the MOD operator).

=end original

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

=begin original

This means that if you specify

=end original

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

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

=begin original

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

=end original

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

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

=begin original

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

=end original

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

=begin original

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

=end original

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

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

=begin original

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

=end original

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

=begin original

I emphasise that C<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.

=end original

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


=back

=head1 デストラクタはどこか？

=begin original

Because MIDI objects (whether opuses or tracks) do not contain any
circular data structures, you don't need to explicitly destroy them in
order to deallocate their memory.  Consider this code snippet:

=end original

（オプスかトラックかに関わらず）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";
 }

=begin original

At the end of each iteration of the foreach loop, the variable $opus
goes away, along with its contents, a reference to the opus object.
Since no other references to it exist (i.e., you didn't do anything like
push(@All_opuses,$opus) where @All_opuses is a global), the object is
automagically destroyed and its memory marked for recovery.

=end original

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

=begin original

If you wanted to explicitly free up the memory used by a given opus
object (and its tracks, if those tracks aren't used anywhere else) without
having to wait for it to pass out of scope, just replace it with a new
empty object:

=end original

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

 $opus = MIDI::Opus->new;

=begin original

or replace it with anything at all -- or even just undef it:

=end original

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

 undef $opus;

=begin original

Of course, in the latter case, you can't then use $opus as an opus
object anymore, since it isn't one.

=end original

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

=head1 ティックについての注意

=begin original

If you want to use "negative" values for ticks (so says the spec: "If
division is negative, it represents the division of a second
represented by the delta-times in the file,[...]"), then it's up to
you to figure out how to represent that whole ball of wax so that when
it gets C<pack()>'d as an "n", it comes out right.  I think it'll involve
something like:

=end original

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


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

=begin original

for bit resolution (80) at 25 f/s.

=end original

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

=begin original

But I've never tested this.  Let me know if you get it working right,
OK?  If anyone I<does> get it working right, and tells me how, I'll
try to support it natively.

=end original

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

=head1 WARNとDIEの注意

=begin original

In the case of trying to parse a malformed MIDI file (which is not a
common thing, in my experience), this module (or MIDI::Track or
MIDI::Event) may warn() or die() (Actually, carp() or croak(), but
it's all the same in the end).  For this reason, you shouldn't use
this suite in a case where the script, well, can't warn or die -- such
as, for example, in a CGI that scans for text events in a uploaded
MIDI file that may or may not be well-formed.  If this I<is> the kind
of task you or someone you know may want to do, let me know and I'll
consider some kind of 'no_die' parameter in future releases.
(Or just trap the die in an eval { } around your call to anything you
think you could die.)

=end original

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



=head1 著作権

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.

=head1 作者

Sean M. Burke C<sburke@cpan.org>