1Beep(3)               User Contributed Perl Documentation              Beep(3)
2
3
4

NAME

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

SYNOPSIS

9           #functional simple way
10           use Audio::Beep;
11
12           beep($freq, $milliseconds);
13
14           #OO more musical way
15           use Audio::Beep;
16
17           my $beeper = Audio::Beep->new();
18
19                       # lilypond subset syntax accepted
20                       # relative notation is the default
21                       # (now correctly implemented)
22           my $music = "g' f bes' c8 f d4 c8 f d4 bes c g f2";
23                       # Pictures at an Exhibition by Modest Mussorgsky
24
25           $beeper->play( $music );
26

USAGE

28   Exported Functions
29       beep([FREQUENCY], [DURATION]);
30           Plays a customizable beep out of your computer beeper.
31
32           FREQUENCY is in Hz. Defaults to 440.
33
34           DURATION is in milliseconds. Defaults to 100.
35
36   OO Methods
37       Audio::Beep->new([%options])
38           Returns a new "beeper" object.  Follow the available options for
39           the "new" method to be passed in hash fashion.
40
41       player => [player object | player module]
42               You are free to initialize your player object and then give it
43               to the Audio::Beep object.  Player objects come from
44               Audio::Beep submodules (like "Audio::Beep::Linux::beep").  If
45               you're lazy (as any good programmer should be) you can pass a
46               string as a player, like "Audio::Beep::Linux::PP" or even just
47               "Linux::PP": the method will prepend the "Audio::Beep"
48               namespace, require the module and call the "new" method on it
49               for you.  The "new" method will try to look up the best player
50               on your platform if you don't specify one.  So the following is
51               all valid:
52
53                   use Audio::Beep;
54
55                   #super lazy (should do the right thing most of the time)
56                   my $beeper = Audio::Beep->new();
57
58                   #still lazy
59                   my $beeper2 = Audio::Beep->new(player => 'Linux::PP');
60
61                   #medium lazy
62                   my $beeper3 = Audio::Beep->new(
63                       player  => 'Audio::Beep::Win32::API'
64                   );
65
66                   #not so lazy, but more versatile
67                   require Audio::Beep::Linux::beep;
68                   my $beeper4 = Audio::Beep->new(
69                       player  => Audio::Beep::Linux::beep->new(
70                           path    =>  '/home/foo/bin/beep'
71                       )
72                   );
73
74       rest => [ms]
75               Sets the rest in milliseconds between every sound played (and
76               even pause). This is useful for users which computer beeper has
77               problems and would just stick to the first sound played.  For
78               example on my PowerbookG3 i have to set this around 120
79               milliseconds.  In that way i can still hear some music.
80               Otherwise is just a long single beep.
81
82       $beeper->play( $music )
83           Plays the "music" written in $music.  The accepted format is a
84           subset of <http://lilypond.org> syntax.  The string is a space
85           separated list of notes to play.  See the "NOTATION" section below
86           for more info.
87
88       $beeper->player( [player] )
89           Sets the player object that will be used to play your music.  See
90           the player option above at the "new" method for more info.  With no
91           parameter it just gives you back the current player.
92
93       $beeper->rest( [ms] )
94           Sets the extra rest between each note.  See the rest option above
95           at the "new" method for more info.  With no parameter it gives you
96           back the current rest.
97

NOTATION

