Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/348.lha/chatterbox_v1.0/README

Text File | 1990-02-14 | 12KB | 279 lines

chatterbox - have the Amiga play IFF audio sample files when events occur

Version 1.0 -- first public release

Copyright (C) 1989 by Karl Lehenbauer, All Rights Reserved
  This code is freely redistributable (and reusable) for
  noncommercial purposes providing this notice is retained.


Intro
-----

Chatterbox is largely the result of two evenings work, the 22nd and 23rd
of May, 1989.  One reason for the fast start was that I was able to reuse
a lot of code from some other Amiga programs I've written.

In any case, Chatterbox allows one to load and play sounds on the occurence
of several detectable events, such as disk insertion and deletion, calling
the DisplayBeep function, a time interval elapsing, preferences chaging,
activation and deactivation of Chatterbox's window, and eventually, other
events as well.  In order that it not eat up your precious "chip" RAM,
chatterbox uses your "fast" RAM (if you have any) to cache the loaded
sounds, only copying them to chip RAM when it's to play them.

There are a maximum of 32 sounds that may be defined for each type of
event that Chatterbox can play sounds for, although hard disk users may
have many more sounds triggered by timer events (more on this later).


Running Chatterbox
------------------

If you got Chatterbox on a disk and everything's set up properly, you should
be able to click open the disk, then doubleclick on the chatterbox icon, and
off it goes.  If you downloaded this from somewhere or something, you may
have to set it up yourself.  If so, please examine the "Configuring
Chatterbox" section following this one.

Chatterbox can also be run from the CLI.  Thus, it could be started
automatically by your boot sequence (by starting it from your
s:startups-sequence).  You'll need to do a "run" or "runback" on it
if you do start it in the startup sequence, as it does not return
until you exit it by clicking the close gadget in the Chatterbox window,
select the "quit" option in Chatterbox's pull-down menu or entering
Control-C in the window of the CLI from which Chatterbox was started.


Configuring Chatterbox
----------------------

Chatterbox looks in ChatterBox: for a configuration file named "config.data".
ChatterBox: should be the name of the floppy containing the config file and
all the sounds, or it can be an assign to a directory on your hard disk,
floppy, RAM disk, or whatever.  The format for config.data is very simple.
A number of keywords may occur in column one of a line.  After a line
containing a keyword (and possibly, optional parameters), a number of file
names are specified, with a blank in column one and the name starting in
column two.  Chatterbox is pretty stupid about this, so it is important
that you adhere to this format.  For example, if you wanted to play the
sound of a toilet flush (named "Toilet") or a car crash (named "CarCrash")
when a disk is removed while chatterbox is running, you would put the
following three lines in your config.data file:

diskout
 Toilet
 CarCrash

Note that the keywords must be all lower case.  The keywords and their
functions are explained below:

    diskin - play a sound when a disk is inserted
    diskout - play a sound when a disk is removed
    activate - play a sound when chatterbox's window is activated
    deactivate - play a sound when chatterbox's window is deactivated
    beep - play a sound on the next occurence of a DisplayBeep
    timer - play a sound every so often (default is every five minutes)
    preferences - play a sound when preferences change (weird, but hey)

Following the keyword, specify the names of the sample files, one to a
line with a blank in column one and the name starting in column two,
up to 32 sounds.  If a sound is repeated in more than one event's list,
it will still only be loaded once.  A sample config.data file occurs at
the end of this document.


Memory Considerations
---------------------

There are two types of memory on the Amiga, "chip" and "fast."  So-called
chip RAM is memory that can be accessed by the custom chips in the Amiga.
When a sound is played, it must reside in chip RAM.  Graphics displays
must reside in chip RAM when they are being displayed, and some other
things as well. Sounds, too, must reside in chip RAM when they're being
played.  Amigas right now have 512K bytes of chip RAM, although
the forthcoming "fat Agnes" will raise that limit to one megabyte.

"Fast" RAM is basically any RAM that is not "chip."  Unlike chip RAM, the
custom chips cannot access fast RAM.  Fast RAM is called "fast" because
the 68000 microprocessor can access this memory without delays caused by
the custom chips stealing memory cycles from the CPU.  (Don't worry at
the idea of the custom chips slowing the 68000, as the blitter, for example,
is much more efficient doing what it does that the 68000 would be in the
same number of cycles.)  Note that not all fast RAM is fast.  Specifically,
the second 512K of RAM that comes in the Amiga 2000 and the internal 512K
RAM upgrade for the Amiga 500 are wired to ultimately support the "fat Agnes"
chip.  As such, they still incur the performance hits when the blitter is
in heavy use and/or lots of other DMA (hires display, etc) is occuring.

As mentioned before, if you have fast RAM (or any non-chip RAM, as above),
Chatterbox loads and maintains its sounds in non-chip RAM, copying them
to chip RAM only as needed, and freeing them when they're done playing.
It's rather clever about it, like it won't free until it's completely
done if it's playing multiple times.

Chatterbox tries to chew up as much memory as you ask it to.  This means
it can cause low memory situations on your machine.  If you run into
problems, don't ask it to load as many sounds.  It would be a relatively
trivial thing for Chatterbox to insure that and adequate amount of memory
remained by refusing to load any more sounds when the available memory
dropped below a certain limit.  It would be driven by a line in the command
file.  But I'm burnt out on it and will be saving that for a new version.


