File: beep.1.in

package info (click to toggle)
beep 1.4.3-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 524 kB
  • sloc: ansic: 863; sh: 228; python: 26; makefile: 10
file content (258 lines) | stat: -rw-r--r-- 10,295 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
.\" The beep(1) man page
.\"
.\" This man page has been rewritten adhering to the following
.\" documentation: man(7), man-pages(7), tbl(1)
.\"
.TH BEEP 1 "2019\-01\-11" "Linux" "User commands"
.\"
.\" ====================================================================
.\"
.SH NAME
beep \- beep the pc speaker any number of ways
.\"
.\" ====================================================================
.\"
.SH SYNOPSIS
.B beep
.RB [\| GLOBALS \|]
.RB [\| \-f
.IR FREQ \|]
.RB [\| \-l
.IR LEN \|]
.RB [\| \-r
.IR REPEATS \|]
.RB [\|< \-d|\-D >
.IR DELAY \|]
.RB [\| \-s \|]
.RB [\| \-c \|]
.br
.B beep
.RB [\| GLOBALS \|]
.RI <\| TONE_OPTIONS \|>
.RB [\| \-n|\-\-new \|]
.RI <\| TONE_OPTIONS \|>
.br
.B beep
.RI <\| \-h | \-\-help \|>
.br
.B beep
.RI <\| \-v | \-V | \-\-version \|>
.\"
.\" ====================================================================
.\"
.SH DESCRIPTION
.PP
\fBbeep\fR allows the user to control the PC speaker with precision, allowing different sounds to indicate different events.  While \fBbeep\fR can be run quite happily on the command line, \fBbeep\fR's intended use is within shell/perl scripts, notifying the user when something interesting occurs.  Of course, it has no notion of what \fIIS\fR interesting, but it is good at the notifying part.
.PP
All options have default values, meaning that just typing '\fBbeep\fR' will work.  If an option is specified more than once on the command line, subsequent options override their predecessors.  So '\fBbeep\fR \-f 200 \-f 300' will beep at 300Hz.
.PP
All durations are given in a unit of milliseconds, frequencies as Hertz, and the number of repeats is a dimensionless number.
.\"
.\" ====================================================================
.\"
.SH OPTIONS
.SS "Global options"
.TP
.BI \-e\ DEVICE \fR, \ \fB\-\-device= DEVICE
Explicitly set the device \fBbeep\fR shall use to generate beep tones.  When not given a device explicitly, \fBbeep\fR runs through an internal list of devices until one appears to work.
.TP
.BR \-\-debug ,\  \-\-verbose
Make the \fBbeep\fR program more verbose.
.SS "Tone options"
.TP
.BI \-f\  FREQ
Beep with a tone frequency of \fIFREQ\fR Hz, where 0 < \fIFREQ\fR < 20000.  As a general ballpark, the regular terminal beep is around 750Hz.  For backwards compatibility, you can give \fIFREQ\fR as a floating point number, but \fBbeep\fR will round that to integer values as the kernel APIs expect them.
.TP
.BI \-l\  LEN
Beep for a tone length of \fILEN\fR milliseconds.
.TP
.BI \-r\  REPEATS
Repeat the tone including delays \fIREPEATS\fR times (defaults to 1).
.TP
.BI \-d\  DELAY\fR\ |\  \-D\  DELAY
Specify a delay of \fIDELAY\fR milliseconds between repetitions.  Small letter \fB\-d\fR specifies that this delay should only occur \fIbetween\fR beeps, that is, it should \fInot\fR occur after the last repetition.  Capital letter \fB\-D\fR specifies that the delay should occur after every repetition, \fIincluding\fR the last one.  Normally, \fB\-d\fR is what you want, but if, for example, you are stringing several \fBbeep\fR commands together to play the star wars anthem, you may want control over every delay.
.TP
.BR \-n ,\  \-\-new
The \fB\-\-new\fR option allows you to chain multiple beeps together on a single command line.  Each time the \fB\-\-new\FR is used, \fBbeep\fR starts treating all further arguments as though they were for a new beep.  So for example:

    \fBbeep\fR \-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 \fB\-r\fR value, since \fB\-r\fR repeats the same beep multiple times, whereas \fB\-\-new\fR allows you to specify different beeps.  After a \fB\-\-new\fR, 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 \fBEXAMPLES\fR section if this managed to confuse you.
