beep

BEEP(1)                          User commands                         BEEP(1)



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).

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



Linux                             2019-01-11                           BEEP(1)