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