MIDI-Perl-0.8/MIDI/Score.pod


=encoding euc-jp

=head1 NAME

MIDI::Score - MIDI scores

MIDI::Score - MIDIスコア

=head1 概要

  # 話せば長くなるので、下をみよ。

=head1 説明

This module provides functions to do with with MIDI scores.
It is used as the basis for all the functions in MIDI::Simple.
(Incidentally, MIDI::Opus's draw() method also uses some of the
functions in here.)

このモジュールはMIDIスコアを扱うための機能を提供する。
MIDI::Simpleの全ての機能の基として利用されている。
ちなみに、MIDI::Opusのdraw()メソッドもこのモジュールの機能の
一部を利用している。

Whereas the events in a MIDI event structure are items whose timing
is expressed in delta-times, the timing of items in a score is
expressed as an absolute number of ticks from the track's start time.
Moreover, pairs of 'note_on' and 'note_off' events in an event structure
are abstracted into a single 'note' item in a score structure.

MIDIイベント構造体の中に入っている各イベントは、デルタタイムで表される
時間間隔を持った要素である。これに対してスコアの中の要素が持つ時間間隔は、
そのトラックの開始時間から計ったティックの絶対値として表現される。
さらに、イベント構造内で対になっているノートオン（'note_on'）と
ノートオフ（'note_off'）は、スコアの中では単体のノート（'note'）へと
抽象化される。

'note' takes the following form:

ノート（'note'）は次の形式をとる：

 ('note', I<start_time>, I<duration>, I<channel>, I<note>, I<velocity>)

The problem that score structures are meant to solve is that 1)
people definitely don't think in delta-times -- they think in absolute
times or in structures based on that (like 'time from start of measure');
2) people think in notes, not note_on and note_off events.

スコア構造体によって次の問題が解決する。
(1)人々は明らかにデルタタイムでは考えない。絶対時間か、上に述べた
ような構造（スタートからの時間）でもって考える。
(2)人々はノート（音符）で考えるのであって、ノートオンやノートオフで
ではない。

So, given this event structure:

そこで、次のようなイベント構造体があるとする：

 ['text_event', 0, 'www.ely.anglican.org/parishes/camgsm/chimes.html'],
 ['text_event', 0, 'Lord through this hour/ be Thou our guide'],
 ['text_event', 0, 'so, by Thy power/ no foot shall slide'],
 ['patch_change', 0, 1, 8],
 ['note_on', 0, 1, 25, 96],
 ['note_off', 96, 0, 1, 0],
 ['note_on', 0, 1, 29, 96],
 ['note_off', 96, 0, 1, 0],
 ['note_on', 0, 1, 27, 96],
 ['note_off', 96, 0, 1, 0],
 ['note_on', 0, 1, 20, 96],
 ['note_off', 192, 0, 1, 0],
 ['note_on', 0, 1, 25, 96],
 ['note_off', 96, 0, 1, 0],
 ['note_on', 0, 1, 27, 96],
 ['note_off', 96, 0, 1, 0],
 ['note_on', 0, 1, 29, 96],
 ['note_off', 96, 0, 1, 0],
 ['note_on', 0, 1, 25, 96],
 ['note_off', 192, 0, 1, 0],
 ['note_on', 0, 1, 29, 96],
 ['note_off', 96, 0, 1, 0],
 ['note_on', 0, 1, 25, 96],
 ['note_off', 96, 0, 1, 0],
 ['note_on', 0, 1, 27, 96],
 ['note_off', 96, 0, 1, 0],
 ['note_on', 0, 1, 20, 96],
 ['note_off', 192, 0, 1, 0],
 ['note_on', 0, 1, 20, 96],
 ['note_off', 96, 0, 1, 0],
 ['note_on', 0, 1, 27, 96],
 ['note_off', 96, 0, 1, 0],
 ['note_on', 0, 1, 29, 96],
 ['note_off', 96, 0, 1, 0],
 ['note_on', 0, 1, 25, 96],
 ['note_off', 192, 0, 1, 0],

here is the corresponding score sctructure:

