1.\" 2.\" $FreeBSD$ 3.\" 4.Dd November 7, 1993 5.Dt SPKR 4 i386 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 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.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.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.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 . 237