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