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. -s tells beep to read from stdin, and beep after each
85 newline. -c tells beep to beep after every character. In both
86 cases, the beep will also echo the input back out to stdout,
87 which makes it easy to slip beep into a text processing pipe‐
88 line. See the EXAMPLES section.
89 Other Actions
91 -h, --help Display beep usage info and exit.
92 -v, -V, --version
94 Display beep version information and exit.
95
97 When successful, beep returns with exit code 0.
98 Any non-0 exit means beep has encountered an error and has bailed out.
100
102 The device files beep uses by default are the following:
103 /dev/input/by-path/platform-pcspkr-event-spkr
104 /dev/tty0
105 /dev/vc/0
106
108 Devices and Permissions
109 When you run beep without explicitly giving a device to use, beep tries
110 opening the following devices in sequence until one succeeds:
111 /dev/input/by-path/platform-pcspkr-event-spkr
113 Uses the evdev API, and system administrator can allow access to
114 any set of users and groups using the normal file permissions.
115 /dev/tty0
117 Uses the console API, and the kernel insists you are root or own
118 the TTY.
119 /dev/vc/0
121 Uses the console API, and the kernel insists you are root or own
122 the TTY.
123 beep does not support running as setuid root or via sudo(1).
125 For non-root uses, the system administrator can set up a udev(7) rule
127 to allow write access to /dev/input/by-path/platform-pcspkr-event-spkr
128 for certain users and/or user groups. For details, see the beep
129 /usr/share/doc/beep/PERMISSIONS.md file.
130 APIs
132 evdev
133 Uses the input event device driver, which means running write(2) on
134 /dev/input/by-path/platform-pcspkr-event-spkr.
135 console
137 Uses the ancient console API, which means running the KIOCSOUND
138 ioctl(2) on a tty device like /dev/tty0 or /dev/vc/0.
139 Concurrent Invocations
141 Concurrent invocations of beep are not supported. There is only one
142 tone generator in the PC hardware, and we do not manage access to that
143 shared resource in any way. So if a first beep -f 1000 -l 10000
144 process starts a long 10 second beep with 1000Hz, and 2 seconds later a
145 second quick beep -f 2050 -l 100 with 2050Hz comes in, you will hear
146 that 2050Hz beep for 100ms, and then silence as the quick beep silences
147 the tone generator. Now you will not hear that the first beep process
148 is still running after having waited for the first 2100ms of 10000ms.
149 You will also not that the first beep process will silence the already
150 silent speaker 7900ms later, i.e. 10000ms after the first beep started.
151 Sound Volume
153 The PC speaker hardware has no way to explicitly set the volume of a
154 beep.
155 If you have a standalone PC, however, chances are you have a piezo
157 beeper connected to the mainboard. If you prioritize a loud beep over
158 a certain frequency beep, you can choose to beep at a frequency close
159 to the resonance frequency of the piezo beeper. Typical piezo beepers
160 have a resonance frequency around 2000Hz, so you can test frequencies
161 around that range. The author's piezo beeper is the loudest at about
162 2050Hz.
163 If you have a PC laptop, chances are that your laptop will not have a
165 piezo beeper hardware inside and that it will route the output of the
166 pcspkr circuit to the laptop's internal speakers via the sound card
167 mixer. In that case, you can and/or must change the mixer level for
168 the beeper using a sound card mixer application.
169 Frequency Table
171 This frequency table might come in hand for translating musical notes
172 to frequencies. The frequencies are rounded to integer numbers as the
173 kernel driver only works with integers. The column for octave 4 is the
174 octave of middle C.
175 ┌─────┬─────────────────────────┐
177 │note │ octave │
178 │name │ 3 4 5 6 │
179 ├─────├─────────────────────────┤
180 │ C │ 131 262 523 1047 │
181 │ C# │ 139 277 554 1109 │
182 │ D │ 147 294 587 1175 │
183 │ D# │ 156 311 622 1245 │
184 │ E │ 165 330 659 1319 │
185 │ F │ 175 349 698 1397 │
186 │ F# │ 185 370 740 1480 │
187 │ G │ 196 392 784 1568 │
188 │ G# │ 208 415 831 1661 │
189 │ A │ 220 440 880 1760 │
190 │ A# │ 233 466 932 1865 │
191 │ B │ 247 494 988 1976 │
192 │ C │ 262 523 1047 2093 │
193 └─────┴─────────────────────────┘
195 Report bugs to ⟨https://github.com/spkr-beep/beep/issues⟩.
196
198 At its simplest (yet still effective)
199 beep
201 A more interesting standalone setup
203 beep -f 300.7 -r 2 -d 100 -l 400
205 As part of a log watching pipeline
207 tail -f /var/log/xferlog | grep 'passwd' | beep -f 1000 -r 5 -s
209 When using -c mode, I recommend using a short -D, and a shorter -l, so
211 that the beeps do not blur together. Something like this will get you
212 a cheesy 1970's style beep-as-you-type-each-letter effect
213 cat file | beep -c -f 400 -D 50 -l 10
215 A highly contrived example of -n/--new usage
217 beep -f 1000 -r 2 -n -r 5 -l 10 --new
219 will produce first two 1000Hz beeps, then 5 beeps at the default tone,
221 but only 10ms long each, followed by a third beep using all the default
222 settings (since none are specified).
223
225 /usr/share/doc/beep/README.fedora, /usr/share/doc/beep/README.md,
226 /usr/share/doc/beep/PERMISSIONS.md, ⟨https://github.com/spkr-beep/beep⟩
227Linux 2019-01-11 BEEP(1)