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