=head1 名前

Audio::Beep - 素敵な方法で、コンピュータの警報機を使うモジュール

=head1 概要

    #関数的な簡単なやりかた
    use Audio::Beep;

    beep($freq, $milliseconds);

    #オブジェクト指向的なより音楽的なやりかた
    use Audio::Beep;

    my $beeper = Audio::Beep->new();
    
                # lilypond サブセット文法が受け入れられます。
                # 相対的な記法がデフォルトです。
                # (今現在実装されています)
    my $music = "g' f bes' c8 f d4 c8 f d4 bes c g f2";
                # モデスト・ムソルグスキーの「展覧会の絵」

    $beeper->play( $music );
    
=head1 使用法

=head2 export される関数

=over 4

=item beep([FREQUENCY], [DURATION]);

Plays a customizable beep out of your computer beeper.

カスタマイズできるビープ音を、コンピュータの警報機で再生します。

FREQUENCY is in Hz. Defaults to 440.

FREQUENCY は、Hz で、デフォルトは、440です。

DURATION is in milliseconds. Defaults to 100.

DURATION は、ミリ秒で、デフォルトは100です。

=back

=head2 オブジェクト指向メソッド

=over 4

=item Audio::Beep->new([%options])

Returns a new "beeper" object.  Follows the available
options for the new method to be passed in hash fashion.

新しい"beeper" オブジェクトを返します。
new メソッドには、下記のオプションがハッシュのかたちで渡されます。

=back

=over 8

=item player => [player object | player module]

You can initialize your player object and then give it to the 
Audio::Beep object.
Player objects come from Audio::Beep submodules (like
Audio::Beep::Linux::beep). 

演奏オブジェクトを初期化でき、それから、
Audio::Beep オブジェクトに、演奏オブジェクトを渡せます。
演奏オブジェクトは Audio::Beep サブモジュール(Audio::Beep::Linux::Beepのような)からもたらされます。

If you're lazy (as any good programmer should be) 
you can give a string as a player,
like C<"Audio::Beep::Linux::PP"> or even just C<"Linux::PP">: the method
will prepend the C<Audio::Beep> namespace, require the module and call
the new method on it for you.
The new method will try to look up the best player
on your platform if you don't specify one.
So the following is all valid:

もし、あなたが怠惰なら(どんなよいプログラマはそうあるべきように)、player として、
C<"Audio::Beep::Linux::PP">か、ただ、C<"Linux::PP">のような文字列をあたえることができます:
メソッドはC<"Audio::Beep">名前空間を先頭に付け加え(訳註：prepend)し、
そのモジュールを require し、new メソッドをその上で呼び出します。

    use Audio::Beep;
    
    #とても怠惰 (通常、正しいことを行うべきです)
    my $beeper = Audio::Beep->new();
    
    #まだ怠惰。
    my $beeper2 = Audio::Beep->new(player => 'Linux::PP');

    #なかなか怠惰。
    my $beeper3 = Audio::Beep->new(
        player  => 'Audio::Beep::Win32::API'
    );

    #怠惰じゃないが、より可変性がある。
    require Audio::Beep::Linux::beep;
    my $beeper4 = Audio::Beep->new(
        player  => Audio::Beep::Linux::beep->new(
            path    =>  '/home/foo/bin/beep/'
        )
    );


=item rest => [ms]

Sets the rest in milliseconds between every sound played (and
even pause). This is useful for users which computer beeper has problems
and would just stick to the first sound played.
For example on my PowerbookG3 i have to set this around 120 milliseconds.
In that way i can still hear some music. Otherwise is just a long single beep.

演奏されるサウンド(とポーズ)ごとに、ミリ秒の休憩をセットします。
このことは、問題のあるコンピュータの警報機のユーザ - 
演奏される最初の音を突き刺すような - にとって、有益です。
たとえば、私の PowerbookGCで は、120ミリ秒あたりをセットしなければなりません。
このようにすれば、まだ、音楽を聞くことができます。
さもなくば、長い単一のビープになります。