これに対応するスコア構造体は：

 ['text_event', 0, 'www.ely.anglican.org/parishes/camgsm/chimes.html'],
 ['text_event', 0, 'Lord through this hour/ be Thou our guide'],
 ['text_event', 0, 'so, by Thy power/ no foot shall slide'],
 ['patch_change', 0, 1, 8],
 ['note', 0, 96, 1, 25, 96],
 ['note', 96, 96, 1, 29, 96],
 ['note', 192, 96, 1, 27, 96],
 ['note', 288, 192, 1, 20, 96],
 ['note', 480, 96, 1, 25, 96],
 ['note', 576, 96, 1, 27, 96],
 ['note', 672, 96, 1, 29, 96],
 ['note', 768, 192, 1, 25, 96],
 ['note', 960, 96, 1, 29, 96],
 ['note', 1056, 96, 1, 25, 96],
 ['note', 1152, 96, 1, 27, 96],
 ['note', 1248, 192, 1, 20, 96],
 ['note', 1440, 96, 1, 20, 96],
 ['note', 1536, 96, 1, 27, 96],
 ['note', 1632, 96, 1, 29, 96],
 ['note', 1728, 192, 1, 25, 96]

Note also that scores aren't crucially ordered.  So this:

スコアは厳密に順番に並んでいるわけではない。だから：

 ['note', 768, 192, 1, 25, 96],
 ['note', 960, 96, 1, 29, 96],
 ['note', 1056, 96, 1, 25, 96],

means the same thing as:

これは次のものと同じだ：

 ['note', 960, 96, 1, 29, 96],
 ['note', 768, 192, 1, 25, 96],
 ['note', 1056, 96, 1, 25, 96],

The only exception to this is in the case of things like:

この唯一の例外は、次のようなケースの時だ：

 ['patch_change', 200,     2, 15],
 ['note',         200, 96, 2, 25, 96],

where two (or more) score items happen I<at the same time> and where one
affects the meaning of the other.

二つ以上のスコア要素が同時に発生し、かつ、一つが他方の意味に
影響を与える場合。


=head1 スコアの中に何があるのか

Besides the new score structure item C<note> (covered above),
the possible contents of a score structure can be summarized thus:
Whatever can appear in an event structure can appear in a score
structure, save that its second parameter denotes not a
delta-time in ticks, but instead denotes the absolute number of ticks
from the start of the track.

（先に述べた）C<note>以外に、スコア構造体が持ちうる構成要素をもとめると：
イベント構造体に現れるものは何でもスコア構造体に現れうるということだ。
要素が保持する第二パラメータはティックで表現されるデルタタイムではなく、
トラック開始からの絶対的なティックの数を意味している。

To avoid the long periphrase "items in a score structure", I will
occasionally refer to items in a score structure as "notes", whether or
not they are actually C<note> commands.  This leaves "event" to
unambiguously denote items in an event structure.

「スコア構造体の要素」などという回りくどい言い方は避けたいので、
私はしばしばこれをノート（"notes"）と呼ぶ。それが本当にC<note>コマンド
なのかどうかとは関係ない。"event"の方は、明確にイベント構造体の要素を
意味するよう、そのままにしておく。

These, below, are all the items that can appear in a score.
This is basically just a repetition of the table in
L<MIDI::Event>, with starttime substituting for dtime --
so refer to L<MIDI::Event> for an explanation of what the data types
(like "velocity" or "pitch_wheel").
As far as order, the first items are generally the most important:

以下はスコアに登場する全項目である。
基本的にL<MIDI::Event>にあった表の繰り返しでしかない。デルタタイムの
代わりにスタート時からのタイムに置き換わってはいるが。だから、
データタイプ（"velocity"や"pitch_wheel"など）の説明はL<MIDI::Event>を
参照して欲しい。順番に限っていえば、一般的に最初のほうに出てくるものが
最も重要である。

=over

=item ('note', I<starttime>, I<duration>, I<channel>, I<note>, I<velocity>)

=item ('key_after_touch', I<starttime>, I<channel>, I<note>, I<velocity>)

=item ('control_change', I<starttime>, I<channel>, I<controller(0-127)>, I<value(0-127)>)

=item ('patch_change', I<starttime>, I<channel>, I<patch>)

=item ('channel_after_touch', I<starttime>, I<channel>, I<velocity>)

=item ('pitch_wheel_change', I<starttime>, I<channel>, I<pitch_wheel>)

=item ('set_sequence_number', I<starttime>, I<sequence>)

=item ('text_event', I<starttime>, I<text>)

=item ('copyright_text_event', I<starttime>, I<text>)

=item ('track_name', I<starttime>, I<text>)

=item ('instrument_name', I<starttime>, I<text>)