.TP
.BR \-s ,\  \-c
Both the \fB\-s\fR and the \fB\-c\fR option put \fBbeep\fR into input processing mode.  \fB\-s\fR tells \fBbeep\fR to read from \fIstdin\fR, and beep after each newline.  \fB\-c\fR tells \fBbeep\fR to beep after every character.  In both cases, the \fBbeep\fR will also echo the input back out to stdout, which makes it easy to slip \fBbeep\fR into a text processing pipeline.  See the \fBEXAMPLES\fR section.
.SS "Other Actions"
.BR \-h ,\  \-\-help
Display \fBbeep\fR usage info and exit.
.TP
.BR \-v ,\  \-V ,\  \-\-version
Display \fBbeep\fR version information and exit.
.\"
.\" ====================================================================
.\"
.SH EXIT STATUS
.PP
When successful,
.B beep
returns with exit code 0.
.PP
Any non\-0 exit means
.B beep
has encountered an error and has bailed out.
.\"
.\" ====================================================================
.\"
.SH FILES
The device files
.B beep
uses by default are the following:
.\"
    /dev/input/by\-path/platform\-pcspkr\-event\-spkr
    /dev/tty0
    /dev/vc/0
.\"
.\" ====================================================================
.\"
.SH NOTES
.SS "Devices and Permissions"
.PP
When you run \fBbeep\fR without explicitly giving a device to use, \fBbeep\fR tries opening the following devices in sequence until one succeeds:
.IP "\fB/dev/input/by\-path/platform\-pcspkr\-event\-spkr\fR" 4
Uses the evdev API, and system administrator can allow access to any set of users and groups using the normal file permissions.
.IP "\fB/dev/tty0\fR" 4
Uses the console API, and the kernel insists you are root or own the TTY.
.IP "\fB/dev/vc/0\fR" 4
Uses the console API, and the kernel insists you are root or own the TTY.
.PP
.B beep
does not support running as setuid root or via
.BR "sudo" "(1)" .
.PP
For non\-root uses, the system administrator can set up a
.BR udev "(7)"
rule to allow write access to
.B /dev/input/by\-path/platform\-pcspkr\-event\-spkr
for certain users and/or user groups. For details, see the
.B beep
.B @pkgdocdir@/PERMISSIONS.md
file.
.\"
.SS "APIs"
.IP "evdev" 4
Uses the input event device driver, which means running
.BR "write" "(2)"
on
.BR /dev/input/by\-path/platform\-pcspkr\-event\-spkr .
.IP "console" 4
Uses the ancient console API, which means running the
.B "KIOCSOUND"
.BR "ioctl" "(2)"
on a tty device like
.BR /dev/tty0\  or\  /dev/vc/0.
.\"
.SS "Concurrent Invocations"
Concurrent invocations of
.B 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
.B "beep \-f 1000 \-l 10000"
process starts a long 10 second beep with 1000Hz, and 2 seconds later a second quick
.B "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
.B "beep"
process is still running after having waited for the first 2100ms of 10000ms. You will also not that the first
.B "beep"
process will silence the already silent speaker 7900ms later, i.e. 10000ms after the first
.B "beep"
started.
.\"
.SS "Sound Volume"
.PP
The PC speaker hardware has no way to explicitly set the volume of a beep.
.PP
If you have a
.IR "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.
.PP
If you have a
.IR "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.
.\"
.SS "Frequency Table"
.PP
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
.B "octave 4"
is the octave of middle C.
.\" This table was generated by the gen-freq-table script and
.\" inserted into this man page manually.
.TS
center box;
Cb | Cb s  s  s
Cb | Cb Cb Cb Cb
-  | -  -  -  -
C  | N  N  N  N.
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	
.TE
.\"
.\" ====================================================================
.\"
.SH BUGS
Report bugs to
.UR https://github.com/spkr\-beep/beep/issues
.UE .
.\"
.\" ====================================================================
.\"
.SH EXAMPLES
.PP
At its simplest (yet still effective)

    \fBbeep\fR
.\"
.PP
A more interesting standalone setup

    \fBbeep\fR \-f 300.7 \-r 2 \-d 100 \-l 400
.\"
.PP
As part of a log watching pipeline

    tail \-f /var/log/xferlog | grep 'passwd' | \fBbeep\fR \-f 1000 \-r 5 \-s
.\"
.PP
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 | \fBbeep\fR \-c \-f 400 \-D 50 \-l 10
.\"
.PP
A highly contrived example of \-n/\-\-new usage

    \fBbeep\fR \-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).
.\"
.PP See also the \fBFREQUENCY TABLE\fR below.
.\"
.\" ====================================================================
.\"
.SH SEE ALSO
.\" .BR fixme (1),
.\" .BR andme (1),
.BR @pkgdocdir@/README.md ,
.BR @pkgdocdir@/INSTALL.md ,
.BR @pkgdocdir@/PERMISSIONS.md ,
.UR "https://github.com/spkr\-beep/beep"
.UE