=back

=over 4

=item $beeper->play( $music )

Plays the "music" written in $music.
The accepted format is a subset of lilypond.org syntax.
The string is a space separated list of notes to play.
See the NOTATION section below for more info.

$music にかかれた"音楽"を演奏します。
受け入れるフォーマットは lilypond.org の文法のサブセットです。
文字列はスペースで分割された演奏する音符のリストです。
詳しくは、後述の記法のセクションを見て下さい。

=item $beeper->player( [player] )

Sets the player object that will be used to play your music.
See the player option above at the C<new> method for more info.
With no parameter it just gives you back the current player.

音楽を演奏するのに使った演奏オブジェクトをセットします。
詳しくは、上述のC<new>メソッドの player オプションを見て下さい。
パラメータをあたえなければ、現在の player を戻します。

=item $beeper->rest( [ms] )

Sets the extra rest between each note. 
See the rest option above at the C<new> method for more info.
With no parameter it gives you back the current rest.

それぞれの音符の間に特別の休憩をセットします。
詳しくは、上述のC<new>メソッドの rest オプションを見て下さい。
パラメータをあたえなければ、現在の rest を戻します。

=back

=head1 記法

The defaults at start are middle octave C and a quarter length.
Standard notation is the relative notation. 
Here is an explanation from Lilypond documentation:

最初のデフォルトは、中間のオクターブのドで、1/4長です。
標準の記法は相対的な記法です。Lilypond ドキュメントにある説明です；

    If no octave changing marks are used, the basic interval between 
    this and the last note is always taken to be a fourth or less 
    (This distance is determined without regarding alterations; 
    a fisis following a ceses will be put above the ceses)

    もし、オクターブを変更するマークが使われなければ、
    これと最後の音符の間の基本的な間隔は常に1/4かより少なくなります。
    (この間隔は変更に注意せずに決定されます；
    a fisis following a ceses will be put above the ceses)

    The octave changing marks ' and , can be added to raise or lower 
    the pitch by an extra octave.

    オクターブを変更するマークは ' で、特別なオクターブでピッチをあげたり下げたり
    できます。

You can switch from relative to non relative notation (in which you specify for
every note the octave) using the C<\norel> and C<\rel> commands (see below)

C<\norel>と、C<\rel> コマンド(後述)を使って、相対から相対でない記法にスイッチできます
(音符ごとにオクターブを特定します)。

=head2 音符

Every note has the following structure:

全ての音符には下記の構造があります。

    [note][flat|sharp][octave][duration][dots]

    [音符][フラット|シャープ][オクターブ][長さ][ドット]

NB: previous note duration is used if omitted.
"Flatness", "Sharpness" and "Dottiness" are reset after each note. 

注意：省略されると前の音符の持続時間が使われます。
"Flatness"と、"Sharpness"と、"Dottiness" は、音符ごとにリセットされます。

=over 4

=item note

A note can be any of [c d e f g a b] or [r] for rest.

音符は[c d e f g a b] か、休符の[r] のどれかです。

=item flat or sharp

