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
20 occurs. 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.
48 -l LEN Beep for a tone length of LEN milliseconds.
50 -r REPEATS
52 Repeat the tone including delays REPEATS times (defaults to 1).
53 -d DELAY | -D DELAY
55 Specify a delay of DELAY milliseconds between repetitions.
56 Small letter -d specifies that this delay should only occur
57 between beeps, that is, it should not occur after the last repe‐
58 tition. Capital letter -D specifies that the delay should occur
59 after every repetition, including the last one. Normally, -d is
60 what you want, but if, for example, you are stringing several
61 beep commands together to play the star wars anthem, you may
62 want control over every delay.
63 -n, --new
65 The --new option allows you to chain multiple beeps together on
66 a single command line. Each time the --new is used, beep starts
67 treating all further arguments as though they were for a new
68 beep. So for example:
69 beep -f 1000 -n -f 2000 -n -f 1500
71 would produce a sequence of three beeps, the first with a fre‐
73 quency of 1000Hz (and otherwise default values), then a second
74 beep with a frequency of 2000Hz (again, with things like delay
75 and reps being set to their defaults), then a third beep, at
76 1500Hz. This is different from specifying a -r value, since -r
77 repeats the same beep multiple times, whereas --new allows you
78 to specify different beeps. After a --new, the new beep is cre‐
79 ated with all the default values, and any of these can be speci‐
80 fied without altering values for preceding (or later) beeps.
81 See the EXAMPLES section if this managed to confuse you.
82 -s, -c Both the -s and the -c option put beep into input processing
84 mode, reading from stdin and copying all received data to std‐
85 out. This makes it easy to slip beep into a text processing
86 pipeline to acoustically monitor the data flow within that pipe‐
87 line. See the EXAMPLES section.
88 -c Beep after every character received.
90 -s Beep after every set of data received. Usually, this
92 means after newlines occur in text processing pipes.
93 In a sequence of notes specified with one or more occurrences of
95 -n or --new, it only makes sense to have one single note marked
96 with either -s or -c attached to it. Then beep will beep all
97 notes until it reaches that marked note, then repeat the marked
98 note according to the input it receives, and once the input has
99 reached EOF, beep will continue with the remainder of the note
100 sequence.
101 The behaviour of beep with more than one note marked with -s or
103 -c is undefined.
104 Other Actions
106 -h, --help Display beep usage info and exit.
107 -v, -V, --version
109 Display beep version information and exit.
110
112 When successful, beep returns with exit code 0.
113 Any non-0 exit code means beep has encountered an error and has bailed
115 out.
116
118 BEEP_LOG_LEVEL
119 When set to a number between -999 and 999, BEEP_LOG_LEVEL will
120 be used as the default loglevel until overridden by a command
121 line parameter.
122
124 The device files beep uses by default are the following:
125 /dev/input/by-path/platform-pcspkr-event-spkr
126 /dev/tty0
127 /dev/vc/0
128
130 Devices and Permissions
131 When you run beep without explicitly giving a device to use, beep tries
132 opening the following devices in sequence until one succeeds:
133 /dev/input/by-path/platform-pcspkr-event-spkr
135 Uses the evdev API, and system administrator can allow access to
136 any set of users and groups using the normal file permissions.
137 /dev/tty0
139 Uses the console API, and the kernel insists you are root or own
140 the TTY.
141 /dev/vc/0
143 Uses the console API, and the kernel insists you are root or own
144 the TTY.
145 beep does not support running as setuid root or via sudo(1).
147 For non-root uses, the system administrator can set up a udev(7) rule
149 to allow write access to /dev/input/by-path/platform-pcspkr-event-spkr
150 for certain users and/or user groups. For details, see the beep
151 /usr/share/doc/beep/PERMISSIONS.md file.
152 APIs
154 evdev
155 Uses the input event device driver, which means running write(2) on
156 /dev/input/by-path/platform-pcspkr-event-spkr.
157 The permissions to this device file can be set up such that beep
159 can be run by any non-root user the system administrator wants to.
160 Opening this device takes on the order of magnitude of 20ms in the
162 Linux kernel for every time you start the beep command. Therefore,
163 if you need to play multiple notes in a rhythmical sequence for a
164 melody, use one beep command invocation with multiple notes, not
165 several beep invocations playing one note each.
166 console
168 Uses the ancient console API, which means running the KIOCSOUND
169 ioctl(2) on a tty device like /dev/tty0 or /dev/vc/0.
170 This requires being root, unless the non-root user happens be
172 logged into the virtual console and be using that specific virtual
173 console device like e.g. /dev/tty4. This makes the console driver
174 useless for non-root users logged in via ssh, and often X11 or Way‐
175 land.
176 Use the evdev API instead.
178 Concurrent Invocations
180 Concurrent invocations of beep are not supported. There is only one
181 tone generator in the PC hardware, and we do not manage access to that
182 shared resource in any way. So if a first beep -f 1000 -l 10000
183 process starts a long 10 second beep with 1000Hz, and 2 seconds later a
184 second quick beep -f 2050 -l 100 with 2050Hz comes in, you will hear
185 that 2050Hz beep for 100ms, and then silence as the quick beep silences
186 the tone generator. Now you will not hear that the first beep process
187 is still running after having waited for the first 2100ms of its
188 10000ms. You will also not hear that the first beep process will
189 silence the already silent speaker 7900ms later, i.e. 10000ms after the
190 first beep started.
191 Sound Volume
193 The PC speaker hardware has no way to explicitly set the volume of a
194 beep.
195 If you have a standalone PC, however, chances are you have a piezo
197 beeper connected to the mainboard. If you prioritize a loud beep over
198 a certain frequency beep, you can choose to beep at a frequency close
199 to the resonance frequency of the piezo beeper. Typical piezo beepers
200 have a resonance frequency around 2000Hz, so you can test frequencies
201 around that range. The author's piezo beeper is the loudest at about
202 2050Hz.
203 If you have a PC laptop, chances are that your laptop will not have a
205 piezo beeper hardware inside and that it will route the output of the
206 pcspkr circuit to the laptop's internal speakers via the sound card
207 mixer. In that case, you can and/or must change the mixer level for
208 the beeper using a sound card mixer application.
209 Frequency Table
211 This frequency table might come in handy for translating musical notes
212 to frequencies. The frequencies are rounded to integer numbers as the
213 kernel driver only works with integers. The column for octave 4 is the
214 octave of middle C.
215 ┌─────┬─────────────────────────┐
217 │note │ octave │
218 │name │ 3 4 5 6 │
219 ├─────├─────────────────────────┤
220 │ C │ 131 262 523 1047 │
221 │ C# │ 139 277 554 1109 │
222 │ D │ 147 294 587 1175 │
223 │ D# │ 156 311 622 1245 │
224 │ E │ 165 330 659 1319 │
225 │ F │ 175 349 698 1397 │
226 │ F# │ 185 370 740 1480 │
227 │ G │ 196 392 784 1568 │
228 │ G# │ 208 415 831 1661 │
229 │ A │ 220 440 880 1760 │
230 │ A# │ 233 466 932 1865 │
231 │ B │ 247 494 988 1976 │
232 │ C │ 262 523 1047 2093 │
233 └─────┴─────────────────────────┘
235 Report bugs to ⟨https://github.com/spkr-beep/beep/issues⟩.
236
238 At its simplest (yet still effective)
239 beep
241 A more interesting standalone setup
243 beep -f 300.7 -r 2 -d 100 -l 400
245 As part of a log watching pipeline
247 tail -f /var/log/xferlog | grep 'passwd' | beep -f 1000 -r 5 -s
249 When using -c mode, I recommend using a short -D, and a shorter -l, so
251 that the beeps do not blur together. Something like this will get you
252 a cheesy 1970's style beep-as-you-type-each-letter effect
253 cat file | beep -c -f 400 -D 50 -l 10
255 A highly contrived example of -n/--new usage
257 beep -f 1000 -r 2 -n -r 5 -l 10 --new
259 will produce first two 1000Hz beeps, then 5 beeps at the default tone,
261 but only 10ms long each, followed by a third beep using all the default
262 settings (since none are specified).
263
265 /usr/share/doc/beep/README.fedora, /usr/share/doc/beep/README.md,
266 /usr/share/doc/beep/PERMISSIONS.md, ⟨https://github.com/spkr-beep/beep⟩
267Linux 2020-01-01 BEEP(1)