1.\" 2.\" $FreeBSD$ 3.\" 4.Dd November 10, 2005 5.Dt SPKR 4 6.Os 7.Sh NAME 8.Nm speaker , 9.Nm spkr 10.Nd console speaker device driver 11.Sh SYNOPSIS 12.Cd device speaker 13.In dev/speaker/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.In dev/speaker/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 modeled on the PLAY statement conventions of 70.Tn IBM 71Advanced BASIC 2.0. 72The 73.Li MB , 74.Li MF , 75and 76.Li X 77primitives of PLAY are not 78useful in a timesharing environment and are omitted. 79The `octave-tracking' 80feature and the slur mark are new. 81.Pp 82There are 84 accessible notes numbered 1-84 in 7 octaves, each running from 83C to B, numbered 0-6; the scale is equal-tempered A440 and octave 3 starts 84with middle C. 85By default, the play function emits half-second notes with the 86last 1/16th second being `rest time'. 87.Pp 88Play strings are interpreted left to right as a series of play command groups; 89letter case is ignored. 90Play command groups are as follows: 91.Bl -tag -width CDEFGABxx 92.It Li CDEFGAB 93Letters A through G cause the corresponding note to be played in the 94current octave. 95A note letter may optionally be followed by an 96.Dq Em "accidental sign" , 97one of # + or -; the first two of these cause it to be sharped one 98half-tone, the last causes it to be flatted one half-tone. 99It may 100also be followed by a time value number and by sustain dots (see 101below). 102Time values are interpreted as for the L command below. 103.It Ns Li O Sy n 104If 105.Sy n 106is numeric, this sets the current octave. 107.Sy n 108may also be one of 109.Li L 110or 111.Li N 112to enable or disable octave-tracking (it is disabled by default). 113When octave-tracking is on, interpretation of a pair of letter notes 114will change octaves if necessary in order to make the smallest 115possible jump between notes. 116Thus ``olbc'' will be played as 117``olb>c'', and ``olcb'' as ``olc<b''. 118Octave locking is disabled for 119one letter note following >, < and O[0123456]. 120(The octave-locking 121feature is not supported in 122.Tn IBM 123BASIC.) 124.It Li > 125Bump the current octave up one. 126.It Li < 127Drop the current octave down one. 128.It Ns Li N Sy n 129Play note 130.Sy n , 131.Sy n 132being 1 to 84 or 0 for a rest of current time value. 133May be followed by sustain dots. 134.It Ns Li L Sy n 135Sets the current time value for notes. 136The default is 137.Li L4 , 138quarter or crotchet notes. 139The lowest possible value is 1; values up 140to 64 are accepted. 141.Li L1 142sets whole notes, 143.Li L2 144sets half notes, 145.Li L4 146sets quarter notes, etc. 147.It Ns Li P Sy n 148Pause (rest), with 149.Sy n 150interpreted as for 151.Li L Sy n . 152May be followed by 153sustain dots. 154May also be written 155.Li ~ . 156.It Ns Li T Sy n 157Sets the number of quarter notes per minute; default is 120. 158Musical 159names for common tempi are: 160.Bd -literal -offset indent 161 Tempo Beats Per Minute 162very slow Larghissimo 163 Largo 40-60 164 Larghetto 60-66 165 Grave 166 Lento 167 Adagio 66-76 168slow Adagietto 169 Andante 76-108 170medium Andantino 171 Moderato 108-120 172fast Allegretto 173 Allegro 120-168 174 Vivace 175 Veloce 176 Presto 168-208 177very fast Prestissimo 178.Ed 179.It Li M[LNS] 180Set articulation. 181.Li MN 182.Li ( N 183for normal) is the default; the last 1/8th of 184the note's value is rest time. 185You can set 186.Li ML 187for legato (no rest space) or 188.Li MS 189for staccato (1/4 rest space). 190.El 191.Pp 192Notes (that is, 193.Li CDEFGAB 194or 195.Li N 196command character groups) may be followed by 197sustain dots. 198Each dot causes the note's value to be lengthened by one-half 199for each one. 200Thus, a note dotted once is held for 3/2 of its undotted value; 201dotted twice, it is held 9/4, and three times would give 27/8. 202.Pp 203A note and its sustain dots may also be followed by a slur mark (underscore). 204This causes the normal micro-rest after the note to be filled in, slurring it 205to the next one. 206(The slur feature is not supported in 207.Tn IBM 208BASIC.) 209.Pp 210Whitespace in play strings is simply skipped and may be used to separate 211melody sections. 212.Sh FILES 213.Bl -tag -width /dev/speakerxx 214.It Pa /dev/speaker 215speaker device file 216.El 217.Sh SEE ALSO 218.Xr spkrtest 8 219.Sh HISTORY 220The 221.Nm 222device appeared in 223.Fx 1.0 . 224.Sh AUTHORS 225.An Eric S. Raymond Aq Mt esr@snark.thyrsus.com , 226June 1990 227.Sh PORTED BY 228.An Andrew A. Chernov Aq Mt ache@astral.msk.su 229.Sh BUGS 230Due to roundoff in the pitch tables and slop in the tone-generation and timer 231hardware (neither of which was designed for precision), neither pitch accuracy 232nor timings will be mathematically exact. 233There is no volume control. 234.Pp 235The action of two or more sustain dots does not reflect standard musical 236notation, in which each dot adds half the value of the previous dot 237modifier, not half the value of the note as modified. 238Thus, a note dotted 239once is held for 3/2 of its undotted value; dotted twice, it is held 7/4, 240and three times would give 15/8. 241The multiply-by-3/2 interpretation, 242however, is specified in the 243.Tn IBM 244BASIC manual and has been retained for 245compatibility. 246.Pp 247In play strings which are very long (longer than your system's physical I/O 248blocks) note suffixes or numbers may occasionally be parsed incorrectly due 249to crossing a block boundary. 250