A sharp note is produced postponing a "is" to the note itself 
(like "cis" for a C#).

シャープの音符は、"is"を音符の後に置くことで、作れます。
(C#のために、"cis"のようにします)

A flat note is produced adding a "es" or "s" 
(so "aes" and "as" are both an A flat).

フラットの音符は、"es"か、"s"を音符の後に置くことで、作れます。
("aes"と、"as"は、どちらもAフラットです)

=item octave

A ' (apostrophe) raise one octave, while a , (comma) lower it.

'(アポストロフィ) は、オクターブをひとつあげます。
一方、,(カンマ)は、オクターブをひとつ下げます。

=item duration

A duration is expressed with a number. 
A 4 is a beat, a 1 is a whole 4/4 measure. Higher the number, shorter the note.

duration は、数字で表します。
4 は、ビートで、1 は、まったく4/4の長さです。
数字が高ければ高いほど、音符は短くなります。

=item dots

You can add dots after the duration number to add half its length. 
So a4. is an A note long 1/4 + 1/8 and gis2.. is a G# long 7/8 (1/2 + 1/4 + 1/8)

durationの数字の後に、ドットを加えることができ、その長さの半分を加えることができます。
a4. でしたら、ラの 1/4 + 1/8 の長さの音符ですし、gis2 は、ソ# 8/7(1/2 + 1/4 + 1/8)の長さです。
 
=item 特記: "r"

A r note means a rest. You can still use duration and dots parameters. 

r 音符は、休符を意味します。duration と、dots のパラメタを使うことができます。

=back

=head2 特別なコマンド

Special commands always begin with a "\". They change the behavior of the
parser or the music played. Unlike in the Lilypond original syntax, these
commands are embedded between notes so they have a slightly different syntax.

特別なコマンドは常に、"\" で始まります。
パーサか、演奏される音楽の振る舞いを変更します。Lilypondのオリジナルの文法とは違って、
これらのコマンドは音符の間に埋め込まれます。それで、少々違った文法になっています。

=over 4

=item \bpm(\d+)

You can use this option  to change the tempo of the music.
The only parameter you can use is a number following the bpm string 
(like "bpm144").  
BPM stands for Beats Per Minute.
The default is 120 BPM.
You can also invoke this command as C<\tempo>

このオプションを使って、音楽のテンポを変更できます。
使うパラメタは、bpmの後に数字が続く文字列です("bpm144"のような)。
BPM は、Beats Per Minute を意味します。デフォルトは 120 BPM です。
C<\tempo> のようなコマンドで、呼び出すこともできます。

=item \norel

Switches the relative mode off. From here afterward you have to always specify
the octave where the note is.

相対モードをオフにするスイッチです。
ここから後は、いつも、音符がある場所のオクターブを特定する必要があります。

=item \rel

Switches the relative mode on. This is the default.

相対モードをオンにするスイッチです。これはデフォルトです。

=item \transpose([',]+)

You can transpose all your music up or down some octave. 
' (apostrophe) raise octave. , (comma) lowers it. This has effect just
if you are in non-relative mode.

全ての音楽のオクターブをいくつか上げるか下げるか置き換えます。
'(アポストロフィ)はオクターブを上げます。,(comma)はオクターブを下げます。
相対モードでないモードでだけ、これは効果があります。

=back

=head2 コメント

You can embed comments in your music the Perl way. Everything after a #
will be ignored until end of file

音楽にPerlの方法でコメントを埋め込めます。
ファイルの最後まで、#の後の全てのものは無視されます。

=head2 音楽の例

    my $scale = <<'EOS';
    \rel \bpm144
    c d e f g a b c2. r4    # a scale going up
    c b a g f e d c1        # and then down
    EOS

    my $music = <<'EOM'; # a Smashing Pumpkins tune
    \bpm90 \norel \transpose''
        d8 a, e a, d a, fis16 d a,8
        d  a, e a, d a, fis16 d a,8
    EOM

    my $love_will_tear_us_apart = <<'EOLOVE'; # a happier tune
    \bpm160
      d'8 
        e1      fis4 g8 fis4 e8 d4
        b2.. d8 a2..            d8
        e1      fis4 g8 fis4 e8 d4
        b2.. d8 a1
    EOLOVE


There should be extra examples in the "music" directory of this tarball.

tarballの"music"ディレクトリに、特別な例があるでしょう。

=head1 例

 #大きなビープ
 perl -MAudio::Beep -ne 'print and beep(550, 1000) if /ERROR/i' logfile

 # PCをホフマンモードにする (courtesy of Thomas Klausner)
 perl -MAudio::Beep -e 'beep(21 + rand 1000, rand 300) while 1'

 #あなたの新しいミュージックプレイヤー
 perl -mAudio::Beep -0777e 'Audio::Beep->new->play(<>)' musicfile

=head1 必要条件

=head2 Linux

Requires either the "beep" program by Johnathan Nightingale 
(you should find sources in this tarball) SUID root or you to be root (that's
because we need writing access to the /dev/console device).
If you don't have the "beep" program this library will also assume some kernel
constants which may vary from kernel to kernel (or not, i'm no kernel expert).
Anyway this was tested on a 2.4.20 kernel compiled for i386.
With the same kernel i have problems on my PowerBook G3 (it plays a continous
single beep). See the C<rest> method if you'd like to play something anyway.

Johnathan Nightingale による、"beep"プログラム
(tarballのソースで見つけるはずです)を必要とします。
rootにSUIDするか、rootになる必要があります
(/dev/consoleデバイスに書き込みアクセスする必要があるからです)。
"beep"プログラムがなければ、このライブラリは、
kernelからkernelに変えるいくつかのkernel定数を想定します
(違うかもしれない。私はkernelエキスパートではないので)。
とにかく、このモジュールは、i386用にコンパイルされた2.4.20 kernel でテストされています。
同じkernelで私のPowerBook G3に問題があります(単一のbeepを連続して演奏します)。
とにかく、何かを演奏したい場合は、C<rest>メソッドを見て下さい。

=head2 Windows

Requires Windows NT, 2000 or XP and the Win32::API module. 
You can find sources on CPAN. 
Some PPM precompiled packages are at http://dada.perl.it/PPM/
No support is available for Windows 95, 98 and ME yet:
that would require some assembler and an XS module.

Windows NT か 2000 か XP と、Win32::APIモジュールを必要とします。
CPANでソースを見付けることができます。
プリコンパイルされたパッケージはhttp://data.perl.it/RPM/ にあります。
Window 95, 98, ME は、まだ、サポートしていません:
それはアセンブラと、XSモジュールを必要とします。

=head1 バックエンド

If you are a developer interested in having Audio::Beep working on your
platform, you should think about writing a backend module.
A backend module for Beep should offer just a couple of methods:

Audio::Beepを自分のプラットフォームで動かせるのに関心のある開発者なら、
バックエンドモジュールを書くことについて考えるべきです。
Beepのための、バックエンドモジュールは1組のメソッドを提供すべきです:

NB: FREQUENCY is in Hertz. DURATION in milliseconds

注意:FREQUENCY は、ヘルツであり、DURATIONは、ミリ秒です。

=over 4

=item new([%options])

This is kinda obvious. Take in the options you like. Keep the hash fashion
for parameters, thanks.

これはある程度自明です。お好みならオプションを入れて下さい。
パラメータはハッシュの形式です。よろしく。

=item play(FREQUENCY, DURATION)

Plays a single sound.

単一の音を演奏します。

=item rest(DURATION)

Rests a DURATION amount of time

DURATIONの時間、休止させます。

=back

=head1 TODO

This module works for me, but if someone wants to help here is some cool stuff
to do:

このモジュールは、私のために働きます。ですが、助けてくださるなら、
やるべき、cool stuff があります:

- an XS backend

- an XS Windoze backend (look at the Prima project for some useful code)

- some work is needed on Windows Makefile part

=head1 バグ

もちろん、いくつかは。

=head1 著作権

(原文まま)

Copyright 2003 Giulio Motta <giulienk@cpan.org>.

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

=head1 翻訳について

翻訳者：加藤敦 (atusi@pure.ne.jp)

Perlドキュメント日本語訳 Project にて、
Perlモジュール、ドキュメントの翻訳を行っております。

 http://perldocjp.sourceforge.jp
 http://sourceforge.jp/projects/perldocjp/
 http://freeml.com/ctrl/html/MLInfoForm/perldocjp@freeml.com
 http://www.perldoc.jp
