1Beep(3) User Contributed Perl Documentation Beep(3)
2
6 Audio::Beep - a module to use your computer beeper in fancy ways
7
9 #functional simple way
10 use Audio::Beep;
11 beep($freq, $milliseconds);
13 #OO more musical way
15 use Audio::Beep;
16 my $beeper = Audio::Beep->new();
18 # 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 $beeper->play( $music );
26
28 Exported Functions
29 beep([FREQUENCY], [DURATION]);
30 Plays a customizable beep out of your computer beeper.
31 FREQUENCY is in Hz. Defaults to 440.
33 DURATION is in milliseconds. Defaults to 100.
35 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 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 use Audio::Beep;
54 #super lazy (should do the right thing most of the time)
56 my $beeper = Audio::Beep->new();
57 #still lazy
59 my $beeper2 = Audio::Beep->new(player => 'Linux::PP');
60 #medium lazy
62 my $beeper3 = Audio::Beep->new(
63 player => 'Audio::Beep::Win32::API'
64 );
65 #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 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 $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 $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 $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
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 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 The octave changing marks ' and , can be added to raise or lower
109 the pitch by an extra octave.
110 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 Notes
116 Every note has the following structure:
117 [note][flat|sharp][octave][duration][dots]
119 NB: previous note duration is used if omitted. "Flatness", "Sharpness"
121 and "Dottiness" are reset after each note.
122 note
124 A note can be any of [c d e f g a b] or [r] for rest.
125 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 octave
132 A ' (apostrophe) raise one octave, while a , (comma) lower it.
133 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 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 special note: "r"
144 A r note means a rest. You can still use duration and dots
145 parameters.
146 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 \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 \norel
160 Switches the relative mode off. From here afterward you have to
161 always specify the octave where the note is.
162 \rel
164 Switches the relative mode on. This is the default.
165 \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 Comments
172 You can embed comments in your music the Perl way. Everything after a #
173 will be ignored until end of line.
174 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 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 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 There should be extra examples in the "music" directory of this
198 tarball.
199
201 #a louder beep
202 perl -MAudio::Beep -ne 'print and beep(550, 1000) if /ERROR/i' logfile
203 #turn your PC in Hofmann mode (courtesy of Thomas Klausner)
205 perl -MAudio::Beep -e 'beep(21 + rand 1000, rand 300) while 1'
206 #your new music player
208 perl -mAudio::Beep -0777e 'Audio::Beep->new->play(<>)' musicfile
209
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 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 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
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 NB: FREQUENCY is in Hertz. DURATION in milliseconds
242 new([%options])
244 This is kinda obvious. Take in the options you like. Keep the hash
245 fashion for parameters, thanks.
246 play(FREQUENCY, DURATION)
248 Plays a single sound.
249 rest(DURATION)
251 Rests a DURATION amount of time
252
254 This module works for me, but if someone wants to help here is some
255 cool stuff to do:
256 - an XS Windoze backend (look at the Prima project for some useful
258 code)
259 - test this on BSD (cause it's not tested yet!)
261
263 Some of course.
264
266 Copyright 2003-2004 Giulio Motta giulienk@cpan.org.
267 This library is free software; you can redistribute it and/or modify it
269 under the same terms as Perl itself.
270perl v5.12.0 2004-04-13 Beep(3)