Provided by: beep_1.4.3-2_amd64 bug

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.

                                    ┌─────┬─────────────────────────┐
                                    │noteoctave          │
                                    │name3     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).

SEE ALSO

       /usr/share/doc/beep/README.md,                             /usr/share/doc/beep/INSTALL.md,
       /usr/share/doc/beep/PERMISSIONS.md, ⟨https://github.com/spkr-beep/beep⟩