diff options
Diffstat (limited to 'static/netbsd/man4/speaker.4')
| -rw-r--r-- | static/netbsd/man4/speaker.4 | 322 |
1 files changed, 322 insertions, 0 deletions
diff --git a/static/netbsd/man4/speaker.4 b/static/netbsd/man4/speaker.4 new file mode 100644 index 00000000..cb57ba98 --- /dev/null +++ b/static/netbsd/man4/speaker.4 @@ -0,0 +1,322 @@ +.\" $NetBSD: speaker.4,v 1.31 2024/09/07 19:13:27 rillig Exp $ +.\" +.\" Copyright (c) 2016 Nathanial Sloss <nathanialsloss@yahoo.com.au> +.\" All rights reserved. +.\" +.\" 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 https://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 June 13, 2017 +.Dt SPEAKER 4 +.Os +.Sh NAME +.Nm speaker +.Nd console speaker audio device driver +.Sh SYNOPSIS +.Cd "spkr* at pcppi?" +.Cd "spkr* at audio?" +.Pp +.In dev/spkrio.h +.Sh DESCRIPTION +The speaker device driver allows applications to control the console +speaker on machines with a PC-like 8253 timer implementation or a synthesized +speaker from an audio device/soundcard. +.Pp +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 +.Xr open 2 +when another 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 +.Tn ASCII +melody notation. +An +.Fn ioctl +for tone generation at arbitrary frequencies is also supported. +.Pp +For the +.Xr pcppi 4 +device 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 +For the audio device speaker, the speaker uses one of the virtual audio +channels. +Enabling this device will also provide a +.Xr wsbell 4 +keyboard bell. +.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 +.In dev/spkrio.h . +.Pp +The +.Vt tone_t +structure is as follows: +.Bd -literal -offset indent +typedef struct { + int frequency; /* in hertz */ + int duration; /* in 1/100ths of a second */ +} tone_t; +.Ed +.Pp +A frequency of zero is interpreted as a rest. +.Pp +At present there are four ioctls: +.Bl -tag -width Dv +.It Dv SPKRGETVOL +Returns an integer, which is the current bell volume as a percentage (0\(en100). +.It Dv SPKRSETVOL +Accepts an integer, which is the desired volume as a percentage. +.It Dv SPKRTONE +Accepts a pointer to a single tone structure as third argument and plays it. +.It Dv 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. +.El +.\" +.Ss Play string language +.\" +The play string language is modelled on the +.Ic PLAY +statement conventions of +.Tn IBM BASIC No 2.0 . +The +.Ic MB , +.Ic MF +and +.Ic X +commands of +.Ic PLAY +are not useful in a +.Tn UNIX +environment and are not implemented. +The +.Dq octave-tracking +feature is also new. +.Pp +There are 84 accessible notes numbered 1\(en84 in 7 octaves numbered 0\(en6; +octave\~2 starts with middle C. +The tuning is equal-tempered A440. +.Pp +In the initial state the current octave is 4, +the default note duration is quarter notes, +the tempo is 120 bpm, +and the articulation is non-legato or normal, +i.e. 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. +Whitespace between groups is ignored +and may be used to separate melody sections. +Play command groups are as follows: +.Bl -tag -width Ic +.It Ic C , D , E , F , G , A , B +Letters +.Sq Ic A +through +.Sq Ic 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 +.Sq Ic \&# , +.Sq Ic \&+ , +or +.Sq Ic \&- ; +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 +.Sq Ic L +command below;. +.\" +.It Ic O Ns Ar n , Ic OL , Ic ON +If +.Ar n +is numeric, this sets the current octave. +.Sq Ic OL +enables, and +.Sq Ic ON +disables +.Em 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 +.Dq Li olbc +will be played as +.Dq Li olb>c , +and +.Dq Li olcb +as +.Dq Li olc<b . +Octave tracking is temporarily disabled for one letter note that follows +.Sq Ic \&> , +.Sq Ic \&< +or +.Sq Ic O Ns Ar n . +.\" +.It Ic \&> +Bump the current octave up one. +.\" +.It Ic \&< +Drop the current octave down one. +.\" +.It Ic N Ns 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. +.\" +.It Ic L Ns Ar n +Sets the current time value for notes. +The default is +.Dq Li L4 , +quarter notes. +The lowest possible value is 1; values up to 64 are accepted. +.Dq Li L1 +sets whole notes, +.Dq Li L2 +sets half notes, +.Dq Li L4 +sets quarter notes, etc... +.\" +.It Ic P Ns Ar n , Ic \&~ Ns Ar n +Pause (rest), with +.Ar n +interpreted as for +.Sq Ic L . +May be followed by sustain dots. +.\" +.It Ic T Ns Ar n +Sets the number of quarter notes per minute; default is 120. +Musical names for common tempi are: +.Bl -column "very slow" "Larghissimo" "999\(en999" -offset indent +.It Ta Sy "Tempo" Ta Sy "BPM" +.It very slow Ta Larghissimo Ta "" +.It Ta Largo Ta 40\(en60 +.It Ta Larghetto Ta 60\(en66 +.It Ta Grave Ta "" +.It Ta Lento Ta "" +.It Ta Adagio Ta 66\(en76 +.It slow Ta Adagietto Ta "" +.It Ta Andante Ta 76\(en108 +.It medium Ta Andantino Ta "" +.It Ta Moderato Ta 108\(en120 +.It fast Ta Allegretto Ta "" +.It Ta Allegro Ta 120\(en168 +.It Ta Vivace Ta "" +.It Ta Veloce Ta "" +.It Ta Presto Ta 168\(en208 +.It very fast Ta Prestissimo Ta "" +.El +.\" +.It Ic ML , Ic MN , Ic MS +Set articulation. +.Sq Ic MN +(for normal) is the default; the last 1/8th of +the note's value is rest time. +You can set +.Sq Ic ML +for legato (no rest time) or +.Sq Ic MS +for staccato (1/4 rest time). +.El +.Pp +Notes, that is, +.Ic C , D , E , F , G , A , B , +or +.Ic 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. +.Sh FILES +.Bl -tag -width Pa -compact +.It Pa /dev/speaker +.El +.Sh SEE ALSO +.Xr audio 4 , +.Xr pcppi 4 , +.Xr wsbell 4 , +.Xr sysctl 8 +.Sh HISTORY +This +.Nm +device was originally for the pcppi PC timer interface. +Support was added for a synthesized device by Nathanial Sloss, first appearing +in +.Nx 8.0 . +.Sh AUTHORS +.An Eric S. Raymond Aq Mt 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 +The action of two or more sustain dots does not reflect standard musical +notation, in which each dot adds half the value of the previous dot +modifier, not half the value of the note as modified. +Thus, a note dotted +once is held for 3/2 of its undotted value; dotted twice, it is held 7/4, +and three times would give 15/8. +The multiply-by-3/2 interpretation, +however, is specified in the +.Tn IBM BASIC +manual and has been retained for compatibility. +.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. |