99       The defaults at start are middle octave C and a quarter length.
100       Standard notation is the relative notation.  Here is an explanation
101       from Lilypond documentation:
102
103           If no octave changing marks are used, the basic interval between
104           this and the last note is always taken to be a fourth or less
105           (This distance is determined without regarding alterations;
106           a fisis following a ceses will be put above the ceses)
107
108           The octave changing marks ' and , can be added to raise or lower
109           the pitch by an extra octave.
110
111       You can switch from relative to non relative notation (in which you
112       specify for every note the octave) using the "\norel" and "\rel"
113       commands (see below)
114
115   Notes
116       Every note has the following structure:
117
118           [note][flat|sharp][octave][duration][dots]
119
120       NB: previous note duration is used if omitted.  "Flatness", "Sharpness"
121       and "Dottiness" are reset after each note.
122
123       note
124           A note can be any of [c d e f g a b] or [r] for rest.
125
126       flat or sharp
127           A sharp note is produced postponing a "is" to the note itself (like
128           "cis" for a C#).  A flat note is produced adding a "es" or "s" (so
129           "aes" and "as" are both an A flat).
130
131       octave
132           A ' (apostrophe) raise one octave, while a , (comma) lower it.
133
134       duration
135           A duration is expressed with a number.  A 4 is a beat, a 1 is a
136           whole 4/4 measure. Higher the number, shorter the note.
137
138       dots
139           You can add dots after the duration number to add half its length.
140           So a4. is an A note long 1/4 + 1/8 and gis2.. is a G# long 7/8 (1/2
141           + 1/4 + 1/8)
142
143       special note: "r"
144           A r note means a rest. You can still use duration and dots
145           parameters.
146
147   Special Commands
148       Special commands always begin with a "\". They change the behavior of
149       the parser or the music played. Unlike in the Lilypond original syntax,
150       these commands are embedded between notes so they have a slightly
151       different syntax.
152
153       \bpm(\d+)
154           You can use this option  to change the tempo of the music.  The
155           only parameter you can use is a number following the bpm string
156           (like "\bpm144").  BPM stands for Beats Per Minute.  The default is
157           120 BPM.  You can also invoke this command as "\tempo"
158
159       \norel
160           Switches the relative mode off. From here afterward you have to
161           always specify the octave where the note is.
162
163       \rel
164           Switches the relative mode on. This is the default.
165
166       \transpose([',]+)
167           You can transpose all your music up or down some octave.  '
168           (apostrophe) raise octave. , (comma) lowers it. This has effect
169           just if you are in non-relative mode.
170
171   Comments
172       You can embed comments in your music the Perl way. Everything after a #
173       will be ignored until end of line.
174
175   Music Examples
176           my $scale = <<'EOS';
177           \rel \bpm144
178           c d e f g a b c2. r4    # a scale going up
179           c b a g f e d c1        # and then down
180           EOS
181
182           my $music = <<'EOM'; # a Smashing Pumpkins tune
183           \bpm90 \norel \transpose''
184               d8 a, e a, d a, fis16 d a,8
185               d  a, e a, d a, fis16 d a,8
186           EOM
187
188           my $love_will_tear_us_apart = <<'EOLOVE'; # a happier tune
189           \bpm160
190             d'8
191               e1      fis4 g8 fis4 e8 d4
192               b2.. d8 a2..            d8
193               e1      fis4 g8 fis4 e8 d4
194               b2.. d8 a1
195           EOLOVE
196
197       There should be extra examples in the "music" directory of this
198       tarball.
199

EXAMPLES

201        #a louder beep
202        perl -MAudio::Beep -ne 'print and beep(550, 1000) if /ERROR/i' logfile
203
204        #turn your PC in Hofmann mode (courtesy of Thomas Klausner)
205        perl -MAudio::Beep -e 'beep(21 + rand 1000, rand 300) while 1'
206
207        #your new music player
208        perl -mAudio::Beep -0777e 'Audio::Beep->new->play(<>)' musicfile
209

REQUIREMENTS

211   Linux
212       Requires either the beep program by Johnathan Nightingale (you should
213       find sources in this tarball) SUID root or you to be root (that's
214       because we need writing access to the /dev/console device).  If you
215       don't have the beep program this library will also assume some kernel
216       constants which may vary from kernel to kernel (or not, i'm no kernel
217       expert).  Anyway this was tested on a 2.4.20 kernel compiled for i386
218       and it worked with all 2.4 kernel since. It also works with the 2.6
219       kernel series.  With 2.4 kernels i have problems on my PowerBook G3 (it
220       plays a continous single beep). See the "rest" method if you'd like to
221       play something anyway.
222
223   Windows
224       Requires Windows NT, 2000 or XP and the Win32::API module.  You can
225       find sources on CPAN or you can install it using ActiveState ppm.  No
226       support is available for Windows 95, 98 and ME yet: that would require
227       some assembler and an XS module.
228
229   BSD
230       IMPORTANT! This IS NOT TESTED ON BSD! It may work, it may not.  Try it,
231       let me know what you got.  BTW, you need the beep program wrote by
232       Andrew Stevenson.  I found it at
233       <http://www.freshports.org/audio/beep/> , but you can even find it at
234       <http://www.freebsd.org/ports/audio.html>
235

BACKEND

237       If you are a developer interested in having Audio::Beep working on your
238       platform, you should think about writing a backend module.  A backend
239       module for Beep should offer just a couple of methods:
240
241       NB: FREQUENCY is in Hertz. DURATION in milliseconds
242
243       new([%options])
244           This is kinda obvious. Take in the options you like. Keep the hash
245           fashion for parameters, thanks.
246
247       play(FREQUENCY, DURATION)
248           Plays a single sound.
249
250       rest(DURATION)
251           Rests a DURATION amount of time
252

TODO

254       This module works for me, but if someone wants to help here is some
255       cool stuff to do:
256
257       - an XS Windoze backend (look at the Prima project for some useful
258       code)
259
260       - test this on BSD (cause it's not tested yet!)
261

BUGS

263       Some of course.
264
266       Copyright 2003-2004 Giulio Motta giulienk@cpan.org.
267
268       This library is free software; you can redistribute it and/or modify it
269       under the same terms as Perl itself.
270
271
272
273perl v5.12.0                      2004-04-13                           Beep(3)
Impressum