1.\" $NetBSD: speaker.4,v 1.31 2024/09/07 19:13:27 rillig Exp $ 2.\" 3.\" Copyright (c) 2016 Nathanial Sloss <nathanialsloss@yahoo.com.au> 4.\" All rights reserved. 5.\" 6.\" Copyright (c) 1993 Christopher G. Demetriou 7.\" All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed for the 20.\" NetBSD Project. See https://www.NetBSD.org/ for 21.\" information about NetBSD. 22.\" 4. The name of the author may not be used to endorse or promote products 23.\" derived from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 26.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 27.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 28.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 29.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 30.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 31.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 32.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 33.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 34.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 35.\" 36.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>> 37.\" 38.Dd June 13, 2017 39.Dt SPEAKER 4 40.Os 41.Sh NAME 42.Nm speaker 43.Nd console speaker audio device driver 44.Sh SYNOPSIS 45.Cd "spkr* at pcppi?" 46.Cd "spkr* at audio?" 47.Pp 48.In dev/spkrio.h 49.Sh DESCRIPTION 50The speaker device driver allows applications to control the console 51speaker on machines with a PC-like 8253 timer implementation or a synthesized 52speaker from an audio device/soundcard. 53.Pp 54Only one process may have this device open at any given time; 55.Xr open 2 56and 57.Xr close 2 58are used to lock and relinquish it. 59An attempt to 60.Xr open 2 61when another process has the device locked will return \-1 with an 62.Er EBUSY 63error indication. 64Writes to the device are interpreted as 65.Dq play strings 66in a simple 67.Tn ASCII 68melody notation. 69An 70.Fn ioctl 71for tone generation at arbitrary frequencies is also supported. 72.Pp 73For the 74.Xr pcppi 4 75device sound-generation does 76.Em not 77monopolize the processor; in fact, the driver 78spends most of its time sleeping while the PC hardware is emitting 79tones. 80Other processes may emit beeps while the driver is running. 81.Pp 82For the audio device speaker, the speaker uses one of the virtual audio 83channels. 84Enabling this device will also provide a 85.Xr wsbell 4 86keyboard bell. 87.Pp 88Applications may call 89.Fn ioctl 90on a speaker file descriptor to control the speaker driver directly; 91definitions for the 92.Fn ioctl 93interface are in 94.In dev/spkrio.h . 95.Pp 96The 97.Vt tone_t 98structure is as follows: 99.Bd -literal -offset indent 100typedef struct { 101 int frequency; /* in hertz */ 102 int duration; /* in 1/100ths of a second */ 103} tone_t; 104.Ed 105.Pp 106A frequency of zero is interpreted as a rest. 107.Pp 108At present there are four ioctls: 109.Bl -tag -width Dv 110.It Dv SPKRGETVOL 111Returns an integer, which is the current bell volume as a percentage (0\(en100). 112.It Dv SPKRSETVOL 113Accepts an integer, which is the desired volume as a percentage. 114.It Dv SPKRTONE 115Accepts a pointer to a single tone structure as third argument and plays it. 116.It Dv SPKRTUNE 117Accepts a pointer to the first of an array of tone structures and plays 118them in continuous sequence; this array must be terminated by a final member 119with a zero duration. 120.El 121.\" 122.Ss Play string language 123.\" 124The play string language is modelled on the 125.Ic PLAY 126statement conventions of 127.Tn IBM BASIC No 2.0 . 128The 129.Ic MB , 130.Ic MF 131and 132.Ic X 133commands of 134.Ic PLAY 135are not useful in a 136.Tn UNIX 137environment and are not implemented. 138The 139.Dq octave-tracking 140feature is also new. 141.Pp 142There are 84 accessible notes numbered 1\(en84 in 7 octaves numbered 0\(en6; 143octave\~2 starts with middle C. 144The tuning is equal-tempered A440. 145.Pp 146In the initial state the current octave is 4, 147the default note duration is quarter notes, 148the tempo is 120 bpm, 149and the articulation is non-legato or normal, 150i.e. half-second notes with the last 1/16th second being 151.Dq rest time . 152.Pp 153Play strings are interpreted left to right as a series of play command groups. 154Letter case is ignored. 155Whitespace between groups is ignored 156and may be used to separate melody sections. 157Play command groups are as follows: 158.Bl -tag -width Ic 159.It Ic C , D , E , F , G , A , B 160Letters 161.Sq Ic A 162through 163.Sq Ic G 164cause the corresponding note to be played in the current octave. 165A note letter may optionally be followed by an 166.Em accidental sign , 167one of 168.Sq Ic \&# , 169.Sq Ic \&+ , 170or 171.Sq Ic \&- ; 172the first two of these cause it to be sharped one 173half-tone, the last causes it to be flatted one half-tone. 174It may also be 175followed by a time value number and by sustain dots (see below). 176Time values are interpreted as for the 177.Sq Ic L 178command below;. 179.\" 180.It Ic O Ns Ar n , Ic OL , Ic ON 181If 182.Ar n 183is numeric, this sets the current octave. 184.Sq Ic OL 185enables, and 186.Sq Ic ON 187disables 188.Em octave-tracking 189(it is disabled by default). 190When octave-tracking is on, interpretation of a pair of letter notes will 191change octaves if necessary in order to make the smallest possible jump between 192notes. 193Thus 194.Dq Li olbc 195will be played as 196.Dq Li olb>c , 197and 198.Dq Li olcb 199as 200.Dq Li olc<b . 201Octave tracking is temporarily disabled for one letter note that follows 202.Sq Ic \&> , 203.Sq Ic \&< 204or 205.Sq Ic O Ns Ar n . 206.\" 207.It Ic \&> 208Bump the current octave up one. 209.\" 210.It Ic \&< 211Drop the current octave down one. 212.\" 213.It Ic N Ns Ar n 214Play note 215.Ar n , 216.Ar n 217being 1 to 84 or 0 for a rest of current time value. 218May be followed by sustain dots. 219.\" 220.It Ic L Ns Ar n 221Sets the current time value for notes. 222The default is 223.Dq Li L4 , 224quarter notes. 225The lowest possible value is 1; values up to 64 are accepted. 226.Dq Li L1 227sets whole notes, 228.Dq Li L2 229sets half notes, 230.Dq Li L4 231sets quarter notes, etc... 232.\" 233.It Ic P Ns Ar n , Ic \&~ Ns Ar n 234Pause (rest), with 235.Ar n 236interpreted as for 237.Sq Ic L . 238May be followed by sustain dots. 239.\" 240.It Ic T Ns Ar n 241Sets the number of quarter notes per minute; default is 120. 242Musical names for common tempi are: 243.Bl -column "very slow" "Larghissimo" "999\(en999" -offset indent 244.It Ta Sy "Tempo" Ta Sy "BPM" 245.It very slow Ta Larghissimo Ta "" 246.It Ta Largo Ta 40\(en60 247.It Ta Larghetto Ta 60\(en66 248.It Ta Grave Ta "" 249.It Ta Lento Ta "" 250.It Ta Adagio Ta 66\(en76 251.It slow Ta Adagietto Ta "" 252.It Ta Andante Ta 76\(en108 253.It medium Ta Andantino Ta "" 254.It Ta Moderato Ta 108\(en120 255.It fast Ta Allegretto Ta "" 256.It Ta Allegro Ta 120\(en168 257.It Ta Vivace Ta "" 258.It Ta Veloce Ta "" 259.It Ta Presto Ta 168\(en208 260.It very fast Ta Prestissimo Ta "" 261.El 262.\" 263.It Ic ML , Ic MN , Ic MS 264Set articulation. 265.Sq Ic MN 266(for normal) is the default; the last 1/8th of 267the note's value is rest time. 268You can set 269.Sq Ic ML 270for legato (no rest time) or 271.Sq Ic MS 272for staccato (1/4 rest time). 273.El 274.Pp 275Notes, that is, 276.Ic C , D , E , F , G , A , B , 277or 278.Ic N 279command character groups, may be followed by sustain dots. 280Each dot causes the note's value to be lengthened by one-half 281for each one. 282Thus, a note dotted once is held for 3/2 of its undotted value; 283dotted twice, it is held 9/4, and three times would give 27/8. 284.Sh FILES 285.Bl -tag -width Pa -compact 286.It Pa /dev/speaker 287.El 288.Sh SEE ALSO 289.Xr audio 4 , 290.Xr pcppi 4 , 291.Xr wsbell 4 , 292.Xr sysctl 8 293.Sh HISTORY 294This 295.Nm 296device was originally for the pcppi PC timer interface. 297Support was added for a synthesized device by Nathanial Sloss, first appearing 298in 299.Nx 8.0 . 300.Sh AUTHORS 301.An Eric S. Raymond Aq Mt esr@snark.thyrsus.com 302.Sh BUGS 303Due to roundoff in the pitch tables and slop in the tone-generation and timer 304hardware (neither of which was designed for precision), neither pitch accuracy 305nor timings will be mathematically exact. 306.Pp 307There is no volume control. 308.Pp 309The action of two or more sustain dots does not reflect standard musical 310notation, in which each dot adds half the value of the previous dot 311modifier, not half the value of the note as modified. 312Thus, a note dotted 313once is held for 3/2 of its undotted value; dotted twice, it is held 7/4, 314and three times would give 15/8. 315The multiply-by-3/2 interpretation, 316however, is specified in the 317.Tn IBM BASIC 318manual and has been retained for compatibility. 319.Pp 320In play strings which are very long (longer than your system's physical I/O 321blocks) note suffixes or numbers may occasionally be parsed incorrectly due 322to crossing a block boundary. 323