Ubuntu Manpage: beep - beep the pc speaker any number of ways

NAME

       beep - beep the pc speaker any number of ways

SYNOPSIS

       beep [GLOBALS] [-f FREQ] [-l LEN] [-r REPEATS] [<-d|-D> DELAY] [-s] [-c]
       beep [GLOBALS] <TONE_OPTIONS> [-n|--new] <TONE_OPTIONS>
       beep <-h|--help>
       beep <-v|-V|--version>

DESCRIPTION

       beep  allows  the  user  to  control the PC speaker with precision, allowing different sounds to indicate
       different events.  While beep can be run quite happily on the command line, beep's intended use is within
       shell/perl scripts, notifying the user when something interesting occurs.  Of course, it has no notion of
       what IS interesting, but it is good at the notifying part.

       All options have default values, meaning that just typing 'beep' will work.  If an  option  is  specified
       more  than  once on the command line, subsequent options override their predecessors.  So 'beep -f 200 -f
       300' will beep at 300Hz.

       All durations are given in a unit of milliseconds, frequencies as Hertz, and the number of repeats  is  a
       dimensionless number.

OPTIONS

Global options
-e DEVICE, --device=DEVICE
Explicitly set the device beep shall use to generate beep tones. When not given a device
explicitly, beep runs through an internal list of devices until one appears to work.

--debug, --verbose
Make the beep program more verbose.

Tone options
-f FREQ
Beep with a tone frequency of FREQ Hz, where 0 < FREQ < 20000. As a general ballpark, the regular
terminal beep is around 750Hz. For backwards compatibility, you can give FREQ as a floating point
number, but beep will round that to integer values as the kernel APIs expect them.

-l LEN Beep for a tone length of LEN milliseconds.

-r REPEATS
Repeat the tone including delays REPEATS times (defaults to 1).

-d DELAY | -D DELAY
Specify a delay of DELAY milliseconds between repetitions. Small letter -d specifies that this
delay should only occur between beeps, that is, it should not occur after the last repetition.
Capital letter -D specifies that the delay should occur after every repetition, including the last
one. Normally, -d is what you want, but if, for example, you are stringing several beep commands
together to play the star wars anthem, you may want control over every delay.

-n, --new
The --new option allows you to chain multiple beeps together on a single command line. Each time
the --new is used, beep starts treating all further arguments as though they were for a new beep.
So for example:

beep -f 1000 -n -f 2000 -n -f 1500

would produce a sequence of three beeps, the first with a frequency of 1000Hz (and otherwise
default values), then a second beep with a frequency of 2000Hz (again, with things like delay and
reps being set to their defaults), then a third beep, at 1500Hz. This is different from
specifying a -r value, since -r repeats the same beep multiple times, whereas --new allows you to
specify different beeps. After a --new, the new beep is created with all the default values, and
any of these can be specified without altering values for preceding (or later) beeps. See the
EXAMPLES section if this managed to confuse you.

-s, -c Both the -s and the -c option put beep into input processing mode. -s tells beep to read from
stdin, and beep after each newline. -c tells beep to beep after every character. In both cases,
the beep will also echo the input back out to stdout, which makes it easy to slip beep into a text
processing pipeline. See the EXAMPLES section.

Other Actions
-h, --help Display beep usage info and exit.

-v, -V, --version
Display beep version information and exit.

EXIT STATUS

       When successful, beep returns with exit code 0.

       Any non-0 exit means beep has encountered an error and has bailed out.

FILES

       The device files beep uses by default are the following:
           /dev/input/by-path/platform-pcspkr-event-spkr
           /dev/tty0
           /dev/vc/0

