1.\" 2.\" $FreeBSD$ 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.Tn FreeBSD . 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: 150 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 . 238