3.\"
4.Dd November 7, 1993
5.Dt SPKR 4 i386
6.Os FreeBSD
7.Sh NAME
8.Nm speaker ,
9.Nm spkr
10.Nd console speaker device driver
11.Sh SYNOPSIS
12.Cd pseudo-device speaker
13.Fd #include <machine/speaker.h>
14.Sh DESCRIPTION
15The speaker device driver allows applications to control the PC console
16speaker on an
17.Tn IBM-PC Ns --compatible
18machine running
19.Fx .
20.Pp
21Only one process may have this device open at any given time;
22.Xr open 2
23and
24.Xr close 2
25are used to lock and relinquish it.
26An attempt to open when
27another process has the device locked will return -1 with an
28.Er EBUSY
29error
30indication.
31Writes to the device are interpreted as `play strings' in a
32simple ASCII melody notation.
33An
34.Xr ioctl 2
35request
36for tone generation at arbitrary
37frequencies is also supported.
38.Pp
39Sound-generation does not monopolize the processor; in fact, the driver
40spends most of its time sleeping while the PC hardware is emitting
41tones.
42Other processes may emit beeps while the driver is running.
43.Pp
44Applications may call
45.Xr ioctl 2
46on a speaker file descriptor to control the
47speaker driver directly; definitions for the
48.Xr ioctl 2
49interface are in
50.Pa /usr/include/machine/speaker.h .
51The
52.Li tone_t
53structure used in these calls has two fields,
54specifying a frequency (in Hz) and a duration (in 1/100ths of a second).
55A frequency of zero is interpreted as a rest.
56.Pp
57At present there are two such
58.Xr ioctl 2
59calls.
60.Dv SPKRTONE
61accepts a pointer to a
62single tone structure as third argument and plays it.
63.Dv SPKRTUNE
64accepts a
65pointer to the first of an array of tone structures and plays them in
66continuous sequence; this array must be terminated by a final member with
67a zero duration.
68.Pp
69The play-string language is modelled on the PLAY statement conventions of
70.Tn IBM
71Advanced BASIC 2.0. The
72.Li MB ,
73.Li MF ,
74and
75.Li X
76primitives of PLAY are not
77useful in a timesharing environment and are omitted.
78The `octave-tracking'
79feature and the slur mark are new.
80.Pp
81There are 84 accessible notes numbered 1-84 in 7 octaves, each running from
82C to B, numbered 0-6; the scale is equal-tempered A440 and octave 3 starts
83with middle C. By default, the play function emits half-second notes with the
84last 1/16th second being `rest time'.
85.Pp
86Play strings are interpreted left to right as a series of play command groups;
87letter case is ignored.
88Play command groups are as follows:
89.Bl -tag -width CDEFGABxx
90.It Li CDEFGAB
91Letters A through G cause the corresponding note to be played in the
92current octave. A note letter may optionally be followed by an
93.Dq Em "accidental sign" ,
94one of # + or -; the first two of these cause it to be sharped one
95half-tone, the last causes it to be flatted one half-tone. It may
96also be followed by a time value number and by sustain dots (see
97below). Time values are interpreted as for the L command below.
98.It Ns Li O Sy n
99If
100.Sy n
101is numeric, this sets the current octave.
102.Sy n
103may also be one of
104.Li L
105or
106.Li N
107to enable or disable octave-tracking (it is disabled by default).
108When octave-tracking is on, interpretation of a pair of letter notes
109will change octaves if necessary in order to make the smallest
110possible jump between notes.
111Thus ``olbc'' will be played as
112``olb>c'', and ``olcb'' as ``olc<b''. Octave locking is disabled for
113one letter note following >, < and O[0123456]. (The octave-locking
114feature is not supported in
115.Tn IBM
116BASIC.)
117.It Li >
118Bump the current octave up one.
119.It Li <
120Drop the current octave down one.
121.It Ns Li N Sy n
122Play note
123.Sy n ,
124.Sy n
125being 1 to 84 or 0 for a rest of current time value.
126May be followed by sustain dots.
127.It Ns Li L Sy n
128Sets the current time value for notes. The default is
129.Li L4 ,
130quarter or crotchet notes.
131The lowest possible value is 1; values up
132to 64 are accepted.
133.Li L1
134sets whole notes,
135.Li L2
136sets half notes,
137.Li L4
138sets quarter notes, etc.
139.It Ns Li P Sy n
140Pause (rest), with
141.Sy n
142interpreted as for
143.Ns Li L Sy n .
144May be followed by
145sustain dots. May also be written
146.Li ~ .
147.It Ns Li T Sy n
148Sets the number of quarter notes per minute; default is 120. Musical
149names for common tempi are:
| 3.\"
4.Dd November 7, 1993
5.Dt SPKR 4 i386
6.Os FreeBSD
7.Sh NAME
8.Nm speaker ,
9.Nm spkr
10.Nd console speaker device driver
11.Sh SYNOPSIS
12.Cd pseudo-device speaker
13.Fd #include <machine/speaker.h>
14.Sh DESCRIPTION
15The speaker device driver allows applications to control the PC console
16speaker on an
17.Tn IBM-PC Ns --compatible
18machine running
19.Fx .
20.Pp
21Only one process may have this device open at any given time;
22.Xr open 2
23and
24.Xr close 2
25are used to lock and relinquish it.
26An attempt to open when
27another process has the device locked will return -1 with an
28.Er EBUSY
29error
30indication.
31Writes to the device are interpreted as `play strings' in a
32simple ASCII melody notation.
33An
34.Xr ioctl 2
35request
36for tone generation at arbitrary
37frequencies is also supported.
38.Pp
39Sound-generation does not monopolize the processor; in fact, the driver
40spends most of its time sleeping while the PC hardware is emitting
41tones.
42Other processes may emit beeps while the driver is running.
43.Pp
44Applications may call
45.Xr ioctl 2
46on a speaker file descriptor to control the
47speaker driver directly; definitions for the
48.Xr ioctl 2
49interface are in
50.Pa /usr/include/machine/speaker.h .
51The
52.Li tone_t
53structure used in these calls has two fields,
54specifying a frequency (in Hz) and a duration (in 1/100ths of a second).
55A frequency of zero is interpreted as a rest.
56.Pp
57At present there are two such
58.Xr ioctl 2
59calls.
60.Dv SPKRTONE
61accepts a pointer to a
62single tone structure as third argument and plays it.
63.Dv SPKRTUNE
64accepts a
65pointer to the first of an array of tone structures and plays them in
66continuous sequence; this array must be terminated by a final member with
67a zero duration.
68.Pp
69The play-string language is modelled on the PLAY statement conventions of
70.Tn IBM
71Advanced BASIC 2.0. The
72.Li MB ,
73.Li MF ,
74and
75.Li X
76primitives of PLAY are not
77useful in a timesharing environment and are omitted.
78The `octave-tracking'
79feature and the slur mark are new.
80.Pp
81There are 84 accessible notes numbered 1-84 in 7 octaves, each running from
82C to B, numbered 0-6; the scale is equal-tempered A440 and octave 3 starts
83with middle C. By default, the play function emits half-second notes with the
84last 1/16th second being `rest time'.
85.Pp
86Play strings are interpreted left to right as a series of play command groups;
87letter case is ignored.
88Play command groups are as follows:
89.Bl -tag -width CDEFGABxx
90.It Li CDEFGAB
91Letters A through G cause the corresponding note to be played in the
92current octave. A note letter may optionally be followed by an
93.Dq Em "accidental sign" ,
94one of # + or -; the first two of these cause it to be sharped one
95half-tone, the last causes it to be flatted one half-tone. It may
96also be followed by a time value number and by sustain dots (see
97below). Time values are interpreted as for the L command below.
98.It Ns Li O Sy n
99If
100.Sy n
101is numeric, this sets the current octave.
102.Sy n
103may also be one of
104.Li L
105or
106.Li N
107to enable or disable octave-tracking (it is disabled by default).
108When octave-tracking is on, interpretation of a pair of letter notes
109will change octaves if necessary in order to make the smallest
110possible jump between notes.
111Thus ``olbc'' will be played as
112``olb>c'', and ``olcb'' as ``olc<b''. Octave locking is disabled for
113one letter note following >, < and O[0123456]. (The octave-locking
114feature is not supported in
115.Tn IBM
116BASIC.)
117.It Li >
118Bump the current octave up one.
119.It Li <
120Drop the current octave down one.
121.It Ns Li N Sy n
122Play note
123.Sy n ,
124.Sy n
125being 1 to 84 or 0 for a rest of current time value.
126May be followed by sustain dots.
127.It Ns Li L Sy n
128Sets the current time value for notes. The default is
129.Li L4 ,
130quarter or crotchet notes.
131The lowest possible value is 1; values up
132to 64 are accepted.
133.Li L1
134sets whole notes,
135.Li L2
136sets half notes,
137.Li L4
138sets quarter notes, etc.
139.It Ns Li P Sy n
140Pause (rest), with
141.Sy n
142interpreted as for
143.Ns Li L Sy n .
144May be followed by
145sustain dots. May also be written
146.Li ~ .
147.It Ns Li T Sy n
148Sets the number of quarter notes per minute; default is 120. Musical
149names for common tempi are:
|
151.Bd -literal -offset indent
152 Tempo Beats Per Minute
153very slow Larghissimo
154 Largo 40-60
155 Larghetto 60-66
156 Grave
157 Lento
158 Adagio 66-76
159slow Adagietto
160 Andante 76-108
161medium Andantino
162 Moderato 108-120
163fast Allegretto
164 Allegro 120-168
165 Vivace
166 Veloce
167 Presto 168-208
168very fast Prestissimo
169.Ed
170.It Li M[LNS]
171Set articulation.
172.Li MN
173.Ns No ( Li N
174for normal) is the default; the last 1/8th of
175the note's value is rest time.
176You can set
177.Li ML
178for legato (no rest space) or
179.Li MS
180for staccato (1/4 rest space).
181.El
182.Pp
183Notes (that is,
184.Li CDEFGAB
185or
186.Li N
187command character groups) may be followed by
188sustain dots.
189Each dot causes the note's value to be lengthened by one-half
190for each one.
191Thus, a note dotted once is held for 3/2 of its undotted value;
192dotted twice, it is held 9/4, and three times would give 27/8.
193.Pp
194A note and its sustain dots may also be followed by a slur mark (underscore).
195This causes the normal micro-rest after the note to be filled in, slurring it
196to the next one. (The slur feature is not supported in
197.Tn IBM
198BASIC.)
199.Pp
200Whitespace in play strings is simply skipped and may be used to separate
201melody sections.
202.Sh BUGS
203Due to roundoff in the pitch tables and slop in the tone-generation and timer
204hardware (neither of which was designed for precision), neither pitch accuracy
205nor timings will be mathematically exact.
206There is no volume control.
207.Pp
208The action of two or more sustain dots does not reflect standard musical
209notation, in which each dot adds half the value of the previous dot
210modifier, not half the value of the note as modified. Thus, a note dotted
211once is held for 3/2 of its undotted value; dotted twice, it is held 7/4,
212and three times would give 15/8. The multiply-by-3/2 interpretation,
213however, is specified in the
214.Tn IBM
215BASIC manual and has been retained for
216compatibility.
217.Pp
218In play strings which are very long (longer than your system's physical I/O
219blocks) note suffixes or numbers may occasionally be parsed incorrectly due
220to crossing a block boundary.
221.Sh FILES
222.Bl -tag -width /dev/speakerxx
223.It Pa /dev/speaker
224speaker device file
225.El
226.Sh SEE ALSO
227.Xr spkrtest 8
228.Sh AUTHORS
229.An Eric S. Raymond Aq esr@snark.thyrsus.com
230June 1990
231.Sh "PORTED BY"
232.An Andrew A. Chernov Aq ache@astral.msk.su
233.Sh HISTORY
234The
235.Nm
236device appeared in
237.Fx 1.0 .
| 150.Bd -literal -offset indent
151 Tempo Beats Per Minute
152very slow Larghissimo
153 Largo 40-60
154 Larghetto 60-66
155 Grave
156 Lento
157 Adagio 66-76
158slow Adagietto
159 Andante 76-108
160medium Andantino
161 Moderato 108-120
162fast Allegretto
163 Allegro 120-168
164 Vivace
165 Veloce
166 Presto 168-208
167very fast Prestissimo
168.Ed
169.It Li M[LNS]
170Set articulation.
171.Li MN
172.Ns No ( Li N
173for normal) is the default; the last 1/8th of
174the note's value is rest time.
175You can set
176.Li ML
177for legato (no rest space) or
178.Li MS
179for staccato (1/4 rest space).
180.El
181.Pp
182Notes (that is,
183.Li CDEFGAB
184or
185.Li N
186command character groups) may be followed by
187sustain dots.
188Each dot causes the note's value to be lengthened by one-half
189for each one.
190Thus, a note dotted once is held for 3/2 of its undotted value;
191dotted twice, it is held 9/4, and three times would give 27/8.
192.Pp
193A note and its sustain dots may also be followed by a slur mark (underscore).
194This causes the normal micro-rest after the note to be filled in, slurring it
195to the next one. (The slur feature is not supported in
196.Tn IBM
197BASIC.)
198.Pp
199Whitespace in play strings is simply skipped and may be used to separate
200melody sections.
201.Sh BUGS
202Due to roundoff in the pitch tables and slop in the tone-generation and timer
203hardware (neither of which was designed for precision), neither pitch accuracy
204nor timings will be mathematically exact.
205There is no volume control.
206.Pp
207The action of two or more sustain dots does not reflect standard musical
208notation, in which each dot adds half the value of the previous dot
209modifier, not half the value of the note as modified. Thus, a note dotted
210once is held for 3/2 of its undotted value; dotted twice, it is held 7/4,
211and three times would give 15/8. The multiply-by-3/2 interpretation,
212however, is specified in the
213.Tn IBM
214BASIC manual and has been retained for
215compatibility.
216.Pp
217In play strings which are very long (longer than your system's physical I/O
218blocks) note suffixes or numbers may occasionally be parsed incorrectly due
219to crossing a block boundary.
220.Sh FILES
221.Bl -tag -width /dev/speakerxx
222.It Pa /dev/speaker
223speaker device file
224.El
225.Sh SEE ALSO
226.Xr spkrtest 8
227.Sh AUTHORS
228.An Eric S. Raymond Aq esr@snark.thyrsus.com
229June 1990
230.Sh "PORTED BY"
231.An Andrew A. Chernov Aq ache@astral.msk.su
232.Sh HISTORY
233The
234.Nm
235device appeared in
236.Fx 1.0 .
|