NOTES

   Devices and Permissions
       When  you run beep without explicitly giving a device to use, beep tries opening the following devices in
       sequence until one succeeds:

       /dev/input/by-path/platform-pcspkr-event-spkr
           Uses the evdev API, and system administrator can allow access to any set of users  and  groups  using
           the normal file permissions.

       /dev/tty0
           Uses the console API, and the kernel insists you are root or own the TTY.

       /dev/vc/0
           Uses the console API, and the kernel insists you are root or own the TTY.

       beep does not support running as setuid root or via sudo(1).

       For  non-root  uses,  the  system  administrator  can  set  up  a  udev(7)  rule to allow write access to
       /dev/input/by-path/platform-pcspkr-event-spkr for certain users and/or user groups. For details, see  the
       beep /usr/share/doc/beep/PERMISSIONS.md file.

   APIs
       evdev
           Uses     the     input     event     device    driver,    which    means    running    write(2)    on
           /dev/input/by-path/platform-pcspkr-event-spkr.

       console
           Uses the ancient console API, which means running  the  KIOCSOUND  ioctl(2)  on  a  tty  device  like
           /dev/tty0 or /dev/vc/0.

   Concurrent Invocations
       Concurrent  invocations  of  beep are not supported. There is only one tone generator in the PC hardware,
       and we do not manage access to that shared resource in any way.  So if a first  beep  -f  1000  -l  10000
       process  starts a long 10 second beep with 1000Hz, and 2 seconds later a second quick beep -f 2050 -l 100
       with 2050Hz comes in, you will hear that 2050Hz beep for 100ms,  and  then  silence  as  the  quick  beep
       silences  the  tone  generator.  Now you will not hear that the first beep process is still running after
       having waited for the first 2100ms of 10000ms. You will also not that the first beep process will silence
       the already silent speaker 7900ms later, i.e. 10000ms after the first beep started.

   Sound Volume
       The PC speaker hardware has no way to explicitly set the volume of a beep.

       If you have a standalone PC, however, chances are you have a piezo beeper connected to the mainboard.  If
       you prioritize a loud beep over a certain frequency beep, you can choose to beep at a frequency close  to
       the  resonance  frequency  of  the piezo beeper.  Typical piezo beepers have a resonance frequency around
       2000Hz, so you can test frequencies around that range.  The author's piezo beeper is the loudest at about
       2050Hz.

       If you have a PC laptop, chances are that your laptop will not have a piezo beeper  hardware  inside  and
       that  it will route the output of the pcspkr circuit to the laptop's internal speakers via the sound card
       mixer.  In that case, you can and/or must change the mixer level for the beeper using a sound card  mixer
       application.

   Frequency Table
       This  frequency  table  might come in hand for translating musical notes to frequencies.  The frequencies
       are rounded to integer numbers as the kernel driver only works with integers.  The column for octave 4 is
       the octave of middle C.
                                          ┌──────┬─────────────────────────┐
                                          │ note │         octave          │
                                          │ name │  3     4     5      6   │
                                          ├──────├─────────────────────────┤
                                          │  C   │ 131   262    523   1047 │
                                          │  C#  │ 139   277    554   1109 │
                                          │  D   │ 147   294    587   1175 │
                                          │  D#  │ 156   311    622   1245 │
                                          │  E   │ 165   330    659   1319 │
                                          │  F   │ 175   349    698   1397 │
                                          │  F#  │ 185   370    740   1480 │
                                          │  G   │ 196   392    784   1568 │
                                          │  G#  │ 208   415    831   1661 │
                                          │  A   │ 220   440    880   1760 │
                                          │  A#  │ 233   466    932   1865 │
                                          │  B   │ 247   494    988   1976 │
                                          │  C   │ 262   523   1047   2093 │
                                          └──────┴─────────────────────────┘

BUGS

       Report bugs to https://github.com/spkr-beep/beep/issues.

EXAMPLES

       At its simplest (yet still effective)

           beep

       A more interesting standalone setup

           beep -f 300.7 -r 2 -d 100 -l 400

       As part of a log watching pipeline

           tail -f /var/log/xferlog | grep 'passwd' | beep -f 1000 -r 5 -s

       When using -c mode, I recommend using a short -D, and a shorter  -l,  so  that  the  beeps  do  not  blur
       together.  Something like this will get you a cheesy 1970's style beep-as-you-type-each-letter effect

           cat file | beep -c -f 400 -D 50 -l 10

       A highly contrived example of -n/--new usage

           beep -f 1000 -r 2 -n -r 5 -l 10 --new

       will  produce first two 1000Hz beeps, then 5 beeps at the default tone, but only 10ms long each, followed
       by a third beep using all the default settings (since none are specified).