diff options
Diffstat (limited to 'share/man/man4/man4.i386/speaker.4')
| -rw-r--r-- | share/man/man4/man4.i386/speaker.4 | 202 |
1 files changed, 135 insertions, 67 deletions
diff --git a/share/man/man4/man4.i386/speaker.4 b/share/man/man4/man4.i386/speaker.4 index 4a11de9cfbf..ae7f8e87759 100644 --- a/share/man/man4/man4.i386/speaker.4 +++ b/share/man/man4/man4.i386/speaker.4 @@ -1,4 +1,4 @@ -.\" $OpenBSD: speaker.4,v 1.8 1999/09/23 04:12:06 alex Exp $ +.\" $OpenBSD: speaker.4,v 1.9 2000/07/05 13:46:53 aaron Exp $ .\" $NetBSD: speaker.4,v 1.9 1998/08/18 08:16:56 augustss Exp $ .\" .\" Copyright (c) 1993 Christopher G. Demetriou @@ -36,77 +36,142 @@ speaker \- console speaker device driver .Sh SYNOPSIS .Cd "spkr0 at pcppi?" -.Fd #include <machine/spkr.h> -.Pa /dev/speaker .Sh DESCRIPTION The speaker device driver allows applications to control the PC console speaker on an IBM-PC-compatible machine running UNIX. .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 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. -.Pp -Sound-generation does \fInot\fR 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 ioctl() on a speaker file descriptor to control the -speaker driver directly; definitions for the ioctl() interface are in -<machine/spkr.h>. The tone_t structure used in these calls has two fields, +Only one process may have this device open at any given time; +.Xr open 2 +and +.Xr close 2 +are used to lock and relinquish it. +An attempt to +.Fn open +whenanother process has the device locked will return \-1 with an +.Er EBUSY +error indication. +Writes to the device are interpreted as +.Dq 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 +.Li 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. +At present there are two such ioctls. +The +.Dv SPKRTONE +ioctl accepts a pointer to a single tone structure as a third argument and +plays it. +The +.Dv SPKRTUNE +ioctl 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. +IBM BASIC 2.0. +The MB, MF and X primitives of PLAY are not useful in a UNIX environment and +are omitted. +The +.Dq 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'. +with middle C. +By default, the play function emits half-second notes with the last 1/16th +second being +.Dq 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 \fIaccidental -sign\fR, 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 <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). +letter case is ignored. +Play command groups are as follows: +.Bl -tag -width xxx +.It 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 +.Dq accidental sign , +one of +.Ql # , +.Ql + , +or +.Ql - ; +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;. +.It O Aq Ar n +If +.Ar n +is numeric, this sets the current octave. +.Ar n +may also be one of +.Sq L +or +.Sq 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]. -.Pp +notes. +Thus +.Qq olbc +will be played as +.Qq olb>c , +and +.Qq olcb +as +.Qq olc<b . +Octave locking is disabled for one letter note following by +.Ql > , +.Ql < , +and +.Ql O[0123456] . +.Pp +.Bd -literal -offset indent > -- bump the current octave up one. -.Pp < -- drop the current octave down one. -.Pp -N <n> -- play note n, n being 1 to 84 or 0 for a rest of current time value. +.Ed +.It N Aq Ar n +Play note +.Ar n , +.Ar n +being 1 to 84 or 0 for a rest of current time value. May be followed by sustain dots. -.Pp -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.. -.Pp -P <n> -- pause (rest), with <n> interpreted as for L. May be followed by -sustain dots. May also be written '~'. -.Pp -T <n> -- Sets the number of quarter notes per minute; default is 120. Musical -names for common tempi are: +.It L Aq Ar 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. +.It P Aq Ar n +Pause (rest), with +.Ar n +interpreted as for L. +May be followed by sustain dots. +May also be written +.Ql ~ . +.It T Aq Ar n +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 @@ -126,18 +191,29 @@ fast Allegretto 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. +.It 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. +.El .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; +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 AUTHOR +Eric S. Raymond (esr@snark.thyrsus.com) Feb 1990 .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 @@ -148,11 +224,3 @@ There is no volume control. 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. -.Sh FILES -.Bl -tag -width Pa -compact -.It Pa /dev/speaker -.El -.\" .Sh SEE ALSO -.\" .Xr pcppi 4 . -.Sh AUTHOR -Eric S. Raymond (esr@snark.thyrsus.com) Feb 1990 |