Only one process may have this device open at any given time; open() and close() are used to lock and relinquish it. An attempt to open() when another process has the device locked will return -1 with an EBUSY error indication. Writes to the device are interpreted as 'play strings' in a simple ASCII melody notation. An ioctl() for tone generation at arbitrary frequencies is also supported.
Sound-generation does not monopolize the processor; in fact, the driver spends most of its time sleeping while the PC hardware is emitting tones. Other processes may emit beeps while the driver is running.
Applications may call ioctl() on a speaker file descriptor to control the speaker driver directly; definitions for the ioctl() interface are in sys/spkr.h. The tone_t structure used in these calls has two fields, specifying a frequency (in hz) and a duration (in 1/100ths of a second). A frequency of zero is interpreted as a rest.
At present there are two such ioctls. SPKRTONE accepts a pointer to a single tone structure as third argument and plays it. SPKRTUNE accepts a pointer to the first of an array of tone structures and plays them in continuous sequence; this array must be terminated by a final member with a zero duration.
The play-string language is modelled on the PLAY statement conventions of IBM BASIC 2.0. The MB, MF and X primitives of PLAY are not useful in a UNIX environment and are omitted. The `octave-tracking' feature is also new.
There are 84 accessible notes numbered 1-83 in 7 octaves, each running from C to B, numbered 0-6; the scale is equal-tempered A440 and octave 3 starts with middle C. By default, the play function emits half-second notes with the last 1/16th second being `rest time'.
Play strings are interpreted left to right as a series of play command groups; letter case is ignored. Play command groups are as follows:
CDEFGAB -- letters A through G cause the corresponding note to be played in the current octave. A note letter may optionally be followed by an accidental sign, one of # + or -; the first two of these cause it to be sharped one half-tone, the last causes it to be flatted one half-tone. It may also be followed by a time value number and by sustain dots (see below). Time values are interpreted as for the L command below;.
O <n> -- if <n> is numeric, this sets the current octave. <n> may also be one of 'L' or 'N' to enable or disable octave-tracking (it is disabled by default). When octave-tracking is on, interpretation of a pair of letter notes will change octaves if necessary in order to make the smallest possible jump between notes. Thus "olbc" will be played as "olb>c", and "olcb" as "olc<b". Octave locking is disabled for one letter note following by >, < and O[0123456].
> -- bump the current octave up one.
< -- drop the current octave down one.
N <n> -- play note n, n being 1 to 84 or 0 for a rest of current time value. May be followedv by sustain dots.
L <n> -- sets the current time value for notes. The default is L4, quarter notes. The lowest possible value is 1; values up to 64 are accepted. L1 sets whole notes, L2 sets half notes, L4 sets quarter notes, etc..
P <n> -- pause (rest), with <n> interpreted as for L. May be followed by sustain dots. May also be written '~'.
T <n> -- Sets the number of quarter notes per minute; default is 120. Musical names for common tempi are:
Tempo Beats Per Minute |
very slow Larghissimo |
Largo 40-60 |
Larghetto 60-66 |
Grave |
Lento |
Adagio 66-76 |
slow Adagietto |
Andante 76-108 |
medium Andantino |
Moderato 108-120 |
fast Allegretto |
Allegro 120-168 |
Vivace |
Veloce |
Presto 168-208 |
very fast Prestissimo |
M[LNS] -- set articulation. MN (N for normal) is the default; the last 1/8th of the note's value is rest time. You can set ML for legato (no rest space) or MS (staccato) 1/4 rest space.
Notes (that is, CDEFGAB or N command character groups) may be followed by sustain dots. Each dot causes the note's value to be lengthened by one-half for each one. Thus, a note dotted once is held for 3/2 of its undotted value; dotted twice, it is held 9/4, and three times would give 27/8.
Whitespace in play strings is simply skipped and may be used to separate melody sections.
In play strings which are very long (longer than your system's physical I/O blocks) note suffixes or numbers may occasionally be parsed incorrectly due to crossing a block boundary.