💾 Archived View for spam.works › mirrors › textfiles › apple › DOCUMENTATION › alertsound captured on 2023-06-16 at 21:14:01.
-=-=-=-=-=-=-
Alert Sound Control Panel Device (CDEV)
By Joshua M. Thompson
Copyright (c) 1991 Frontier Technologies
This program contains material from the ORCA/Pascal
Run-Time Libraries, copyright 1987-88
by Byte Works, Inc. Used with permission.
Apple IIGS and Macintosh are trademarks of Apple Computer, Inc.
Disclaimer
----------
I have tested this program extensively and found no problems with it. However,
this does not mean that the program is guaranteed to function under all
possible conditions. Neither Joshua Thompson nor Frontier Technologies are
responsible for any damages, direct or indirect, resulting from the use of this
program.
Introduction
------------
Alert Sound is an accessory to the graphic control panel NDA which allows you
to change the beep sound on your IIGS. Unlike other such programs currently
available, Alert Sound works from within the control panel, and also allows you
change your beep easily and instantly (no more copying a new beep file and
rebooting). Plus, Alert Sound gives you control over the sound volume and over
the pitch of the standard beep, making the old Sound Cdev unnecessary.
Alert Sound is *shareware*! You may try this program out free for one week.
After that, either send in the shareware fee of $8.00 or delete all copies of
this program from your system. By paying the fee, you will help support future
projects from Frontier Technologies. The address can be found at the end of
this file (please make all checks payable to JOSHUA THOMPSON).
See the section "Revision History" for a list of changes made in this version.
Requirements
------------
First and foremost, Alert Sound requires System Disk 5.0.4 or higher. While it
will work with any version above 5.0, versions below 5.0.4 contain some nasty
bugs with resources and may cause problems in the future.
System Disk 5.0.4 is available on America Online or from your local Apple
dealer.
Your boot volume will need at least 14k of free space to install Alert Sound
Cdev. If you wish to install the default sounds as well, then you will need
an additional 40k of free space. I strongly recommend a hard drive if you
don't already have one.
Alert Sound will not function with the program launcher Wings by Vitesse. It
appears that Wings installs its own beep routines for its custom beeps, and
disconnects Alert Sound. At this time there is no known way around this.
Installation
------------
Installing Alert Sound is very simple...simply copy two files!
The first file you must copy is the file "AlertSound". This is the actual
Cdev, and must go in your *:System:Cdevs folder.
The second file to copy will depend on how you want to run Alert Sound. If you
wish to use the default sounds included with the Cdev, then copy the file
"Sounds" into your *:System folder. If you don't want to install the default
sounds, or don't have enough space free, then copy the file called
"Sounds.Empty" into your *:System folder and rename the copy of the file to
"Sounds".
Please be aware that these files contain resource forks, and must therefore be
copied with the Finder or another program which is "Post-System 5.0" (such as
ProSel/16 by Glen Bredon or Wings by Vitesse).
Once you have successfully installed Alert Sound, you can delete the Sound Cdev
from your *:System:Cdevs folder. Alert Sound duplicates the functions of the
Sound Cdev, making it unnecessary.
Using the Cdev
--------------
Functionally, the Alert Sound CDev is very similar to the Macintosh Sound CDev.
The first thing you must do is open the Control Panel NDA (isn't this so
easy?). If Alert Sound is not already selected, then click on its icon to
select it. After a short pause and some disk access, a list of available
sounds will appear. Below the list will be four buttons : "Beep", "Add",
"Remove", and "Extras". And below the four buttons will be two scroll bars
labeled "Volume" and "Pitch".
To change your beep sound, you simply highlight it in the list of available
sounds presented to you. To return to the normal GS beep, select the sound
labeled "Standard Beep", which is always at the top of the list. You can hear
the currently selected beep sound by clicking the "Beep" button.
I have set up Alert Sound with an initial set of sounds, all taken from the
Macintosh. These are Simple Beep (the standard Mac beep tone), Clink-Klank,
Boing, Monkey, and Mac II Chime (the startup chime for the Mac II). To find
out how to add your own sounds, keep reading!
The volume scroll bar is used to control the sound volume. Any changes to the
volume will be saved in your battery RAM and reflected in the text control
panel.
The pitch scroll bar is only useful if you are using the standard beep. It
is used to change the pitch of the beep, and like the volume control, the
setting is saved in battery RAM. If you are not currently using the standard
beep, then the pitch control will not affect the beep.
The "Extras" button is for future use, and is currently dimmed.
The "Add" button is used to add more sounds to the list of those available.
After clicking this button, you are presented with a Standard File dialog from
which you can select the sound file you wish to add to your list (this sound
file must be a standard raw data file; Alert Sound cannot currently handle any
special sound formats such as ASIF). After selecting the file to add, you are
presented with a window in which you can type in a 1-32 character title for the
sound. When you are finished typing the name, click the Add button in this new
window, and Alert Sound will go to work and add the file to your list. If for
some reason an error occurs, Alert Sound does its best to clean up after
itself, including removing any resources which were created. However, no error
message is displayed since it will be obvious if an error occurred as the new
sound will not be in the list.
To remove a sound from the resource file, simply select the sound in the list
of sounds, and click on the "Remove" button. The sound will be removed from
the Sounds file, and the Standard Beep entry will be selected. Please note
that you cannot remove the Standard Beep sound.
Due to the nature of the Resource Manager, deleting a sound does not make the
Sounds file physically smaller. However, the space used by the deleted sounds
will be freed up, and as you add new sounds to the file, this space will be
automatically re-used.
The limit to the number of sounds you can have is 16,383. If you need more
sounds then that, then perhaps you need a larger computer!
Quirks, etc.
------------
From time to time I have noticed that Orca/Pascal programs can do strange
things. The Add and Remove function of Alert Sound is written with
Orca/Pascal, so if they does anything strange, please let me know so I can
attempt to remedy the problem. Often times I can simply "program around" bugs
in Orca/Pascal.
Make sure that any sounds you add are terminated by at least four consecutive
zero bytes. If you don't, you may get a small burst of static or noise (very
short, but annoying) at the end of your beep sound. Many sound programs will
do this for you when you save, so check the documentation of your favorite
sound program.
I have noticed that some sounds would not play completely when added to the
sound list. It turned out that these sounds had spurious zero bytes in them
which caused them to end prematurely. Once I filtered them out, the sounds
played perfectly. At this time I have absolutely no idea why Alert Sound seems
to be more sensitive to these zero bytes then some other programs.
If the program which you are currently running makes use of the Sound Tools,
then Alert Sound will simply beep normally (until you exit that program).
Right now there is no way to avoid this, since Apple has stated that any
program using the sound tools has total control over the sound hardware.
Alert Sound does not function with the program launcher Wings by Vitesse. It
appears that Wings installs its own beep routines which disconnect Alert Sound.
At this time there is no way around this.
The Future
----------
At this time, I have further plans for this CDev, including ideas such as
direct digitization and the ability to handle other sounds formats (ASIF, Sound
Shop, etc). However, much of this depends on how much response I get regarding
the cdev.
If you have any more ideas for Alert Sound, or even ideas for other nifty
programs, drop me a line at one of the places listed at the end of the docs.
I'm always looking for something to program!
Revision History
----------------
v1.0 : First release.
v1.1 : Added "volume" and "pitch" controls, making the old Sound Cdev
unnecessary.
Added "Remove" button to remove sounds from the resource file. Also
added an "Extras" button for future use.
Wrote a built-in check so that Alert Sound will realize when it's been
disconnected (ie, by Wings). When such a situation occurs, Alert Sound
simply displays an error message informing the user that Alert Sound has
been disconnected and cannot function.
Fixed a strange bug that caused Alert Sound to blow up when the system
beeped while inside BASIC System.
About the Author
----------------
I am currently a freshman at the University of Michigan-Dearborn, studying
computer and information science. Some of my other projects include Nupak (an
uncompression utility), some parts of the Metal BBS software, and Future Vision
(a networking BBS which runs under Metal).
A Personal Message from Steven Yuhasz
-------------------------------------
I'm very pleased to be able to say that Frontier Technologies is again
releasing another fine product by Joshua M. Thompson. I am proud to have
Joshua as a fine partner in a growing company. Our first product, Nupak, (the
first StuffIT file unpacker for the IIGS) was mentioned in March 1991 issue of
inCider/A+ and has made us realize that all is not impossible. Frontier
Technologies is dedicated to new and innovative products that bridge the gap
between Apple II and Macintosh computers. Expect more exciting products to be
released in the next few months as Frontier Technologies makes its return to
the computer scene.
Steven Yuhasz
President
Frontier Technologies
Technical Stuff
--------------
Alert Sound hooks itself into the bell vector using the Miscellaneous toolbox
call _SetVector. The beep routine installed has several "dummy" instructions
which are used to store important parameters across uses of the Cdev (such as
Alert Sound's permanent user ID number and the handles of the sound parameter
block and the wave form). Since the Cdev code is disposed of when Alert Sound
is closed, these parameters cannot be stored in the cdev code itself. The ID
check added in version 1.1 is necessary to prevent Alert Sound from retrieving
erroneous parameters when another program patches out the bell vector.
Sounds are stored in the Sounds file in the System folder. This is essentially
huge resource fork containing four types of resources: an rListRef resource
($801C), rPString resources ($8006), rSoundSample resources ($8024), and an
rCDevSetup ($0004).
The rPStrings are simply the titles of the sounds. No big deal.
The rSoundSamples are exactly as defined in Technical Note #76 for the GS,
except that I ignore the Rel Pitch and Stereo Channel fields. Again, no big
deal.
The rListRef resource consists of 10-byte members with the following format:
+0 : reference to title string. Should be ID of pstring resource
+4 : item flags. Always leave the low two bits set to %10 to signal
refIsResource
+5 : unused, but makes the record an even # of bytes
+6 : reference to sound resource. Should be ID of rSoundSample resource
The rCDevSetup resource is 64 bytes long (only 8 of which are currently
defined). It basically looks like this:
+0: Total number of available sounds
+4: rSoundSample resource ID of currently selected beep sound.
+8: Unused and reserved, 56 bytes.
Miscellaneous
-------------
I would like to thank Steven Yuhasz for both beta testing of the Cdev and for
supplying me with the Macintosh sounds. I'd also like to thank Tom Stechow for
his help in beta testing, as well as his comments and suggestions.
If you're a CDev author, please contact me! I've got a ton of room in the
Sounds file where you can put just about anything, like config information,
desktop patterns (hint, hint!), or whatever. I really despise a bunch of
little data files all over my hard drive (aren't the Finder.Data files enough?)
:)
Credits, etc.
-------------
Most of Alert Sound is written in assembly, except the add and remove, which
are written in Orca/Pascal.
Shareware fees (make checks payable to JOSHUA THOMPSON), as well as comments,
questions, or ideas, can be sent to:
Snail Mail : Frontier Technologies
2128 Scotten
Detroit, MI 48209-1667
America Online : Frontier T
I can also be reached as The Magnetic Monopole (user #2) on :
The Electronic Gateway : (313)422-8073 300/1200/2400 bps
Home of the Future Vision software
Look for more great products from Frontier Technologies in the future!