=item ('lyric', I<starttime>, I<text>)

=item ('marker', I<starttime>, I<text>)

=item ('cue_point', I<starttime>, I<text>)

=item ('text_event_08', I<starttime>, I<text>)

=item ('text_event_09', I<starttime>, I<text>)

=item ('text_event_0a', I<starttime>, I<text>)

=item ('text_event_0b', I<starttime>, I<text>)

=item ('text_event_0c', I<starttime>, I<text>)

=item ('text_event_0d', I<starttime>, I<text>)

=item ('text_event_0e', I<starttime>, I<text>)

=item ('text_event_0f', I<starttime>, I<text>)

=item ('end_track', I<starttime>)

=item ('set_tempo', I<starttime>, I<tempo>)

=item ('smpte_offset', I<starttime>, I<hr>, I<mn>, I<se>, I<fr>, I<ff>)

=item ('time_signature', I<starttime>, I<nn>, I<dd>, I<cc>, I<bb>)

=item ('key_signature', I<starttime>, I<sf>, I<mi>)

=item ('sequencer_specific', I<starttime>, I<raw>)

=item ('raw_meta_event', I<starttime>, I<command>(0-255), I<raw>)

=item ('sysex_f0', I<starttime>, I<raw>)

=item ('sysex_f7', I<starttime>, I<raw>)

=item ('song_position', I<starttime>)

=item ('song_select', I<starttime>, I<song_number>)

=item ('tune_request', I<starttime>)

=item ('raw_data', I<starttime>, I<raw>)

=back


=head1 関数

This module provides these functions:

このモジュールは以下の関数を提供する：

=over

=item $score2_r = MIDI::Score::copy_structure($score_r)

This takes a I<reference> to a score structure, and returns a
I<reference> to a copy of it. Example usage:

この関数はスコア構造体へのリファレンスを引数にとり、そのコピーへの
リファレンスを返す。例えば：

          @new_score = @{ MIDI::Score::copy_structure( \@old_score ) };

=item $events_r = MIDI::Score::score_r_to_events_r( $score_r )

=item ($events_r, $ticks) = MIDI::Score::score_r_to_events_r( $score_r )

This takes a I<reference> to a score structure, and converts it to an
event structure, which it returns a I<reference> to.  In list context,
also returns a second value, a count of the number of ticks that
structure takes to play (i.e., the end-time of the temporally last
item).

この関数はスコア構造体へのリファレンスを引数にとってイベント構造体に
変換し、そのリファレンスを返す。リストコンテキストでは、二つ目の値も
返す。これはその構造体が演奏に要するティックの総数（時間的に最後の
項目の終了時間）である。

=item $score2_r = MIDI::Score::sort_score_r( $score_r)

This takes a I<reference> to a score structure, and returns a
I<reference> to a sorted (by time) copy of it. Example usage:

この関数はスコア構造体へのリファレンスを引数にとり、（時間によって）
ソートされたコピーへのリファレンスを返す。例えば：

          @sorted_score = @{ MIDI::Score::sort_score_r( \@old_score ) };

=item $score_r = MIDI::Score::events_r_to_score_r( $events_r )

=item ($score_r, $ticks) = MIDI::Score::events_r_to_score_r( $events_r )

This takes a I<reference> to an event structure, converts it to a
score structure, which it returns a I<reference> to.  If called in
list context, also returns a count of the number of ticks that
structure takes to play (i.e., the end-time of the temporally last
item).

この関数はイベント構造体へのリファレンスを引数にとってスコア構造体に
変換し、そのリファレンスを返す。リストコンテキストでこの関数を
呼び出すと、その構造体が演奏に要するティックの総数（時間的に最後の項目の
終了時間）を返す。

=item $ticks = MIDI::Score::score_r_time( $score_r )

This takes a I<reference> to a score structure, and returns
a count of the number of ticks that structure takes to play
(i.e., the end-time of the temporally last item).

この関数はスコア構造体へのリファレンスを引数にとり、その構造体が
演奏に要するティックの総数（時間的に最後の項目の終了時間）を返す。

=item MIDI::Score::dump_score( $score_r )

This dumps (via C<print>) a text representation of the contents of
the event structure you pass a reference to.

この関数は（C<print>を通じて）リファレンス先のイベント構造体
[訳補足：スコア構造体の間違い？]の中身をテキスト表記でダンプする。

=back

=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>
