173 lines
7.2 KiB
Groff
173 lines
7.2 KiB
Groff
.\" $NetBSD: speaker.4,v 1.12 2003/04/16 13:35:18 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 1993 Christopher G. Demetriou
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed for the
|
|
.\" NetBSD Project. See http://www.NetBSD.org/ for
|
|
.\" information about NetBSD.
|
|
.\" 4. The name of the author may not be used to endorse or promote products
|
|
.\" derived from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>>
|
|
.\"
|
|
.Dd August 6, 1993
|
|
.Dt SPEAKER 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm speaker
|
|
.Nd console speaker audio device driver
|
|
.Sh SYNOPSIS
|
|
.Cd "spkr0 at pcppi?"
|
|
.In machine/spkr.h
|
|
.Pa /dev/speaker
|
|
.Sh DESCRIPTION
|
|
The speaker device driver allows applications to control the console
|
|
speaker on machines with a PC-like 8253 timer implementation.
|
|
.Pp
|
|
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
|
|
.Er EBUSY
|
|
error indication. Writes to the device are interpreted as 'play strings' in a
|
|
simple ASCII melody notation. An
|
|
.Fn ioctl
|
|
for tone generation at arbitrary frequencies is also supported.
|
|
.Pp
|
|
Sound-generation does
|
|
.Em 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.
|
|
.Pp
|
|
Applications may call
|
|
.Fn ioctl
|
|
on a speaker file descriptor to control the speaker driver directly;
|
|
definitions for the
|
|
.Fn ioctl
|
|
interface are in
|
|
.Aq Pa machine/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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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'.
|
|
.Pp
|
|
Play strings are interpreted left to right as a series of play command groups;
|
|
letter case is ignored. Play command groups are as follows:
|
|
.Pp
|
|
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
|
|
.Em 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;.
|
|
.Pp
|
|
O \*[Lt]n\*[Gt] -- if \*[Lt]n\*[Gt] is numeric, this sets the current octave. \*[Lt]n\*[Gt] 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\*[Gt]c", and "olcb" as "olc\*[Lt]b". Octave
|
|
locking is disabled for one letter note following by \*[Gt], \*[Lt] and O[0123456].
|
|
.Pp
|
|
\*[Gt] -- bump the current octave up one.
|
|
.Pp
|
|
\*[Lt] -- drop the current octave down one.
|
|
.Pp
|
|
N \*[Lt]n\*[Gt] -- play note n, n being 1 to 84 or 0 for a rest of current time value.
|
|
May be followed by sustain dots.
|
|
.Pp
|
|
L \*[Lt]n\*[Gt] -- 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..
|
|
.Pp
|
|
P \*[Lt]n\*[Gt] -- pause (rest), with \*[Lt]n\*[Gt] interpreted as for L. May be followed by
|
|
sustain dots. May also be written '~'.
|
|
.Pp
|
|
T \*[Lt]n\*[Gt] -- Sets the number of quarter notes per minute; default is 120. Musical
|
|
names for common tempi are:
|
|
.Bl -column Description Tempo BPM -offset indent
|
|
.Em 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
|
|
.El
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
Whitespace in play strings is simply skipped and may be used to separate
|
|
melody sections.
|
|
.Sh FILES
|
|
.Bl -tag -width Pa -compact
|
|
.It Pa /dev/speaker
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr pcppi 4
|
|
.Sh AUTHORS
|
|
.An Eric S. Raymond Aq esr@snark.thyrsus.com
|
|
.Sh BUGS
|
|
Due to roundoff in the pitch tables and slop in the tone-generation and timer
|
|
hardware (neither of which was designed for precision), neither pitch accuracy
|
|
nor timings will be mathematically exact.
|
|
.Pp
|
|
There is no volume control.
|
|
.Pp
|
|
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.
|