Manpages

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. Default value: 440 Hz.

-r REPEATS

Repeat the tone including delays REPEATS times. Default value: 1 tone, not repeated.

-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 after 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. Default value: 100 ms delay between beeps with no delay after the last beep.

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

-c

In a sequence of notes specified with one or more occurrences of -n or --new, it only makes sense to have one single note marked with either -s or -c attached to it. Then beep will beep all notes until it reaches that marked note, then repeat the marked note according to the input it receives, and once the input has reached EOF, beep will continue with the remainder of the note sequence.

The behaviour of beep with more than one note marked with -s or -c is undefined.

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 code means beep has encountered an error and has bailed out.

ENVIRONMENT

BEEP_LOG_LEVEL

When set to a number between -999 and 999, BEEP_LOG_LEVEL will be used as the default loglevel until overridden by a command line parameter.

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.

The permissions to this device file can be set up such that beep can be run by any non-root user the system administrator wants to.

Opening this device takes on the order of magnitude of 20ms in the Linux kernel for every time you start the beep command. Therefore, if you need to play multiple notes in a rhythmical sequence for a melody, use one beep command invocation with multiple notes, not several beep invocations playing one note each.

console

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