share/man/man4/spkr.4

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