Contents of the SOUNDKIT.DOC file
August 14, 1990
All rights reserved,
Russell B. Hildreth
Documentation and Programmer's Notes
Soundkit 1.0 Documentation and Programmer's Notes:
Soundkit 1.0 is a collection of functions designed
especially for users of Microsoft C compliers (MSC and
QuickC). The functions are provided as shareware in
library format (SOUNDKIT.LIB). All source code is
available to programmers who register Soundkit with
Microsoft does not provide any ready to use sound
functions with its languages as Borland does with
the Turbo series. Soundkit remedies this situation
by providing sound support similar to that of Borlands.
Soundkit, however, goes one step further by additionally
providing a collection of ready to use sound routines.
There are close to forty sound functions in the first
Soundkit release, and there will be even more in the
future. These routines include musical selections,
utility beeps, buzzes, and alarms, and generally silly
sounds. An attempt has been made to provide a wide
variety of routines to satisfy programmers.
Programmers can also, of course, use the core Soundkit
functions [ tone(), soundon(), and soundoff() ] to
create their own sound routines.
All the currently available Soundkit routines can be
tried out with the DEMO program included in the shareware
release. To illustrate using Soundkit functions, the
source code to the DEMO program has been included.
Soundkit is shareware. If you use the routines provided
in the SOUNDKIT.LIB file, you are obligated to register
with the author. Please see the section on registering
in this document, and the SOUNDKIT.REG file.
Using the Soundkit routines is very straightforward. A
programmer can run the DEMO program to assist in selecting
desired sound routines. Once the desired routines have
been identified, the programmer needs only to #include the
SOUNDKIT.H file and call the desired routines by name
in a program. For example,
When a programmer compiles a program containing Soundkit
routines, the SOUNDKIT.LIB file should be linked from the
command line, or specified within a development environment.
For example, to compile the SAMPLE.C file from the command
line with Quick C, use the following line:
QCL SAMPLE.C SOUNDKIT.LIB
Failure to link the SOUNDKIT.LIB file will result in a
program that will not properly execute any Soundkit functions
(they simply won't be available to the program).
delay() This function provides the necessary
delays to make notes sound the same
length of time on any speed CPU.
Call delay() with an unsigned int
value, i.e., delay(5); Experimentation
is usually necessary to obtain the
optimum delay time. The delay()
function is written in assembly
language to increase delay length
accuracy (the delay routine suggested
by Microsoft in the QuickC sample
programs in an example of terrible
programming!). Calling delay() with a
value of 0 is not advised, as it is
liable to lock up your machine.
flushkb() Flushes the keyboard. This routine
is used by many of the Soundkit
which can be stopped by pressing a
key, to make sure that the user does
not stop a sound routine before it
has a chance to begin.
soundon() Takes an integer value and sounds the
PC speaker with that value. This
sound will continue until the
soundoff() function is called.
soundoff() Turns off the PC speaker. Use this to
shut the computer up at the end of
your sound functions.
tone() For many programmers this will be the
primary sound function. It takes two
values, both unsigned integers. The
first is a hz note value (musical note),
and the second is a delay length. The
note is played for the delay length.
For example tone(440,6) would play an
A note for a short time. The file
NOTE.CHT provides a complete list of
notes and their corresponding hz values.
The DEMO program provides a complete list of all currently
available sound routines. These include musical routines
from Bach and other favorites, alarms, buzzes, beeps,
sirens, and other noises that programmers might find handy
at one point or another.
Many of the longer sound routines can be stopped by a
keypress. These include all of the music routines, the alarms,
and several others. Each of these calls the flushkb()
function first to make sure that the routine will get a chance
to play. The shorter routines simply play themselves out,
A prewritten OFF.EXE program has been included to shut
the speaker up from the command line. The author
experienced several instances in which he left the speaker
on at the end of a routine by accident, and found the
OFF program convenient for turning it back off while
editing and recompiling.
One important thing for novice programmers to realize is
that just because there are many routines in the SOUNDKIT.LIB
file, only those routines you call in your program will be
actually used. If your program only uses one beep routine,
then its size will only grow in proportion to the one beep
routine, NOT the full size of the SOUNDKIT.LIB file!
Every effort has been made to keep these routines as small
as possible. They add very little overhead to the size
of finished programs. Further, the author is committed to
making these routines even smaller in future releases of
Soundkit. Register now to get the next release as soon as
it becomes available.
Turbo C: The author has absolutely no idea whether any of
the Soundkit functions will work with Turbo C or Turbo C++.
Probably they will not. The author will, however, make a
Borland compatible version of Soundkit available if demand
warrants doing so.
CPU DEPENDENT ROUTINES:
There are several routines included which are CPU dependent.
This means that they will not sound the same on all machines,
primarily because faster machines will process the loops more
quickly, distorting the sound. These routines have been
optimized to sound best on an 8mhz AT. For consistency
programmers should only use these routines in programs which
will not be distributed to the world at large. The CPU
dependent routines are noted in the DEMO program as being such.
All other Soundkit routines will perform identically on all
machines--they are processor independent. They have been
tested on machines ranging from 4.77mhz to 20mhz with identical
results in every instance. Programmers should rely more heavily
on these routines.
Programmers constructing their own routines should be aware
of the way different speed CPUs handle loops. To create a
routine that is CPU independent, always nest a minimal delay
(i.e., delay(1);). The delay() function performs identically
on every CPU. A routine which lacks a delay function will
not be consistent among different processors (though such a
routine might very well be used to create a desired sound
Programmers who possess the registered version of the Soundkit
have access to the source code for each routine and can compare
a CPU dependent routine such as siren2() with a processor
independent routine such as siren1().
There are three very good reasons for registering with the
author. One is that the programmer receives all of the
source code used to create the SOUNDKIT.LIB. This includes
the core functions and all of the sound routines. The
programmer can then use these as examples for his or her
own routines, or modify them to make new routines. Also, the
programmer can see how the core routines work and perhaps
modify these also.
Another reason is that the author will continually update
Soundkit with a) additional sound routines and b) improved
core routines. The author is committed to producing the
best possible sounds through the limited PC speaker, and is
always searching for new ways to do more.
The third reason deals with copyright laws. Soundkit is
copyright by the author, Russell B. Hildreth, 1990, who
retains all rights to the routines. If a programmer uses
any of the Soundkit routines in a program that is to be
distributed to the public, be it shareware, freeware, or
retail software, the programmer (or distributor, as the
case may be) is legally bound to register Soundkit with the
author. Most programmers, however, will probably want to
register anyway, in order to obtain the source code.
And finally, it is nice to support the work of others. The
author of Soundkit actively supports the shareware community.
Further, all income derived from Soundkit is used by the
author to assist in offsetting the ever increasing costs of
obtaining a higher education.
Please use the SOUNDKIT.REG form for registering. Send
Russell B. Hildreth
P.O. Box 72431
Davis, CA 95617-2431
CONTACTING THE AUTHOR:
The author can be contacted on Compuserve at 71041,2132, or
by U.S. Mail at the registration address.
The author welcomes your suggestions for improvements to the
Soundkit routines, as well as criticims and bug reports.