Sound File Format
-----------------

Sounds files are expected to be in IFF 8SVX format.  Perfect Sound and
Audiomaster files are known to be compatible.


Using Chatterbox with a Hard Disk
---------------------------------

To install Chatterbox on a hard disk, simply create a directory containing
all the sample files you want to use and a config.data file, and do an
'assign ChatterBox:' to that directory.  (For example, if the sounds were
in fs1:data/sounds, use 'assign ChatterBox: fs1:data/sounds')  Then, put
chatterbox in your C: or run it explicitly in your s:startup-sequence, or
whatever, and, as long as no floppy is inserted called ChatterBox at the
time (and perhaps later), you'll get your samples off hard disk.

An additional feature for hard disk users is the "noload" option for sounds
that are to play when the timer event trips.  Noload is selected by having
it be the first word after 'timer' on the timer command line.  If minimum
and maximum time intervals are specified on the line, they come after
the "noload" keyword.  If "noload" is selected, Chatterbox will defer
loading in any of the sounds associated with the timer event until needed.
(This is not useful for floppy-only operation unless you can dedicate a
drive to sounds or don't mind randomly obeying requesters for them.)

If noload is selected, Chatterbox loads and plays the sound at the time
it is to play it, rather than the usual loading of all the sounds at the
beginning and random play from them.  When it is finished, it deallocates
the sound.  When "noload" is selected and certain sounds in the list of
sounds to play for the timer event are the same as sounds for other events,
Chatterbox plays but does not load the sound from disk (as it is already
memory-resident), nor does it deallocate the sound when finished.

A total of 256 deferred timer sounds may be defined.


Configuring The Timer Event
---------------------------

In addition to the "noload" option, the "timer" keyword can additionally
have a low and high number of seconds.  The specifies the range of time
chatterbox will want between speaking.  For example,

timer noload 300 600

...would tell chatterbox not to load the sounds defined for timer events
until they're played, and to wait from between five and ten minutes between
playing them.

timer 3600 3600

...would tell chatterbox to play a sound once an hour, and the abcense of
the "noload" option tells it to load in all the sounds listed to be played
on the occurence of timer events.


Chatterbox's Sound Selection Algorithms
---------------------------------------

Chatterbox implements "random selection without replacement" in determining
what sample to play next when more than one sample is defined to play for
a given function.  What this means is that each sound will play at least
one time before a given sound repeats, for a given "pass" through the list
of sounds.  Note that sounds may still occasionally occur back-to-back.
For example, if there are four sounds for a certain event type and
chatterbox plays the third sound last, then after playing the last sound,
chatterbox rerandomizes the sounds (as it does) and, by chance, ends up
with the third sound first, the third sound will be heard to play twice in
a row.  Nonetheless, you will hear all the other sounds defined for that
event before you hear the third sound an additional time.  This may be
changed later -- it's an easy fix.

Note that if 'noload' is selected, Chatterbox does not do random selection
without repacement for timer events.  The idea is that you have a boatload
of samples on disk and they're not playing that often, so you don't really
care so much about hearing repeats.


Source Code
-----------

The source code is included, at least it was when I shipped it out.
The code was written to run under Manx Aztec C 3.6a.  You should be
able to compile and go.

Note that the file windows.pw is a Power Windows 2.0 file.  Power Windows
was used to generate the file windows.c, which is included in the
distribution.



Only A Programmer Would Say "That's not a bug."
-----------------------------------------------

If you exit Chatterbox by clicking in its "close window" gadget and the
Chatterbox window was not active, Chatterbox will begin playing a sound
then kill it right away as it exits.  This is because when you click the
close gadget on an inactive window, Intuition sends a "window activated"
message (which can trigger Chatterbox to play a sound) then it sends a
"close window" message which tells Chatterbox to exit.  I suppose the
fix would be to receive the window activate and delay a bit before starting
the sound, allowing the receipt of a close to cancel the sound, but that
would mean a delay in starting the sound on the activate.  Alternatively,
it could wait until all sounds had finished playing on a "close window"
before exiting. I'm just gonna leave it the way it is, at least for now.


Anyway, have fun with it.


Karl Lehenbauer @ The Hacker's Haven, 26-May-89
(Usenet: uunet!sugar!karl, Internet/BITNET: [e-mail])
3918 Panorama
Missouri City, Texas  77459
[phone] (daytime)



Sample config.data file
-----------------------

This sample file plays the sound "disk_inserted" when a disk inserted
message is received by Chatterbox, "disk_removed" when one is removed,
"window_activated" when the Chatterbox window is activated,
"window_deactivated" when it is deactivated, preferences_changed when
preferences change, "low_bell" when a DisplayBeep call is made, and
"bass_snap", "bell", "drip", "hammer", "rise", "whip", "synth_echo",
"low_bell", or "low_smash" once every 20 to 120 seconds, loading the
timer sounds from hard disk when they're needed.

diskin
 disk_inserted
diskout
 disk_removed
timer noload 20 120
 bass_snap
 bell
 drip
 hammer
 rise
 whip
 synth_echo
 low_bell
 low_smash
beep
 low_bell
activate
 window_activated
deactivate
 window_deactivated
preferences
 preferences_changed