NAME

Audio::Beep - a module to use your computer beeper in fancy ways

IMPORTANT!!!

This module will work just with the GNU/Linux operating system! It 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.

SYNOPSIS

#functional simple way
use Beep;

beep($freq, $milliseconds);

#OO more musical way
use Beep;

my $beeper = Beep->new();

            #lilypond subset syntax accepted
my $music = "g f bes c'8 f d4 c8 f d4 bes, c' g, f2";
            # Pictures at an Exhibition by Modest Mussorgsky

$beeper->play( $music );

USAGE

Exported Functions

beep([FREQUENCY], [DURATION]);

Plays a customizable beep out of your computer beeper.
FREQUENCY is in Hz. Defaults to 440.
DURATION is in milliseconds. Defaults to 100.

OO Methods

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

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

player => [player object]

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). The new method will try to look up the best player on your platform. Still passing the player to the new method is safer (and you can sometimes personalize the player itself).

$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. Every note has the following structure:

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

NB: if some part is missing the settings from the previous note are applied for octave and duration. "Flatness", "Sharpness" and "Dottiness" are reset after each note. The defaults at start are middle octave and a quarter length.

note

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

flat or sharp

A sharp note is produced postponing a "is" to the note itself (like "cis" for a C#). A flat note is produced adding a "es" or "s" (so "aes" and "as" are both an A flat).

octave

The octave setting is always relative to the previous one. A ' (apostrophe) raise one octave, while a , (comma) lower it.

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.

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)

special note: "r"

A r note means a rest. You can still use duration and dots parameters. Flat and sharp will be ignored. Octave will work, changing the octave.

spacial note: "bpm"

You can use a bpm (beats per minute) "note" to change the tempo of the music. The only parameter you can use is a number following the bpm string (like "bpm144"). The default is 120 BPM.

Music Examples

my $music = <<EOM; # a Smashing Pumpkins tune
bpm90   d''8 a, e' a, d' a, fis'16 d a,8
        d'   a, e' a, d' a, fis'16 d a,8
EOM

my $music = <<EOM; # some Bach
    r'8 c16 b c8 g as     c16 b c8 d
    g,  c16 b c8 d f,16 g as4      g16 f
    es4
EOM

$beeper->player( [player] )

Sets the player object that will be used to play your music. With no parameter it just give you back the current player.

EXAMPLES

                 #a louder beep
perl -MBeep -ne 'print and beep(550, 1000) if /ERROR/' somelogfile

BACKEND

A backend module for Beep should offer just a couple of methods: NB: FREQUENCY is in Hertz. DURATION in milliseconds

play(FREQUENCY, DURATION)

Plays a single sound.

rest(DURATION)

Rests a DURATION amount of time

TODO

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

- an XS backend
- an XS Windoze backend (and other OSs)
- a parse method to preparse the input (usefull??)
- with a cool backend we could export a tied filehandle 
  to which it would be possible to write directly from Perl

BUGS

Sure to be plenty.
Produces a ton of crap if warnings are turned on.

COPYRIGHT

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.