1BEEP(1) User commands BEEP(1)
2
6 beep - beep the pc speaker any number of ways
7
9 beep [GLOBALS] [-f FREQ] [-l LEN] [-r REPEATS] [<-d|-D> DELAY] [-s]
10 [-c]
11 beep [GLOBALS] <TONE_OPTIONS> [-n|--new] <TONE_OPTIONS>
12 beep <-h|--help>
13 beep <-v|-V|--version>
14
16 beep allows the user to control the PC speaker with precision, allowing
17 different sounds to indicate different events. While beep can be run
18 quite happily on the command line, beep's intended use is within
19 shell/perl scripts, notifying the user when something interesting oc‐
20 curs. Of course, it has no notion of what IS interesting, but it is
21 good at the notifying part.
22 All options have default values, meaning that just typing 'beep' will
24 work. If an option is specified more than once on the command line,
25 subsequent options override their predecessors. So 'beep -f 200 -f
26 300' will beep at 300Hz.
27 All durations are given in a unit of milliseconds, frequencies as
29 Hertz, and the number of repeats is a dimensionless number.
30
32 Global options
33 -e DEVICE, --device=DEVICE
34 Explicitly set the device beep shall use to generate beep tones.
35 When not given a device explicitly, beep runs through an inter‐
36 nal list of devices until one appears to work.
37 --debug, --verbose
39 Make the beep program more verbose.
40 Tone options
42 -f FREQ
43 Beep with a tone frequency of FREQ Hz, where 0 < FREQ < 20000.
44 As a general ballpark, the regular terminal beep is around
45 750Hz. For backwards compatibility, you can give FREQ as a
46 floating point number, but beep will round that to integer val‐
47 ues as the kernel APIs expect them. Default value: 440 Hz.
48 -l LEN Beep for a tone length of LEN milliseconds. Default value: 200
50 ms.
51 -r REPEATS
53 Repeat the tone including delays REPEATS times. Default value: 1
54 tone, not repeated.
55 -d DELAY | -D DELAY
57 Specify a delay of DELAY milliseconds between repetitions.
58 Small letter -d specifies that this delay should only occur be‐
59 tween beeps, that is, it should not occur after the last repeti‐
60 tion. Capital letter -D specifies that the delay should occur
61 after every repetition, including after the last one. Normally,
62 -d is what you want, but if, for example, you are stringing sev‐
63 eral beep commands together to play the star wars anthem, you
64 may want control over every delay. Default value: 100 ms delay
65 between beeps with no delay after the last beep.
66 -n, --new
68 The --new option allows you to chain multiple beeps together on
69 a single command line. Each time the --new is used, beep starts
70 treating all further arguments as though they were for a new
71 beep. So for example:
72 beep -f 1000 -n -f 2000 -n -f 1500
74 would produce a sequence of three beeps, the first with a fre‐
76 quency of 1000Hz (and otherwise default values), then a second
77 beep with a frequency of 2000Hz (again, with things like delay
78 and reps being set to their defaults), then a third beep, at
79 1500Hz. This is different from specifying a -r value, since -r
80 repeats the same beep multiple times, whereas --new allows you
81 to specify different beeps. After a --new, the new beep is cre‐
82 ated with all the default values, and any of these can be speci‐
83 fied without altering values for preceding (or later) beeps.
84 See the EXAMPLES section if this managed to confuse you.
85 -s, -c Both the -s and the -c option put beep into input processing
87 mode, reading from stdin and copying all received data to std‐
88 out. This makes it easy to slip beep into a text processing
89 pipeline to acoustically monitor the data flow within that pipe‐
90 line. See the EXAMPLES section.
91 -c Beep after every character received.
93 -s Beep after every set of data received. Usually, this
95 means after newlines occur in text processing pipes.
96 In a sequence of notes specified with one or more occurrences of
98 -n or --new, it only makes sense to have one single note marked
99 with either -s or -c attached to it. Then beep will beep all
100 notes until it reaches that marked note, then repeat the marked
101 note according to the input it receives, and once the input has
102 reached EOF, beep will continue with the remainder of the note
103 sequence.
104 The behaviour of beep with more than one note marked with -s or
106 -c is undefined.
107 Other Actions
109 -h, --help Display beep usage info and exit.
110 -v, -V, --version
112 Display beep version information and exit.
113
115 When successful, beep returns with exit code 0.
116 Any non-0 exit code means beep has encountered an error and has bailed
118 out.
119
121 BEEP_LOG_LEVEL
122 When set to a number between -999 and 999, BEEP_LOG_LEVEL will
123 be used as the default loglevel until overridden by a command
124 line parameter.
125
127 The device files beep uses by default are the following:
128 /dev/input/by-path/platform-pcspkr-event-spkr
129 /dev/tty0
130 /dev/vc/0
131
133 Devices and Permissions
134 When you run beep without explicitly giving a device to use, beep tries
135 opening the following devices in sequence until one succeeds:
136 /dev/input/by-path/platform-pcspkr-event-spkr
138 Uses the evdev API, and system administrator can allow access to
139 any set of users and groups using the normal file permissions.
140 /dev/tty0
142 Uses the console API, and the kernel insists you are root or own
143 the TTY.
144 /dev/vc/0
146 Uses the console API, and the kernel insists you are root or own
147 the TTY.
148 beep does not support running as setuid root or via sudo(1).
150 For non-root uses, the system administrator can set up a udev(7) rule
152 to allow write access to /dev/input/by-path/platform-pcspkr-event-spkr
153 for certain users and/or user groups. For details, see the beep
154 /usr/share/doc/beep/PERMISSIONS.md file.
155 APIs
157 evdev
158 Uses the input event device driver, which means running write(2) on
159 /dev/input/by-path/platform-pcspkr-event-spkr.
160 The permissions to this device file can be set up such that beep
162 can be run by any non-root user the system administrator wants to.
163 Opening this device takes on the order of magnitude of 20ms in the
165 Linux kernel for every time you start the beep command. Therefore,
166 if you need to play multiple notes in a rhythmical sequence for a
167 melody, use one beep command invocation with multiple notes, not
168 several beep invocations playing one note each.
169 console
171 Uses the ancient console API, which means running the KIOCSOUND
172 ioctl(2) on a tty device like /dev/tty0 or /dev/vc/0.
173 This requires being root, unless the non-root user happens be
175 logged into the virtual console and be using that specific virtual
176 console device like e.g. /dev/tty4. This makes the console driver
177 useless for non-root users logged in via ssh, and often X11 or Way‐
178 land.
179 Use the evdev API instead.
181 Concurrent Invocations
183 Concurrent invocations of beep are not supported. There is only one
184 tone generator in the PC hardware, and we do not manage access to that
185 shared resource in any way. So if a first beep -f 1000 -l 10000
186 process starts a long 10 second beep with 1000Hz, and 2 seconds later a
187 second quick beep -f 2050 -l 100 with 2050Hz comes in, you will hear
188 that 2050Hz beep for 100ms, and then silence as the quick beep silences
189 the tone generator. Now you will not hear that the first beep process
190 is still running after having waited for the first 2100ms of its
191 10000ms. You will also not hear that the first beep process will si‐
192 lence the already silent speaker 7900ms later, i.e. 10000ms after the
193 first beep started.
194 Sound Volume
196 The PC speaker hardware has no way to explicitly set the volume of a
197 beep.
198 If you have a standalone PC, however, chances are you have a piezo
200 beeper connected to the mainboard. If you prioritize a loud beep over
201 a certain frequency beep, you can choose to beep at a frequency close
202 to the resonance frequency of the piezo beeper. Typical piezo beepers
203 have a resonance frequency around 2000Hz, so you can test frequencies
204 around that range. The author's piezo beeper is the loudest at about
205 2050Hz.
206 If you have a PC laptop, chances are that your laptop will not have a
208 piezo beeper hardware inside and that it will route the output of the
209 pcspkr circuit to the laptop's internal speakers via the sound card
210 mixer. In that case, you can and/or must change the mixer level for
211 the beeper using a sound card mixer application.
212 Frequency Table
214 This frequency table might come in handy for translating musical notes
215 to frequencies. The frequencies are rounded to integer numbers as the
216 kernel driver only works with integers. The column for octave 4 is the
217 octave of middle C.
218 ┌─────┬─────────────────────────┐
220 │note │ octave │
221 │name │ 3 4 5 6 │
222 ├─────├─────────────────────────┤
223 │ C │ 131 262 523 1047 │
224 │ C# │ 139 277 554 1109 │
225 │ D │ 147 294 587 1175 │
226 │ D# │ 156 311 622 1245 │
227 │ E │ 165 330 659 1319 │
228 │ F │ 175 349 698 1397 │
229 │ F# │ 185 370 740 1480 │
230 │ G │ 196 392 784 1568 │
231 │ G# │ 208 415 831 1661 │
232 │ A │ 220 440 880 1760 │
233 │ A# │ 233 466 932 1865 │
234 │ B │ 247 494 988 1976 │
235 │ C │ 262 523 1047 2093 │
236 └─────┴─────────────────────────┘
238 Report bugs to ⟨https://github.com/spkr-beep/beep/issues⟩.
239
241 At its simplest (yet still effective)
242 beep
244 A more interesting standalone setup
246 beep -f 300.7 -r 2 -d 100 -l 400
248 As part of a log watching pipeline
250 tail -f /var/log/xferlog | grep 'passwd' | beep -f 1000 -r 5 -s
252 When using -c mode, I recommend using a short -D, and a shorter -l, so
254 that the beeps do not blur together. Something like this will get you
255 a cheesy 1970's style beep-as-you-type-each-letter effect
256 cat file | beep -c -f 400 -D 50 -l 10
258 A highly contrived example of -n/--new usage
260 beep -f 1000 -r 2 -n -r 5 -l 10 --new
262 will produce first two 1000Hz beeps, then 5 beeps at the default tone,
264 but only 10ms long each, followed by a third beep using all the default
265 settings (since none are specified).
266
268 /usr/share/doc/beep/README.fedora, /usr/share/doc/beep/README.md,
269 /usr/share/doc/beep/PERMISSIONS.md, ⟨https://github.com/spkr-beep/beep⟩
270Linux 2020-01-01 BEEP(1)