1BEEP(1)                          User commands                         BEEP(1)
2
3
4

NAME

6       beep - beep the pc speaker any number of ways
7

SYNOPSIS

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

DESCRIPTION

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
23       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
28       All durations are given in  a  unit  of  milliseconds,  frequencies  as
29       Hertz, and the number of repeats is a dimensionless number.
30

OPTIONS

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
38       --debug, --verbose
39              Make the beep program more verbose.
40
41   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
49       -l LEN Beep for a tone length of LEN milliseconds.
50
51       -r REPEATS
52              Repeat the tone including delays REPEATS times (defaults to 1).
53
54       -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
64       -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
70                  beep -f 1000 -n -f 2000 -n -f 1500
71
72              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
83       -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
89              -c     Beep after every character received.
90
91              -s     Beep after every set of  data  received.   Usually,  this
92                     means after newlines occur in text processing pipes.
93
94              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
102              The  behaviour of beep with more than one note marked with -s or
103              -c is undefined.
104
105   Other Actions
106       -h, --help Display beep usage info and exit.
107
108       -v, -V, --version
109              Display beep version information and exit.
110

EXIT STATUS

112       When successful, beep returns with exit code 0.
113
114       Any non-0 exit code means beep has encountered an error and has  bailed
115       out.
116

ENVIRONMENT

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

FILES

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

NOTES

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
134       /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
138       /dev/tty0
139           Uses  the  console  API, and the kernel insists you are root or own
140           the TTY.
141
142       /dev/vc/0
143           Uses the console API, and the kernel insists you are  root  or  own
144           the TTY.
145
146       beep does not support running as setuid root or via sudo(1).
147
148       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
153   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
158           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
161           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
167       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
171           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
177           Use the evdev API instead.
178
179   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
192   Sound Volume
193       The  PC  speaker  hardware has no way to explicitly set the volume of a
194       beep.
195
196       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
204       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
210   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
216                          ┌─────┬─────────────────────────┐
217note octave          
218name 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                          └─────┴─────────────────────────┘

BUGS

235       Report bugs to ⟨https://github.com/spkr-beep/beep/issues⟩.
236

EXAMPLES

238       At its simplest (yet still effective)
239
240           beep
241
242       A more interesting standalone setup
243
244           beep -f 300.7 -r 2 -d 100 -l 400
245
246       As part of a log watching pipeline
247
248           tail -f /var/log/xferlog | grep 'passwd' | beep -f 1000 -r 5 -s
249
250       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
254           cat file | beep -c -f 400 -D 50 -l 10
255
256       A highly contrived example of -n/--new usage
257
258           beep -f 1000 -r 2 -n -r 5 -l 10 --new
259
260       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

SEE ALSO

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
267
268
269
270Linux                             2020-01-01                           BEEP(1)
Impressum